@zik000/archai 0.2.1 → 0.2.3

package/templates/PROMPTS.md

@@ -1,480 +1,506 @@
-# archai Prompt Templates
-
-Complete reference for using the agent system. Copy and customize these prompts.
-
----
-
-## Full Orchestration Prompt (Recommended)
-
-Copy this to start the full three-phase workflow:
-
-```
-Follow the orchestration guide in .claude/agents/iteration-controller.md to create an
-implementation plan for: {YOUR TASK DESCRIPTION}
-
-PHASE 1 INSTRUCTIONS (Planning - requires approval):
-1. Read each agent's full instruction file from .claude/agents/ BEFORE spawning
-2. Pass the COMPLETE instructions to each subagent in the Task prompt
-3. Save ALL agent outputs to .claude/state/ directory
-4. Run at least 2 planning iterations (THINK → VALIDATE → TEST DESIGN → VALIDATE TESTS → RETHINK)
-5. After planning complete, write final plan to .claude/plans/{task-name}.md
-6. STOP and present the plan summary - do NOT implement until I say "APPROVE"
-
-PHASE 2 INSTRUCTIONS (Implementation - AUTONOMOUS after approval):
-When I say "APPROVE", execute Phase 2 AUTONOMOUSLY:
-- Implement ALL steps without stopping to ask
-- Run tests after each step
-- Fix failures automatically (up to 5 attempts per step)
-- Only report back when ALL DONE or truly BLOCKED
-- DO NOT ask "should I proceed?" - just execute the full loop
-- When Phase 2 complete, present summary and wait for FINAL APPROVAL
-
-PHASE 3 INSTRUCTIONS (Finalization - after implementation approved):
-When I say "APPROVE" on implementation:
-- Read .claude/agents/finalization-agent.md
-- Spawn finalization-agent to verify, cleanup, commit, push, wait for CI/CD
-- Report final status
-
-Start with Phase 1, Iteration 1: Read .claude/agents/deep-analyst.md and
-spawn a deep-analyst subagent to analyze the task.
-```
-
----
-
-## Phase 2 Only Prompt (After Plan is Approved)
-
-Use this when resuming after approval:
-
-```
-The plan in .claude/plans/{task-name}.md has been APPROVED.
-
-Execute Phase 2 AUTONOMOUSLY:
-1. Read .claude/agents/implementation-agent.md
-2. Spawn implementation-agent with FULL instructions
-3. The agent must execute ALL steps WITHOUT stopping to ask
-4. Loop: implement → test → fix failures → next step → repeat
-5. Only report back when COMPLETELY DONE or truly BLOCKED
-6. When done, present summary and wait for FINAL APPROVAL
-
-DO NOT ask for permission between steps. Just execute until done.
-```
-
----
-
-## Phase 3 Only Prompt (After Implementation is Approved)
-
-Use this when implementation is done and you've approved it:
-
-```
-The implementation is complete and APPROVED.
-
-Execute Phase 3 (Finalization):
-1. Read .claude/agents/finalization-agent.md
-2. Spawn finalization-agent with FULL instructions
-3. The agent will:
-   - Verify all acceptance criteria against original task
-   - Run local quality checks (typecheck, lint)
-   - Clean up temp files
-   - Commit with proper message
-   - Push to remote (triggers CI/CD)
-   - Wait for CI/CD to pass
-4. Report final status when complete
-
-Branch: {branch-name}
-Task file: {.tasks/epics/TASK-XXX/epic.md or original task}
-```
-
----
-
-## Planning Phase Only
-
-### Deep Analysis
-
-```
-Read .claude/agents/deep-analyst.md and spawn a deep-analyst to analyze:
-{WHAT TO ANALYZE}
-
-Focus on:
-- What is the REAL problem we're solving?
-- What are the dependencies?
-- What could go wrong?
-
-DO NOT create an implementation plan yet - just analysis.
-Output to .claude/state/analysis-{topic}.md
-```
-
-**Examples:**
-```
-Read .claude/agents/deep-analyst.md and spawn a deep-analyst to analyze
-our current authentication flow.
-
-Trace:
-1. How users log in
-2. How tokens are validated
-3. How sessions are managed
-
-DO NOT create an implementation plan yet - just analysis.
-Output to .claude/state/auth-flow-analysis.md
-```
-
-### Plan Validation
-
-```
-Read .claude/agents/plan-validator.md and spawn a plan-validator to
-challenge the plan in .claude/state/{plan-file}.md
-
-Your job is to FIND PROBLEMS, not approve the plan.
-Look for:
-- Vague steps ("handle edge cases")
-- Missing error handling
-- Untested assumptions
-- Performance concerns
-
-Output critique to .claude/state/plan-validation.md
-```
-
-### Test Design (TDD)
-
-```
-Read .claude/agents/tdd-designer.md and spawn a tdd-designer to create
-test designs for: {FEATURE DESCRIPTION}
-
-Focus on:
-- Real user workflows, not implementation details
-- Concrete values (not "test with valid input")
-- Tests that would FAIL if code is broken
-- Edge cases and boundary conditions
-
-Output to .claude/state/test-design-{feature}.md
-```
-
-**Examples:**
-```
-Read .claude/agents/tdd-designer.md and spawn a tdd-designer to create
-test designs for the user registration flow.
-
-Focus on:
-- Valid registration with all fields
-- Missing required fields (each field separately)
-- Invalid email formats
-- Password strength requirements
-- Duplicate email handling
-
-Use concrete values like:
-- email: "test@example.com"
-- password: "SecureP@ss123"
-
-Output to .claude/state/test-design-registration.md
-```
-
----
-
-## Implementation Phase Only
-
-### Direct Implementation (Skip Planning)
-
-Use only for simple, well-defined tasks:
-
-```
-Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
-{SPECIFIC TASK}
-
-Execute WITHOUT stopping to ask. Just implement and test.
-Report back when DONE or truly BLOCKED.
-```
-
-**Examples:**
-```
-Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
-Fix the typo in src/components/Header.tsx - change "Welcom" to "Welcome"
-
-Execute WITHOUT stopping to ask. Report back when done.
-```
-
-```
-Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
-Add a loading spinner to the submit button in LoginForm.tsx
-
-Requirements:
-- Show spinner when form is submitting
-- Disable button during submission
-- Hide spinner when complete
-
-Execute WITHOUT stopping to ask. Run tests after changes.
-```
-
-### Code Review
-
-```
-Read .claude/agents/code-reviewer.md and spawn a code-reviewer to
-review the changes in: {LOCATION}
-
-Focus on:
-- Does it match the approved plan?
-- Are there bugs or edge cases missed?
-- Is error handling complete?
-- Are tests adequate?
-
-Output review to .claude/state/code-review-{feature}.md
-```
-
-**Examples:**
-```
-Read .claude/agents/code-reviewer.md and spawn a code-reviewer to
-review the changes in src/api/auth/
-
-Focus on:
-- Security vulnerabilities
-- Error handling completeness
-- Test coverage
-- API contract compliance
-
-Output review to .claude/state/code-review-auth-api.md
-```
-
----
-
-## Finalization Phase
-
-### Cleanup Before Commit
-
-```
-Read .claude/agents/cleanup-agent.md and spawn a cleanup-agent for task: {TASK}
-
-Clean up:
-- .claude/state/ (except archived)
-- .agents/scratch/
-- .agents/thoughts/
-- Any temporary files
-
-Preserve:
-- .knowledge/ (all of it)
-- .claude/plans/ (approved plans)
-- Actual source code changes
-```
-
-### Full Finalization
-
-```
-Read .claude/agents/finalization-agent.md and spawn a finalization-agent.
-
-Task: {TASK DESCRIPTION}
-Branch: {BRANCH NAME}
-
-The agent will:
-1. Verify all acceptance criteria
-2. Run quality checks (typecheck, lint)
-3. Clean temporary files
-4. Commit with proper message
-5. Push to remote
-6. Wait for CI/CD
-7. Report final status
-```
-
----
-
-## Task Management
-
-### Pick Up Next Task
-
-```
-Read .claude/agents/task-orchestrator.md and spawn a task-orchestrator to:
-Pick up the next task from .tasks/inbox/
-
-The agent will:
-1. Scan inbox for available tasks
-2. Select highest priority task
-3. Move to .tasks/epics/
-4. Create branch
-5. Begin Phase 1 planning
-```
-
-### Create New Epic
-
-```
-Read .claude/agents/task-orchestrator.md and spawn a task-orchestrator to:
-Create an epic for: {FEATURE DESCRIPTION}
-
-Include:
-- Clear acceptance criteria
-- Priority level
-- Estimated complexity
-- Dependencies (if any)
-
-Save to .tasks/inbox/TASK-{XXX}/epic.md
-```
-
----
-
-## Specialist Agents
-
-After running `archai generate`, use your project-specific specialists:
-
-### Template: Invoke Any Specialist
-
-```
-Read .claude/agents/{specialist-name}.md and spawn a {specialist-name} to:
-{SPECIFIC TASK}
-
-Context:
-- {relevant context}
-
-Output to .claude/state/{output-file}.md
-```
-
-### Common Specialist Prompts
-
-```
-# Frontend work
-Read .claude/agents/frontend-specialist.md and spawn a frontend-specialist to:
-Create a reusable modal component with:
-- Backdrop click to close
-- ESC key to close
-- Focus trap
-- Smooth animations
-
-Output to .claude/state/modal-component-design.md
-```
-
-```
-# Backend work
-Read .claude/agents/backend-specialist.md and spawn a backend-specialist to:
-Add rate limiting to the API endpoints in src/api/
-
-Requirements:
-- 100 requests per minute per IP
-- Return 429 with Retry-After header
-- Whitelist internal services
-
-Output to .claude/state/rate-limiting-design.md
-```
-
-```
-# Database work
-Read .claude/agents/database-specialist.md and spawn a database-specialist to:
-Optimize the slow query in getUserOrders()
-
-Current query takes 2+ seconds with 10k orders.
-Target: under 100ms
-
-Output to .claude/state/query-optimization.md
-```
-
----
-
-## Quick Reference Card
-
-| I want to... | Use this prompt... |
-|--------------|-------------------|
-| Implement a feature | `Use iteration-controller for: X. Run Phase 1, wait for APPROVE.` |
-| Analyze code first | `Read deep-analyst.md, spawn deep-analyst to analyze: X` |
-| Design tests only | `Read tdd-designer.md, spawn tdd-designer to design tests for: X` |
-| Get specialist help | `Read {name}-specialist.md, spawn {name}-specialist for: X` |
-| Resume implementation | `The plan in .claude/plans/X.md has been APPROVED. Execute Phase 2 AUTONOMOUSLY.` |
-| Finalize (commit/push) | `Implementation APPROVED. Execute Phase 3 with finalization-agent.` |
-| Clean up before commit | `Read cleanup-agent.md, spawn cleanup-agent for task: X` |
-| Approve a plan | `APPROVE` |
-| Approve implementation | `APPROVE` (triggers Phase 3 finalization) |
-| Request changes | `REVISE: [specific changes]` |
-| Stop workflow | `REJECT: [reason]` |
-
----
-
-## Step-by-Step Examples
-
-### Example 1: Implement a New Feature
-
-**Task:** "Add user authentication with JWT"
-
-**Step 1: Start the orchestrated workflow**
-```
-Use iteration-controller to implement: Add user authentication with JWT
-that supports login, logout, and token refresh.
-
-Run Phase 1 with at least 2 iterations.
-Write plan to .claude/plans/jwt-auth.md.
-STOP and wait for my APPROVE before implementing.
-```
-
-**Step 2: Wait for Phase 1 to complete**
-
-The agent will:
-1. Spawn `deep-analyst` → Creates analysis in `.claude/state/phase1_analysis.md`
-2. Spawn `plan-validator` → Challenges plan in `.claude/state/phase1_validation.md`
-3. Spawn `tdd-designer` → Designs tests in `.claude/state/phase1_test_design.md`
-4. Iterate 2-4 times until plan is solid
-5. Write final plan to `.claude/plans/jwt-auth.md`
-6. **STOP and present summary**
-
-**Step 3: Review and approve**
-```
-# Review the plan
-Read .claude/plans/jwt-auth.md
-
-# If satisfied:
-APPROVE
-
-# If changes needed:
-REVISE: Add support for refresh token rotation, also consider session invalidation on password change
-```
-
-**Step 4: Autonomous implementation**
-
-After APPROVE, Phase 2 runs without stopping:
-- Implements each step
-- Runs tests after each step
-- Fixes failures automatically
-- Reports only when DONE or BLOCKED
-
----
-
-### Example 2: Quick Bug Fix
-
-**Task:** "Fix the broken date formatting in user profiles"
-
-```
-Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
-Fix the date formatting bug in src/components/UserProfile.tsx
-
-The issue: Dates show as "Invalid Date" for users with null birthdates.
-
-Fix: Add null check before formatting.
-Test: Verify with null, valid date, and edge cases.
-
-Execute WITHOUT stopping. Report when done.
-```
-
----
-
-### Example 3: Analysis Without Implementation
-
-**Task:** "Understand how the caching layer works before optimizing"
-
-```
-Read .claude/agents/deep-analyst.md and spawn a deep-analyst to analyze
-the caching implementation in src/services/cache/.
-
-Trace:
-1. What gets cached and for how long
-2. Cache invalidation strategy
-3. Memory usage patterns
-4. Performance bottlenecks
-
-DO NOT create an implementation plan - just analysis.
-Output to .claude/state/cache-analysis.md
-```
-
----
-
-## Tips for Best Results
-
-1. **Be specific** - More detail = better results
-2. **Include context** - Mention relevant files, constraints, or requirements
-3. **Start with iteration-controller** - For any non-trivial task
-4. **Use specialists** - They know your project's patterns
-5. **Let Phase 2 run** - Don't interrupt unless truly necessary
-6. **Review plans carefully** - Reject vague steps
-
----
-
-*Generated by archai. See README.md for full documentation.*
+# archai Prompt Templates
+
+Complete reference for using the agent system. Copy and customize these prompts.
+
+---
+
+## Full Orchestration Prompt (Recommended)
+
+Copy this to start the full three-phase workflow:
+
+```
+Follow the orchestration guide in .claude/agents/maestro-agent.md to create an
+implementation plan for: {YOUR TASK DESCRIPTION}
+
+PHASE 1 INSTRUCTIONS (Planning - requires approval):
+1. Read each agent's full instruction file from .claude/agents/ BEFORE spawning
+2. Pass the COMPLETE instructions to each subagent in the Task prompt
+3. Save ALL agent outputs to .claude/state/ directory
+4. Run at least 2 planning iterations (THINK → VALIDATE → TEST DESIGN → VALIDATE TESTS → RETHINK)
+5. After planning complete, write final plan to .claude/plans/{task-name}.md
+6. STOP and present the plan summary - do NOT implement until I say "APPROVE"
+
+PHASE 2 INSTRUCTIONS (Implementation - AUTONOMOUS after approval):
+When I say "APPROVE", execute Phase 2 AUTONOMOUSLY:
+- Implement ALL steps without stopping to ask
+- Run tests after each step
+- Fix failures automatically (up to 5 attempts per step)
+- Only report back when ALL DONE or truly BLOCKED
+- DO NOT ask "should I proceed?" - just execute the full loop
+- When Phase 2 complete, present summary and wait for FINAL APPROVAL
+
+PHASE 3 INSTRUCTIONS (Finalization - after implementation approved):
+When I say "APPROVE" on implementation:
+- Read .claude/agents/finalization-agent.md
+- Spawn finalization-agent to verify, cleanup, commit, push, wait for CI/CD
+- Report final status
+
+Start with Phase 1, Iteration 1: Read .claude/agents/deep-analyst.md and
+spawn a deep-analyst subagent to analyze the task.
+```
+
+---
+
+## Task Preparation Prompt (Recommended First Step)
+
+Use this to structure a vague or complex task before execution:
+
+```
+Use task-prep for: {YOUR RAW TASK DESCRIPTION}
+```
+
+After approval, feed the result to the execution loop:
+
+```
+Use maestro-agent for: the prepared task in .claude/state/prepared-task.md
+```
+
+---
+
+## Phase 2 Only Prompt (After Plan is Approved)
+
+Use this when resuming after approval:
+
+```
+The plan in .claude/plans/{task-name}.md has been APPROVED.
+
+Execute Phase 2 AUTONOMOUSLY:
+1. Read .claude/agents/implementation-agent.md
+2. Spawn implementation-agent with FULL instructions
+3. The agent must execute ALL steps WITHOUT stopping to ask
+4. Loop: implement → test → fix failures → next step → repeat
+5. Only report back when COMPLETELY DONE or truly BLOCKED
+6. When done, present summary and wait for FINAL APPROVAL
+
+DO NOT ask for permission between steps. Just execute until done.
+```
+
+---
+
+## Phase 3 Only Prompt (After Implementation is Approved)
+
+Use this when implementation is done and you've approved it:
+
+```
+The implementation is complete and APPROVED.
+
+Execute Phase 3 (Finalization):
+1. Read .claude/agents/finalization-agent.md
+2. Spawn finalization-agent with FULL instructions
+3. The agent will:
+   - Verify all acceptance criteria against original task
+   - Run local quality checks (typecheck, lint)
+   - Clean up temp files
+   - Commit with proper message
+   - Push to remote (triggers CI/CD)
+   - Wait for CI/CD to pass
+4. Report final status when complete
+
+Branch: {branch-name}
+Task file: {.tasks/epics/TASK-XXX/epic.md or original task}
+```
+
+---
+
+## Planning Phase Only
+
+### Deep Analysis
+
+```
+Read .claude/agents/deep-analyst.md and spawn a deep-analyst to analyze:
+{WHAT TO ANALYZE}
+
+Focus on:
+- What is the REAL problem we're solving?
+- What are the dependencies?
+- What could go wrong?
+
+DO NOT create an implementation plan yet - just analysis.
+Output to .claude/state/analysis-{topic}.md
+```
+
+**Examples:**
+```
+Read .claude/agents/deep-analyst.md and spawn a deep-analyst to analyze
+our current authentication flow.
+
+Trace:
+1. How users log in
+2. How tokens are validated
+3. How sessions are managed
+
+DO NOT create an implementation plan yet - just analysis.
+Output to .claude/state/auth-flow-analysis.md
+```
+
+### Plan Validation
+
+```
+Read .claude/agents/plan-validator.md and spawn a plan-validator to
+challenge the plan in .claude/state/{plan-file}.md
+
+Your job is to FIND PROBLEMS, not approve the plan.
+Look for:
+- Vague steps ("handle edge cases")
+- Missing error handling
+- Untested assumptions
+- Performance concerns
+
+Output critique to .claude/state/plan-validation.md
+```
+
+### Test Design (TDD)
+
+```
+Read .claude/agents/tdd-designer.md and spawn a tdd-designer to create
+test designs for: {FEATURE DESCRIPTION}
+
+Focus on:
+- Real user workflows, not implementation details
+- Concrete values (not "test with valid input")
+- Tests that would FAIL if code is broken
+- Edge cases and boundary conditions
+
+Output to .claude/state/test-design-{feature}.md
+```
+
+**Examples:**
+```
+Read .claude/agents/tdd-designer.md and spawn a tdd-designer to create
+test designs for the user registration flow.
+
+Focus on:
+- Valid registration with all fields
+- Missing required fields (each field separately)
+- Invalid email formats
+- Password strength requirements
+- Duplicate email handling
+
+Use concrete values like:
+- email: "test@example.com"
+- password: "SecureP@ss123"
+
+Output to .claude/state/test-design-registration.md
+```
+
+---
+
+## Implementation Phase Only
+
+### Direct Implementation (Skip Planning)
+
+Use only for simple, well-defined tasks:
+
+```
+Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
+{SPECIFIC TASK}
+
+Execute WITHOUT stopping to ask. Just implement and test.
+Report back when DONE or truly BLOCKED.
+```
+
+**Examples:**
+```
+Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
+Fix the typo in src/components/Header.tsx - change "Welcom" to "Welcome"
+
+Execute WITHOUT stopping to ask. Report back when done.
+```
+
+```
+Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
+Add a loading spinner to the submit button in LoginForm.tsx
+
+Requirements:
+- Show spinner when form is submitting
+- Disable button during submission
+- Hide spinner when complete
+
+Execute WITHOUT stopping to ask. Run tests after changes.
+```
+
+### Code Review
+
+```
+Read .claude/agents/code-reviewer.md and spawn a code-reviewer to
+review the changes in: {LOCATION}
+
+Focus on:
+- Does it match the approved plan?
+- Are there bugs or edge cases missed?
+- Is error handling complete?
+- Are tests adequate?
+
+Output review to .claude/state/code-review-{feature}.md
+```
+
+**Examples:**
+```
+Read .claude/agents/code-reviewer.md and spawn a code-reviewer to
+review the changes in src/api/auth/
+
+Focus on:
+- Security vulnerabilities
+- Error handling completeness
+- Test coverage
+- API contract compliance
+
+Output review to .claude/state/code-review-auth-api.md
+```
+
+---
+
+## Finalization Phase
+
+### Cleanup Before Commit
+
+```
+Read .claude/agents/cleanup-agent.md and spawn a cleanup-agent for task: {TASK}
+
+Clean up:
+- .claude/state/ (except archived)
+- .agents/scratch/
+- .agents/thoughts/
+- Any temporary files
+
+Preserve:
+- .knowledge/ (all of it)
+- .claude/plans/ (approved plans)
+- Actual source code changes
+```
+
+### Full Finalization
+
+```
+Read .claude/agents/finalization-agent.md and spawn a finalization-agent.
+
+Task: {TASK DESCRIPTION}
+Branch: {BRANCH NAME}
+
+The agent will:
+1. Verify all acceptance criteria
+2. Run quality checks (typecheck, lint)
+3. Clean temporary files
+4. Commit with proper message
+5. Push to remote
+6. Wait for CI/CD
+7. Report final status
+```
+
+---
+
+## Task Management
+
+### Pick Up Next Task
+
+```
+Read .claude/agents/task-orchestrator.md and spawn a task-orchestrator to:
+Pick up the next task from .tasks/inbox/
+
+The agent will:
+1. Scan inbox for available tasks
+2. Select highest priority task
+3. Move to .tasks/epics/
+4. Create branch
+5. Begin Phase 1 planning
+```
+
+### Create New Epic
+
+```
+Read .claude/agents/task-orchestrator.md and spawn a task-orchestrator to:
+Create an epic for: {FEATURE DESCRIPTION}
+
+Include:
+- Clear acceptance criteria
+- Priority level
+- Estimated complexity
+- Dependencies (if any)
+
+Save to .tasks/inbox/TASK-{XXX}/epic.md
+```
+
+---
+
+## Specialist Agents
+
+After running `archai generate`, use your project-specific specialists:
+
+### Template: Invoke Any Specialist
+
+```
+Read .claude/agents/{specialist-name}.md and spawn a {specialist-name} to:
+{SPECIFIC TASK}
+
+Context:
+- {relevant context}
+
+Output to .claude/state/{output-file}.md
+```
+
+### Common Specialist Prompts
+
+```
+# Frontend work
+Read .claude/agents/frontend-specialist.md and spawn a frontend-specialist to:
+Create a reusable modal component with:
+- Backdrop click to close
+- ESC key to close
+- Focus trap
+- Smooth animations
+
+Output to .claude/state/modal-component-design.md
+```
+
+```
+# Backend work
+Read .claude/agents/backend-specialist.md and spawn a backend-specialist to:
+Add rate limiting to the API endpoints in src/api/
+
+Requirements:
+- 100 requests per minute per IP
+- Return 429 with Retry-After header
+- Whitelist internal services
+
+Output to .claude/state/rate-limiting-design.md
+```
+
+```
+# Database work
+Read .claude/agents/database-specialist.md and spawn a database-specialist to:
+Optimize the slow query in getUserOrders()
+
+Current query takes 2+ seconds with 10k orders.
+Target: under 100ms
+
+Output to .claude/state/query-optimization.md
+```
+
+---
+
+## Quick Reference Card
+
+| I want to... | Use this prompt... |
+|--------------|-------------------|
+| Prepare a task spec | `Use task-prep for: [description]` |
+| Implement a feature | `Use maestro-agent for: X. Run Phase 1, wait for APPROVE.` |
+| Analyze code first | `Read deep-analyst.md, spawn deep-analyst to analyze: X` |
+| Design tests only | `Read tdd-designer.md, spawn tdd-designer to design tests for: X` |
+| Get specialist help | `Read {name}-specialist.md, spawn {name}-specialist for: X` |
+| Resume implementation | `The plan in .claude/plans/X.md has been APPROVED. Execute Phase 2 AUTONOMOUSLY.` |
+| Finalize (commit/push) | `Implementation APPROVED. Execute Phase 3 with finalization-agent.` |
+| Clean up before commit | `Read cleanup-agent.md, spawn cleanup-agent for task: X` |
+| Approve a plan | `APPROVE` |
+| Approve implementation | `APPROVE` (triggers Phase 3 finalization) |
+| Request changes | `REVISE: [specific changes]` |
+| Stop workflow | `REJECT: [reason]` |
+
+---
+
+## Step-by-Step Examples
+
+### Example 1: Implement a New Feature
+
+**Task:** "Add user authentication with JWT"
+
+**Step 1: Prepare the task spec (recommended)**
+```
+Use task-prep for: add user authentication with JWT
+```
+
+The agent will:
+1. Read project context and codebase structure
+2. Classify as Task or Epic
+3. Ask 1-2 targeted clarifying questions (scope, constraints)
+4. Write structured spec to `.claude/state/prepared-task.md`
+5. Present for your approval
+
+```
+APPROVE
+```
+
+**Step 2: Start the orchestrated workflow**
+```
+Use maestro-agent for: the prepared task in .claude/state/prepared-task.md
+```
+
+The agent will:
+1. Spawn `deep-analyst` → Creates analysis in `.claude/state/phase1_analysis.md`
+2. Spawn `plan-validator` → Challenges plan in `.claude/state/phase1_validation.md`
+3. Spawn `tdd-designer` → Designs tests in `.claude/state/phase1_test_design.md`
+4. Iterate 2-4 times until plan is solid
+5. Write final plan to `.claude/plans/jwt-auth.md`
+6. **STOP and present summary**
+
+**Step 3: Review and approve**
+```
+# Review the plan
+Read .claude/plans/jwt-auth.md
+
+# If satisfied:
+APPROVE
+
+# If changes needed:
+REVISE: Add support for refresh token rotation, also consider session invalidation on password change
+```
+
+**Step 4: Autonomous implementation**
+
+After APPROVE, Phase 2 runs without stopping:
+- Implements each step
+- Runs tests after each step
+- Fixes failures automatically
+- Reports only when DONE or BLOCKED
+
+---
+
+### Example 2: Quick Bug Fix
+
+**Task:** "Fix the broken date formatting in user profiles"
+
+```
+Read .claude/agents/implementation-agent.md and spawn an implementation-agent to:
+Fix the date formatting bug in src/components/UserProfile.tsx
+
+The issue: Dates show as "Invalid Date" for users with null birthdates.
+
+Fix: Add null check before formatting.
+Test: Verify with null, valid date, and edge cases.
+
+Execute WITHOUT stopping. Report when done.
+```
+
+---
+
+### Example 3: Analysis Without Implementation
+
+**Task:** "Understand how the caching layer works before optimizing"
+
+```
+Read .claude/agents/deep-analyst.md and spawn a deep-analyst to analyze
+the caching implementation in src/services/cache/.
+
+Trace:
+1. What gets cached and for how long
+2. Cache invalidation strategy
+3. Memory usage patterns
+4. Performance bottlenecks
+
+DO NOT create an implementation plan - just analysis.
+Output to .claude/state/cache-analysis.md
+```
+
+---
+
+## Tips for Best Results
+
+1. **Be specific** - More detail = better results
+2. **Include context** - Mention relevant files, constraints, or requirements
+3. **Start with maestro-agent** - For any non-trivial task
+4. **Use specialists** - They know your project's patterns
+5. **Let Phase 2 run** - Don't interrupt unless truly necessary
+6. **Review plans carefully** - Reject vague steps
+
+---
+
+*Generated by archai. See README.md for full documentation.*