@gannonh/kata 0.1.4 → 0.2.0

package/kata/workflows/resume-project.md

@@ -13,6 +13,10 @@ Enables seamless session continuity for fully autonomous workflows.
 "Where were we?" should have an immediate, complete answer.
 </purpose>
 
+<required_reading>
+@~/.claude/kata/references/continuation-format.md
+</required_reading>
+
 <process>
 
 <step name="detect_existing_project">

package/kata/workflows/verify-phase.md

@@ -18,9 +18,8 @@ Then verify each level against the actual codebase.
 </core_principle>
 
 <required_reading>
-**Load these references:**
-- ~/.claude/kata/references/verification-patterns.md (detection patterns)
-- ~/.claude/kata/templates/verification-report.md (output format)
+@~/.claude/kata/references/verification-patterns.md
+@~/.claude/kata/templates/verification-report.md
 </required_reading>
 
 <process>

package/kata/workflows/verify-work.md

@@ -20,6 +20,25 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 
 <process>
 
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| kata-planner | opus | opus | sonnet |
+| kata-plan-checker | sonnet | sonnet | haiku |
+
+Store resolved models for use in Task calls below.
+</step>
+
 <step name="check_active_session">
 **First: Check for active UAT sessions**
 
@@ -285,6 +304,17 @@ Clear Current Test section:
 [testing complete]
 ```
 
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 Commit the UAT file:
 ```bash
 git add ".planning/phases/XX-name/{phase}-UAT.md"
@@ -345,7 +375,7 @@ Diagnosis runs automatically - no user prompt. Parallel agents investigate simul
 Display:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- KATA ► PLANNING FIXES
+ Kata ► PLANNING FIXES
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Spawning planner for gap closure...
@@ -378,6 +408,7 @@ Plans must be executable prompts.
 </downstream_consumer>
 """,
   subagent_type="kata-planner",
+  model="{planner_model}",
   description="Plan gap fixes for Phase {phase}"
 )
 ```
@@ -393,7 +424,7 @@ On return:
 Display:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- KATA ► VERIFYING FIX PLANS
+ Kata ► VERIFYING FIX PLANS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 ◆ Spawning plan checker...
@@ -423,6 +454,7 @@ Return one of:
 </expected_output>
 """,
   subagent_type="kata-plan-checker",
+  model="{checker_model}",
   description="Verify Phase {phase} fix plans"
 )
 ```
@@ -463,6 +495,7 @@ Do NOT replan from scratch unless issues are fundamental.
 </instructions>
 """,
   subagent_type="kata-planner",
+  model="{planner_model}",
   description="Revise Phase {phase} plans"
 )
 ```
@@ -487,7 +520,7 @@ Wait for user response.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- KATA ► FIXES READY ✓
+ Kata ► FIXES READY ✓
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Phase {X}: {Name}** — {N} gap(s) diagnosed, {M} fix plan(s) created

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@gannonh/kata",
-  "version": "0.1.4",
-  "description": "Development framework for Claude Code.",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Spec-driven development framework for Claude Code.",
+  "scripts": {
+    "test": "node --test --test-reporter spec tests/**/*.test.js",
+    "test:skills": "node --test --test-reporter spec tests/skills/*.test.js",
+    "test:skill": "node --test --test-reporter spec"
+  },
   "bin": {
     "kata": "bin/install.js"
   },
@@ -10,7 +16,8 @@
     "commands",
     "kata",
     "agents",
-    "hooks"
+    "hooks",
+    "skills"
   ],
   "keywords": [
     "claude",
@@ -27,6 +34,6 @@
     "url": "git+https://github.com/gannonh/kata.git"
   },
   "engines": {
-    "node": ">=16.7.0"
+    "node": ">=20.0.0"
   }
-}
+}

package/skills/kata-adding-phases/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: kata-adding-phases
+description: Use this skill to add planned work discovered during execution to the end of the current milestone in the roadmap. This skill appends sequential phases to the current milestone's phase list, automatically calculating the next phase number. Triggers include "add phase", "append phase", "new phase", and "create phase". This skill updates ROADMAP.md and STATE.md accordingly.
+version: 0.1.0
+user-invocable: false
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.
+
+Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/kata:add-phase Add authentication` → description = "Add authentication"
+- Example: `/kata:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /kata:add-phase <description>
+Example: /kata:add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="load_roadmap">
+Load the roadmap file:
+
+```bash
+if [ -f .planning/ROADMAP.md ]; then
+  ROADMAP=".planning/ROADMAP.md"
+else
+  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
+  exit 1
+fi
+```
+
+Read roadmap content for parsing.
+</step>
+
+<step name="find_current_milestone">
+Parse the roadmap to find the current milestone section:
+
+1. Locate the "## Current Milestone:" heading
+2. Extract milestone name and version
+3. Identify all phases under this milestone (before next "---" separator or next milestone heading)
+4. Parse existing phase numbers (including decimals if present)
+
+Example structure:
+
+```
+## Current Milestone: v1.0 Foundation
+
+### Phase 4: Focused Command System
+### Phase 5: Path Routing & Validation
+### Phase 6: Documentation & Distribution
+```
+
+</step>
+
+<step name="calculate_next_phase">
+Find the highest integer phase number in the current milestone:
+
+1. Extract all phase numbers from phase headings (### Phase N:)
+2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
+3. Find the maximum integer value
+4. Add 1 to get the next phase number
+
+Example: If phases are 4, 5, 5.1, 6 → next is 7
+
+Format as two-digit: `printf "%02d" $next_phase`
+</step>
+
+<step name="generate_slug">
+Convert the phase description to a kebab-case slug:
+
+```bash
+# Example transformation:
+# "Add authentication" → "add-authentication"
+# "Fix critical performance issues" → "fix-critical-performance-issues"
+
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+```
+
+Phase directory name: `{two-digit-phase}-{slug}`
+Example: `07-add-authentication`
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory structure:
+
+```bash
+phase_dir=".planning/phases/${phase_num}-${slug}"
+mkdir -p "$phase_dir"
+```
+
+Confirm: "Created directory: $phase_dir"
+</step>
+
+<step name="update_roadmap">
+Add the new phase entry to the roadmap:
+
+1. Find the insertion point (after last phase in current milestone, before "---" separator)
+2. Insert new phase heading:
+
+   ```
+   ### Phase {N}: {Description}
+
+   **Goal:** [To be planned]
+   **Depends on:** Phase {N-1}
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (run /kata:plan-phase {N} to break down)
+
+   **Details:**
+   [To be added during planning]
+   ```
+
+3. Write updated roadmap back to file
+
+Preserve all other content exactly (formatting, spacing, other phases).
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Current Position" → "**Next Phase:**" add reference to new phase
+3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: {roadmap-path}
+Project state updated: .planning/STATE.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/kata:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/kata:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't modify phases outside current milestone
+- Don't renumber existing phases
+- Don't use decimal numbering (that's /kata:insert-phase)
+- Don't create plans yet (that's /kata:plan-phase)
+- Don't commit changes (user decides when to commit)
+  </anti_patterns>
+
+<success_criteria>
+Phase addition is complete when:
+
+- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] New phase appears at end of current milestone
+- [ ] Next phase number calculated correctly (ignoring decimals)
+- [ ] User informed of next steps
+      </success_criteria>

package/skills/kata-adding-todos/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: kata-adding-todos
+description: Use this skill to capture an idea, task, or issue that surfaces during a Kata session as a structured todo for later work. This skill creates markdown todo files in the .planning/todos/pending directory with relevant metadata and content extracted from the conversation. Triggers include "add todo", "capture todo", "new todo", and "create todo". 
+version: 0.1.0
+user-invocable: false
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a Kata session as a structured todo for later work.
+
+Enables "thought → capture → continue" flow without losing context or derailing current work.
+</objective>
+
+<context>
+@.planning/STATE.md
+</context>
+
+<process>
+
+<step name="ensure_directory">
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+</step>
+
+<step name="check_existing_areas">
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u
+```
+
+Note existing areas for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/kata:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+```bash
+timestamp=$(date "+%Y-%m-%dT%H:%M")
+date_prefix=$(date "+%Y-%m-%d")
+```
+
+Generate slug from title (lowercase, hyphens, no special chars).
+
+Write to `.planning/todos/pending/${date_prefix}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Count todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Todo saved (not committed - commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
+```bash
+git add .planning/todos/pending/[filename]
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
+git commit -m "$(cat <<'EOF'
+docs: capture todo - [title]
+
+Area: [area]
+EOF
+)"
+```
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/kata:check-todos)
+```
+</step>
+
+</process>
+
+<output>
+- `.planning/todos/pending/[date]-[slug].md`
+- Updated `.planning/STATE.md` (if exists)
+</output>
+
+<anti_patterns>
+- Don't create todos for work in current plan (that's deviation rule territory)
+- Don't create elaborate solution sections — captures ideas, not plans
+- Don't block on missing information — "TBD" is fine
+</anti_patterns>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>