@zik000/archai 0.1.4 → 0.2.1

package/README.md

@@ -1,486 +1,217 @@
-# 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
+
+**A team of AI agents for Claude Code — not just one assistant, but a full development 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.
+
+```
+Plan → Implement → Finalize
+```
+
+[Join our Discord](https://discord.gg/J3wgDb4YJv)
+
+---
+
+## Why archai?
+
+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**:
+
+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
+
+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
+npm install -g @zik000/archai
+cd your-project
+archai init
+```
+
+That's it. archai detects your tech stack and creates everything you need. Now open Claude Code:
+
+```bash
+claude
+```
+
+And tell it what to build:
+
+```
+> Use iteration-controller for: add user authentication with JWT
+```
+
+The agent system takes over — plans the work, waits for your approval, implements it, runs tests, and commits.
+
+### For small fixes
+
+Skip the full workflow:
+
+```
+> Use quick-fix for: rename the userId variable to accountId
+```
+
+### Optional setup wizards
+
+```bash
+archai setup-project     # Describe your project architecture
+archai setup-config      # Configure commands, specialists, permissions
+archai generate          # Generate project-specific specialist agents
+```
+
+## How to Use
+
+### The Main Workflow
+
+For any non-trivial task, use `iteration-controller`. It orchestrates the entire three-phase workflow:
+
+```
+> Use iteration-controller for: [describe your task]
+```
+
+**What happens:**
+1. `deep-analyst` analyzes your codebase and creates an implementation plan
+2. `plan-validator` challenges the plan and finds gaps
+3. `tdd-designer` designs tests before any code is written
+4. **You review and approve the plan** (or request revisions)
+5. `implementation-agent` builds it, `code-reviewer` verifies it
+6. `finalization-agent` runs quality checks, commits, and pushes
+
+### Critical Review Mode
+
+For routine tasks where you trust the process, skip manual plan approval:
+
+```
+> Use iteration-controller with critical-review for: [your task]
+```
+
+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.
+
+| 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 |
+
+### Quick Fix
+
+For small, obvious changes (typos, renames, config tweaks, 1-3 files):
+
+```
+> Use quick-fix for: [small change]
+```
+
+No planning docs, no approval gates. If the change turns out to be bigger than expected, it tells you to use `iteration-controller` instead.
+
+### Task Management
+
+For managing multiple tasks across an epic:
+
+```
+> Use task-orchestrator for: work through the tasks in .tasks/inbox/
+```
+
+It claims tasks, creates branches, spawns the workflow, and tracks progress.
+
+### Standalone Agents
+
+You can use any agent directly:
+
+| 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.
+
+## Commands
+
+| 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 |
+
+All commands support `--dry-run` to preview changes and `-y` for non-interactive CI mode.
+
+### Key flags
+
+```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
+```
+
+## Permission Presets
+
+archai configures Claude Code permissions via `.claude/settings.local.json`:
+
+| 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. |
+
+## Project Structure
+
+```
+your-project/
+├── .claude/
+│   ├── agents/          # Core + specialist agent definitions
+│   ├── plans/           # Approved implementation plans
+│   ├── state/           # Working state (gitignored)
+│   └── version.json     # Version tracking for smart updates
+├── .knowledge/          # Project context, decisions, 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
+```
+
+## Requirements
+
+- **Node.js 18+**
+- **Claude Code CLI** — [claude.ai/code](https://claude.ai/code)
+
+## Troubleshooting
+
+**Agent not following instructions?** Make sure agent file content is being passed and output locations are specified.
+
+**Planning keeps iterating?** After 4 iterations, it stops automatically. If requirements are unclear, it escalates to you.
+
+**Implementation failing?** After 5 fix attempts on the same step, it reports BLOCKED and stops. Check if the plan was specific enough.
+
+**Tests too shallow?** Verify `tdd-designer` used concrete values and covered edge cases, not just happy paths.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Join the [Discord](https://discord.gg/J3wgDb4YJv) to discuss ideas.