🤖 AI Agents Documentation

This document outlines the AI agents and automation tools used in the development of the Clean-Autofill Chrome extension. It serves as a guide for developers working with AI-assisted development workflows.

🎯 Overview

The Clean-Autofill project leverages AI agents to streamline development, automate repetitive tasks, and maintain high code quality. This document provides guidelines for working with AI assistants and maintaining consistent development practices.

🤖 Primary AI Agent: Claude

Agent Profile

• Name: Claude (Anthropic)
• Version: Claude 3.5 Sonnet
• Primary Role: Full-stack development assistant
• Capabilities: Code generation, debugging, documentation, testing, deployment automation

Core Responsibilities

1. Code Development

• Feature Implementation: Translating requirements into functional code
• Bug Fixes: Identifying and resolving issues across the codebase
• Refactoring: Improving code structure and performance
• Code Review: Analyzing code quality and suggesting improvements

2. Architecture & Design

• System Design: Creating scalable Chrome extension architecture
• File Organization: Maintaining clean project structure
• Best Practices: Implementing industry standards and security measures

3. Automation & CI/CD

• GitHub Actions: Setting up automated workflows for:
  • Build and testing
  • Code validation
  • Chrome Web Store deployment
  • Version management
• Script Development: Creating utility scripts for:
  • Version bumping
  • Extension packaging
  • Validation and testing

4. Documentation

• Technical Writing: Creating comprehensive documentation
• API Documentation: Documenting functions and workflows
• User Guides: Writing setup and usage instructions
• Process Documentation: Maintaining development workflows

Communication Protocol

Interaction Guidelines

✅ DO:
- Provide clear, specific requirements
- Include context and examples
- Specify file paths and line numbers
- Request validation/testing
- Ask for alternative approaches

❌ DON'T:
- Make assumptions about implementation details
- Skip validation steps
- Request incomplete features
- Ignore error messages

Standard Request Format

Feature: [Brief description]
Requirements: [Detailed specifications]
Files: [Affected file paths]
Testing: [Validation criteria]

Development Workflow

1. Feature Development

# 1. Plan and discuss requirements
# 2. Implement core functionality
# 3. Add comprehensive validation
# 4. Update documentation
# 5. Test thoroughly
# 6. Commit with descriptive messages

2. Code Quality Standards

• Linting: Automated code style enforcement
• Testing: Unit and integration test coverage
• Security: Regular security audits
• Performance: Optimized resource usage

🛠️ Automation Tools

GitHub Actions Workflows

1. Build & Test (build-and-test.yml)

Trigger: Push to main/develop, Pull Requests Actions:

• Validate manifest.json structure
• Check all required files exist
• Generate extension package (ZIP)
• Upload build artifacts

2. Chrome Web Store Release (release-chrome-store.yml)

Trigger: Version tags (v*), Manual dispatch Actions:

• Version management and bumping
• Package creation and validation
• Upload to Chrome Web Store API
• Publish extension (requires review)
• Create GitHub releases

Development Scripts

1. Version Management (toolkit/scripts/bump-version.js)

# Bump patch version (1.0.0 → 1.0.1)
bun run bump:patch

# Bump minor version (1.0.0 → 1.1.0)
bun run bump:minor

# Bump major version (1.0.0 → 2.0.0)
bun run bump:major

2. Extension Packaging (toolkit/scripts/pack.js)

# Validate and package extension
bun run pack

3. Comprehensive Validation (toolkit/scripts/validate.js)

# Run full validation suite
bun run validate

4. Build Validation (toolkit/scripts/build.js)

# Check project structure and dependencies
bun run build

📋 Project Structure & Standards

Directory Organization

Clean-Autofill/
├── 📁 .github/workflows/     # CI/CD automation
├── 📁 src/                  # Extension source code (TypeScript)
│   ├── 📄 background.ts     # Service worker logic
│   ├── 📄 content.ts        # Content script
│   ├── 📄 options.ts        # Settings page logic
│   ├── 📄 options.html      # Settings page UI
│   ├── 📄 utils.ts          # Shared utilities
│   └── 📁 icons/            # Extension icons (all sizes)
├── 📁 toolkit/              # Development utilities
│   ├── 📁 scripts/          # Build scripts
│   ├── 📁 biome/            # Biome linter config
│   ├── 📁 typescript/       # TypeScript config
│   └── 📁 husky/            # Pre-commit hooks
├── 📁 docs/                 # Documentation
├── 📄 manifest.json         # Extension configuration
├── 📄 package.json          # Bun/NPM configuration
└── 📁 dist/                 # Build output (gitignored)
    └── 📄 Clean-Autofill.zip # Chrome Web Store package

Coding Standards

JavaScript/ES6+

• Style: Consistent formatting with ESLint
• Structure: Modular, reusable functions
• Documentation: JSDoc comments for public APIs
• Error Handling: Comprehensive try-catch blocks

Chrome Extension Best Practices

• Manifest V3: Latest Chrome extension standards
• Permissions: Minimal required permissions only
• Security: Content Security Policy compliance
• Performance: Optimized resource usage

Git Standards

• Commit Messages: Conventional commits format

  type(scope): description
  
  [optional body]
  
  [optional footer]
  

• Branch Strategy: Feature branches with PR reviews
• Version Tags: Semantic versioning (v1.0.0 format)

🔄 Development Lifecycle

1. Planning Phase

• Requirements Analysis: Break down user requests
• Technical Design: Plan implementation approach
• Risk Assessment: Identify potential issues
• Timeline Estimation: Realistic delivery expectations

2. Implementation Phase

• Incremental Development: Small, testable changes
• Continuous Validation: Regular testing and validation
• Documentation Updates: Keep docs current
• Code Reviews: Self-review and improvement

3. Testing Phase

• Unit Testing: Individual component validation
• Integration Testing: End-to-end functionality
• Edge Cases: Error handling and edge conditions
• Cross-browser Testing: Chrome compatibility

4. Deployment Phase

• Version Bumping: Semantic version updates
• Packaging: Clean extension builds
• Release Notes: Comprehensive changelog
• Rollback Plan: Emergency recovery procedures

📊 Quality Assurance

Automated Checks

• Manifest Validation: JSON structure and required fields
• File Integrity: All required files present
• Code Quality: ESLint compliance
• Security Scan: Basic security checks

Manual Testing Checklist

• Extension loads without errors
• Settings page functions correctly
• Email filling works as expected
• Error handling is robust
• UI is responsive and accessible

🚨 Error Handling & Debugging

Common Issues

1. Manifest Errors: Invalid JSON or missing required fields
2. Permission Issues: Chrome Web Store API credentials
3. File Path Errors: Incorrect relative paths
4. Version Conflicts: Semantic versioning inconsistencies

Debug Commands

# Validate extension
bun run validate

# Check build status
bun run build

# View detailed logs
bun run pack

📈 Performance Monitoring

Metrics Tracked

• Build Time: GitHub Actions execution time
• File Sizes: Extension package size limits
• Error Rates: Failed workflow percentages
• Code Quality: Automated quality scores

Optimization Goals

• Build Speed: < 5 minutes for standard builds
• Package Size: < 1MB total extension size
• Zero Errors: All automated tests passing
• Fast Response: < 2 seconds for extension actions

🔒 Security Considerations

API Security

• Token Management: Secure credential storage
• Permission Scope: Minimal required permissions
• Data Privacy: No user data collection
• Code Review: Security-focused code analysis

Development Security

• Credential Handling: Never commit secrets
• Access Control: Repository permission management
• Audit Trail: Complete change history
• Incident Response: Security breach procedures

📚 Learning & Improvement

Knowledge Base

• Documentation: Comprehensive guides and references
• Code Examples: Reusable patterns and templates
• Best Practices: Industry standards and guidelines
• Troubleshooting: Common issues and solutions

Continuous Learning

• Technology Updates: Stay current with Chrome APIs
• Performance Optimization: Regular code reviews
• Security Updates: Monitor and implement fixes
• User Feedback: Incorporate improvement suggestions

🤝 Collaboration Guidelines

Working with AI Agents

1. Clear Communication: Provide specific, detailed requirements
2. Context Sharing: Include relevant background information
3. Iterative Feedback: Review and refine outputs
4. Documentation: Keep records of decisions and changes

Human-AI Partnership

• Strengths Combination: AI handles repetitive tasks, humans provide creative direction
• Quality Assurance: Human oversight ensures requirements are met
• Ethical Development: Responsible AI usage and data privacy
• Knowledge Transfer: Document processes for team scalability

📞 Contact & Support

For questions about AI agent workflows or development processes:

• Documentation: Check this file and related docs
• Issues: Create GitHub issues for bugs/features
• Discussions: Use GitHub Discussions for general questions
• Reviews: Request code reviews for complex changes

Last Updated: January 2026 Version: 0.2.0 Maintained by: Manuel Gruber