@zik000/archai 0.1.4 → 0.2.0

package/README.md

@@ -1,486 +1,636 @@
-# 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
-
-- **10 Core Agents** - Pre-built orchestration agents for planning, implementation, and quality assurance
-- **Critical Review Mode** - Automated plan review via separate SDK session for blind spot detection
-- **Permission Presets** - Configurable permission settings (permissive/strict/custom) with safety guardrails
-- **Dynamic Specialists** - Claude Code generates project-specific specialists based on your tech stack
-- **Three-Phase Workflow** - Planning Loop → (Optional Critical Review) → Implementation Loop → Finalization
-- **Language Agnostic** - Works with any language, framework, or tech stack
-- **Task Management** - Built-in epic/task tracking system
-
-## Quick Start
-
-```bash
-# Install globally
-npm install -g @zik000/archai
-
-# Initialize in your project
-cd your-project
-archai init
-
-# Fill in the generated files (or use wizards):
-archai setup-project     # Interactive project description wizard
-archai setup-config      # Interactive configuration wizard
-
-# Generate specialist agents
-archai generate
-
-# Start using with Claude Code
-claude
-
-# Manual mode (default) - user approves at both gates
-> "Use iteration-controller for: [your task]"
-
-# Critical review mode - auto-approve with SDK critical review
-> "Use iteration-controller with critical-review for: [your task]"
-```
-
-## Requirements
-
-- **Node.js 18+**
-- **Claude Code CLI** - Install from [claude.ai/code](https://claude.ai/code)
-- Claude Code must be authenticated
-
-## Commands
-
-### archai init
-
-Initialize archai in your project. Runs an interactive wizard to gather project information.
-
-```bash
-archai init              # Interactive wizard
-archai init --skip-wizard    # Use detected defaults
-archai init --force      # Overwrite existing setup
-```
-
-Creates:
-- `.claude/agents/` - Agent definitions
-- `.claude/settings.local.json` - Permission settings (permissive mode by default)
-- `.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.
-
-```bash
-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 setup-project
-
-Interactive wizard to fill out your project description.
-
-```bash
-archai setup-project          # Interactive wizard
-archai setup-project --force  # Overwrite existing content
-```
-
-Guides you through:
-- Project overview and description
-- Architecture and key modules
-- Domain concepts and workflows
-- Technical constraints
-- Development guidelines
-- Current state and priorities
-
-### archai setup-config
-
-Interactive wizard to configure your project settings.
-
-```bash
-archai setup-config          # Interactive wizard
-archai setup-config --force  # Overwrite existing content
-```
-
-Configures:
-- Tech stack (languages, frameworks, testing)
-- Build commands (install, build, test, lint, dev)
-- Project structure
-- Specialist agents (with interactive loop to define multiple)
-- Permission presets (permissive/strict/custom) with `.claude/settings.local.json`
-- MCP/Skills placeholder section
-
-### archai doctor
-
-Validate your archai setup.
-
-```bash
-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 |
-| `critical-reviewer` | SDK-spawned blind spot detection | Fresh unbiased perspective |
-
-### 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. Approval Gates (Two Modes)
-
-Phase 1 outputs a **plan document** to `.claude/plans/{task}.md`. What happens next depends on the mode:
-
-**Manual Mode** (default):
-- Workflow **STOPS** and waits for user to: APPROVE / REVISE / REJECT
-- User reviews plan before any code is written
-- User reviews implementation before finalization
-
-**Critical Review Mode** (`with critical-review`):
-- Spawns a **separate SDK session** to critically review the plan
-- Fresh perspective catches blind spots the planning agent missed
-- Up to 2 review iterations with plan revisions
-- Auto-proceeds if review passes (no CRITICAL/HIGH issues)
-- Falls back to manual if unresolved issues after 2 iterations
-
-| Mode | Plan Gate | Final Gate | Best For |
-|------|-----------|------------|----------|
-| Manual | User approval | User approval | High-stakes changes, learning |
-| Critical Review | Auto (if passed) | Auto (if passed) | Routine tasks, trusted workflows |
-
-### 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
-
-## Permission Presets
-
-archai configures Claude Code permissions via `.claude/settings.local.json`. Three presets available:
-
-### Permissive (Default)
-
-Close to `--dangerously-skip-permissions` but with safety guardrails. Allows most operations while blocking irreversible actions:
-
-**Always Denied** (even in permissive mode):
-- Destructive file ops: `rm -rf *`, `rmdir /s`
-- Force git: `git push --force`, `git reset --hard`
-- System damage: `sudo *`, `chmod 777`, `mkfs*`
-- Credentials: `cat ~/.ssh/*`, `echo $*SECRET*`
-- Remote code exec: `curl * | bash`, `wget * | sh`
-- Database destruction: `DROP DATABASE`, `TRUNCATE TABLE`
-
-### Strict
-
-Production-safe preset. Only allows read-only operations and controlled writes:
-
-**Allowed**:
-- Package management: `npm install`, `pip install`, etc.
-- Build/test: `tsc`, `eslint`, `jest`, `pytest`
-- Read operations: `cat`, `grep`, `ls`, `git status`, `git diff`
-- Safe git: `git add`, `git commit`, `git checkout -b`
-
-**Denied** (in addition to Always Denied):
-- Network: `curl`, `wget`, `ssh`, `scp`
-- Publish: `npm publish`, `pip upload`
-- Push: `git push` (any form)
-- Process control: `kill`, `pkill`
-
-### Custom
-
-Define your own allow/deny lists via the wizard. Useful for specific project requirements.
-
-### Command Chaining
-
-Permissions validate **each segment** of chained commands:
-```bash
-npm install && npm test    # Both validated separately
-git add . && git push      # Would fail in strict mode (push denied)
-```
-
-## 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` |
-
-### When to Use Critical Review Mode
-
-| Situation | Mode | Why |
-|-----------|------|-----|
-| Learning the workflow | Manual | See how planning works |
-| High-stakes feature | Manual | Want full control |
-| Security-sensitive code | Manual | Extra human review |
-| Routine refactoring | Critical Review | Trust the review process |
-| Well-understood feature | Critical Review | Faster iteration |
-| Batch of similar tasks | Critical Review | Efficiency at scale |
-
-## 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!
-
----
+# 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.
+
+# DISCORD COMMUNITY
+
+Join our Discord community to collaborate, share ideas, and get help with archai:
+
+[JOIN DISCORD](https://discord.gg/2Y88888888)
+
+## 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
+
+- **10 Core Agents** - Pre-built orchestration agents for planning, implementation, and quality assurance
+- **Critical Review Mode** - Automated plan review via separate SDK session for blind spot detection
+- **Permission Presets** - Configurable permission settings (permissive/strict/custom) with safety guardrails
+- **Dynamic Specialists** - Claude Code generates project-specific specialists based on your tech stack
+- **Three-Phase Workflow** - Planning Loop → (Optional Critical Review) → Implementation Loop → Finalization
+- **Language Agnostic** - Works with any language, framework, or tech stack
+- **Task Management** - Built-in epic/task tracking system
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @zik000/archai
+
+# Initialize in your project
+cd your-project
+archai init
+
+# Fill in the generated files (or use wizards):
+archai setup-project     # Interactive project description wizard
+archai setup-config      # Interactive configuration wizard
+
+# Generate specialist agents
+archai generate
+
+# Start using with Claude Code
+claude
+
+# Manual mode (default) - user approves at both gates
+> "Use iteration-controller for: [your task]"
+
+# Critical review mode - auto-approve with SDK critical review
+> "Use iteration-controller with critical-review for: [your task]"
+```
+
+## Requirements
+
+- **Node.js 18+**
+- **Claude Code CLI** - Install from [claude.ai/code](https://claude.ai/code)
+- Claude Code must be authenticated
+
+## Commands
+
+### archai init
+
+Initialize archai in your project. Runs an interactive wizard to gather project information.
+
+```bash
+archai init                  # Interactive wizard
+archai init --skip-wizard    # Use detected defaults
+archai init --force          # Smart update with file comparison
+archai init --dry-run        # Preview what would be created
+archai init -y               # Non-interactive mode (CI-friendly)
+```
+
+**Smart Initialization Features:**
+- **Legacy Migration**: Automatically migrates pre-0.2.0 installations to version tracking
+- **File Comparison**: Compares existing files against templates
+- **Conflict Detection**: Identifies user modifications vs archai updates
+- **Interactive Resolution**: Prompts for action on conflicting files
+- **Automatic Backup**: Creates backup before `--force` operations
+
+Creates:
+- `.claude/agents/` - Agent definitions
+- `.claude/version.json` - Version and file hash tracking
+- `.claude/settings.local.json` - Permission settings (permissive mode by default)
+- `.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.
+
+```bash
+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 setup-project
+
+Interactive wizard to fill out your project description.
+
+```bash
+archai setup-project          # Interactive wizard
+archai setup-project --force  # Overwrite existing content
+```
+
+Guides you through:
+- Project overview and description
+- Architecture and key modules
+- Domain concepts and workflows
+- Technical constraints
+- Development guidelines
+- Current state and priorities
+
+### archai setup-config
+
+Interactive wizard to configure your project settings.
+
+```bash
+archai setup-config          # Interactive wizard
+archai setup-config --force  # Overwrite existing content
+```
+
+Configures:
+- Tech stack (languages, frameworks, testing)
+- Build commands (install, build, test, lint, dev)
+- Project structure
+- Specialist agents (with interactive loop to define multiple)
+- Permission presets (permissive/strict/custom) with `.claude/settings.local.json`
+- MCP/Skills placeholder section
+
+### archai doctor
+
+Validate your archai setup.
+
+```bash
+archai doctor
+```
+
+Checks:
+- Configuration file exists and is valid
+- Required directories exist
+- Core agents are installed
+- Claude Code CLI is available and shows version
+
+### archai update
+
+Update core agents and templates to the latest version with smart file comparison.
+
+```bash
+archai update              # Smart update with comparison
+archai update --all        # Force update all files
+archai update --dry-run    # Preview what would change
+archai update -y           # Non-interactive mode (CI-friendly)
+```
+
+**Smart Update Features:**
+- **Three-Way Comparison**: Detects if you, archai, or both modified files
+- **Auto-Merge**: Automatically merges settings.json (union arrays) and .gitignore (append)
+- **User Protection**: Skips files you modified (unless you choose otherwise)
+- **Specialist Protection**: Never overwrites generated specialist agents
+- **Automatic Backup**: Creates backup before any changes
+- **Deprecated Detection**: Identifies files no longer in archai templates
+
+**File Status Categories:**
+| Status | Description | Action |
+|--------|-------------|--------|
+| New | File doesn't exist locally | Auto-add |
+| Unchanged | Identical to template | Skip |
+| Updated by archai | New template version | Auto-update |
+| Modified by you | You changed it | Ask/skip |
+| Conflict | Both changed | Ask/merge |
+| Generated | Specialist file | Protected |
+
+### archai rollback
+
+Restore from a previous backup. Backups are automatically created before updates.
+
+```bash
+archai rollback              # Interactive backup selection
+archai rollback --list       # List all available backups
+archai rollback <timestamp>  # Restore specific backup
+archai rollback --dry-run    # Preview what would be restored
+archai rollback -y           # Skip confirmation
+```
+
+**Features:**
+- Lists backups with timestamps, reasons, and file counts
+- Full restore of all files from backup
+- Updates version.json after rollback
+
+### archai cleanup
+
+Clean up deprecated files and old backups.
+
+```bash
+archai cleanup               # Show cleanup status
+archai cleanup --deprecated  # Remove deprecated/orphaned files
+archai cleanup --backups     # Prune old backups (keeps 5)
+archai cleanup --all         # Clean everything
+archai cleanup --dry-run     # Preview what would be removed
+archai cleanup -y            # Skip confirmation
+```
+
+**Features:**
+- Identifies files tracked by archai but no longer in templates
+- Prunes old backups (configurable with `--keep-backups <count>`)
+- Safe: confirms before deleting
+
+### archai uninstall
+
+Remove archai artifacts from your project.
+
+```bash
+archai uninstall                 # Interactive removal
+archai uninstall --dry-run       # Preview what would be removed
+archai uninstall --keep-knowledge # Preserve .knowledge/ directory
+archai uninstall --force         # Skip confirmation
+```
+
+### Debug Mode
+
+Add `--debug` to any command for verbose logging:
+
+```bash
+archai init --debug
+archai doctor --debug
+```
+
+## 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 |
+| `critical-reviewer` | SDK-spawned blind spot detection | Fresh unbiased perspective |
+
+### 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. Approval Gates (Two Modes)
+
+Phase 1 outputs a **plan document** to `.claude/plans/{task}.md`. What happens next depends on the mode:
+
+**Manual Mode** (default):
+- Workflow **STOPS** and waits for user to: APPROVE / REVISE / REJECT
+- User reviews plan before any code is written
+- User reviews implementation before finalization
+
+**Critical Review Mode** (`with critical-review`):
+- Spawns a **separate SDK session** to critically review the plan
+- Fresh perspective catches blind spots the planning agent missed
+- Up to 2 review iterations with plan revisions
+- Auto-proceeds if review passes (no CRITICAL/HIGH issues)
+- Falls back to manual if unresolved issues after 2 iterations
+
+| Mode | Plan Gate | Final Gate | Best For |
+|------|-----------|------------|----------|
+| Manual | User approval | User approval | High-stakes changes, learning |
+| Critical Review | Auto (if passed) | Auto (if passed) | Routine tasks, trusted workflows |
+
+### 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
+
+## Permission Presets
+
+archai configures Claude Code permissions via `.claude/settings.local.json`. Three presets available:
+
+### Permissive (Default)
+
+Close to `--dangerously-skip-permissions` but with safety guardrails. Allows most operations while blocking irreversible actions:
+
+**Always Denied** (even in permissive mode):
+- Destructive file ops: `rm -rf *`, `rmdir /s`
+- Force git: `git push --force`, `git reset --hard`
+- System damage: `sudo *`, `chmod 777`, `mkfs*`
+- Credentials: `cat ~/.ssh/*`, `echo $*SECRET*`
+- Remote code exec: `curl * | bash`, `wget * | sh`
+- Database destruction: `DROP DATABASE`, `TRUNCATE TABLE`
+
+### Strict
+
+Production-safe preset. Only allows read-only operations and controlled writes:
+
+**Allowed**:
+- Package management: `npm install`, `pip install`, etc.
+- Build/test: `tsc`, `eslint`, `jest`, `pytest`
+- Read operations: `cat`, `grep`, `ls`, `git status`, `git diff`
+- Safe git: `git add`, `git commit`, `git checkout -b`
+
+**Denied** (in addition to Always Denied):
+- Network: `curl`, `wget`, `ssh`, `scp`
+- Publish: `npm publish`, `pip upload`
+- Push: `git push` (any form)
+- Process control: `kill`, `pkill`
+
+### Custom
+
+Define your own allow/deny lists via the wizard. Useful for specific project requirements.
+
+### Command Chaining
+
+Permissions validate **each segment** of chained commands:
+```bash
+npm install && npm test    # Both validated separately
+git add . && git push      # Would fail in strict mode (push denied)
+```
+
+## Version Tracking
+
+archai tracks file states in `.claude/version.json` to enable smart updates:
+
+```json
+{
+  "schemaVersion": 1,
+  "archai": "0.2.0",
+  "installedAt": "2026-02-01T10:00:00Z",
+  "lastUpdated": "2026-02-05T14:30:00Z",
+  "files": {
+    ".claude/agents/deep-analyst.md": {
+      "baseHash": "abc123def456",
+      "isGenerated": false
+    },
+    ".claude/agents/frontend-specialist.md": {
+      "baseHash": null,
+      "isGenerated": true
+    }
+  },
+  "expectedFiles": [".claude/agents/deep-analyst.md", "..."]
+}
+```
+
+**How It Works:**
+1. **baseHash**: SHA256 hash when archai installed the file
+2. **currentHash**: Hash of file on disk now
+3. **templateHash**: Hash of new archai template
+
+**Three-Way Comparison:**
+- `current == template` → Unchanged
+- `current != base`, `template == base` → You modified it
+- `current == base`, `template != base` → Archai updated it
+- `current != base`, `template != base` → Conflict (both changed)
+
+**Migration from Pre-0.2.0:**
+When you run `init` or `update` on an old installation, archai automatically:
+1. Creates version.json
+2. Compares existing files to current templates
+3. Marks matching files as unmodified
+4. Marks differing files as user-modified (conservative approach)
+5. Marks `*-specialist.md` files as generated
+
+## Directory Structure
+
+After initialization:
+
+```
+your-project/
+├── .claude/
+│   ├── agents/             # Agent definitions
+│   │   ├── *.md            # Core agents (archai-managed)
+│   │   └── *-specialist.md # Generated specialists (protected)
+│   ├── backups/            # Automatic backups (gitignored)
+│   │   └── {timestamp}/    # Timestamped backup with manifest.json
+│   ├── plans/              # Approved plans (per task)
+│   │   └── archived/       # Completed task plans
+│   ├── state/              # Working state (gitignored)
+│   └── version.json        # Version and file hash tracking
+├── .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` |
+
+### When to Use Critical Review Mode
+
+| Situation | Mode | Why |
+|-----------|------|-----|
+| Learning the workflow | Manual | See how planning works |
+| High-stakes feature | Manual | Want full control |
+| Security-sensitive code | Manual | Extra human review |
+| Routine refactoring | Critical Review | Trust the review process |
+| Well-understood feature | Critical Review | Faster iteration |
+| Batch of similar tasks | Critical Review | Efficiency at scale |
+
+## 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.