ai-qakit 1.0.0

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

@@ -0,0 +1,148 @@
+---
+description: AI-DevKit usage guide - just type naturally
+argument-hint: [category|command|task description]
+---
+
+Think harder.
+All-in-one AI-DevKit guide. Run the script and present output based on type markers.
+
+## Pre-Processing
+
+**IMPORTANT: Always translate `$ARGUMENTS` to English before passing to script.**
+
+The Python script only understands English keywords. If `$ARGUMENTS` is in another language:
+1. Translate `$ARGUMENTS` to English
+2. Pass the translated English string to the script
+
+## Execution
+
+```bash
+python .claude/scripts/helper.py "$ARGUMENTS"
+```
+
+## Output Type Detection
+
+The script outputs a type marker on the first line: `@OUTPUT_TYPE:<type>`
+
+**Read this marker and adjust your presentation accordingly:**
+
+### `@OUTPUT_TYPE:comprehensive-docs`
+
+Full documentation (config, schema, setup guides).
+
+**Presentation:**
+1. Show the **COMPLETE** script output verbatim - every section, every code block
+2. **THEN ADD** helpful context:
+   - Real-world usage examples ("For example, if you're working on multiple projects...")
+   - Common gotchas and tips ("Watch out for: ...")
+   - Practical scenarios ("This is useful when...")
+3. End with a specific follow-up question
+
+**Example enhancement after showing full output:**
+```
+## Additional Tips
+
+**When to use global vs local config:**
+- Use global (~/.claude/) for personal preferences like language, issue prefix style
+- Use local (./.claude/) for project-specific paths, naming conventions
+
+**Common setup for teams:**
+Each team member sets their locale globally, but projects share local config via git.
+
+Need help setting up a specific configuration?
+```
+
+### `@OUTPUT_TYPE:category-guide`
+
+Workflow guides for command categories (fix, spec, review, frontend, etc.).
+
+**Presentation:**
+1. Show the complete workflow and command list
+2. **ADD** practical context:
+   - When to use this workflow vs alternatives
+   - Real example: "If you encounter a bug in authentication, start with..."
+   - Transition tips between commands
+3. Offer to help with a specific task
+
+### `@OUTPUT_TYPE:command-details`
+
+Single command documentation.
+
+**Presentation:**
+1. Show full command info from script
+2. **ADD**:
+   - Concrete usage example with realistic input
+   - When this command shines vs alternatives
+   - Common flags or variations
+3. Offer to run the command for them
+
+### `@OUTPUT_TYPE:search-results`
+
+Search matches for a keyword.
+
+**Presentation:**
+1. Show all matches from script
+2. **HELP** user navigate:
+   - Group by relevance if many results
+   - Suggest most likely match based on context
+   - Offer to explain any specific command
+3. Ask what they're trying to accomplish
+
+### `@OUTPUT_TYPE:task-recommendations`
+
+Task-based command suggestions.
+
+**Presentation:**
+1. Show recommended commands from script
+2. **EXPLAIN** the reasoning:
+   - Why these commands fit the task
+   - Suggested order of execution
+   - What each step accomplishes
+3. Offer to start with the first recommended command
+
+## Key Principle
+
+**Script output = foundation. Your additions = value-add.**
+
+Never replace or summarize the script output. Always show it fully, then enhance with your knowledge and context.
+
+## Important: Correct Workflows
+
+**Spec Workflow** (complex features that require brainstorming - if you only have a vague idea, use this):
+- `/devkit:spec:task` → `/devkit:spec:brainstorm` → `/devkit:spec:plan` → `/devkit:spec:implement` → `/devkit:spec:test`
+
+**Spec Workflow** (complex features with unclear requirements - need deep analysis):
+- `/devkit:spec:task` → `/devkit:spec:capture-requirement` → `/devkit:spec:plan` → `/devkit:spec:implement` → `/devkit:spec:test`
+- Use `/devkit:spec:deep-capture-requirement` for promax version with extensive codebase analysis
+
+**Spec Workflow** (updating existing task requirements with new changes):
+- `/devkit:spec:update-requirement [task-id] [changes]` → `/devkit:spec:update-plan [task-id] [changes]` → `/devkit:spec:implement` → `/devkit:spec:test`
+
+**Spec Workflow** (updating existing plan with new changes):
+- `/devkit:spec:update-plan [task-id] [changes]` → `/devkit:spec:implement` → `/devkit:spec:test`
+
+**Spec-Lite Workflow** (quick small tasks):
+- `/devkit:spec-lite:task` → `/devkit:spec-lite:plan` → `/devkit:spec-lite:do` → `/devkit:spec-lite:test`
+
+**Fix Workflow**:
+- `/devkit:fix` auto-routes to `/devkit:fix:fast` or `/devkit:fix:hard`
+- Use `/debug` first if cause is unknown
+
+**Code Quality**:
+- `/devkit:review:code` → `/devkit:refactor` for cleanup
+
+- **`/devkit:spec:cook`**: Standalone - plans internally, no separate `/plan` needed
+
+- **NEVER** suggest `/devkit:spec:plan` → `/devkit:spec:cook` (cook has its own planning)
+
+**IMPORTANT**: Command `devkit:spec:task` is the only command that can be used to create a new task. User should provide a task-id for this to work. (eg. `devkit:spec:task AIDEVKIT-001`)
+
+## Version & Changelog
+
+Users can ask about the AI-DevKit version and see recent changes using these keywords:
+- `version`, `v`, `what version`, `devkit version`
+- `changelog`, `changes`, `what's new`, `updates`, `release notes`
+
+Example: `/devkit:help version` or `/devkit:help changelog`
+
+This will display the current version from `.claude/settings.json` (env.AI_DEVKIT_VERSION) and the last 2 changelog entries from `.claude/CHANGELOG.md`.

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

@@ -0,0 +1,510 @@
+---
+description: Code refactoring with simplification and verification gates
+argument-hint: [file-path] | [function-name] | [module]
+allowed-tools: Read, Write, Edit, Grep, Bash, Task, AskUserQuestion, Skill
+---
+
+<!--
+Usage: /refactor [file-path] | [function-name] | [module]
+Requires: Tests configured for verification
+Example: /refactor src/services/auth.service.ts
+Example: /refactor "handlePayment function"
+Example: /refactor src/utils/
+-->
+
+# Refactor - Code Simplification with Quality Verification
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+Orchestrates code simplification with skeptical review and verification.
+
+## Input Validation
+
+### Validate Refactoring Target ($ARGUMENTS)
+
+If $ARGUMENTS not provided:
+  Jump to Phase 1 "Target Selection" and use `AskUserQuestion` tool to ask user what to refactor
+
+If $ARGUMENTS provided:
+  Determine if it's a file path, function name, or module:
+
+  If looks like file path (contains / or file extension):
+    Check file exists: !`test -f "$ARGUMENTS" && echo "EXISTS" || echo "MISSING"`
+
+    If MISSING:
+      - Show error: "File not found: $ARGUMENTS"
+      - List similar files: !`find . -name "*$(basename "$ARGUMENTS")*" -type f 2>/dev/null | head -10`
+      - Use `AskUserQuestion` tool to ask user for correct path or use "Help me find candidates" option
+      - Do not proceed
+
+    If EXISTS:
+      - Proceed with refactoring for file @$ARGUMENTS
+
+  Otherwise (function name or module):
+    - Proceed with target identification in Phase 1
+
+## Agents Used
+- **code-simplifier** - Expert refactoring without changing behavior
+- **tattletale-reporter** - Verify no shortcuts, demand proof
+
+## Skills Applied
+- **code-review** - Verification gates before completion
+- **sequential-thinking** - Step-by-step refactoring approach
+
+---
+
+## Phase 0: Project Context
+
+**IMPORTANT:** Read project context first.
+
+```bash
+# Read CLAUDE.md for tech stack
+cat CLAUDE.md 2>/dev/null || cat .claude/CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found"
+```
+
+Extract from CLAUDE.md:
+- **Language**: [TypeScript/JavaScript/Python/Go/Rust/Java/etc.]
+- **Framework**: [NestJS/Express/FastAPI/Django/Gin/Spring/etc.]
+- **Testing**: [Jest/Vitest/Pytest/Go test/etc.]
+- **Linting**: [ESLint/Ruff/golangci-lint/Clippy/etc.]
+
+If CLAUDE.md not found, detect from files:
+```bash
+# Detect language
+ls *.ts *.tsx 2>/dev/null && echo "TypeScript detected"
+ls *.py 2>/dev/null && echo "Python detected"
+ls *.go 2>/dev/null && echo "Go detected"
+ls *.rs 2>/dev/null && echo "Rust detected"
+ls *.java 2>/dev/null && echo "Java detected"
+cat package.json 2>/dev/null | head -5
+cat pyproject.toml 2>/dev/null | head -5
+cat go.mod 2>/dev/null | head -5
+cat Cargo.toml 2>/dev/null | head -5
+```
+
+---
+
+## Phase 1: Target Selection
+
+### Identify Refactoring Target
+
+If $ARGUMENTS provided, analyze it. Otherwise:
+
+```
+Question: What should I refactor?
+Header: Refactor Target
+Options:
+  - Specific file (I'll provide path)
+  - Specific function/method
+  - Entire module/directory
+  - Code with specific smell (duplicates, complexity, etc.)
+  - Help me find candidates
+```
+
+### Find Refactoring Candidates (Language-Aware)
+
+```bash
+# TypeScript/JavaScript
+if [ -f "package.json" ]; then
+  find . -name "*.ts" -o -name "*.js" -o -name "*.tsx" -o -name "*.jsx" 2>/dev/null | grep -v node_modules | xargs wc -l 2>/dev/null | sort -rn | head -10
+  grep -c "function\|const.*=.*=>\|class " --include="*.ts" --include="*.js" . -r 2>/dev/null | grep -v node_modules | sort -t: -k2 -rn | head -10
+fi
+
+# Python
+if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
+  find . -name "*.py" 2>/dev/null | grep -v __pycache__ | grep -v .venv | xargs wc -l 2>/dev/null | sort -rn | head -10
+  grep -c "def \|class " --include="*.py" . -r 2>/dev/null | grep -v __pycache__ | sort -t: -k2 -rn | head -10
+fi
+
+# Go
+if [ -f "go.mod" ]; then
+  find . -name "*.go" 2>/dev/null | grep -v vendor | xargs wc -l 2>/dev/null | sort -rn | head -10
+  grep -c "func " --include="*.go" . -r 2>/dev/null | grep -v vendor | sort -t: -k2 -rn | head -10
+fi
+
+# Rust
+if [ -f "Cargo.toml" ]; then
+  find . -name "*.rs" 2>/dev/null | grep -v target | xargs wc -l 2>/dev/null | sort -rn | head -10
+  grep -c "fn \|impl " --include="*.rs" . -r 2>/dev/null | grep -v target | sort -t: -k2 -rn | head -10
+fi
+
+# Java
+if [ -f "pom.xml" ] || [ -f "build.gradle" ]; then
+  find . -name "*.java" 2>/dev/null | grep -v target | grep -v build | xargs wc -l 2>/dev/null | sort -rn | head -10
+  grep -c "public.*\|private.*\|protected.*" --include="*.java" . -r 2>/dev/null | sort -t: -k2 -rn | head -10
+fi
+```
+
+---
+
+## Phase 2: Analysis
+
+**Apply:** `sequential-thinking` skill
+
+### Thought 1/N: Understand Current Code
+
+Read and analyze target:
+
+```
+════════════════════════════════════════════════════════════════════
+                    📊 CODE ANALYSIS
+════════════════════════════════════════════════════════════════════
+
+TARGET: [file/function/module]
+LANGUAGE: [from CLAUDE.md or detection]
+LINES: [line count]
+
+CURRENT STATE:
+  - Complexity: [assessment]
+  - Readability: [assessment]
+  - Duplication: [assessment]
+  - Test Coverage: [assessment]
+
+CODE SMELLS DETECTED:
+  □ [Smell 1] - [location]
+  □ [Smell 2] - [location]
+  □ [Smell 3] - [location]
+
+PUBLIC API:
+  - [Function/method 1] - MUST PRESERVE
+  - [Function/method 2] - MUST PRESERVE
+
+DEPENDENCIES:
+  - Used by: [files that import this]
+  - Uses: [files this imports]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Language-Specific Code Smells
+
+**TypeScript/JavaScript:**
+- Callback hell / Promise chains without async/await
+- `any` type usage
+- Nested ternaries
+- Large switch statements
+- Prop drilling in React
+
+**Python:**
+- Mutable default arguments
+- Nested list comprehensions
+- God classes
+- Long parameter lists
+- Too many nested contexts
+
+**Go:**
+- Ignored errors (using `_`)
+- Deeply nested if/else
+- Large functions
+- Missing defer cleanup
+- Global state
+
+**Rust:**
+- Unnecessary clones
+- Complex match arms
+- Missing error context
+- Long lifetimes
+- Unwrap/expect in library code
+
+**Java:**
+- Checked exception abuse
+- Null checks everywhere
+- Large constructors
+- Static method abuse
+- Missing builders for complex objects
+
+### Identify Issues
+
+```
+REFACTORING OPPORTUNITIES:
+
+1. [Issue: e.g., "Duplicated validation logic"]
+   - Location: lines X-Y and A-B
+   - Impact: Maintenance burden, inconsistency risk
+   - Approach: Extract to shared function
+
+2. [Issue: e.g., "Deep nesting"]
+   - Location: lines X-Y
+   - Impact: Hard to read and test
+   - Approach: Early returns, extract methods
+
+3. [Issue: e.g., "God function"]
+   - Location: functionName()
+   - Impact: 200+ lines, multiple responsibilities
+   - Approach: Split into focused functions
+```
+
+---
+
+## Phase 3: Refactoring Plan
+
+### Present Plan
+
+```
+════════════════════════════════════════════════════════════════════
+                    📋 REFACTORING PLAN
+════════════════════════════════════════════════════════════════════
+
+GOAL: [What we're improving]
+LANGUAGE: [detected language]
+
+CONSTRAINTS:
+  ✓ Preserve all public APIs
+  ✓ Maintain all external behavior
+  ✓ Keep tests passing
+  ✓ No new dependencies
+  ✓ Follow [language] idioms
+
+REFACTORING STEPS:
+
+Step 1: [Action - e.g., "Extract validation helper"]
+  - Before: [brief description]
+  - After: [brief description]
+  - Risk: Low
+
+Step 2: [Action - e.g., "Simplify conditionals"]
+  - Before: [brief description]
+  - After: [brief description]
+  - Risk: Low
+
+Step 3: [Action - e.g., "Rename for clarity"]
+  - Before: [brief description]
+  - After: [brief description]
+  - Risk: Low
+
+EXPECTED IMPROVEMENTS:
+  - Lines: [before] → [after] ([X]% reduction)
+  - Complexity: [before] → [after]
+  - Duplication: [before] → [after]
+
+════════════════════════════════════════════════════════════════════
+```
+
+### Get Approval
+
+```
+Question: Approve this refactoring plan?
+Header: Plan Review
+Options:
+  - Yes, proceed with refactoring
+  - Modify the plan
+  - Skip certain steps
+  - Need more analysis
+```
+
+---
+
+## Phase 4: Execute Refactoring
+
+**Spawn:** `code-simplifier` agent
+
+### Code Simplifier Instructions
+
+```
+You are refactoring [LANGUAGE] code. Follow these STRICT rules:
+
+1. PRESERVE BEHAVIOR
+   - All public method signatures unchanged
+   - All return values unchanged
+   - All side effects unchanged
+   - All error handling unchanged
+
+2. SIMPLIFICATION TECHNIQUES (language-agnostic):
+   - Reduce complexity: Early returns, guard clauses
+   - Eliminate redundancy: DRY, extract shared logic
+   - Improve naming: Descriptive, intent-revealing names
+   - Extract methods: Single responsibility
+   - Simplify data structures: Appropriate types
+   - Remove dead code: Unreachable paths
+   - Clarify logic: Happy path obvious
+
+3. LANGUAGE-SPECIFIC PATTERNS:
+
+   TypeScript/JavaScript:
+   - Use async/await over callbacks/promises
+   - Use optional chaining (?.) and nullish coalescing (??)
+   - Prefer const over let
+   - Use destructuring
+   - Use template literals
+
+   Python:
+   - Use list/dict comprehensions appropriately
+   - Use context managers (with statements)
+   - Use dataclasses or Pydantic models
+   - Use walrus operator (:=) where readable
+   - Follow PEP 8
+
+   Go:
+   - Handle all errors explicitly
+   - Use defer for cleanup
+   - Use named returns for clarity
+   - Prefer composition over inheritance
+   - Use interfaces for abstraction
+
+   Rust:
+   - Use ? operator for error propagation
+   - Avoid unnecessary clones
+   - Use iterators over loops
+   - Leverage pattern matching
+   - Use Result/Option appropriately
+
+   Java:
+   - Use Optional over null checks
+   - Use streams where appropriate
+   - Use records for data classes
+   - Use builders for complex objects
+   - Prefer interfaces
+
+4. FOR EACH CHANGE:
+   - Show before/after
+   - Explain improvement
+   - Verify behavior preserved
+
+5. QUALITY CHECKS:
+   - Tests still pass (run them)
+   - No new warnings
+   - Complexity actually reduced
+
+REFACTORING STEPS TO EXECUTE:
+[paste steps from plan]
+```
+
+### Step-by-Step Execution
+
+For each refactoring step:
+
+```
+════════════════════════════════════════════════════════════════════
+                    STEP [N]: [Action]
+════════════════════════════════════════════════════════════════════
+
+BEFORE:
+```[language]
+[original code]
+```
+
+AFTER:
+```[language]
+[refactored code]
+```
+
+IMPROVEMENT:
+  - [What's better]
+
+BEHAVIOR CHECK:
+  - Public API: ✓ Unchanged
+  - Side effects: ✓ Unchanged
+  - Error handling: ✓ Unchanged
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 5: Verification
+
+**Spawn:** `tattletale-reporter` agent
+**Apply:** `code-review` skill (verification gates)
+
+### Tattletale Verification
+
+```
+Verify this refactoring. Be SKEPTICAL:
+
+1. BEHAVIOR PRESERVED?
+   - Run tests: show me the output
+   - Compare public API before/after
+   - Check all edge cases still handled
+
+2. ACTUALLY SIMPLER?
+   - Is it genuinely more readable?
+   - Did complexity actually decrease?
+   - Or did we just move complexity around?
+
+3. NO SHORTCUTS?
+   - Were any steps skipped?
+   - Any "temporary" code introduced?
+   - Any TODO comments added?
+
+4. COMPLETE?
+   - All planned refactorings done?
+   - No half-finished changes?
+
+DEMAND EVIDENCE:
+- "Show me the test output"
+- "Prove behavior is unchanged"
+- "Show complexity metrics before/after"
+```
+
+### Verification Gates (Language-Specific)
+
+```bash
+# TypeScript/JavaScript
+npm test 2>&1 || yarn test 2>&1 || pnpm test 2>&1 || echo "JS tests skipped"
+npm run lint 2>&1 || yarn lint 2>&1 || pnpm lint 2>&1 || echo "JS lint skipped"
+npx tsc --noEmit 2>&1 || echo "TypeScript check skipped"
+
+# Python
+pytest 2>&1 || python -m pytest 2>&1 || echo "Python tests skipped"
+ruff check . 2>&1 || flake8 . 2>&1 || echo "Python lint skipped"
+mypy . 2>&1 || echo "Python type check skipped"
+
+# Go
+go test ./... 2>&1 || echo "Go tests skipped"
+go vet ./... 2>&1 || echo "Go vet skipped"
+golangci-lint run 2>&1 || echo "Go lint skipped"
+
+# Rust
+cargo test 2>&1 || echo "Rust tests skipped"
+cargo clippy 2>&1 || echo "Clippy skipped"
+cargo fmt --check 2>&1 || echo "Rust fmt skipped"
+
+# Java
+./gradlew test 2>&1 || mvn test 2>&1 || echo "Java tests skipped"
+./gradlew check 2>&1 || mvn verify 2>&1 || echo "Java check skipped"
+```
+
+---
+
+## Phase 6: Summary
+
+```
+════════════════════════════════════════════════════════════════════
+                    ✅ REFACTORING COMPLETE
+════════════════════════════════════════════════════════════════════
+
+TARGET: [file/function/module]
+LANGUAGE: [detected language]
+
+METRICS:
+  ┌─────────────────┬──────────┬──────────┬──────────┐
+  │ Metric          │ Before   │ After    │ Change   │
+  ├─────────────────┼──────────┼──────────┼──────────┤
+  │ Lines of Code   │ [X]      │ [Y]      │ [-Z%]    │
+  │ Functions       │ [X]      │ [Y]      │ [+/-Z]   │
+  │ Max Nesting     │ [X]      │ [Y]      │ [-Z]     │
+  │ Duplications    │ [X]      │ [Y]      │ [-Z]     │
+  └─────────────────┴──────────┴──────────┴──────────┘
+
+CHANGES MADE:
+  ✓ [Change 1]
+  ✓ [Change 2]
+  ✓ [Change 3]
+
+VERIFICATION:
+  ✓ Tests: All passing
+  ✓ Lint: No errors
+  ✓ Types: Valid (if applicable)
+  ✓ Behavior: Unchanged
+
+BEFORE/AFTER COMPARISON:
+  [Key code snippet showing improvement]
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Begin Now
+
+What code would you like to refactor?