Ai Dev Agents

Autonomous AI development team coordination built on Claude Code Agent Teams architecture. Enables Team Leads to orchestrate specialized AI teammates (PM, Architect, Developer, QA, Security) through shared task lists, inter-agent messaging, and persistent learning.

Features

Core Coordination

• Claude Code Agent Teams Integration: Native support for spawning and orchestrating AI teammates
• Shared Task List: Centralized task management with file ownership tracking
• Inter-Agent Messaging: Direct peer-to-peer communication between teammates
• File Conflict Detection: Prevents parallel edits to the same files

Workflows

• Graceful Shutdown: Coordinated shutdown requests with approval/rejection flows
• Plan Approval: PM and Architect teammates submit plans for Team Lead review
• Code Review: Peer review requests with approval tracking
• Branch Management: Feature branch coordination with PR creation

Learning & Intelligence

• Hybrid Learning System: MCP Memory (real-time) + Git (persistent)
• Consensus Validation: Patterns validated by multiple teammates before persisting
• Requirements Management: BACKLOG.md and GitHub Issues parsing with RICE scoring
• Stakeholder Simulation: AI personas evaluate requirement impact

Installation

Prerequisites

1. Claude Code with Agent Teams:

   # Enable experimental Agent Teams feature
   export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
   

2. Node.js 18+: Required for TypeScript and MCP server

Setup

# Clone repository
cd /path/to/ai-dev-agents

# Install dependencies
npm install

# Build TypeScript
npm run build

# Configure MCP server in Claude Code settings
# Add to ~/.claude/settings.json:
{
  "mcpServers": {
    "ai-dev-agents-mcp": {
      "command": "node",
      "args": ["/path/to/ai-dev-agents/dist/index.js"],
      "env": {}
    }
  }
}

Usage

Use the /ai-dev-team skill in Claude Code for quick team spawning, or see CLAUDE.md for manual control and advanced patterns.

/ai-dev-team spawn standard

Testing

Running Tests

# Run all tests
npm test

# Run specific test file
npm test lifecycle.test.ts

# Run with coverage
npm test -- --coverage

# Watch mode (re-runs on file changes)
npm run test:watch

Test Coverage

The project maintains >80% test coverage across unit and integration tests.

Unit Tests

Individual module validation with focused test cases:

• src/tasks.test.ts - Task creation, claiming, file conflict detection (8 test cases)

  • File ownership conflict detection
  • Task status transitions
  • MCP tool interface validation

• src/lifecycle.test.ts - Shutdown workflow validation (12 test cases)

  • Shutdown request creation and tracking
  • Approval and rejection flows
  • Multiple agent coordination
  • State transitions

• src/team.test.ts - Permission inheritance documentation (6 test cases)

  • Team member structure validation
  • spawn_teammate MCP tool parameters
  • Permission adjustment scenarios

• src/pm-workflow.test.ts - PM requirements management (8 test cases)

  • RICE scoring and prioritization
  • Autonomous decision-making by confidence level
  • Plan approval workflow

• src/requirements/backlog-parser.test.ts - BACKLOG.md parsing (7 test cases)

  • Markdown parsing with priority markers
  • RICE metadata extraction
  • MoSCoW categorization

• src/requirements/github-issues.test.ts - GitHub Issues integration (6 test cases)

  • Issue fetching and parsing
  • Label-based priority inference
  • Metadata extraction

• src/tools/requirements.test.ts - MCP tool interfaces (5 test cases)

  • list_requirements tool validation
  • evaluate_stakeholder_impact tool
  • request_requirement_clarification tool

Integration Tests

End-to-end workflow validation across modules:

• src/integration.test.ts - Cross-module workflow coordination (15 test cases)

  Team Coordination (3 tests):

  • Complete workflow: team creation → spawn → task → completion
  • File conflict detection prevents parallel edits
  • Multiple tasks in parallel without conflicts

  Messaging Integration (3 tests):

  • Complete message flow: send → receive → mark read
  • Broadcast pattern to multiple recipients
  • Multi-message conversation workflow

  Shutdown Integration (3 tests):

  • Graceful shutdown with approval
  • Shutdown rejection with reason
  • Multiple shutdown requests tracked independently

  Cross-Module Workflows (6 tests):

  • Complete feature workflow: task → implement → message → review → complete
  • Conflict resolution workflow with messaging
  • Shutdown coordination with task cleanup

Test Philosophy

Unit Tests:

• Validate individual module behavior in isolation
• Mock external dependencies (Git, GitHub API, filesystem)
• Fast execution (<2 seconds for unit suite)
• Focus on our MCP server logic, not framework internals

Integration Tests:

• Validate cross-module workflows end-to-end
• Simulate complete user scenarios
• Test state management and coordination
• No external dependencies (in-memory only)
• Fast execution (<5 seconds for integration suite)

What We Don't Test:

• Claude Code Agent Teams framework behavior (trust spawn_teammate, delegate mode, etc.)
• External APIs (GitHub, Git) - mocked or skipped
• UI/UX - this is a headless MCP server

Coverage Goals:

• Critical paths: 100% (team coordination, task claiming, messaging)
• Business logic: >90% (requirements parsing, RICE scoring, stakeholder simulation)
• Edge cases: >80% (error handling, conflict detection, state transitions)
• Overall: >80% line coverage

Continuous Testing

Tests run automatically on:

• Pre-commit hooks (via git hooks)
• Pull request creation
• Main branch commits

Development

Development Workflow

# Build TypeScript
npm run build

# Watch mode (rebuilds on file changes)
npm run dev

# Start MCP server
npm start

# Run tests in watch mode
npm run test:watch

Project Structure

ai-dev-agents/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── server.ts             # MCP protocol implementation
│   ├── team.ts               # Team and teammate registry
│   ├── tasks.ts              # Task list storage and conflict detection
│   ├── messages.ts           # Inter-agent messaging queue
│   ├── lifecycle.ts          # Shutdown coordination
│   ├── learning.ts           # Pattern learning and validation
│   ├── planning.ts           # Plan approval workflow
│   ├── review.ts             # Code review requests
│   ├── branches.ts           # Branch management
│   ├── pr.ts                 # Pull request coordination
│   ├── hooks.ts              # Quality gate hooks
│   ├── roles.ts              # Agent role definitions
│   ├── types.ts              # TypeScript type definitions
│   ├── requirements/         # Requirements management
│   │   ├── sources.ts        # Multi-source requirement aggregation
│   │   ├── backlog-parser.ts # BACKLOG.md parsing
│   │   ├── github-issues.ts  # GitHub Issues integration
│   │   ├── prioritizer.ts    # RICE scoring
│   │   └── stakeholder.ts    # Stakeholder simulation
│   └── tools/                # MCP tool definitions
│       └── requirements.ts   # Requirements MCP tools
├── dist/                     # Compiled JavaScript (generated)
├── .planning/                # Project planning documents
├── CLAUDE.md                 # Manual control documentation
├── README.md                 # This file
├── package.json              # Dependencies and scripts
└── tsconfig.json             # TypeScript configuration

Adding New Features

1. Define Types: Add type definitions to src/types.ts
2. Implement Logic: Create module in src/ (e.g., src/my-feature.ts)
3. Add MCP Tools: Register tools in src/server.ts or dedicated tool file
4. Write Tests: Create unit tests (src/my-feature.test.ts) and integration tests
5. Update Documentation: Document in README.md and CLAUDE.md
6. Test Coverage: Ensure >80% coverage for new code

Debugging

Enable MCP Server Logging:

# Set debug level in environment
DEBUG=mcp:* npm start

Check Claude Code Logs:

tail -f ~/.claude/logs/mcp.log | grep ai-dev-agents-mcp

Test Individual MCP Tools:

# Use Node.js REPL to test tools directly
node
> import { callMessageTool } from './dist/messages.js'
> await callMessageTool('send_message', { from: 'dev1', to: 'dev2', content: 'test' })

Architecture

MCP Server Components

Team Registry:

• Tracks active teams and teammates
• Stores spawn metadata and status
• Provides team lookup and status updates

Task Store:

• In-memory task list with CRUD operations
• File ownership tracking and conflict detection
• Status transitions (pending → in_progress → completed)

Message Queue:

• Peer-to-peer messaging between agents
• Unread message tracking
• Inbox filtering by read status

Shutdown Manager:

• Graceful shutdown request/approval workflow
• Tracks pending shutdown requests
• Prevents duplicate requests per agent

Learning System:

• Pattern proposal and consensus validation
• Git persistence for cross-session learning
• MCP Memory for real-time access

Requirements Management:

• BACKLOG.md and GitHub Issues parsing
• RICE scoring (Reach × Impact × Confidence / Effort)
• Stakeholder simulation with AI personas
• Autonomous PM decision-making

MCP Protocol

The server exposes resources and tools via the Model Context Protocol:

Resources:

• memory:///team - Team configuration and member list
• memory:///tasks - Shared task list
• memory:///patterns - Learned patterns and best practices
• tasks:///{taskId} - Individual task details

Tools:

• spawn_teammate - Create new AI teammate
• send_message, get_inbox, mark_read - Messaging
• create_task, list_tasks, update_task - Task management
• check_file_conflicts - File ownership validation
• request_shutdown, approve_shutdown, reject_shutdown - Shutdown coordination
• submit_plan_approval, respond_plan_approval - Plan review
• request_review, respond_review - Code review
• list_requirements, evaluate_stakeholder_impact - Requirements management

Claude Code Integration

The MCP server works within Claude Code's Agent Teams architecture:

1. Team Lead spawns in delegate mode (coordination only)
2. Team Lead uses spawn_teammate MCP tool to create specialized teammates
3. Teammates inherit Team Lead's permissions (file access, sandbox, tools)
4. All coordination happens through MCP tools (no direct Claude API calls)
5. Teammates work independently, coordinating via task list and messages
6. Learning persists to Git for cross-session knowledge sharing

Design Principles

Fail-Fast on Conflicts: Task claiming throws errors on file conflicts, forcing explicit resolution.

In-Memory State: All state kept in-memory for fast access. Git used only for persistent learning.

No External Dependencies in Tests: Tests mock Git, GitHub API, and filesystem for fast, reliable execution.

Trust the Framework: We test our MCP server logic, not Claude Code Agent Teams framework behavior.

Autonomous Decision-Making: PM and teammates make operational decisions autonomously, escalating only when needed.

Contributing

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes with tests
4. Verify tests pass: npm test
5. Commit with conventional commits: git commit -m "feat: add my feature"
6. Push and create pull request

Commit Message Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• test: Add or update tests
• docs: Documentation changes
• refactor: Code refactoring
• chore: Build/tooling changes

Examples:

feat(tasks): add file ownership conflict detection
test(integration): add cross-module workflow tests
docs(readme): update testing documentation

Code Review Checklist

• Tests written and passing (npm test)
• Type checking passes (npm run build)
• Coverage >80% for new code
• Documentation updated (README.md, CLAUDE.md)
• Conventional commit messages
• No external dependencies added without discussion

License

ISC

Support

For issues, feature requests, or questions:

• Open a GitHub issue
• Check CLAUDE.md for detailed usage patterns
• Review .planning/ directory for project roadmap

Acknowledgments

Built on:

• Claude Code Agent Teams: Anthropic's AI orchestration framework
• Model Context Protocol (MCP): Standardized AI tool interface
• TypeScript: Type-safe implementation
• Vitest: Fast unit testing framework