ai-devkit 0.4.2 → 0.6.0

package/dist/templates/phases/requirements.md

@@ -0,0 +1,51 @@
+---
+phase: requirements
+title: Requirements & Problem Understanding
+description: Clarify the problem space, gather requirements, and define success criteria
+---
+
+# Requirements & Problem Understanding
+
+## Problem Statement
+**What problem are we solving?**
+
+- Describe the core problem or pain point
+- Who is affected by this problem?
+- What is the current situation/workaround?
+
+## Goals & Objectives
+**What do we want to achieve?**
+
+- Primary goals
+- Secondary goals
+- Non-goals (what's explicitly out of scope)
+
+## User Stories & Use Cases
+**How will users interact with the solution?**
+
+- As a [user type], I want to [action] so that [benefit]
+- Key workflows and scenarios
+- Edge cases to consider
+
+## Success Criteria
+**How will we know when we're done?**
+
+- Measurable outcomes
+- Acceptance criteria
+- Performance benchmarks (if applicable)
+
+## Constraints & Assumptions
+**What limitations do we need to work within?**
+
+- Technical constraints
+- Business constraints
+- Time/budget constraints
+- Assumptions we're making
+
+## Questions & Open Items
+**What do we still need to clarify?**
+
+- Unresolved questions
+- Items requiring stakeholder input
+- Research needed
+

package/dist/templates/phases/testing.md

@@ -0,0 +1,81 @@
+---
+phase: testing
+title: Testing Strategy
+description: Define testing approach, test cases, and quality assurance
+---
+
+# Testing Strategy
+
+## Test Coverage Goals
+**What level of testing do we aim for?**
+
+- Unit test coverage target (default: 100% of new/changed code)
+- Integration test scope (critical paths + error handling)
+- End-to-end test scenarios (key user journeys)
+- Alignment with requirements/design acceptance criteria
+
+## Unit Tests
+**What individual components need testing?**
+
+### Component/Module 1
+- [ ] Test case 1: [Description] (covers scenario / branch)
+- [ ] Test case 2: [Description] (covers edge case / error handling)
+- [ ] Additional coverage: [Description]
+
+### Component/Module 2
+- [ ] Test case 1: [Description]
+- [ ] Test case 2: [Description]
+- [ ] Additional coverage: [Description]
+
+## Integration Tests
+**How do we test component interactions?**
+
+- [ ] Integration scenario 1
+- [ ] Integration scenario 2
+- [ ] API endpoint tests
+- [ ] Integration scenario 3 (failure mode / rollback)
+
+## End-to-End Tests
+**What user flows need validation?**
+
+- [ ] User flow 1: [Description]
+- [ ] User flow 2: [Description]
+- [ ] Critical path testing
+- [ ] Regression of adjacent features
+
+## Test Data
+**What data do we use for testing?**
+
+- Test fixtures and mocks
+- Seed data requirements
+- Test database setup
+
+## Test Reporting & Coverage
+**How do we verify and communicate test results?**
+
+- Coverage commands and thresholds (`npm run test -- --coverage`)
+- Coverage gaps (files/functions below 100% and rationale)
+- Links to test reports or dashboards
+- Manual testing outcomes and sign-off
+
+## Manual Testing
+**What requires human validation?**
+
+- UI/UX testing checklist (include accessibility)
+- Browser/device compatibility
+- Smoke tests after deployment
+
+## Performance Testing
+**How do we validate performance?**
+
+- Load testing scenarios
+- Stress testing approach
+- Performance benchmarks
+
+## Bug Tracking
+**How do we manage issues?**
+
+- Issue tracking process
+- Bug severity levels
+- Regression testing strategy
+

package/dist/templates/templates/commands/capture-knowledge.md

@@ -0,0 +1,55 @@
+---
+description: Capture structured knowledge about a code entry point and save it to the knowledge docs.
+---
+
+# Knowledge Capture Assistant
+
+Guide me through creating a structured understanding of a code entry point and saving it to the knowledge docs.
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+## 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.

package/dist/templates/templates/commands/check-implementation.md

@@ -0,0 +1,30 @@
+---
+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:
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+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
+
+4. Summarize findings with recommended next steps.
+

package/dist/templates/templates/commands/code-review.md

@@ -0,0 +1,90 @@
+---
+description: Perform a local code review before pushing changes, ensuring alignment with design docs and best practices.
+---
+
+# Local Code Review Assistant
+
+You are helping me perform a local code review **before** I push changes. Please follow this structured workflow.
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+## 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.

package/dist/templates/templates/commands/debug.md

@@ -0,0 +1,54 @@
+---
+description: Guide me through debugging a code issue by clarifying expectations, identifying gaps, and agreeing on a fix plan 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.
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+## 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.
+

package/dist/templates/templates/commands/execute-plan.md

@@ -0,0 +1,80 @@
+---
+description: Execute a feature plan interactively, guiding me through each task while referencing relevant docs and updating status.
+---
+
+# Feature Plan Execution Assistant
+
+Help me work through a feature plan one task at a time.
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+## 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.

package/dist/templates/templates/commands/new-requirement.md

@@ -0,0 +1,136 @@
+---
+description: Add new feature/requirement documentation and guide me through the development workflow from requirements to testing.
+---
+
+I want to add a new feature/requirement. Please guide me through the complete development workflow:
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+## Step 1: Capture Requirement
+First, ask me:
+- What is the feature name? (e.g., "user-authentication", "payment-integration")
+- What problem does it solve?
+- Who will use it?
+- What are the key user stories?
+
+## Step 2: Create Feature Documentation Structure
+Once I provide the requirement, create the following files (copy the existing template content so sections/frontmatter match exactly):
+- Start from `docs/ai/requirements/README.md` → save as `docs/ai/requirements/feature-{name}.md`
+- Start from `docs/ai/design/README.md` → save as `docs/ai/design/feature-{name}.md`
+- Start from `docs/ai/planning/README.md` → save as `docs/ai/planning/feature-{name}.md`
+- Start from `docs/ai/implementation/README.md` → save as `docs/ai/implementation/feature-{name}.md`
+- Start from `docs/ai/testing/README.md` → save as `docs/ai/testing/feature-{name}.md`
+
+Ensure the YAML frontmatter and section headings remain identical to the templates before filling in feature-specific content.
+
+## Step 3: Requirements Phase
+Help me fill out `docs/ai/requirements/feature-{name}.md`:
+- Clarify the problem statement
+- Define goals and non-goals
+- Write detailed user stories
+- Establish success criteria
+- Identify constraints and assumptions
+- List open questions
+
+## Step 4: Design Phase
+Guide me through `docs/ai/design/feature-{name}.md`:
+- Propose system architecture changes needed
+- Define data models/schema changes
+- Design API endpoints or interfaces
+- Identify components to create/modify
+- Document key design decisions
+- Note security and performance considerations
+
+## Step 5: Planning Phase
+Help me break down work in `docs/ai/planning/feature-{name}.md`:
+- Create task breakdown with subtasks
+- Identify dependencies (on other features, APIs, etc.)
+- Estimate effort for each task
+- Suggest implementation order
+- Identify risks and mitigation strategies
+
+## Step 6: Documentation Review (Chained Commands)
+Once the docs above are drafted, run the following commands to tighten them up:
+- `/review-requirements` to validate the requirements doc for completeness and clarity
+- `/review-design` to ensure the design doc aligns with requirements and highlights key decisions
+
+(If you are using Claude Code, reference the `review-requirements` and `review-design` commands instead.)
+
+## Step 7: Implementation Phase (Deferred)
+This command focuses on documentation only. Actual implementation happens later via `/execute-plan`.
+For each task in the plan:
+1. Review the task requirements and design
+2. Ask me to confirm I'm starting this task
+3. Guide implementation with reference to design docs
+4. Suggest code structure and patterns
+5. Help with error handling and edge cases
+6. Update `docs/ai/implementation/feature-{name}.md` with notes
+
+## Step 8: Testing Phase
+Guide testing in `docs/ai/testing/feature-{name}.md`:
+- Draft unit test cases with `/writing-test`
+- Draft integration test scenarios with `/writing-test`
+- Recommend manual testing steps
+- Help write test code
+- Verify all success criteria are testable
+
+## Step 9: Local Testing & Verification
+Guide me through:
+1. Running all tests locally
+2. Manual testing checklist
+3. Reviewing against requirements
+4. Checking design compliance
+5. Preparing for code review (diff summary, list of files, design references)
+
+## Step 10: Local Code Review (Optional but recommended)
+Before pushing, ask me to run `/code-review` with the modified file list and relevant docs.
+
+## Step 11: Implementation Execution Reminder
+When ready to implement, run `/execute-plan` to work through the planning doc tasks interactively. That command will orchestrate implementation, testing, and follow-up documentation.
+
+## Step 12: Create Merge/Pull Request
+Provide the MR/PR description:
+```markdown
+## Feature: [Feature Name]
+
+### Summary
+[Brief description of what this feature does]
+
+### Requirements
+- Documented in: `docs/ai/requirements/feature-{name}.md`
+- Related to: [issue/ticket number if applicable]
+
+### Changes
+- [List key changes]
+- [List new files/components]
+- [List modified files]
+
+### Design
+- Architecture: [Link to design doc section]
+- Key decisions: [Brief summary]
+
+### Testing
+- Unit tests: [coverage/status]
+- Integration tests: [status]
+- Manual testing: Completed
+- Test documentation: `docs/ai/testing/feature-{name}.md`
+
+### Checklist
+- [ ] Code follows project standards
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented if any)
+- [ ] Ready for review
+```
+
+Then provide the appropriate command:
+- **GitHub**: `gh pr create --title "feat: [feature-name]" --body-file pr-description.md`
+- **GitLab**: `glab mr create --title "feat: [feature-name]" --description "$(cat mr-description.md)"`
+
+---
+
+**Let's start! Tell me about the feature you want to build.**
+

package/dist/templates/templates/commands/remember.md

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

package/dist/templates/templates/commands/review-design.md

@@ -0,0 +1,21 @@
+---
+description: Review the design documentation for a feature to ensure completeness and accuracy.
+---
+
+Review the design documentation in docs/ai/design/feature-{name}.md (and the project-level README if relevant). Summarize:
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+- 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.
+

package/dist/templates/templates/commands/review-requirements.md

@@ -0,0 +1,19 @@
+---
+description: Review the requirements documentation for a feature to ensure completeness and alignment with project standards.
+---
+
+Please review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize:
+
+## Memory (use when helpful)
+- If you need clarification or project conventions, query `memory.searchKnowledge` with a brief task description, tags, and scope.
+- If I ask to save reusable guidance, run `/remember` (or call `memory.storeKnowledge`).
+- If MCP tools are unavailable, use `ai-devkit memory search` or `ai-devkit memory store`.
+
+- 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.
+