ai-qakit 1.0.0

package/templates/.cursor/commands/devkit/solve.md

@@ -0,0 +1,355 @@
+---
+description: Complex problem solving with multiple techniques
+argument-hint: [problem-description]
+allowed-tools: Read, Grep, Bash, Task, WebSearch, AskUserQuestion
+---
+
+# Solve - Multi-Technique Problem Solving
+
+Orchestrates systematic problem-solving techniques for complex challenges.
+
+## Agents Used
+- **cunningham** - Provokes deep understanding through strategic wrongness
+
+## Rules Applied (inline)
+- **problem-solving** (`./.cursor/rules/problem-solving/problem-solving.mdc`): 5 systematic techniques (see table)
+- **sequential-thinking** (`./.cursor/rules/sequential-thinking.mdc`): Structured multi-step analysis
+- **research** (`./.cursor/rules/research.mdc`): When external knowledge needed
+
+---
+
+## Phase 1: Problem Understanding
+
+**Apply:** `sequential-thinking` skill
+
+### Thought 1/N: Initial Analysis
+
+If $ARGUMENTS provided, analyze it. Otherwise:
+
+```
+Question: What problem are you trying to solve?
+Header: Problem
+Options:
+  - I'll describe the problem
+  - I'm stuck on implementation
+  - I need to understand a concept
+  - I'm facing a design decision
+  - Something isn't working as expected
+```
+
+### Problem Classification
+
+```
+════════════════════════════════════════════════════════════════════
+                    🧩 PROBLEM ANALYSIS
+════════════════════════════════════════════════════════════════════
+
+PROBLEM: [brief description]
+
+TYPE: [classify the problem]
+  □ Complexity spiral - Too many cases, growing special handling
+  □ Innovation block - Conventional solutions inadequate
+  □ Recurring pattern - Same issue in different places
+  □ Assumption constraint - Feeling forced into "only one way"
+  □ Scale uncertainty - Will this work at production scale?
+  □ Understanding gap - Need deeper knowledge
+  □ Design decision - Multiple valid approaches, unclear best choice
+
+SYMPTOMS:
+  - [Symptom 1]
+  - [Symptom 2]
+  - [Symptom 3]
+
+CONSTRAINTS:
+  - [Constraint 1]
+  - [Constraint 2]
+
+ATTEMPTED SOLUTIONS:
+  - [What's been tried]
+  - [Why it didn't work]
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 2: Technique Selection
+
+**Apply:** `problem-solving` skill
+
+### Match Problem to Technique
+
+Based on problem type, select technique:
+
+| Problem Type | Technique | Reference |
+|--------------|-----------|-----------|
+| Complexity spiral | **Simplification Cascades** | Find one insight eliminating multiple components |
+| Innovation block | **Collision-Zone Thinking** | Force unrelated concepts together |
+| Recurring pattern | **Meta-Pattern Recognition** | Spot patterns across 3+ domains |
+| Assumption constraint | **Inversion Exercise** | Flip core assumptions |
+| Scale uncertainty | **Scale Game** | Test at 1000x extremes |
+| Understanding gap | **Cunningham's Law** | Provoke corrections for learning |
+
+```
+Question: Which technique seems most relevant?
+Header: Approach
+Options:
+  - Simplification Cascades (too complex)
+  - Collision-Zone Thinking (need innovation)
+  - Meta-Pattern Recognition (recurring issue)
+  - Inversion Exercise (feeling constrained)
+  - Scale Game (uncertain about scale)
+  - Deep Learning via Cunningham (need understanding)
+  - Let the assistant choose based on analysis
+  - Combine multiple techniques
+```
+
+---
+
+## Phase 3: Apply Selected Technique
+
+### Option A: Simplification Cascades
+
+```
+════════════════════════════════════════════════════════════════════
+                🔄 SIMPLIFICATION CASCADES
+════════════════════════════════════════════════════════════════════
+
+GOAL: Find one insight that eliminates multiple components
+
+CURRENT COMPLEXITY:
+  - Component 1: [description]
+  - Component 2: [description]
+  - Component 3: [description]
+  - Special case 1: [description]
+  - Special case 2: [description]
+
+RED FLAG CHECK: "Just need to add one more case..." ❌
+
+SIMPLIFICATION HYPOTHESIS:
+  "If [this insight] is true, we don't need:
+    - [Component X]
+    - [Component Y]
+    - [Special case Z]"
+
+VALIDATION:
+  - Does this actually simplify?
+  - Are we hiding complexity elsewhere?
+  - Does the core abstraction hold?
+
+RESULT:
+  [Simplified solution]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Option B: Collision-Zone Thinking
+
+```
+════════════════════════════════════════════════════════════════════
+                💥 COLLISION-ZONE THINKING
+════════════════════════════════════════════════════════════════════
+
+GOAL: Force unrelated concepts together for breakthrough
+
+CONCEPT A: [Domain/technology/pattern 1]
+CONCEPT B: [Unrelated domain/technology/pattern 2]
+
+COLLISION QUESTION:
+  "What if we treated [A] like [B]?"
+
+EMERGENT PROPERTIES:
+  - [New insight 1]
+  - [New insight 2]
+  - [New insight 3]
+
+UNEXPECTED CONNECTIONS:
+  - [Connection 1]
+  - [Connection 2]
+
+BREAKTHROUGH:
+  [Novel solution from collision]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Option C: Meta-Pattern Recognition
+
+```
+════════════════════════════════════════════════════════════════════
+                🔍 META-PATTERN RECOGNITION
+════════════════════════════════════════════════════════════════════
+
+GOAL: Find pattern appearing in 3+ domains
+
+OCCURRENCE 1: [Domain/context]
+  - How it manifests: [description]
+  - Solution used: [description]
+
+OCCURRENCE 2: [Domain/context]
+  - How it manifests: [description]
+  - Solution used: [description]
+
+OCCURRENCE 3: [Domain/context]
+  - How it manifests: [description]
+  - Solution used: [description]
+
+UNIVERSAL PATTERN:
+  [The abstraction that spans all occurrences]
+
+REUSABLE SOLUTION:
+  [Generic solution applicable everywhere]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Option D: Inversion Exercise
+
+```
+════════════════════════════════════════════════════════════════════
+                🔄 INVERSION EXERCISE
+════════════════════════════════════════════════════════════════════
+
+GOAL: Flip core assumptions to reveal hidden constraints
+
+CURRENT ASSUMPTION: [What you believe must be true]
+
+INVERSION: "What if the opposite were true?"
+  - [Inverted assumption]
+
+VALIDITY CHECK:
+  - In what context is the inversion valid?
+  - What does this reveal about our constraints?
+  - Are these constraints real or assumed?
+
+HIDDEN CONSTRAINTS REVEALED:
+  - [Constraint 1] - Real / Assumed
+  - [Constraint 2] - Real / Assumed
+  - [Constraint 3] - Real / Assumed
+
+NEW SOLUTION SPACE:
+  [Solutions now possible after questioning assumptions]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Option E: Scale Game
+
+```
+════════════════════════════════════════════════════════════════════
+                📊 SCALE GAME
+════════════════════════════════════════════════════════════════════
+
+GOAL: Test at extremes to expose fundamental truths
+
+CURRENT SCALE: [Normal operating parameters]
+
+1000x BIGGER:
+  - What happens: [description]
+  - What breaks: [description]
+  - What still works: [description]
+
+1000x SMALLER:
+  - What happens: [description]
+  - What becomes unnecessary: [description]
+  - What's essential: [description]
+
+INSTANT (0 time):
+  - What's needed: [description]
+
+YEAR-LONG:
+  - What changes: [description]
+
+FUNDAMENTAL TRUTHS:
+  - [Truth that holds at all scales]
+  - [Truth that only matters at certain scales]
+
+SCALE-APPROPRIATE SOLUTION:
+  [Solution designed for actual scale requirements]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Option F: Cunningham's Law (Deep Learning)
+
+**Spawn:** `cunningham` agent
+
+```
+For deep understanding, use Cunningham's Law:
+"The best way to get the right answer is to post the wrong answer."
+
+TOPIC: [What you need to understand deeply]
+
+The cunningham agent will make a strategically wrong assertion
+about this topic. The correction will provide deeper insight
+than a direct question would elicit.
+
+LEARNING GOAL:
+  - [What you want to understand]
+  - [Edge cases you want revealed]
+  - [Nuances you want explained]
+```
+
+---
+
+## Phase 4: Solution Synthesis
+
+**Apply:** `sequential-thinking` skill
+
+### Thought N/M: Synthesize Insights
+
+```
+════════════════════════════════════════════════════════════════════
+                    💡 SOLUTION SYNTHESIS
+════════════════════════════════════════════════════════════════════
+
+TECHNIQUE(S) APPLIED: [which techniques]
+
+KEY INSIGHTS:
+  1. [Insight from technique]
+  2. [Insight from technique]
+  3. [Insight from technique]
+
+SOLUTION:
+  [Clear description of the solution]
+
+WHY IT WORKS:
+  - [Reason 1]
+  - [Reason 2]
+  - [Reason 3]
+
+IMPLEMENTATION APPROACH:
+  1. [Step 1]
+  2. [Step 2]
+  3. [Step 3]
+
+VALIDATION:
+  - Does it address the original problem? ✓
+  - Is it simpler than alternatives? ✓
+  - Does it scale appropriately? ✓
+  - Are assumptions explicit? ✓
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 5: Next Steps
+
+```
+Question: How should we proceed?
+Header: Next Steps
+Options:
+  - Implement this solution
+  - Apply another technique for more insight
+  - Explore a different aspect
+  - Document the solution
+  - Done - problem solved
+```
+
+---
+
+## Begin Now
+
+What problem are you trying to solve?
+

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

@@ -0,0 +1,184 @@
+---
+description: Clarify ambiguities and brainstorm a feature with a structured, high-signal workflow
+---
+
+# Brainstorm v2
+
+Goal: run a concise clarify → brainstorm flow that reduces rework risk and captures requirements/decisions in the task folder.
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Usage
+`@spec/brainstorm-v2 <task-id> [question]`
+
+### Phase 1: Validate Task ID
+
+**Required:** task-id must be provided and valid
+
+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/`
+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)
+   - Use detected platform to guide brainstorming context
+
+## Phase 2: Quick Clarify (max 5 questions, only if impact)
+- Purpose: resolve high-impact ambiguities before ideation (security, data, scope, UX, performance).  
+- If everything is clear, skip to Phase 3.
+
+Question rules:
+- Max 5 total; strictly one question at a time (no batching multiple questions in one message).
+- Each must be multiple-choice (2–5 options) or short-answer (<=50 words).  
+- Ask only if it changes architecture, data model, validation, UX, or testing.
+
+Format:
+- Start with recommendation: `**Recommended:** Option X - <reason>` or `**Suggested:** <answer> - <reason>`  
+- Render options table:  
+  | Option | Description |  
+  |--------|-------------|  
+  | A | ... |  
+  | B | ... |  
+  | C | ... |  
+  | Short | Free-form (<=50 words) | (include only if useful)  
+- Prompt: "Reply with letter (e.g., A), say 'recommended' to accept, or give your own short answer."
+
+Recording answers:
+- Maintain in-memory list. No file writes during questioning. Stop asking on user "done" or after 5.
+
+## Phase 3: Integrate Clarifications
+- After all answers, update the spec/requirements in the task folder:
+  - Ensure `## Clarifications` with `### Session YYYY-MM-DD` exists in the active spec file (if present).  
+  - Append bullets: `- Q: <question> → A: <answer>`.  
+  - Apply answers to relevant sections: functional, non-functional, data model, edge cases, terminology, etc. Replace vague text; avoid contradictions.  
+- Save the updated spec (do not reorder unrelated content).
+
+## Phase 4: Brainstorm
+Principles: YAGNI, KISS, DRY. Use concise, high-signal notes.
+
+Steps:
+1) Discovery: restate problem, users, success criteria.  
+2) Research: perform targeted searches (up to 5) for best practices, similar patterns, security/perf guidance; cite sources briefly.  
+3) Analysis: propose 2–3 options with pros/cons and tradeoffs (include constraints and risks).  
+4) Debate: challenge assumptions; note rejected alternatives with rationale.  
+5) Consensus: pick recommended approach and why.
+
+## Phase 5: Capture Outputs
+Update `./.cursor/tasks/<task-id>/requirements/` (append, don't duplicate):
+- `01-functional.md`: add/adjust functional bullets with checkboxes.
+- `02-non-functional.md`: perf/security/observability targets.
+- `03-constraints.md`: tech/time/storage constraints.
+- `04-decisions.md`: key choices + rationale.
+- `05-risks.md`: risk/impact/mitigation table.
+- `YYYYMMDD-session.md`: full brainstorm session log (problem, requirements, options, recommendation, risks, next steps, unresolved questions).
+- After saving outputs, update `./.cursor/tasks/<task-id>/README.md` to mark `Requirements gathered` as completed.
+
+**De-duplication rule:** Each requirements file should contain a single instance of its top-level heading (e.g., `# Functional Requirements`). If older brainstorm content exists (different task scope or duplicate sections), replace it with the new canonical content instead of appending. Preserve only the latest clarifications block under `## Clarifications` for the current session date.
+
+Session file template:
+```
+# Brainstorm: <topic>
+Date: YYYY-MM-DD
+Task: <task-id>
+
+## Problem Statement
+<brief>
+
+## Requirements
+### Functional
+- [ ] ...
+### Non-Functional
+- [ ] Performance: ...
+- [ ] Security: ...
+
+## Approaches
+### Option 1: <name>
+Pros: ...
+Cons: ...
+### Option 2: <name>
+Pros: ...
+Cons: ...
+
+## Recommendation
+<chosen approach + rationale>
+
+## Risks
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+
+## Next Steps
+- [ ] ...
+
+## Questions Resolved During Session
+| Question | Decision | Rationale |
+|----------|----------|-----------|
+| ... | ... | ... |
+```
+
+## Phase 6: Resolve Remaining Questions
+
+**IMPORTANT:** Before completing, ALL unresolved questions MUST be resolved.
+
+1. Check for any unresolved questions from the brainstorm session
+2. If questions exist:
+   - Ask user about each question using multiple-choice format
+   - Present recommendation: `**Recommended:** Option X - <reason>`
+   - Record decision in `04-decisions.md`
+   - Update relevant requirement files
+3. Resolution loop:
+   ```
+   WHILE unresolved_questions.length > 0:
+     - Pick most critical question
+     - Ask with clear options
+     - Record decision
+     - Remove from unresolved list
+   ```
+4. Only proceed to output when ALL questions are resolved
+
+## Phase 7: Output
+Respond with:
+```
+════════════════════════════════════════
+💡 BRAINSTORM 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
+
+QUESTIONS RESOLVED: [count] questions answered during session
+
+RECOMMENDATION: <brief summary>
+
+NEXT STEPS:
+  1. Review captured requirements in ./.cursor/tasks/<task-id>/requirements/
+  2. Run @spec/update-requirement <task-id> [changes] to update requirements with new changes
+  3. 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>
+════════════════════════════════════════
+```
+
+## Guardrails
+- Never exceed 5 clarification questions; skip low-impact ambiguity.
+- Do not implement code.
+- Keep file sections under ~250 lines; preserve formatting.
+- Use uniform error messaging to avoid user enumeration when relevant.
+- Cite research sources succinctly in session notes; avoid PII.
+- If task/spec missing: instruct to run `@spec/task` first.
+- **MUST resolve ALL unresolved questions before completing brainstorm.**

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

@@ -0,0 +1,164 @@
+---
+description: Capture requirements into structured task artifacts without brainstorming
+---
+
+Ultrathink
+
+# Update Requirements (Lightweight)
+
+Consolidate and update task requirements from the requirements folder.
+
+**Note:** This is a lightweight version of `@spec/deep-capture-requirement`.
+
+## Usage
+```
+@spec/capture-requirement [task-id]
+```
+
+## Examples
+```
+@spec/capture-requirement ABC-123
+@spec/capture-requirement feature-user-auth
+```
+
+## Your Mission
+
+Consolidate requirements for task: **$ARGUMENTS**
+
+Read all files in the requirements folder and generate two output files:
+- `01-functional.md` - Consolidated functional requirements
+- `10-notes.md` - Notes, decisions, constraints, risk and other information
+
+## Workflow
+
+### Phase 1: Validate Task
+
+1. If task-id not provided: Ask user to input task-id
+2. Verify `./.cursor/tasks/[task-id]/` exists
+3. If not found: "Task not found. Run `@spec/task` first."
+4. Verify `./.cursor/tasks/[task-id]/requirements/` exists and has content
+5. If missing/empty: "No requirements found. Run `@spec/brainstorm` or `@spec/capture-requirement` first."
+
+### Phase 2: Read Existing Artifacts
+
+Read ALL files within `./.cursor/tasks/[task-id]/requirements/`:
+- Any `.md` files
+- Any subdirectories containing requirements
+- Remember to read the content of each file carefully, don't skip any file
+
+Extract and consolidate:
+- Functional requirements
+- Non-functional requirements
+- Constraints and limitations
+- Decisions made
+- Notes and other information
+
+### Phase 3: Generate Consolidated Files
+
+Create/update two files:
+
+**1. `./.cursor/tasks/[task-id]/requirements/01-functional.md`:**
+```markdown
+# Functional Requirements: [task-id]
+
+**Last Updated:** [YYYY-MM-DD]
+
+## Overview
+[Brief description of the feature/task]
+
+## Requirements
+
+### Core Functionality
+- FR-001: [Requirement]
+- FR-002: [Requirement]
+
+### User Stories
+- As a [user], I want [action], so that [benefit]
+
+### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+```
+
+**2. `./.cursor/tasks/[task-id]/requirements/10-notes.md`:**
+```markdown
+# Notes: [task-id]
+
+**Last Updated:** [YYYY-MM-DD]
+
+## Decisions
+- [Decision 1 with rationale]
+- [Decision 2 with rationale]
+
+## Constraints
+- [Constraint 1]
+- [Constraint 2]
+
+## Non-Functional Requirements
+- Performance: [requirements]
+- Security: [requirements]
+
+## Questions Resolved
+| Question | Decision | Date |
+|----------|----------|------|
+| [Question 1] | [Answer] | [When] |
+
+## Miscellaneous
+[Any other relevant notes]
+```
+
+### Phase 4: Resolve Open Questions
+
+**IMPORTANT:** Before completing, ALL open questions MUST be resolved.
+
+1. **Check for open questions** found in requirement files
+2. **If questions exist:**
+   - Ask user about each question using multiple-choice format
+   - Present recommendation: `**Recommended:** Option X - <reason>`
+   - Update `10-notes.md` with decisions
+   - Update `01-functional.md` if answers affect requirements
+3. **Resolution loop:**
+   - Pick most critical question
+   - Ask with clear options
+   - Record decision in 10-notes.md
+   - Remove from open list
+4. **Only proceed to summary when ALL questions are resolved**
+
+### Phase 5: Summary Output
+
+```
+════════════════════════════════════════
+✅ REQUIREMENTS CONSOLIDATED: [task-id]
+════════════════════════════════════════
+
+FILES GENERATED:
+  📄 requirements/01-functional.md
+  📄 requirements/10-notes.md
+
+SUMMARY:
+  • Functional requirements: [count]
+  • Decisions documented: [count]
+  • Constraints identified: [count]
+  • Questions resolved: [count]
+
+NEXT STEPS:
+  1. Review updated requirements in ./.cursor/tasks/[task-id]/requirements/
+  2. Run @spec/update-requirement [task-id] [changes] to update requirements with new changes
+  3. 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]
+
+════════════════════════════════════════
+```
+
+## 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**