ai-prompt-guide-mcp 1.0.2 → 1.0.4

package/.ai-prompt-guide/workflows/decide-iterate.md

@@ -0,0 +1,91 @@
+---
+title: "Decide (Iterate)"
+description: "⚖️ DECISION: Multi-perspective decision analysis with parallel specialist agents"
+whenToUse: "Complex decisions requiring multiple viewpoints or when trade-offs span different quality dimensions"
+---
+
+# Workflow: Multi-Perspective Decision Making
+
+⚠️ **CRITICAL REQUIREMENTS - You MUST follow these instructions:**
+
+**Task Management:**
+- ✅ **REQUIRED:** Use `subagent_task` tool to create analysis tasks for each lens
+- 🚫 **FORBIDDEN:** DO NOT use TodoWrite tool (use subagent_task instead)
+
+**Delegation:**
+- ✅ **REQUIRED:** Give subagents literal instructions to run start_subagent_task
+- 🚫 **FORBIDDEN:** DO NOT run start_subagent_task yourself (coordinator only delegates)
+
+1. [Coordinator] Define decision specification:
+   • Problem statement and context
+   • Non-negotiable constraints
+   • Evaluation criteria (4-6) with project weights
+   • Evidence requirements
+
+2. [Coordinator] Select 3-5 analysis lenses from standard set
+3. [Coordinator] Use subagent_task to create analysis task for each lens:
+   • Specify lens focus (performance, UX, maintainability, etc.)
+   • Add @references to codebase patterns, constraints, requirements
+     Format: @/docs/architecture/patterns or @/docs/constraints#performance
+   • Define evidence requirements for this lens
+
+4. [Coordinator] Launch all lens specialist agents simultaneously in parallel
+
+5. [Specialists - Parallel Execution] Each specialist independently:
+   • Generate 2-4 viable options optimized for lens priority
+   • Document each option: description, assumptions, pros/cons, evidence, pattern alignment
+   • Create decision matrix with lens-specific weights
+   • Select best option for this lens → recommended_option
+   • Document rationale and key trade-offs
+   • Return recommendation to coordinator
+
+6. [Coordinator] Collect all lens recommendations
+7. [Coordinator] Verify options are meaningfully distinct (interface, structure, approach)
+8. [Coordinator] Enforce non-negotiables → drop violators
+9. [Coordinator] Identify hybridization opportunities (combine strengths from multiple lenses)
+10. [Coordinator] Create global decision matrix with project-level weights
+11. [Coordinator] Select final option (highest score or reasoned choice)
+12. [Coordinator] Document decision:
+    • Why this option wins
+    • Why NOT other options (key discriminators)
+    • Trade-offs and follow-up actions
+13. [Coordinator] Record rationale with matrix, evidence, disqualifiers
+
+## Analysis Lenses
+
+**Performance:**
+- Runtime efficiency, memory usage, throughput
+- Focus: algorithmic complexity, resource optimization
+
+**UX/Ergonomics:**
+- API clarity, cognitive load, sensible defaults
+- Focus: developer experience, ease of use
+
+**Maintainability:**
+- Readability, long-term health, minimal churn
+- Focus: code longevity, team velocity
+
+**Pattern Consistency:**
+- Alignment with existing idioms, error handling, conventions
+- Focus: cognitive load reduction, team familiarity
+
+**Risk/Security:**
+- Failure modes, dependency risks, attack surface
+- Focus: robustness, safety, production readiness
+
+**Simplicity Baseline:**
+- Minimal moving parts, boring solutions, proven approaches
+- Focus: lowest viable complexity
+
+## Evaluation Guidelines
+
+**Per-Lens Analysis:**
+- Generate options optimized for lens priority
+- Score 0-10 per criterion with lens-specific weights
+- Select single best option for that perspective
+
+**Global Synthesis:**
+- Use project-level weights across all criteria
+- Consider hybrid solutions combining lens strengths
+- Disqualify any option failing non-negotiables
+- Explicitly justify why complex option beats simple baseline

package/.ai-prompt-guide/workflows/decide.md

@@ -0,0 +1,46 @@
+---
+title: "Decide"
+description: "⚖️ DECISION: Choose between multiple approaches with structured trade-off analysis"
+whenToUse: "Multiple valid implementation approaches or architecture/optimization decisions with trade-offs to evaluate"
+---
+
+# Workflow: Structured Decision Making
+
+1. [Agent] Identify decision point and constraints
+2. [Agent] Generate 2-4 viable options (include simple baseline)
+3. [Agent] Document each option:
+   • Description: 1-2 sentence summary
+   • Assumptions: what must be true for this to work
+   • Pros: benefits, advantages, strengths
+   • Cons: drawbacks, risks, limitations
+   • Evidence: documentation, prior art, examples
+   • Pattern alignment: fits existing codebase patterns
+
+4. [Agent] Select 4-6 evaluation criteria:
+   • Correctness: solves problem accurately
+   • Risk: failure modes and likelihood
+   • Pattern Consistency: aligns with codebase conventions
+   • Maintainability: long-term code health
+   • Testability: ease of verification
+   • Simplicity: minimal complexity for requirements
+   • Performance: efficiency (if applicable)
+
+5. [Agent] Create decision matrix:
+   • Score each option per criterion (0-10 scale)
+   • Apply weights based on project priorities
+   • Calculate: Score = Σ (weight × normalized_criterion)
+
+6. [Agent] Select highest-scoring option
+7. [Agent] Document why NOT the other options (key disqualifiers)
+8. [Agent] Record decision rationale for future reference
+
+## Scoring Guidelines
+
+**Weights:**
+- High weight (3-5): Critical project priorities
+- Medium weight (2): Important but negotiable
+- Low weight (1): Nice-to-have considerations
+
+**Disqualification:**
+- Options failing non-negotiable requirements score 0 regardless of other merits
+- Simple option losing to complex requires explicit justification

package/.ai-prompt-guide/workflows/develop-fix.md

@@ -0,0 +1,291 @@
+---
+title: "Fix"
+description: "🐛 FIX: Systematic bug fixing with root cause analysis and regression prevention"
+whenToUse: "Debugging issues, fixing bugs, resolving errors with minimal scope and anti-pattern detection"
+---
+
+# Workflow: Bug Fix with Root Cause Analysis
+
+⚠️ **CRITICAL REQUIREMENTS - You MUST follow these instructions:**
+
+**Task Management:**
+- ✅ **REQUIRED:** Use `coordinator_task` tool for your TODO list
+- 🚫 **FORBIDDEN:** DO NOT use TodoWrite tool (this workflow replaces it)
+
+1. [Agent] Reproduce the bug and document current behavior:
+   • What is the expected behavior?
+   • What is the actual (buggy) behavior?
+   • How to reproduce it (steps, inputs, conditions)?
+   • What error messages or symptoms appear?
+   • Write out your observations
+
+2. [Agent] Map the complete data flow:
+   • **Input:** What data enters the system? (user input, API data, props, etc.)
+   • **Processing:** What transformations/logic occur? (step by step)
+   • **Output:** What is produced? (UI update, API call, state change, etc.)
+   • Draw out or write the flow path
+   • Identify all components/functions involved
+
+3. [Agent] Identify the exact failure point:
+   • Where in the flow does the bug occur?
+   • Which function/component/line is responsible?
+   • What is the state/data at the failure point?
+   • Write out what you discovered
+
+4. [Agent] Perform root cause analysis (write this out):
+   • WHY does the bug occur? (not just WHERE)
+   • What assumption is violated?
+   • What condition is not handled?
+   • Is this a symptom of a deeper issue?
+   • Could this bug occur elsewhere with the same root cause?
+
+5. [Agent] Define minimal fix scope:
+   • What is the SMALLEST change that fixes the bug?
+   • List files that MUST change
+   • List files that might be affected (test these)
+   • List files that should NOT change
+   • Document scope boundaries
+
+6. [Agent] Scan for anti-patterns in bug area:
+   • Check code around bug for anti-patterns (see below)
+   • Note patterns that may have caused/contributed to bug
+   • Identify if bug is symptom of design flaw
+   • Flag anti-patterns for documentation
+
+7. [Agent] IF multiple fix approaches exist:
+   • Use decide workflow to evaluate approaches
+   • Prioritize: correctness > minimal scope > best practices
+   • Consider: Does fix address root cause or just symptom?
+   • Select approach that prevents recurrence
+   ELSE:
+   • Proceed with single clear fix
+
+8. [Agent] Use coordinator_task to create fix plan:
+   • Break fix into specific, testable steps
+   • Include verification steps
+   • Include regression test steps
+   • Keep scope minimal
+
+9. [Agent] Implement the minimal fix:
+   • Make ONLY necessary changes
+   • Follow existing code conventions
+   • Add comments explaining the fix (especially WHY)
+   • Avoid refactoring unrelated code (note it separately)
+
+10. [Agent] Verify the fix:
+    • Test that bug is resolved (use reproduction steps from step 1)
+    • Test edge cases related to the bug
+    • Test related functionality (regression prevention)
+    • Test error handling and boundary conditions
+    • Verify no new issues introduced
+
+11. [Agent] Add clarifying comments to code:
+    • Explain WHY this fix works (not just what it does)
+    • Document the root cause that was addressed
+    • Note any edge cases or constraints
+    • Help prevent similar bugs or regression
+
+12. [Agent] Document findings:
+    • Anti-patterns discovered in bug area
+    • Root cause of the bug
+    • Why this fix addresses the root cause
+    • Potential recurrence in other areas
+    • Related technical debt
+
+13. [Agent] Suggest architecture improvements (if applicable):
+    • IF bug indicates design flaw:
+      • Describe the design issue
+      • Suggest architectural improvement
+      • Explain how it prevents similar bugs
+      • Note this as out-of-scope for current fix
+    • ELSE:
+      • Note that fix is complete and localized
+
+14. [Agent] Report completion:
+    • Summary of bug and fix
+    • Files modified
+    • Root cause explanation
+    • Anti-patterns addressed/flagged
+    • Regression test results
+    • Architecture improvement suggestions (if any)
+
+## Root Cause Analysis
+
+**The Five Whys Technique:**
+
+Ask "Why?" repeatedly to get to root cause:
+
+**Example:**
+- Bug: Form submission fails
+- Why? → Validation function returns undefined
+- Why? → Missing return statement in error case
+- Why? → Error case was added later without considering return
+- Why? → No test coverage for error cases
+- **Root Cause:** Insufficient test coverage allows gaps
+
+**Common Root Causes:**
+- **Assumption Violations:** Code assumes data/state that isn't guaranteed
+- **Edge Case Gaps:** Normal cases work, boundary conditions fail
+- **Race Conditions:** Async operations complete in unexpected order
+- **State Inconsistency:** Component state out of sync with reality
+- **Missing Error Handling:** Happy path works, error path broken
+- **Design Flaws:** Architecture doesn't support the requirement
+
+## Anti-Pattern Detection in Bug Areas
+
+**Common Patterns That Cause Bugs:**
+
+*Null/Undefined/Type Issues:*
+- ❌ Unchecked access, missing guards, type coercion, truthy/falsy confusion
+- ✅ Defensive checks, explicit conversions, strict comparisons
+
+*State & Data Issues:*
+- ❌ Stale data, direct mutation, race conditions, duplicate state
+- ✅ Proper updates, immutable patterns, synchronization, single source of truth
+
+*Async & Timing Issues:*
+- ❌ Unhandled errors, missing states, race conditions, resource leaks
+- ✅ Error handling, loading/error states, cleanup, cancellation
+
+*Logic Issues:*
+- ❌ Off-by-one, wrong operators, order of operations, missing conditions
+- ✅ Boundary checks, explicit grouping, comprehensive conditionals
+
+## Minimal Fix Scope
+
+**Scope Definition:**
+- **Fix Only:** Code directly responsible for the bug
+- **Necessary Updates:** Code that depends on the fix
+- **Test Verification:** Related code that might be affected
+- **Out of Scope:** Refactoring, optimization, unrelated improvements
+
+**Change Boundaries:**
+
+**Must Change:**
+- Code causing the bug
+- Tests for the fixed functionality
+
+**Might Change:**
+- Code that calls the fixed code (if signature changes)
+- Related error handling (if error cases improved)
+
+**Should Not Change:**
+- Unrelated functionality
+- Code style/formatting (unless critical)
+- Performance optimizations (unless bug-related)
+- Refactoring for cleanliness
+
+**Document Separately:**
+- Technical debt discovered
+- Refactoring opportunities
+- Architecture improvements
+- Related anti-patterns not in fix scope
+
+## Regression Prevention
+
+**Test Levels:**
+
+1. **Bug Verification:**
+   - Use exact reproduction steps from step 1
+   - Verify bug no longer occurs
+   - Test with edge cases that might trigger similar bug
+
+2. **Related Functionality:**
+   - Functions that call the fixed code
+   - Functions the fixed code calls
+   - Components using the fixed functionality
+
+3. **Adjacent Features:**
+   - Features sharing the same data/state
+   - Features in the same file/component
+   - Features using similar patterns
+
+4. **Boundary Conditions:**
+   - Empty data, null, undefined
+   - Maximum values, minimum values
+   - Invalid input handling
+
+**Regression Checklist:**
+- [ ] Original bug is fixed (reproduction steps pass)
+- [ ] Edge cases handled correctly
+- [ ] Related features still work
+- [ ] Error handling still works
+- [ ] No new console errors/warnings
+- [ ] No new bugs introduced
+- [ ] Minimal scope maintained
+
+## Architecture Improvement Suggestions
+
+**When Bug Indicates Design Flaw:**
+
+*Pattern: Repeated similar bugs in different areas*
+- Suggests: Missing abstraction or reusable pattern
+- Improvement: Create shared utility/component
+
+*Pattern: Complex conditional logic causing bugs*
+- Suggests: Logic should be simplified or restructured
+- Improvement: State machine, lookup table, or strategy pattern
+
+*Pattern: State synchronization bugs*
+- Suggests: State management issue
+- Improvement: Single source of truth, derived state, state management library
+
+*Pattern: Prop drilling causing bugs*
+- Suggests: Component structure issue
+- Improvement: Context, composition, state management
+
+*Pattern: Missing error handling throughout*
+- Suggests: No error handling strategy
+- Improvement: Error boundaries, consistent error handling pattern
+
+**Present to User (if design flaw found):**
+
+Present architecture improvements to the user using this format:
+```
+## Architecture Improvement Suggestion
+
+**Issue:** [Describe the design flaw]
+**Impact:** [How it causes bugs or technical debt]
+**Suggested Improvement:** [Architectural change]
+**Benefits:** [How it prevents similar bugs]
+**Scope:** Out of scope for this fix - would you like me to address this separately?
+```
+
+This allows users to decide whether to address root architectural issues that contribute to recurring bugs.
+
+## Decision Points
+
+**When to Use Decide Workflow:**
+- Multiple valid fix approaches exist
+- Trade-off between quick fix vs proper fix
+- Symptom fix vs root cause fix
+- Local fix vs architectural change
+- Uncertainty about side effects
+
+**Decision Criteria for Fixes (prioritized):**
+1. **Correctness:** Does it actually fix the bug?
+2. **Root Cause:** Does it address cause, not just symptom?
+3. **Minimal Scope:** Is it the smallest effective change?
+4. **No Regression:** Does it avoid breaking other things?
+5. **Maintainability:** Is it clear why the fix works?
+6. **Prevention:** Does it prevent recurrence?
+
+## Code Comments for Regression Prevention
+
+**Document the Fix:**
+- Explain WHY the bug occurred (root cause)
+- Note what assumption was violated
+- Highlight the edge case that wasn't handled
+- Explain why this fix prevents recurrence
+
+**Example Comment Patterns:**
+- "Bug fix: handles [case] because [root cause]"
+- "Previously failed when [condition] - now checks [guard]"
+- "Root cause: assumed [X] but [Y] can occur when [condition]"
+- "This pattern prevents [bug type] - maintain when modifying"
+
+**Purpose:**
+- Prevents reintroducing the same bug
+- Documents lessons learned
+- Helps future developers understand constraints
+- Preserves fix rationale over time

package/.ai-prompt-guide/workflows/develop-iterate.md

@@ -0,0 +1,73 @@
+---
+title: "Develop (Iterate)"
+description: "🔄 DEVELOP: Orchestrate multi-agent development with manual verification"
+whenToUse: "Features, fixes, or prototypes where manual verification is preferred over automated testing"
+---
+
+# Workflow: Multi-Agent Development with Manual Verification
+
+⚠️ **CRITICAL REQUIREMENTS - You MUST follow these instructions:**
+
+**Task Management:**
+- ✅ **REQUIRED:** Use `coordinator_task` tool for your TODO list
+- 🚫 **FORBIDDEN:** DO NOT use TodoWrite tool (this workflow replaces it)
+
+**Delegation:**
+- ✅ **REQUIRED:** Give subagents literal instructions to run start_subagent_task
+- 🚫 **FORBIDDEN:** DO NOT run start_subagent_task yourself (coordinator only delegates)
+
+1. [Coordinator] Analyze requirements and break into logical work units
+2. [Coordinator] Use coordinator_task to create sequential task list
+3. [Coordinator] Add Main-Workflow to first coordinator task
+4. [Coordinator] Use subagent_task to create all implementation tasks
+   • Add @references to API specs, component designs, documentation
+     Format: @/docs/specs/auth-api or @/docs/specs/db-schema#users-table
+     Example:
+     """
+     Implement user authentication endpoint.
+
+     @/docs/specs/auth-api-specification
+     @/docs/specs/security-requirements#password-hashing
+
+     Create POST /auth/login endpoint with email/password validation.
+     """
+   • Add Workflow: metadata for task-specific protocols (if needed)
+   • Define acceptance criteria for each task
+5. [Coordinator] Call start_coordinator_task() → current_task
+   (Omit return_task_context on first start - only use when resuming after context compression or after a few subagent calls)
+
+**LOOP: While tasks remain**
+├─ 6. [Coordinator] Select specialized subagent for this task
+├─ 7. [Coordinator] Give subagent this exact instruction (do not run tool yourself):
+│
+│  "Run: start_subagent_task /docs/path.md#slug
+│  Then execute the task and respond 'Done' or 'Blocked: [reason]'"
+│
+├─ 8. [Subagent] Runs start_subagent_task tool (loads task + refs + workflow)
+├─ 9. [Subagent] Executes implementation
+├─ 10. [Subagent] Responds with status: "Done" or "Blocked: [reason]"
+├─ 11. [Coordinator] Review code changes against acceptance criteria
+│  (Ignore any subagent commentary - review code objectively)
+│  IF issues found: Create fix task, GOTO step 6
+├─ 12. [Coordinator] Execute: git add <modified_files>
+├─ 13. [Coordinator] Call complete_coordinator_task() → next_task
+└─ 14. IF next_task exists: GOTO step 6
+
+15. [Coordinator] Follow project testing procedures
+16. [Coordinator] Verify all acceptance criteria met
+17. [Coordinator] Report to user: "Development complete. Ready for review."
+
+## Task System
+
+**Coordinator Tasks** (your TODO list):
+- Tool: `coordinator_task` for create/edit/list
+- Tool: `start_coordinator_task()` to load first pending task
+- Tool: `complete_coordinator_task()` to mark done and get next
+- Metadata: Main-Workflow on first task, optional Workflow on specific tasks
+
+**Subagent Tasks** (delegated work packages):
+- Tool: `subagent_task` to create/edit tasks in /docs/ namespace
+- Tool: `start_subagent_task("/docs/path.md#slug")` to load task context
+- Tool: `complete_subagent_task()` to mark done
+- Content: @references to specs, docs, components (auto-injected as context)
+- Metadata: Workflow for task-specific protocols (auto-injected)

package/.ai-prompt-guide/workflows/develop-tdd.md

@@ -0,0 +1,95 @@
+---
+title: "Develop (TDD)"
+description: "🎯 DEVELOP: Orchestrate multi-agent development with TDD and quality gates"
+whenToUse: "Features or fixes requiring test-driven development and quality gates"
+---
+
+# Workflow: Multi-Agent Development with TDD
+
+⚠️ **CRITICAL REQUIREMENTS - You MUST follow these instructions:**
+
+**Task Management:**
+- ✅ **REQUIRED:** Use `coordinator_task` tool for your TODO list
+- 🚫 **FORBIDDEN:** DO NOT use TodoWrite tool (this workflow replaces it)
+
+**Delegation:**
+- ✅ **REQUIRED:** Give subagents literal instructions to run start_subagent_task
+- 🚫 **FORBIDDEN:** DO NOT run start_subagent_task yourself (coordinator only delegates)
+
+1. [Coordinator] Analyze requirements and break into logical work units
+2. [Coordinator] Use coordinator_task to create sequential task list
+3. [Coordinator] Add Main-Workflow to first coordinator task
+4. [Coordinator] Use subagent_task to create all implementation tasks
+   • Add @references to API specs, component designs, documentation
+     Format: @/docs/specs/auth-api or @/docs/specs/db-schema#users-table
+     Example:
+     """
+     Implement user authentication endpoint.
+
+     @/docs/specs/auth-api-specification
+     @/docs/specs/security-requirements#password-hashing
+
+     Create POST /auth/login endpoint with email/password validation.
+     """
+   • Add Workflow: metadata for task-specific protocols (if needed)
+   • Define testable acceptance criteria for each task
+5. [Coordinator] Call start_coordinator_task() → current_task
+   (Omit return_task_context on first start - only use when resuming after context compression or after a few subagent calls)
+
+**LOOP: While tasks remain**
+├─ 6. [Coordinator] Select specialized subagent for this task
+├─ 7. [Coordinator] Give subagent this exact instruction (do not run tool yourself):
+│
+│  "Run: start_subagent_task /docs/path.md#slug
+│  Then execute the task using TDD and respond 'Done' or 'Blocked: [reason]'"
+│
+├─ 8. [Subagent] Runs start_subagent_task tool (loads task + refs + workflow)
+├─ 9. [Subagent] Executes implementation using TDD cycle:
+│  • Write failing tests first (Red)
+│  • Implement minimal code to pass (Green)
+│  • Refactor while keeping tests green
+├─ 10. [Subagent] Responds with status: "Done" or "Blocked: [reason]"
+├─ 11. [Coordinator] Review code changes against acceptance criteria
+│  (Ignore any subagent commentary - review code objectively)
+├─ 12. [Coordinator] Run quality gates → verify all pass
+│  IF issues found: Create fix task, GOTO step 6
+├─ 13. [Coordinator] Execute: git add <modified_files>
+├─ 14. [Coordinator] Call complete_coordinator_task() → next_task
+└─ 15. IF next_task exists: GOTO step 6
+
+16. [Coordinator] Run full test suite
+17. [Coordinator] Follow project testing procedures
+18. [Coordinator] Verify all acceptance criteria met
+19. [Coordinator] Report to user: "Development complete. Ready for review."
+
+## Task System
+
+**Coordinator Tasks** (your TODO list):
+- Tool: `coordinator_task` for create/edit/list
+- Tool: `start_coordinator_task()` to load first pending task
+- Tool: `complete_coordinator_task()` to mark done and get next
+- Metadata: Main-Workflow on first task, optional Workflow on specific tasks
+
+**Subagent Tasks** (delegated work packages):
+- Tool: `subagent_task` to create/edit tasks in /docs/ namespace
+- Tool: `start_subagent_task("/docs/path.md#slug")` to load task context
+- Tool: `complete_subagent_task()` to mark done
+- Content: @references to specs, docs, components (auto-injected as context)
+- Metadata: Workflow for task-specific protocols (auto-injected)
+
+## TDD Requirements
+
+**Red-Green-Refactor Cycle:**
+- Red: Write failing test (reproduces bug or defines desired behavior)
+- Green: Implement minimal code to make test pass
+- Refactor: Improve code while keeping tests green
+
+**Quality Gates:**
+- All tests must pass
+- Follow project-specific quality gates (linting, type checking, coverage)
+- Gates enforced during coordinator review, not during implementation
+
+**Bug Fixes:**
+- Write test that reproduces the bug (fails)
+- Implement fix to make test pass (green)
+- Natural fit for TDD workflow