ai-devkit 0.2.0

package/templates/env/cursor/commands/update-planning.md

@@ -0,0 +1,61 @@
+# Planning Update Assistant
+
+Please help me reconcile the current implementation progress with our planning documentation.
+
+## 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/templates/env/cursor/commands/writing-test.md

@@ -0,0 +1,44 @@
+Review `docs/ai/testing/feature-{name}.md` and ensure it mirrors the base template before writing tests.
+
+## 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/templates/env/cursor/rules/ai-devkit.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/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/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/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/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/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
+

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