@bhimudev/gnanai 0.4.0

package/templates/PROMPTS.md

@@ -0,0 +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/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.*