ai-devkit 0.4.2 → 0.6.0

package/{templates/commands/new-requirement.toml → dist/templates/commands/new-requirement.md}

@@ -1,6 +1,13 @@
-description='''Add new feature/requirement documentation and guide me through
-the development workflow from requirements to testing.'''
-prompt='''I want to add a new feature/requirement. Please guide me through the complete development workflow:
+---
+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:
@@ -126,4 +133,4 @@ Then provide the appropriate command:
 ---
 
 **Let's start! Tell me about the feature you want to build.**
-'''
+

package/dist/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/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/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.
+

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

@@ -0,0 +1,153 @@
+---
+description: Analyze and simplify existing implementations to reduce complexity, improve maintainability, and enhance scalability.
+---
+
+# Simplify Implementation Assistant
+
+You are an expert engineer focused on reducing complexity and improving scalability. Help me simplify an existing implementation while maintaining or improving its functionality.
+
+## 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:
+- Target file(s) or component(s) to simplify
+- Current pain points (hard to understand, maintain, or extend?)
+- Performance or scalability concerns
+- Any constraints (backward compatibility, API stability, deadlines)
+- Relevant design docs or requirements
+
+If available, request the current implementation:
+```bash
+# For a specific file
+cat <file_path>
+
+# For recent changes
+git diff HEAD~5 --stat
+```
+
+## Step 2: Analyze Current Complexity
+For each target file or component:
+1. **Identify complexity sources:**
+   - Deep nesting or long functions
+   - Duplicate or redundant code
+   - Unclear abstractions or leaky interfaces
+   - Tightly coupled components
+   - Over-engineering or premature optimization
+   - Magic numbers, hardcoded values, or scattered configuration
+
+2. **Measure impact:**
+   - Lines of code that could be reduced
+   - Number of dependencies that could be removed
+   - Cognitive load for future maintainers
+
+3. **Assess scalability blockers:**
+   - Single points of failure
+   - Synchronous operations that should be async
+   - Missing caching or memoization opportunities
+   - Inefficient data structures or algorithms
+
+## Step 3: Apply Readability Principles
+
+**Core Philosophy: Good code reads like a good book — naturally, from left to right, top to bottom.**
+
+When simplifying, prioritize readability over brevity. The goal is not to write the shortest code, but to write code that communicates intent clearly.
+
+### ✅ DO: Embrace Readability
+- **Linear flow:** Code should tell a story. A reader should understand the logic by reading top-to-bottom without jumping around.
+- **Explicit over implicit:** Favor clear, explicit code over clever shortcuts that require mental decoding.
+- **Meaningful names:** Variables, functions, and classes should describe their purpose without needing comments.
+- **Consistent patterns:** Use the same patterns throughout the codebase so readers build familiarity.
+- **Appropriate abstraction level:** Each function should operate at one level of abstraction.
+- **White space and grouping:** Use blank lines to separate logical blocks, like paragraphs in prose.
+
+### ❌ AVOID: Over-Optimization for Brevity
+Reducing line count is NOT the goal. These patterns often harm readability:
+
+| Anti-Pattern | Problem | Better Alternative |
+|--------------|---------|--------------------|
+| **Nested ternaries** | `a ? b ? c : d : e` is cryptic | Use explicit if/else blocks |
+| **Chained one-liners** | `x.map().filter().reduce().flat()` is hard to debug | Break into named intermediate steps |
+| **Clever bitwise tricks** | `n & 1` instead of `n % 2 === 1` obscures intent | Use readable arithmetic unless performance-critical |
+| **Overly short variable names** | `const x = getData(); const y = x.filter(z => z.a);` | Use descriptive names like `users`, `activeUsers` |
+| **Implicit returns everywhere** | Arrow functions without braces hide complexity | Add braces and explicit returns for complex logic |
+| **Magic one-liners** | Regex or reduce expressions that "do everything" | Split into documented steps |
+| **Premature DRY** | Forcing abstraction to avoid 2-3 lines of duplication | Some duplication is clearer than wrong abstraction |
+
+### 📖 The "Reading Test"
+For each simplification, ask:
+1. Can a new team member understand this in under 30 seconds?
+2. Does the code flow naturally without needing to jump to other files?
+3. Are there any "wait, what does this do?" moments?
+4. Would this code still be clear 6 months from now?
+
+If the answer is "no" to any of these, the code needs more clarity, not more optimization.
+
+## Step 4: Propose Simplifications
+For each identified issue, suggest concrete improvements:
+
+| Category | Pattern |
+|----------|---------|
+| **Extract** | Long functions → smaller, focused functions |
+| **Consolidate** | Duplicate code → shared utilities or base classes |
+| **Flatten** | Deep nesting → early returns, guard clauses |
+| **Decouple** | Tight coupling → dependency injection, interfaces |
+| **Remove** | Dead code, unused features, excessive abstractions |
+| **Replace** | Complex logic → built-in language/library features |
+| **Defer** | Premature optimization → measure-first approach |
+
+## Step 5: Prioritize Changes
+Rank suggestions by:
+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:
+- Before/after code snippets
+- Risk level (breaking change? needs migration?)
+- Testing requirements
+- Estimated effort
+
+## Step 6: Create Simplification Plan
+Provide a structured action plan:
+
+```
+### Simplification Summary
+- Total suggestions: [count]
+- Estimated LOC reduction: [estimate]
+- Complexity score before/after: [if measurable]
+
+### Prioritized Actions
+1. **[Component/Function Name]**
+   - Issue: ...
+   - Solution: ...
+   - Risk: Low/Medium/High
+   - Effort: S/M/L
+
+2. ... (repeat)
+
+### Recommended Order
+1. [ ] [First change - safest, unlocks others]
+2. [ ] [Second change]
+3. [ ] ...
+
+### Post-Simplification Checklist
+- [ ] Run existing tests to verify no regressions
+- [ ] Add tests for any new helper functions
+- [ ] Update documentation if interfaces changed
+- [ ] Review with team before merging larger refactors
+```
+
+## Step 7: Scalability Recommendations
+Beyond immediate simplification, suggest patterns for future scalability:
+- Modular architecture improvements
+- Caching strategies
+- Async/parallel processing opportunities
+- Configuration externalization
+- Feature flags for gradual rollouts
+
+---
+Let me know when you're ready to simplify your implementation.

package/{templates/commands/update-planning.toml → dist/templates/commands/update-planning.md}

@@ -1,9 +1,16 @@
-description='''Assist in updating planning documentation to reflect current
-implementation progress for a feature.'''
-prompt='''# Planning Update Assistant
+---
+description: Assist in updating planning documentation to reflect current implementation progress for a feature.
+---
+
+# Planning Update Assistant
 
 Please help me reconcile the current implementation progress with our planning documentation.
 
+## 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/branch name and brief status
@@ -60,4 +67,4 @@ Prepare a summary paragraph to copy into the planning doc, covering:
 
 ---
 Let me know when you're ready to begin the planning update.
-'''
+

package/{templates/commands/writing-test.toml → dist/templates/commands/writing-test.md}

@@ -1,5 +1,13 @@
-description='''Add tests for a new feature'''
-prompt='''Review `docs/ai/testing/feature-{name}.md` and ensure it mirrors the base template before writing tests.
+---
+description: Add tests for a new feature.
+---
+
+Review `docs/ai/testing/feature-{name}.md` and ensure it mirrors the base template before writing tests.
+
+## 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:
@@ -43,4 +51,3 @@ For each module/function:
 - Flag follow-up tasks for deferred tests (with owners/dates)
 
 Let me know when you have the latest code changes ready; we'll write tests together until we hit 100% coverage.
-'''

package/dist/templates/env/base.md

@@ -0,0 +1,51 @@
+# AI DevKit Rules
+
+## Project Context
+This project uses ai-devkit for structured AI-assisted development. Phase documentation is located in `docs/ai/`.
+
+## Documentation Structure
+- `docs/ai/requirements/` - Problem understanding and requirements
+- `docs/ai/design/` - System architecture and design decisions (include mermaid diagrams)
+- `docs/ai/planning/` - Task breakdown and project planning
+- `docs/ai/implementation/` - Implementation guides and notes
+- `docs/ai/testing/` - Testing strategy and test cases
+- `docs/ai/deployment/` - Deployment and infrastructure docs
+- `docs/ai/monitoring/` - Monitoring and observability setup
+
+## Code Style & Standards
+- Follow the project's established code style and conventions
+- Write clear, self-documenting code with meaningful variable names
+- Add comments for complex logic or non-obvious decisions
+
+## Development Workflow
+- Review phase documentation in `docs/ai/` before implementing features
+- Keep requirements, design, and implementation docs updated as the project evolves
+- Reference the planning doc for task breakdown and priorities
+- Copy the testing template (`docs/ai/testing/README.md`) before creating feature-specific testing docs
+
+## AI Interaction Guidelines
+- When implementing features, first check relevant phase documentation
+- For new features, start with requirements clarification
+- Update phase docs when significant changes or decisions are made
+
+## Testing & Quality
+- Write tests alongside implementation
+- Follow the testing strategy defined in `docs/ai/testing/`
+- Use `/writing-test` to generate unit and integration tests targeting 100% coverage
+- Ensure code passes all tests before considering it complete
+
+## Documentation
+- Update phase documentation when requirements or design changes
+- Keep inline code comments focused and relevant
+- Document architectural decisions and their rationale
+- Use mermaid diagrams for any architectural or data-flow visuals (update existing diagrams if needed)
+- Record test coverage results and outstanding gaps in `docs/ai/testing/`
+
+## Key Commands
+When working on this project, you can run commands to:
+- Understand project requirements and goals (`review-requirements`)
+- Review architectural decisions (`review-design`)
+- Plan and execute tasks (`execute-plan`)
+- Verify implementation against design (`check-implementation`)
+- Suggest missing tests (`suggest-tests`)
+- Perform structured code reviews (`code-review`)

package/dist/templates/phases/deployment.md

@@ -0,0 +1,72 @@
+---
+phase: deployment
+title: Deployment Strategy
+description: Define deployment process, infrastructure, and release procedures
+---
+
+# Deployment Strategy
+
+## Infrastructure
+**Where will the application run?**
+
+- Hosting platform (AWS, GCP, Azure, etc.)
+- Infrastructure components (servers, databases, etc.)
+- Environment separation (dev, staging, production)
+
+## Deployment Pipeline
+**How do we deploy changes?**
+
+### Build Process
+- Build steps and commands
+- Asset compilation/optimization
+- Environment configuration
+
+### CI/CD Pipeline
+- Automated testing gates
+- Build automation
+- Deployment automation
+
+## Environment Configuration
+**What settings differ per environment?**
+
+### Development
+- Configuration details
+- Local setup
+
+### Staging
+- Configuration details
+- Testing environment
+
+### Production
+- Configuration details
+- Monitoring setup
+
+## Deployment Steps
+**What's the release process?**
+
+1. Pre-deployment checklist
+2. Deployment execution steps
+3. Post-deployment validation
+4. Rollback procedure (if needed)
+
+## Database Migrations
+**How do we handle schema changes?**
+
+- Migration strategy
+- Backup procedures
+- Rollback approach
+
+## Secrets Management
+**How do we handle sensitive data?**
+
+- Environment variables
+- Secret storage solution
+- Key rotation strategy
+
+## Rollback Plan
+**What if something goes wrong?**
+
+- Rollback triggers
+- Rollback steps
+- Communication plan
+

package/dist/templates/phases/design.md

@@ -0,0 +1,60 @@
+---
+phase: design
+title: System Design & Architecture
+description: Define the technical architecture, components, and data models
+---
+
+# System Design & Architecture
+
+## Architecture Overview
+**What is the high-level system structure?**
+
+- Include a mermaid diagram that captures the main components and their relationships. Example:
+  ```mermaid
+  graph TD
+    Client -->|HTTPS| API
+    API --> ServiceA
+    API --> ServiceB
+    ServiceA --> Database[(DB)]
+  ```
+- Key components and their responsibilities
+- Technology stack choices and rationale
+
+## Data Models
+**What data do we need to manage?**
+
+- Core entities and their relationships
+- Data schemas/structures
+- Data flow between components
+
+## API Design
+**How do components communicate?**
+
+- External APIs (if applicable)
+- Internal interfaces
+- Request/response formats
+- Authentication/authorization approach
+
+## Component Breakdown
+**What are the major building blocks?**
+
+- Frontend components (if applicable)
+- Backend services/modules
+- Database/storage layer
+- Third-party integrations
+
+## Design Decisions
+**Why did we choose this approach?**
+
+- Key architectural decisions and trade-offs
+- Alternatives considered
+- Patterns and principles applied
+
+## Non-Functional Requirements
+**How should the system perform?**
+
+- Performance targets
+- Scalability considerations
+- Security requirements
+- Reliability/availability needs
+

package/dist/templates/phases/implementation.md

@@ -0,0 +1,65 @@
+---
+phase: implementation
+title: Implementation Guide
+description: Technical implementation notes, patterns, and code guidelines
+---
+
+# Implementation Guide
+
+## Development Setup
+**How do we get started?**
+
+- Prerequisites and dependencies
+- Environment setup steps
+- Configuration needed
+
+## Code Structure
+**How is the code organized?**
+
+- Directory structure
+- Module organization
+- Naming conventions
+
+## Implementation Notes
+**Key technical details to remember:**
+
+### Core Features
+- Feature 1: Implementation approach
+- Feature 2: Implementation approach
+- Feature 3: Implementation approach
+
+### Patterns & Best Practices
+- Design patterns being used
+- Code style guidelines
+- Common utilities/helpers
+
+## Integration Points
+**How do pieces connect?**
+
+- API integration details
+- Database connections
+- Third-party service setup
+
+## Error Handling
+**How do we handle failures?**
+
+- Error handling strategy
+- Logging approach
+- Retry/fallback mechanisms
+
+## Performance Considerations
+**How do we keep it fast?**
+
+- Optimization strategies
+- Caching approach
+- Query optimization
+- Resource management
+
+## Security Notes
+**What security measures are in place?**
+
+- Authentication/authorization
+- Input validation
+- Data encryption
+- Secrets management
+

package/dist/templates/phases/monitoring.md

@@ -0,0 +1,80 @@
+---
+phase: monitoring
+title: Monitoring & Observability
+description: Define monitoring strategy, metrics, alerts, and incident response
+---
+
+# Monitoring & Observability
+
+## Key Metrics
+**What do we need to track?**
+
+### Performance Metrics
+- Response time/latency
+- Throughput/requests per second
+- Resource utilization (CPU, memory, disk)
+
+### Business Metrics
+- User engagement metrics
+- Conversion/success rates
+- Feature usage
+
+### Error Metrics
+- Error rates by type
+- Failed requests
+- Exception tracking
+
+## Monitoring Tools
+**What tools are we using?**
+
+- Application monitoring (APM)
+- Infrastructure monitoring
+- Log aggregation
+- User analytics
+
+## Logging Strategy
+**What do we log and how?**
+
+- Log levels and categories
+- Structured logging format
+- Log retention policy
+- Sensitive data handling
+
+## Alerts & Notifications
+**When and how do we get notified?**
+
+### Critical Alerts
+- Alert 1: [Condition] → [Action]
+- Alert 2: [Condition] → [Action]
+
+### Warning Alerts
+- Alert 1: [Condition] → [Action]
+- Alert 2: [Condition] → [Action]
+
+## Dashboards
+**What do we visualize?**
+
+- System health dashboard
+- Business metrics dashboard
+- Custom views per team/role
+
+## Incident Response
+**How do we handle issues?**
+
+### On-Call Rotation
+- Schedule and contacts
+- Escalation path
+
+### Incident Process
+1. Detection and triage
+2. Investigation and diagnosis
+3. Resolution and mitigation
+4. Post-mortem and learning
+
+## Health Checks
+**How do we verify system health?**
+
+- Endpoint health checks
+- Dependency checks
+- Automated smoke tests
+

package/dist/templates/phases/planning.md

@@ -0,0 +1,60 @@
+---
+phase: planning
+title: Project Planning & Task Breakdown
+description: Break down work into actionable tasks and estimate timeline
+---
+
+# Project Planning & Task Breakdown
+
+## Milestones
+**What are the major checkpoints?**
+
+- [ ] Milestone 1: [Description]
+- [ ] Milestone 2: [Description]
+- [ ] Milestone 3: [Description]
+
+## Task Breakdown
+**What specific work needs to be done?**
+
+### Phase 1: Foundation
+- [ ] Task 1.1: [Description]
+- [ ] Task 1.2: [Description]
+
+### Phase 2: Core Features
+- [ ] Task 2.1: [Description]
+- [ ] Task 2.2: [Description]
+
+### Phase 3: Integration & Polish
+- [ ] Task 3.1: [Description]
+- [ ] Task 3.2: [Description]
+
+## Dependencies
+**What needs to happen in what order?**
+
+- Task dependencies and blockers
+- External dependencies (APIs, services, etc.)
+- Team/resource dependencies
+
+## Timeline & Estimates
+**When will things be done?**
+
+- Estimated effort per task/phase
+- Target dates for milestones
+- Buffer for unknowns
+
+## Risks & Mitigation
+**What could go wrong?**
+
+- Technical risks
+- Resource risks
+- Dependency risks
+- Mitigation strategies
+
+## Resources Needed
+**What do we need to succeed?**
+
+- Team members and roles
+- Tools and services
+- Infrastructure
+- Documentation/knowledge
+