feat(cli): update command templates

Author: codeaholicguy

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-devkit",
-  "version": "0.5.0",
+  "version": "0.12.0",
   "private": true,
   "description": "A CLI toolkit for AI-assisted software development with phase templates and environment setup",
   "scripts": {

packages/cli/templates/commands/capture-knowledge.md

@@ -1,50 +1,12 @@
 ---
-description: Capture structured knowledge about a code entry point and save it to the knowledge docs.
+description: Document a code entry point in knowledge docs.
 ---
 
-# Knowledge Capture Assistant
-
 Guide me through creating a structured understanding of a code entry point and saving it to the knowledge docs.
 
-## Step 1: Gather Context
-- Entry point (file, folder, function, API)
-- Why this entry point matters (feature, bug, investigation)
-- Relevant requirements/design docs (if any)
-- Desired depth or focus areas (logic, dependencies, data flow)
-
-## Step 2: Validate Entry Point
-- Determine entry point type and confirm it exists
-- Surface ambiguity (multiple matches) and ask for clarification
-- If not found, suggest likely alternatives or spelling fixes
-
-## Step 3: Collect Source Context
-- Read the primary file/module and summarize purpose, exports, key patterns
-- For folders: list structure, highlight key modules
-- For functions/APIs: capture signature, parameters, return values, error handling
-- Extract essential snippets (avoid large dumps)
-
-## Step 4: Analyze Dependencies
-- Build a dependency view up to depth 3
-- Track visited nodes to avoid loops
-- Categorize dependencies (imports, function calls, services, external packages)
-- Note important external systems or generated code that should be excluded
-
-## Step 5: Synthesize Explanation
-- Draft an overview (purpose, language, high-level behavior)
-- Detail core logic, key components, execution flow, patterns
-- Highlight error handling, performance, security considerations
-- Identify potential improvements or risks discovered during analysis
-
-## Step 6: Create Documentation
-- Normalize entry point name to kebab-case (`calculateTotalPrice` → `calculate-total-price`)
-- Create `docs/ai/implementation/knowledge-{name}.md` using the headings implied in Step 5 (Overview, Implementation Details, Dependencies, Visual Diagrams, Additional Insights, Metadata, Next Steps)
-- Populate sections with findings, diagrams, and metadata (analysis date, depth, files touched)
-- Include mermaid diagrams when they clarify flows or relationships
-
-## Step 7: Review & Next Actions
-- Summarize key insights and open questions for follow-up
-- Suggest related areas for deeper dives or refactors
-- Confirm the knowledge file path and remind to commit it
-- Encourage running `/capture-knowledge` again for related entry points if needed
-
-Let me know the entry point and goals when you’re ready to begin the knowledge capture.
+1. **Gather & Validate Entry Point** — If not already provided, ask for: entry point (file, folder, function, API), why it matters (feature, bug, investigation), and desired depth or focus areas. Confirm the entry point exists; if ambiguous or not found, clarify or suggest alternatives.
+2. **Collect Source Context** — Read the primary file/module and summarize purpose, exports, key patterns. For folders: list structure, highlight key modules. For functions/APIs: capture signature, parameters, return values, error handling. Extract essential snippets (avoid large dumps).
+3. **Analyze Dependencies** — Build a dependency view up to depth 3, tracking visited nodes to avoid loops. Categorize: imports, function calls, services, external packages. Note external systems or generated code to exclude.
+4. **Synthesize Explanation** — Draft overview (purpose, language, high-level behavior). Detail core logic, execution flow, key patterns. Highlight error handling, performance, security considerations. Identify potential improvements or risks.
+5. **Create Documentation** — Normalize name to kebab-case (`calculateTotalPrice` → `calculate-total-price`). Create `docs/ai/implementation/knowledge-{name}.md` with sections: Overview, Implementation Details, Dependencies, Visual Diagrams, Additional Insights, Metadata, Next Steps. Include mermaid diagrams when they clarify flows or relationships. Add metadata (analysis date, depth, files touched).
+6. **Review & Next Actions** — Summarize key insights and open questions. Suggest related areas for deeper dives. Confirm file path and remind to commit.

packages/cli/templates/commands/check-implementation.md

@@ -2,24 +2,9 @@
 description: Compare implementation with design and requirements docs to ensure alignment.
 ---
 
-Compare the current implementation with the design in docs/ai/design/ and requirements in docs/ai/requirements/. Please follow this structured review:
-
-1. Ask me for:
-   - Feature/branch description
-   - List of modified files
-   - Relevant design doc(s) (feature-specific and/or project-level)
-   - Any known constraints or assumptions
-
-2. For each design doc:
-   - Summarize key architectural decisions and constraints
-   - Highlight components, interfaces, and data flows that must be respected
-
-3. File-by-file comparison:
-   - Confirm implementation matches design intent
-   - Note deviations or missing pieces
-   - Flag logic gaps, edge cases, or security issues
-   - Suggest simplifications or refactors
-   - Identify missing tests or documentation updates
+Compare the current implementation with the design in docs/ai/design/ and requirements in docs/ai/requirements/.
 
+1. If not already provided, ask for: feature/branch description, list of modified files, relevant design doc(s), and any known constraints or assumptions.
+2. For each design doc: summarize key architectural decisions and constraints, highlight components, interfaces, and data flows that must be respected.
+3. File-by-file comparison: confirm implementation matches design intent, note deviations or missing pieces, flag logic gaps, edge cases, or security issues, suggest simplifications or refactors, and identify missing tests or documentation updates.
 4. Summarize findings with recommended next steps.
-

packages/cli/templates/commands/code-review.md

@@ -1,85 +1,11 @@
 ---
-description: Perform a local code review before pushing changes, ensuring alignment with design docs and best practices.
+description: Pre-push code review against design docs.
 ---
 
-# Local Code Review Assistant
+Perform a local code review **before** pushing changes.
 
-You are helping me perform a local code review **before** I push changes. Please follow this structured workflow.
-
-## Step 1: Gather Context
-Ask me for:
-- Brief feature/branch description
-- List of modified files (with optional summaries)
-- Relevant design doc(s) (e.g., `docs/ai/design/feature-{name}.md` or project-level design)
-- Any known constraints or risky areas
-- Any open bugs or TODOs linked to this work
-- Which tests have already been run
-
-If possible, request the latest diff:
-```bash
-git status -sb
-git diff --stat
-```
-
-## Step 2: Understand Design Alignment
-For each provided design doc:
-- Summarize the architectural intent
-- Note critical requirements, patterns, or constraints the design mandates
-
-## Step 3: File-by-File Review
-For every modified file:
-1. Highlight deviations from the referenced design or requirements
-2. Spot potential logic or flow issues and edge cases
-3. Identify redundant or duplicate code
-4. Suggest simplifications or refactors (prefer clarity over cleverness)
-5. Flag security concerns (input validation, secrets, auth, data handling)
-6. Check for performance pitfalls or scalability risks
-7. Ensure error handling, logging, and observability are appropriate
-8. Note any missing comments or docs
-9. Flag missing or outdated tests related to this file
-
-## Step 4: Cross-Cutting Concerns
-- Verify naming consistency and adherence to project conventions
-- Confirm documentation/comments are updated where the behavior changed
-- Identify missing tests (unit, integration, E2E) needed to cover the changes
-- Ensure configuration/migration updates are captured if applicable
-
-## Step 5: Summarize Findings
-Provide results in this structure:
-```
-### Summary
-- Blocking issues: [count]
-- Important follow-ups: [count]
-- Nice-to-have improvements: [count]
-
-### Detailed Notes
-1. **[File or Component]**
-   - Issue/Observation: ...
-   - Impact: (e.g., blocking / important / nice-to-have)
-   - Recommendation: ...
-   - Design reference: [...]
-
-2. ... (repeat per finding)
-
-### Recommended Next Steps
-- [ ] Address blocking issues
-- [ ] Update design/implementation docs if needed
-- [ ] Add/adjust tests:
-      - Unit:
-      - Integration:
-      - E2E:
-- [ ] Rerun local test suite
-- [ ] Re-run code review command after fixes
-```
-
-## Step 6: Final Checklist
-Confirm whether each item is complete (yes/no/needs follow-up):
-- Implementation matches design & requirements
-- No obvious logic or edge-case gaps remain
-- Redundant code removed or justified
-- Security considerations addressed
-- Tests cover new/changed behavior
-- Documentation/design notes updated
-
----
-Let me know when you're ready to begin the review.
+1. **Gather Context** — If not already provided, ask for: feature/branch description, list of modified files, relevant design doc(s) (e.g., `docs/ai/design/feature-{name}.md`), known constraints or risky areas, and which tests have been run. Also review the latest diff via `git status` and `git diff --stat`.
+2. **Understand Design Alignment** — For each design doc, summarize architectural intent and critical constraints.
+3. **File-by-File Review** — For every modified file: check alignment with design/requirements and flag deviations, spot logic issues/edge cases/redundant code, flag security concerns (input validation, secrets, auth, data handling), check error handling/performance/observability, and identify missing or outdated tests.
+4. **Cross-Cutting Concerns** — Verify naming consistency and project conventions. Confirm docs/comments updated where behavior changed. Identify missing tests (unit, integration, E2E). Check for needed configuration/migration updates.
+5. **Summarize Findings** — Categorize each finding as **blocking**, **important**, or **nice-to-have** with: file, issue, impact, recommendation, and design reference.

packages/cli/templates/commands/debug.md

@@ -1,49 +1,11 @@
 ---
-description: Guide me through debugging a code issue by clarifying expectations, identifying gaps, and agreeing on a fix plan before changing code.
+description: Debug an issue with structured root-cause analysis before changing code.
 ---
 
-# Local Debugging Assistant
-
-Help me debug an issue by clarifying expectations, identifying gaps, and agreeing on a fix plan before changing code.
-
-## Step 1: Gather Context
-Ask me for:
-- Brief issue description (what is happening?)
-- Expected behavior or acceptance criteria (what should happen?)
-- Current behavior and any error messages/logs
-- Recent related changes or deployments
-- Scope of impact (users, services, environments)
-
-## Step 2: Clarify Reality vs Expectation
-- Restate the observed behavior vs the expected outcome
-- Confirm relevant requirements, tickets, or docs that define the expectation
-- Identify acceptance criteria for the fix (how we know it is resolved)
-
-## Step 3: Reproduce & Isolate
-- Determine reproducibility (always, intermittent, environment-specific)
-- Capture reproduction steps or commands
-- Note any available tests that expose the failure
-- List suspected components, services, or modules
-
-## Step 4: Analyze Potential Causes
-- Brainstorm plausible root causes (data, config, code regressions, external dependencies)
-- Gather supporting evidence (logs, metrics, traces, screenshots)
-- Highlight gaps or unknowns that need investigation
-
-## Step 5: Surface Options
-- Present possible resolution paths (quick fix, deeper refactor, rollback, feature flag, etc.)
-- For each option, list pros/cons, risks, and verification steps
-- Consider required approvals or coordination
-
-## Step 6: Confirm Path Forward
-- Ask which option we should pursue
-- Summarize chosen approach, required pre-work, and success criteria
-- Plan validation steps (tests, monitoring, user sign-off)
-
-## Step 7: Next Actions & Tracking
-- Document tasks, owners, and timelines for the selected option
-- Note follow-up actions after deployment (monitoring, comms, postmortem if needed)
-- Encourage updating relevant docs/tests once resolved
-
-Let me know when you're ready to walk through the debugging flow.
+Help me debug an issue. Clarify expectations, identify gaps, and agree on a fix plan before changing code.
 
+1. **Gather Context** — If not already provided, ask for: issue description (what is happening vs what should happen), error messages/logs/screenshots, recent related changes or deployments, and scope of impact.
+2. **Clarify Reality vs Expectation** — Restate observed vs expected behavior. Confirm relevant requirements or docs that define the expectation. Define acceptance criteria for the fix.
+3. **Reproduce & Isolate** — Determine reproducibility (always, intermittent, environment-specific). Capture reproduction steps. List suspected components or modules.
+4. **Analyze Potential Causes** — Brainstorm root causes (data, config, code regressions, external dependencies). Gather supporting evidence (logs, metrics, traces). Highlight unknowns needing investigation.
+5. **Resolve** — Present resolution options (quick fix, refactor, rollback, etc.) with pros/cons and risks. Ask which option to pursue. Summarize chosen approach, pre-work, success criteria, and validation steps.

packages/cli/templates/commands/execute-plan.md

@@ -1,75 +1,11 @@
 ---
-description: Execute a feature plan interactively, guiding me through each task while referencing relevant docs and updating status.
+description: Execute a feature plan task by task.
 ---
 
-# Feature Plan Execution Assistant
-
 Help me work through a feature plan one task at a time.
 
-## Step 1: Gather Context
-Ask me for:
-- Feature name (kebab-case, e.g., `user-authentication`)
-- Brief feature/branch description
-- Relevant planning doc path (default `docs/ai/planning/feature-{name}.md`)
-- Any supporting design/implementation docs (design, requirements, implementation)
-- Current branch and latest diff summary (`git status -sb`, `git diff --stat`)
-
-## Step 2: Load the Plan
-- Request the planning doc contents or offer commands like:
-  ```bash
-  cat docs/ai/planning/feature-<name>.md
-  ```
-- Parse sections that represent task lists (look for headings + checkboxes `[ ]`, `[x]`).
-- Build an ordered queue of tasks grouped by section (e.g., Foundation, Core Features, Testing).
-
-## Step 3: Present Task Queue
-Show an overview:
-```
-### Task Queue: <Feature Name>
-1. [status] Section • Task title
-2. ...
-```
-Status legend: `todo`, `in-progress`, `done`, `blocked` (based on checkbox/notes if present).
-
-## Step 4: Interactive Task Execution
-For each task in order:
-1. Display the section/context, full bullet text, and any existing notes.
-2. Suggest relevant docs to reference (requirements/design/implementation).
-3. Ask: "Plan for this task?" Offer to outline sub-steps using the design doc.
-4. Prompt to mark status (`done`, `in-progress`, `blocked`, `skipped`) and capture short notes/next steps.
-5. Encourage code/document edits inside Cursor; offer commands/snippets when useful.
-6. If blocked, record blocker info and move task to the end or into a "Blocked" list.
-
-## Step 5: Update Planning Doc
-After each status change, generate a Markdown snippet the user can paste back into the planning doc, e.g.:
-```
-- [x] Task: Implement auth service (Notes: finished POST /auth/login, tests added)
-```
-Remind the user to keep the source doc updated.
-
-## Step 6: Check for Newly Discovered Work
-After each section, ask if new tasks were discovered. If yes, capture them in a "New Work" list with status `todo` and include in the summary.
-
-## Step 7: Session Summary
-Produce a summary table:
-```
-### Execution Summary
-- Completed: (list)
-- In Progress: (list + owners/next steps)
-- Blocked: (list + blockers)
-- Skipped / Deferred: (list + rationale)
-- New Tasks: (list)
-```
-
-## Step 8: Next Actions
-Remind the user to:
-- Update `docs/ai/planning/feature-{name}.md` with the new statuses
-- Sync related docs (requirements/design/implementation/testing) if decisions changed
-- Run `/check-implementation` to validate changes against design docs
-- Run `/writing-test` to produce unit/integration tests targeting 100% coverage
-- Run `/update-planning` to reconcile the planning doc with the latest status
-- Run `/code-review` when ready for final review
-- Run test suites relevant to completed tasks
-
----
-Let me know when you're ready to start executing the plan. Provide the feature name and planning doc first.
+1. **Gather Context** — If not already provided, ask for: feature name (kebab-case, e.g., `user-authentication`), brief feature/branch description, planning doc path (default `docs/ai/planning/feature-{name}.md`), and any supporting docs (design, requirements, implementation).
+2. **Load & Present Plan** — Read the planning doc and parse task lists (headings + checkboxes). Present an ordered task queue grouped by section, with status: `todo`, `in-progress`, `done`, `blocked`.
+3. **Interactive Task Execution** — For each task in order: display context and full bullet text, reference relevant design/requirements docs, offer to outline sub-steps before starting, prompt for status update (`done`, `in-progress`, `blocked`, `skipped`) with short notes after work, and if blocked record blocker and move to a "Blocked" list.
+4. **Update Planning Doc** — After each status change, generate a markdown snippet to paste back into the planning doc. After each section, ask if new tasks were discovered.
+5. **Session Summary** — Produce a summary: Completed, In Progress (with next steps), Blocked (with blockers), Skipped/Deferred, and New Tasks. Remind to update `docs/ai/planning/feature-{name}.md` and sync related docs if decisions changed.