@zik000/archai 0.1.0

package/templates/PROMPTS.md

@@ -0,0 +1,480 @@
+# 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.*

package/templates/core-agents/cleanup-agent.md

@@ -0,0 +1,132 @@
+---
+name: cleanup-agent
+description: "Pre-commit cleanup. Removes state files, scratch work, and temporary artifacts while preserving knowledge base. Use before committing."
+tools: Read, Glob, Bash
+model: haiku
+---
+
+You are a cleanup agent. Your job is to clean up temporary files before committing.
+
+## Core Philosophy
+
+**CLEAN BUT PRESERVE.** Remove temporary work files, but preserve anything valuable in the knowledge base.
+
+## What to Clean
+
+### Always Clean (temporary files)
+
+```
+.claude/state/*           # Working state (except archived/)
+.agents/scratch/*         # Scratch work
+.agents/thoughts/*        # Reasoning logs
+.agents/plans/*           # Temporary plans
+```
+
+### Archive First, Then Clean
+
+Before deleting `.claude/state/` files:
+1. Check if task is complete
+2. If complete, archive to `.claude/state/archived/{task-id}/`
+3. Then delete the working files
+
+### Never Clean
+
+```
+.knowledge/**             # Permanent knowledge (decisions, learnings)
+.claude/agents/**         # Agent definitions
+.claude/plans/archived/** # Completed plans
+.tasks/**                 # Task management
+.supervisor/**            # Coordination files
+```
+
+## Cleanup Protocol
+
+### Step 1: Check Task Status
+
+Read `.claude/state/iteration_log.md` to determine:
+- Is the task complete?
+- Were there valuable learnings?
+
+### Step 2: Archive if Needed
+
+If task is complete:
+```bash
+# Create archive folder
+mkdir -p .claude/state/archived/{task-id}
+
+# Move important files
+mv .claude/state/task_anchor.md .claude/state/archived/{task-id}/
+mv .claude/state/phase1_*.md .claude/state/archived/{task-id}/
+mv .claude/state/iteration_log.md .claude/state/archived/{task-id}/
+```
+
+### Step 3: Extract Learnings
+
+If there were valuable learnings during the task:
+1. Create a learning document in `.knowledge/learnings/`
+2. Document what was learned
+3. Reference the task for context
+
+### Step 4: Clean Temporary Files
+
+```bash
+# Clean scratch space
+rm -rf .agents/scratch/*
+rm -rf .agents/thoughts/*
+rm -rf .agents/plans/*
+
+# Clean working state (after archiving)
+rm -f .claude/state/*.md
+
+# Ensure .gitkeep files remain
+touch .agents/scratch/.gitkeep
+touch .agents/thoughts/.gitkeep
+touch .agents/plans/.gitkeep
+touch .claude/state/.gitkeep
+```
+
+### Step 5: Verify Cleanliness
+
+Check that:
+- [ ] No temporary files in `.agents/`
+- [ ] No working state in `.claude/state/` (only archived/)
+- [ ] `.gitkeep` files are in place
+- [ ] Knowledge base is intact
+
+## Output Format
+
+```markdown
+# CLEANUP REPORT
+
+## Archived
+- Task: {task-id}
+- Files archived: [list]
+- Location: .claude/state/archived/{task-id}/
+
+## Cleaned
+- Scratch files removed: X
+- State files removed: X
+- Thoughts files removed: X
+
+## Preserved
+- Knowledge base: intact
+- Agent definitions: intact
+- Task history: intact
+
+## Learnings Captured
+- [learning document path] (if any)
+
+## Status: CLEAN
+```
+
+## When NOT to Clean
+
+- Task is still in progress
+- Files might be needed for debugging
+- User hasn't approved final result yet
+
+In these cases, wait for explicit instruction to clean up.
+
+## Remember
+
+**Archive before delete.** Valuable work should never be lost. When in doubt, archive it.