@gannonh/kata 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+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,439 @@
+<div align="center">
+
+# KATA
+
+**A light-weight and powerful 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)
+[![npm downloads](https://img.shields.io/npm/dm/@gannonh/kata?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@gannonh/kata)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/gannonh/kata?style=for-the-badge&logo=github&color=181717)](https://github.com/gannonh/kata)
+
+<br>
+
+```bash
+npx @gannonh/kata
+```
+
+**Works on Mac, Windows, and Linux.**
+
+<br>
+
+![Kata Install](assets/terminal.svg)
+
+<br>
+
+**Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
+
+</div>
+
+---
+
+
+## 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.
+
+---
+
+## Getting Started
+
+```bash
+npx @gannonh/kata (coming soon)
+```
+
+That's it. Verify with `/kata:help` inside your Claude Code interface.
+
+### Staying Updated
+
+Kata evolves fast. Check for updates periodically:
+
+```
+/kata:whats-new
+```
+
+Update with:
+
+```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]
+> This is how Kata is intended to be used — stopping to approve `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: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.
+
+### 1. Initialize Project
+
+```
+/kata:new-project
+```
+
+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
+
+```
+/kata:discuss-phase 1
+```
+
+**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)
+
+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.
+
+**Creates:** `{phase}-CONTEXT.md`
+
+---
+
+### 3. Plan Phase
+
+```
+/kata:plan-phase 1
+```
+
+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 is small enough to execute in a fresh context window. No degradation, no "I'll be more concise now."
+
+**Creates:** `{phase}-RESEARCH.md`, `{phase}-{N}-PLAN.md`
+
+---
+
+### 4. Execute Phase
+
+```
+/kata:execute-phase 1
+```
+
+The system:
+
+1. **Runs plans in waves** — Parallel where possible, sequential when dependent
+2. **Fresh context per plan** — 200k tokens purely 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
+
+```
+/kata:verify-work 1
+```
+
+**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, you don't manually debug — you just run `/kata:execute-phase` again with the fix plans it created.
+
+**Creates:** `{phase}-UAT.md`, fix plans if issues found
+
+---
+
+### 6. Repeat → Complete → Next Milestone
+
+```
+/kata:discuss-phase 2
+/kata:plan-phase 2
+/kata:execute-phase 2
+/kata:verify-work 2
+...
+/kata:complete-milestone
+/kata:new-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, `/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.
+
+---
+
+## Why It Works
+
+### Context Engineering
+
+Claude Code is incredibly powerful *if* you give it the context it needs. Most people don't.
+
+Kata handles it 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. Stay under, get consistent excellence.
+
+### 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. No guessing. 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 — 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
+
+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 surgical, traceable, and meaningful.
+
+### Modular by Design
+
+- Add phases to current milestone
+- Insert urgent work between phases
+- Complete milestones and start fresh
+- Adjust plans without rebuilding everything
+
+You're never locked in. The system adapts.
+
+---
+
+## Commands
+
+### Core Workflow
+
+| Command                      | What it does                                                       |
+| ---------------------------- | ------------------------------------------------------------------ |
+| `/kata:new-project`          | Full initialization: questions → research → requirements → roadmap |
+| `/kata:discuss-phase [N]`    | Capture implementation decisions before planning                   |
+| `/kata:plan-phase [N]`       | Research + plan + verify for a phase                               |
+| `/kata:execute-phase <N>`    | Execute all plans in parallel waves, verify when complete          |
+| `/kata:verify-work [N]`      | Manual user acceptance testing ¹                                   |
+| `/kata:complete-milestone`   | Archive milestone, tag release                                     |
+| `/kata:new-milestone [name]` | Start next version: questions → research → requirements → roadmap  |
+
+### Navigation
+
+| Command          | What it does                      |
+| ---------------- | --------------------------------- |
+| `/kata:progress` | Where am I? What's next?          |
+| `/kata:help`     | Show all commands and usage guide |
+
+### Brownfield
+
+| Command              | What it does                                 |
+| -------------------- | -------------------------------------------- |
+| `/kata:map-codebase` | Analyze existing codebase before new-project |
+
+### Phase Management
+
+| Command                  | What it does                      |
+| ------------------------ | --------------------------------- |
+| `/kata:add-phase`        | Append phase to roadmap           |
+| `/kata:insert-phase [N]` | Insert urgent work between phases |
+| `/kata:remove-phase [N]` | Remove future phase, renumber     |
+
+### Session
+
+| Command             | What it does                           |
+| ------------------- | -------------------------------------- |
+| `/kata:pause-work`  | Create handoff when stopping mid-phase |
+| `/kata:resume-work` | Restore from last session              |
+
+### Utilities
+
+| Command                 | What it does                               |
+| ----------------------- | ------------------------------------------ |
+| `/kata:add-todo [desc]` | Capture idea for later                     |
+| `/kata:check-todos`     | List pending todos                         |
+| `/kata:debug [desc]`    | Systematic debugging with persistent state |
+
+<sup>¹ Contributed by reddit user OracleGreyBeard</sup>
+
+---
+
+## Troubleshooting
+
+**Commands not found after install?**
+- Restart Claude Code to reload slash commands
+- Verify files exist in `~/.claude/commands/gsd/` (global) or `./.claude/commands/gsd/` (local)
+
+**Commands not working as expected?**
+- Run `/kata:help` 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.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Claude Code is powerful. Kata makes it reliable.**
+
+</div>