Multi-Agent Feature Development System

Automated feature implementation using coordinated AI agents

🎯 What Is This?

This is an automated feature development workflow that uses multiple specialized AI agents to plan, implement, review, test, and commit code changes. Simply describe what you want built, and the system handles the entire development lifecycle.

🚀 Quick Start

1. Request a Feature

In your GitHub Copilot conversation, invoke the Feature Builder agent:

@Feature Builder: Add user email validation that checks format and blocks disposable email providers

2. Sit Back and Watch

The system will automatically:

• ✅ Create an implementation plan
• ✅ Validate against existing code patterns
• ✅ Write the implementation with tests
• ✅ Review code for quality and security
• ✅ Run tests with coverage checks
• ✅ Commit with proper formatting

3. Review the Results

When complete, you'll have:

• Working, tested code
• Git commit with conventional message
• Detailed artifacts documenting the process

📊 How It Works

graph TD
    You[You: Describe Feature] --> FB[Feature Builder]
    FB --> P[Planner: Break Into Tasks]
    P --> PA[Plan Architect: Validate Against Codebase]
    PA -->|Needs Changes| P
    PA -->|Approved| I[Implementer: Write Code + Tests]
    I --> R[Thorough Reviewer: Check Quality]
    R -->|Issues Found| I
    R -->|Approved| T[Tester: Run Pytest]
    T -->|Failures| I
    T -->|Passed| GC[Git Committer: Pre-commit Hooks + Commit]
    GC --> Done[✅ Feature Complete]

Loading

🎯 The Agents

Agent	Role	What It Does
Feature Builder	Orchestrator	Coordinates all agents, manages workflow
Planner	Task Designer	Breaks feature into actionable tasks
Plan Architect	Code Reuse Expert	Finds existing patterns to reuse
Implementer	Developer	Writes code and unit tests
Thorough Reviewer	Quality Checker	Reviews for correctness, security, quality
Tester	QA Engineer	Runs pytest, checks 100% coverage
Git Committer	Release Manager	Runs pre-commit hooks, makes commit

💡 How to Request Features

The Interactive Process

The workflow includes a mandatory approval checkpoint after planning. Here's what to expect:

1. You submit request → Feature Builder starts planning
2. Planning completes → You receive plan for review
3. You approve/revise → Implementation begins
4. System completes → You receive working code

Be Specific

Good:

@Feature Builder: Create a password strength validator that:
- Requires minimum 8 characters
- Checks for uppercase, lowercase, numbers, special chars
- Returns detailed feedback on what's missing
- Includes tests for edge cases

Too Vague:

@Feature Builder: Add some password checking

Include Context

Good:

@Feature Builder: Add pagination to the user list endpoint.
Should work with our existing Flask app and return pages
of 20 users. Include page number and total pages in response.

Missing Context:

@Feature Builder: Add pagination

Mention Constraints

Good:

@Feature Builder: Add CSV export for reports. Must use the
existing ReportGenerator class and work with Python 3.11+.
Export should include headers and handle Unicode properly.

Missing Constraints:

@Feature Builder: Add CSV export

📈 Workflow Phases

Phase 1: Planning 📋

What happens:

1. Planner breaks your request into tasks
2. Plan Architect searches codebase for reusable patterns
3. If architect finds issues, plan is revised
4. Maximum 3 iterations, then escalates if stuck
5. ✅ PAUSE: Waiting for your approval

You'll see:

✅ Phase 1: Planning - approved (2/3 iterations)

📋 Plan ready for review:
- Plan: .github/artifacts/plans/your-feature.md
- Architecture review: .github/artifacts/reviews/plan-your-feature-review.md

👉 Please review and respond:
- "approve" or "proceed" → Continue to implementation
- "revise: [your feedback]" → Update plan with your changes
- "cancel" → Stop workflow

Your action required:

1. Read the plan artifact to understand what will be implemented
2. Read the architecture review to see reuse opportunities
3. Respond with one of:
   • "approve" or "proceed" - Start implementation
   • "revise: [feedback]" - Request plan changes (e.g., "revise: use FastAPI instead of Flask")
   • "cancel" - Stop the workflow

Output artifacts:

• .github/artifacts/plans/your-feature.md
• .github/artifacts/reviews/plan-your-feature-review.md

Phase 2: Implementation 💻

What happens:

1. Implementer writes code following the plan
2. Creates unit tests for every function (100%+ coverage required)
3. Thorough Reviewer checks code quality in parallel:
   • Correctness (logic, edge cases)
   • Quality (readability, naming)
   • Security (validation, injection risks)
   • Architecture (pattern consistency)
4. If issues found, implementer fixes them
5. Maximum 3 iterations, then escalates if stuck

You'll see:

✅ Phase 2: Implementation - approved (1/3 iterations)

Output artifact:

• .github/artifacts/reviews/code-your-feature-review.md
• Source files created/modified
• Test files created

Phase 3: Testing ✅

What happens:

1. Tester runs pytest -v --cov
2. Verifies 100% minimum coverage
3. Checks all tests pass
4. If failures, implementer fixes issues
5. Maximum 3 iterations, then escalates if stuck

You'll see:

✅ Phase 3: Testing - passed (1/3 iterations)

Output artifact:

• .github/artifacts/test-reports/your-feature-test-report.md

Phase 4: Commit 📝

What happens:

1. Git Committer runs pre-commit hooks:
   • Black (formatting)
   • isort (imports)
   • Ruff (linting)
   • Mypy (type checking)
   • Pytest (tests)
   • And more (see Pre-commit Hooks)
2. If hooks fail, implementer fixes issues
3. Creates conventional commit
4. Maximum 3 retries, then escalates if stuck

You'll see:

✅ Phase 4: Commit - complete

Commit: feat(auth): add email validation with disposable provider blocking

⚠️ When Things Get Stuck

If any phase reaches maximum iterations (3), you'll receive an escalation message:

⚠️ Feature implementation blocked - manual intervention needed

Feature: email-validation
Blocked at: Testing - Pytest failures
Iterations: 3/3

Summary of attempts:

1. Iteration 1: Fixed email regex pattern
2. Iteration 2: Added edge case for internationalized domains
3. Iteration 3: Still failing on Unicode edge case

Current blocker:
Test test_unicode_email_domains is failing with UnicodeDecodeError
when processing emails with emoji in local part.

Suggested manual action:

1. Review test case in tests/test_validation.py:45
2. Decide if emoji emails should be supported
3. Either fix implementation or update test expectations

Relevant artifacts:

- Plan: .github/artifacts/plans/email-validation.md
- Test report: .github/artifacts/test-reports/email-validation-test-report.md
- Code review: .github/artifacts/reviews/code-email-validation-review.md

What to do:

1. Review the artifacts mentioned
2. Understand the blocker
3. Make a decision (fix code, update plan, or change requirements)
4. Either fix manually or provide clearer guidance to Feature Builder

📁 Artifacts & Documentation

All process artifacts are stored in .github/artifacts/:

.github/artifacts/
├── plans/                    # Implementation plans
│   ├── feature-name-draft.md   # Initial plan
│   └── feature-name.md          # Approved plan
├── reviews/                  # Quality reviews
│   ├── plan-feature-name-review.md  # Architecture review
│   └── code-feature-name-review.md  # Code review
└── test-reports/             # Test results
    └── feature-name-test-report.md

These artifacts give you:

• 📋 Traceability: See why decisions were made
• 🔍 Debugging: Understand what went wrong
• 📚 Learning: Review best practices applied
• ✅ Verification: Confirm quality checks passed

🎓 Examples

Example 1: Interactive Approval Workflow

Your request:

@Feature Builder: Create a Calculator class with add, subtract, multiply, divide methods

Feature Builder response:

Starting feature implementation: calculator

✅ Phase 1: Planning - approved (1/3 iterations)
   - Planner created 6 tasks
   - Plan Architect: No existing patterns found, new implementation approved

📋 Plan ready for review:
- Plan: .github/artifacts/plans/calculator.md
- Architecture review: .github/artifacts/reviews/plan-calculator-review.md

👉 Please review and respond:
- "approve" or "proceed" → Continue to implementation
- "revise: [your feedback]" → Update plan with your changes
- "cancel" → Stop workflow

You review the plan (opens calculator.md) and see it's good:

approve

Feature Builder continues:

✅ User approved plan - proceeding to implementation

🔄 Phase 2: Implementation - iteration 1/3
   - Implementer writing code following TDD approach
   - Creating tests/test_calculator.py first
   - Implementing app/calculator.py

✅ Phase 2: Implementation - approved (1/3 iterations)
   - Thorough Reviewer: All checks passed

✅ Phase 3: Testing - passed (1/3 iterations)
   - All 20 tests passed
   - Coverage: 100%

✅ Phase 4: Commit - complete
   - Pre-commit hooks: All passed
   - Commit: feat: add Calculator class with basic arithmetic operations

Feature complete!

Example 2: Requesting Plan Revisions

Your request:

@Feature Builder: Add user authentication to the API

Feature Builder:

✅ Phase 1: Planning - approved (1/3 iterations)

📋 Plan ready for review:
- Plan: .github/artifacts/plans/user-authentication.md
...

You review and want changes:

revise: Use JWT tokens instead of sessions, and add password reset functionality

Feature Builder:

Sending revision request to Planner...

✅ Phase 1: Planning - approved (2/3 iterations)
   - Updated to use JWT authentication
   - Added password reset flow with email tokens

📋 Updated plan ready for review:
- Plan: .github/artifacts/plans/user-authentication.md
...

You review again and approve:

proceed

Example 3: Simple Utility Function

Request:

@Feature Builder: Create a function to slugify strings (convert
"Hello World!" to "hello-world"). Should handle Unicode, remove
special characters, and convert spaces to hyphens.

Result:

• File: app/utils/text.py with slugify() function
• Tests: tests/test_text.py with 15+ test cases
• Coverage: 98%
• Time: ~5 minutes

Example 4: API Endpoint

Request:

@Feature Builder: Add a REST API endpoint GET /api/users/{id}/profile
that returns user profile data. Should use existing User model, return
JSON, handle 404 for missing users, and require authentication.

Result:

• File: src/api/users.py with endpoint
• Tests: tests/test_user_api.py with auth, 404, success cases
• Uses existing: Authentication middleware, User model
• Coverage: 94%
• Time: ~10 minutes

Example 3: Feature with Dependencies

Request:

@Feature Builder: Implement password reset via email. User submits
email, receives reset token, uses token to set new password. Tokens
expire after 1 hour. Use existing EmailService and User model.

Result:

• Files: src/auth/password_reset.py, src/auth/tokens.py
• Tests: Token generation, expiry, email sending, edge cases
• Database: New token storage table
• Integration: With existing EmailService
• Coverage: 96%
• Time: ~20 minutes

⚙️ Project Standards

All code follows these guidelines:

Coding Standards

• Style: PEP 8, Black formatting (88 char lines)
• Functions: Max 50 lines, ideally 5-20
• Files: Max 500-1000 lines
• Naming: snake_case for functions, PascalCase for classes

See Coding Guidelines

Testing Requirements

• Coverage: Minimum 100%
• Framework: Pytest
• Methodology: Test-Driven Development (TDD) - write tests first, then implement
• Tests: One test file per module (test_*.py)
• Naming: test_{function}_{scenario}
• Cycle: 🔴 Red (failing test) → 🟢 Green (minimal code) → 🔵 Refactor (improve)

See Pytest README

Pre-commit Checks

• Black, isort, Prettier (formatting)
• Ruff, Mypy (linting, type checking)
• Pytest (tests + coverage)
• Security checks (no secrets, no large files)

See Pre-commit Hooks

🔧 Customization

Adjusting Code Standards

Edit .github/guidelines/CODING_GUIDELINES.md and agents will follow the new standards.

Modifying Pre-commit Hooks

Edit .github/templates/.pre-commit-config.yaml to add/remove hooks.

Changing Coverage Threshold

Edit pyproject.toml:

[tool.pytest.ini_options]
addopts = "--cov --cov-fail-under=90"  # Change 90 to desired %

Adding Custom Agents

See agents/README.md for how to create new agents.

📚 Documentation

• WORKFLOW.md - Detailed agent communication protocol
• agents/README.md - Complete agent registry
• guidelines/CODING_GUIDELINES.md - Code standards
• guidelines/PRECOMMITHOOKS.md - Pre-commit guide
• guidelines/PYTEST_README.md - Testing guide
• templates/ - Configuration templates

🐛 Troubleshooting

"Feature Builder not found"

Check that:

1. You're using @Feature Builder (case-sensitive)
2. The agent file exists at .github/agents/feature_builder.agent.md
3. Your Copilot has access to workspace agents

"All hooks pass but commit fails"

Check:

1. Git is properly initialized
2. You have commit permissions
3. No external git hooks interfering

"Tests pass locally but fail in agent"

Check:

1. All dependencies installed
2. Environment variables set
3. Database/fixtures properly configured

"Coverage below 100%"

Run locally:

pytest --cov --cov-report=html
open htmlcov/index.html

Find uncovered lines and add tests.

"Stuck in infinite loop"

This shouldn't happen (max 3 iterations per phase). If it does:

1. Check the iteration counter in status messages
2. Report as a bug in the agent system
3. Manually complete the feature

🎯 Best Practices

✅ DO

• Be specific and detailed in feature requests
• Review the plan carefully before approving - it's easier to change now than later
• Mention existing code patterns to reuse
• State constraints and requirements upfront
• Use "revise:" to request specific changes to the plan
• Review artifacts when escalated
• Check test coverage reports
• Read code reviews for learning

❌ DON'T

• Give vague requirements
• Approve plans without reviewing them - take time to understand what will be built
• Interrupt agents mid-phase (except at approval checkpoints)
• Bypass pre-commit hooks
• Ignore escalation messages
• Skip reviewing generated code
• Assume context without stating it

📝 Quick Reference: Approval Commands

When Feature Builder pauses for your approval after planning:

Command	Action	Usage
approve	Proceed to implementation with current plan	Use when plan looks good
proceed	Same as approve	Alternative command
revise: [feedback]	Send changes to Planner, stay in planning phase	revise: add error logging to all functions
cancel	Stop the workflow completely	Use if you want to abort

Examples:

approve

revise: Use PostgreSQL instead of SQLite

revise: Add caching layer and reduce database queries

cancel

🚦 Getting Started Checklist

Before requesting your first feature:

• Pre-commit hooks installed (pre-commit install)
• Pytest configured in pyproject.toml
• Python environment activated
• Dependencies installed (pip install -r requirements.txt)
• Git repository initialized
• Read Coding Guidelines

🤝 Contributing

To improve the agent system:

1. Report issues: If agents make bad decisions, document them
2. Suggest improvements: Better prompts, new agents, workflow changes
3. Update guidelines: Keep coding standards current
4. Share learnings: Document edge cases and solutions

📞 Support

• Questions: Ask in Copilot chat
• Agent issues: Check WORKFLOW.md for expected behavior
• Code standards: See guidelines/
• Escalations: Review artifacts in .github/artifacts/

🎉 Ready to Build!

The system is ready to use. Simply describe your feature and invoke:

@Feature Builder: [Your feature description here]

Happy coding! 🚀