chore: add commands to root

Author: codeaholicguy

commands/capture-knowledge.md

@@ -0,0 +1,12 @@
+---
+description: Document a code entry point in knowledge docs.
+---
+
+Guide me through creating a structured understanding of a code entry point and saving it to the knowledge docs.
+
+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.

commands/check-implementation.md

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

commands/code-review.md

@@ -0,0 +1,11 @@
+---
+description: Pre-push code review against design docs.
+---
+
+Perform a local code review **before** pushing changes.
+
+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.

commands/debug.md

@@ -0,0 +1,11 @@
+---
+description: Debug an issue with structured root-cause analysis before changing code.
+---
+
+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.

commands/execute-plan.md

@@ -0,0 +1,11 @@
+---
+description: Execute a feature plan task by task.
+---
+
+Help me work through a feature plan one task at a time.
+
+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.

commands/new-requirement.md

@@ -0,0 +1,18 @@
+---
+description: Scaffold feature documentation from requirements through planning.
+---
+
+Guide me through adding a new feature, from requirements documentation to implementation readiness.
+
+1. **Capture Requirement** — If not already provided, ask for: feature name (kebab-case, e.g., `user-authentication`), what problem it solves and who will use it, and key user stories.
+2. **Create Feature Documentation Structure** — Copy each template's content (preserving YAML frontmatter and section headings) into feature-specific files:
+   - `docs/ai/requirements/README.md` → `docs/ai/requirements/feature-{name}.md`
+   - `docs/ai/design/README.md` → `docs/ai/design/feature-{name}.md`
+   - `docs/ai/planning/README.md` → `docs/ai/planning/feature-{name}.md`
+   - `docs/ai/implementation/README.md` → `docs/ai/implementation/feature-{name}.md`
+   - `docs/ai/testing/README.md` → `docs/ai/testing/feature-{name}.md`
+3. **Requirements Phase** — Fill out `docs/ai/requirements/feature-{name}.md`: problem statement, goals/non-goals, user stories, success criteria, constraints, open questions.
+4. **Design Phase** — Fill out `docs/ai/design/feature-{name}.md`: architecture changes, data models, API/interfaces, components, design decisions, security and performance considerations.
+5. **Planning Phase** — Fill out `docs/ai/planning/feature-{name}.md`: task breakdown with subtasks, dependencies, effort estimates, implementation order, risks.
+6. **Documentation Review** — Run `/review-requirements` and `/review-design` to validate the drafted docs.
+7. **Next Steps** — This command focuses on documentation. When ready to implement, use `/execute-plan`. Generate a PR description covering: summary, requirements doc link, key changes, test status, and a readiness checklist.

commands/remember.md

@@ -0,0 +1,10 @@
+---
+description: Store reusable guidance in the knowledge memory service.
+---
+
+When I say "remember this" or want to save a reusable rule, help me store it in the knowledge memory service.
+
+1. **Capture Knowledge** — If not already provided, ask for: a short explicit title (5-12 words), detailed content (markdown, examples encouraged), optional tags (keywords like "api", "testing"), and optional scope (`global`, `project:<name>`, `repo:<name>`). If vague, ask follow-ups to make it specific and actionable.
+2. **Validate Quality** — Ensure it is specific and reusable (not generic advice). Avoid storing secrets or sensitive data.
+3. **Store** — Call `memory.storeKnowledge` with title, content, tags, scope. If MCP tools are unavailable, use `npx ai-devkit memory store` instead.
+4. **Confirm** — Summarize what was saved and offer to store more knowledge if needed.

commands/review-design.md

@@ -0,0 +1,15 @@
+---
+description: Review feature design for completeness.
+---
+
+Review the design documentation in docs/ai/design/feature-{name}.md (and the project-level README if relevant). Summarize:
+
+- Architecture overview (ensure mermaid diagram is present and accurate)
+- Key components and their responsibilities
+- Technology choices and rationale
+- Data models and relationships
+- API/interface contracts (inputs, outputs, auth)
+- Major design decisions and trade-offs
+- Non-functional requirements that must be preserved
+
+Highlight any inconsistencies, missing sections, or diagrams that need updates.

commands/review-requirements.md

@@ -0,0 +1,13 @@
+---
+description: Review feature requirements for completeness.
+---
+
+Review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize:
+
+- Core problem statement and affected users
+- Goals, non-goals, and success criteria
+- Primary user stories & critical flows
+- Constraints, assumptions, open questions
+- Any missing sections or deviations from the template
+
+Identify gaps or contradictions and suggest clarifications.

commands/simplify-implementation.md

@@ -0,0 +1,10 @@
+---
+description: Simplify existing code to reduce complexity.
+---
+
+Help me simplify an existing implementation while maintaining or improving its functionality.
+
+1. **Gather Context** — If not already provided, ask for: target file(s) or component(s) to simplify, current pain points (hard to understand, maintain, or extend?), performance or scalability concerns, constraints (backward compatibility, API stability, deadlines), and relevant design docs or requirements.
+2. **Analyze Current Complexity** — For each target: identify complexity sources (deep nesting, duplication, unclear abstractions, tight coupling, over-engineering, magic values), assess cognitive load for future maintainers, and identify scalability blockers (single points of failure, sync-where-async-needed, missing caching, inefficient algorithms).
+3. **Propose Simplifications** — Prioritize readability over brevity — apply the 30-second test: can a new team member understand each change quickly? For each issue, suggest concrete improvements (extract, consolidate, flatten, decouple, remove dead code, replace with built-ins). Provide before/after snippets.
+4. **Prioritize & Plan** — Rank by impact vs risk: (1) high impact, low risk — do first, (2) high impact, higher risk — plan carefully, (3) low impact, low risk — quick wins if time permits, (4) low impact, high risk — skip or defer. For each change specify risk level, testing requirements, and effort. Produce a prioritized action plan with recommended execution order.