kata-help

What this skill does

<objective>
Display the complete Kata skill reference with version info.

First, read the installed version:

```bash
if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then
  cat "$CLAUDE_PLUGIN_ROOT/VERSION" 2>/dev/null
else
  echo "unknown"
fi
```

Then output the reference content below, inserting the version at the top. Do NOT add:

- Project-specific analysis
- Git status or file context
- Next-step suggestions
- Any commentary beyond the reference
  </objective>

<reference>
# Kata Skill Reference

**Version:** {version from bash above}

**Kata** is a spec-driven development framework for Claude Code. It creates hierarchical project plans optimized for agentic development.

## Quick Start

1. `/kata-new-project` - Initialize project (includes research, requirements, roadmap)
2. `/kata-plan-phase 1` - Create detailed plan for first phase
3. `/kata-execute-phase 1` - Execute the phase

## Staying Updated

Kata evolves fast. Check for updates periodically:

```
/kata-whats-new
```

Shows what changed since your installed version and how to update.

## Core Workflow

```
/kata-new-project → /kata-plan-phase → /kata-execute-phase → repeat
```

### Project Initialization

**`/kata-new-project`**
Initialize new project through unified flow.

One skill takes you from idea to ready-for-planning:

- Deep questioning to understand what you're building
- Optional domain research (spawns 4 parallel researcher agents)
- Requirements definition with v1/v2/out-of-scope scoping
- Roadmap creation with phase breakdown and success criteria

Creates all `.planning/` artifacts:

- `PROJECT.md` — vision and requirements
- `config.json` — workflow mode (interactive/yolo)
- `research/` — domain research (if selected)
- `REQUIREMENTS.md` — scoped requirements with REQ-IDs
- `ROADMAP.md` — phases mapped to requirements
- `STATE.md` — project memory

Usage: `/kata-new-project`

**`/kata-map-codebase`**
Map an existing codebase for brownfield projects.

- Analyzes codebase with parallel Explore agents
- Creates `.planning/codebase/` with 7 focused documents
- Covers stack, architecture, structure, conventions, testing, integrations, concerns
- Use before `/kata-new-project` on existing codebases

Usage: `/kata-map-codebase`

### Phase Planning

**`/kata-discuss-phase <number>`**
Help articulate your vision for a phase before planning.

- Captures how you imagine this phase working
- Creates CONTEXT.md with your vision, essentials, and boundaries
- Use when you have ideas about how something should look/feel

Usage: `/kata-discuss-phase 2`

**`/kata-research-phase <number>`**
Comprehensive ecosystem research for niche/complex domains.

- Discovers standard stack, architecture patterns, pitfalls
- Creates RESEARCH.md with "how experts build this" knowledge
- Use for 3D, games, audio, shaders, ML, and other specialized domains
- Goes beyond "which library" to ecosystem knowledge

Usage: `/kata-research-phase 3`

**`/kata-listing-phase-assumptions <number>`**
See what Claude is planning to do before it starts.

- Shows Claude's intended approach for a phase
- Lets you course-correct if Claude misunderstood your vision
- No files created - conversational output only

Usage: `/kata-listing-phase-assumptions 3`

**`/kata-plan-phase <number>`**
Create detailed execution plan for a specific phase.

- Generates `.planning/phases/pending/XX-phase-name/XX-YY-PLAN.md`
- Breaks phase into concrete, actionable tasks
- Includes verification criteria and success measures
- Multiple plans per phase supported (XX-01, XX-02, etc.)

Usage: `/kata-plan-phase 1`
Result: Creates `.planning/phases/pending/01-foundation/01-01-PLAN.md`

### Execution

**`/kata-execute-phase <phase-number>`**
Execute all plans in a phase.

- Moves phase from `pending/` → `active/` → `completed/`
- Groups plans by wave (from frontmatter), executes waves sequentially
- Plans within each wave run in parallel via Task tool
- Verifies phase goal after all plans complete
- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md

Usage: `/kata-execute-phase 5`

### Quick Mode

**`/kata-execute-quick-task`**
Execute small, ad-hoc tasks with Kata guarantees but skip optional agents.

Quick mode uses the same system with a shorter path:

- Spawns planner + executor (skips researcher, checker, verifier)
- Quick tasks live in `.planning/quick/` separate from planned phases
- Updates STATE.md tracking (not ROADMAP.md)

Use when you know exactly what to do and the task is small enough to not need research or verification.

Usage: `/kata-execute-quick-task`
Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`

### Roadmap Management

**`/kata-add-phase <description>`**
Add new phase to end of current milestone.

- Appends to ROADMAP.md
- Uses next sequential number
- Creates phase directory in `pending/`

Usage: `/kata-add-phase "Add admin dashboard"`

**`/kata-insert-phase <after> <description>`**
Insert urgent work as decimal phase between existing phases.

- Creates intermediate phase (e.g., 7.1 between 7 and 8)
- Useful for discovered work that must happen mid-milestone
- Maintains phase ordering

Usage: `/kata-insert-phase 7 "Fix critical auth bug"`
Result: Creates Phase 7.1

**`/kata-remove-phase <number>`**
Remove a future phase and renumber subsequent phases.

- Deletes phase directory and all references
- Renumbers all subsequent phases to close the gap
- Only works on future (unstarted) phases
- Git commit preserves historical record

Usage: `/kata-remove-phase 17`
Result: Phase 17 deleted, phases 18-20 become 17-19

**`/kata-move-phase <phase> <operation>`**
Move a phase between milestones or reorder within a milestone.

- Cross-milestone: moves phase to target milestone, renumbers both
- Reorder: changes phase position within milestone, renumbers all
- Only pending phases can be moved

Usage: `/kata-move-phase 3 to v1.6.0` (cross-milestone)
Usage: `/kata-move-phase 3 before 1` (reorder within milestone)

### Milestone Management

**`/kata-add-milestone <name>`**
Start a new milestone through unified flow.

- Deep questioning to understand what you're building next
- Optional domain research (spawns 4 parallel researcher agents)
- Requirements definition with scoping
- Roadmap creation with phase breakdown

Mirrors `/kata-new-project` flow for brownfield projects (existing PROJECT.md).

Usage: `/kata-add-milestone "v2.0 Features"`

**`/kata-complete-milestone <version>`**
Archive completed milestone and prepare for next version.

- Creates MILESTONES.md entry with stats
- Archives full details to milestones/ directory
- Creates git tag for the release
- Prepares workspace for next version

Usage: `/kata-complete-milestone 1.0.0`

### Progress Tracking

**`/kata-track-progress`**
Check project status and intelligently route to next action.

- Shows visual progress bar and completion percentage
- Summarizes recent work from SUMMARY files
- Displays current position and what's next
- Lists key decisions and open issues
- Offers to execute next plan or create it if missing
- Detects 100% milestone completion

Usage: `/kata-track-progress`

### Session Management

**`/kata-resume-work`**
Resume work from previous session with full context restoration.

- Reads STATE.md for project context
- Shows current position and recent progress
- Offers next actions based on project state

Usage: `/kata-resume-work`

**`/kata-pause-work`**
Create context handoff when pausing work mid-phase.

- Creates .continue-here file with current state
- Updates STATE.md session continuity section
- Captures in-progress work context

Usage: `/kata-pause-work`

### Debugging

**`/kata-debug [issue description]`**
Systematic debugging with persistent state across context resets.

- Gathers symptoms through adaptive questioning
- Creates `.planning/debug/[slug].md` to track investigation
- Investigates using scientific method (evidence → hypothesis → test)
- Survives `/clear` — run `/kata-debug` with no args to resume
- Archives resolved i