@gannonh/kata 0.1.4 → 0.2.0

package/skills/kata-executing-quick-tasks/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: kata-executing-quick-tasks
+description: Use this skill when executing small ad-hoc tasks with Kata guarantees, running quick tasks without full planning, or handling one-off work outside the roadmap. Triggers include "quick task", "quick mode", "quick fix", "ad-hoc task", "small task", and "one-off task".
+version: 0.1.0
+user-invocable: false
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Execute small, ad-hoc tasks with Kata guarantees (atomic commits, STATE.md tracking) while skipping optional agents (research, plan-checker, verifier).
+
+Quick mode is the same system with a shorter path:
+- Spawns kata-planner (quick mode) + kata-executor(s)
+- Skips kata-phase-researcher, kata-plan-checker, kata-verifier
+- Quick tasks live in `.planning/quick/` separate from planned phases
+- Updates STATE.md "Quick Tasks Completed" table (NOT ROADMAP.md)
+
+Use when: You know exactly what to do and the task is small enough to not need research or verification.
+</objective>
+
+<execution_context>
+Orchestration is inline - no separate workflow file. Quick mode is deliberately simpler than full Kata.
+</execution_context>
+
+<context>
+@.planning/STATE.md
+</context>
+
+<process>
+**Step 0: Resolve Model Profile**
+
+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-executor | opus | sonnet | sonnet |
+
+Store resolved models for use in Task calls below.
+
+---
+
+**Step 1: Pre-flight validation**
+
+Check that an active Kata project exists:
+
+```bash
+if [ ! -f .planning/ROADMAP.md ]; then
+  echo "Quick mode requires an active project with ROADMAP.md."
+  echo "Run /kata:new-project first."
+  exit 1
+fi
+```
+
+If validation fails, stop immediately with the error message.
+
+Quick tasks can run mid-phase - validation only checks ROADMAP.md exists, not phase status.
+
+---
+
+**Step 2: Get task description**
+
+Prompt user interactively for the task description:
+
+```
+AskUserQuestion(
+  header: "Quick Task",
+  question: "What do you want to do?",
+  followUp: null
+)
+```
+
+Store response as `$DESCRIPTION`.
+
+If empty, re-prompt: "Please provide a task description."
+
+Generate slug from description:
+```bash
+slug=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+```
+
+---
+
+**Step 3: Calculate next quick task number**
+
+Ensure `.planning/quick/` directory exists and find the next sequential number:
+
+```bash
+# Ensure .planning/quick/ exists
+mkdir -p .planning/quick
+
+# Find highest existing number and increment
+last=$(ls -1d .planning/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1 | xargs -I{} basename {} | grep -oE '^[0-9]+')
+
+if [ -z "$last" ]; then
+  next_num="001"
+else
+  next_num=$(printf "%03d" $((10#$last + 1)))
+fi
+```
+
+---
+
+**Step 4: Create quick task directory**
+
+Create the directory for this quick task:
+
+```bash
+QUICK_DIR=".planning/quick/${next_num}-${slug}"
+mkdir -p "$QUICK_DIR"
+```
+
+Report to user:
+```
+Creating quick task ${next_num}: ${DESCRIPTION}
+Directory: ${QUICK_DIR}
+```
+
+Store `$QUICK_DIR` for use in orchestration.
+
+---
+
+**Step 5: Spawn planner (quick mode)**
+
+Spawn kata-planner with quick mode context:
+
+```
+Task(
+  prompt="
+<planning_context>
+
+**Mode:** quick
+**Directory:** ${QUICK_DIR}
+**Description:** ${DESCRIPTION}
+
+**Project State:**
+@.planning/STATE.md
+
+</planning_context>
+
+<constraints>
+- Create a SINGLE plan with 1-3 focused tasks
+- Quick tasks should be atomic and self-contained
+- No research phase, no checker phase
+- Target ~30% context usage (simple, focused)
+</constraints>
+
+<output>
+Write plan to: ${QUICK_DIR}/${next_num}-PLAN.md
+Return: ## PLANNING COMPLETE with plan path
+</output>
+",
+  subagent_type="kata-planner",
+  model="{planner_model}",
+  description="Quick plan: ${DESCRIPTION}"
+)
+```
+
+After planner returns:
+1. Verify plan exists at `${QUICK_DIR}/${next_num}-PLAN.md`
+2. Extract plan count (typically 1 for quick tasks)
+3. Report: "Plan created: ${QUICK_DIR}/${next_num}-PLAN.md"
+
+If plan not found, error: "Planner failed to create ${next_num}-PLAN.md"
+
+---
+
+**Step 6: Spawn executor**
+
+Spawn kata-executor with plan reference:
+
+```
+Task(
+  prompt="
+Execute quick task ${next_num}.
+
+Plan: @${QUICK_DIR}/${next_num}-PLAN.md
+Project state: @.planning/STATE.md
+
+<constraints>
+- Execute all tasks in the plan
+- Commit each task atomically
+- Create summary at: ${QUICK_DIR}/${next_num}-SUMMARY.md
+- Do NOT update ROADMAP.md (quick tasks are separate from planned phases)
+</constraints>
+",
+  subagent_type="kata-executor",
+  model="{executor_model}",
+  description="Execute: ${DESCRIPTION}"
+)
+```
+
+After executor returns:
+1. Verify summary exists at `${QUICK_DIR}/${next_num}-SUMMARY.md`
+2. Extract commit hash from executor output
+3. Report completion status
+
+If summary not found, error: "Executor failed to create ${next_num}-SUMMARY.md"
+
+Note: For quick tasks producing multiple plans (rare), spawn executors in parallel waves per execute-phase patterns.
+
+---
+
+**Step 7: Update STATE.md**
+
+Update STATE.md with quick task completion record.
+
+**7a. Check if "Quick Tasks Completed" section exists:**
+
+Read STATE.md and check for `### Quick Tasks Completed` section.
+
+**7b. If section doesn't exist, create it:**
+
+Insert after `### Blockers/Concerns` section:
+
+```markdown
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+```
+
+**7c. Append new row to table:**
+
+```markdown
+| ${next_num} | ${DESCRIPTION} | $(date +%Y-%m-%d) | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+```
+
+**7d. Update "Last activity" line:**
+
+Find and update the line:
+```
+Last activity: $(date +%Y-%m-%d) - Completed quick task ${next_num}: ${DESCRIPTION}
+```
+
+Use Edit tool to make these changes atomically
+
+---
+
+**Step 8: Final commit and completion**
+
+Stage and commit quick task artifacts:
+
+```bash
+# Stage quick task artifacts
+git add ${QUICK_DIR}/${next_num}-PLAN.md
+git add ${QUICK_DIR}/${next_num}-SUMMARY.md
+git add .planning/STATE.md
+
+# Commit with quick task format
+git commit -m "$(cat <<'EOF'
+docs(quick-${next_num}): ${DESCRIPTION}
+
+Quick task completed.
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+Get final commit hash:
+```bash
+commit_hash=$(git rev-parse --short HEAD)
+```
+
+Display completion output:
+```
+---
+
+Kata > QUICK TASK COMPLETE
+
+Quick Task ${next_num}: ${DESCRIPTION}
+
+Summary: ${QUICK_DIR}/${next_num}-SUMMARY.md
+Commit: ${commit_hash}
+
+---
+
+Ready for next task: /kata:quick
+```
+
+</process>
+
+<success_criteria>
+- [ ] ROADMAP.md validation passes
+- [ ] User provides task description
+- [ ] Slug generated (lowercase, hyphens, max 40 chars)
+- [ ] Next number calculated (001, 002, 003...)
+- [ ] Directory created at `.planning/quick/NNN-slug/`
+- [ ] `${next_num}-PLAN.md` created by planner
+- [ ] `${next_num}-SUMMARY.md` created by executor
+- [ ] STATE.md updated with quick task row
+- [ ] Artifacts committed
+</success_criteria>

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

@@ -0,0 +1,229 @@
+---
+name: kata-inserting-phases
+description: Use this skill when inserting urgent work as a decimal phase between existing phases, adding mid-milestone work, or creating intermediate phases. Triggers include "insert phase", "add urgent phase", "create decimal phase", "insert between phases", and "urgent work".
+version: 0.1.0
+user-invocable: false
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<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>

package/skills/kata-listing-phase-assumptions/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: kata-listing-phase-assumptions
+description: Use this skill when surfacing Claude's assumptions about a phase approach before planning, checking what Claude thinks, or validating understanding before planning. Triggers include "list assumptions", "what are you thinking", "show assumptions", "phase assumptions", and "what's the plan".
+version: 0.1.0
+user-invocable: false
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+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>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/list-phase-assumptions.md
+</execution_context>
+
+<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>

package/skills/kata-mapping-codebases/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: kata-mapping-codebases
+description: Use this skill when analyzing an existing codebase with parallel mapper agents, creating codebase documentation, understanding brownfield projects, or mapping code structure. Triggers include "map codebase", "analyze codebase", "document codebase", "understand code", and "codebase map".
+version: 0.1.0
+user-invocable: false
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Write
+  - 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/get-shit-done/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
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<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>
+
+<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>