@kata-sh/cli 0.1.0 → 0.1.1

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

@@ -0,0 +1,85 @@
+{{preamble}}
+
+Say exactly: "What do you want to add?" — nothing else. Wait for the user's answer.
+
+## Discussion Phase
+
+After they describe it, your job is to understand the new work deeply enough to create context files that a future planning session can use.
+
+**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
+- How the new work relates to existing milestones — overlap, dependencies, prerequisites
+- If `.kata/REQUIREMENTS.md` exists: which unmet Active or Deferred requirements this queued work advances
+
+**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:** After about 10-15 questions total (3-5 rounds), or when you feel you have a solid understanding, include a question like:
+"I think I have a good picture. Ready to queue this, or are there more things to discuss?"
+with options: "Ready to queue (Recommended)", "I have more to discuss"
+
+If the user wants to keep going, keep asking. If they're ready, proceed.
+
+## Existing Milestone Awareness
+
+{{existingMilestonesContext}}
+
+Before writing anything, assess the new work against what already exists:
+
+1. **Dedup check** — Is this already covered (fully or partially) by an existing milestone? If so, tell the user and explain what's already planned. Don't create duplicate milestones.
+2. **Extension check** — Should this be added to an existing *pending* (not yet started) milestone rather than creating a new one? If the scope naturally belongs with existing pending work, propose extending that milestone's context instead.
+3. **Dependency check** — Does the new work depend on something that's currently in progress or planned? Note the dependency so context files capture it.
+4. **Requirement check** — If `.kata/REQUIREMENTS.md` exists, identify whether this queued work advances unmet Active requirements, promotes Deferred work, or introduces entirely new scope that should also update the requirement contract.
+
+If the new work is already fully covered, say so and stop — don't create anything.
+
+## Scope Assessment
+
+Before writing artifacts, assess whether this is **single-milestone** or **multi-milestone** scope.
+
+**Single milestone** if the work is one coherent body of deliverables that fits in roughly 2-12 slices.
+
+**Multi-milestone** if:
+- The work has natural phase boundaries
+- Different parts could ship independently on different timelines
+- The full scope is too large for one milestone to stay focused
+- The document/spec describes what is clearly multiple major efforts
+
+If multi-milestone: propose the split to the user before writing artifacts.
+
+## Sequencing
+
+Determine where the new milestones should go in the overall sequence. Consider dependencies, prerequisites, and independence.
+
+## Output Phase
+
+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."
+
+Then, after all milestone directories and context files are written:
+
+3. Update `.kata/PROJECT.md` — add the new milestones to the Milestone Sequence. Keep existing entries exactly as they are. Only add new lines.
+4. If `.kata/REQUIREMENTS.md` exists and the queued work introduces new in-scope capabilities or promotes Deferred items, update it.
+5. If discussion produced decisions relevant to existing work, append to `.kata/DECISIONS.md`.
+6. Append to `.kata/QUEUE.md`.
+7. Commit: `docs: queue <milestone list>`
+
+**Do NOT write roadmaps for queued milestones.**
+**Do NOT update `.kata/STATE.md`.**
+
+After writing the files and committing, say exactly: "Queued N milestone(s). Auto-mode will pick them up after current work completes." — nothing else.

package/src/resources/extensions/kata/prompts/reassess-roadmap.md

@@ -0,0 +1,48 @@
+You are executing Kata auto-mode.
+
+## UNIT: Reassess Roadmap — Milestone {{milestoneId}} after {{completedSliceId}}
+
+All relevant context has been preloaded below — the current roadmap, completed slice summary, project state, and decisions are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during reassessment, without relaxing required verification or artifact rules.
+
+Then assess whether the remaining roadmap still makes sense given what was just built.
+
+**Bias strongly toward "roadmap is fine."** Most of the time, the plan is still good. Only rewrite if you have concrete evidence that remaining slices need to change. Don't rewrite for cosmetic reasons, minor optimization, or theoretical improvements.
+
+Ask yourself:
+- Did this slice retire the risk it was supposed to? If not, does a remaining slice need to address it?
+- Did new risks or unknowns emerge that should change slice ordering?
+- Are the boundary contracts in the boundary map still accurate given what was actually built?
+- Should any remaining slices be reordered, merged, split, or adjusted based on concrete evidence?
+- Did assumptions in remaining slice descriptions turn out wrong?
+- If `.kata/REQUIREMENTS.md` exists: did this slice validate, invalidate, defer, block, or newly surface requirements?
+- If `.kata/REQUIREMENTS.md` exists: does the remaining roadmap still provide credible coverage for Active requirements, including launchability, primary user loop, continuity, and failure visibility where relevant?
+
+### Success-Criterion Coverage Check
+
+Before deciding whether changes are needed, enumerate each success criterion from the roadmap's `## Success Criteria` section and map it to the remaining (unchecked) slice(s) that prove it. Each criterion must have at least one remaining owning slice. If any criterion has no remaining owner after the proposed changes, flag it as a **blocking issue** — do not accept changes that leave a criterion unproved.
+
+Format each criterion as a single line:
+
+- `Criterion text → S02, S03` (covered by at least one remaining slice)
+- `Criterion text → ⚠ no remaining owner — BLOCKING` (no slice proves this criterion)
+
+If all criteria have at least one remaining owning slice, the coverage check passes. If any criterion has no remaining owner, resolve it before finalizing the assessment — either by keeping a slice that was going to be removed, adding coverage to another slice, or explaining why the criterion is no longer relevant.
+
+**If the roadmap is still good:**
+
+Write `{{assessmentAbsPath}}` with a brief confirmation that roadmap coverage still holds after {{completedSliceId}}. If requirements exist, explicitly note whether requirement coverage remains sound.
+
+**If changes are needed:**
+
+1. Rewrite the remaining (unchecked) slices in `{{roadmapPath}}`. Keep completed slices exactly as they are (`[x]`). Update the boundary map for changed slices. Update the proof strategy if risks changed. Update requirement coverage if ownership or scope changed.
+2. Write `{{assessmentAbsPath}}` explaining what changed and why — keep it brief and concrete.
+3. If `.kata/REQUIREMENTS.md` exists and requirement ownership or status changed, update it.
+4. Commit: `docs({{milestoneId}}): reassess roadmap after {{completedSliceId}}`
+
+**You MUST write the file `{{assessmentAbsPath}}` before finishing.**
+
+When done, say: "Roadmap reassessed."

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

@@ -0,0 +1,39 @@
+You are executing Kata auto-mode.
+
+## UNIT: Replan Slice {{sliceId}} ("{{sliceTitle}}") — Milestone {{milestoneId}}
+
+A completed task reported `blocker_discovered: true`, meaning the current slice plan cannot be executed as-is. Your job is to rewrite the remaining tasks in the slice plan to address the blocker while preserving all completed work.
+
+All relevant context has been preloaded below — the roadmap, current slice plan, the blocker task summary, and decisions are inlined. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+## Hard Constraints
+
+- **Do NOT renumber or remove completed tasks.** All `[x]` tasks and their IDs must remain exactly as they are in the plan.
+- **Do NOT change completed task descriptions, estimates, or metadata.** They are historical records.
+- **Preserve completed task summaries.** Do not modify any `T0x-SUMMARY.md` files for completed tasks.
+- Only modify `[ ]` (incomplete) tasks. You may rewrite, reorder, add, or remove incomplete tasks as needed to address the blocker.
+- New tasks must follow the existing ID numbering sequence (e.g., if T01–T03 exist, new tasks start at T04 or continue from the highest existing ID).
+
+## Instructions
+
+1. Read the blocker task summary carefully. Understand exactly what was discovered and why it blocks the current plan.
+2. Analyze the remaining `[ ]` tasks in the slice plan. Determine which are still valid, which need modification, and which should be replaced.
+3. Write `{{replanAbsPath}}` documenting:
+   - What blocker was discovered and in which task
+   - What changed in the plan and why
+   - Which incomplete tasks were modified, added, or removed
+   - Any new risks or considerations introduced by the replan
+4. Rewrite `{{planPath}}` with the updated slice plan:
+   - Keep all `[x]` tasks exactly as they were (same IDs, same descriptions, same checkmarks)
+   - Update the `[ ]` tasks to address the blocker
+   - Ensure the slice Goal and Demo sections are still achievable with the new tasks, or update them if the blocker fundamentally changes what the slice can deliver
+   - Update the Files Likely Touched section if the replan changes which files are affected
+5. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
+6. Commit all changes: `git add -A && git commit -m 'refactor({{sliceId}}): replan after blocker in {{blockerTaskId}}'`
+7. Update `.kata/STATE.md`
+
+**You MUST write `{{replanAbsPath}}` and the updated slice plan before finishing.**
+
+When done, say: "Slice {{sliceId}} replanned."

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

@@ -0,0 +1,37 @@
+You are executing Kata auto-mode.
+
+## UNIT: Research Milestone {{milestoneId}} ("{{milestoneTitle}}")
+
+All relevant context has been preloaded below — start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+Then research the codebase and relevant technologies:
+1. 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
+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`
+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)
+   - Don't Hand-Roll table (problems with existing solutions)
+   - Common Pitfalls (what goes wrong, how to avoid)
+   - Relevant Code (existing files, patterns, integration points)
+   - Sources
+
+## Strategic Questions to Answer
+
+- What should be proven first?
+- What existing patterns should be reused?
+- What boundary contracts matter?
+- What constraints does the existing codebase impose?
+- Are there known failure modes that should shape slice ordering?
+- If requirements exist: what table stakes, expected behaviors, continuity expectations, launchability expectations, or failure-visibility expectations are missing, optional, or clearly out of scope?
+- Which research findings should become candidate requirements versus remaining advisory only?
+
+**Research is advisory, not auto-binding.** Surface candidate requirements clearly instead of silently expanding scope.
+
+**You MUST write the file `{{outputAbsPath}}` before finishing.**
+
+When done, say: "Milestone {{milestoneId}} researched."

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

@@ -0,0 +1,28 @@
+You are executing Kata auto-mode.
+
+## UNIT: Research 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 to watch out for.
+
+{{dependencySummaries}}
+
+Then research what this slice needs:
+0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements this slice owns or supports. Research should target these requirements — surfacing risks, unknowns, and implementation constraints that could affect whether the slice actually delivers them.
+1. 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
+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`
+6. Write `{{outputPath}}`
+
+The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.
+
+**You MUST write the file `{{outputAbsPath}}` before finishing.**
+
+When done, say: "Slice {{sliceId}} researched."

package/src/resources/extensions/kata/prompts/run-uat.md

@@ -0,0 +1,109 @@
+You are executing Kata auto-mode.
+
+## UNIT: Run UAT — {{milestoneId}}/{{sliceId}}
+
+All relevant context has been preloaded below. Start working immediately without re-reading these files.
+
+{{inlinedContext}}
+
+If a `Kata Skill Preferences` block is present in system context, use it to decide which skills to load and follow during UAT execution, without relaxing required verification or artifact rules.
+
+---
+
+## UAT Instructions
+
+**UAT file:** `{{uatPath}}`
+**UAT type:** `{{uatType}}`
+**Result file to write:** `{{uatResultAbsPath}}` (relative: `{{uatResultPath}}`)
+
+### If UAT type is `artifact-driven`
+
+You are the test runner. Execute every check defined in `{{uatPath}}` directly:
+
+- Run shell commands with `bash`
+- Run `grep` / `rg` checks against files
+- Run `node` / script invocations
+- Read files and verify their contents
+- Check that expected artifacts exist and have correct structure
+
+For each check, record:
+- The check description (from the UAT file)
+- The command or action taken
+- The actual result observed
+- PASS or FAIL verdict
+
+After running all checks, compute the **overall verdict**:
+- `PASS` — all checks passed
+- `FAIL` — one or more checks failed
+- `PARTIAL` — some checks passed, some failed or were skipped
+
+Write `{{uatResultAbsPath}}` with:
+
+```markdown
+---
+sliceId: {{sliceId}}
+uatType: {{uatType}}
+verdict: PASS | FAIL | PARTIAL
+date: <ISO 8601 timestamp>
+---
+
+# UAT Result — {{sliceId}}
+
+## Checks
+
+| Check | Result | Notes |
+|-------|--------|-------|
+| <check description> | PASS / FAIL | <observed output or reason> |
+
+## Overall Verdict
+
+<PASS / FAIL / PARTIAL> — <one sentence summary>
+
+## Notes
+
+<any additional context, errors encountered, or follow-up items>
+```
+
+### If UAT type is NOT `artifact-driven` (type is `{{uatType}}`)
+
+This UAT type requires human execution or live-runtime observation that you cannot perform mechanically. Your role is to surface it clearly for review.
+
+Write `{{uatResultAbsPath}}` with:
+
+```markdown
+---
+sliceId: {{sliceId}}
+uatType: {{uatType}}
+verdict: surfaced-for-human-review
+date: <ISO 8601 timestamp>
+---
+
+# UAT Result — {{sliceId}}
+
+## UAT Type
+
+`{{uatType}}` — requires human execution or live-runtime verification.
+
+## Status
+
+Surfaced for human review. Auto-mode will pause after this unit so the UAT can be performed manually.
+
+## UAT File
+
+See `{{uatPath}}` for the full UAT specification and acceptance criteria.
+
+## Instructions for Human Reviewer
+
+Review `{{uatPath}}`, perform the described UAT steps, then update this file with:
+- The actual verdict (PASS / FAIL / PARTIAL)
+- Results for each check
+- Date completed
+
+Once updated, run `/kata auto` to resume auto-mode.
+```
+
+---
+
+**You MUST write `{{uatResultAbsPath}}` before finishing.**
+
+When done, say: "UAT {{sliceId}} complete."