@gannonh/kata 0.1.4 → 0.2.0

package/commands/kata/insert-phase.md

@@ -1,227 +1,20 @@
 ---
-name: kata:insert-phase
+name: insert-phase
 description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
 argument-hint: <after> <description>
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
   - Write
   - Bash
 ---
 
-<objective>
-Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+## Step 1: Parse Context
 
-Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+Arguments: "$ARGUMENTS"
 
-Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
-</objective>
+## Step 2: Invoke Skill
 
-<execution_context>
-@.planning/ROADMAP.md
-@.planning/STATE.md
-</execution_context>
-
-<process>
-
-<step name="parse_arguments">
-Parse the command arguments:
-- First argument: integer phase number to insert after
-- Remaining arguments: phase description
-
-Example: `/kata:insert-phase 72 Fix critical auth bug`
-→ after = 72
-→ description = "Fix critical auth bug"
-
-Validation:
-
-```bash
-if [ $# -lt 2 ]; then
-  echo "ERROR: Both phase number and description required"
-  echo "Usage: /kata:insert-phase <after> <description>"
-  echo "Example: /kata:insert-phase 72 Fix critical auth bug"
-  exit 1
-fi
-```
-
-Parse first argument as integer:
-
-```bash
-after_phase=$1
-shift
-description="$*"
-
-# Validate after_phase is an integer
-if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
-  echo "ERROR: Phase number must be an integer"
-  exit 1
-fi
-```
-
-</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="verify_target_phase">
-Verify that the target phase exists in the roadmap:
-
-1. Search for "### Phase {after_phase}:" heading
-2. If not found:
-
-   ```
-   ERROR: Phase {after_phase} not found in roadmap
-   Available phases: [list phase numbers]
-   ```
-
-   Exit.
-
-3. Verify phase is in current milestone (not completed/archived)
-   </step>
-
-<step name="find_existing_decimals">
-Find existing decimal phases after the target phase:
-
-1. Search for all "### Phase {after_phase}.N:" headings
-2. Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)
-3. Find the highest decimal suffix
-4. Calculate next decimal: max + 1
-
-Examples:
-
-- Phase 72 with no decimals → next is 72.1
-- Phase 72 with 72.1 → next is 72.2
-- Phase 72 with 72.1, 72.2 → next is 72.3
-
-Store as: `decimal_phase="$(printf "%02d" $after_phase).${next_decimal}"`
-</step>
-
-<step name="generate_slug">
-Convert the phase description to a kebab-case slug:
-
-```bash
-slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
-```
-
-Phase directory name: `{decimal-phase}-{slug}`
-Example: `06.1-fix-critical-auth-bug` (phase 6 insertion)
-</step>
-
-<step name="create_phase_directory">
-Create the phase directory structure:
-
-```bash
-phase_dir=".planning/phases/${decimal_phase}-${slug}"
-mkdir -p "$phase_dir"
-```
-
-Confirm: "Created directory: $phase_dir"
-</step>
-
-<step name="update_roadmap">
-Insert the new phase entry into the roadmap:
-
-1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
-2. Insert new phase heading with (INSERTED) marker:
-
-   ```
-   ### Phase {decimal_phase}: {Description} (INSERTED)
-
-   **Goal:** [Urgent work - to be planned]
-   **Depends on:** Phase {after_phase}
-   **Plans:** 0 plans
-
-   Plans:
-   - [ ] TBD (run /kata:plan-phase {decimal_phase} to break down)
-
-   **Details:**
-   [To be added during planning]
-   ```
-
-3. Write updated roadmap back to file
-
-The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
-
-Preserve all other content exactly (formatting, spacing, other phases).
-</step>
-
-<step name="update_project_state">
-Update STATE.md to reflect the inserted phase:
-
-1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
-   ```
-   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
-   ```
-
-If "Roadmap Evolution" section doesn't exist, create it.
-
-Add note about insertion reason if appropriate.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {decimal_phase} inserted after Phase {after_phase}:
-- Description: {description}
-- Directory: .planning/phases/{decimal-phase}-{slug}/
-- Status: Not planned yet
-- Marker: (INSERTED) - indicates urgent work
-
-Roadmap updated: {roadmap-path}
-Project state updated: .planning/STATE.md
-
----
-
-## ▶ Next Up
-
-**Phase {decimal_phase}: {description}** — urgent insertion
-
-`/kata:plan-phase {decimal_phase}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<anti_patterns>
-
-- Don't use this for planned work at end of milestone (use /kata:add-phase)
-- Don't insert before Phase 1 (decimal 0.1 makes no sense)
-- Don't renumber existing phases
-- Don't modify the target phase content
-- Don't create plans yet (that's /kata:plan-phase)
-- Don't commit changes (user decides when to commit)
-  </anti_patterns>
-
-<success_criteria>
-Phase insertion is complete when:
-
-- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
-- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
-- [ ] Phase inserted in correct position (after target phase, before next integer phase)
-- [ ] STATE.md updated with roadmap evolution note
-- [ ] Decimal number calculated correctly (based on existing decimals)
-- [ ] User informed of next steps and dependency implications
-      </success_criteria>
+Run the following skill:
+`Skill("kata-inserting-phases")`

package/commands/kata/list-phase-assumptions.md

@@ -1,50 +1,20 @@
 ---
-name: kata:list-phase-assumptions
+name: list-phase-assumptions
 description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
+argument-hint: [phase]
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
+  - Write
   - Bash
-  - Grep
-  - Glob
 ---
 
-<objective>
-Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+## Step 1: Parse Context
 
-Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
-Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
-</objective>
+Arguments: "$ARGUMENTS"
 
-<execution_context>
-@~/.claude/kata/workflows/list-phase-assumptions.md
-</execution_context>
+## Step 2: Invoke Skill
 
-<context>
-Phase number: $ARGUMENTS (required)
-
-**Load project state first:**
-@.planning/STATE.md
-
-**Load roadmap:**
-@.planning/ROADMAP.md
-</context>
-
-<process>
-1. Validate phase number argument (error if missing or invalid)
-2. Check if phase exists in roadmap
-3. Follow list-phase-assumptions.md workflow:
-   - Analyze roadmap description
-   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
-   - Prompt "What do you think?"
-4. Gather feedback and offer next steps
-</process>
-
-<success_criteria>
-
-- Phase validated against roadmap
-- Assumptions surfaced across five areas
-- User prompted for feedback
-- User knows next steps (discuss context, plan phase, or correct assumptions)
-  </success_criteria>
+Run the following skill:
+`Skill("kata-listing-phase-assumptions")`

package/commands/kata/map-codebase.md

@@ -1,71 +1,20 @@
 ---
-name: kata:map-codebase
+name: map-codebase
 description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
-argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+argument-hint: [optional: specific area to map, e.g., 'api' or 'auth']
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
-  - Bash
-  - Glob
-  - Grep
   - Write
-  - Task
+  - Bash
 ---
 
-<objective>
-Analyze existing codebase using parallel kata-codebase-mapper agents to produce structured codebase documents.
-
-Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
-
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
-</objective>
-
-<execution_context>
-@~/.claude/kata/workflows/map-codebase.md
-</execution_context>
-
-<context>
-Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
-
-**Load project state if exists:**
-Check for .planning/STATE.md - loads context if project already initialized
-
-**This command can run:**
-- Before /kata:new-project (brownfield codebases) - creates codebase map first
-- After /kata:new-project (greenfield codebases) - updates codebase map as code evolves
-- Anytime to refresh codebase understanding
-</context>
-
-<when_to_use>
-**Use map-codebase for:**
-- Brownfield projects before initialization (understand existing code first)
-- Refreshing codebase map after significant changes
-- Onboarding to an unfamiliar codebase
-- Before major refactoring (understand current state)
-- When STATE.md references outdated codebase info
+## Step 1: Parse Context
 
-**Skip map-codebase for:**
-- Greenfield projects with no code yet (nothing to map)
-- Trivial codebases (<5 files)
-</when_to_use>
+Arguments: "$ARGUMENTS"
 
-<process>
-1. Check if .planning/codebase/ already exists (offer to refresh or skip)
-2. Create .planning/codebase/ directory structure
-3. Spawn 4 parallel kata-codebase-mapper agents:
-   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
-   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
-   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
-   - Agent 4: concerns focus → writes CONCERNS.md
-4. Wait for agents to complete, collect confirmations (NOT document contents)
-5. Verify all 7 documents exist with line counts
-6. Commit codebase map
-7. Offer next steps (typically: /kata:new-project or /kata:plan-phase)
-</process>
+## Step 2: Invoke Skill
 
-<success_criteria>
-- [ ] .planning/codebase/ directory created
-- [ ] All 7 codebase documents written by mapper agents
-- [ ] Documents follow template structure
-- [ ] Parallel agents completed without errors
-- [ ] User knows next steps
-</success_criteria>
+Run the following skill:
+`Skill("kata-mapping-codebases")`

package/commands/kata/pause-work.md

@@ -1,123 +1,20 @@
 ---
-name: kata:pause-work
+name: pause-work
 description: Create context handoff when pausing work mid-phase
+argument-hint: <description>
+version: 0.1.0
+disable-model-invocation: true
 allowed-tools:
   - Read
   - Write
   - Bash
 ---
 
-<objective>
-Create `.continue-here.md` handoff file to preserve complete work state across sessions.
+## Step 1: Parse Context
 
-Enables seamless resumption in fresh session with full context restoration.
-</objective>
+Arguments: "$ARGUMENTS"
 
-<context>
-@.planning/STATE.md
-</context>
+## Step 2: Invoke Skill
 
-<process>
-
-<step name="detect">
-Find current phase directory from most recently modified files.
-</step>
-
-<step name="gather">
-**Collect complete state for handoff:**
-
-1. **Current position**: Which phase, which plan, which task
-2. **Work completed**: What got done this session
-3. **Work remaining**: What's left in current plan/phase
-4. **Decisions made**: Key decisions and rationale
-5. **Blockers/issues**: Anything stuck
-6. **Mental context**: The approach, next steps, "vibe"
-7. **Files modified**: What's changed but not committed
-
-Ask user for clarifications if needed.
-</step>
-
-<step name="write">
-**Write handoff to `.planning/phases/XX-name/.continue-here.md`:**
-
-```markdown
----
-phase: XX-name
-task: 3
-total_tasks: 7
-status: in_progress
-last_updated: [timestamp]
----
-
-<current_state>
-[Where exactly are we? Immediate context]
-</current_state>
-
-<completed_work>
-
-- Task 1: [name] - Done
-- Task 2: [name] - Done
-- Task 3: [name] - In progress, [what's done]
-  </completed_work>
-
-<remaining_work>
-
-- Task 3: [what's left]
-- Task 4: Not started
-- Task 5: Not started
-  </remaining_work>
-
-<decisions_made>
-
-- Decided to use [X] because [reason]
-- Chose [approach] over [alternative] because [reason]
-  </decisions_made>
-
-<blockers>
-- [Blocker 1]: [status/workaround]
-</blockers>
-
-<context>
-[Mental state, what were you thinking, the plan]
-</context>
-
-<next_action>
-Start with: [specific first action when resuming]
-</next_action>
-```
-
-Be specific enough for a fresh Claude to understand immediately.
-</step>
-
-<step name="commit">
-```bash
-git add .planning/phases/*/.continue-here.md
-git commit -m "wip: [phase-name] paused at task [X]/[Y]"
-```
-</step>
-
-<step name="confirm">
-```
-✓ Handoff created: .planning/phases/[XX-name]/.continue-here.md
-
-Current state:
-
-- Phase: [XX-name]
-- Task: [X] of [Y]
-- Status: [in_progress/blocked]
-- Committed as WIP
-
-To resume: /kata:resume-work
-
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] .continue-here.md created in correct phase directory
-- [ ] All sections filled with specific content
-- [ ] Committed as WIP
-- [ ] User knows location and how to resume
-</success_criteria>
-```
+Run the following skill:
+`Skill("kata-pausing-work")`