@gannonh/kata 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 # KATA
 
-**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code.**
+**A meta-prompting, context engineering and spec-driven development system for Claude Code.**
 
 [![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>
@@ -25,10 +25,9 @@ npx @gannonh/kata
 
 ---
 
-
 ## Who This Is For
 
-People who want to describe what they want and have it built correctly — without pretending they're running a 50-person engineering org.
+Developers who describe what they want and have it built correctly.
 
 ---
 
@@ -38,17 +37,17 @@ People who want to describe what they want and have it built correctly — witho
 npx @gannonh/kata
 ```
 
-That's it. Verify with `/kata:help` inside your Claude Code interface.
+Verify with `/kata:help` inside Claude Code.
 
 ### Staying Updated
 
-Kata evolves fast. Check for updates periodically:
+Kata updates frequently. Check for changes:
 
 ```
 /kata:whats-new
 ```
 
-Update with:
+Update:
 
 ```bash
 npx @gannonh/kata@latest
@@ -83,19 +82,19 @@ Installs to `./.claude/` for testing modifications before contributing.
 
 ### Recommended: Skip Permissions Mode
 
-Kata is designed for frictionless automation. Run Claude Code with:
+Kata automates many operations. Run Claude Code with:
 
 ```bash
 claude --dangerously-skip-permissions
 ```
 
 > [!TIP]
-> This is how Kata is intended to be used — stopping to approve `date` and `git commit` 50 times defeats the purpose.
+> Kata works best this way. Approving `date` and `git commit` 50 times slows down the workflow.
 
 <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`:
+Add this to your project's `.claude/settings.json`:
 
 ```json
 {
@@ -129,7 +128,7 @@ If you prefer not to use that flag, add this to your project's `.claude/settings
 
 ## How It Works
 
-> **Already have code?** Run `/kata:map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/kata:new-project` knows your codebase — questions focus on what you're adding, and planning automatically loads your patterns.
+> **Existing codebase?** Run `/kata:map-codebase` first. It spawns parallel agents to analyze your stack, architecture, conventions, and concerns. Then `/kata:new-project` references your codebase. Questions focus on what you're adding, and planning loads your patterns automatically.
 
 ### 1. Initialize Project
 
@@ -156,9 +155,9 @@ You approve the roadmap. Now you're ready to build.
 /kata:discuss-phase 1
 ```
 
-**This is where you shape the implementation.**
+**Here 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.
+Your roadmap has a sentence or two per phase. That lacks 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:
 
@@ -167,12 +166,12 @@ The system analyzes the phase and identifies gray areas based on what's being bu
 - **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:
+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)
 
-The deeper you go here, the more the system builds what you actually want. Skip it and you get reasonable defaults. Use it and you get *your* vision.
+Going deeper here makes the system build what you actually want. Skip it and you get reasonable defaults. Use it and you get your vision.
 
 **Creates:** `{phase}-CONTEXT.md`
 
@@ -221,9 +220,9 @@ Walk away, come back to completed work with clean git history.
 /kata:verify-work 1
 ```
 
-**This is where you confirm it actually works.**
+**Here 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.
+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:
 
@@ -232,7 +231,7 @@ The system:
 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, you don't manually debug — you just run `/kata:execute-phase` again with the fix plans it created.
+If everything passes, you move on. If something's broken, you don't manually debug. Run `/kata:execute-phase` again with the fix plans it created.
 
 **Creates:** `{phase}-UAT.md`, fix plans if issues found
 
@@ -252,11 +251,11 @@ If everything passes, you move on. If something's broken, you don't manually deb
 
 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.
+Each phase gets your input (discuss), research (plan), clean execution (execute), and human verification (verify). Context stays fresh. Quality stays high.
 
 When all phases are done, `/kata:complete-milestone` archives the milestone and tags the release.
 
-Then `/kata:new-milestone` starts the next version — same flow as `new-project` but 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.
+Then `/kata:new-milestone` starts the next version. Same flow as `new-project` but 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.
 
 ---
 
@@ -264,11 +263,11 @@ Then `/kata:new-milestone` starts the next version — same flow as `new-project
 
 ### Context Engineering
 
-Claude Code is incredibly powerful *if* you give it the context it needs. Most people don't.
+Claude Code performs well with the right context. Most users don't provide it.
 
 Kata handles it for you:
 
-| File              | What it does                                                  |
+| File              | Function                                                      |
 | ----------------- | ------------------------------------------------------------- |
 | `PROJECT.md`      | Project vision, always loaded                                 |
 | `research/`       | Ecosystem knowledge (stack, features, architecture, pitfalls) |
@@ -279,7 +278,7 @@ Kata handles it for you:
 | `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. Stay under, get consistent excellence.
+Size limits based on where Claude's quality degrades. Stay under, get consistent results.
 
 ### XML Prompt Formatting
 
@@ -312,9 +311,9 @@ Every stage uses the same pattern: a thin orchestrator spawns specialized agents
 | 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 orchestrator spawns agents, waits, and integrates results.
 
-**The result:** You can run an entire phase — deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals — and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
+**Result:** You can run an entire phase (deep research, multiple plans created and verified, thousands of lines of code written across parallel executors, automated verification against goals) and your main context window stays at 30-40%. The work happens in fresh subagent contexts. Your session stays fast and responsive.
 
 ### Atomic Git Commits
 
@@ -339,7 +338,7 @@ Every commit is surgical, traceable, and meaningful.
 - Complete milestones and start fresh
 - Adjust plans without rebuilding everything
 
-You're never locked in. The system adapts.
+The system adapts.
 
 ---
 
@@ -347,7 +346,7 @@ You're never locked in. The system adapts.
 
 ### Core Workflow
 
-| Command                      | What it does                                                       |
+| Command                      | Function                                                           |
 | ---------------------------- | ------------------------------------------------------------------ |
 | `/kata:new-project`          | Full initialization: questions → research → requirements → roadmap |
 | `/kata:discuss-phase [N]`    | Capture implementation decisions before planning                   |
@@ -359,20 +358,20 @@ You're never locked in. The system adapts.
 
 ### Navigation
 
-| Command          | What it does                      |
+| Command          | Function                          |
 | ---------------- | --------------------------------- |
 | `/kata:progress` | Where am I? What's next?          |
 | `/kata:help`     | Show all commands and usage guide |
 
 ### Brownfield
 
-| Command              | What it does                                 |
+| Command              | Function                                     |
 | -------------------- | -------------------------------------------- |
 | `/kata:map-codebase` | Analyze existing codebase before new-project |
 
 ### Phase Management
 
-| Command                  | What it does                      |
+| Command                  | Function                          |
 | ------------------------ | --------------------------------- |
 | `/kata:add-phase`        | Append phase to roadmap           |
 | `/kata:insert-phase [N]` | Insert urgent work between phases |
@@ -380,14 +379,14 @@ You're never locked in. The system adapts.
 
 ### Session
 
-| Command             | What it does                           |
+| Command             | Function                               |
 | ------------------- | -------------------------------------- |
 | `/kata:pause-work`  | Create handoff when stopping mid-phase |
 | `/kata:resume-work` | Restore from last session              |
 
 ### Utilities
 
-| Command                 | What it does                               |
+| Command                 | Function                                   |
 | ----------------------- | ------------------------------------------ |
 | `/kata:add-todo [desc]` | Capture idea for later                     |
 | `/kata:check-todos`     | List pending todos                         |
@@ -430,6 +429,6 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 <div align="center">
 
-**Claude Code is powerful. Kata makes it reliable.**
+**Claude Code performs well. Kata makes it reliable.**
 
 </div>

package/commands/kata/update.md

@@ -11,9 +11,41 @@ Provides a better update experience than raw `npx @gannonh/kata` by showing vers
 
 <process>
 
+<step name="detect_installation">
+Detect whether Kata is installed locally (in current project) or globally:
+
+```bash
+if [ -d "./.claude/commands/kata" ]; then
+  echo "local"
+else
+  echo "global"
+fi
+```
+
+**Set paths based on installation type:**
+
+| Installation | VERSION Path | Install Flag | Cache Path |
+|-------------|--------------|--------------|------------|
+| Local | `./.claude/kata/VERSION` | (no flag) | `./.claude/kata/cache/update-check.json` |
+| Global | `~/.claude/kata/VERSION` | `--global` | `~/.claude/kata/cache/update-check.json` |
+
+Store the installation type for use in subsequent steps.
+
+**Display detection result:**
+```
+Detected installation: [local/global]
+```
+</step>
+
 <step name="get_installed_version">
-Read installed version:
+Read installed version from the detected installation path:
 
+**For local installation:**
+```bash
+cat ./.claude/kata/VERSION 2>/dev/null
+```
+
+**For global installation:**
 ```bash
 cat ~/.claude/kata/VERSION 2>/dev/null
 ```
@@ -23,6 +55,7 @@ cat ~/.claude/kata/VERSION 2>/dev/null
 ## Kata Update
 
 **Installed version:** Unknown
+**Installation type:** [local/global]
 
 Your installation doesn't include version tracking.
 
@@ -105,13 +138,20 @@ STOP here if ahead.
 
 ────────────────────────────────────────────────────────────
 
-⚠️  **Note:** The installer performs a clean install of Kata folders:
+⚠️  **Note:** The installer performs a clean install of Kata folders.
+
+**For local installation (in current project):**
+- `./.claude/commands/kata/` will be wiped and replaced
+- `./.claude/kata/` will be wiped and replaced
+- `./.claude/agents/kata-*` files will be replaced
+
+**For global installation:**
 - `~/.claude/commands/kata/` will be wiped and replaced
 - `~/.claude/kata/` will be wiped and replaced
 - `~/.claude/agents/kata-*` files will be replaced
 
 Your custom files in other locations are preserved:
-- Custom commands in `~/.claude/commands/your-stuff/` ✓
+- Custom commands not in the kata folder ✓
 - Custom agents not prefixed with `kata-` ✓
 - Custom hooks ✓
 - Your CLAUDE.md files ✓
@@ -129,8 +169,14 @@ Use AskUserQuestion:
 </step>
 
 <step name="run_update">
-Run the update:
+Run the update using the appropriate flag based on installation type:
 
+**For local installation:**
+```bash
+npx @gannonh/kata
+```
+
+**For global installation:**
 ```bash
 npx @gannonh/kata --global
 ```
@@ -139,8 +185,14 @@ Capture output. If install fails, show error and STOP.
 
 Clear the update cache so statusline indicator disappears:
 
+**For local installation:**
+```bash
+rm -f ./.claude/kata/cache/update-check.json
+```
+
+**For global installation:**
 ```bash
-rm -f ~/.claude/cache/kata-update-check.json
+rm -f ~/.claude/kata/cache/update-check.json
 ```
 </step>
 
@@ -161,12 +213,14 @@ Format completion message (changelog was already shown in confirmation step):
 </process>
 
 <success_criteria>
+- [ ] Installation type detected (local vs global)
+- [ ] Correct paths used based on installation type
 - [ ] Installed version read correctly
 - [ ] Latest version checked via npm
 - [ ] Update skipped if already current
 - [ ] Changelog fetched and displayed BEFORE update
-- [ ] Clean install warning shown
+- [ ] Clean install warning shown with appropriate paths
 - [ ] User confirmation obtained
-- [ ] Update executed successfully
+- [ ] Update executed with correct flag (--global for global only)
 - [ ] Restart reminder shown
 </success_criteria>

package/hooks/kata-check-update.js

@@ -8,9 +8,23 @@ const os = require('os');
 const { execSync, spawn } = require('child_process');
 
 const homeDir = os.homedir();
-const cacheDir = path.join(homeDir, '.claude', 'cache');
-const cacheFile = path.join(cacheDir, 'kata-update-check.json');
-const versionFile = path.join(homeDir, '.claude', 'kata', 'VERSION');
+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)) {
@@ -24,6 +38,8 @@ const child = spawn(process.execPath, ['-e', `
 
   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 {
@@ -39,7 +55,9 @@ const child = spawn(process.execPath, ['-e', `
     update_available: latest && installed !== latest,
     installed,
     latest: latest || 'unknown',
-    checked: Math.floor(Date.now() / 1000)
+    checked: Math.floor(Date.now() / 1000),
+    cwd: checkedCwd,
+    isLocalInstall: isLocalInstall
   };
 
   fs.writeFileSync(cacheFile, JSON.stringify(result));

package/hooks/statusline.js

@@ -61,11 +61,27 @@ process.stdin.on('end', () => {
 
     // Kata update available?
     let kataUpdate = '';
-    const cacheFile = path.join(homeDir, '.claude', 'cache', 'kata-update-check.json');
+    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'));
-        if (cache.update_available) {
+
+        // 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) {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gannonh/kata",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Development framework for Claude Code.",
   "bin": {
     "kata": "bin/install.js"
@@ -29,4 +29,4 @@
   "engines": {
     "node": ">=16.7.0"
   }
-}
+}