ai-devkit 0.4.2 → 0.6.0

package/dist/templates/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/dist/templates/templates/commands/update-planning.md

@@ -0,0 +1,70 @@
+---
+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
+- Tasks completed since last update
+- Any new tasks discovered
+- Current blockers or risks
+- Relevant planning docs (e.g., `docs/ai/planning/feature-{name}.md`)
+
+## Step 2: Review Planning Doc
+If a planning doc exists:
+- Summarize existing milestones and task breakdowns
+- Note expected sequencing and dependencies
+- Identify outstanding tasks in the plan
+
+## Step 3: Reconcile Progress
+For each planned task:
+- Mark status (done / in progress / blocked / not started)
+- Note actual work completed vs. planned scope
+- Record blockers or changes in approach
+- Identify tasks that were skipped or added
+
+## Step 4: Update Task List
+Help me produce an updated checklist such as:
+```
+### Current Status: [Feature Name]
+
+#### Done
+- [x] Task A - short note on completion or link to commit/pr
+- [x] Task B
+
+#### In Progress
+- [ ] Task C - waiting on [dependency]
+
+#### Blocked
+- [ ] Task D - blocked by [issue/owner]
+
+#### Newly Discovered Work
+- [ ] Task E - reason discovered
+- [ ] Task F - due by [date]
+```
+
+## Step 5: Next Steps & Priorities
+- Suggest the next 2-3 actionable tasks
+- Highlight risky areas needing attention
+- Recommend coordination (design changes, stakeholder sync, etc.)
+- List documentation updates needed
+
+## Step 6: Summary for Planning Doc
+Prepare a summary paragraph to copy into the planning doc, covering:
+- Current state and progress
+- Major risks/blockers
+- Upcoming focus items
+- Any changes to scope or timeline
+
+---
+Let me know when you're ready to begin the planning update.
+

package/dist/templates/templates/commands/writing-test.md

@@ -0,0 +1,53 @@
+---
+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:
+- Feature name and branch
+- Summary of what changed (link to design & requirements docs)
+- Target environment (backend, frontend, full-stack)
+- Existing automated test suites (unit, integration, E2E)
+- Any flaky or slow tests to avoid
+
+## Step 2: Analyze Testing Template
+- Identify required sections from `docs/ai/testing/feature-{name}.md` (unit, integration, manual verification, coverage targets)
+- Confirm success criteria and edge cases from requirements & design docs
+- Note any mocks/stubs or fixtures already available
+
+## Step 3: Unit Tests (Aim for 100% coverage)
+For each module/function:
+1. List behavior scenarios (happy path, edge cases, error handling)
+2. Generate concrete test cases with assertions and inputs
+3. Reference existing utilities/mocks to accelerate implementation
+4. Provide pseudocode or actual test snippets
+5. Highlight potential missing branches preventing full coverage
+
+## Step 4: Integration Tests
+1. Identify critical flows that span multiple components/services
+2. Define setup/teardown steps (databases, APIs, queues)
+3. Outline test cases validating interaction boundaries, data contracts, and failure modes
+4. Suggest instrumentation/logging to debug failures
+
+## Step 5: Coverage Strategy
+- Recommend tooling commands (e.g., `npm run test -- --coverage`)
+- Call out files/functions that still need coverage and why
+- Suggest additional tests if coverage <100%
+
+## Step 6: Manual & Exploratory Testing
+- Propose manual test checklist covering UX, accessibility, and error handling
+- Identify exploratory scenarios or chaos/failure injection tests if relevant
+
+## Step 7: Update Documentation & TODOs
+- Summarize which tests were added or still missing
+- Update `docs/ai/testing/feature-{name}.md` sections with links to test files and results
+- 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/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/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/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/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/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/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
+