@zik000/archai 0.2.0 → 0.2.2

package/README.md

@@ -1,627 +1,221 @@
 # archai
 
-**Multi-agent AI development workflow for any project.**
+**A team of AI agents for Claude Code — not just one assistant, but a full development workflow.**
 
-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.
+Archai scaffolds a multi-agent system that plans before it codes, validates before it implements, and tests before it ships. One command sets it up. Claude Code does the rest.
 
-# DISCORD COMMUNITY
+![Three-Phase Architecture](diagram.jpg)
 
-Join our Discord community to collaborate, share ideas, and get help with archai:
+[Join our Discord](https://discord.gg/J3wgDb4YJv)
 
-[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.
+## Why archai?
 
-## The Three-Phase Architecture
+Without structure, AI assistants jump straight to code — skipping analysis, missing edge cases, and producing work that needs reworking. archai fixes this with a **three-phase workflow**:
 
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         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   │
-                            └──────────────┘
-```
+1. **Planning Loop** — Analyze the problem, validate the plan, design tests (2-4 iterations)
+2. **Implementation Loop** — Code, test, review (only after you approve the plan)
+3. **Finalization** — Quality checks, cleanup, commit, push, CI verification
 
-## Features
+Agents **learn across sessions** through a persistent knowledge base — decisions, constraints, patterns, and gotchas are recorded and searched before every new task.
 
-- **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
+You stay in control with approval gates between phases. Or use **critical review mode** to let a separate AI session review the plan automatically.
 
 ## 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.
+That's it. archai detects your tech stack and creates everything you need. Now open Claude Code:
 
 ```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)
+claude
 ```
 
-**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
+And tell it what to build:
 
-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
+> Use iteration-controller for: add user authentication with JWT
 ```
 
-Guides you through:
-- Project overview and description
-- Architecture and key modules
-- Domain concepts and workflows
-- Technical constraints
-- Development guidelines
-- Current state and priorities
+The agent system takes over — plans the work, waits for your approval, implements it, runs tests, and commits.
 
-### archai setup-config
+### For small fixes
 
-Interactive wizard to configure your project settings.
+Skip the full workflow:
 
-```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
+> Use quick-fix for: rename the userId variable to accountId
 ```
 
-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.
+### Optional setup wizards
 
 ```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)
+archai setup-project     # Describe your project architecture
+archai setup-config      # Configure commands, specialists, permissions
+archai generate          # Generate project-specific specialist agents
 ```
 
-**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 |
+## How to Use
 
-### archai rollback
+### Step 1: Define Your Task
 
-Restore from a previous backup. Backups are automatically created before updates.
+Write a clear description of what you want done. Drop it into a task file:
 
-```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
+.tasks/inbox/add-user-auth.md
 ```
 
-**Features:**
-- Identifies files tracked by archai but no longer in templates
-- Prunes old backups (configurable with `--keep-backups <count>`)
-- Safe: confirms before deleting
+Or just describe it directly in Claude Code. The more specific you are, the better the agents perform.
 
-### archai uninstall
+### Step 2: Feed It to the Agent System
 
-Remove archai artifacts from your project.
+Open Claude Code and hand the task to `iteration-controller`:
 
-```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
+> Use iteration-controller for: add user authentication with JWT
 ```
 
-## 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 |
+That's it. The agent system takes over:
 
-### Orchestrator
+1. **Planning** — `deep-analyst` studies your codebase, `plan-validator` challenges the plan, `tdd-designer` writes tests first. This iterates 2-4 times until the plan is solid.
+2. **Your approval** — The workflow stops and presents the plan. You APPROVE, REVISE, or REJECT.
+3. **Implementation** — `implementation-agent` builds it, `code-reviewer` verifies it. Iterates until tests pass.
+4. **Finalization** — `finalization-agent` runs quality checks, cleans up, commits, and pushes.
 
-| 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
+### Critical Review Mode
 
-Define your own allow/deny lists via the wizard. Useful for specific project requirements.
+For routine tasks where you trust the process, skip manual plan approval:
 
-### 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", "..."]
-}
+> Use iteration-controller with critical-review for: [your task]
 ```
 
-**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)
+A separate Claude session reviews the plan for blind spots. If it passes, implementation starts automatically. If issues are found, it falls back to asking you.
 
-**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
+| Mode | When to use | Plan approval |
+|------|-------------|---------------|
+| Manual (default) | Learning, high-stakes, security-sensitive | You approve |
+| Critical review | Routine tasks, well-understood features | Auto if review passes |
 
-## Directory Structure
+### Quick Fix
 
-After initialization:
+For small, obvious changes (typos, renames, config tweaks, 1-3 files):
 
 ```
-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
+> Use quick-fix for: [small change]
 ```
 
-## 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` |
+No planning docs, no approval gates. If the change turns out to be bigger than expected, it tells you to use `iteration-controller` instead.
 
-### When to Use Critical Review Mode
+### Batch Tasks
 
-| 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 |
+For managing multiple tasks across an epic, drop them all into `.tasks/inbox/` and run:
 
-## Why This Architecture?
-
-### Problem: Incomplete Plans
-
-"Handle edge cases" leads to implementation guessing.
+```
+> Use task-orchestrator for: work through the tasks in .tasks/inbox/
+```
 
-**Solution**: `plan-validator` rejects vague plans, forces specificity.
+It claims tasks one by one, creates branches, spawns the full workflow for each, and tracks progress.
 
-### Problem: Code First, Think Later
+### Standalone Agents
 
-Jumping to code before understanding leads to rewrites.
+You can use any agent directly:
 
-**Solution**: Three-phase architecture enforces 2-4 thinking iterations BEFORE any code.
+| Agent | Use for |
+|-------|---------|
+| `deep-analyst` | Understanding code, analyzing a problem |
+| `tdd-designer` | Designing test suites |
+| `cleanup-agent` | Cleaning temp files before committing |
+
+## Agents (11 Core)
+
+| Agent | Phase | Role |
+|-------|-------|------|
+| `iteration-controller` | Orchestrator | Manages all three phases with iteration limits |
+| `deep-analyst` | Planning | Deep analysis and implementation planning |
+| `plan-validator` | Planning | Adversarial plan review — finds gaps |
+| `tdd-designer` | Planning | Designs tests before code, with concrete values |
+| `critical-reviewer` | Planning | Blind review via separate SDK session |
+| `implementation-agent` | Implementation | Autonomous execution of approved plan |
+| `code-reviewer` | Implementation | Verifies against acceptance criteria |
+| `cleanup-agent` | Finalization | Removes temp files, archives state |
+| `finalization-agent` | Finalization | Quality checks, commit, push, CI/CD |
+| `task-orchestrator` | Workflow | Epic/task lifecycle management |
+| `quick-fix` | Standalone | Fast single-pass for small changes |
+
+**Specialist agents** are generated from your config with `archai generate` — they understand your specific tech stack, file paths, and conventions.
 
-### Problem: Tests Written To Pass
+## Commands
 
-Tests written after code tend to validate the implementation, not the requirement.
+| Command | Purpose |
+|---------|---------|
+| `archai init` | Initialize archai in your project (smart — handles existing setups) |
+| `archai update` | Update agents/templates with smart file comparison |
+| `archai generate` | Generate specialist agents from your config |
+| `archai setup-project` | Interactive wizard for project description |
+| `archai setup-config` | Interactive wizard for config, commands, permissions |
+| `archai doctor` | Validate your setup |
+| `archai rollback` | Restore from automatic backup |
+| `archai cleanup` | Remove deprecated files and old backups |
+| `archai uninstall` | Remove archai from your project |
 
-**Solution**: Tests designed BEFORE implementation, based on user stories, not code.
+All commands support `--dry-run` to preview changes and `-y` for non-interactive CI mode.
 
-### Problem: Agents Cut Corners
+### Key flags
 
-Without enforcement, agents skip steps and produce low-quality work.
+```bash
+archai init --skip-wizard    # Use detected defaults
+archai init --force          # Re-initialize with file comparison
+archai update --all          # Force update all files
+archai rollback --list       # Show available backups
+archai cleanup --all         # Remove deprecated files + prune backups
+```
 
-**Solution**: Explicit phase gates, required artifacts, adversarial validation.
+## Permission Presets
 
-## Common Mistakes to Avoid
+archai configures Claude Code permissions via `.claude/settings.local.json`:
 
-### Mistake 1: Skipping to implementation
-```
-# BAD
-"Just implement the auth feature"
+| Preset | Description |
+|--------|-------------|
+| **Permissive** (default) | Allows most operations. Blocks destructive actions: `rm -rf`, `git push --force`, `sudo`, credential access, database drops. |
+| **Strict** | Read-only + controlled writes. No network, no push, no publish. Good for production environments. |
+| **Custom** | Define your own allow/deny lists via the wizard. |
 
-# GOOD
-"Use iteration-controller to implement the auth feature.
-Run Phase 1 first and wait for my APPROVE."
-```
+## Project Structure
 
-### 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'"
+your-project/
+├── .claude/
+│   ├── agents/          # Core + specialist agent definitions
+│   ├── plans/           # Approved implementation plans
+│   ├── state/           # Working state (gitignored)
+│   └── version.json     # Version tracking for smart updates
+├── .knowledge/          # Persistent knowledge base (decisions, constraints, patterns, learnings)
+├── .tasks/              # Task inbox, epics, review, done
+├── archai.config.md     # Project configuration
+├── CLAUDE.md            # Agentic behavior guidelines (auto-generated)
+└── PROMPTS.md           # Quick reference for all prompts
 ```
 
-### Mistake 3: Interrupting Phase 2
-```
-# BAD
-[Agent implementing step 2]
-You: "How's it going? Should I help?"
+## Requirements
 
-# GOOD
-[Let it run until DONE or BLOCKED]
-[Only interrupt if truly necessary]
-```
+- **Node.js 18+**
+- **Claude Code CLI** — [claude.ai/code](https://claude.ai/code)
 
 ## 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
+**Agent not following instructions?** Make sure agent file content is being passed and output locations are specified.
 
-### 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")
+**Planning keeps iterating?** After 4 iterations, it stops automatically. If requirements are unclear, it escalates to you.
 
-### 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 failing?** After 5 fix attempts on the same step, it reports BLOCKED and stops. Check if the plan was specific enough.
 
-### 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
+**Tests too shallow?** Verify `tdd-designer` used concrete values and covered edge cases, not just happy paths.
 
 ## License
 
@@ -629,8 +223,4 @@ MIT
 
 ## Contributing
 
-Contributions welcome!
-
----
-
-Built with Claude Code.
+Contributions welcome! Join the [Discord](https://discord.gg/J3wgDb4YJv) to discuss ideas.