@gannonh/kata 1.1.1 → 1.1.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+Copyright (c) 2026 Gannon Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,600 @@
+<div align="center">
+
+# KATA
+
+**型** · /ˈkɑːtɑː/ · *noun*
+<br>
+<sub>a choreographed pattern practiced repeatedly until perfected</sub>
+
+<br>
+
+Agent orchestration framework for spec-driven development.
+<br>
+
+[kata.sh](https://kata.sh)
+
+<br>
+
+[![Plugin](https://img.shields.io/badge/plugin-kata--marketplace-blue?style=for-the-badge)](https://github.com/gannonh/kata-marketplace)
+[![npm version](https://img.shields.io/npm/v/@gannonh/kata?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@gannonh/kata)
+
+<br>
+
+[![Kata Install](assets/terminal.svg)](https://kata.sh/)
+
+<br>
+
+</div>
+
+
+```bash
+# Install as Claude Code plugin
+/plugin marketplace add gannonh/kata-marketplace
+/plugin install kata@gannonh-kata-marketplace
+
+# Or install via NPM
+npx @gannonh/kata
+```
+
+---
+
+## Talk to It Like a Person
+
+Drive your entire workflow with **natural language**.
+
+Say what you want:
+
+| You say...               | Kata does...                           |
+| ------------------------ | -------------------------------------- |
+| "Start a new project"    | Launches full project initialization   |
+| "What's the status?"     | Shows progress, next steps, blockers   |
+| "Plan phase 2"           | Researches and creates execution plans |
+| "Execute the phase"      | Runs all plans with parallel agents    |
+| "I'm done for today"     | Creates handoff for session resumption |
+| "Debug this login issue" | Spawns systematic debugging workflow   |
+
+Every workflow responds to natural language. Slash commands exist for precision when you want them (`/kata:planning-phases 2`), but you never *need* them.
+
+**Intent recognition.** Kata parses what you're trying to accomplish and routes to the right workflow (research, planning, execution, verification) automatically.
+
+---
+
+## Who This Is For
+
+Teams and individuals that want to describe what they want and have it built correctly.
+
+---
+
+<!-- sanitize -->
+## Getting Started
+
+### Recommended: Plugin Install
+
+```bash
+/plugin marketplace add gannonh/kata-marketplace
+/plugin install kata@gannonh-kata-marketplace
+```
+
+Verify with `/kata:providing-help` (plugin) or `/kata-providing-help` (NPX) inside Claude Code.
+
+<details>
+<summary><strong>Alternative: NPM Install</strong></summary>
+
+```bash
+npx @gannonh/kata
+```
+
+Use NPM if you prefer global installation or need CI/container support.
+
+</details>
+
+### Staying Updated
+
+Kata evolves fast. Check for updates periodically:
+
+```
+/kata:showing-whats-new   # plugin
+/kata-showing-whats-new   # NPX
+```
+
+**Plugin users:**
+```bash
+claude plugin update kata@gannonh-kata-marketplace
+```
+
+**NPM users:**
+```bash
+npx @gannonh/kata@latest
+```
+
+<details>
+<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
+
+```bash
+npx @gannonh/kata --global   # Install to ~/.claude/
+npx @gannonh/kata --local    # Install to ./.claude/
+```
+
+Use `--global` (`-g`) or `--local` (`-l`) to skip the interactive prompt.
+
+</details>
+
+<details>
+<summary><strong>Development Installation</strong></summary>
+
+Clone the repository and run the installer locally:
+
+```bash
+git clone https://github.com/gannonh/kata.git
+cd kata
+node bin/install.js --local
+```
+
+Installs to `./.claude/` for testing modifications before contributing.
+
+</details>
+
+### Recommended: Skip Permissions Mode
+
+Kata is designed for frictionless automation. Run Claude Code with:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+> [!TIP]
+> Kata works best this way. Approving `date` and `git commit` 50 times defeats the purpose.
+
+<details>
+<summary><strong>Alternative: Granular Permissions</strong></summary>
+
+If you prefer not to use that flag, add this to your project's `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(date:*)",
+      "Bash(echo:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(mkdir:*)",
+      "Bash(wc:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(sort:*)",
+      "Bash(grep:*)",
+      "Bash(tr:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git tag:*)"
+    ]
+  }
+}
+```
+
+</details>
+
+---
+
+## How It Works
+
+> **Already have code?** Run `/kata:mapping-codebases` (plugin) or `/kata-mapping-codebases` (NPX) first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then your next project setup knows your codebase. Questions focus on what you're adding, and planning automatically loads your patterns.
+
+### 1. Initialize Project
+
+```
+"Start a new project"
+```
+<sub>or `/kata:starting-projects` (plugin) | `/kata-starting-projects` (NPX)</sub>
+
+One command, one flow. The system:
+
+1. **Questions**: Asks until it understands your idea completely (goals, constraints, tech preferences, edge cases)
+2. **Research**: Spawns parallel agents to investigate the domain (optional but recommended)
+3. **Requirements**: Extracts what's v1, v2, and out of scope
+4. **Roadmap**: Creates phases mapped to requirements
+
+You approve the roadmap. Now you're ready to build.
+
+**Creates:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+
+---
+
+### 2. Discuss Phase
+
+```
+"Let's discuss phase 1"
+```
+<sub>or `/kata:discussing-phases 1` (plugin) | `/kata-discussing-phases 1` (NPX)</sub>
+
+**This is where you shape the implementation.**
+
+Your roadmap has a sentence or two per phase. That's not enough context to build something the way *you* imagine it. This step captures your preferences before anything gets researched or planned.
+
+The system analyzes the phase and identifies gray areas based on what's being built:
+
+- **Visual features** → Layout, density, interactions, empty states
+- **APIs/CLIs** → Response format, flags, error handling, verbosity
+- **Content systems** → Structure, tone, depth, flow
+- **Organization tasks** → Grouping criteria, naming, duplicates, exceptions
+
+For each area you select, it asks until you're satisfied. The output (`CONTEXT.md`) feeds directly into the next two steps:
+
+1. **Researcher reads it**: Knows what patterns to investigate ("user wants card layout" → research card component libraries)
+2. **Planner reads it**: Knows what decisions are locked ("infinite scroll decided" → plan includes scroll handling)
+
+Depth here correlates with alignment to your intent. Skip it for reasonable defaults.
+
+**Creates:** `{phase}-CONTEXT.md`
+
+---
+
+### 3. Plan Phase
+
+```
+"Plan phase 1"
+```
+<sub>or `/kata:planning-phases 1` (plugin) | `/kata-planning-phases 1` (NPX)</sub>
+
+The system:
+
+1. **Researches**: Investigates how to implement this phase, guided by your CONTEXT.md decisions
+2. **Plans**: Creates 2-3 atomic task plans with XML structure
+3. **Verifies**: Checks plans against requirements, loops until they pass
+
+Each plan fits in a fresh context window.
+
+**Creates:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`
+
+---
+
+### 4. Execute Phase
+
+```
+"Execute phase 1"
+```
+<sub>or `/kata:executing-phases 1` (plugin) | `/kata-executing-phases 1` (NPX)</sub>
+
+The system:
+
+1. **Runs plans in waves**: Parallel where possible, sequential when dependent
+2. **Fresh context per plan**: 200k tokens for implementation, zero accumulated garbage
+3. **Commits per task**: Every task gets its own atomic commit
+4. **Verifies against goals**: Checks the codebase delivers what the phase promised
+
+Walk away, come back to completed work with clean git history.
+
+**Creates:** `{phase}-{N}-SUMMARY.md`, `{phase}-VERIFICATION.md`
+
+---
+
+### 5. Verify Work
+
+```
+"Verify phase 1"
+```
+<sub>or `/kata:verifying-phases 1` (plugin) | `/kata-verifying-phases 1` (NPX)</sub>
+
+**This is where you confirm it actually works.**
+
+Automated verification checks that code exists and tests pass. But does the feature *work* the way you expected? This is your chance to use it.
+
+The system:
+
+1. **Extracts testable deliverables**: What you should be able to do now
+2. **Walks you through one at a time**: "Can you log in with email?" Yes/no, or describe what's wrong
+3. **Diagnoses failures automatically**: Spawns debug agents to find root causes
+4. **Creates verified fix plans**: Ready for immediate re-execution
+
+If everything passes, you move on. If something's broken, run `/kata:executing-phases` again with the fix plans it created.
+
+**Creates:** `{phase}-UAT.md`, fix plans if issues found
+
+---
+
+### 6. Repeat → Complete → Next Milestone
+
+```
+"Discuss phase 2"
+"Plan phase 2"
+"Execute phase 2"
+"Verify phase 2"
+...
+"Complete the milestone"
+"Start the next milestone"
+```
+
+Loop **discuss → plan → execute → verify** until milestone complete.
+
+Each phase gets your input (discuss), proper research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high.
+
+When all phases are done, "complete the milestone" archives the milestone and tags the release.
+
+Then "start the next milestone" kicks off the next version. Same flow as project initialization for your existing codebase. You describe what you want to build next, the system researches the domain, you scope requirements, and it creates a fresh roadmap. Each milestone is a clean cycle: define → build → ship.
+
+---
+
+### Quick Mode
+
+```
+"Quick task: add dark mode toggle"
+```
+<sub>or `/kata:executing-quick-tasks` (plugin) | `/kata-executing-quick-tasks` (NPX)</sub>
+
+**For ad-hoc tasks that don't need full planning.**
+
+Quick mode gives you Kata guarantees (atomic commits, state tracking) with a faster path:
+
+- **Same agents**: Planner + executor, same quality
+- **Skips optional steps**: No research, no plan checker, no verifier
+- **Separate tracking**: Lives in `.planning/quick/`
+
+Use for: bug fixes, small features, config changes, one-off tasks.
+
+```
+"Quick task: add dark mode toggle to settings"
+```
+
+**Creates:** `.planning/quick/001-add-dark-mode-toggle/PLAN.md`, `SUMMARY.md`
+
+---
+
+## Why It Works
+
+### Context Engineering
+
+Claude Code requires the right context to perform well. Kata manages context for you:
+
+| File              | What it does                                                  |
+| ----------------- | ------------------------------------------------------------- |
+| `PROJECT.md`      | Project vision, always loaded                                 |
+| `research/`       | Ecosystem knowledge (stack, features, architecture, pitfalls) |
+| `REQUIREMENTS.md` | Scoped v1/v2 requirements with phase traceability             |
+| `ROADMAP.md`      | Where you're going, what's done                               |
+| `STATE.md`        | Decisions, blockers, position. Memory across sessions         |
+| `PLAN.md`         | Atomic task with XML structure, verification steps            |
+| `SUMMARY.md`      | What happened, what changed, committed to history             |
+| `todos/`          | Captured ideas and tasks for later work                       |
+
+Size limits based on where Claude's quality degrades.
+
+### XML Prompt Formatting
+
+Every plan is structured XML optimized for Claude:
+
+```xml
+<task type="auto">
+  <name>Create login endpoint</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>
+    Use jose for JWT (not jsonwebtoken - CommonJS issues).
+    Validate credentials against users table.
+    Return httpOnly cookie on success.
+  </action>
+  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
+  <done>Valid credentials return cookie, invalid return 401</done>
+</task>
+```
+
+Precise instructions with verification built in.
+
+### Multi-Agent Orchestration
+
+Every stage uses the same pattern: a thin orchestrator spawns specialized agents, collects results, and routes to the next step.
+
+| Stage        | Orchestrator does                  | Agents do                                                                  |
+| ------------ | ---------------------------------- | -------------------------------------------------------------------------- |
+| Research     | Coordinates, presents findings     | 4 parallel researchers investigate stack, features, architecture, pitfalls |
+| Planning     | Validates, manages iteration       | Planner creates plans, checker verifies, loop until pass                   |
+| Execution    | Groups into waves, tracks progress | Executors implement in parallel, each with fresh 200k context              |
+| Verification | Presents results, routes next      | Verifier checks codebase against goals, debuggers diagnose failures        |
+
+The orchestrator never does heavy lifting. It spawns agents, waits, integrates results.
+
+**The result:** You can run an entire phase (research, planning, execution, verification) and your main context window stays at 30-40%. The work happens in fresh subagent contexts.
+
+### Atomic Git Commits
+
+Each task gets its own commit immediately after completion:
+
+```bash
+abc123f docs(08-02): complete user registration plan
+def456g feat(08-02): add email confirmation flow
+hij789k feat(08-02): implement password hashing
+lmn012o feat(08-02): create registration endpoint
+```
+
+> [!NOTE]
+> **Benefits:** Git bisect finds exact failing task. Each task independently revertable. Clear history for Claude in future sessions. Better observability in AI-automated workflow.
+
+Every commit is traceable and revertable.
+
+### Modular by Design
+
+- Add phases to current milestone
+- Insert urgent work between phases
+- Complete milestones and start fresh
+- Adjust plans without rebuilding everything
+
+The system adapts to changing requirements.
+
+---
+
+## Skills
+
+> **Remember:** All skills respond to natural language. "What's my progress?" works the same as `/kata:tracking-progress` (plugin) or `/kata-tracking-progress` (NPX).
+
+Skills are invoked via slash commands. The syntax differs between plugin and NPX installations:
+
+| Installation | Syntax | Example |
+| ------------ | ------ | ------- |
+| Plugin | `/kata:skill-name` | `/kata:planning-phases 1` |
+| NPX | `/kata-skill-name` | `/kata-planning-phases 1` |
+
+### Core Workflow
+
+| Skill | What it does |
+| ----- | ------------ |
+| `starting-projects` | Full initialization: questions → research → requirements → roadmap |
+| `discussing-phases [N]` | Capture implementation decisions before planning |
+| `planning-phases [N]` | Research + plan + verify for a phase |
+| `executing-phases <N>` | Execute all plans in parallel waves, verify when complete |
+| `verifying-phases [N]` | Manual user acceptance testing |
+| `auditing-milestones` | Verify milestone achieved its definition of done |
+| `completing-milestones` | Archive milestone, tag release |
+| `starting-milestones [name]` | Start next version: questions → research → requirements → roadmap |
+
+### Navigation
+
+| Skill | What it does |
+| ----- | ------------ |
+| `tracking-progress` | Where am I? What's next? |
+| `providing-help` | Show all skills and usage guide |
+| `showing-whats-new` | See what changed since your installed version |
+| `updating` | Update Kata with changelog preview (NPX only) |
+
+### Brownfield
+
+| Skill | What it does |
+| ----- | ------------ |
+| `mapping-codebases` | Analyze existing codebase before project setup |
+
+### Phase Management
+
+| Skill | What it does |
+| ----- | ------------ |
+| `adding-phases` | Append phase to roadmap |
+| `inserting-phases [N]` | Insert urgent work between phases |
+| `removing-phases [N]` | Remove future phase, renumber |
+| `listing-phase-assumptions [N]` | See Claude's intended approach before planning |
+| `planning-milestone-gaps` | Create phases to close gaps from audit |
+
+### Session
+
+| Skill | What it does |
+| ----- | ------------ |
+| `pausing-work` | Create handoff when stopping mid-phase |
+| `resuming-work` | Restore from last session |
+
+### Utilities
+
+| Skill | What it does |
+| ----- | ------------ |
+| `configuring-settings` | Configure model profile and workflow agents |
+| `setting-profiles <profile>` | Switch model profile (quality/balanced/budget) |
+| `adding-todos [desc]` | Capture idea for later |
+| `checking-todos` | List pending todos |
+| `debugging [desc]` | Systematic debugging with persistent state |
+| `executing-quick-tasks` | Execute ad-hoc task with Kata guarantees |
+
+---
+
+## Configuration
+
+Kata stores project settings in `.planning/config.json`. Configure during `/kata:starting-projects` or update later with `/kata:configuring-settings`.
+
+### Core Settings
+
+| Setting | Options                              | Default       | What it controls                       |
+| ------- | ------------------------------------ | ------------- | -------------------------------------- |
+| `mode`  | `yolo`, `interactive`                | `interactive` | Auto-approve vs confirm at each step   |
+| `depth` | `quick`, `standard`, `comprehensive` | `standard`    | Planning thoroughness (phases × plans) |
+
+### Model Profiles
+
+Control which Claude model each agent uses. Balance quality vs token spend.
+
+| Profile              | Planning | Execution | Verification |
+| -------------------- | -------- | --------- | ------------ |
+| `quality`            | Opus     | Opus      | Sonnet       |
+| `balanced` (default) | Opus     | Sonnet    | Sonnet       |
+| `budget`             | Sonnet   | Sonnet    | Haiku        |
+
+Switch profiles:
+```
+/kata:setting-profiles budget
+```
+
+Or configure via `/kata:configuring-settings`.
+
+### Workflow Agents
+
+These spawn additional agents during planning/execution. They improve quality but add tokens and time.
+
+| Setting               | Default | What it does                                        |
+| --------------------- | ------- | --------------------------------------------------- |
+| `workflow.research`   | `true`  | Researches domain before planning each phase        |
+| `workflow.plan_check` | `true`  | Verifies plans achieve phase goals before execution |
+| `workflow.verifier`   | `true`  | Confirms must-haves were delivered after execution  |
+
+Use `/kata:configuring-settings` to toggle these, or override per-invocation:
+- `planning-phases --skip-research`
+- `planning-phases --skip-verify`
+
+### Execution
+
+| Setting                   | Default | What it controls                     |
+| ------------------------- | ------- | ------------------------------------ |
+| `parallelization.enabled` | `true`  | Run independent plans simultaneously |
+| `planning.commit_docs`    | `true`  | Track `.planning/` in git            |
+
+---
+
+## Troubleshooting
+
+**Skills not found after install?**
+- Restart Claude Code to reload skills
+- **Plugin:** Verify skills exist in `./.claude/skills/` (prefixes stripped)
+- **NPX:** Verify skills exist in `~/.claude/skills/kata-*` (global) or `./.claude/skills/kata-*` (local)
+
+**Skills not working as expected?**
+- Run `/kata:providing-help` (plugin) or `/kata-providing-help` (NPX) to verify installation
+- Re-run `npx @gannonh/kata` to reinstall
+
+**Updating to the latest version?**
+```bash
+npx @gannonh/kata@latest
+```
+
+**Using Docker or containerized environments?**
+
+If file reads fail with tilde paths (`~/.claude/...`), set `CLAUDE_CONFIG_DIR` before installing:
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @gannonh/kata --global
+```
+This ensures absolute paths are used instead of `~` which may not expand correctly in containers.
+
+---
+
+## Background
+
+This project began as a fork of the [GSD system](https://github.com/glittercowboy/get-shit-done), and then quickly became a hard fork. Why hard fork and not contribute to the original project? The reasons are two fold, well three fold, or two and a half-fold.
+
+- **Team-oriented by design.** GSD is optimized for solo devs, viewing "enterprise" features as anti-patterns. I respect that position, but my projects are multi-player. At a minimum, I need:
+  - **GitHub integration**: PRs, issues, code review workflows. Planning that connects to where teams actually collaborate.
+  - **IDE agnostic**: Kata should work with the tools teams already use.
+
+- **Skills as the foundation.** GSD is built on `/commands`, which are Claude Code-specific. Kata standardizes on **skills**, an emerging open standard supported across major agentic frameworks.
+  - Portable across tools.
+  - Progressive disclosure keeps prompts lean.
+  - Natural language instantiation (useful for voice input).
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Kata adds structure to Claude Code.**
+
+*Tell it what you want.*
+
+</div>

package/hooks/dist/kata-check-update.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Check for Kata updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { spawn } from 'child_process';
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+
+// Detect local vs global installation by checking VERSION file
+// This single check tells us both: existence = local install, contents = version
+const localVersionFile = path.join(cwd, '.claude', 'kata', 'VERSION');
+const globalVersionFile = path.join(homeDir, '.claude', 'kata', 'VERSION');
+const isLocalInstall = fs.existsSync(localVersionFile);
+
+// Use paths based on installation type - cache location matches install context
+const versionFile = isLocalInstall ? localVersionFile : globalVersionFile;
+const cacheDir = isLocalInstall
+  ? path.join(cwd, '.claude', 'kata', 'cache')
+  : path.join(homeDir, '.claude', 'kata', 'cache');
+const cacheFile = path.join(cacheDir, 'update-check.json');
+
+// Store cwd in cache so statusline can detect stale cache
+const checkedCwd = cwd;
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn detached process)
+// Note: The spawned process uses --input-type=module for ESM compatibility
+const child = spawn(process.execPath, ['--input-type=module', '-e', `
+  import fs from 'fs';
+  import { execSync } from 'child_process';
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const versionFile = ${JSON.stringify(versionFile)};
+  const checkedCwd = ${JSON.stringify(checkedCwd)};
+  const isLocalInstall = ${JSON.stringify(isLocalInstall)};
+
+  let installed = '0.0.0';
+  try {
+    installed = fs.readFileSync(versionFile, 'utf8').trim();
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view @gannonh/kata version', { encoding: 'utf8', timeout: 10000 }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000),
+    cwd: checkedCwd,
+    isLocalInstall: isLocalInstall
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  detached: true,
+  stdio: 'ignore'
+});
+
+child.unref();

package/hooks/dist/kata-npm-statusline.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Claude Code Statusline - Kata Edition
+// Shows: model | current task | directory | context usage
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage)
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const used = 100 - rem;
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(10 - filled);
+
+      // Color based on usage
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m\u{1F480} ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      const files = fs.readdirSync(todosDir)
+        .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        try {
+          const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+          const inProgress = todos.find(t => t.status === 'in_progress');
+          if (inProgress) task = inProgress.activeForm || '';
+        } catch (e) {}
+      }
+    }
+
+    // Kata update available?
+    let kataUpdate = '';
+    const currentDir = dir;
+
+    // Detect local vs global installation by checking VERSION file
+    const localVersionFile = path.join(currentDir, '.claude', 'kata', 'VERSION');
+    const currentIsLocalInstall = fs.existsSync(localVersionFile);
+
+    // Read cache from location matching current context
+    const cacheFile = currentIsLocalInstall
+      ? path.join(currentDir, '.claude', 'kata', 'cache', 'update-check.json')
+      : path.join(homeDir, '.claude', 'kata', 'cache', 'update-check.json');
+
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+
+        // Validate cache matches current context (sanity check)
+        const cacheIsRelevant = currentIsLocalInstall
+          ? (cache.isLocalInstall && cache.cwd === currentDir)
+          : !cache.isLocalInstall;
+
+        if (cache.update_available && cacheIsRelevant) {
+          kataUpdate = '\x1b[33m\u2B06 /kata:update\x1b[0m \u2502 ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${kataUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${kataUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/hooks/dist/kata-plugin-statusline.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Claude Code Statusline - Kata Plugin Edition
+// Shows: model | current task | directory | context usage
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage)
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const used = 100 - rem;
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(10 - filled);
+
+      // Color based on usage
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m\u{1F480} ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      const files = fs.readdirSync(todosDir)
+        .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        try {
+          const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+          const inProgress = todos.find(t => t.status === 'in_progress');
+          if (inProgress) task = inProgress.activeForm || '';
+        } catch (e) {}
+      }
+    }
+
+    // Kata update available?
+    let kataUpdate = '';
+    const currentDir = dir;
+
+    // For plugin installs, check the project-local cache
+    const cacheFile = path.join(currentDir, '.claude', 'kata', 'cache', 'update-check.json');
+
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+
+        if (cache.update_available) {
+          // Plugin update message with version and both update methods
+          const latest = cache.latest || 'new';
+          kataUpdate = `\x1b[33m⬆ v${latest}: /plugin (CC) or claude plugin update kata@kata-marketplace (term)\x1b[0m \u2502 `;
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${kataUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${kataUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/hooks/dist/kata-setup-statusline.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Kata Statusline Setup Hook
+// Runs on SessionStart to set up the statusline if configured
+
+import fs from 'fs';
+import path from 'path';
+
+// Read JSON from stdin (SessionStart hook input)
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const cwd = data.cwd || process.cwd();
+    const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+
+    // Check if statusline is enabled in config
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    if (!fs.existsSync(configPath)) {
+      process.exit(0); // No config, nothing to do
+    }
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (!config.display?.statusline) {
+      process.exit(0); // Statusline not enabled
+    }
+
+    // Check if statusline hook already exists
+    const projectHookPath = path.join(cwd, '.claude', 'hooks', 'kata-statusline.js');
+    if (fs.existsSync(projectHookPath)) {
+      process.exit(0); // Already set up
+    }
+
+    // Find the source statusline hook
+    let sourceHook = null;
+
+    // Try plugin root first
+    if (pluginRoot) {
+      const pluginHook = path.join(pluginRoot, 'hooks', 'kata-plugin-statusline.js');
+      if (fs.existsSync(pluginHook)) {
+        sourceHook = pluginHook;
+      }
+    }
+
+    // Try NPM locations
+    if (!sourceHook) {
+      const homeDir = process.env.HOME || process.env.USERPROFILE;
+      const npmGlobal = path.join(homeDir, '.claude', 'kata', 'hooks', 'kata-npm-statusline.js');
+      if (fs.existsSync(npmGlobal)) {
+        sourceHook = npmGlobal;
+      }
+    }
+
+    if (!sourceHook) {
+      process.exit(0); // No source hook found
+    }
+
+    // Create .claude/hooks directory
+    const hooksDir = path.join(cwd, '.claude', 'hooks');
+    fs.mkdirSync(hooksDir, { recursive: true });
+
+    // Copy the hook
+    fs.copyFileSync(sourceHook, projectHookPath);
+
+    // Set up settings.json if needed
+    const settingsPath = path.join(cwd, '.claude', 'settings.json');
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+
+    if (!settings.statusLine) {
+      settings.statusLine = {
+        type: 'command',
+        command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/kata-statusline.js"'
+      };
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    }
+
+    console.log('✓ Kata statusline configured');
+  } catch (e) {
+    // Silent fail - don't break session start
+  }
+});

package/hooks/dist/kata-statusline.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Claude Code Statusline - Kata Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage)
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const used = 100 - rem;
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on usage
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      const files = fs.readdirSync(todosDir)
+        .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        try {
+          const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+          const inProgress = todos.find(t => t.status === 'in_progress');
+          if (inProgress) task = inProgress.activeForm || '';
+        } catch (e) {}
+      }
+    }
+
+    // Kata update available?
+    let kataUpdate = '';
+    const currentDir = dir;
+
+    // Detect local vs global installation by checking VERSION file
+    const localVersionFile = path.join(currentDir, '.claude', 'kata', 'VERSION');
+    const currentIsLocalInstall = fs.existsSync(localVersionFile);
+
+    // Read cache from location matching current context
+    const cacheFile = currentIsLocalInstall
+      ? path.join(currentDir, '.claude', 'kata', 'cache', 'update-check.json')
+      : path.join(homeDir, '.claude', 'kata', 'cache', 'update-check.json');
+
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+
+        // Validate cache matches current context (sanity check)
+        const cacheIsRelevant = currentIsLocalInstall
+          ? (cache.isLocalInstall && cache.cwd === currentDir)
+          : !cache.isLocalInstall;
+
+        if (cache.update_available && cacheIsRelevant) {
+          kataUpdate = '\x1b[33m⬆ /kata:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${kataUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${kataUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/kata/VERSION

@@ -0,0 +1 @@
+1.0.3

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@gannonh/kata",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "type": "module",
   "description": "Spec-driven development framework for Claude Code.",
   "scripts": {
+    "test": "node --test --test-reporter spec ./tests/build.test.js",
     "test:smoke": "node --test --test-reporter spec ./tests/smoke.test.js",
-    "test:all": "node --test --test-reporter spec ./tests/build.test.js ./tests/smoke.test.js"
+    "test:all": "node --test --test-reporter spec ./tests/build.test.js ./tests/smoke.test.js",
+    "build": "node scripts/build.js all",
+    "build:plugin": "node scripts/build.js plugin",
+    "build:npm": "node scripts/build.js npm",
+    "build:hooks": "node scripts/build-hooks.cjs",
+    "prepublishOnly": "npm run build:hooks"
   },
   "bin": {
     "kata": "bin/install.js"