CD-Agent

AI development agent that embeds XP/CD best practices to achieve Elite DORA metrics.

Build the product right. Ship value fast. Learn continuously.

What is CD-Agent?

CD-Agent turns Claude Code into a disciplined engineering partner. Instead of just generating code, it enforces TDD, Clean Architecture, ATDD, and Continuous Delivery — the practices that separate elite teams from the rest.

Two modes of operation:

| Mode | What you get | Best for | |------|-------------|----------| | Commands Mode | 27 slash commands + 28 rules copied into your project | Quick setup, any Claude Code project | | MCP Server Mode | 11 tools with workflow enforcement, gate validation, license tiers | Full platform experience with automated gates |

Quick Start

cd your-project
npx avesta-cd-agent init

This copies commands, agents, MCP server config, and CLAUDE.md template into your project.

Then start Claude Code and run /cd-help to see your status and available commands.

Opt-out flags

| Flag | Effect | |------|--------| | --no-mcp | Skip MCP server configuration | | --no-claude-md | Skip CLAUDE.md template |

MCP Server: Manual Setup

If you prefer to configure the MCP server manually instead of using --with-mcp, create .mcp.json at your project root:

{
  "mcpServers": {
    "cd-agent": {
      "command": "npx",
      "args": ["avesta-cd-agent", "serve"]
    }
  }
}

Or point directly to the compiled binary:

{
  "mcpServers": {
    "cd-agent": {
      "command": "/path/to/cd-agent/dist/cd-agent"
    }
  }
}

Restart Claude Code and it will automatically connect to the MCP server and expose all 11 tools.

Commands

27 slash commands organized by workflow phase:

| Phase | Command | Purpose | |-------|---------|---------| | Setup | /cd-init [type] | Initialize CD-Agent workflow tracking | | Setup | /cd-scaffold | Scaffold project structure (greenfield) | | Help | /cd-help | Show status, gates, and next steps | | Vision | /vision | Define product vision, success metrics, scope | | Planning | /plan <feature> | Break feature into TDD-ready tasks (Example Mapping) | | Planning | /spike <question> | Technical exploration (disposable code, bypasses gates) | | ATDD | /acceptance-test | Write Executable Specification (Four-Layer Model) | | ATDD | /dsl | Implement Domain Specific Language layer | | ATDD | /driver | Implement Protocol Drivers (UI/API) | | TDD | /red <behavior> | Write ONE failing test | | TDD | /green | Minimal code to make it pass | | TDD | /refactor | Improve structure (tests must be green) | | TDD | /cycle <behavior> | Full red-green-refactor cycle | | TDD | /layer | All tests first, then all production code | | Change Type | /bug-fix <description> | Bug fix workflow (reduced gates) | | Change Type | /enhance <description> | Enhancement workflow (skip vision) | | Change Type | /tech-debt <description> | Tech debt workflow (approval tests) | | Review | /code-review | Domain-specific code review | | Ship | /commit | Conventional commit | | Ship | /ship | Merge to main | | CI/CD | /commit-stage | Set up commit stage workflow | | CI/CD | /release-stage | Set up release stage workflow | | CI/CD | /acceptance-stage | Set up acceptance stage workflow | | Metrics | /dora-init | Initialize DORA metrics tracking | | Metrics | /dora-report | Generate DORA metrics report | | Maintenance | /dependency-review | Review deps and generate gradual update plan | | Quality | /mutation-testing | Analyze test effectiveness with mutation testing | | Orchestration | /orchestrate | Route tasks to agents and enforce gates |

MCP Tools

11 tools available when running as an MCP server:

| Tool | Purpose | |------|---------| | cd_dispatch | Classify intent, check gates, route to the correct agent | | cd_get_prompt | Return agent system prompt with skills and constraints | | cd_get_skill | Return skill content by key (e.g. testing/sociable-unit-test) | | cd_read_state | Read current workflow state (phase, gates, project metadata) | | cd_write_state | Update workflow state | | cd_check_gate | Check if a specific gate is approved | | cd_approve_gate | Approve a gate (validates prerequisites) | | cd_unapprove_gate | Unapprove a gate (cascades to dependents) | | cd_get_status | Formatted workflow status with gate icons | | cd_validate_license | Validate and activate a license key | | cd_get_catalog | Return the complete framework catalog |

Workflow & Gates

8 phases, 6 gates. Each gate requires its prerequisite before proceeding.

  idle ──▶ vision ──▶ plan ──▶ atdd ──▶ tdd ──▶ driver ──▶ review ──▶ ship
              │          │        │         │          │          │
              ▼          ▼        ▼         ▼          ▼          ▼
         vision_     plan_    atdd_     tdd_      driver_    review_
         approved    approved approved  complete  complete   approved

Gate prerequisite chain:

vision_approved ◀── (none)
plan_approved ◀── vision_approved
atdd_approved ◀── plan_approved
tdd_complete ◀── atdd_approved
driver_complete ◀── tdd_complete
review_approved ◀── driver_complete

Gates are enforced in MCP Server Mode (pro tier and above). In Commands Mode, enforcement is advisory.

License Tiers

| Feature | Free | Pro | Team | Enterprise | |---------|------|-----|------|------------| | Agents | 6 (init, scaffolder, cd-help, red, green, refactorer) | All 28 | All 28 | All 28 | | Skills | None | All 27 | All 27 | All 27 | | Gate enforcement | No | Yes | Yes | Yes | | Max projects | 1 | Unlimited | Unlimited | Unlimited |

Free tier gives you the core TDD loop. Pro unlocks the full 8-phase workflow with all agents, skills, and gate enforcement.

Skills (27)

Contextual knowledge injected into agent prompts. Grouped by category:

Testing (13): Sociable Unit (BE/FE), Component (BE/FE), Narrow Integration (BE/FE), Contract (Consumer/Provider), Acceptance Tests, Test Flakiness, Test Data Builders, Test Doubles, Mutation Testing

Architecture (8): Clean Architecture (BE/FE), Controller Pattern, Infrastructure Services, Atomic Design, Code Style, Dependency Management, Domain Logic Placement

Craftsmanship (3): Clean Code, Tidy First, Design Patterns

CI/CD (3): Commit Stage Pipeline, Release Stage Pipeline, Acceptance Stage Pipeline

Architecture

CD-Agent enforces Clean Architecture and a comprehensive test pyramid. See CLAUDE.md for full XP/CD practices, test strategy, and development workflow details.

┌──────────────────────────────────────┐
│          PRESENTATION                │
│  Controllers, Routes, Components     │
├──────────────────────────────────────┤
│          APPLICATION                 │
│  Use Cases (business orchestration)  │
├──────────────────────────────────────┤
│            DOMAIN                    │
│  Entities, Value Objects, Ports      │
├──────────────────────────────────────┤
│         INFRASTRUCTURE               │
│  Repositories, Services (Adapters)   │
└──────────────────────────────────────┘
     Dependencies point inward ▲

┌─────────────────────────────────────┐
│  SYSTEM TESTS (separate repo)       │
│  Acceptance │ E2E │ Smoke           │
├─────────────────────────────────────┤
│  COMPONENT TESTS (same repo)        │
│  Component │ Contract │ Unit │ Int. │
└─────────────────────────────────────┘

CLI Reference

npx avesta-cd-agent init               # Full setup (commands, agents, MCP, CLAUDE.md)
npx avesta-cd-agent init --no-mcp      # Skip MCP server configuration
npx avesta-cd-agent init --no-claude-md # Skip CLAUDE.md template
npx avesta-cd-agent serve              # Start MCP server (used by Claude Code)
npx avesta-cd-agent help               # Show CLI help

Development

# Run MCP server in dev mode
npm run dev

# Embed assets and build binary
npm run build:binary

# Build for all platforms
npm run build:all

# TypeScript compilation
npm run build

Building from Source

Requires Bun for binary compilation:

npm run prebuild:assets    # Embed commands/rules/catalog into TypeScript
npm run build:binary       # Compile to single binary at dist/cd-agent

Cross-platform binaries: dist/cd-agent-linux-x64, dist/cd-agent-darwin-arm64, dist/cd-agent-darwin-x64.

Requirements

• Node.js >= 18
• Claude Code CLI
• Bun (only for building binaries)

License

MIT — Avesta Technologies

Issues and PRs welcome at github.com/chirag1507/cd-agent.