ai-qakit 1.0.0

package/templates/.claude/commands/devkit/spec-lite/plan.md

@@ -0,0 +1,236 @@
+---
+description: Create a quick implementation plan (no research, max 4 phases)
+argument-hint: [task-id]
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, Glob, Grep, Task, Skill
+---
+
+<!--
+Usage: /devkit:spec-lite:plan [task-id]
+Example: /devkit:spec-lite:plan fix-login-bug
+Example: /devkit:spec-lite:plan add-logout
+Requires: Task must exist in ./.claude/tasks/[task-id]/
+-->
+
+**MUST READ** `CLAUDE.md` to understand orchestration rules before proceeding.
+
+Activate `planning` skill for structured planning approach.
+
+## Your Mission
+
+Create a quick implementation plan for: **$ARGUMENTS**
+
+NO research. Just read existing docs and create a simple plan with MAX 4 phases.
+
+## Available Sub-Agents
+
+| Agent | Use For |
+|-------|---------|
+| `scout` | Quick codebase exploration to find related files |
+| `planner` | Create structured implementation plan |
+
+## Pre-Plan Check (Active Task Detection)
+
+Before starting, check for existing active task:
+
+1. **Check active-task file:** If `./.claude/active-task` exists:
+   - Read the path from file
+   - If task-id matches or not provided: use active task
+   - If different task-id provided: update active-task file
+
+2. **If no task-id provided and no active task:** Use `AskUserQuestion` tool to ask user for task-id
+
+## Workflow
+
+### Step 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.
+
+---
+
+### Step 1: Validate Task Exists
+
+1. Verify `./.claude/tasks/$ARGUMENTS/` directory exists
+2. If not found: "Task not found. Run `/devkit:spec-lite:task` first."
+3. Read `requirements.md` to understand the task
+
+### Step 2: Get Current Date
+
+```bash
+date +%Y-%m-%d
+```
+
+### Step 3: Gather Context (Quick Scan)
+
+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)
+   - Store decision in plan metadata for `/devkit:spec:implement` to use
+
+2. **Detect API development approach** ONLY if platform is **backend** (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 this in plan metadata - implementation MUST respect this approach:
+     - Schema-first: Update OpenAPI spec → Run generator → Use generated DTOs/types
+     - Code-first: Write code with annotations → Generate spec as documentation
+   - Store decision in plan metadata for `/devkit:spec:implement` to use
+
+Read existing documentation ONLY (no research):
+- `./docs/codebase-summary.md` (if exists)
+- `./docs/code-standards.md` (if exists)
+- `./.claude/tasks/[task-id]/requirements.md`
+
+**Use `scout` sub-agent** for quick codebase exploration:
+```
+Task(subagent_type="scout", prompt="Quick scan for [task description]. Find: (1) REUSABLE: existing utils, helpers, services, components that can be reused - DO NOT duplicate; (2) PATTERNS: existing similar implementations to follow; (3) RELATED: entry points, modules, tests. Thoroughness: quick.", description="Scout for reuse")
+```
+
+**CRITICAL - REUSE EXISTING RESOURCES:**
+- Scout MUST identify existing code to reuse before planning new code
+- If similar functionality exists → extend/modify, don't create new
+- If utility/helper exists → use it, don't duplicate
+- If pattern exists → follow it consistently
+
+### Step 4: Create Plan (Max 4 Phases)
+
+**Use `planner` sub-agent** to create the plan:
+```
+Task(subagent_type="planner", prompt="Create lite plan for [task-id]. Requirements: [summary]. REUSABLE RESOURCES: [scout findings - utils, services, patterns to reuse]. CRITICAL: Plan MUST use existing resources, NO duplicates. Max 4 phases, single file. Save to ./.claude/tasks/[task-id]/plan.md.", description="Create lite plan")
+```
+
+Plan structure:
+```markdown
+# Plan: [task-id]
+
+**Created:** [YYYY-MM-DD]
+**Type:** Lite Plan
+**Max Phases:** 4
+
+## Overview
+[Brief description of what will be implemented]
+
+## Reusable Resources (MUST USE)
+- **Utils/Helpers:** [existing utils to use - DO NOT recreate]
+- **Services:** [existing services to extend/use]
+- **Components:** [existing components to reuse]
+- **Patterns:** [existing patterns to follow]
+
+## Phases
+
+### Phase 1: [Name]
+**Status:** Pending
+**Files:** [list affected files]
+**Tasks:**
+- [ ] Task 1
+- [ ] Task 2
+
+### Phase 2: [Name] (if needed)
+**Status:** Pending
+**Files:** [list affected files]
+**Tasks:**
+- [ ] Task 1
+- [ ] Task 2
+
+### Phase 3: [Name] (if needed)
+**Status:** Pending
+**Files:** [list affected files]
+**Tasks:**
+- [ ] Task 1
+
+### Phase 4: Code Review
+**Status:** Pending
+**Tasks:**
+- [ ] Review code against ./docs/code-standards.md
+- [ ] Fix any issues
+
+## Success Criteria
+- [ ] All acceptance criteria from requirements.md met
+- [ ] No code standard violations
+```
+
+### Step 5: Update Active Task
+
+Update `./.claude/active-task` to point to this task (if not already).
+
+### Step 6: Summary Output
+
+```
+════════════════════════════════════════════════════════════════════
+                    📋 LITE PLAN CREATED
+════════════════════════════════════════════════════════════════════
+
+TASK: [task-id]
+PHASES: [N] (max 4)
+
+PHASE SUMMARY:
+  1. [Phase 1 name] - [brief]
+  2. [Phase 2 name] - [brief]
+  3. [Phase 3 name] - [brief]
+  4. Code Review
+
+FILES TO MODIFY:
+  • [file1]
+  • [file2]
+
+NEXT STEPS:
+  1. Review the plan in ./.claude/tasks/[task-id]/plan.md
+  2. If changes needed, run `/devkit:spec-lite:update-plan [task-id] [description]`
+  3. Run `/devkit:spec-lite:do [task-id]` to implement all phases
+
+Need to modify the plan? Run:
+  → /devkit:spec-lite:update-plan [task-id] [describe changes]
+
+Ready to implement? Run:
+  → /devkit:spec-lite:do [task-id]
+
+════════════════════════════════════════════════════════════════════
+```
+
+## Constraints
+
+- **MAX 4 PHASES** - Keep it simple
+- **NO RESEARCH** - Use existing docs only
+- **NO TESTS IN PLAN** - Testing (unit tests, E2E tests, integration tests) is handled separately via `/devkit:spec-lite:test` command
+- **SINGLE PLAN FILE** - No separate phase files
+- **MAX 2 SUB-AGENTS** - scout + planner only
+- For larger tasks, use full `/devkit:spec:plan` instead
+
+## Important Notes
+
+- **CRITICAL:** Follow `./.claude/rules/index.md` for code quality standards
+- **CRITICAL:** Follow `./docs/development-rules.md` if exists
+- This is for SMALL tasks only
+- If task seems too complex for 4 phases, suggest using full spec workflow
+- Always include final phase for code review
+- **DO NOT** start implementing

package/templates/.claude/commands/devkit/spec-lite/task.md

@@ -0,0 +1,141 @@
+---
+description: Create a lightweight task with inline requirements
+argument-hint: [task-id] [description]
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, Glob, Task, Skill
+---
+
+<!--
+Usage: /devkit:spec-lite:task [task-id] [description]
+Example: /devkit:spec-lite:task fix-login-bug Fix the login redirect issue
+Example: /devkit:spec-lite:task add-logout Add logout button to navbar
+-->
+
+**MUST READ** `CLAUDE.md` to understand orchestration rules before proceeding.
+
+## Your Mission
+
+Create a lightweight task for: **$ARGUMENTS**
+
+This is for SMALL tasks that don't need research or extensive planning.
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+- **task-id**: First word (kebab-case or ticket format)
+- **description**: Remaining text
+
+If task-id not provided, use `AskUserQuestion` to ask user.
+If description not provided (only task-id given), use `AskUserQuestion` to ask user for task description.
+
+### Step 2: Get Current Date
+
+```bash
+# Get current date for timestamps
+date +%Y-%m-%d
+```
+
+### Step 3: Check Existing Task
+
+- Check if `./.claude/tasks/[task-id]/` already exists
+- If exists, use `AskUserQuestion` tool to ask user: continue with existing or reset?
+
+### Step 4: Gather Acceptance Criteria
+
+**Use `AskUserQuestion`** to gather acceptance criteria from user:
+- Question: "What are the acceptance criteria for this task? (Enter each criterion, or 'skip' to add later)"
+- This helps define clear success conditions upfront
+
+### Step 5: Create Minimal Structure
+
+```
+./.claude/tasks/[task-id]/
+├── README.md
+├── requirements.md    (inline requirements - single file)
+└── plan.md            (inline plan - single file)
+```
+
+### Step 6: Create README.md
+
+```markdown
+# Task: [task-id]
+
+**Created:** [YYYY-MM-DD from Step 2]
+**Type:** Lite (small task)
+**Status:** Initialized
+
+## Description
+[description from arguments]
+
+## Next Steps
+1. Run `/devkit:spec-lite:plan [task-id]` to create implementation plan
+2. Run `/devkit:spec-lite:do [task-id]` to implement
+```
+
+### Step 7: Create requirements.md
+
+```markdown
+# Requirements: [task-id]
+
+## Description
+[description from arguments]
+
+## Acceptance Criteria
+[criteria from Step 4, or placeholder if skipped]
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Scope
+<!-- What's in scope and out of scope -->
+
+## Notes
+<!-- Any additional context -->
+```
+
+### Step 8: Set Active Task
+
+Create/update `./.claude/active-task` file:
+```
+./.claude/tasks/[task-id]
+```
+
+This allows other commands to detect the current active task.
+
+### Step 9: Summary Output
+
+```
+════════════════════════════════════════════════════════════════════
+                    📁 LITE TASK CREATED
+════════════════════════════════════════════════════════════════════
+
+TASK ID: [task-id]
+LOCATION: ./.claude/tasks/[task-id]/
+ACTIVE: Yes (set as active task)
+
+FILES CREATED:
+  ✅ README.md
+  ✅ requirements.md
+  ✅ plan.md
+
+ACCEPTANCE CRITERIA:
+  [list criteria or "To be defined in requirements.md"]
+
+NEXT STEPS:
+  1. Run `/devkit:spec-lite:plan [task-id]` to create quick plan (max 4 phases)
+  2. Run `/devkit:spec-lite:do [task-id]` to implement all phases
+
+Ready to plan? Run:
+  → /devkit:spec-lite:plan [task-id]
+
+════════════════════════════════════════════════════════════════════
+```
+
+## Important Notes
+
+- **CRITICAL:** Follow `./.claude/rules/index.md` for code quality standards
+- This is for SMALL tasks only
+- No research folder - keep it lightweight
+- Requirements in single file, not separate functional/non-functional
+- Active task tracking enables continuity across sessions
+- **DO NOT** start planning or implementing

package/templates/.claude/commands/devkit/spec-lite/test.md

@@ -0,0 +1,171 @@
+---
+description: Run tests and achieve 100% coverage for a lite task, file-by-file
+argument-hint: [task-id]
+allowed-tools: Read, Write, Edit, Task, Bash, Grep, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /devkit:spec-lite:test [task-id]
+Example: /devkit:spec-lite:test fix-login-bug
+Requires: Task with implementation in ./.claude/tasks/[task-id]/
+-->
+
+**MUST READ** `CLAUDE.md` before proceeding.
+
+## Your Mission
+
+Create and run tests for lite task: **$ARGUMENTS**
+
+Process files **ONE BY ONE** - achieve 100% coverage per file before moving to next.
+
+## Primary Sub-Agent
+
+| Agent | Purpose |
+|-------|---------|
+| `tester` | Test creation, execution, coverage per file, fix failures |
+
+---
+
+## Workflow
+
+### Step 0: Setup & Validation
+
+#### Step 0.1: 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.
+
+#### Step 0.2: Validate & Collect Files
+
+1. If task-id not provided, check `./.claude/active-task` or use `AskUserQuestion` tool to ask user
+2. Verify `./.claude/tasks/$ARGUMENTS/plan.md` exists
+3. If not found: "Plan not found. Run `/devkit:spec-lite:plan` first."
+4. **Collect files created/modified by this task:**
+   - Read plan.md to identify files
+   - Build list of source files needing tests
+
+**Output:** `✓ Step 0: [task-id] - [N] source files to test`
+
+---
+
+### Step 1: Process Each File (REPEAT FOR EACH FILE)
+
+**For each file [filename]:**
+
+#### 1.1: Check Existing Tests
+
+```
+Task(subagent_type="tester", prompt="
+FILE: [full-path-to-source-file]
+
+CHECK:
+1. Does test file exist?
+2. If YES: Run tests, report status
+3. If tests FAIL: Fix until all pass
+4. Report current coverage for THIS FILE
+
+OUTPUT: { hasTests: bool, testsPass: bool, coverage: X% }
+", description="Check existing tests for [filename]")
+```
+
+#### 1.2: Create Tests Until 100%
+
+**REPEAT until file = 100% coverage:**
+
+```
+Task(subagent_type="tester", prompt="
+FILE: [full-path-to-source-file]
+CURRENT COVERAGE: [X]%
+
+DO:
+1. Identify uncovered lines/branches
+2. Write tests for uncovered code
+3. Run tests - fix any failures
+4. Check coverage again
+
+TARGET: 100% coverage for THIS FILE
+", description="Add tests for [filename]")
+```
+
+**After each iteration:**
+- Check file coverage
+- If < 100%, repeat
+- If = 100%, move to next file
+
+**Output per file:** `✓ [filename]: 100% - [N] tests`
+
+---
+
+### Step 2: Verify All Complete
+
+1. Run full test suite
+2. Verify each file at 100%
+3. All tests must pass
+
+**Output:** `✓ Step 2: All [N] files at 100% - [Total] tests passing`
+
+---
+
+### Step 3: Finalize
+
+1. Update task status via `project-manager` subagent:
+```
+Task(subagent_type="project-manager", prompt="Update lite task [task-id] test status: COMPLETE, 100% coverage.", description="Update status")
+```
+
+2. Generate test report at `./.claude/tasks/$ARGUMENTS/test-report.md`
+
+**Output:** `✓ Step 3: Report generated`
+
+---
+
+### Step 4: Summary
+
+```
+════════════════════════════════════════════════════════════════════
+                    ✅ LITE TASK TESTS COMPLETE
+════════════════════════════════════════════════════════════════════
+
+TASK: [task-id]
+
+FILES TESTED (each at 100%):
+  ✅ [file1.ts] - [N] tests
+  ✅ [file2.ts] - [N] tests
+
+TOTAL: [X] tests passed, 0 failed
+COVERAGE: 100%
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Critical Rules
+
+- **ONE FILE AT A TIME** - complete file before next
+- **FIX FAILURES FIRST** - before adding new tests
+- **100% per file** - not overall average
+- **DELEGATE to `tester`** - do not write tests manually
+- **SKIP ignored files** - test files, configs, types, etc.
+
+## Blocking Gates
+
+- Step 1: Each file must reach 100%
+- Step 2: All tests must pass
+- Step 3: Report must be generated

package/templates/.claude/commands/devkit/spec-lite/update-plan.md

@@ -0,0 +1,154 @@
+---
+description: Update an existing lite plan with new requirements or modifications
+argument-hint: "[task-id] [description of changes]"
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, Glob, Grep
+---
+
+<!--
+Usage: /devkit:spec-lite:update-plan [task-id] [description]
+Example: /devkit:spec-lite:update-plan fix-login-bug Add loading state during auth
+Requires: Task with plan in ./.claude/tasks/[task-id]/plan.md
+
+This is a LIGHTWEIGHT version - updates single plan.md file only.
+-->
+
+## Your Mission
+
+Update the lite plan for task **$ARGUMENTS** with new requirements or modifications.
+
+Quick update. Single file. Max 4 phases.
+
+---
+
+## Step 1: Parse Arguments
+
+1. **Extract arguments:**
+   - `[task-id]` = first argument (e.g., `fix-login-bug`)
+   - `[description]` = remaining text (the change)
+
+2. **If task-id missing:**
+   - Check `./.claude/active-task` first
+   - If not found, use `AskUserQuestion` to ask for it
+
+3. **If description missing:**
+   - Use `AskUserQuestion`: "What changes do you want to add to the plan?"
+
+---
+
+## Step 2: Validate
+
+1. Verify `./.claude/tasks/[task-id]/plan.md` exists
+2. If not found: "Plan not found. Run `/devkit:spec-lite:plan` first."
+
+---
+
+## Step 3: Read Existing Plan
+
+1. Read `./.claude/tasks/[task-id]/plan.md`
+2. Note current phases and their status
+3. Identify completed vs pending phases
+
+---
+
+## Step 4: Analyze Change
+
+Categorize the change:
+
+| Type | Action |
+|------|--------|
+| **ADD_TASKS** | Add tasks to existing phase |
+| **ADD_PHASE** | Add new phase (if under 4 total) |
+| **MODIFY_PHASE** | Change existing phase scope |
+| **REMOVE_TASKS** | Remove/descope tasks |
+| **CLARIFY** | Add details without structural change |
+
+**Constraint check:**
+- If adding phase would exceed 4: "Cannot add phase. Max 4 phases for lite plan. Use `/devkit:spec:plan` for complex tasks."
+
+---
+
+## Step 5: Confirm with User
+
+Use `AskUserQuestion`:
+```
+question: "I'll update the plan to: [interpreted change]. Proceed?"
+header: "Confirm"
+options:
+  - label: "Yes, update"
+    description: "Apply the changes to plan.md"
+  - label: "Let me clarify"
+    description: "I'll explain the change differently"
+```
+
+---
+
+## Step 6: Update plan.md
+
+Apply changes to `./.claude/tasks/[task-id]/plan.md`:
+
+1. **For ADD_TASKS:** Add new tasks under appropriate phase
+2. **For ADD_PHASE:** Insert new phase (keep code review last)
+3. **For MODIFY_PHASE:** Update phase description/tasks
+4. **For REMOVE_TASKS:** Mark tasks as ~~removed~~ or delete
+5. **For CLARIFY:** Add clarifying notes
+
+**CRITICAL:**
+- Code review phase must remain LAST
+- Never exceed 4 phases
+- Preserve completed work
+
+**Add change log entry at bottom:**
+```markdown
+## Change Log
+| Date | Change |
+|------|--------|
+| [today] | [brief description of change] |
+```
+
+---
+
+## Step 7: Summary
+
+```
+════════════════════════════════════════════════════════════════════
+                    📝 LITE PLAN UPDATED
+════════════════════════════════════════════════════════════════════
+
+TASK: [task-id]
+CHANGE: [ADD_TASKS | ADD_PHASE | MODIFY_PHASE | REMOVE_TASKS | CLARIFY]
+
+WHAT CHANGED:
+  [Brief description]
+
+PHASES NOW:
+  1. [Phase 1] - [status]
+  2. [Phase 2] - [status]
+  3. [Phase 3] - [status]
+  4. Code Review - Pending
+
+NEXT STEPS:
+  → Review: ./.claude/tasks/[task-id]/plan.md
+  → Implement: /devkit:spec-lite:do [task-id]
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Constraints
+
+- **MAX 4 PHASES** - Cannot exceed this limit
+- **SINGLE FILE** - Only updates plan.md
+- **PRESERVE COMPLETED** - Never modify completed phases
+- **CODE REVIEW LAST** - Always keep as final phase
+- **NO RESEARCH** - Just update the plan file
+- For complex changes, suggest `/devkit:spec:update-plan` instead
+
+---
+
+## Important Notes
+
+- **CRITICAL:** Follow `./.claude/rules/index.md` for code quality
+- This is LIGHTWEIGHT - for quick plan adjustments only
+- If change is too complex for 4 phases, suggest full spec workflow
+- **DO NOT** start implementing