@gannonh/kata 0.1.4 → 0.2.0

package/commands/kata/audit-milestone.md

@@ -1,258 +1,20 @@
 ---
-name: kata:audit-milestone
+name: audit-milestone
 description: Audit milestone completion against original intent before archiving
-argument-hint: "[version]"
+argument-hint: [version]
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
-  - Glob
-  - Grep
-  - Bash
-  - Task
   - Write
+  - Bash
 ---
 
-<objective>
-Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
-
-**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
-</objective>
-
-<execution_context>
-<!-- Spawns kata-integration-checker agent which has all audit expertise baked in -->
-</execution_context>
-
-<context>
-Version: $ARGUMENTS (optional — defaults to current milestone)
-
-**Original Intent:**
-@.planning/PROJECT.md
-@.planning/REQUIREMENTS.md
-
-**Planned Work:**
-@.planning/ROADMAP.md
-@.planning/config.json (if exists)
-
-**Completed Work:**
-Glob: .planning/phases/*/*-SUMMARY.md
-Glob: .planning/phases/*/*-VERIFICATION.md
-</context>
-
-<process>
-
-## 1. Determine Milestone Scope
-
-```bash
-# Get phases in milestone
-ls -d .planning/phases/*/ | sort -V
-```
-
-- Parse version from arguments or detect current from ROADMAP.md
-- Identify all phase directories in scope
-- Extract milestone definition of done from ROADMAP.md
-- Extract requirements mapped to this milestone from REQUIREMENTS.md
-
-## 2. Read All Phase Verifications
-
-For each phase directory, read the VERIFICATION.md:
-
-```bash
-cat .planning/phases/01-*/*-VERIFICATION.md
-cat .planning/phases/02-*/*-VERIFICATION.md
-# etc.
-```
-
-From each VERIFICATION.md, extract:
-- **Status:** passed | gaps_found
-- **Critical gaps:** (if any — these are blockers)
-- **Non-critical gaps:** tech debt, deferred items, warnings
-- **Anti-patterns found:** TODOs, stubs, placeholders
-- **Requirements coverage:** which requirements satisfied/blocked
-
-If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
-
-## 3. Spawn Integration Checker
-
-With phase context collected:
-
-```
-Task(
-  prompt="Check cross-phase integration and E2E flows.
-
-Phases: {phase_dirs}
-Phase exports: {from SUMMARYs}
-API routes: {routes created}
-
-Verify cross-phase wiring and E2E user flows.",
-  subagent_type="kata-integration-checker"
-)
-```
-
-## 4. Collect Results
-
-Combine:
-- Phase-level gaps and tech debt (from step 2)
-- Integration checker's report (wiring gaps, broken flows)
-
-## 5. Check Requirements Coverage
-
-For each requirement in REQUIREMENTS.md mapped to this milestone:
-- Find owning phase
-- Check phase verification status
-- Determine: satisfied | partial | unsatisfied
-
-## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
-
-Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:
-
-```yaml
----
-milestone: {version}
-audited: {timestamp}
-status: passed | gaps_found | tech_debt
-scores:
-  requirements: N/M
-  phases: N/M
-  integration: N/M
-  flows: N/M
-gaps:  # Critical blockers
-  requirements: [...]
-  integration: [...]
-  flows: [...]
-tech_debt:  # Non-critical, deferred
-  - phase: 01-auth
-    items:
-      - "TODO: add rate limiting"
-      - "Warning: no password strength validation"
-  - phase: 03-dashboard
-    items:
-      - "Deferred: mobile responsive layout"
----
-```
-
-Plus full markdown report with tables for requirements, phases, integration, tech debt.
-
-**Status values:**
-- `passed` — all requirements met, no critical gaps, minimal tech debt
-- `gaps_found` — critical blockers exist
-- `tech_debt` — no blockers but accumulated deferred items need review
-
-## 7. Present Results
-
-Route by status (see `<offer_next>`).
-
-</process>
-
-<offer_next>
-Output this markdown directly (not as a code block). Route based on status:
-
----
-
-**If passed:**
-
-## ✓ Milestone {version} — Audit Passed
-
-**Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-MILESTONE-AUDIT.md
-
-All requirements covered. Cross-phase integration verified. E2E flows complete.
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Complete milestone** — archive and tag
-
-/kata:complete-milestone {version}
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
----
-
-**If gaps_found:**
-
-## ⚠ Milestone {version} — Gaps Found
-
-**Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-MILESTONE-AUDIT.md
-
-### Unsatisfied Requirements
-
-{For each unsatisfied requirement:}
-- **{REQ-ID}: {description}** (Phase {X})
-  - {reason}
-
-### Cross-Phase Issues
-
-{For each integration gap:}
-- **{from} → {to}:** {issue}
-
-### Broken Flows
-
-{For each flow gap:}
-- **{flow name}:** breaks at {step}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Plan gap closure** — create phases to complete milestone
-
-/kata:plan-milestone-gaps
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- cat .planning/v{version}-MILESTONE-AUDIT.md — see full report
-- /kata:complete-milestone {version} — proceed anyway (accept tech debt)
-
-───────────────────────────────────────────────────────────────
-
----
-
-**If tech_debt (no blockers but accumulated debt):**
-
-## ⚡ Milestone {version} — Tech Debt Review
-
-**Score:** {N}/{M} requirements satisfied
-**Report:** .planning/v{version}-MILESTONE-AUDIT.md
-
-All requirements met. No critical blockers. Accumulated tech debt needs review.
-
-### Tech Debt by Phase
-
-{For each phase with debt:}
-**Phase {X}: {name}**
-- {item 1}
-- {item 2}
-
-### Total: {N} items across {M} phases
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Options
-
-**A. Complete milestone** — accept debt, track in backlog
-
-/kata:complete-milestone {version}
-
-**B. Plan cleanup phase** — address debt before completing
-
-/kata:plan-milestone-gaps
+## Step 1: Parse Context
 
-<sub>/clear first → fresh context window</sub>
+Arguments: "$ARGUMENTS"
 
-───────────────────────────────────────────────────────────────
-</offer_next>
+## Step 2: Invoke Skill
 
-<success_criteria>
-- [ ] Milestone scope identified
-- [ ] All phase VERIFICATION.md files read
-- [ ] Tech debt and deferred gaps aggregated
-- [ ] Integration checker spawned for cross-phase wiring
-- [ ] v{version}-MILESTONE-AUDIT.md created
-- [ ] Results presented with actionable next steps
-</success_criteria>
+Run the following skill:
+`Skill("kata-auditing-milestones")`

package/commands/kata/check-todo.md

@@ -0,0 +1,20 @@
+---
+name: check-todo
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+version: 0.1.0
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+## Step 1: Parse Context
+
+Arguments: "$ARGUMENTS"
+
+## Step 2: Invoke Skill
+
+Run the following skill:
+`Skill("kata-checking-todos")`

package/commands/kata/complete-milestone.md

@@ -1,136 +1,20 @@
 ---
-type: prompt
-name: kata:complete-milestone
+name: complete-milestone
 description: Archive completed milestone and prepare for next version
 argument-hint: <version>
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
   - Write
   - Bash
 ---
 
-<objective>
-Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+## Step 1: Parse Context
 
-Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
-Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
-</objective>
+Arguments: "$ARGUMENTS"
 
-<execution_context>
-**Load these files NOW (before proceeding):**
+## Step 2: Invoke Skill
 
-- @~/.claude/kata/workflows/complete-milestone.md (main workflow)
-- @~/.claude/kata/templates/milestone-archive.md (archive template)
-  </execution_context>
-
-<context>
-**Project files:**
-- `.planning/ROADMAP.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/STATE.md`
-- `.planning/PROJECT.md`
-
-**User input:**
-
-- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
-  </context>
-
-<process>
-
-**Follow complete-milestone.md workflow:**
-
-0. **Check for audit:**
-
-   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
-   - If missing or stale: recommend `/kata:audit-milestone` first
-   - If audit status is `gaps_found`: recommend `/kata:plan-milestone-gaps` first
-   - If audit status is `passed`: proceed to step 1
-
-   ```markdown
-   ## Pre-flight Check
-
-   {If no v{{version}}-MILESTONE-AUDIT.md:}
-   ⚠ No milestone audit found. Run `/kata:audit-milestone` first to verify
-   requirements coverage, cross-phase integration, and E2E flows.
-
-   {If audit has gaps:}
-   ⚠ Milestone audit found gaps. Run `/kata:plan-milestone-gaps` to create
-   phases that close the gaps, or proceed anyway to accept as tech debt.
-
-   {If audit passed:}
-   ✓ Milestone audit passed. Proceeding with completion.
-   ```
-
-1. **Verify readiness:**
-
-   - Check all phases in milestone have completed plans (SUMMARY.md exists)
-   - Present milestone scope and stats
-   - Wait for confirmation
-
-2. **Gather stats:**
-
-   - Count phases, plans, tasks
-   - Calculate git range, file changes, LOC
-   - Extract timeline from git log
-   - Present summary, confirm
-
-3. **Extract accomplishments:**
-
-   - Read all phase SUMMARY.md files in milestone range
-   - Extract 4-6 key accomplishments
-   - Present for approval
-
-4. **Archive milestone:**
-
-   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
-   - Extract full phase details from ROADMAP.md
-   - Fill milestone-archive.md template
-   - Update ROADMAP.md to one-line summary with link
-
-5. **Archive requirements:**
-
-   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
-   - Mark all v1 requirements as complete (checkboxes checked)
-   - Note requirement outcomes (validated, adjusted, dropped)
-   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
-
-6. **Update PROJECT.md:**
-
-   - Add "Current State" section with shipped version
-   - Add "Next Milestone Goals" section
-   - Archive previous content in `<details>` (if v1.1+)
-
-7. **Commit and tag:**
-
-   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
-   - Commit: `chore: archive v{{version}} milestone`
-   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
-   - Ask about pushing tag
-
-8. **Offer next steps:**
-   - `/kata:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
-
-</process>
-
-<success_criteria>
-
-- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
-- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
-- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
-- ROADMAP.md collapsed to one-line entry
-- PROJECT.md updated with current state
-- Git tag v{{version}} created
-- Commit successful
-- User knows next steps (including need for fresh requirements)
-  </success_criteria>
-
-<critical_rules>
-
-- **Load workflow first:** Read complete-milestone.md before executing
-- **Verify completion:** All phases must have SUMMARY.md files
-- **User confirmation:** Wait for approval at verification gates
-- **Archive before deleting:** Always create archive files before updating/deleting originals
-- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
-- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
-- **Fresh requirements:** Next milestone starts with `/kata:new-milestone` which includes requirements definition
-  </critical_rules>
+Run the following skill:
+`Skill("kata-completing-milestones")`

package/commands/kata/debug.md

@@ -1,149 +1,20 @@
 ---
-name: kata:debug
+name: debug
 description: Systematic debugging with persistent state across context resets
 argument-hint: [issue description]
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
+  - Write
   - Bash
-  - Task
-  - AskUserQuestion
 ---
 
-<objective>
-Debug issues using scientific method with subagent isolation.
+## Step 1: Parse Context
 
-**Orchestrator role:** Gather symptoms, spawn kata-debugger agent, handle checkpoints, spawn continuations.
+Arguments: "$ARGUMENTS"
 
-**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
-</objective>
+## Step 2: Invoke Skill
 
-<context>
-User's issue: $ARGUMENTS
-
-Check for active sessions:
-```bash
-ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
-```
-</context>
-
-<process>
-
-## 1. Check Active Sessions
-
-If active sessions exist AND no $ARGUMENTS:
-- List sessions with status, hypothesis, next action
-- User picks number to resume OR describes new issue
-
-If $ARGUMENTS provided OR user describes new issue:
-- Continue to symptom gathering
-
-## 2. Gather Symptoms (if new issue)
-
-Use AskUserQuestion for each:
-
-1. **Expected behavior** - What should happen?
-2. **Actual behavior** - What happens instead?
-3. **Error messages** - Any errors? (paste or describe)
-4. **Timeline** - When did this start? Ever worked?
-5. **Reproduction** - How do you trigger it?
-
-After all gathered, confirm ready to investigate.
-
-## 3. Spawn kata-debugger Agent
-
-Fill prompt and spawn:
-
-```markdown
-<objective>
-Investigate issue: {slug}
-
-**Summary:** {trigger}
-</objective>
-
-<symptoms>
-expected: {expected}
-actual: {actual}
-errors: {errors}
-reproduction: {reproduction}
-timeline: {timeline}
-</symptoms>
-
-<mode>
-symptoms_prefilled: true
-goal: find_and_fix
-</mode>
-
-<debug_file>
-Create: .planning/debug/{slug}.md
-</debug_file>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="kata-debugger",
-  description="Debug {slug}"
-)
-```
-
-## 4. Handle Agent Return
-
-**If `## ROOT CAUSE FOUND`:**
-- Display root cause and evidence summary
-- Offer options:
-  - "Fix now" - spawn fix subagent
-  - "Plan fix" - suggest /kata:plan-phase --gaps
-  - "Manual fix" - done
-
-**If `## CHECKPOINT REACHED`:**
-- Present checkpoint details to user
-- Get user response
-- Spawn continuation agent (see step 5)
-
-**If `## INVESTIGATION INCONCLUSIVE`:**
-- Show what was checked and eliminated
-- Offer options:
-  - "Continue investigating" - spawn new agent with additional context
-  - "Manual investigation" - done
-  - "Add more context" - gather more symptoms, spawn again
-
-## 5. Spawn Continuation Agent (After Checkpoint)
-
-When user responds to checkpoint, spawn fresh agent:
-
-```markdown
-<objective>
-Continue debugging {slug}. Evidence is in the debug file.
-</objective>
-
-<prior_state>
-Debug file: @.planning/debug/{slug}.md
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-
-<mode>
-goal: find_and_fix
-</mode>
-```
-
-```
-Task(
-  prompt=continuation_prompt,
-  subagent_type="kata-debugger",
-  description="Continue debug {slug}"
-)
-```
-
-</process>
-
-<success_criteria>
-- [ ] Active sessions checked
-- [ ] Symptoms gathered (if new)
-- [ ] kata-debugger spawned with context
-- [ ] Checkpoints handled correctly
-- [ ] Root cause confirmed before fixing
-</success_criteria>
+Run the following skill:
+`Skill("kata-debugging")`

package/commands/kata/discuss-phase.md

@@ -1,80 +1,20 @@
 ---
-name: kata:discuss-phase
+name: discuss-phase
 description: Gather phase context through adaptive questioning before planning
-argument-hint: "<phase>"
-allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
+argument-hint: <phase>
+version: 0.1.0
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Write
+  - Bash
 ---
 
-<objective>
-Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
+## Step 1: Parse Context
 
-**How it works:**
-1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
-2. Present gray areas — user selects which to discuss
-3. Deep-dive each selected area until satisfied
-4. Create CONTEXT.md with decisions that guide research and planning
+Arguments: "$ARGUMENTS"
 
-**Output:** `{phase}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
-</objective>
+## Step 2: Invoke Skill
 
-<execution_context>
-@~/.claude/kata/workflows/discuss-phase.md
-@~/.claude/kata/templates/context.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-**Load project state:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
-</context>
-
-<process>
-1. Validate phase number (error if missing or not in roadmap)
-2. Check if CONTEXT.md exists (offer update/view/skip if yes)
-3. **Analyze phase** — Identify domain and generate phase-specific gray areas
-4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
-5. **Deep-dive each area** — 4 questions per area, then offer more/next
-6. **Write CONTEXT.md** — Sections match areas discussed
-7. Offer next steps (research or plan)
-
-**CRITICAL: Scope guardrail**
-- Phase boundary from ROADMAP.md is FIXED
-- Discussion clarifies HOW to implement, not WHETHER to add more
-- If user suggests new capabilities: "That's its own phase. I'll note it for later."
-- Capture deferred ideas — don't lose them, don't act on them
-
-**Domain-aware gray areas:**
-Gray areas depend on what's being built. Analyze the phase goal:
-- Something users SEE → layout, density, interactions, states
-- Something users CALL → responses, errors, auth, versioning
-- Something users RUN → output format, flags, modes, error handling
-- Something users READ → structure, tone, depth, flow
-- Something being ORGANIZED → criteria, grouping, naming, exceptions
-
-Generate 3-4 **phase-specific** gray areas, not generic categories.
-
-**Probing depth:**
-- Ask 4 questions per area before checking
-- "More questions about [area], or move to next?"
-- If more → ask 4 more, check again
-- After all areas → "Ready to create context?"
-
-**Do NOT ask about (Claude handles these):**
-- Technical implementation
-- Architecture choices
-- Performance concerns
-- Scope expansion
-</process>
-
-<success_criteria>
-- Gray areas identified through intelligent analysis
-- User chose which areas to discuss
-- Each selected area explored until satisfied
-- Scope creep redirected to deferred ideas
-- CONTEXT.md captures decisions, not vague vision
-- User knows next steps
-</success_criteria>
+Run the following skill:
+`Skill("kata-discussing-phases")`