ai-qakit 1.0.0

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

@@ -0,0 +1,156 @@
+---
+description: Create a new task folder structure
+argument-hint: [task-id]
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, Glob, Grep, Skill
+---
+
+<!--
+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, use `AskUserQuestion` to ask user
+- Task ID should be kebab-case or ticket format (e.g., `ABC-123`, `feature-name`)
+
+### Step 2: Check Existing Task
+- Check if `./.claude/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 `./.claude/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
+
+```
+./.claude/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
+
+### Option A: AI-Assisted (If you not too sure about the requirements)
+1. `/devkit:spec:brainstorm [task-id]` - Let AI explore solutions and ideas
+
+### Option B: Manual First
+1. Add requirements manually to `./requirements/` folder
+2. Then `/devkit:spec:update-requirement [task-id]` - AI validates & enhances your requirements
+2. Or `/devkit:spec:capture-requirement [task-id]` - AI researches & futher enhances requirements (more detailed)
+
+### Then Continue With
+3. `/devkit:spec:plan [task-id]` - 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: ./.claude/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 not too sure about the requirements)
+1. `/devkit:spec:brainstorm [task-id]` - Let AI explore solutions and ideas
+
+Option B: Manual First
+1. Add requirements manually to `./requirements/` folder
+2. Then `/devkit:spec:capture-requirement [task-id]` - AI validates & enhances your requirements
+2. Or `/devkit:spec:deep-capture-requirement [task-id]` - AI researches & futher enhances requirements (more detailed)
+
+Then Continue With
+3. `/devkit:spec:plan [task-id]` - Create implementation plan
+
+```
+
+## Important Notes
+
+- **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/.claude/commands/devkit/spec/test.md

@@ -0,0 +1,259 @@
+---
+description: Create comprehensive tests with 100% code coverage for an existing task
+argument-hint: [task-id]
+allowed-tools: Read, Write, Edit, Task, Bash, Grep, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /spec:test [task-id]
+Example: /spec:test ABC-123
+Example: /spec:test TICKET-456
+Requires: Task must exist with implementation in ./.claude/tasks/[task-id]/
+-->
+
+**MUST READ** `CLAUDE.md` then **THINK HARDER** to create comprehensive tests for the following task:
+<task-id>$ARGUMENTS</task-id>
+
+---
+
+## Phase 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 Task & Collect Files
+
+1. If task-id not provided, use `AskUserQuestion` to ask for it
+2. Verify `./.claude/tasks/$ARGUMENTS/` directory exists
+3. If not found, return error: "Task not found. Run `/devkit:spec:task` first."
+4. Verify `./.claude/tasks/$ARGUMENTS/plan/plan.md` exists
+5. If not found, return error: "Plan not found. Run `/devkit:spec:plan` first."
+6. **Collect all files created/modified by this task:**
+   - Read plan phases to identify files created/modified
+   - Check git diff or file timestamps if available
+   - Build list of source files that need tests
+
+**Output:** `✓ Phase 0: Task [task-id] validated - [N] source files to test`
+
+---
+
+## Role Responsibilities
+
+- You are an **orchestrator** that delegates testing work to the `tester` sub-agent.
+- Process files **ONE BY ONE** - achieve 100% coverage on each file before moving to next.
+- The `tester` sub-agent handles test creation, execution, and fixing.
+
+**CRITICAL:** Follow file-by-file approach. Do not batch all files together.
+
+---
+
+## Primary Sub-Agent
+
+| Agent | Location | Purpose |
+|-------|----------|---------|
+| `tester` | `./.claude/agents/tester.md` | Test creation, execution, coverage analysis per file |
+
+---
+
+## Workflow: File-by-File Testing
+
+### Phase 1: Initialize File Queue
+
+1. Create ordered list of files to test from Phase 0
+2. Initialize TodoWrite with each file as a task
+3. 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
+
+```
+Task(subagent_type="tester", prompt="
+FILE: [full-path-to-source-file]
+TASK-ID: [task-id]
+
+CHECK:
+1. Does a test file exist 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% }
+", description="Check existing tests for [filename]")
+```
+
+#### Step 2.2: Analyze Coverage Gap
+
+```
+Task(subagent_type="tester", prompt="
+FILE: [full-path-to-source-file]
+CURRENT COVERAGE: [X]%
+
+ANALYZE:
+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
+", description="Analyze coverage for [filename]")
+```
+
+#### Step 2.3: Create Tests Until 100%
+
+**REPEAT this step until file coverage = 100%:**
+
+```
+Task(subagent_type="tester", prompt="
+FILE: [full-path-to-source-file]
+CURRENT COVERAGE: [X]%
+UNCOVERED: [list from Step 2.2]
+
+CREATE TESTS:
+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
+
+TARGET: 100% coverage for THIS FILE
+", description="Create tests for [filename] - iteration [N]")
+```
+
+**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. **Call** `project-manager` sub-agent: "Update task [task-id] test status to COMPLETE with 100% coverage."
+
+2. **Generate test report** at `./.claude/tasks/$ARGUMENTS/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]
+
+## Notes
+[Any observations or recommendations]
+```
+
+**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 Enforcement 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
+
+**REMEMBER:**
+- **DELEGATE to `tester` sub-agent** for all testing work
+- **ONE FILE AT A TIME** - complete file before next
+- **FIX FAILURES FIRST** - before adding new tests
+- **100% per file** - not just overall average

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

@@ -0,0 +1,263 @@
+---
+description: Update an existing implementation plan with new requirements or modifications
+argument-hint: "[task-id] [description of changes]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /devkit:spec:update-plan [task-id] [description]
+Example: /devkit:spec:update-plan ABC-123 Add caching layer for API responses
+Requires: Task must exist with plan in ./.claude/tasks/[task-id]/plan/
+
+This command updates an EXISTING plan with new requirements or modifications.
+It preserves existing phases while incorporating changes.
+-->
+
+Ultrathink
+
+## Your Mission
+
+Update the implementation plan for task **$ARGUMENTS** with new requirements or modifications.
+
+---
+
+## Phase 1: Parse Arguments & Validate
+
+1. **Parse arguments:**
+   - Extract `[task-id]` (first argument, e.g., `ABC-123`)
+   - Extract `[description]` (remaining text - the modification/new requirement)
+   - If task-id not provided, use `AskUserQuestion` to ask for it
+   - If description not provided, use `AskUserQuestion` to ask: "What changes or new requirements do you want to add to the plan?"
+
+2. **Validate task exists:**
+   - Check `./.claude/tasks/[task-id]/` directory exists
+   - If not found, return error: "Task not found. Run `/devkit:spec:task` first."
+
+3. **Validate plan exists:**
+   - Check `./.claude/tasks/[task-id]/plan/plan.md` exists
+   - If not found, return error: "Plan not found. Run `/devkit:spec:plan` first."
+
+---
+
+## Phase 2: Read Existing Plan
+
+1. **Read the main plan file:**
+   - Read `./.claude/tasks/[task-id]/plan/plan.md`
+   - Extract metadata (platform, api-approach, etc.)
+   - Note current phases and their status
+
+2. **Read all phase files:**
+   - List all files in `./.claude/tasks/[task-id]/plan/`
+   - Read each `phase-XX-*.md` file
+   - Build understanding of current plan structure
+   - Identify which phases are completed/in-progress/pending
+
+3. **Read requirements (if needed):**
+   - Read `./.claude/tasks/[task-id]/requirement/` files for context
+   - Understand the original scope
+
+---
+
+## Phase 3: Analyze Change Request
+
+1. **Understand the modification:**
+   - Analyze the user's description of changes
+   - Categorize the change type:
+     - **NEW_PHASE**: Adds entirely new functionality requiring new phase(s)
+     - **MODIFY_PHASE**: Changes existing phase scope or steps
+     - **REORDER**: Changes phase sequence or dependencies
+     - **REMOVE**: Removes or descopes a phase
+     - **REFINEMENT**: Clarifies or adds detail without structural change
+
+2. **Impact assessment:**
+   - Which existing phases are affected?
+   - Are new phases needed?
+   - Does this change dependencies between phases?
+   - Does this affect the API approach (schema-first/code-first)?
+
+3. **Confirm understanding with user:**
+   - Use `AskUserQuestion` to confirm interpretation:
+     ```
+     question: "I understand you want to: [interpreted change]. Is this correct?"
+     header: "Confirm"
+     options:
+       - label: "Yes, proceed"
+         description: "The interpretation is correct, update the plan"
+       - label: "Let me clarify"
+         description: "I'll provide more details about the change"
+     ```
+
+---
+
+## Phase 4: Update Plan Files
+
+### For NEW_PHASE changes:
+
+1. **Create new phase file(s):**
+   - Determine phase number (insert appropriately in sequence)
+   - Renumber existing phases if needed
+   - Create `phase-XX-new-phase-name.md` following the template:
+     - Context links
+     - Overview (date, description, priority, status)
+     - Key Insights
+     - Requirements (reference specific files)
+     - Architecture
+     - Related code files
+     - Implementation Steps
+     - Todo list
+     - Success Criteria
+     - Risk Assessment
+     - Security Considerations
+     - Next steps
+
+2. **Update `plan.md`:**
+   - Add new phase to phase list
+   - Update phase count
+   - Add change log entry
+
+### For MODIFY_PHASE changes:
+
+1. **Update affected phase file(s):**
+   - Read existing phase file
+   - Modify relevant sections
+   - Preserve completed steps
+   - Add new implementation steps as needed
+   - Update success criteria
+   - Add note about modification in the file
+
+2. **Update `plan.md`:**
+   - Update phase description if scope changed
+   - Add change log entry
+
+### For REORDER changes:
+
+1. **Renumber phase files:**
+   - Rename phase files with new numbers
+   - Update internal references
+   - Update dependencies
+
+2. **Update `plan.md`:**
+   - Reorder phase list
+   - Update dependencies
+   - Add change log entry
+
+### For REMOVE changes:
+
+1. **Mark phase as descoped:**
+   - Do NOT delete the file
+   - Add `status: DESCOPED` to phase file
+   - Add reason for removal
+   - Move file to `./.claude/tasks/[task-id]/plan/archive/` if preferred
+
+2. **Update `plan.md`:**
+   - Mark phase as descoped in phase list
+   - Update phase count
+   - Add change log entry
+
+### For REFINEMENT changes:
+
+1. **Update phase file(s):**
+   - Add clarifying details
+   - Update implementation steps
+   - Add/modify success criteria
+
+2. **Update `plan.md`:**
+   - Add change log entry
+
+---
+
+## Phase 5: Maintain Code Review Phase
+
+**CRITICAL:** Ensure `phase-XX-code-review.md` remains the FINAL phase.
+
+1. If new phases were added after code review, renumber code review to be last
+2. Update code review phase to include any new files from added phases
+3. Code review phase is NEVER removed or descoped
+
+---
+
+## Phase 6: Update Change Log
+
+Add entry to `plan.md` change log section:
+
+```markdown
+## Change Log
+
+| Date | Change Type | Description |
+|------|-------------|-------------|
+| [today's date] | [NEW_PHASE/MODIFY_PHASE/etc.] | [Brief description of change] |
+```
+
+---
+
+## Phase 7: Validation & Summary
+
+1. **Validate plan integrity:**
+   - All phases are properly numbered
+   - No gaps in phase sequence
+   - Dependencies are consistent
+   - Code review is final phase
+   - All phase files exist and are valid
+
+2. **Use `AskUserQuestion` to confirm:**
+   ```
+   question: "Plan updated. Would you like to review the changes?"
+   header: "Review"
+   options:
+     - label: "Show summary"
+       description: "Display summary of changes made"
+     - label: "Done"
+       description: "Changes look good, finish"
+   ```
+
+---
+
+## Summary Output
+
+```
+════════════════════════════════════════════════════════════════════
+                    📝 PLAN UPDATED
+════════════════════════════════════════════════════════════════════
+
+TASK: [task-id]
+CHANGE TYPE: [NEW_PHASE | MODIFY_PHASE | REORDER | REMOVE | REFINEMENT]
+
+MODIFICATION SUMMARY:
+  [Brief description of what was changed]
+
+FILES MODIFIED:
+  📄 ./.claude/tasks/[task-id]/plan/plan.md
+  📄 ./.claude/tasks/[task-id]/plan/phase-XX-*.md (if applicable)
+
+PHASE SUMMARY:
+  Total Phases: [count]
+  ✅ Completed: [count]
+  🔄 In Progress: [count]
+  ⏳ Pending: [count]
+
+CHANGES MADE:
+  [+] Added: [phase/step description] (if applicable)
+  [~] Modified: [phase/step description] (if applicable)
+  [-] Removed: [phase/step description] (if applicable)
+
+NEXT STEPS:
+  1. Review updated plan in ./.claude/tasks/[task-id]/plan/
+  2. Run `/devkit:spec:implement [task-id]` to continue implementation
+
+Ready to implement? Run:
+  → /devkit:spec:implement [task-id]
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Important Notes
+
+- **CRITICAL:** You MUST strictly follow `./.claude/rules/index.md` development rules.
+- **IMPORTANT:** This command UPDATES existing plans, it does NOT create new ones.
+- **IMPORTANT:** Preserve completed work - never remove or modify completed phases without explicit user confirmation.
+- **IMPORTANT:** Code review phase must ALWAYS remain the final phase.
+- **IMPORTANT:** Use `AskUserQuestion` when the scope of changes is ambiguous.
+- **IMPORTANT:** Add change log entries for traceability.
+- **IMPORTANT:** Do NOT start implementing - this command only updates the plan.