| name | kata-help |
| description | Show available Kata skills, displaying the usage guide, explaining skill reference, or when the user asks for help with Kata. Triggers include "help", "show skills", "list skills", "what skills", "kata skills", and "usage guide". |
| metadata | {"version":"0.1.0"} |
Display the complete Kata skill reference with version info.
First, read the installed version:
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
# 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
/kata-new-project - Initialize project (includes research, requirements, roadmap)/kata-plan-phase 1 - Create detailed plan for first phase/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 requirementsconfig.json — workflow mode (interactive/yolo)research/ — domain research (if selected)REQUIREMENTS.md — scoped requirements with REQ-IDsROADMAP.md — phases mapped to requirementsSTATE.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 issues to
.planning/debug/resolved/
Usage: /kata-debug "login button doesn't work"
Usage: /kata-debug (resume active session)
Issue Management
/kata-add-issue [description]
Capture idea or task as issue from current conversation.
- Extracts context from conversation (or uses provided description)
- Creates structured issue file in
.planning/issues/open/
- Infers area from file paths for grouping
- Checks for duplicates before creating
- Updates STATE.md issue count
Usage: /kata-add-issue (infers from conversation)
Usage: /kata-add-issue Add auth token refresh
/kata-check-issues [area]
List pending issues and select one to work on.
- Lists all pending issues with title, area, age
- Optional area filter (e.g.,
/kata-check-issues api)
- Loads full context for selected issue
- Routes to appropriate action (work now, add to phase, brainstorm)
- Moves issue to done/ when work begins
Usage: /kata-check-issues
Usage: /kata-check-issues api
User Acceptance Testing
/kata-verify-work [phase]
Validate built features through conversational UAT.
- Extracts testable deliverables from SUMMARY.md files
- Presents tests one at a time (yes/no responses)
- Automatically diagnoses failures and creates fix plans
- Ready for re-execution if issues found
Usage: /kata-verify-work 3
Milestone Auditing
/kata-audit-milestone [version]
Audit milestone completion against original intent.
- Reads all phase VERIFICATION.md files
- Checks requirements coverage
- Spawns integration checker for cross-phase wiring
- Creates MILESTONE-AUDIT.md with gaps and tech debt
Usage: /kata-audit-milestone
/kata-plan-milestone-gaps
Create phases to close gaps identified by audit.
- Reads MILESTONE-AUDIT.md and groups gaps into phases
- Prioritizes by requirement priority (must/should/nice)
- Adds gap closure phases to ROADMAP.md
- Ready for
/kata-plan-phase on new phases
Usage: /kata-plan-milestone-gaps
Configuration
/kata-customize
Manage template overrides for customizing Kata output formats.
- List all customizable templates with override status
- Copy a default template for local editing
- Edit an override with conversational changes
- Validate overrides against required schemas
Usage: /kata-customize
Usage: /kata-customize list
Usage: /kata-customize copy summary-template.md
Usage: /kata-customize validate
/kata-configure-settings
Configure workflow toggles and model profile interactively.
- Toggle researcher, plan checker, verifier agents
- Select model profile (quality/balanced/budget)
- Updates
.planning/config.json
Usage: /kata-configure-settings
/kata-set-profile <profile>
Quick switch model profile for Kata agents.
quality — Opus everywhere except verificationbalanced — Opus for planning, Sonnet for execution (default)budget — Sonnet for writing, Haiku for research/verification
Usage: /kata-set-profile budget
Utility Skills
/kata-help
Show this skill reference.
/kata-whats-new
See what's changed since your installed version.
- Shows installed vs latest version comparison
- Displays changelog entries for versions you've missed
- Highlights breaking changes
- Provides update instructions when behind
Usage: /kata-whats-new
Files & Structure
.planning/
├── PROJECT.md # Project vision
├── REQUIREMENTS.md # Scoped requirements with REQ-IDs
├── ROADMAP.md # Current phase breakdown
├── STATE.md # Project memory & context
├── MILESTONES.md # Completed milestone history
├── config.json # Workflow mode & gates
├── templates/ # Template overrides (customized output formats)
├── research/ # Domain research (from project init)
├── issues/ # Captured ideas and tasks
│ ├── open/ # Issues waiting to be worked on
│ └── done/ # Completed issues
├── debug/ # Active debug sessions
│ └── resolved/ # Archived resolved issues
├── codebase/ # Codebase map (brownfield projects)
│ ├── STACK.md # Languages, frameworks, dependencies
│ ├── ARCHITECTURE.md # Patterns, layers, data flow
│ ├── STRUCTURE.md # Directory layout, key files
│ ├── CONVENTIONS.md # Coding standards, naming
│ ├── TESTING.md # Test setup, patterns
│ ├── INTEGRATIONS.md # External services, APIs
│ └── CONCERNS.md # Tech debt, known issues
├── milestones/ # Archived milestone details
├── quick/ # Quick task plans and summaries
│ └── NNN-slug/
│ ├── PLAN.md
│ └── SUMMARY.md
└── phases/
├── pending/ # Phases not yet started
│ └── 03-next-phase/
│ └── 03-01-PLAN.md
├── active/ # Phase currently being executed
│ └── 02-in-progress/
│ ├── 02-01-PLAN.md
│ └── 02-01-SUMMARY.md
└── completed/ # Finished phases
└── 01-foundation/
├── 01-01-PLAN.md
└── 01-01-SUMMARY.md
Workflow Modes
Set during /kata-new-project:
Interactive Mode
- Confirms each major decision
- Pauses at checkpoints for approval
- More guidance throughout
YOLO Mode
- Auto-approves most decisions
- Executes plans without confirmation
- Only stops for critical checkpoints
Change anytime by editing .planning/config.json
Planning Configuration
Configure how planning artifacts are managed in .planning/config.json:
planning.commit_docs (default: true)
true: Planning artifacts committed to git (standard workflow)false: Planning artifacts kept local-only, not committed
When commit_docs: false:
- Add
.planning/ to your .gitignore
- Useful for OSS contributions, client projects, or keeping planning private
- All planning files still work normally, just not tracked in git
planning.search_gitignored (default: false)
true: Add --no-ignore to broad ripgrep searches- Only needed when
.planning/ is gitignored and you want project-wide searches to include it
Example config:
{
"planning": {
"commit_docs": false,
"search_gitignored": true
}
}
Common Workflows
Starting a new project:
/kata-new-project # Unified flow: questioning → research → requirements → roadmap
/clear
/kata-plan-phase 1 # Create plans for first phase
/clear
/kata-execute-phase 1 # Execute all plans in phase
Resuming work after a break:
/kata-track-progress # See where you left off and continue
Adding urgent mid-milestone work:
/kata-insert-phase 5 "Critical security fix"
/kata-plan-phase 5.1
/kata-execute-phase 5.1
Completing a milestone:
/kata-complete-milestone 1.0.0
/clear
/kata-add-milestone # Start next milestone (questioning → research → requirements → roadmap)
Capturing ideas during work:
/kata-add-issue # Capture from conversation context
/kata-add-issue Fix modal z-index # Capture with explicit description
/kata-check-issues # Review and work on issues
/kata-check-issues api # Filter by area
Debugging an issue:
/kata-debug "form submission fails silently" # Start debug session
# ... investigation happens, context fills up ...
/clear
/kata-debug # Resume from where you left off
Getting Help
- Read
.planning/PROJECT.md for project vision
- Read
.planning/STATE.md for current context
- Check
.planning/ROADMAP.md for phase status
- Run
/kata-track-progress to check where you're up to
