archai

Multi-agent AI development workflow for any project.

archai sets up a sophisticated multi-agent system for Claude Code that transforms how you build software. Instead of one AI assistant, you get a team of specialized agents working together through a structured three-phase workflow.

Philosophy: Think Before Acting

This agent system implements a three-phase iteration architecture:

1. Phase 1: Planning Loop - Think, validate, design tests, validate tests, rethink (2-4 iterations)
2. Phase 2: Implementation Loop - Implement, test, review (only after Phase 1 approved)
3. Phase 3: Finalization - Verify, cleanup, commit, push, CI/CD verification

Key Insight: The cost of thinking is much lower than the cost of re-implementing. Most bugs come from insufficient planning, not insufficient coding skill.

The Three-Phase Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         PHASE 1: PLANNING LOOP                               │
│                      (Think deeply BEFORE any code)                          │
│                                                                              │
│   ┌─────────┐   ┌───────────┐   ┌───────────┐   ┌──────────┐   ┌─────────┐ │
│   │  THINK  │──▶│ VALIDATE  │──▶│   TEST    │──▶│ VALIDATE │──▶│ RETHINK │ │
│   │ (deep-  │   │ (plan-    │   │  DESIGN   │   │  TESTS   │   │ (deep-  │ │
│   │ analyst)│   │ validator)│   │ (tdd-     │   │ (critic) │   │ analyst)│ │
│   └─────────┘   └───────────┘   │ designer) │   └──────────┘   └─────────┘ │
│        ▲                        └───────────┘                       │       │
│        │                   ◀─── ITERATE 2-4x ───────────────────────┘       │
│                                                                              │
│   EXIT: Plan + Tests validated + All questions answered                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
              ╔═══════════════════════════════════════════╗
              ║     🛑 AWAIT USER PLAN APPROVAL 🛑        ║
              ╚═══════════════════════════════════════════╝
                                   │
                                   ▼ (only on APPROVE)
┌─────────────────────────────────────────────────────────────────────────────┐
│                       PHASE 2: IMPLEMENTATION LOOP                           │
│                      (Only after user approves plan)                         │
│                                                                              │
│   ┌──────────────┐    ┌─────────┐    ┌────────────┐                         │
│   │  IMPLEMENT   │───▶│  TEST   │───▶│   REVIEW   │                         │
│   │(implement-   │    │  (run)  │    │ (code-     │                         │
│   │ation-agent)  │    │         │    │  reviewer) │                         │
│   └──────────────┘    └─────────┘    └────────────┘                         │
│          ▲                                │                                  │
│          │        ◀─── ITERATE ───────────┘                                  │
│                                                                              │
│   EXIT: Tests pass + Review approved                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
              ╔═══════════════════════════════════════════╗
              ║   🛑 AWAIT USER FINAL APPROVAL 🛑         ║
              ╚═══════════════════════════════════════════╝
                                   │
                                   ▼ (only on APPROVE)
┌─────────────────────────────────────────────────────────────────────────────┐
│                       PHASE 3: FINALIZATION                                  │
│                    (finalization-agent handles)                              │
│                                                                              │
│   ┌──────────┐   ┌─────────┐   ┌────────┐   ┌────────┐   ┌─────────────┐   │
│   │  VERIFY  │──▶│ QUALITY │──▶│CLEANUP │──▶│ COMMIT │──▶│  WAIT FOR   │   │
│   │ CRITERIA │   │ CHECKS  │   │        │   │ + PUSH │   │   CI/CD     │   │
│   └──────────┘   └─────────┘   └────────┘   └────────┘   └─────────────┘   │
│                                                                              │
│   EXIT: CI passes + All verified                                            │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                            ┌──────────────┐
                            │   COMPLETE   │
                            └──────────────┘

Features

• 9 Core Agents - Pre-built orchestration agents for planning, implementation, and quality assurance
• Dynamic Specialists - Claude Code generates project-specific specialists based on your tech stack
• Three-Phase Workflow - Planning Loop → Implementation Loop → Finalization
• Language Agnostic - Works with any language, framework, or tech stack
• Task Management - Built-in epic/task tracking system

Quick Start

# Install globally
npm install -g @zik000/archai

# Initialize in your project
cd your-project
archai init

# Fill in the generated files:
# - archai.config.md (your tech stack and specialists)
# - .knowledge/context/project-description.md (project context)

# Generate specialist agents
archai generate

# Start using with Claude Code
claude
> "Use iteration-controller for: [your task]"

Requirements

• Node.js 18+
• Claude Code CLI - Install from claude.ai/code
• Claude Code must be authenticated

Commands

archai init

Initialize archai in your project. Runs an interactive wizard to gather project information.

archai init              # Interactive wizard
archai init --skip-wizard    # Use detected defaults
archai init --force      # Overwrite existing setup

Creates:

• .claude/agents/ - Agent definitions
• .claude/state/ - Working state (gitignored)
• .knowledge/ - Permanent knowledge base
• .tasks/ - Task management
• archai.config.md - Configuration file
• PROMPTS.md - Quick reference for all prompts

archai generate

Generate specialist agents based on your configuration.

archai generate          # Generate all specialists
archai generate --dry-run    # Preview without writing
archai generate -y       # Skip confirmation

This command:

1. Reads your archai.config.md
2. Calls Claude Code CLI to generate each specialist
3. Writes specialists to .claude/agents/

archai doctor

Validate your archai setup.

archai doctor

Checks:

• Configuration file exists and is valid
• Required directories exist
• Core agents are installed
• Claude Code CLI is available

Agent Roles

Phase 1 Agents (Planning)

| Agent | Purpose | Focus | |-------|---------|-------| | deep-analyst | Deep analysis, initial planning, rethinking | Understanding the REAL problem | | plan-validator | Challenge plans, find gaps | Breaking assumptions | | tdd-designer | Design tests BEFORE code | Real user workflows |

Phase 2 Agents (Implementation)

| Agent | Purpose | Focus | |-------|---------|-------| | implementation-agent | Execute the validated plan | Following specs exactly | | code-reviewer | Verify implementation | Finding problems |

Phase 3 Agents (Finalization)

| Agent | Purpose | Focus | |-------|---------|-------| | cleanup-agent | Clean temporary work files | Before committing | | finalization-agent | Post-implementation finalization | Verify, cleanup, commit, push, CI/CD |

Orchestrator

| Agent | Purpose | |-------|---------| | iteration-controller | Manages all three phases, handles escalation | | task-orchestrator | Manages epic/task lifecycle from .tasks/inbox/ |

Specialist Agents (Generated)

Specialists are generated dynamically by Claude Code based on your project. They understand:

• Your specific tech stack and versions
• Actual file paths in your codebase
• Existing patterns and conventions
• Testing frameworks you use

Example specialists:

• frontend-specialist - React/Vue/Angular expertise
• backend-specialist - Express/FastAPI/Django expertise
• database-specialist - SQL/NoSQL optimization
• auth-specialist - Authentication/authorization

Key Principles

1. No Code Without Validated Plan

Never skip Phase 1. Every implementation must have:

• Dependency analysis
• Risk assessment
• Test design with concrete values
• All questions answered

2. Human Approval Gate

Phase 1 outputs a plan document to .claude/plans/{task}.md. The workflow STOPS and waits for user to:

• APPROVE → Proceed to Phase 2
• REVISE → Return to Phase 1 with feedback
• REJECT → Stop entirely

No code is written until the user explicitly approves the plan.

3. Tests Define Done

Tests are designed FIRST, in Phase 1. Implementation follows. Tests must:

• Reflect real user workflows
• Use concrete values
• FAIL when code is wrong
• NOT mock core logic

4. Validation Is Adversarial

plan-validator exists to find problems, not approve plans. Expect:

• 2-4 planning iterations minimum
• Questions that force deeper thinking
• Rejection of vague plans

5. Iterate Until Right

Phase 1: Iterate until plan is specific, validated, and tests designed Phase 2: Iterate until tests pass and review approves

Directory Structure

After initialization:

your-project/
├── .claude/
│   ├── agents/             # Agent definitions
│   ├── plans/              # Approved plans (per task)
│   │   └── archived/       # Completed task plans
│   └── state/              # Working state (gitignored)
├── .knowledge/
│   ├── context/
│   │   └── project-description.md
│   ├── decisions/          # Architecture decisions
│   └── learnings/          # Learned patterns
├── .tasks/
│   ├── inbox/              # New tasks
│   ├── epics/              # Active work
│   ├── review/             # Awaiting merge
│   └── done/               # Completed
├── archai.config.md        # Configuration
└── PROMPTS.md              # Quick reference prompts

When to Use Which Agent

| Situation | Start With | |-----------|------------| | New feature | iteration-controller | | Bug fix (complex) | iteration-controller | | Bug fix (simple, <10 lines) | Direct fix, no agents | | Understanding code | deep-analyst only | | Test quality review | tdd-designer only | | Before committing | cleanup-agent | | Managing epics | task-orchestrator |

Why This Architecture?

Problem: Incomplete Plans

"Handle edge cases" leads to implementation guessing.

Solution: plan-validator rejects vague plans, forces specificity.

Problem: Code First, Think Later

Jumping to code before understanding leads to rewrites.

Solution: Three-phase architecture enforces 2-4 thinking iterations BEFORE any code.

Problem: Tests Written To Pass

Tests written after code tend to validate the implementation, not the requirement.

Solution: Tests designed BEFORE implementation, based on user stories, not code.

Problem: Agents Cut Corners

Without enforcement, agents skip steps and produce low-quality work.

Solution: Explicit phase gates, required artifacts, adversarial validation.

Common Mistakes to Avoid

Mistake 1: Skipping to implementation

# BAD
"Just implement the auth feature"

# GOOD
"Use iteration-controller to implement the auth feature.
Run Phase 1 first and wait for my APPROVE."

Mistake 2: Approving vague plans

# BAD plan that should be REVISED
"Step 3: Handle edge cases"

# GOOD plan that can be APPROVED
"Step 3: Handle boundary values
 - Empty input: Return validation error 'input_required'
 - Input > 1000 chars: Truncate with warning
 - Invalid characters: Reject with 'invalid_chars'"

Mistake 3: Interrupting Phase 2

# BAD
[Agent implementing step 2]
You: "How's it going? Should I help?"

# GOOD
[Let it run until DONE or BLOCKED]
[Only interrupt if truly necessary]

Troubleshooting

Agent isn't following instructions

1. Check if agent file content was passed in prompt
2. Verify output location is specified
3. Make task boundaries explicit

Tests are too shallow

1. Check if tdd-designer used all test categories (correctness, edge, boundary)
2. Verify concrete values used (not "test with valid input")

Phase 1 keeps iterating

1. After 4 iterations, check if requirements are unclear
2. May need to escalate to human for clarification
3. Check if plan-validator is rejecting for valid reasons

Implementation keeps failing

1. Check if plan was specific enough
2. Review test design - were edge cases covered?
3. After 5 attempts on same error, escalate

License

MIT

Contributing

Contributions welcome!

Built with Claude Code.