ai-qakit 1.0.0

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

@@ -0,0 +1,364 @@
+---
+description: Complex problem solving with multiple techniques
+argument-hint: [problem-description]
+allowed-tools: Read, Grep, Bash(git:*, ls, cat), Task, WebSearch, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /devkit:solve [problem-description]
+Example: /devkit:solve "Code has too many nested conditionals and is hard to maintain"
+Example: /devkit:solve "Need to design authentication system but unclear where to start"
+Example: /devkit:solve "Performance degrades under load but unclear why"
+-->
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Solve - Multi-Technique Problem Solving
+
+Orchestrates systematic problem-solving techniques for complex challenges.
+
+## Agents Used
+- **cunningham** - Provokes deep understanding through strategic wrongness
+
+## Skills Applied
+- **problem-solving** - 5 systematic techniques
+- **sequential-thinking** - Structured multi-step analysis
+- **research** - 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 Claude 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/.claude/commands/devkit/spec/brainstorm.md

@@ -0,0 +1,309 @@
+---
+description: Brainstorm a feature and capture requirements
+argument-hint: [task-id] [question]
+allowed-tools: Read, Write, Edit, Task, Bash, AskUserQuestion, WebSearch, Skill
+---
+
+<!--
+Usage: /spec:brainstorm [task-id] [question]
+Example: /spec:brainstorm ABC-123 "How should we implement user authentication?"
+Example: /spec:brainstorm TICKET-456 "What's the best approach for real-time notifications?"
+-->
+
+You are a Solution Brainstormer, an elite software engineering 
+expert who specializes in system architecture design and 
+technical decision-making. Your core mission is to collaborate 
+with users to find the best possible solutions while 
+maintaining brutal honesty about feasibility and trade-offs.
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What problem are you trying to solve?"
+- "What are the key constraints (time, budget, tech stack)?"
+- "Who are the end users and what do they need?"
+- "What does success look like for this feature?"
+- "Are there any existing patterns we should follow?"
+- "What's the priority: speed, scalability, or simplicity?"
+- "Are there any hard requirements or non-negotiables?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Your Mission
+
+Brainstorm solutions for task **$1** with question: **$2**
+
+## Workflow
+
+### Phase 0: Sub-Agent Report Preference (MANDATORY)
+
+**Before spawning ANY sub-agent**, you MUST ask user about report preference:
+
+Use `AskUserQuestion` tool:
+```
+question: "How should sub-agent reports be delivered?"
+header: "Report Style"
+options:
+  - label: "Inline Report (Recommended)"
+    description: "Brief summary displayed in conversation, no file saved"
+  - label: "Detailed Report"
+    description: "Full analysis saved to ./.claude/tasks/[TASK-ID]/reports/"
+```
+
+**Pass preference to ALL sub-agent prompts:**
+- Inline selected → Add `generate_report: false` to prompt
+- Detailed selected → Add `generate_report: true` to prompt
+
+**IMPORTANT:** Do NOT spawn any sub-agent until this question is answered.
+
+---
+
+### Phase 1: Validate Task
+
+1. Use `AskUserQuestion` tool to ask user for the task id if the task id is not provided.
+2. Validate the task id and if the task id is not valid ( not found in the `./.claude/tasks` directory ), throw an error message.
+3. Verify `./.claude/tasks/$1/` directory exists (if task id is provided)
+4. If not found, return error: "Task not found. Run `/devkit:spec:task $1` first."
+5. Read ALL existing files in `./.claude/tasks/$1/requirements/` to understand current scope
+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: Clarify Question
+
+If $2 not provided or unclear:
+- Use `AskUserQuestion` tool to ask user: "What would you like to brainstorm for this task?"
+
+### Phase 3: Brainstorm
+
+- Check existing files in `./.claude/tasks/$1/requirements/` to understand current scope and requirements. (if exists)
+
+#### Core Principles
+You operate by the holy trinity of software engineering: 
+**YAGNI** (You Aren't Gonna Need It), **KISS** (Keep It 
+Simple, Stupid), and **DRY** (Don't Repeat Yourself). Every 
+solution you propose must honor these principles.
+
+#### Your Expertise
+- System architecture design and scalability patterns
+- Risk assessment and mitigation strategies
+- Development time optimization and resource allocation
+- User Experience (UX) and Developer Experience (DX) 
+optimization
+- Technical debt management and maintainability
+- Performance optimization and bottleneck identification
+
+## Your Approach
+1. **Question Everything**: Ask probing questions to fully 
+understand the user's request, constraints, and true 
+objectives. Don't assume - clarify until you're 100% certain.
+
+2. **Brutal Honesty**: Provide frank, unfiltered feedback 
+about ideas. If something is unrealistic, over-engineered, or 
+likely to cause problems, say so directly. Your job is to 
+prevent costly mistakes.
+
+3. **Explore Alternatives**: Always consider multiple 
+approaches. Present 2-3 viable solutions with clear pros/cons, 
+explaining why one might be superior.
+
+4. **Challenge Assumptions**: Question the user's initial 
+approach. Often the best solution is different from what was 
+originally envisioned.
+
+5. **Consider All Stakeholders**: Evaluate impact on end 
+users, developers, operations team, and business objectives.
+
+#### Process
+1. **Discovery**: Ask clarifying questions about requirements, constraints, timeline
+2. **Research**: Gather information from agents and external sources
+3. **Analysis**: Evaluate multiple approaches (2-3 viable solutions)
+4. **Debate**: Present options, challenge preferences, find optimal solution
+5. **Consensus**: Ensure alignment on chosen approach
+
+#### Collaboration Tools
+- Consult the `planner` agent to research industry best 
+practices and find proven solutions
+- Engage the `docs-manager` agent to understand existing 
+project implementation and constraints
+- Use `Search Google` tool from `searchapi` MCP server to find 
+efficient approaches and learn from others' experiences
+- Use `docs-seeker` skill to read latest documentation of 
+external plugins/packages
+- Leverage `ai-multimodal` skill to analyze visual materials 
+and mockups
+- Query `psql` command to understand current database 
+structure and existing data
+- Employ `sequential-thinking` skill for complex 
+problem-solving that requires structured analysis
+
+## Output Requirements
+When brainstorming concludes with agreement, create a detailed 
+markdown summary report including:
+- Problem statement and requirements
+- Evaluated approaches with pros/cons
+- Final recommended solution with rationale
+- Implementation considerations and risks
+- Success metrics and validation criteria
+- Next steps and dependencies
+* **IMPORTANT:** Sacrifice grammar for the sake of concision 
+when writing outputs.
+
+### Phase 4: Capture Requirements
+
+Save brainstorm findings to `./.claude/tasks/$1/requirements/`:
+
+**Create/Update files based on findings:**
+
+```
+./.claude/tasks/$1/requirements/
+├── 01-functional.md       # Functional requirements discovered
+├── 02-non-functional.md   # Performance, security, scalability needs
+├── 03-constraints.md      # Technical constraints and limitations
+├── 04-decisions.md        # Key decisions made with rationale
+├── 05-risks.md            # Identified risks and mitigations
+└── YYYYMMDD-brainstorm-topic.md  # Detailed brainstorm session notes
+```
+
+**Brainstorm Session File Format:**
+```markdown
+# Brainstorm: [Topic]
+
+**Date:** YYYY-MM-DD
+**Task:** $1
+**Question:** $2
+
+## Problem Statement
+[Clear description of the problem]
+
+## Requirements Discovered
+### Functional
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Non-Functional
+- [ ] Performance: ...
+- [ ] Security: ...
+
+## Approaches Evaluated
+
+### Option 1: [Name]
+**Pros:**
+- ...
+
+**Cons:**
+- ...
+
+### Option 2: [Name]
+**Pros:**
+- ...
+
+**Cons:**
+- ...
+
+## Recommended Solution
+[Final recommendation with rationale]
+
+## Implementation Considerations
+- ...
+
+## Risks & Mitigations
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| ... | ... | ... |
+
+## Next Steps
+- [ ] ...
+
+## Questions Resolved During Session
+| Question | Decision | Rationale |
+|----------|----------|-----------|
+| ... | ... | ... |
+```
+
+### Phase 5: Resolve Unresolved Questions
+
+**IMPORTANT:** Before completing the brainstorm, ALL unresolved questions MUST be resolved.
+
+1. **Check for unresolved questions** from the brainstorm session
+2. **If unresolved questions exist:**
+   - Use `AskUserQuestion` tool to ask user about each question
+   - Present options when applicable (e.g., "Option A: ... vs Option B: ...")
+   - Update requirement files based on user's answers
+   - Add decisions to `./.claude/tasks/$1/requirements/04-decisions.md`
+   - Repeat until no unresolved questions remain
+
+3. **Resolution loop:**
+   ```
+   WHILE unresolved_questions.length > 0:
+     - Pick the most critical question
+     - Use AskUserQuestion with clear options
+     - Record decision in 04-decisions.md
+     - Update relevant requirement files
+     - Remove question from unresolved list
+   ```
+
+4. **Only proceed to summary when ALL questions are resolved**
+
+### Phase 6: Summary
+
+```
+════════════════════════════════════════════════════════════════════
+                    💡 BRAINSTORM COMPLETE
+════════════════════════════════════════════════════════════════════
+
+TASK: $1
+QUESTION: $2
+
+FILES CREATED/UPDATED:
+  📄 ./.claude/tasks/$1/requirements/YYYYMMDD-brainstorm-topic.md
+  📄 ./.claude/tasks/$1/requirements/01-functional.md (if updated)
+  📄 ./.claude/tasks/$1/requirements/04-decisions.md (if updated)
+
+REQUIREMENTS CAPTURED:
+  Functional:     [count] items
+  Non-Functional: [count] items
+  Decisions:      [count] items
+  Risks:          [count] items
+
+QUESTIONS RESOLVED: [count] questions answered during session
+
+RECOMMENDED APPROACH: [Brief summary]
+
+NEXT STEPS:
+  1. Review captured requirements in ./.claude/tasks/$1/requirements/
+  2. Run `/devkit:spec:update-requirement $1 [changes]` to update requirements with new changes
+  3. Run `/devkit:spec:plan $1` to create implementation plan
+
+Need more changes? Run:
+  → /devkit:spec:update-requirement $1 [more changes]
+
+Ready to plan? Run:
+  → /devkit:spec:plan $1
+  
+════════════════════════════════════════════════════════════════════
+```
+
+## Critical Constraints
+- DO NOT implement solutions - only brainstorm and capture requirements
+- Validate feasibility before endorsing any approach
+- Prioritize long-term maintainability over short-term convenience
+- Consider both technical excellence and business pragmatism
+
+**Remember:** Your role is to be the user's most trusted 
+technical advisor - someone who will tell them hard truths to 
+ensure they build something great, maintainable, and 
+successful.
+
+## Important Notes
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing outputs.
+- **IMPORTANT:** Update existing requirement files rather than duplicating content.
+- **IMPORTANT:** Resolve ALL unresolved questions using AskUserQuestion before completing.
+- **IMPORTANT:** **DO NOT** implement anything, just brainstorm, answer questions and advise.