@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/kata/prompt-loader.ts

@@ -0,0 +1,50 @@
+/**
+ * Kata Prompt Loader
+ *
+ * Reads .md prompt templates from the prompts/ directory and substitutes
+ * {{variable}} placeholders with provided values.
+ *
+ * Templates live at prompts/ relative to this module's directory.
+ * They use {{variableName}} syntax for substitution.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const promptsDir = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+
+/**
+ * Load a prompt template and substitute variables.
+ *
+ * @param name - Template filename without .md extension (e.g. "execute-task")
+ * @param vars - Key-value pairs to substitute for {{key}} placeholders
+ */
+export function loadPrompt(name: string, vars: Record<string, string> = {}): string {
+  const path = join(promptsDir, `${name}.md`);
+  let content = readFileSync(path, "utf-8");
+
+  // Check BEFORE substitution: find all {{varName}} placeholders the template
+  // declares and verify every one has a value in vars. Checking after substitution
+  // would also flag {{...}} patterns injected by inlined content (e.g. template
+  // files embedded in {{inlinedContext}}), producing false positives.
+  const declared = content.match(/\{\{[a-zA-Z][a-zA-Z0-9_]*\}\}/g);
+  if (declared) {
+    const missing = [...new Set(declared)]
+      .map(m => m.slice(2, -2))
+      .filter(key => !(key in vars));
+    if (missing.length > 0) {
+      throw new Error(
+        `loadPrompt("${name}"): template declares {{${missing.join("}}, {{")}}}} but no value was provided. ` +
+        `This usually means the extension code in memory is older than the template on disk. ` +
+        `Restart pi to reload the extension.`
+      );
+    }
+  }
+
+  for (const [key, value] of Object.entries(vars)) {
+    content = content.replaceAll(`{{${key}}}`, value);
+  }
+
+  return content.trim();
+}

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

@@ -0,0 +1,25 @@
+You are executing Kata auto-mode.
+
+## UNIT: Complete Milestone {{milestoneId}} ("{{milestoneTitle}}")
+
+All relevant context has been preloaded below — the roadmap, all slice summaries, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+Then:
+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.
+5. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
+6. Write `{{milestoneSummaryAbsPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
+7. Update `.kata/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
+8. Update `.kata/PROJECT.md` to reflect milestone completion and current project state.
+9. Commit all changes: `git add -A && git commit -m 'feat(kata): complete {{milestoneId}}'`
+10. Update `.kata/STATE.md`
+
+**Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
+
+**You MUST write `{{milestoneSummaryAbsPath}}` AND update PROJECT.md before finishing.**
+
+When done, say: "Milestone {{milestoneId}} complete."

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

@@ -0,0 +1,27 @@
+You are executing Kata auto-mode.
+
+## UNIT: Complete Slice {{sliceId}} ("{{sliceTitle}}") — Milestone {{milestoneId}}
+
+All relevant context has been preloaded below — the slice plan, all task summaries, and the milestone roadmap are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+Then:
+1. Read the templates:
+   - `~/.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.
+5. If `.kata/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change. Surface any new candidate requirements discovered during execution instead of silently dropping them.
+6. Write `{{sliceSummaryAbsPath}}` (compress all task summaries). Fill the requirement-related sections explicitly.
+7. Write `{{sliceUatAbsPath}}`. Fill the new `UAT Type`, `Requirements Proved By This UAT`, and `Not Proven By This UAT` sections explicitly.
+8. Review task summaries for `key_decisions`. Ensure any significant architectural, pattern, or observability decisions are in `.kata/DECISIONS.md`. If any are missing, append them now.
+9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
+10. Commit all remaining slice changes: `git add -A && git commit -m 'feat(kata): complete {{sliceId}}'`. Do not squash-merge manually; the extension will merge the slice branch back to main after this unit succeeds.
+11. Update `.kata/PROJECT.md` if it exists — refresh current state if needed.
+12. Update `.kata/STATE.md`
+
+**You MUST mark {{sliceId}} as `[x]` in `{{roadmapPath}}` AND write `{{sliceSummaryAbsPath}}` before finishing.**
+
+When done, say: "Slice {{sliceId}} complete."

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

@@ -0,0 +1,151 @@
+{{preamble}}
+
+Say exactly: "What's the vision?" — nothing else. Wait for the user's answer.
+
+## Discussion Phase
+
+After they describe it, your job is to understand the project deeply enough to define the project's capability contract before planning slices.
+
+## Vision Mapping
+
+Before diving into detailed Q&A, read the user's description and classify its scale:
+
+- **Task** — a focused piece of work (single milestone, few slices)
+- **Project** — a coherent product with multiple major capabilities (multi-milestone likely)
+- **Product/Platform** — a large vision with distinct phases, audiences, or systems (definitely multi-milestone)
+
+**For Project or Product/Platform scale:** Before drilling into details, map the full landscape:
+1. Propose a milestone sequence — names, one-line intents, rough dependencies
+2. Present this to the user for confirmation or adjustment
+3. Only then begin the deep Q&A — and scope the Q&A to the full vision, not just M001
+
+**For Task scale:** Proceed directly to the discussion flow below (single milestone).
+
+**Anti-reduction rule:** If the user describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or try to reduce scope unless the user explicitly asks for an MVP or minimal version. When something is complex or risky, phase it into a later milestone — do not cut it. The user's ambition is the target, and your job is to sequence it intelligently, not shrink it.
+
+---
+
+**If the user provides a file path or pastes a large document** (spec, design doc, product plan, chat export), read it fully before asking questions. Use it as the starting point — don't ask them to re-explain what's already in the document. Your questions should fill gaps and resolve ambiguities the document doesn't cover.
+
+**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 the user mentions tech you need current facts about — capabilities, constraints, API shapes, version-specific behavior
+- Do web searches (`search-the-web`) to verify the landscape — what solutions exist, what's changed recently, what's the current best practice. Use `freshness` for recency-sensitive queries, `domain` to target specific sites. Use `fetch_page` to read the full content of promising URLs when snippets aren't enough.
+- Scout the codebase (`ls`, `find`, `rg`, or `scout` for broad unfamiliar areas) to understand what already exists, what patterns are established, what constraints current code imposes
+
+Don't go deep — just enough that your next question reflects what's actually true rather than what you assume.
+
+**Use this to actively surface:**
+- The biggest technical unknowns — what could fail, what hasn't been proven, what might invalidate the plan
+- Integration surfaces — external systems, APIs, libraries, or internal modules this work touches
+- What needs to be proven before committing — the things that, if they don't work, mean the plan is wrong
+- Product reality requirements: primary user loop, launchability expectations, continuity expectations, and failure visibility expectations
+- Items that are complex, risky, or lower priority — phase these into later milestones rather than deferring or cutting them. Only truly unwanted capabilities become anti-features.
+
+**Then use ask_user_questions** to dig into gray areas — architecture choices, scope boundaries, tech preferences, what's in vs out. 1-3 questions per round.
+
+If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during discuss/planning work, but do not let it override the required discuss flow or artifact requirements.
+
+**Self-regulate depth by scale:**
+- **Task scale:** After about 5-10 questions total (2-3 rounds), or when you feel you have a solid understanding, offer to proceed.
+- **Project/Product scale:** After about 15-25 questions total (5-8 rounds), or when you feel you have a solid understanding, offer to proceed.
+
+Include a question like:
+"I think I have a good picture. Ready to confirm requirements and milestone plan, or are there more things to discuss?"
+with options: "Ready to confirm requirements and milestone plan (Recommended)", "I have more to discuss"
+
+If the user wants to keep going, keep asking. If they're ready, proceed.
+
+## Focused Research
+
+For a new project or any project that does not yet have `.kata/REQUIREMENTS.md`, do a focused research pass before roadmap creation.
+
+Research is advisory, not auto-binding. Use the discussion output to identify:
+- table stakes the product space usually expects
+- domain-standard behaviors the user may or may not want
+- likely omissions that would make the product feel incomplete
+- plausible anti-features or scope traps
+- differentiators worth preserving
+
+If the research suggests requirements the user did not explicitly ask for, present them as candidate requirements to confirm, defer, or reject. Do not silently turn research into scope.
+
+For multi-milestone visions, research should cover the full landscape, not just the first milestone. Research findings may affect milestone sequencing, not just slice ordering within M001.
+
+## Capability Contract
+
+Before writing a roadmap, produce or update `.kata/REQUIREMENTS.md`.
+
+Use it as the project's explicit capability contract.
+
+Requirements must be organized into:
+- Active
+- Validated
+- Deferred
+- Out of Scope
+- Traceability
+
+Each requirement should include:
+- stable ID (`R###`)
+- title
+- class
+- status
+- description
+- why it matters
+- source (`user`, `inferred`, `research`, or `execution`)
+- primary owning slice
+- supporting slices
+- validation status
+- notes
+
+Rules:
+- Keep requirements capability-oriented, not a giant feature inventory
+- Every Active requirement must either be mapped to a roadmap owner, explicitly deferred, blocked with reason, or moved out of scope
+- Product-facing work should capture launchability, primary user loop, continuity, and failure visibility when relevant
+- Later milestones may have provisional ownership, but the first planned milestone should map requirements to concrete slices wherever possible
+
+For multi-milestone projects, requirements should span the full vision. Requirements owned by later milestones get provisional ownership. The full requirement set captures the user's complete vision — milestones are the sequencing strategy, not the scope boundary.
+
+If the project is new or has no `REQUIREMENTS.md`, confirm candidate requirements with the user before writing the roadmap. Keep the confirmation lightweight: confirm, defer, reject, or add.
+
+## Scope Assessment
+
+Confirm the scale assessment from Vision Mapping still holds after discussion. If the scope grew or shrank significantly during Q&A, adjust the milestone count accordingly.
+
+If Vision Mapping classified the work as Task but discussion revealed Project-scale complexity, upgrade to multi-milestone and propose the split. If Vision Mapping classified it as Project but the scope narrowed to a single coherent body of work (roughly 2-12 slices), downgrade to single-milestone.
+
+## Output Phase
+
+### Naming Convention
+
+Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file content, not in names.
+- Milestone dir: `.kata/milestones/{{milestoneId}}/`
+- Milestone files: `{{milestoneId}}-CONTEXT.md`, `{{milestoneId}}-ROADMAP.md`
+- Slice dirs: `S01/`, `S02/`, etc.
+
+### Single Milestone
+
+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-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`
+
+After writing the files and committing, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+
+### Multi-Milestone
+
+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-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`.
+7. Update `.kata/STATE.md`
+8. Commit: `docs: project plan — N milestones` (replace N with the actual milestone count)
+
+After writing the files and committing, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.

package/src/resources/extensions/kata/prompts/doctor-heal.md

@@ -0,0 +1,29 @@
+You are executing Kata doctor heal mode.
+
+The doctor has already scanned the repo and optionally applied deterministic fixes. You are now responsible for resolving the remaining issues using the smallest safe set of changes.
+
+Rules:
+1. Prioritize the active milestone or the explicitly requested scope. Do not fan out across unrelated historical milestones unless the report explicitly scopes you there.
+2. Read before edit.
+3. Prefer fixing authoritative artifacts over masking warnings.
+4. For missing summaries or UAT files, generate the real artifact from existing slice/task context when possible — do not leave placeholders if you can reconstruct the real content.
+5. After each repair cluster, verify the relevant invariant directly from disk.
+6. When done, rerun `/kata doctor {{doctorCommandSuffix}}` mentally by ensuring the remaining issue set for this scope is reduced or cleared.
+
+## Doctor Summary
+
+{{doctorSummary}}
+
+## Structured Issues
+
+{{structuredIssues}}
+
+## Requested Scope
+
+{{scopeLabel}}
+
+Then:
+- Repair the unresolved issues in scope
+- Keep changes minimal and targeted
+- If unresolved issues remain outside scope, leave them untouched and mention them briefly
+- End with: "Kata doctor heal complete."

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

@@ -0,0 +1,64 @@
+You are executing Kata auto-mode.
+
+## UNIT: Execute Task {{taskId}} ("{{taskTitle}}") — Slice {{sliceId}} ("{{sliceTitle}}"), Milestone {{milestoneId}}
+
+Start with the inlined context below. Treat the inlined task plan as the authoritative local execution contract for this unit. Use the referenced source artifacts to verify details, resolve ambiguity, and run the required checks — do not waste time reconstructing context that is already provided here.
+
+{{resumeSection}}
+
+{{carryForwardSection}}
+
+{{taskPlanInline}}
+
+{{slicePlanExcerpt}}
+
+## Backing Source Artifacts
+- Slice plan: `{{planPath}}`
+- Task plan source: `{{taskPlanPath}}`
+- Prior task summaries in this slice:
+{{priorTaskLines}}
+
+Then:
+1. 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
+2. Execute the steps in the inlined task plan
+3. Build the real thing. If the task plan says "create login endpoint", build an endpoint that actually authenticates against a real store, not one that returns a hardcoded success response. If the task plan says "create dashboard page", build a page that renders real data from the API, not a component with hardcoded props. Stubs and mocks are for tests, not for the shipped feature.
+4. Write or update tests as part of execution — tests are verification, not an afterthought. If the slice plan defines test files in its Verification section and this is the first task, create them (they should initially fail).
+5. When implementing non-trivial runtime behavior, add or preserve agent-usable observability:
+   - Prefer structured logs/events, stable error codes/types, and explicit status surfaces over ad hoc console text
+   - Ensure failures are externally inspectable rather than swallowed or hidden
+   - Persist high-value failure state when it materially improves retries, recovery, or later debugging
+   - Never log secrets, tokens, or sensitive raw payloads unnecessarily
+6. Verify must-haves are met by running concrete checks (tests, commands, observable behaviors)
+7. Run the slice-level verification checks defined in the slice plan's Verification section. Track which pass. On the final task of the slice, all must pass before marking done. On intermediate tasks, partial passes are expected — note which ones pass in the summary.
+8. If the task touches UI, browser flows, DOM behavior, or user-visible web state:
+   - exercise the real flow in the browser
+   - prefer `browser_batch` when the next few actions are obvious and sequential
+   - prefer `browser_assert` for explicit pass/fail verification of the intended outcome
+   - use `browser_diff` when an action's effect is ambiguous
+   - use console/network/dialog diagnostics when validating async, stateful, or failure-prone UI
+   - record verification in terms of explicit checks passed/failed, not only prose interpretation
+9. If observability or diagnostics were part of this task's scope, verify them directly — e.g. structured errors, status inspection, health endpoints, persisted failure state, browser/network diagnostics, or equivalent.
+10. **If execution is running long or verification fails:**
+
+    **Context budget:** If you've used most of your context and haven't finished all steps, stop implementing and prioritize writing the task summary with clear notes on what's done and what remains. A partial summary that enables clean resumption is more valuable than one more half-finished step with no documentation. Never sacrifice summary quality for one more implementation step.
+
+    **Debugging discipline:** If a verification check fails or implementation hits unexpected behavior:
+    - Form a hypothesis first. State what you think is wrong and why, then test that specific theory. Don't shotgun-fix.
+    - Change one variable at a time. Make one change, test, observe. Multiple simultaneous changes mean you can't attribute what worked.
+    - Read completely. When investigating, read entire functions and their imports, not just the line that looks relevant.
+    - Distinguish "I know" from "I assume." Observable facts (the error says X) are strong evidence. Assumptions (this library should work this way) need verification.
+    - 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-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.
+17. Update `.kata/STATE.md`
+
+You are on the slice branch. All work stays here.
+
+**You MUST mark {{taskId}} as `[x]` in `{{planPath}}` AND write `{{taskSummaryAbsPath}}` before finishing.**
+
+When done, say: "Task {{taskId}} complete."

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

@@ -0,0 +1 @@
+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

@@ -0,0 +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-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

@@ -0,0 +1,59 @@
+You are interviewing the user to surface behavioural, UX, and usage grey areas for slice **{{sliceId}}: {{sliceTitle}}** of milestone **{{milestoneId}}**.
+
+Your goal is **not** to settle tech stack, naming conventions, or architecture — that happens during research and planning. Your goal is to produce a context file that captures the human decisions: what this slice should feel like, how it should behave, what edge cases matter, where scope begins and ends, and what the user cares about that won't be obvious from the roadmap entry alone.
+
+{{inlinedContext}}
+
+---
+
+## Interview Protocol
+
+### Before your first question round
+
+Do a lightweight targeted investigation so your questions are grounded in reality:
+- Scout the codebase (`rg`, `find`, or `scout` for broad unfamiliar areas) to understand what already exists that this slice touches or builds on
+- Check the roadmap context above to understand what surrounds this slice — what comes before, what depends on it
+- Identify the 3–5 biggest behavioural unknowns: things where the user's answer will materially change what gets built
+
+Do **not** go deep — just enough that your questions reflect what's actually true rather than what you assume.
+
+### Question rounds
+
+Ask **1–3 questions per round** using `ask_user_questions`. Keep each question focused on one of:
+- **UX and user-facing behaviour** — what does the user see, click, trigger, or experience?
+- **Edge cases and failure states** — what happens when things go wrong or are in unusual states?
+- **Scope boundaries** — what is explicitly in vs out for this slice? What deferred to later?
+- **Feel and experience** — tone, responsiveness, feedback, transitions, what "done" feels like to the user
+
+After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
+
+### Check-in after each round
+
+After each round of answers, use `ask_user_questions` to ask:
+
+> "I think I have a solid picture of this slice. Ready to wrap up and write the context file, or is there more to cover?"
+
+Options:
+- "Wrap up — write the context file" *(recommended after ~2–3 rounds)*
+- "Keep going — more to discuss"
+
+If the user wants to keep going, keep asking. Stop when they say wrap up.
+
+---
+
+## Output
+
+Once the user is ready to wrap up:
+
+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
+   - **Why this Slice** — why now, what it unblocks
+   - **Scope / In Scope** — what was confirmed in scope during the interview
+   - **Scope / Out of Scope** — what was explicitly deferred or excluded
+   - **Constraints** — anything the user flagged as a hard constraint
+   - **Integration Points** — what this slice consumes and produces
+   - **Open Questions** — anything still unresolved, with current thinking
+4. Commit: `git -C {{projectRoot}} add {{contextAbsPath}} && git -C {{projectRoot}} commit -m "docs({{milestoneId}}/{{sliceId}}): slice context from discuss"`
+5. Say exactly: `"{{sliceId}} context written."` — nothing else.

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

@@ -0,0 +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-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

@@ -0,0 +1,23 @@
+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
+
+- Every relevant Active requirement must be mapped to a slice, deferred, blocked with reason, or moved out of scope.
+- Each requirement gets one primary owner and may have supporting slices.
+- Surface orphaned Active requirements instead of silently ignoring them.
+- Product-facing milestones should cover launchability, primary user loop, continuity, and failure visibility when relevant.
+
+## Planning Doctrine
+
+- **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
+- **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
+- **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
+- **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.
+- **Completion must imply capability.** If every slice in this roadmap were completed exactly as written, the milestone's promised outcome should actually work at the proof level claimed. Do not write slices that can all be checked off while the user-visible capability still does not exist.
+- **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
+- **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
+- **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.

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

@@ -0,0 +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-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

@@ -0,0 +1,11 @@
+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
+
+Research should drive planning decisions, not just collect facts. Explicitly address:
+
+- **What should be proven first?** What's the riskiest assumption — the thing that, if wrong, invalidates downstream work?
+- **What existing patterns should be reused?** What modules, conventions, or infrastructure already exist that the plan should build on rather than reinvent?
+- **What boundary contracts matter?** What interfaces, data shapes, event formats, or invariants will slices need to agree on?
+- **What constraints does the existing codebase impose?** What can't be changed, what's expensive to change, what patterns must be respected?
+- **Are there known failure modes that should shape slice ordering?** Pitfalls that mean certain work should come before or after other work?

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

@@ -0,0 +1 @@
+Resume interrupted work. Find the continue file (`{{sliceId}}-CONTINUE.md` or `continue.md`) in slice {{sliceId}} of milestone {{milestoneId}}, then pick up from where you left off. Delete the continue file after reading it. 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.

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

@@ -0,0 +1,47 @@
+You are executing Kata auto-mode.
+
+## UNIT: Plan Milestone {{milestoneId}} ("{{milestoneTitle}}")
+
+All relevant context has been preloaded below — start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+Then:
+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-cli/agent/extensions/kata/templates/decisions.md` if the file doesn't exist yet)
+8. Update `.kata/STATE.md`
+
+## Requirement Mapping Rules
+
+- Every Active requirement relevant to this milestone must be in one of these states by the end of planning: mapped to a slice, explicitly deferred, blocked with reason, or moved out of scope.
+- Each requirement should have one accountable primary owner and may have supporting slices.
+- Product-facing milestones should cover launchability, primary user loop, continuity, and failure visibility when relevant.
+- A slice may support multiple requirements, but should not exist with no requirement justification unless it is clearly enabling work for a mapped requirement.
+- Include a compact coverage summary in the roadmap so omissions are mechanically visible.
+- If `.kata/REQUIREMENTS.md` exists and an Active requirement has no credible path, surface that clearly. Do not silently ignore orphaned Active requirements.
+
+## Planning Doctrine
+
+Apply these when decomposing and ordering slices:
+
+- **Risk-first means proof-first.** The earliest slices should prove the hardest thing works by shipping the real feature through the uncertain path. If auth is the risk, the first slice ships a real login page with real session handling that a user can actually use — not a CLI command that returns "authenticated: true". Proof is the shipped feature working. There is no separate "proof" artifact. Do not plan spikes, proof-of-concept slices, or validation-only slices — the proof is the real feature, built through the risky path.
+- **Every slice is vertical, demoable, and shippable.** Every slice ships real, user-facing functionality. "Demoable" means you could show a stakeholder and they'd see real product progress — not a developer showing a terminal command. If the only way to demonstrate the slice is through a test runner or a curl command, the slice is missing its UI/UX surface. Add it. A slice that only proves something but doesn't ship real working code is not a slice — restructure it.
+- **Brownfield bias.** When planning against an existing codebase, ground slices in existing modules, conventions, and seams. Prefer extending real patterns over inventing new ones.
+- **Each slice should establish something downstream slices can depend on.** Think about what stable surface this slice creates for later work — an API, a data shape, a proven integration path.
+- **Avoid foundation-only slices.** If a slice doesn't produce something demoable end-to-end, it's probably a layer, not a vertical slice. Restructure it.
+- **Verification-first.** When planning slices, know what "done" looks like before detailing implementation. Each slice's demo line should describe concrete, verifiable evidence — not vague "it works" claims.
+- **Plan for integrated reality, not just local proof.** Distinguish contract proof from live integration proof. If the milestone involves multiple runtime boundaries, one slice must explicitly prove the assembled system through the real entrypoint or runtime path.
+- **Truthful demo lines only.** If a slice is proven by fixtures or tests only, say so. Do not phrase harness-level proof as if the user can already perform the live end-to-end behavior unless that has actually been exercised.
+- **Completion must imply capability.** If every slice in this roadmap were completed exactly as written, the milestone's promised outcome should actually work at the proof level claimed. Do not write slices that can all be checked off while the user-visible capability still does not exist.
+- **Don't invent risks.** If the project is straightforward, skip the proof strategy and just ship value in smart order. Not everything has major unknowns.
+- **Ship features, not proofs.** A completed slice should leave the product in a state where the new capability is actually usable through its real interface. A login flow slice ends with a working login page, not a middleware function. An API slice ends with endpoints that return real data from a real store, not hardcoded fixtures. A dashboard slice ends with a real dashboard rendering real data, not a component that renders mock props. If a slice can't ship the real thing yet because a dependency isn't built, it should ship with realistic stubs that are clearly marked for replacement — but the user-facing surface must be real.
+- **Ambition matches the milestone.** The number and depth of slices should match the milestone's ambition. A milestone promising "core platform with auth, data model, and primary user loop" should have enough slices to actually deliver all three as working features — not two proof-of-concept slices and a note that "the rest will come in the next milestone." If the milestone's context promises an outcome, the roadmap must deliver it.
+
+**You MUST write the file `{{outputAbsPath}}` before finishing.**
+
+When done, say: "Milestone {{milestoneId}} planned."

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

@@ -0,0 +1,63 @@
+You are executing Kata auto-mode.
+
+## UNIT: Plan Slice {{sliceId}} ("{{sliceTitle}}") — Milestone {{milestoneId}}
+
+All relevant context has been preloaded below — start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+### Dependency Slice Summaries
+
+Pay particular attention to **Forward Intelligence** sections — they contain hard-won knowledge about what's fragile, what assumptions changed, and what this slice should watch out for.
+
+{{dependencySummaries}}
+
+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-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.
+   - For simple slices: executable commands or script assertions are fine.
+   - If the project is non-trivial and has no test framework, the first task should set one up.
+   - If this slice establishes a boundary contract, verification must exercise that contract.
+4. Plan observability and diagnostics explicitly:
+   - For non-trivial backend, integration, async, stateful, or UI slices, include an `Observability / Diagnostics` section in the slice plan.
+   - Define how a future agent will inspect state, detect failure, and localize the problem.
+   - Prefer structured logs/events, stable error codes/types, status surfaces, and persisted failure state over ad hoc debug text.
+   - Include at least one verification check for a diagnostic or failure-path signal when relevant.
+5. Fill the `Proof Level` and `Integration Closure` sections truthfully:
+   - State whether the slice proves contract, integration, operational, or final-assembly behavior.
+   - Say whether real runtime or human/UAT is required.
+   - Name the wiring introduced in this slice and what still remains before the milestone is truly usable end-to-end.
+6. Decompose the slice into tasks, each fitting one context window
+7. Every task in the slice plan should be written as an executable increment with:
+   - a concrete, action-oriented title
+   - the inline task entry fields defined in the plan.md template (Why / Files / Do / Verify / Done when)
+   - a matching task plan containing description, steps, must-haves, verification, observability impact, inputs, and expected output
+8. Each task needs: title, description, steps, must-haves, verification, observability impact, inputs, and expected output
+9. If verification includes test files, ensure the first task includes creating them with expected assertions (they should fail initially — that's correct)
+10. Write `{{outputPath}}`
+11. Write individual task plans in `{{sliceAbsPath}}/tasks/`: `T01-PLAN.md`, `T02-PLAN.md`, etc.
+12. **Self-audit the plan before continuing.** Walk through each check — if any fail, fix the plan files before moving on:
+    - **Completion semantics:** If every task were completed exactly as written, the slice goal/demo should actually be true at the claimed proof level. Do not allow a task plan that only scaffolds toward a future working state.
+    - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned.
+    - **Task completeness:** Every task has steps, must-haves, verification, observability impact, inputs, and expected output — none are blank or vague.
+    - **Dependency correctness:** Task ordering is consistent. No task references work from a later task.
+    - **Key links planned:** For every pair of artifacts that must connect (component → API, API → database, form → handler), there is an explicit step that wires them — not just "create X" and "create Y" in separate tasks with no connection step.
+    - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 6–8 steps or 8–10 files is a warning — consider splitting. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.
+    - **Context compliance:** If context/research artifacts or `.kata/DECISIONS.md` exist, the plan honors locked decisions and doesn't include deferred or out-of-scope items.
+    - **Requirement coverage:** If `REQUIREMENTS.md` exists, every Active requirement this slice owns (per the roadmap) maps to at least one task with verification that proves the requirement is met. No owned requirement is left without a task. No task claims to satisfy a requirement that is Deferred or Out of Scope.
+    - **Proof honesty:** The `Proof Level` and `Integration Closure` sections match what this slice will actually prove, and they do not imply live end-to-end completion if only fixture or contract proof is planned.
+    - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding. If the slice has a UI surface, at least one task builds the real UI (not a placeholder). If the slice has an API, at least one task connects it to a real data source (not hardcoded returns). If every task were completed and you showed the result to a non-technical stakeholder, they should see real product progress, not developer artifacts.
+13. If planning produced structural decisions (e.g. verification strategy, observability strategy, technology choices, patterns to follow), append them to `.kata/DECISIONS.md`
+14. Commit: `docs({{sliceId}}): add slice plan`
+15. Update `.kata/STATE.md`
+
+The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. You are on the slice branch; all work stays here.
+
+**You MUST write the file `{{outputAbsPath}}` before finishing.**
+
+When done, say: "Slice {{sliceId}} planned."