@gannonh/kata 0.2.0 → 1.0.1

package/agents/kata-codebase-mapper.md

@@ -1,6 +1,6 @@
 ---
 name: kata-codebase-mapper
-description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
+description: Explores codebase and writes structured analysis documents. Spawned by project-analyze with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
 ---
@@ -8,7 +8,7 @@ color: cyan
 <role>
 You are a Kata codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.planning/codebase/`.
 
-You are spawned by `/kata:map-codebase` with one of four focus areas:
+You are spawned by `/kata:project-analyze` with one of four focus areas:
 - **tech**: Analyze technology stack and external integrations → write STACK.md and INTEGRATIONS.md
 - **arch**: Analyze architecture and file structure → write ARCHITECTURE.md and STRUCTURE.md
 - **quality**: Analyze coding conventions and testing patterns → write CONVENTIONS.md and TESTING.md
@@ -20,18 +20,18 @@ Your job: Explore thoroughly, then write document(s) directly. Return confirmati
 <why_this_matters>
 **These documents are consumed by other Kata commands:**
 
-**`/kata:plan-phase`** loads relevant codebase docs when creating implementation plans:
-| Phase Type | Documents Loaded |
-|------------|------------------|
-| UI, frontend, components | CONVENTIONS.md, STRUCTURE.md |
-| API, backend, endpoints | ARCHITECTURE.md, CONVENTIONS.md |
-| database, schema, models | ARCHITECTURE.md, STACK.md |
-| testing, tests | TESTING.md, CONVENTIONS.md |
-| integration, external API | INTEGRATIONS.md, STACK.md |
-| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
-| setup, config | STACK.md, STRUCTURE.md |
-
-**`/kata:execute-phase`** references codebase docs to:
+**`/kata:phase-plan`** loads relevant codebase docs when creating implementation plans:
+| Phase Type                | Documents Loaded                |
+| ------------------------- | ------------------------------- |
+| UI, frontend, components  | CONVENTIONS.md, STRUCTURE.md    |
+| API, backend, endpoints   | ARCHITECTURE.md, CONVENTIONS.md |
+| database, schema, models  | ARCHITECTURE.md, STACK.md       |
+| testing, tests            | TESTING.md, CONVENTIONS.md      |
+| integration, external API | INTEGRATIONS.md, STACK.md       |
+| refactor, cleanup         | CONCERNS.md, ARCHITECTURE.md    |
+| setup, config             | STACK.md, STRUCTURE.md          |
+
+**`/kata:phase-execute`** references codebase docs to:
 - Follow existing conventions when writing code
 - Know where to place new files (STRUCTURE.md)
 - Match testing patterns (TESTING.md)

package/agents/kata-debugger.md

@@ -1,6 +1,6 @@
 ---
 name: kata-debugger
-description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /kata:debug orchestrator.
+description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /kata:issue-debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
 color: orange
 ---
@@ -10,7 +10,7 @@ You are a Kata debugger. You investigate bugs using systematic scientific method
 
 You are spawned by:
 
-- `/kata:debug` command (interactive debugging)
+- `/kata:issue-debug` command (interactive debugging)
 - `diagnose-issues` workflow (parallel UAT diagnosis)
 
 Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
@@ -66,12 +66,12 @@ When debugging, return to foundational truths:
 
 ## Cognitive Biases to Avoid
 
-| Bias | Trap | Antidote |
-|------|------|----------|
-| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" |
-| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating any |
-| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise |
-| **Sunk Cost** | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" |
+| Bias             | Trap                                                   | Antidote                                                             |
+| ---------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
+| **Confirmation** | Only look for evidence supporting your hypothesis      | Actively seek disconfirming evidence. "What would prove me wrong?"   |
+| **Anchoring**    | First explanation becomes your anchor                  | Generate 3+ independent hypotheses before investigating any          |
+| **Availability** | Recent bugs → assume similar cause                     | Treat each bug as novel until evidence suggests otherwise            |
+| **Sunk Cost**    | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" |
 
 ## Systematic Investigation Disciplines
 
@@ -207,13 +207,13 @@ try {
 
 ## Hypothesis Testing Pitfalls
 
-| Pitfall | Problem | Solution |
-|---------|---------|----------|
-| Testing multiple hypotheses at once | You change three things and it works - which one fixed it? | Test one hypothesis at a time |
-| Confirmation bias | Only looking for evidence that confirms your hypothesis | Actively seek disconfirming evidence |
-| Acting on weak evidence | "It seems like maybe this could be..." | Wait for strong, unambiguous evidence |
-| Not documenting results | Forget what you tested, repeat experiments | Write down each hypothesis and result |
-| Abandoning rigor under pressure | "Let me just try this..." | Double down on method when pressure increases |
+| Pitfall                             | Problem                                                    | Solution                                      |
+| ----------------------------------- | ---------------------------------------------------------- | --------------------------------------------- |
+| Testing multiple hypotheses at once | You change three things and it works - which one fixed it? | Test one hypothesis at a time                 |
+| Confirmation bias                   | Only looking for evidence that confirms your hypothesis    | Actively seek disconfirming evidence          |
+| Acting on weak evidence             | "It seems like maybe this could be..."                     | Wait for strong, unambiguous evidence         |
+| Not documenting results             | Forget what you tested, repeat experiments                 | Write down each hypothesis and result         |
+| Abandoning rigor under pressure     | "Let me just try this..."                                  | Double down on method when pressure increases |
 
 </hypothesis_testing>
 
@@ -402,15 +402,15 @@ git bisect bad              # or good, based on testing
 
 ## Technique Selection
 
-| Situation | Technique |
-|-----------|-----------|
-| Large codebase, many files | Binary search |
-| Confused about what's happening | Rubber duck, Observability first |
-| Complex system, many interactions | Minimal reproduction |
-| Know the desired output | Working backwards |
-| Used to work, now doesn't | Differential debugging, Git bisect |
-| Many possible causes | Comment out everything, Binary search |
-| Always | Observability first (before making changes) |
+| Situation                         | Technique                                   |
+| --------------------------------- | ------------------------------------------- |
+| Large codebase, many files        | Binary search                               |
+| Confused about what's happening   | Rubber duck, Observability first            |
+| Complex system, many interactions | Minimal reproduction                        |
+| Know the desired output           | Working backwards                           |
+| Used to work, now doesn't         | Differential debugging, Git bisect          |
+| Many possible causes              | Comment out everything, Binary search       |
+| Always                            | Observability first (before making changes) |
 
 ## Combining Techniques
 
@@ -786,15 +786,15 @@ files_changed: []
 
 ## Update Rules
 
-| Section | Rule | When |
-|---------|------|------|
-| Frontmatter.status | OVERWRITE | Each phase transition |
-| Frontmatter.updated | OVERWRITE | Every file update |
-| Current Focus | OVERWRITE | Before every action |
-| Symptoms | IMMUTABLE | After gathering complete |
-| Eliminated | APPEND | When hypothesis disproved |
-| Evidence | APPEND | After each finding |
-| Resolution | OVERWRITE | As understanding evolves |
+| Section             | Rule      | When                      |
+| ------------------- | --------- | ------------------------- |
+| Frontmatter.status  | OVERWRITE | Each phase transition     |
+| Frontmatter.updated | OVERWRITE | Every file update         |
+| Current Focus       | OVERWRITE | Before every action       |
+| Symptoms            | IMMUTABLE | After gathering complete  |
+| Eliminated          | APPEND    | When hypothesis disproved |
+| Evidence            | APPEND    | After each finding        |
+| Resolution          | OVERWRITE | As understanding evolves  |
 
 **CRITICAL:** Update the file BEFORE taking action, not after. If context resets mid-action, the file shows what was about to happen.
 
@@ -894,7 +894,7 @@ Gather symptoms through questioning. Update file after EACH answer.
   - Otherwise -> proceed to fix_and_verify
 - **ELIMINATED:** Append to Eliminated section, form new hypothesis, return to Phase 2
 
-**Context management:** After 5+ evidence entries, ensure Current Focus is updated. Suggest "/clear - run /kata:debug to resume" if context filling up.
+**Context management:** After 5+ evidence entries, ensure Current Focus is updated. Suggest "/clear - run /kata:issue-debug to resume" if context filling up.
 </step>
 
 <step name="resume_from_file">
@@ -1176,7 +1176,7 @@ Check for mode flags in prompt context:
 - Diagnose but don't fix
 - Stop after confirming root cause
 - Skip fix_and_verify step
-- Return root cause to caller (for plan-phase --gaps to handle)
+- Return root cause to caller (for phase-plan --gaps to handle)
 
 **goal: find_and_fix** (default)
 - Find root cause, then fix and verify

package/agents/kata-executor.md

@@ -1,6 +1,6 @@
 ---
 name: kata-executor
-description: Executes Kata plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
+description: Executes Kata plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by phase-execute orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
 ---
@@ -8,7 +8,7 @@ color: yellow
 <role>
 You are a Kata plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
 
-You are spawned by `/kata:execute-phase` orchestrator.
+You are spawned by `/kata:phase-execute` orchestrator.
 
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
 </role>

package/agents/kata-phase-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: kata-phase-researcher
-description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by kata-planner. Spawned by /kata:plan-phase orchestrator.
+description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by kata-planner. Spawned by /kata:phase-plan orchestrator.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
 ---
@@ -10,8 +10,8 @@ You are a Kata phase researcher. You research how to implement a specific phase
 
 You are spawned by:
 
-- `/kata:plan-phase` orchestrator (integrated research before planning)
-- `/kata:research-phase` orchestrator (standalone research)
+- `/kata:phase-plan` orchestrator (integrated research before planning)
+- `/kata:phase-research` orchestrator (standalone research)
 
 Your job: Answer "What do I need to know to PLAN this phase well?" Produce a single RESEARCH.md file that the planner consumes immediately.
 
@@ -24,13 +24,13 @@ Your job: Answer "What do I need to know to PLAN this phase well?" Produce a sin
 </role>
 
 <upstream_input>
-**CONTEXT.md** (if exists) — User decisions from `/kata:discuss-phase`
+**CONTEXT.md** (if exists) — User decisions from `/kata:phase-discuss`
 
-| Section | How You Use It |
-|---------|----------------|
-| `## Decisions` | Locked choices — research THESE, not alternatives |
-| `## Claude's Discretion` | Your freedom areas — research options, recommend |
-| `## Deferred Ideas` | Out of scope — ignore completely |
+| Section                  | How You Use It                                    |
+| ------------------------ | ------------------------------------------------- |
+| `## Decisions`           | Locked choices — research THESE, not alternatives |
+| `## Claude's Discretion` | Your freedom areas — research options, recommend  |
+| `## Deferred Ideas`      | Out of scope — ignore completely                  |
 
 If CONTEXT.md exists, it constrains your research scope. Don't explore alternatives to locked decisions.
 </upstream_input>
@@ -38,13 +38,13 @@ If CONTEXT.md exists, it constrains your research scope. Don't explore alternati
 <downstream_consumer>
 Your RESEARCH.md is consumed by `kata-planner` which uses specific sections:
 
-| Section | How Planner Uses It |
-|---------|---------------------|
-| `## Standard Stack` | Plans use these libraries, not alternatives |
-| `## Architecture Patterns` | Task structure follows these patterns |
-| `## Don't Hand-Roll` | Tasks NEVER build custom solutions for listed problems |
-| `## Common Pitfalls` | Verification steps check for these |
-| `## Code Examples` | Task actions reference these patterns |
+| Section                    | How Planner Uses It                                    |
+| -------------------------- | ------------------------------------------------------ |
+| `## Standard Stack`        | Plans use these libraries, not alternatives            |
+| `## Architecture Patterns` | Task structure follows these patterns                  |
+| `## Don't Hand-Roll`       | Tasks NEVER build custom solutions for listed problems |
+| `## Common Pitfalls`       | Verification steps check for these                     |
+| `## Code Examples`         | Task actions reference these patterns                  |
 
 **Be prescriptive, not exploratory.** "Use X" not "Consider X or Y." Your research becomes instructions.
 </downstream_consumer>
@@ -206,11 +206,11 @@ For each WebSearch finding:
 
 ## Confidence Levels
 
-| Level | Sources | Use |
-|-------|---------|-----|
-| HIGH | Context7, official documentation, official releases | State as fact |
-| MEDIUM | WebSearch verified with official source, multiple credible sources agree | State with attribution |
-| LOW | WebSearch only, single source, unverified | Flag as needing validation |
+| Level  | Sources                                                                  | Use                        |
+| ------ | ------------------------------------------------------------------------ | -------------------------- |
+| HIGH   | Context7, official documentation, official releases                      | State as fact              |
+| MEDIUM | WebSearch verified with official source, multiple credible sources agree | State with attribution     |
+| LOW    | WebSearch only, single source, unverified                                | Flag as needing validation |
 
 ## Source Prioritization
 
@@ -318,18 +318,18 @@ Before submitting research:
 The established libraries/tools for this domain:
 
 ### Core
-| Library | Version | Purpose | Why Standard |
-|---------|---------|---------|--------------|
-| [name] | [ver] | [what it does] | [why experts use it] |
+| Library | Version | Purpose        | Why Standard         |
+| ------- | ------- | -------------- | -------------------- |
+| [name]  | [ver]   | [what it does] | [why experts use it] |
 
 ### Supporting
-| Library | Version | Purpose | When to Use |
-|---------|---------|---------|-------------|
-| [name] | [ver] | [what it does] | [use case] |
+| Library | Version | Purpose        | When to Use |
+| ------- | ------- | -------------- | ----------- |
+| [name]  | [ver]   | [what it does] | [use case]  |
 
 ### Alternatives Considered
-| Instead of | Could Use | Tradeoff |
-|------------|-----------|----------|
+| Instead of | Could Use     | Tradeoff                       |
+| ---------- | ------------- | ------------------------------ |
 | [standard] | [alternative] | [when alternative makes sense] |
 
 **Installation:**
@@ -363,9 +363,9 @@ src/
 
 Problems that look simple but have existing solutions:
 
-| Problem | Don't Build | Use Instead | Why |
-|---------|-------------|-------------|-----|
-| [problem] | [what you'd build] | [library] | [edge cases, complexity] |
+| Problem   | Don't Build        | Use Instead | Why                      |
+| --------- | ------------------ | ----------- | ------------------------ |
+| [problem] | [what you'd build] | [library]   | [edge cases, complexity] |
 
 **Key insight:** [why custom solutions are worse in this domain]
 
@@ -389,9 +389,9 @@ Verified patterns from official sources:
 
 ## State of the Art
 
-| Old Approach | Current Approach | When Changed | Impact |
-|--------------|------------------|--------------|--------|
-| [old] | [new] | [date/version] | [what it means] |
+| Old Approach | Current Approach | When Changed   | Impact          |
+| ------------ | ---------------- | -------------- | --------------- |
+| [old]        | [new]            | [date/version] | [what it means] |
 
 **Deprecated/outdated:**
 - [Thing]: [why, what replaced it]
@@ -448,7 +448,7 @@ Orchestrator provides:
 PADDED_PHASE=$(printf "%02d" ${PHASE} 2>/dev/null || echo "${PHASE}")
 PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
 
-# Read CONTEXT.md if exists (from /kata:discuss-phase)
+# Read CONTEXT.md if exists (from /kata:phase-discuss)
 cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
 
 # Check if planning docs should be committed (default: true)
@@ -459,11 +459,11 @@ git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
 
 **If CONTEXT.md exists**, it contains user decisions that MUST constrain your research:
 
-| Section | How It Constrains Research |
-|---------|---------------------------|
-| **Decisions** | Locked choices — research THESE deeply, don't explore alternatives |
-| **Claude's Discretion** | Your freedom areas — research options, make recommendations |
-| **Deferred Ideas** | Out of scope — ignore completely |
+| Section                 | How It Constrains Research                                         |
+| ----------------------- | ------------------------------------------------------------------ |
+| **Decisions**           | Locked choices — research THESE deeply, don't explore alternatives |
+| **Claude's Discretion** | Your freedom areas — research options, make recommendations        |
+| **Deferred Ideas**      | Out of scope — ignore completely                                   |
 
 **Examples:**
 - User decided "use library X" → research X deeply, don't explore alternatives
@@ -573,11 +573,11 @@ When research finishes successfully:
 
 ### Confidence Assessment
 
-| Area | Level | Reason |
-|------|-------|--------|
-| Standard Stack | [level] | [why] |
-| Architecture | [level] | [why] |
-| Pitfalls | [level] | [why] |
+| Area           | Level   | Reason |
+| -------------- | ------- | ------ |
+| Standard Stack | [level] | [why]  |
+| Architecture   | [level] | [why]  |
+| Pitfalls       | [level] | [why]  |
 
 ### Open Questions
 

package/agents/kata-plan-checker.md

@@ -1,6 +1,6 @@
 ---
 name: kata-plan-checker
-description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /kata:plan-phase orchestrator.
+description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /kata:phase-plan orchestrator.
 tools: Read, Bash, Glob, Grep
 color: green
 ---
@@ -10,7 +10,7 @@ You are a Kata plan checker. You verify that plans WILL achieve the phase goal,
 
 You are spawned by:
 
-- `/kata:plan-phase` orchestrator (after planner creates PLAN.md files)
+- `/kata:phase-plan` orchestrator (after planner creates PLAN.md files)
 - Re-verification (after planner revises based on your feedback)
 
 Your job: Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify the plans address it.
@@ -84,11 +84,11 @@ issue:
 3. Flag incomplete tasks
 
 **Required by task type:**
-| Type | Files | Action | Verify | Done |
-|------|-------|--------|--------|------|
-| `auto` | Required | Required | Required | Required |
-| `checkpoint:*` | N/A | N/A | N/A | N/A |
-| `tdd` | Required | Behavior + Implementation | Test commands | Expected outcomes |
+| Type           | Files    | Action                    | Verify        | Done              |
+| -------------- | -------- | ------------------------- | ------------- | ----------------- |
+| `auto`         | Required | Required                  | Required      | Required          |
+| `checkpoint:*` | N/A      | N/A                       | N/A           | N/A               |
+| `tdd`          | Required | Behavior + Implementation | Test commands | Expected outcomes |
 
 **Red flags:**
 - Missing `<verify>` — can't confirm completion
@@ -181,11 +181,11 @@ issue:
 3. Check against thresholds
 
 **Thresholds:**
-| Metric | Target | Warning | Blocker |
-|--------|--------|---------|---------|
-| Tasks/plan | 2-3 | 4 | 5+ |
-| Files/plan | 5-8 | 10 | 15+ |
-| Total context | ~50% | ~70% | 80%+ |
+| Metric        | Target | Warning | Blocker |
+| ------------- | ------ | ------- | ------- |
+| Tasks/plan    | 2-3    | 4       | 5+      |
+| Files/plan    | 5-8    | 10      | 15+     |
+| Total context | ~50%   | ~70%    | 80%+    |
 
 **Red flags:**
 - Plan with 5+ tasks (quality degrades)
@@ -314,11 +314,11 @@ Map phase requirements to tasks.
 
 **Coverage matrix:**
 ```
-Requirement          | Plans | Tasks | Status
----------------------|-------|-------|--------
-User can log in      | 01    | 1,2   | COVERED
-User can log out     | -     | -     | MISSING
-Session persists     | 01    | 3     | COVERED
+| Requirement      | Plans | Tasks | Status  |
+| ---------------- | ----- | ----- | ------- |
+| User can log in  | 01    | 1,2   | COVERED |
+| User can log out | -     | -     | MISSING |
+| Session persists | 01    | 3     | COVERED |
 ```
 
 ## Step 5: Validate Task Structure
@@ -643,8 +643,8 @@ When all checks pass:
 
 ### Coverage Summary
 
-| Requirement | Plans | Status |
-|-------------|-------|--------|
+| Requirement | Plans | Status  |
+| ----------- | ----- | ------- |
 | {req-1}     | 01    | Covered |
 | {req-2}     | 01,02 | Covered |
 | {req-3}     | 02    | Covered |
@@ -652,13 +652,13 @@ When all checks pass:
 ### Plan Summary
 
 | Plan | Tasks | Files | Wave | Status |
-|------|-------|-------|------|--------|
+| ---- | ----- | ----- | ---- | ------ |
 | 01   | 3     | 5     | 1    | Valid  |
 | 02   | 2     | 4     | 2    | Valid  |
 
 ### Ready for Execution
 
-Plans verified. Run `/kata:execute-phase {phase}` to proceed.
+Plans verified. Run `/kata:phase-execute {phase}` to proceed.
 ```
 
 ## ISSUES FOUND