@zik000/archai 0.1.0

package/templates/ARCHAI_README.md

@@ -0,0 +1,326 @@
+# archai Agent System
+
+This project uses **archai** - a multi-agent AI development workflow powered by Claude Code.
+
+## Quick Start
+
+```bash
+# Open Claude Code in this project
+claude
+
+# Start with the full workflow
+> "Use iteration-controller for: [your task description]"
+```
+
+## How It Works
+
+### The Three-Phase Workflow
+
+```
+Phase 1: PLANNING (requires your approval)
+   │
+   ├── deep-analyst      → Analyzes the task deeply
+   ├── plan-validator    → Challenges the plan, finds gaps
+   └── tdd-designer      → Designs tests BEFORE code
+   │
+   ▼
+🛑 STOP: Review plan → Say "APPROVE" or "REVISE: [feedback]"
+   │
+   ▼
+Phase 2: IMPLEMENTATION (autonomous after approval)
+   │
+   ├── implementation-agent → Writes code following the plan
+   └── code-reviewer        → Verifies the implementation
+   │
+   ▼
+🛑 STOP: Review implementation → Say "APPROVE" to finalize
+   │
+   ▼
+Phase 3: FINALIZATION
+   │
+   ├── cleanup-agent       → Cleans temporary files
+   └── finalization-agent  → Commits, pushes, verifies CI
+```
+
+### Key Principle: Think Before Coding
+
+**No code is written until you approve the plan.** This prevents:
+- Implementing the wrong thing
+- Missing edge cases
+- Rewriting code due to poor planning
+
+## Launching Tasks
+
+### For New Features (Full Workflow)
+
+```
+Use iteration-controller for: Add user authentication with JWT
+
+Run Phase 1 with at least 2 iterations.
+Write plan to .claude/plans/jwt-auth.md.
+STOP and wait for my APPROVE before implementing.
+```
+
+### For Quick Fixes (Skip Planning)
+
+```
+Use implementation-agent for: Fix the typo in Header.tsx
+```
+
+### For Analysis Only
+
+```
+Use deep-analyst for: Analyze how the caching layer works
+```
+
+## Prompting Guide
+
+### Starting a Task
+
+| What you want | Prompt |
+|---------------|--------|
+| New feature | `Use iteration-controller for: [feature]` |
+| Bug fix (complex) | `Use iteration-controller for: [bug description]` |
+| Bug fix (simple) | `Use implementation-agent for: [fix]` |
+| Code analysis | `Use deep-analyst for: [what to analyze]` |
+| Test design | `Use tdd-designer for: [feature to test]` |
+| Code review | `Use code-reviewer for: [what to review]` |
+
+### Controlling the Workflow
+
+| Action | Say |
+|--------|-----|
+| Approve plan/implementation | `APPROVE` |
+| Request changes | `REVISE: [specific feedback]` |
+| Stop completely | `REJECT: [reason]` |
+
+### Tips for Good Prompts
+
+**Be specific:**
+```
+# BAD
+"Add authentication"
+
+# GOOD
+"Add JWT authentication with:
+- Login endpoint returning access + refresh tokens
+- Token refresh endpoint
+- Middleware for protected routes
+- 15 minute access token expiry"
+```
+
+**Include constraints:**
+```
+"Use iteration-controller for: Add rate limiting
+
+Constraints:
+- 100 requests per minute per IP
+- Use Redis for distributed counting
+- Return 429 with Retry-After header"
+```
+
+## Using Tasks & Epics
+
+### Task Directory Structure
+
+```
+.tasks/
+├── inbox/          # New tasks waiting to be picked up
+├── epics/          # Active work in progress
+├── review/         # Completed, awaiting review/merge
+└── done/           # Completed and merged
+```
+
+### Creating a Task
+
+1. Create a folder in `.tasks/inbox/`:
+```
+.tasks/inbox/TASK-001/epic.md
+```
+
+2. Use the epic template:
+```markdown
+---
+id: TASK-001
+title: "Add user authentication"
+type: epic
+priority: high
+status: inbox
+created: 2024-01-15
+---
+
+## Description
+Add JWT-based authentication to the API.
+
+## Acceptance Criteria
+- [ ] Users can register with email/password
+- [ ] Users can login and receive tokens
+- [ ] Protected routes require valid token
+- [ ] Tokens expire and can be refreshed
+```
+
+### Working with Tasks
+
+```
+# Pick up next task from inbox
+Use task-orchestrator for: Pick up the next task from inbox
+
+# Create a new epic
+Use task-orchestrator for: Create an epic for user authentication
+```
+
+### Task Lifecycle
+
+```
+inbox/ → epics/ → review/ → done/
+  │         │         │
+  │         │         └── Merged to main
+  │         └── Implementation complete, PR created
+  └── Claimed and work started
+```
+
+## Core Principles
+
+### 1. Plan First, Code Second
+
+Every feature goes through planning:
+- What exactly needs to be built?
+- What are the edge cases?
+- How will we test it?
+- What could go wrong?
+
+### 2. Tests Define Done
+
+Tests are designed BEFORE implementation:
+- Use concrete values, not "valid input"
+- Tests should FAIL if code is broken
+- Cover edge cases and error states
+
+### 3. Human Approval Gates
+
+You control when to proceed:
+- Review plans before implementation starts
+- Review implementation before it's committed
+- Nothing happens without your explicit `APPROVE`
+
+### 4. Adversarial Validation
+
+The `plan-validator` agent exists to find problems:
+- Challenges assumptions
+- Finds missing edge cases
+- Rejects vague plans
+- Expects 2-4 planning iterations
+
+### 5. Autonomous Execution
+
+Once approved, implementation runs without interruption:
+- Implements step by step
+- Runs tests after each change
+- Fixes failures automatically
+- Only stops when done or truly blocked
+
+## Directory Structure
+
+```
+your-project/
+├── .claude/
+│   ├── agents/          # Agent instruction files
+│   ├── plans/           # Approved implementation plans
+│   │   └── archived/    # Completed plans
+│   └── state/           # Working state (auto-cleaned)
+├── .knowledge/
+│   ├── context/         # Project description (READ THIS)
+│   ├── decisions/       # Architecture decision records
+│   └── learnings/       # Patterns learned during development
+├── .tasks/
+│   ├── inbox/           # New tasks
+│   ├── epics/           # Active work
+│   ├── review/          # Awaiting merge
+│   └── done/            # Completed
+├── PROMPTS.md           # Full prompt reference
+└── archai.config.md     # Configuration
+```
+
+## Common Workflows
+
+### Starting Your Day
+
+```
+# Check for pending tasks
+ls .tasks/inbox/
+
+# Or pick up the next one
+Use task-orchestrator for: Pick up the next task from inbox
+```
+
+### Feature Development
+
+```
+# 1. Start with full workflow
+Use iteration-controller for: [feature description]
+
+# 2. Review the plan when presented
+# Read .claude/plans/[feature].md
+
+# 3. Approve or revise
+APPROVE
+# or
+REVISE: Add error handling for network failures
+
+# 4. Let implementation run
+
+# 5. Approve final implementation
+APPROVE
+```
+
+### Quick Bug Fix
+
+```
+Use implementation-agent for: Fix null pointer in getUserById when user not found
+
+The function should return null instead of throwing.
+```
+
+### Code Investigation
+
+```
+Use deep-analyst for: Trace how authentication tokens flow through the system
+
+I need to understand:
+1. Where tokens are created
+2. How they're validated
+3. Where they're stored
+```
+
+## Troubleshooting
+
+### "Agent isn't following the plan"
+
+Make sure the plan was specific enough. Vague plans lead to interpretation.
+
+### "Tests are too shallow"
+
+Ask `tdd-designer` to include:
+- Edge cases with specific values
+- Error conditions
+- Boundary values
+
+### "Phase 1 keeps iterating"
+
+After 4 iterations, the requirements might be unclear. Provide more context or simplify the task.
+
+### "Implementation keeps failing"
+
+1. Check if the plan covered the failing scenario
+2. Let it retry (up to 5 attempts)
+3. If still failing, it will escalate to you
+
+## Need Help?
+
+- **PROMPTS.md** - Full prompt reference with examples
+- **.knowledge/context/project-description.md** - Project context (fill this in!)
+- **archai.config.md** - Configuration options
+
+---
+
+*Powered by archai - Multi-agent AI development workflow*