@kata-sh/cli 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kata-sh/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Kata CLI coding agent",
   "license": "MIT",
   "private": false,

package/src/resources/AGENTS.md

@@ -9,7 +9,7 @@ Kata CLI is a thin wrapper around pi-coding-agent that provides:
 - **Branded entry point**: `src/loader.ts` sets env vars and launches `src/cli.ts`
 - **Bundled extensions**: `src/resources/extensions/` contains all built-in extensions
 - **Resource syncing**: `src/resource-loader.ts` copies bundled extensions to `~/.kata-cli/agent/` on startup
-- **Config directory**: `~/.kata-cli/` (not `~/.kata/` to avoid collision with other Kata apps)
+- **Config directory**: `~/.kata-cli/` (not `~/.kata-cli/` to avoid collision with other Kata apps)
 - **Package shim**: `pkg/package.json` provides `piConfig` with `name: "kata"` and `configDir: ".kata-cli"`
 
 ## Directory Structure

package/src/resources/extensions/kata/docs/preferences-reference.md

@@ -1,6 +1,6 @@
 # Kata Preferences Reference
 
-Full documentation for `~/.kata/preferences.md` (global) and `.kata/preferences.md` (project).
+Full documentation for `~/.kata-cli/preferences.md` (global) and `.kata/preferences.md` (project).
 
 ---
 

package/src/resources/extensions/kata/gitignore.ts

@@ -132,7 +132,7 @@ auto_supervisor: {}
 
 Project-specific guidance for skill selection and execution preferences.
 
-See \`~/.kata/agent/extensions/kata/docs/preferences-reference.md\` for full field documentation and examples.
+See \`~/.kata-cli/agent/extensions/kata/docs/preferences-reference.md\` for full field documentation and examples.
 
 ## Fields
 

package/src/resources/extensions/kata/preferences.ts

@@ -122,7 +122,7 @@ export interface SkillResolutionReport {
 
 /**
  * Known skill directories, in priority order.
- * User skills (~/.kata/agent/skills/) take precedence over project skills.
+ * User skills (~/.kata-cli/agent/skills/) take precedence over project skills.
  */
 function getSkillSearchDirs(
   cwd: string,

package/src/resources/extensions/kata/prompts/complete-milestone.md

@@ -7,7 +7,7 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 {{inlinedContext}}
 
 Then:
-1. Read the milestone-summary template at `~/.kata/agent/extensions/kata/templates/milestone-summary.md`
+1. Read the milestone-summary template at `~/.kata-cli/agent/extensions/kata/templates/milestone-summary.md`
 2. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
 4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.

package/src/resources/extensions/kata/prompts/complete-slice.md

@@ -8,8 +8,8 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 Then:
 1. Read the templates:
-   - `~/.kata/agent/extensions/kata/templates/slice-summary.md`
-   - `~/.kata/agent/extensions/kata/templates/uat.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/slice-summary.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/uat.md`
 2. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. Confirm the slice's observability/diagnostic surfaces are real and useful where relevant: status inspection works, failure state is externally visible, structured errors/logs are actionable, and hidden failures are not being mistaken for success.

package/src/resources/extensions/kata/prompts/discuss.md

@@ -126,11 +126,11 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file co
 
 Once the user is satisfied, in a single pass:
 1. `mkdir -p .kata/milestones/{{milestoneId}}/slices`
-2. Write or update `.kata/PROJECT.md` — read the template at `~/.kata/agent/extensions/kata/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.kata/REQUIREMENTS.md` — read the template at `~/.kata/agent/extensions/kata/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
-4. Write `{{contextAbsPath}}` — read the template at `~/.kata/agent/extensions/kata/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
-5. Write `{{roadmapAbsPath}}` — read the template at `~/.kata/agent/extensions/kata/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
-6. Seed `.kata/DECISIONS.md` — read the template at `~/.kata/agent/extensions/kata/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
+2. Write or update `.kata/PROJECT.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
+3. Write or update `.kata/REQUIREMENTS.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
+4. Write `{{contextAbsPath}}` — read the template at `~/.kata-cli/agent/extensions/kata/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
+5. Write `{{roadmapAbsPath}}` — read the template at `~/.kata-cli/agent/extensions/kata/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
+6. Seed `.kata/DECISIONS.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
 7. Update `.kata/STATE.md`
 8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
 
@@ -140,8 +140,8 @@ After writing the files and committing, say exactly: "Milestone {{milestoneId}}
 
 Once the user confirms the milestone split, in a single pass:
 1. `mkdir -p .kata/milestones/{{milestoneId}}/slices` for each milestone
-2. Write `.kata/PROJECT.md` — read the template at `~/.kata/agent/extensions/kata/templates/project.md` first.
-3. Write `.kata/REQUIREMENTS.md` — read the template at `~/.kata/agent/extensions/kata/templates/requirements.md` first. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+2. Write `.kata/PROJECT.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/project.md` first.
+3. Write `.kata/REQUIREMENTS.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/requirements.md` first. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
 4. Write a `CONTEXT.md` for **every** milestone — capture the intent, scope, risks, constraints, user-visible outcome, completion class, final integrated acceptance, and relevant requirements for each. Each future milestone's CONTEXT.md should be rich enough that a planning agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like.
 5. Write a `ROADMAP.md` for **only the first milestone** — detail-planning later milestones now is waste because the codebase will change. Include requirement coverage and a milestone definition of done.
 6. Seed `.kata/DECISIONS.md`.

package/src/resources/extensions/kata/prompts/execute-task.md

@@ -50,8 +50,8 @@ Then:
     - Know when to stop. If you've tried 3+ fixes without progress, your mental model is probably wrong. Stop. List what you know for certain. List what you've ruled out. Form fresh hypotheses from there.
     - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
-12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.kata/DECISIONS.md` (read the template at `~/.kata/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
-13. Read the template at `~/.kata/agent/extensions/kata/templates/task-summary.md`
+12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.kata/DECISIONS.md` (read the template at `~/.kata-cli/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
+13. Read the template at `~/.kata-cli/agent/extensions/kata/templates/task-summary.md`
 14. Write `{{taskSummaryAbsPath}}`
 15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
 16. Commit your work: `git add -A && git commit -m 'feat({{sliceId}}/{{taskId}}): <what was built>'`. If `git add` silently fails to stage files (a known git worktree stat-cache bug), use this workaround per file: `git update-index --cacheinfo 100644,$(git hash-object -w <file>),<file>` then commit. If that also fails, move on — the system will auto-commit remaining changes after your session ends.

package/src/resources/extensions/kata/prompts/guided-complete-slice.md

@@ -1 +1 @@
-Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Read the templates at `~/.kata/agent/extensions/kata/templates/slice-summary.md` and `uat.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.kata/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back to main automatically.
+Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Read the templates at `~/.kata-cli/agent/extensions/kata/templates/slice-summary.md` and `uat.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.kata/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back to main automatically.

package/src/resources/extensions/kata/prompts/guided-discuss-milestone.md

@@ -1,3 +1,3 @@
-Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Read the template at `~/.kata/agent/extensions/kata/templates/context.md` first. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Read the template at `~/.kata-cli/agent/extensions/kata/templates/context.md` first. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
 
 **Investigate between question rounds to make your questions smarter.** Before each round of questions, do enough lightweight research that your questions are grounded in reality — not guesses about what exists or what's possible. Check library docs (`resolve_library`/`get_library_docs`) when tech choices are relevant, search the web (`search-the-web` with `freshness`/`domain` filters, then `fetch_page` for full content) to verify the landscape, scout the codebase (`rg`, `find`, `scout`) to understand what already exists. Don't go deep — just enough that your next question reflects what's actually true. The goal is to ask questions the user can't answer by saying "did you check the docs?" or "look at the code."

package/src/resources/extensions/kata/prompts/guided-discuss-slice.md

@@ -45,7 +45,7 @@ If the user wants to keep going, keep asking. Stop when they say wrap up.
 
 Once the user is ready to wrap up:
 
-1. Read the slice context template at `~/.kata/agent/extensions/kata/templates/slice-context.md`
+1. Read the slice context template at `~/.kata-cli/agent/extensions/kata/templates/slice-context.md`
 2. `mkdir -p {{sliceDirAbsPath}}`
 3. Write `{{contextAbsPath}}` — use the template structure, filling in:
    - **Goal** — one sentence: what this slice delivers

package/src/resources/extensions/kata/prompts/guided-execute-task.md

@@ -1 +1 @@
-Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.kata/DECISIONS.md`. Read the template at `~/.kata/agent/extensions/kata/templates/task-summary.md`. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.
+Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.kata/DECISIONS.md`. Read the template at `~/.kata-cli/agent/extensions/kata/templates/task-summary.md`. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.

package/src/resources/extensions/kata/prompts/guided-plan-milestone.md

@@ -1,4 +1,4 @@
-Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Read the template at `~/.kata/agent/extensions/kata/templates/roadmap.md`. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.kata/DECISIONS.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting.
+Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Read the template at `~/.kata-cli/agent/extensions/kata/templates/roadmap.md`. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.kata/DECISIONS.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting.
 
 ## Requirement Rules
 

package/src/resources/extensions/kata/prompts/guided-plan-slice.md

@@ -1 +1 @@
-Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Read the templates at `~/.kata/agent/extensions/kata/templates/plan.md` and `task-plan.md`. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.kata/decisions.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
+Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Read the templates at `~/.kata-cli/agent/extensions/kata/templates/plan.md` and `task-plan.md`. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.kata/decisions.md`. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.

package/src/resources/extensions/kata/prompts/guided-research-slice.md

@@ -1,4 +1,4 @@
-Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Read the template at `~/.kata/agent/extensions/kata/templates/research.md`. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
+Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.kata/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.kata/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Read the template at `~/.kata-cli/agent/extensions/kata/templates/research.md`. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
 
 ## Strategic Questions to Answer
 

package/src/resources/extensions/kata/prompts/plan-milestone.md

@@ -7,13 +7,13 @@ All relevant context has been preloaded below — start working immediately with
 {{inlinedContext}}
 
 Then:
-1. Read the template at `~/.kata/agent/extensions/kata/templates/roadmap.md`
+1. Read the template at `~/.kata-cli/agent/extensions/kata/templates/roadmap.md`
 2. Read `.kata/REQUIREMENTS.md` if it exists. Treat **Active** requirements as the capability contract for planning. If it does not exist, continue in legacy compatibility mode but explicitly note that requirement coverage is operating without a contract.
 3. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required roadmap formatting
 4. Create the roadmap: decompose into demoable vertical slices — as many as the work needs, no more
 5. Order by risk (high-risk first)
 6. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
-7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.kata/DECISIONS.md` (read the template at `~/.kata/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet)
+7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.kata/DECISIONS.md` (read the template at `~/.kata-cli/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet)
 8. Update `.kata/STATE.md`
 
 ## Requirement Mapping Rules

package/src/resources/extensions/kata/prompts/plan-slice.md

@@ -15,8 +15,8 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 Then:
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
 1. Read the templates:
-   - `~/.kata/agent/extensions/kata/templates/plan.md`
-   - `~/.kata/agent/extensions/kata/templates/task-plan.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/plan.md`
+   - `~/.kata-cli/agent/extensions/kata/templates/task-plan.md`
 2. If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting
 3. Define slice-level verification first — the objective stopping condition for this slice:
    - For non-trivial slices: plan actual test files with real assertions. Name the files. The first task creates them (initially failing). Remaining tasks make them pass.

package/src/resources/extensions/kata/prompts/queue.md

@@ -69,7 +69,7 @@ Determine where the new milestones should go in the overall sequence. Consider d
 Once the user is satisfied, in a single pass for **each** new milestone (starting from {{nextId}}):
 
 1. `mkdir -p .kata/milestones/<ID>/slices`
-2. Write `.kata/milestones/<ID>/<ID>-CONTEXT.md` — read the template at `~/.kata/agent/extensions/kata/templates/context.md` first. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution."
+2. Write `.kata/milestones/<ID>/<ID>-CONTEXT.md` — read the template at `~/.kata-cli/agent/extensions/kata/templates/context.md` first. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution."
 
 Then, after all milestone directories and context files are written:
 

package/src/resources/extensions/kata/prompts/research-milestone.md

@@ -11,7 +11,7 @@ Then research the codebase and relevant technologies:
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries
-5. Read the template at `~/.kata/agent/extensions/kata/templates/research.md`
+5. Read the template at `~/.kata-cli/agent/extensions/kata/templates/research.md`
 6. If `.kata/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
 7. Write `{{outputPath}}` with:
    - Summary (2-3 paragraphs, primary recommendation)

package/src/resources/extensions/kata/prompts/research-slice.md

@@ -18,7 +18,7 @@ Then research what this slice needs:
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries
-5. Read the template at `~/.kata/agent/extensions/kata/templates/research.md`
+5. Read the template at `~/.kata-cli/agent/extensions/kata/templates/research.md`
 6. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.

package/src/resources/extensions/kata/prompts/system.md

@@ -12,9 +12,9 @@ Kata ships with bundled skills. Load the relevant skill file with the `read` too
 
 | Trigger                                                                                          | Skill to load                                     |
 | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
-| Frontend UI — web components, pages, landing pages, dashboards, React/HTML/CSS, styling          | `~/.kata/agent/skills/frontend-design/SKILL.md`   |
-| macOS or iOS apps — SwiftUI, Xcode, App Store                                                    | `~/.kata/agent/skills/swiftui/SKILL.md`           |
-| Debugging — complex bugs, failing tests, root-cause investigation after standard approaches fail | `~/.kata/agent/skills/debug-like-expert/SKILL.md` |
+| Frontend UI — web components, pages, landing pages, dashboards, React/HTML/CSS, styling          | `~/.kata-cli/agent/skills/frontend-design/SKILL.md`   |
+| macOS or iOS apps — SwiftUI, Xcode, App Store                                                    | `~/.kata-cli/agent/skills/swiftui/SKILL.md`           |
+| Debugging — complex bugs, failing tests, root-cause investigation after standard approaches fail | `~/.kata-cli/agent/skills/debug-like-expert/SKILL.md` |
 
 ## Hard Rules
 
@@ -84,7 +84,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
 ### Artifact Templates
 
 Templates showing the expected format for each artifact type are in:
-`~/.kata/agent/extensions/kata/templates/`
+`~/.kata-cli/agent/extensions/kata/templates/`
 
 **Always read the relevant template before writing an artifact** to match the expected structure exactly. The parsers that read these files depend on specific formatting:
 

package/src/resources/extensions/kata/templates/preferences.md

@@ -12,4 +12,4 @@ auto_supervisor: {}
 
 # Kata Skill Preferences
 
-See `~/.kata/agent/extensions/kata/docs/preferences-reference.md` for full field documentation and examples.
+See `~/.kata-cli/agent/extensions/kata/docs/preferences-reference.md` for full field documentation and examples.

package/src/resources/extensions/kata/tests/complete-milestone.test.ts

@@ -9,7 +9,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 
-// loadPrompt reads from ~/.kata/agent/extensions/kata/prompts/ (main checkout).
+// loadPrompt reads from ~/.kata-cli/agent/extensions/kata/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
 // relative to this test file's location (the worktree copy).
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/src/resources/extensions/kata/tests/reassess-prompt.test.ts

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// loadPrompt reads from ~/.kata/agent/extensions/kata/prompts/ (main checkout).
+// loadPrompt reads from ~/.kata-cli/agent/extensions/kata/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
 // relative to this test file's location (the worktree copy).
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/src/resources/extensions/slash-commands/create-extension.ts

@@ -273,66 +273,66 @@ function sendPrompt(
     : "";
 
   const docHints: string[] = [
-    "- `~/.kata/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
-    "- `~/.kata/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
-    "- `~/.kata/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
-    "- `~/.kata/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
-    "- `~/.kata/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
+    "- `~/.kata-cli/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
+    "- `~/.kata-cli/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
+    "- `~/.kata-cli/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
+    "- `~/.kata-cli/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
+    "- `~/.kata-cli/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
   ];
 
   if (uiSelected.includes("custom component")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays",
+      "- `~/.kata-cli/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide",
     );
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls",
     );
   } else if (uiSelected.includes("Dialogs")) {
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor",
     );
   } else if (uiSelected.includes("Status")) {
     docHints.push(
-      "- `~/.kata/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header",
+      "- `~/.kata-cli/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header",
     );
   }
 
   if (uiSelected.includes("tool") || result.answers["purpose"]) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult",
+      "- `~/.kata-cli/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult",
     );
   }
 
   if (eventsSelected && !eventsSelected.includes("standalone")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference",
+      "- `~/.kata-cli/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference",
     );
   }
 
   if (eventsSelected.includes("context / prompt")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks",
+      "- `~/.kata-cli/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks",
     );
   }
 
   if (persistenceSelected.includes("session")) {
     docHints.push(
-      "- `~/.kata/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state",
+      "- `~/.kata-cli/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state",
     );
   }
 
@@ -350,11 +350,11 @@ ${docHints.join("\n")}
 
 Write the complete implementation as a single self-contained extension file:
 
-\`~/.kata/agent/extensions/<kebab-case-name>.ts\`
+\`~/.kata-cli/agent/extensions/<kebab-case-name>.ts\`
 
 Then register it in the main extensions index:
 
-\`~/.kata/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
+\`~/.kata-cli/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
 
 ## Rules you must follow exactly
 

package/src/resources/extensions/slash-commands/create-slash-command.ts

@@ -257,8 +257,8 @@ function sendPrompt(
 ${contextSection}
 Write the complete file contents for two files:
 
-1. \`~/.kata/agent/extensions/slash-commands/<name>.ts\` — the command implementation
-2. Update \`~/.kata/agent/extensions/slash-commands/index.ts\` — import and register the new command alongside existing ones
+1. \`~/.kata-cli/agent/extensions/slash-commands/<name>.ts\` — the command implementation
+2. Update \`~/.kata-cli/agent/extensions/slash-commands/index.ts\` — import and register the new command alongside existing ones
 
 Rules you must follow exactly:
 - Command registration: \`pi.registerCommand("name", { description, handler })\`

package/src/resources/extensions/subagent/index.ts

@@ -502,7 +502,7 @@ export default function (pi: ExtensionAPI) {
       const discovery = discoverAgents(ctx.cwd, "both");
       if (discovery.agents.length === 0) {
         ctx.ui.notify(
-          "No agents found. Add .md files to ~/.kata/agent/agents/ or .kata/agents/",
+          "No agents found. Add .md files to ~/.kata-cli/agent/agents/ or .kata/agents/",
           "warning",
         );
         return;
@@ -525,7 +525,7 @@ export default function (pi: ExtensionAPI) {
       "Delegate tasks to specialized subagents with isolated context windows.",
       "Each subagent is a separate pi process with its own tools, model, and system prompt.",
       "Modes: single ({ agent, task }), parallel ({ tasks: [{agent, task},...] }), chain ({ chain: [{agent, task},...] } with {previous} placeholder).",
-      "Agents are defined as .md files in ~/.kata/agent/agents/ (user) or .kata/agents/ (project).",
+      "Agents are defined as .md files in ~/.kata-cli/agent/agents/ (user) or .kata/agents/ (project).",
       "Use the /subagent command to list available agents and their descriptions.",
       "Use chain mode to pipeline: scout finds context, planner designs, worker implements.",
     ].join(" "),