ai-qakit 1.0.0

package/templates/.cursor/commands/devkit/spec/plan.md

@@ -0,0 +1,317 @@
+---
+description: Research, analyze, and create implementation plan for a task
+---
+
+# Create Plan
+
+Research and create a detailed implementation plan for an existing task.
+
+## Usage
+
+`@spec/plan [task-id]`
+
+**Pathing rule:** Always generate absolute paths rooted at `./.cursor/...` (e.g., `./.cursor/tasks/SUDOKU-004/requirements/input.md`) to avoid wrong lookups.
+
+## Workflow
+
+### Phase 1: Validate Task
+
+1. Verify `./.cursor/tasks/[task-id]/` exists
+2. If not found: "Run `@spec/task` first"
+3. Read `./.cursor/tasks/[task-id]/requirements/`
+
+**IMPORTANT** All the requirements can be found in the `./.cursor/tasks/[task-id]/requirements/` directory.
+
+### Phase 1.5: Detect Platform & User Preferences
+
+1. **Detect coding platform** (auto-detect, do not ask user)
+   - Analyze source code to determine platform type:
+     - Check `package.json` dependencies (React/Vue/Angular/Next.js = frontend; Express/NestJS/Fastify = backend)
+     - Check for frontend indicators: `src/components/`, `src/pages/`, `vite.config.*`, `next.config.*`, `.tsx/.jsx` files
+     - Check for backend indicators: `src/controllers/`, `src/routes/`, `src/services/`, `Dockerfile`, `docker-compose.*`
+     - Check for Python backend: `requirements.txt`, `pyproject.toml`, FastAPI/Django/Flask imports
+     - Check for Java/Kotlin backend: `pom.xml`, `build.gradle`, Spring Boot annotations
+   - Determine platform: **frontend** | **backend** | **fullstack** (if both indicators present)
+
+2. **Detect API development approach** (auto-detect, do not ask user)
+   - Analyze project to determine API approach:
+     - **Schema-first indicators** (OpenAPI/Swagger first, then generate code):
+       - OpenAPI spec files: `openapi.yaml`, `openapi.json`, `swagger.yaml`, `swagger.json`, `api-spec.*`
+       - Code generation config: `openapitools.json`, `.openapi-generator/`, `nswag.json`
+       - Generator dependencies: `@openapitools/openapi-generator-cli`, `openapi-typescript`, `swagger-codegen`, `nswag`
+       - Generated code directories: `generated/`, `api-client/`, `src/generated/`, `__generated__/`
+       - Build scripts containing: `openapi-generator`, `swagger-codegen`, `nswag`
+     - **Code-first indicators** (write code, generate spec from annotations):
+       - Swagger decorators: `@ApiProperty`, `@ApiOperation`, `@ApiResponse` (NestJS)
+       - OpenAPI annotations in code: `@OpenAPI`, `@Schema` (Java/Spring)
+       - Doc generation tools: `swagger-jsdoc`, `tsoa`, `springdoc-openapi`
+   - Determine approach: **schema-first** | **code-first** | **no-api** (if no API indicators)
+   - **CRITICAL**: Store in plan metadata - implementation MUST respect this approach
+
+3. **NO TESTS**: Do not include unit tests, integration tests, or E2E tests in the plan (testing is handled separately via `@spec/test`)
+
+### Phase 2: Research
+
+- Read and follow `./.cursor/rules/researcher.mdc` (as researcher) and run a deep-dive workflow: online search + repo context.
+- All the requirements can be found in the `./.cursor/tasks/[task-id]/requirements/` directory.
+- Use `researcher` (up to 5 times) to gather authoritative patterns, security guidance, performance practices, and similar implementations; include targeted internet searches for best practices, JWT rotation, secure cookies, and rate limiting.
+- Save all findings (summaries + links) to `./.cursor/tasks/[task-id]/research/`, clearly citing sources and mapping insights to requirements.
+
+### Phase 3: Analyze Documentation
+
+Read:
+- `codebase-summary.md`
+- `code-standards.md`
+- `system-architecture.md`
+- `project-overview-pdr.md`
+- `technical-documents.md`
+- `./docs/` directory
+- Root `*.md` files
+- Key `README.md` files
+
+If `codebase-summary.md` unavailable or >3 days old:
+- Use `@scout` to search codebase
+
+### Phase 3.5: CRITICAL - Identify Reusable Resources
+
+**Scout for existing code to REUSE before planning new implementations:**
+- Existing utils, helpers, services that provide similar functionality
+- Existing components, modules that can be extended
+- Existing patterns and conventions in the codebase
+
+**Rules:**
+- **DO NOT create duplicates** - if similar code exists, plan to extend/modify it
+- **Follow existing patterns** - maintain consistency with codebase conventions
+- Document all reusable resources in the plan for implementers to use
+
+### Phase 4: Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set
+
+### Phase 5: Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### Phase 6: Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### Phase 7: Create Plan
+
+- Read and follow `./.cursor/rules/planner.mdc` (as planner)
+- Use `planner` agents for planning
+- When defining phases, ensure the final phase is a task-wide review covering: (a) review all implemented code, (b) verify created files achieve at least 99% code coverage, and (c) confirm all tests pass and the app starts successfully.
+- Immediately after the review phase, add a **documentation phase** that creates and/or updates comprehensive feature docs under `/docs` (or relevant existing docs) to reflect the new functionality. This phase must produce meaningful documentation artifacts and refresh existing related documents with the latest task details.
+
+Save to `./.cursor/tasks/[task-id]/plan/`:
+
+```
+plan/
+├── reports/
+│   └── *.md              # Analysis reports
+├── scout/
+│   └── *.md              # Scout reports
+├── plan.md               # Overview (<80 lines)
+├── phase-01-name.md
+├── phase-02-name.md
+└── ...
+```
+
+### Phase 8: Review
+
+Ask user to review the plan before proceeding.
+- After plan approval and files are saved, update `./.cursor/tasks/<task-id>/README.md` to mark `Plan created` as completed.
+
+## Plan File Format
+
+### plan.md (Overview)
+
+```markdown
+---
+platform: frontend | backend | fullstack
+api-approach: schema-first | code-first | no-api
+openapi-spec: path/to/openapi.yaml  # if schema-first
+generator-config: path/to/config    # if schema-first
+---
+
+# Implementation Plan: [Task]
+
+## Summary
+[Brief description]
+
+## Phases
+
+| # | Phase | Status | Progress |
+|---|-------|--------|----------|
+| 1 | [name] | pending | 0% |
+| 2 | [name] | pending | 0% |
+
+## Requirements
+- See: `../requirements/functional.md`
+- See: `../requirements/non-functional.md`
+
+## Timeline
+[Estimated duration]
+
+## Dependencies
+- [dep 1]
+- [dep 2]
+```
+
+### phase-XX-name.md (Detail)
+
+```markdown
+# Phase [X]: [Name]
+
+## Context
+- Plan: `./plan.md`
+- Requirements: `../requirements/...`
+
+## Overview
+- Date: YYYY-MM-DD
+- Priority: [high/medium/low]
+- Status: pending
+- Review: pending
+
+## Key Insights
+- [insight 1]
+
+## Requirements
+- See: `../requirements/...`
+
+## Architecture
+[Design decisions]
+
+## Related Files
+- Modify: `path/to/file`
+- Create: `path/to/file`
+
+## Implementation Steps
+1. [ ] Step 1
+2. [ ] Step 2
+
+## Success Criteria
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+## Risks
+| Risk | Mitigation |
+|------|------------|
+
+## Security
+- [consideration]
+
+## Next Steps
+- [what comes after]
+```
+
+### API Implementation Patterns
+
+**Schema-First Projects** (`api-approach: schema-first`):
+Phases involving API changes MUST follow this order:
+1. **OpenAPI Spec Update** - Modify spec file first (endpoints, schemas, DTOs)
+2. **Code Generation** - Run generator command, verify generated types
+3. **Implementation** - Use ONLY generated DTOs/types, NEVER create manual DTOs
+
+**Code-First Projects** (`api-approach: code-first`):
+1. **Implementation** - Write code with `@ApiProperty`, `@ApiOperation` decorators
+2. **Spec Generation** - Run spec generation to update documentation
+
+## Output
+
+```
+════════════════════════════════════════
+✅ PLAN CREATED: [task-id]
+════════════════════════════════════════
+
+LOCATION: ./.cursor/tasks/[task-id]/plan/
+
+PHASES:
+  1. [phase-01-name]
+  2. [phase-02-name]
+  3. [phase-03-name]
+
+RESEARCH: [X] reports saved
+
+NEXT STEPS:
+  1. Review the plan in ./.cursor/tasks/[task-id]/plan/
+  2. If changes needed, run @spec/update-plan [task-id] [description]
+  3. Run @spec/implement [task-id] to start implementation
+
+Need to modify the plan? Run:
+  → @spec/update-plan [task-id] [describe changes]
+
+Ready to implement? Run:
+  → @spec/implement [task-id]
+════════════════════════════════════════
+```
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+- **NO TESTS** (do not include unit/integration/E2E tests in the plan - testing handled separately via `@spec/test`)
+
+## Important Notes
+
+- **CRITICAL:** You MUST strictly follow `./docs/development-rules.md` in ALL circumstances. This is NON-NEGOTIABLE.
+
+## Context
+
+$ARGUMENTS

package/templates/.cursor/commands/devkit/spec/task.md

@@ -0,0 +1,150 @@
+---
+description: Create a new task folder structure
+---
+
+<!--
+Usage: @spec/task [task-id]
+Example: @spec/task ABC-123
+Example: @spec/task TICKET-456
+Example: @spec/task feature-user-auth
+-->
+
+## Your Mission
+
+Initialize task folder structure for: **$ARGUMENTS**
+
+This command ONLY creates the folder structure. No research, planning, or implementation.
+
+## Workflow
+
+### Step 1: Get Task ID
+
+- If task ID not provided, ask user for task ID
+- Task ID should be kebab-case or ticket format (e.g., `ABC-123`, `feature-name`)
+
+### Step 2: Check Existing Task
+
+- Check if `./.cursor/tasks/[task-id]/` already exists
+- If exists, inform user and ask if they want to reset or continue with existing
+
+### Step 3: Check Git History for Prior Implementation
+
+Search git history for any prior work related to this task:
+
+```bash
+# Search commit messages for task ID
+git log --oneline --all --grep="[task-id]" 2>/dev/null
+
+# Search for task ID in code comments/files
+git log --oneline --all -S "[task-id]" 2>/dev/null
+```
+
+If prior implementation found:
+1. Create `./.cursor/tasks/[task-id]/requirements/existing-implementation.md`
+2. Document:
+   - Related commits (hash, message, date)
+   - Files that were modified
+   - Brief summary of what was already implemented
+   - Any related branches found
+
+### Step 4: Create Folder Structure
+
+```
+./.cursor/tasks/[task-id]/
+├── README.md
+├── requirements/
+│   ├── 01-functional.md     (empty template)
+│   ├── 02-non-functional.md (empty template)
+│   └── existing-implementation.md  (only if prior work found)
+├── research/                (empty, populated by capture-requirement/brainstorm)
+└── plan/                    (empty, populated by plan command)
+```
+
+### Step 5: Create README.md
+
+```markdown
+# Task: [task-id]
+
+**Created:** YYYY-MM-DD
+**Status:** Initialized
+
+## Overview
+[To be filled during brainstorming/capture-requirement]
+
+## Quick Links
+- Requirements: `./requirements/`
+- Research: `./research/`
+- Plan: `./plan/`
+
+## Next Steps
+1. Run `@spec/brainstorm [task-id]` to explore solutions
+2. Run `@spec/capture-requirement [task-id]` to document requirements
+3. Run `@spec/plan [task-id]` to create implementation plan
+```
+
+### Step 6: Create Empty Templates
+
+**requirements/01-functional.md:**
+```markdown
+# Functional Requirements: [task-id]
+
+<!-- Add functional requirements here -->
+<!-- Use @spec/brainstorm or @spec/capture-requirement to populate -->
+```
+
+**requirements/02-non-functional.md:**
+```markdown
+# Non-Functional Requirements: [task-id]
+
+<!-- Add non-functional requirements here -->
+<!-- Performance, security, scalability, etc. -->
+```
+
+### Step 7: Summary Output
+
+```
+════════════════════════════════════════════════════════════════════
+                    📁 TASK INITIALIZED
+════════════════════════════════════════════════════════════════════
+
+TASK ID: [task-id]
+LOCATION: ./.cursor/tasks/[task-id]/
+
+STRUCTURE CREATED:
+  ✅ README.md
+  ✅ requirements/01-functional.md
+  ✅ requirements/02-non-functional.md
+  [✅ requirements/existing-implementation.md] (if prior work found)
+  📁 research/    (empty)
+  📁 plan/        (empty)
+
+PRIOR IMPLEMENTATION: [Found X commits | None found]
+
+NEXT STEPS:
+  Option A: AI-Assisted (If you're not sure about requirements)
+    → @spec/brainstorm [task-id]         # Let AI explore solutions and ideas
+
+  Option B: Manual First
+    → Add requirements manually to ./requirements/ folder
+    → Then @spec/update-requirement [task-id]  #  AI validates & enhances your requirements
+    → Or @spec/capture-requirement [task-id]   # AI researches & futher enhances requirements (more detailed)
+
+  Then Continue With:
+    → @spec/plan [task-id]               # Create implementation plan
+
+════════════════════════════════════════════════════════════════════
+```
+
+## Important Notes
+
+- **CRITICAL:** `@docs/init` MUST be run before creating any task. No exceptions.
+- **IMPORTANT:** Don't create git-keep files.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** Ensure token efficiency while maintaining high quality.
+- **IMPORTANT**: **Do not** start implementing.
+- **DO NOT** do any research during this phase
+- **DO NOT** do any planning during this phase
+- **DO NOT** start implementing
+- **DO NOT** create .gitkeep files
+- Only create folder structure and basic templates
+- If prior implementation exists, document it but don't analyze deeply

package/templates/.cursor/commands/devkit/spec/test.md

@@ -0,0 +1,203 @@
+# Create Comprehensive Tests
+
+Create and run tests with 100% code coverage for an existing task, processing files one-by-one.
+
+## Usage
+```
+@spec/test [task-id]
+```
+
+## Examples
+```
+@spec/test ABC-123
+@spec/test feature-user-auth
+```
+
+**Requires:** Task must exist with implementation in `./.cursor/tasks/[task-id]/`
+
+## Your Mission
+
+Create comprehensive tests for task: **$ARGUMENTS**
+
+Process files **ONE BY ONE** - achieve 100% coverage per file before moving to next.
+
+---
+
+## Phase 0: Validate Task & Collect Files
+
+1. If task-id not provided, ask user for it
+2. Verify `./.cursor/tasks/[task-id]/` exists
+3. If not found: "Task not found. Run `@spec/task` first."
+4. Verify `./.cursor/tasks/[task-id]/plan/plan.md` exists
+5. If not found: "Plan not found. Run `@spec/plan` first."
+6. **Collect all files created/modified by this task:**
+   - Read plan phases to identify files created/modified
+   - Build list of source files that need tests
+
+
+**Output:** `✓ Phase 0: Task [task-id] validated - [N] source files to test`
+
+---
+
+## Workflow: File-by-File Testing
+
+### Phase 1: Initialize File Queue
+
+1. Create ordered list of files to test from Phase 0
+2. Set first file as current target
+
+**Output:** `✓ Phase 1: File queue initialized - [N] files`
+
+---
+
+### Phase 2: Process Each File (REPEAT FOR EACH FILE)
+
+**For current file [filename]:**
+
+#### Step 2.1: Check Existing Tests
+
+Use `tester` agent (`./.cursor/rules/tester.mdc`) to:
+
+1. Check if a test file exists for this source file
+2. If YES: Run existing tests, report pass/fail status
+3. If tests FAIL: Fix them until all pass
+4. Report current coverage for THIS FILE ONLY
+
+**Output:** `{ hasTests: bool, testsPass: bool, coverage: X% }`
+
+#### Step 2.2: Analyze Coverage Gap
+
+Use `tester` agent to:
+
+1. Run coverage report for THIS FILE ONLY
+2. List all uncovered lines
+3. List all uncovered branches
+4. Identify functions/methods without tests
+5. List edge cases not covered
+
+**Output:** Detailed list of what needs test coverage
+
+#### Step 2.3: Create Tests Until 100%
+
+**REPEAT this step until file coverage = 100%:**
+
+Use `tester` agent to:
+
+1. Write tests for uncovered lines/branches
+2. Focus on ONE function/section at a time
+3. Include edge cases and error scenarios
+4. Run tests - fix any failures immediately
+5. Re-check coverage
+
+**FORBIDDEN:**
+- Commenting out tests
+- Fake mocks just to pass
+- Tests without real assertions
+- Skipping difficult cases
+
+**After each iteration:**
+- Run coverage check for this file
+- If < 100%, repeat Step 2.3
+- If = 100%, proceed to next file
+
+**Output per file:** `✓ [filename]: 100% coverage - [N] tests created/fixed`
+
+---
+
+### Phase 3: Verify All Files Complete
+
+1. Run full test suite with coverage
+2. Verify each file has 100% coverage
+3. Verify all tests pass (0 failures)
+4. If any file < 100%, return to Phase 2 for that file
+
+**Output:** `✓ Phase 3: All [N] files at 100% coverage - [Total] tests passing`
+
+---
+
+### Phase 4: Generate Report & Finalize
+
+1. Update task status to COMPLETE with 100% coverage
+
+2. **Generate test report** at `./.cursor/tasks/[task-id]/test-report.md`:
+```markdown
+# Test Report: [task-id]
+
+## Summary
+- Files Tested: [N]
+- Total Tests: [X]
+- Coverage: 100%
+
+## Per-File Results
+
+| File | Tests | Coverage | Status |
+|------|-------|----------|--------|
+| [file1] | [N] | 100% | ✅ |
+| [file2] | [N] | 100% | ✅ |
+
+## Test Categories
+- Unit Tests: [X]
+- Integration Tests: [Y]
+- Edge Cases: [Z]
+```
+
+**Output:** `✓ Phase 4: Test report generated, task status updated`
+
+---
+
+### Phase 5: Summary Report
+
+```
+════════════════════════════════════════════════════════════════════
+                    ✅ TEST SUITE COMPLETE
+════════════════════════════════════════════════════════════════════
+
+TASK: [task-id]
+
+FILES TESTED (each at 100% coverage):
+  ✅ [file1.ts] - [N] tests
+  ✅ [file2.ts] - [N] tests
+  ✅ [file3.ts] - [N] tests
+
+TOTAL TESTS: [X] passed, 0 failed
+
+COVERAGE: 100% (lines, branches, functions)
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Critical Rules
+
+**File-by-file processing:**
+- Process ONE file at a time
+- Achieve 100% coverage before moving to next file
+- If existing tests fail, FIX THEM FIRST
+- Never skip a file
+
+**Coverage verification per file:**
+- Run coverage for specific file, not entire codebase
+- Example: `npm test -- --coverage --collectCoverageFrom='path/to/file.ts'`
+
+**Files to SKIP (no tests needed):**
+- `*.test.ts`, `*.spec.ts` (test files)
+- `*.d.ts` (type definitions)
+- `*.config.*` (configuration)
+- `index.ts` (barrel files)
+- Generated files
+- Migration files
+
+## Blocking Gates
+
+- Phase 2: Each file must reach 100% before proceeding
+- Phase 3: All files must be at 100%
+- Phase 4: Report must be generated
+
+## Principles
+
+- **ONE FILE AT A TIME** - complete file before next
+- **FIX FAILURES FIRST** - before adding new tests
+- **100% per file** - not just overall average
+- **DELEGATE to `tester` agent** for all testing work
+- **CRITICAL:** Follow `./docs/development-rules.md` - NO EXCEPTIONS