ai-qakit 1.0.0

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

@@ -0,0 +1,101 @@
+---
+description: Full feature implementation from scratch (research → plan → implement)
+---
+
+# Cook
+
+Complete end-to-end feature implementation: research, plan, and implement.
+
+## Usage
+
+`@spec/cook [task-id or description]`
+
+## Workflow
+
+### Phase 1: Setup Task
+
+1. If task doesn't exist, create `./.cursor/tasks/[task-id]/`
+2. Read any existing requirements
+
+### Phase 2: Research
+
+- Use `researcher` agents (max 2 parallel)
+- Each agent: max 5 tool calls
+- Save to `./.cursor/tasks/[task-id]/research/`
+
+### Phase 3: Plan
+
+Create implementation plan in `./.cursor/tasks/[task-id]/plan/`:
+- `plan.md` - Overview (under 80 lines)
+- `phase-XX-name.md` - Phase details
+- After plan approval, update `./.cursor/tasks/<task-id>/README.md` to mark `Plan created` as completed.
+
+### Phase 4: Implement
+
+For each phase:
+1. Read phase file
+2. Implement step by step
+3. Run type checking
+4. Update progress
+- When coding begins, update `./.cursor/tasks/<task-id>/README.md` to mark `Implementation started` as in progress/checked.
+
+### Phase 5: Test
+
+- Write real tests (no mocks/fakes)
+- Run tests with `tester` agent
+- Fix failures with `debugger` agent
+- Save reports to `./.cursor/tasks/[task-id]/testing/`
+- After tests pass, update `./.cursor/tasks/<task-id>/README.md` to mark `Testing complete` as completed.
+
+### Phase 6: Review
+
+- `code-reviewer` agent reviews
+- Fix critical issues
+- Repeat tests until passing
+- After review is complete, update `./.cursor/tasks/<task-id>/README.md` to mark `Review complete` as completed.
+
+### Phase 7: Document
+
+If approved:
+- Update `plan.md` with completion status
+- Update `./docs/` if needed
+- Update project roadmap
+
+### Phase 8: Report
+
+```
+════════════════════════════════════════
+✅ COOK COMPLETE: [task-id]
+════════════════════════════════════════
+
+PHASES COMPLETED:
+  ✓ Research
+  ✓ Planning
+  ✓ Implementation
+  ✓ Testing
+  ✓ Review
+
+FILES CREATED:
+  📄 [file] - [description]
+
+TESTS: [X] passing
+
+NEXT STEPS:
+  - [step 1]
+  - [step 2]
+════════════════════════════════════════
+```
+
+## Principles
+
+- YAGNI, KISS, DRY
+- No fake data or mocks in tests
+- Regular progress updates
+- Ask clarifying questions first
+
+## Important
+
+- Question assumptions before starting
+- Challenge user's initial approach
+- Consider all stakeholders
+

package/templates/.cursor/commands/devkit/spec/deep-capture-requirement.md

@@ -0,0 +1,149 @@
+---
+description: Deep Analyze and Capture finalized requirements into structured task artifacts without brainstorming
+---
+
+Ultrathink
+
+# Capture Requirement
+
+Convert already-defined requirements (PRDs, tickets, designs) into the standard task requirement artifacts. Skip ideation; focus on organization, validation, and traceability.
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Usage
+`@spec/deep-capture-requirement <task-id> [notes]`
+
+## Workflow
+
+### Phase 1: Validate Task ID
+1. If task-id not provided: Ask user to input task-id.
+2. Verify `./.cursor/tasks/[task-id]/` exists.
+3. If not found: "Task [task-id] not found. Run `@spec/task` first to create it."
+4. **Repeat steps 1-3 until valid task-id is provided.**
+5. Read existing `./.cursor/tasks/[task-id]/requirements/` (if present) to avoid duplication.
+6. **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)
+7. **IMPORTANT:** Testing (unit tests, E2E tests, integration tests) is handled separately via `/devkit:spec:test` command. Do NOT include test planning unless user explicitly requests it.
+
+### Phase 2: Collect Inputs
+- The input of the requirement to be parse can be found from the requirements folder (`./.cursor/tasks/[task-id]/requirements/`) if that folder is empty, ask the user to provide or start with brainstorm step (`./.cursor/commands/devkit/spec/brainstorm.md`). For the user to choose.
+- If the requirements folder contains images, you **must** analyze them: if an image is a UI/design template, mark it as the design to follow for UI creation (cite the file); if it contains tasks/text, extract and record them as requirements; if it is another type, capture the specific requirement it implies. Do not skip images.
+- If assets are files in the repo, read them. If external, request short summaries or pasted text.
+- Record provenance for each requirement (source name or link).
+- Based on auto-detected platform: if frontend, emphasize UI/UX requirements; if backend, emphasize API/data requirements; if fullstack, cover both aspects.
+
+### Phase 3: Gap Scan (optional, max 5 questions)
+- Only ask if a category is missing or unclear (functional, non-functional, constraints, decisions, risks, out-of-scope).
+- Each question must be multiple-choice or short-answer (<=5 words).
+- Stop after 5 total questions or when gaps are resolved. Do NOT brainstorm new scope—clarify only.
+
+### Phase 4: Normalize & Classify
+- Convert inputs into discrete, testable requirements; avoid duplicates and contradictions.
+- Tag each item: functional / non-functional / constraint / decision / risk / out-of-scope.
+- Ensure non-functional items carry measurable targets (latency, availability, security posture, accessibility).
+- Note assumptions and dependencies explicitly.
+
+### Phase 5: Capture Outputs
+Save/merge into `./.cursor/tasks/[task-id]/requirements/` (append, don't duplicate):
+```
+requirements/
+├── 01-functional.md      # Functional requirements (checkbox list)
+├── 02-non-functional.md  # Performance, security, accessibility, reliability
+├── 03-constraints.md     # Tech/time/storage/compliance constraints
+├── 04-decisions.md       # Key decisions + rationale + source
+├── 05-risks.md           # Risks + impact + mitigation
+└── YYYYMMDD-session.md   # Capture session log
+```
+
+**Session File Template:**
+```
+# Requirements Capture: <topic>
+Date: YYYY-MM-DD
+Task: <task-id>
+
+## Sources
+- PRD: ...
+- Designs: ...
+- Tickets: ...
+
+## Functional
+- [ ] ...
+
+## Non-Functional
+- [ ] Performance: ...
+- [ ] Security: ...
+- [ ] Accessibility: ...
+- [ ] Reliability: ...
+
+## Constraints
+- [ ] ...
+
+## Decisions
+- [ ] Decision: ... (Source: ...)
+
+## Risks
+| Risk | Impact | Mitigation | Source |
+|------|--------|------------|--------|
+
+## Assumptions
+- ...
+
+## Testing Strategy
+[OPTIONAL - Only include if user explicitly requests test planning]
+[NOTE: Testing is handled separately via /devkit:spec:test command]
+- Unit tests: ...
+- Integration tests: ...
+- E2E tests: ...
+
+## Out of Scope
+- ...
+
+## Unresolved Questions
+- ...
+```
+
+### Phase 6: Output
+Respond with:
+```
+════════════════════════════════════════
+📋 REQUIREMENTS CAPTURE COMPLETE: <task-id>
+════════════════════════════════════════
+
+FILES UPDATED:
+  📄 requirements/01-functional.md
+  📄 requirements/02-non-functional.md
+  📄 requirements/03-constraints.md
+  📄 requirements/04-decisions.md
+  📄 requirements/05-risks.md
+  📄 requirements/<date>-session.md
+
+SUMMARY: <brief highlights + key decisions>
+
+NEXT STEPS:
+  1. Review generated artifacts in ./.cursor/tasks/<task-id>/requirements/
+  2. Address any open questions listed
+  3. Run @spec/update-requirement <task-id> [changes] to update requirements with new changes
+  4. Run @spec/plan <task-id> to create implementation plan
+
+Need more changes? Run:
+  → @spec/update-requirement <task-id> [changes]
+
+Ready to plan? Run:
+  → @spec/plan <task-id>
+════════════════════════════════════════
+```
+- After saving outputs, update `./.cursor/tasks/<task-id>/README.md` to mark `Requirements gathered` as completed.
+
+## Guardrails
+- Do not invent scope; capture only what the user provides or cites from sources.
+- Keep files under ~250 lines; merge similar items to reduce noise.
+- Preserve existing requirements; append or refine without deleting unless the user explicitly approves.
+- Maintain traceability by noting source for decisions and risks.
+- **DO NOT focus on testing** - Testing (unit tests, E2E tests, integration tests) is handled separately via `/devkit:spec:test` command unless user explicitly requests it.
+- **MUST resolve ALL open questions before completing**

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

@@ -0,0 +1,354 @@
+---
+description: Start coding an existing task with plan (use @spec/test for testing)
+---
+
+# Implement Task
+
+Execute implementation plan for an existing task.
+
+**Note:** Testing is handled separately via `@spec/test` command. **DO NOT create any tests** (unit tests, integration tests, E2E tests) during implementation.
+
+**Checkpoint-Based Execution:** This command implements a phase-based workflow with mandatory checkpoints. After completing each phase, execution will pause and present a phase-specific summary. The user must explicitly confirm (type "continue", "proceed", or phase-specific commands) before advancing to the next phase. This ensures visibility, control, and opportunity for course correction at each milestone.
+
+**VERY IMPORTANT — MUST FOLLOW:** During implementation, if any issue occurs (build failure, test failure, runtime error, lint error, start-up problem), you must fix it immediately and continue until the app is stable and can start successfully. Do not leave known issues unresolved.
+
+## Usage
+
+`@spec/implement [task-id]`
+
+## Workflow
+
+### Phase 0: Validate
+
+1. Verify `./.cursor/tasks/[task-id]/` exists
+2. Verify `./.cursor/tasks/[task-id]/plan/plan.md` exists
+3. If not found: "Run `@spec/plan` first"
+4. If user has approved the implementation plan, first generate `./.cursor/tasks/[task-id]/plan/implementation-plan.md` with the aggregated plan (overview + all phase files) **and any AI-generated implementation notes**. This file must include technical implementation details as explicitly as possible (schemas, routes, middleware, data flows, env/config, test strategy). Do this before any coding and keep it updated when plan changes. **Do not pause after generating this plan—continue directly to Phase 1.**
+5. Before starting coding, update `./.cursor/tasks/[task-id]/README.md` to mark `Implementation started` as in progress/checked.
+
+### Phase 1: Analysis
+
+1. Read `./.cursor/tasks/[task-id]/plan/plan.md`
+2. Read `./.cursor/tasks/[task-id]/requirements/`
+3. Read `./.cursor/tasks/[task-id]/research/` (if exists)
+4. Read `./.cursor/tasks/[task-id]/plan/implementation-plan.md` (if exists)
+5. Map dependencies, list ambiguities
+6. Review relevant rules and context from `.cursor/rules/`
+7. Take a deep summary of everything you have read and understood. Use it for the next phase.
+
+**Phase 1 Summary & Checkpoint:**
+```
+════════════════════════════════════════
+📊 PHASE 1: ANALYSIS COMPLETE
+════════════════════════════════════════
+
+📋 Requirements Analyzed:
+  • [X] user stories reviewed
+  • [X] acceptance criteria mapped
+  • [X] dependencies identified
+
+⚠️  Risks & Ambiguities:
+  • [list any identified risks]
+  • [list any ambiguities]
+
+🔗 Dependencies:
+  • [list external dependencies]
+  • [list internal dependencies]
+
+💡 Key Insights:
+  • [insight 1]
+  • [insight 2]
+
+════════════════════════════════════════
+Type 'continue' to proceed to Phase 2: Implementation
+Type 'review' to see detailed analysis
+Type 'abort' to stop implementation
+════════════════════════════════════════
+```
+
+### Phase 2: Implementation
+
+For each implementation phase:
+> Need more input? First check the task's `requirements/` folder before asking.
+1. Read phase file: `plan/phase-XX-*.md`
+2. Before coding, set the phase status/progress in `plan.md` and the specific phase file. Do not start coding until both are updated.
+3. Implement step by step; for each step completed, immediately mark the corresponding item in the phase file's **Implementation Steps** checklist as done (no batching later).
+4. Run type checking.
+5. Update progress in `plan.md` and that phase file as you work (status, % and checklist) immediately after each step; keep % increments small and sequential to reflect real-time progress.
+6. If blocked awaiting user confirmation/input/modification, mark status/progress as `on-hold (waiting on user)` with a brief note of what is needed in both `plan.md` and the phase file; resume once unblocked.
+7. Complete the current implementation phase thoroughly before presenting checkpoint summary.
+8. If any bash/terminal command hangs with no output for ~60 seconds, interrupt it, diagnose the cause, fix, and rerun; do not leave hanging commands running.
+
+Use agents:
+- `ui-ux-designer` for frontend (follow `./docs/design-guidelines.md`) (if available)
+- `ai-multimodal` for image assets (if available)
+- `imagemagick` for image editing (if available)
+- If browser-based testing or implementation is needed, start the browser as part of the flow.
+
+**Phase 2 Summary & Checkpoint:**
+```
+════════════════════════════════════════
+🛠️ PHASE 2: IMPLEMENTATION COMPLETE
+════════════════════════════════════════
+
+📦 Features Built:
+  • [feature 1] - [status]
+  • [feature 2] - [status]
+  • [feature 3] - [status]
+
+📄 Files Modified:
+  • [file 1] - [change description]
+  • [file 2] - [change description]
+
+📄 Files Created:
+  • [file 1] - [purpose]
+  • [file 2] - [purpose]
+
+⚡ Type Checking:
+  • Status: [✅ Pass / ❌ Fail]
+  • Issues: [count]
+
+📊 Progress:
+  • Phase completion: [X]%
+  • Blockers: [list any]
+
+════════════════════════════════════════
+Type 'continue' to proceed to Phase 3: Testing
+Type 'review' to see implementation details
+Type 'fix' to address any issues
+════════════════════════════════════════
+```
+
+### Phase 3: Code Review
+- Use `code-reviewer` (./.cursor/rules/code-reviewer.mdc) agent
+- Fix critical issues
+- Update progress
+- Start the app (e.g., `npm run dev`) and confirm the web UI loads in a browser without errors before marking review done.
+- After review is complete and start-up is verified, update `./.cursor/tasks/[task-id]/README.md` to mark `Review complete` as completed.
+
+**Phase 3 Summary & Checkpoint:**
+```
+════════════════════════════════════════
+🔍 PHASE 3: CODE REVIEW COMPLETE
+════════════════════════════════════════
+
+📋 Review Findings:
+  • Critical issues: [X]
+  • Warnings: [X]
+  • Suggestions: [X]
+
+🛠️ Issues Fixed:
+  • [issue 1] - ✅ Fixed
+  • [issue 2] - ✅ Fixed
+
+💯 Code Quality:
+  • Security: [✅ Pass / ❌ Issues found]
+  • Performance: [✅ Optimized / ⚠️  Concerns]
+  • Best Practices: [✅ Followed / ⚠️  Deviations]
+
+✅ Verification:
+  • App starts: [✅ Yes / ❌ No]
+  • UI loads: [✅ Yes / ❌ No]
+
+════════════════════════════════════════
+Type 'continue' to proceed to Phase 4: User Approval
+Type 'view' to see detailed review report
+Type 'fix' to address remaining issues
+════════════════════════════════════════
+```
+
+### Phase 4: User Approval
+
+**REQUIRED:** Before finalizing, get explicit user approval for the completed phase.
+
+1. **Present Phase Summary:**
+   - Files created/modified
+   - Key changes implemented
+   - Code review status
+
+2. **Request Approval:**
+   Ask user: "Implementation complete. Please review the changes and confirm:
+
+   **Files Changed:** [list]
+   **Key Changes:** [summary]
+   **Code Review:** [status]
+
+   Approve this phase? (yes/no/feedback)"
+
+3. **Handle Response:**
+   - **"yes" or approval:** Proceed to Phase 5
+   - **"no" or rejection:** STOP, ask for specific feedback, return to relevant phase (2/3)
+   - **feedback provided:** Address feedback, re-run affected phases, request approval again
+
+**Phase 4 Summary & Checkpoint:**
+```
+════════════════════════════════════════
+✅ PHASE 4: USER APPROVAL
+════════════════════════════════════════
+
+📋 Summary Presented:
+  • Files changed: [X]
+  • Key features: [list]
+  • Code review: [status]
+
+👤 User Response:
+  • Status: [✅ Approved / ❌ Rejected / 📝 Feedback]
+
+════════════════════════════════════════
+Type 'continue' to proceed to Phase 5: Documentation
+Type 'details' to review changes
+════════════════════════════════════════
+```
+
+**Validation:** User must explicitly approve. Do not proceed without approval.
+
+### Phase 5: Documentation
+
+If approved:
+- Update `plan.md` with completion status
+- Update `./docs/` if needed
+- Update project roadmap
+
+If rejected:
+- Get feedback
+- Fix issues
+- Repeat process
+
+**Phase 5 Summary & Checkpoint:**
+```
+════════════════════════════════════════
+📚 PHASE 5: DOCUMENTATION COMPLETE
+════════════════════════════════════════
+
+📄 Documentation Updated:
+  • README.md: [✅ / ❌]
+  • API docs: [✅ / ❌]
+  • Changelog: [✅ / ❌]
+
+🎯 Task Documentation:
+  • plan.md: [✅ Updated]
+  • Implementation notes: [✅ Complete]
+
+🗺️ Project Updates:
+  • Roadmap: [✅ Updated / ⏭️ Not needed]
+  • Dependencies: [✅ Documented / ⏭️ None]
+
+════════════════════════════════════════
+Type 'continue' to proceed to Phase 6: Onboarding
+Type 'skip' to skip onboarding and proceed to final report
+Type 'review' to review documentation
+════════════════════════════════════════
+```
+
+### Phase 6: Onboarding
+
+- Guide user to get started
+- Help with configuration
+- Ask one question at a time
+
+**Phase 6 Summary & Checkpoint:**
+```
+════════════════════════════════════════
+🎓 PHASE 6: ONBOARDING COMPLETE
+════════════════════════════════════════
+
+🚀 Setup Status:
+  • Environment configured: [✅ / ❌]
+  • Dependencies installed: [✅ / ❌]
+  • Services running: [✅ / ❌]
+
+📋 Configuration:
+  • Environment variables: [✅ Set / ⚠️  Missing]
+  • Database setup: [✅ Ready / ⏭️ N/A]
+  • External services: [✅ Connected / ⏭️ N/A]
+
+👤 User Guidance:
+  • Quick start guide: [✅ Provided]
+  • Common commands: [✅ Documented]
+  • Troubleshooting tips: [✅ Included]
+
+════════════════════════════════════════
+Type 'continue' to proceed to Final Report
+Type 'help' for additional setup assistance
+Type 'test' to verify everything is working
+════════════════════════════════════════
+```
+
+### Phase 7: Final Report
+
+```
+════════════════════════════════════════
+✅ IMPLEMENTATION COMPLETE
+════════════════════════════════════════
+
+TASK: [task-id]
+
+COMPLETED PHASES:
+  ✓ Phase 1: Analysis
+  ✓ Phase 2: Implementation
+  ✓ Phase 3: Code Review
+  ✓ Phase 4: User Approval
+  ✓ Phase 5: Documentation
+  ✓ Phase 6: Onboarding
+
+FILES MODIFIED:
+  📄 path/to/file - [change]
+
+FILES CREATED:
+  📄 path/to/file - [description]
+
+NEXT STEPS:
+  - If more phases remain: Run @spec/implement [task-id] again
+  - If all phases complete: Run @spec/test [task-id] for testing
+
+Ready for testing? Run:
+  → @spec/test [task-id]
+
+UNRESOLVED:
+  - [question]
+════════════════════════════════════════
+```
+
+## Approach
+
+1. **Absorb Plan** - Read plan, map dependencies
+2. **Execute Phase by Phase** - Complete each phase thoroughly before checkpoint
+3. **Update First** - Set phase status/progress before coding in both `plan.md` and the phase file; keep them current.
+4. **Checkpoint & Confirm** - After completing each phase, present a comprehensive summary and wait for explicit user confirmation before proceeding. This ensures visibility, control, and opportunity for course correction.
+5. **On-Hold Handling** - If waiting on user input, mark phase `on-hold` with % and needed info in plan + phase file.
+6. **Update Progress** - Keep stakeholders informed through real-time updates
+7. **Course-Correct** - Use checkpoint feedback to adjust approach as needed
+
+## Principles
+
+- YAGNI, KISS, DRY
+- No shortcuts in tests
+- Regular progress updates
+- Sacrifice grammar for concision
+- **CRITICAL:** You MUST strictly follow `./docs/development-rules.md` in ALL circumstances. This is NON-NEGOTIABLE.
+
+## Remember
+
+- **CRITICAL:** ALWAYS follow `./docs/development-rules.md` - NO EXCEPTIONS.
+- Generate images with `ai-multimodal` on the fly
+- Verify assets meet requirements
+- Use ImageMagick for image editing
+
+---
+
+**🛑 CRITICAL REMINDER: MANDATORY PHASE CHECKPOINTS**
+
+This command enforces a checkpoint-based workflow. You MUST:
+1. Complete each phase thoroughly
+2. Present the phase-specific summary template
+3. STOP and WAIT for explicit user confirmation
+4. Only proceed when user types "continue", "proceed", or phase-specific commands
+
+Never auto-continue between phases. The checkpoint system ensures user awareness, control, and opportunity for intervention at each critical milestone. This is not optional—it's a core operational requirement.
+
+**🧪 TESTING:**
+Testing is handled separately via `@spec/test [task-id]`. After implementation is complete, run:
+```
+@spec/test [task-id]
+```
+This ensures 100% code coverage with comprehensive tests.