buildkeel 0.3.0 → 0.5.0

package/antigravity/skills/bk-capture/SKILL.md

@@ -5,17 +5,29 @@ description: "BuildKeel: Turn what you discussed into a plan: a plain summary, t
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
 
-When you ask a question with choices, the user may see nothing you wrote before it: whenever a step says to show something and then ask, put it in the question itself, as it is, and never say it was shown above.
+Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
 
 Turn the conversation into a plan the team's process can build from, with the user agreeing at each step: the summary, the list of what will be created, the pace, then each artifact. Nothing is saved that the user has not agreed to, and everything saved stays a draft until it is approved.
 
 The user typed: whatever follows /bk-capture in the user's message (nothing, if they typed only /bk-capture)
 
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
 If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow step 1, then "In a Spec-driven tree" at the end in place of steps 2 to 6.
 
+## How each review goes
+
+The summary, the plan and each artifact are reviewed the same way: shown in full in your reply, with your question in plain text at its end. The user's reply decides what follows:
+
+- **Agreement**, such as "looks good", "yes" or "next": go on, and for an artifact, save it.
+- **"Draft the rest"**: draft what is left in one go, and show it as a set, as "All at once" says.
+- **Anything else is feedback**, "ok, but…" included: discuss it for as long as the user wants. Then list each point they raised with how you addressed it, or why you did not, show the final version, and ask again. Save nothing until they agree. When the only change is small, the final version may be just the changed parts, with a note that nothing else changed. When you cannot tell whether a reply agrees, ask.
+
+When later discussion in this capture would change something the user already agreed, such as a story agreed before a decision on the next one, say so openly: which artifact, what changes and why. Show the change and take it through the same review, and save it with `save_draft` only once the user agrees. In a Spec-driven tree, read one file of the change with `query`, `view: "changes"`, its `id` and `file`, and save a change to one requirement with `save_draft`, `type: "spec-change"`, the change's `id`, its `capability` and `requirement`, rather than resending the whole file. Never change an agreed artifact silently, and never add a requirement, criterion or test case that was not discussed.
+
 ## 1. Say what you heard
 
-Before calling any tool, sum up the discussion in plain words, with no BuildKeel terms yet (no stages, IDs or templates):
+Once that check is done, and before any other tool call, sum up the discussion in plain words, with no BuildKeel terms yet (no stages, IDs or templates):
 
 - **What you set out to do**: the user's intent, in a sentence.
 - **The idea**: what it is, and who it is for.
@@ -24,41 +36,59 @@ Before calling any tool, sum up the discussion in plain words, with no BuildKeel
 
 If the user typed something above, sum up that part of the conversation. If there is nothing to capture yet, say so, ask what they want to plan, and stop. If the conversation was compacted, say that its earlier parts may be missing from the summary, and ask the user to add anything left out.
 
-Then ask, with your tool for asking a question with choices if you have one, showing the summary. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+Then ask whether to go on, with the summary in that same reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices:
 
 1. **Create the artifacts** (the default, listed first).
-2. **Change something.** Take in what they say and show the summary again.
+2. **Change something.** Take it as feedback, as "How each review goes" says, and show the summary again.
 3. **Keep talking.** Stop here: nothing is drafted, and the conversation goes on.
 
 Any other answer, such as a correction or a new thought, is more conversation: answer it as you would, and draft nothing.
 
+### A problem someone reported
+
+When the discussion is about a problem someone reported with how the system behaves, sort it once the user chooses to create the artifacts, before step 2.
+
+**Sorting a report.** When someone reports that the system does something wrong, check it before recording anything: what the spec says about that behavior now (in a Spec-driven tree, `query` with `view: "capabilities"` and the capability's `id`; otherwise the stories and their acceptance criteria, with `query`), and the code linked to it (`query` with `view: "describes"` and the files involved). Then propose one reading, labelled as yours, such as "My reading: a defect", with what it rests on:
+
+- **A defect**: the code does not do what the spec says. The code is fixed and the spec keeps its version. It is recorded as a defect with `source: reported`.
+- **A change in behavior**: the code does what the spec says, and the user wants something else. The spec changes and gets a new version: in a Spec-driven tree through a change, otherwise through a new version of the story, or a new item of the team's kind for it, such as an enhancement.
+- **A gap**: the spec says nothing about it. Settle with the user what it should do; that goes into the spec as a change in behavior.
+- **Nothing describes this code yet**: `describes` finds no artifact for it. In Full SDLC, draft version 0 of the story the code belongs to first, stating the intended behavior, and record the defect with that draft as its parent; both are reviewed and approved together, version 0 first. In a Spec-driven tree, ask **Record it standalone** (the default) or **Document this code first**, as version 0 of a capability spec, then link the defect to its requirement.
+
+Ask with your tool for asking a question with choices, your reading first, then the other readings, so the user confirms or overrides it. Record nothing until they answer. A defect found while building, such as a failing test of the work under way, needs no sorting: it is a defect of that work.
+
+A defect is recorded as /bk-new defect records one: `get_template` for `defect`, then `save_draft` with `type: "defect"`, `source: reported` and the parent agreed. A change in behavior or a gap goes on to step 2 as work to plan, with the reading the user confirmed.
+
 ## 2. Propose the plan
 
 1. Call the BuildKeel `query` tool with `view: "process"` for the stages and the documents each requires, and with `view: "tree"` for what exists. Read an existing artifact with `view: "artifact"` when you need to know what it covers.
 2. Work out the artifacts the work needs, level by level, from the business idea down to the tasks, in the team's stage names: which already exist, which are new, and the documents each stage requires, such as a design document for a new epic and a test plan for each new story. For each task, work out which of its story's test cases its tests will implement. A task whose tests implement none of them, such as a building block (a client, a data model, a migration), needs a test plan of its own, or it can never be finished: put it in the table.
 3. Recommend where the work fits in the tree, and say why: under an existing business idea or epic, or as something new.
 4. If the work changes how something already built behaves, and a document describes how it works today (such as EP-01's design document for password reset), the plan includes a new version of that document.
-5. If the work changes code that already exists, work out which files it will change, from the discussion and the code, and call `query` with `view: "describes"` and their `paths`. Where an artifact describes them, the work builds on it. Where nothing describes the behavior the work changes, the plan includes a **version 0**: one artifact, usually a story, describing only what the work touches, as it works today, before the change. The change is then its version 1, or an artifact under it. A version 0 is a proposal: the user can drop it.
+5. When a stage holds more than one kind of work (`view: "process"` lists the kinds at each stage), propose a kind for each new artifact at that stage, from where the work came from, and say why in the table: an enhancement when it improves existing behavior, a feature when it adds something new, as the team's kinds are named. The user confirms or changes each kind as part of the plan; never draft one as a kind the user has not agreed to. Each is drafted with its kind as `type`, from that kind's template, and numbered in that kind's sequence.
+6. If the work changes code that already exists, work out which files it will change, from the discussion and the code, and call `query` with `view: "describes"` and their `paths`. Where an artifact describes them, the work builds on it. Where nothing describes the behavior the work changes, the plan includes a **version 0**: one artifact, usually a story, describing only what the work touches, as it works today, before the change. The change is then its version 1, or an artifact under it. A version 0 is a proposal: the user can drop it.
 
 Show the plan as a table, top down, each row with a one-line purpose, and say where the work fits and why, in a sentence:
 
-| Level | Artifact | Status | Purpose |
-|---|---|---|---|
-| Business idea | BI-01 "Self-service account recovery" | exists | the goal this serves |
-| Epic | "Reset by text message" | new | the new capability |
-| Design document | of the new epic | new, required | how it is built |
-| Story | "Request a code by text" | new | one per user-facing behavior |
-| Test plan | one per story | new, required | covers every criterion |
-| Task | "SMS gateway client" | new | one per piece of code, with its repository |
-| Test plan | of "SMS gateway client" | new | its tests are none of the story's test cases |
-| Design document | EP-01-DD | new version | password reset now works differently |
-| Story | "Password reset" | version 0, then the change as version 1 | how reset by email works today, which nothing describes yet |
+| Level | Kind | Artifact | Status | Purpose |
+|---|---|---|---|---|
+| Business idea | business idea | BI-01 "Self-service account recovery" | exists | the goal this serves |
+| Epic | epic | "Reset by text message" | new | the new capability |
+| Design document | | of the new epic | new, required | how it is built |
+| Story | user story | "Request a code by text" | new | one per user-facing behavior |
+| Test plan | | one per story | new, required | covers every criterion |
+| Task | task | "SMS gateway client" | new | one per piece of code, with its repository |
+| Test plan | | of "SMS gateway client" | new | its tests are none of the story's test cases |
+| Design document | | EP-01-DD | new version | password reset now works differently |
+| Story | user story | "Password reset" | version 0, then the change as version 1 | how reset by email works today, which nothing describes yet |
 
-Then ask, the same way, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+The Kind column names each artifact's kind; when every stage holds one kind, it is the stage's name, and you may leave the column out.
+
+Then ask, the same way, with the table and that sentence in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices:
 
 1. **Looks right** (the default).
 2. **Place it somewhere else.** Ask where. The new artifact is drafted where the user says, with a link to the one you recommended (`related: [EP-01]`).
-3. **Change the plan.** Take in what they say and show the table again.
+3. **Change the plan.** Take it as feedback, as "How each review goes" says, and show the table again.
 4. **Keep talking.** Stop here; nothing is drafted.
 
 When the plan holds a version 0, offer **Looks right, without the version 0** in place of the second choice; placing the work somewhere else is then a change to the plan. Without the version 0, the change is drafted as version 1 of a new artifact, as for any new work.
@@ -82,7 +112,7 @@ Ask, every time, how the user wants to go through the drafts. Never assume it, a
 - A design document has no `id`; its `parent` is the artifact it describes. Add an offered section (`get_template` lists them) only when the discussion covered it.
 - When the work changes how an existing capability works: save the new version of that capability's document with `save_draft` and its ID, and give the new artifact `changes: [<that document's ID>]`, so it cannot be finished until that version is approved.
 - A **version 0** in the plan is drafted before the change, by the rules below, with `save_draft` and `version: 0`. Name the paths it covers in its `scope`. Then draft the change: as its version 1, with `save_draft`, the version 0's draft ID as `id` and no `version`, holding the whole artifact as it will be after the change. Start from version 0's text as saved, with its entry IDs: keep the ID of every entry that stays, changed or not (a criterion whose limit changes keeps its ID), and write `{{new}}` only for an entry the change adds. Or, when the change is new work under it, as a new artifact whose `parent` is that draft ID.
-- Save each one with `save_draft`.
+- Save each one with `save_draft`, and only once the user has agreed to it.
 
 ### Step by step
 
@@ -90,14 +120,14 @@ Go through the plan in this order, leaving out what already exists: a version 0
 
 1. Draft it against the artifacts already saved in this capture.
 2. Show it, with a line naming the pitfalls and constraints from the summary that it covers. Ask about each gap it has, as "Gaps" says, before going on.
-3. Ask, showing it. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Looks good, next** (the default), **Change something** (take in what they say and show it again), and **Draft the rest at once** (draft what is left in one go, then show it as a set).
+3. Ask, with it in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices: **Looks good, next** (the default), **Change something** (feedback, as "How each review goes" says: the points with how each was addressed, then the final version), and **Draft the rest at once** (draft what is left in one go, then show it as a set).
 4. Save it with `save_draft` once the user agrees, before drafting the next.
 
 If the user stops partway, what they agreed to stays saved as drafts; draft nothing more.
 
 ### All at once
 
-Draft everything, asking about gaps as you go, and save each one with `save_draft`. Then show what was drafted as a table: ID, title, and the pitfalls each covers.
+Draft everything, asking about gaps as you go. Show the set in full, each artifact with the pitfalls it covers, then a table of them all: title and the pitfalls each covers. Take the set through the review: feedback on any of them is answered as "How each review goes" says, with the final version of each artifact it changed. Once the user agrees, save them with `save_draft`, top down, each child naming the draft ID its parent was given.
 
 ### Gaps
 
@@ -117,16 +147,21 @@ Version 0 describes what the code does today, as if BuildKeel had been used from
 - Reword what the code and the sources say into the template's form, such as a ticket's description written as testable criteria. Add nothing they do not support.
 - Describe only what the work touches, not the whole area around it.
 - Keep each source as you read it: pass it to `save_draft` in `sources`, with where it came from, its key and link, and its text exactly as your tool returned it (description, fields and comments). Never copy code into a source: the baseline commit names the code.
-- When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended, before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it with /bk-new bug once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
+- When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended, before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded against it with /bk-new defect once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
 - Supported means the code or a source says it. A plausible guess is not support: who a story is for and why, a business idea's problem and goals, or a design's context are rarely in the code. Leave a required section empty when nothing supports it, and do not ask about it here: `save_draft` lists what version 0 leaves empty, and the reviewer sees it.
 
 ## 5. What is left
 
 List each pitfall or constraint from the summary that no saved artifact covers, and treat each as a gap, as above. Then show what was drafted as a table: ID, title, and its open questions, if any.
 
-## 6. Next step
+## 6. Approve them, or leave them as drafts
+
+Agreeing to an artifact here does not approve it: approving is a separate choice, with permanent numbers and frozen versions. Once the last artifact is agreed, ask in plain text, at the end of the reply with the table: **Approve them now** (the default), or **Leave them as drafts**, for another approver to approve later with /bk-approve.
+
+- **Approve them now:** call the BuildKeel `approve` tool with `ids` set to every artifact agreed in this capture, without `apply`. Name a version 0 with `@v0`, such as `US-draft-k3x9@v0`, and keep the version built on it in the set too. A task's own test plan is not in the set unless the process approves task plans: it is recorded when its task is approved. Show the set as `approve` gives it, in the order it will be approved, with what each will become and anything that would not pass, and why. Then ask: **Approve them** (the default; any that would not pass stay drafts), **Fix what would not pass first** (each fix shown and saved with `save_draft` once the user agrees, then the set checked again), or **Stop**. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when the user confirms, call `approve` again with the same `ids` and `apply: true`, and show the result as it is.
+- **Leave them as drafts:** approve nothing. Say that the drafts wait for /bk-approve, which shows them as one set.
 
-Agreeing to an artifact here does not approve it. Offer approval as the next step: /bk-approve shows the drafts from this capture as one set, with anything that would not pass, and approves them in one review once the user confirms, a version 0 before the change built on it. A task's own test plan is not in the set unless the process approves task plans: it is recorded when its task is approved. Do not approve anything yourself here.
+Never approve anything the user has not confirmed in this conversation.
 
 Do not create or edit spec tree files yourself; `save_draft` does all writing.
 
@@ -135,9 +170,12 @@ Do not create or edit spec tree files yourself; `save_draft` does all writing.
 The plan is one change: a proposal, a spec change for each capability whose behavior it alters, a design only when needed, and tasks. Nothing is approved.
 
 1. **Read the capability specs first.** Call `query` with `view: "capabilities"`, then with the `id` of each capability the work touches, so the change starts from how the system behaves now. Check `view: "changes"` for an open change that already covers the work.
-2. **Propose the change**, showing a table of the capabilities it adds or modifies, by code, with what changes in each, and say in a sentence whether it needs a design: only when it makes decisions worth recording, such as a new component, data, an interface or a trade-off. A change that alters no behavior, such as a refactor, says so and has no spec changes. For a new capability, propose a short code from its name, such as SMS, which the user can change before anything is saved. Then ask, the same way as in step 1, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Looks right** (the default), **Change the plan**, **Keep talking**.
+   - **A late addition.** When the work would add a requirement to an open change with more than half its tasks ticked, ask once, in plain text, before drafting anything: does it belong in that change, or in a new one? Draft nothing until the user answers, and go on with the change they choose.
+2. **Propose the change**, showing a table of the capabilities it adds or modifies, by code, with what changes in each, and say in a sentence whether it needs a design: only when it makes decisions worth recording, such as a new component, data, an interface or a trade-off. A change that alters no behavior, such as a refactor, says so and has no spec changes. For a new capability, propose a short code from its name, such as SMS, which the user can change before anything is saved. Then ask, the same way as in step 1, with the table and that sentence in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices: **Looks right** (the default), **Change the plan**, **Keep talking**.
+   - **Revising an open change.** When the work revises a change that is already open, call `query` with `view: "changes"` and its `id` first: besides its files, it gives what the work so far traces to, the files each ticked task's commits changed and the tests tagged with each requirement's scenarios. Add an **Affected** part to the table, for each requirement the revision removes or modifies: the tests tagged with its scenarios, the tasks that name it with the files their commits changed, and which ticked tasks no longer apply or now build on a changed requirement. Take the code from that trace, never from file names. Then ask the user about each affected ticked task, one at a time: **Keep it ticked**, **Rework it** (untick it and reword it as the revision needs), or **Drop it** (take it out of the tasks, with the code it leaves to remove named as a task when the user wants one). What the user decides goes into the tasks through the review.
+   - **A new title.** When the revision changes what the change is about, show its current title beside the one you propose, and ask whether to change it. Change it only when the user agrees: the proposal is saved with the new title, and the change's folder is renamed with it. If the user says the title still fits, keep it.
 3. **Ask the pace**, as in step 3 above: **Step by step** (the default) or **All at once**, every time.
 4. **Draft the change.** Call `get_template` for proposal, spec-change, tasks and, when needed, design. Draft by "How to draft" and "Gaps" above: each settled pitfall becomes a requirement or scenario, and nothing is invented. A modified requirement keeps its ID and holds its full new text; a removed one says why and what replaces it. Each task says how its completion is verified, and each group holds the tests and docs its work needs.
-   - **Step by step:** show the proposal, with the pitfalls it covers, and save it once the user agrees, with `save_draft`, `type: "change"` and the proposal as `content`: that creates the change. Then each spec change, then the design if one is needed, then the tasks, each shown, agreed and saved in turn with `save_draft`, its `type` (`spec-change`, `design` or `tasks`) and the change's `id`. Offer **Looks good, next** (the default), **Change something** and **Draft the rest at once** at each step, as above.
-   - **All at once:** save them in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`, then show them.
-5. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Treat each pitfall from the summary that no file covers as a gap, and each missing part `save_draft` names. Then offer /bk-start with the change's ID as the next step.
+   - **Step by step:** show the proposal, with the pitfalls it covers, and save it once the user agrees, with `save_draft`, `type: "change"` and the proposal as `content`: that creates the change. Then each spec change, then the design if one is needed, then the tasks, each shown, agreed and saved in turn with `save_draft`, its `type` (`spec-change`, `design` or `tasks`) and the change's `id`. Offer **Looks good, next** (the default), **Change something** and **Draft the rest at once** at each step, and answer feedback as "How each review goes" says.
+   - **All at once:** show the whole change in full and take it through the review. Once the user agrees, save it in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`.
+5. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Treat each pitfall from the summary that no file covers as a gap, and each missing part `save_draft` names. Then offer /bk-build with the change's ID as the next step.

package/antigravity/skills/bk-done/SKILL.md

@@ -5,19 +5,21 @@ description: "BuildKeel: Finish the active unit, or a story or epic once everyth
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
 
-When you ask a question with choices, the user may see nothing you wrote before it: whenever a step says to show something and then ask, put it in the question itself, as it is, and never say it was shown above.
+Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
 
 Finish a BuildKeel unit with the user. Finishing writes a permanent record of what was built, against which approved versions and with which test results, so it is the user's decision: never finish a unit they have not confirmed in this conversation.
 
 The user typed: whatever follows /bk-done in the user's message (nothing, if they typed only /bk-done)
 
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
 If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end for a change.
 
 ## Choose the unit
 
 If the user named a unit above, use it.
 
-If the user typed nothing, ask straight away, before calling any tool: "What do you want to finish?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+If the user typed nothing, ask straight away: "What do you want to finish?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
 
 1. **The active unit in this working tree** (the default, listed first).
 2. **Another unit, or a story or epic whose work is all done: type its ID.** If they pick this, ask for the ID.
@@ -31,17 +33,17 @@ A story built through tasks, an epic, or a stage the team added above its storie
    - **Refused only because tests have no current result** (not run, or run before the code last changed): run the tests with a JUnit XML report, record it with `test_results`, and call `finish_work` without `apply` again. Do this once, without asking.
    - **Refused by the done gate** for anything else: show every failing check with its fix, as it is, and where each test case stands. Offer the fix that comes first: commit uncommitted changes (ending the message with `BuildKeel-Unit: <ID>`), write a test that is missing its tag, fix a failing test, or run the tests again. Do not finish anything else in its place.
    - **Not the active unit, or no active unit:** show the message and its fix.
-   - **A story or epic refused because work under it is open:** show every open unit with its fix, and where each test case stands. Offer to start the first open unit with /bk-start.
+   - **A story or epic refused because work under it is open:** show every open unit with its fix, and where each test case stands. Offer to start the first open unit with /bk-build.
    - **Ready:** show what finishing will record: the commits, the files, each test case's result, and any test cases left for the story. For a story or epic: the units under it and where each test case passed.
-   - **A standalone bug:** the result also says which stories its changes belong to. Ask where to attach it, with your tool for asking a question with choices: **the story it suggests** (the default), then each task it names, then **leave it standalone**. Pass the chosen ID in `attach` when you finish.
+   - **A standalone defect:** the result also says which stories its changes belong to. Ask where to attach it, with your tool for asking a question with choices: **the story it suggests** (the default), then each task it names, then **leave it standalone**. Pass the chosen ID in `attach` when you finish.
 
-## A bug that is not a defect
+## A defect closed without a fix
 
-When the unit is a bug, offer closing it without a fix beside finishing it, with your tool for asking a question with choices, whether or not it is started: **Finish <ID>** (the default when its regression test passes, or when the user has not said it is not a defect) or **Close without a fix**, for a bug that turns out not to be a defect (a duplicate, one that cannot be reproduced, behavior that works as intended, or a test that was wrong; the default when the user says so). To close, ask for the reason with the same tool, then for a duplicate which bug it duplicates, and for an optional note in the user's words. Call `finish_work` with `close` (`reason`, `duplicateOf`, `note`) and without `apply`, show what it says with the bug's title, and ask the user to confirm. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Only when they confirm, call it again with `apply: true`. Never close a bug the user has not confirmed in this conversation. When the test was wrong, offer to correct the test case as a new version of its test plan.
+When the unit is a defect, offer closing it without a fix beside finishing it, with your tool for asking a question with choices, whether or not it is started: **Finish <ID>** (the default when its regression test passes, or when the user has not said it is not one) or **Close without a fix**, for a defect that turns out not to be one (a duplicate, one that cannot be reproduced, behavior that works as intended, a test that was wrong, or a change in behavior: the code does what the spec says, and the spec is what must change; the default when the user says so). To close, ask for the reason with the same tool, then for a duplicate which defect it duplicates, for a change in behavior the change, version or item that takes it over (draft it first if there is none yet, such as a change, or a story's next version, with /bk-new), and for an optional note in the user's words. Call `finish_work` with `close` (`reason`, `duplicateOf`, `takenOverBy`, `note`) and without `apply`, show what it says with the defect's title, and ask the user to confirm. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when they confirm, call it again with `apply: true`. Never close a defect the user has not confirmed in this conversation. When the test was wrong, offer to correct the test case as a new version of its test plan.
 
 ## Confirm
 
-Ask the user with your tool for asking a question with choices, the default first, showing what the result said. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+Ask the user, the default first, with what the result said in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices:
 
 - If the result lists commits without a BuildKeel-Unit line, ask what to do with them:
   1. **Count them all as <ID> work and finish** (the default).
@@ -51,16 +53,26 @@ Ask the user with your tool for asking a question with choices, the default firs
   1. **Finish <ID>** (the default).
   2. **Stop, and do not finish yet.**
 
-Only when the user confirms, call `finish_work` again with `apply: true` (and the same `id` if you passed one), with `exclude` listing the IDs of any commits they left out, and with `attach` when they chose where to attach a standalone bug.
+Only when the user confirms, call `finish_work` again with `apply: true` (and the same `id` if you passed one), with `exclude` listing the IDs of any commits they left out, and with `attach` when they chose where to attach a standalone defect.
 
 ## Afterwards
 
 Show the result as it is: the completion record, the commit in the spec repo, and whether it was pushed. Remind the user to push the unit's branch and open a pull request as usual, and to push the spec repo when the record is not pushed. If test cases were left for the story, name them: the story cannot be finished until they pass.
 
-If the result names the next unit ready under the same parent, offer to start it, with your tool for asking a question with choices: **Start <ID>** (the default), or **Not now**. If the user agrees, call `start_work` with its `id` and `stack: true`, so its branch starts from this unit's branch and has this work before it is merged, and carry on as /bk-start does. Otherwise call `query` with `view: "startable"`, show what can be started next, and offer to start it with /bk-start, or to build everything ready with /bk-build.
+If the result names the next unit ready under the same parent, offer to start it, with your tool for asking a question with choices: **Start <ID>** (the default), or **Not now**. If the user agrees, call `start_work` with its `id` and `stack: true`, so its branch starts from this unit's branch and has this work before it is merged, and carry on as /bk-build does. Otherwise call `query` with `view: "startable"`, show what can be started next, and offer to build it with /bk-build.
 
 Do not create or edit spec tree files yourself: `finish_work` writes the record, and completion records are never edited.
 
 ## In a Spec-driven tree
 
-A change is finished by archiving it, and need not be the active unit. With none named and none active, `finish_work` lists the open changes: ask which to finish, allowing several, those with every task ticked first. Call `finish_work` without `apply` (with `ids` for several) and follow its result step by step: review the code against the change, report it labeled as your judgment, and ask **Fix first** or **Finish anyway**, fix first being the default when anything is reported missing. Nothing blocks the finish but uncommitted work. Bugs and ad-hoc units finish as above.
+A change is finished by archiving it, and need not be the active unit. With none named and none active, `finish_work` lists the open changes: ask which to finish, allowing several, those with every task ticked first. Call `finish_work` without `apply` (with `ids` for several) and follow its result step by step:
+
+1. **Unticked tasks first.** When it lists unticked tasks, check each against the code and the test results before showing anything else. Say in a line each which now pass their verification, and offer to tick them. Tick those the user agrees to with `save_draft`, `type: "tasks"`, the change's `id` and `tick`, then preview again.
+2. **Review and show.** Review the code against the change, and report it labeled as your judgment. In the same reply, show what finishing will write, as the result gives it: the capability specs after the merge, with the requirements the change adds or modifies in full and the others by name.
+3. **Ask.** End that reply with the choice, in plain text: **Fix first** or **Finish anyway**, fix first being the default when anything is reported missing. When your review finds a gap where the code is right and the spec is not, also offer **Reword the spec, then finish**. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Nothing blocks the finish but uncommitted work.
+   - **Fix first:** help fix it.
+   - **Reword the spec:** show the requirement's new text in full, with why, and save it only once the user agrees, with `save_draft`, `type: "spec-change"`, the change's `id`, its `capability` and `requirement`.
+   - After any commit or change, call `finish_work` without `apply` again, and ask on the new preview, never on the old one.
+4. **Finish.** Call `finish_work` with `apply: true` as the result says. When the change was finished anyway with tasks or gaps left open, the result lists them: offer a follow-up change holding them. If the user agrees, draft it as /bk-capture drafts a change, from its proposal, through the review; if not, they stay recorded with the archived change.
+
+Defects and ad-hoc units finish as above.

package/antigravity/skills/bk-impact/SKILL.md

@@ -5,19 +5,21 @@ description: "BuildKeel: Review what a change to an approved artifact affects: p
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
 
-When you ask a question with choices, the user may see nothing you wrote before it: whenever a step says to show something and then ask, put it in the question itself, as it is, and never say it was shown above.
+Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
 
-Review change impact in BuildKeel with the user. A suspect is a task, story, epic, bug or test case built against an older version of something that has changed since, in what it relies on. Deciding on a suspect is the user's choice: never record a decision they have not confirmed in this conversation.
+Review change impact in BuildKeel with the user. A suspect is a task, story, epic, defect or test case built against an older version of something that has changed since, in what it relies on. Deciding on a suspect is the user's choice: never record a decision they have not confirmed in this conversation.
 
 The user typed: whatever follows /bk-impact in the user's message (nothing, if they typed only /bk-impact)
 
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
 If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end as well.
 
 ## Choose what to review
 
 If the user named an artifact or test case above, use it.
 
-If the user typed nothing, ask straight away, before calling any tool: "What do you want to review?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+If the user typed nothing, ask straight away: "What do you want to review?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
 
 1. **Every suspect** (the default, listed first).
 2. **Type an ID:** an artifact with a new version in draft, to see what approving it would affect, or an artifact or test case to review on its own. If they pick this, ask for the ID.
@@ -33,14 +35,14 @@ Call the BuildKeel `impact` tool, with `id` if there is one. Show its result as
 
 For each suspect in the result, in order:
 
-1. Show what it is and what changed with the question in step 3, never in a choice's label or description. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. For a test case, read its plan with `query` (`view: "artifact"` and the plan's ID) and show the test case with the old and new text of what it covers. For a task, story, epic or bug, show its own text (`query`, `view: "artifact"`) with the old and new text of what changed above it. For a finished unit, show the commits and files its completion record lists.
+1. Show what it is and what changed, in the same reply as the question in step 3, never in a choice's label or description. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. For a test case, read its plan with `query` (`view: "artifact"` and the plan's ID) and show the test case with the old and new text of what it covers. For a task, story, epic or defect, show its own text (`query`, `view: "artifact"`) with the old and new text of what changed above it. For a finished unit, show the commits and files its completion record lists.
 2. Propose a decision, saying why in a sentence or two:
    - **Still valid** when the change does not affect what it says, builds or checks, such as a rewording, or a change to something it does not rely on in substance.
    - **Needs change** when what it says, builds or checks no longer matches the new text, such as a test case checking a 30-minute expiry when the criterion now says 15 minutes. For finished work, name the files that likely need to change.
-3. Ask the user to decide, with your tool for asking a question with choices: your proposal first, then the other decision, then **Skip it for now**.
+3. Ask the user to decide, in plain text at the end of that reply: your proposal first, then the other decision, then **Skip it for now**.
 4. Record only what the user chose: call `resolve_suspect` with the `id` and the `decision` (`still-valid` or `needs-change`), and show its result as it is.
-   - After **needs change**, offer to make the change now: read the draft it opened with `query`, change it with `save_draft`, show the user the result, and approve it with /bk-approve only when they confirm. For a unit already finished, its new version can be started again with /bk-start once approved, to change the code.
-   - For a **bug**, needs change on an open bug means changing its file with the user and saving it with `save_draft`: the save records the decision. For a finished bug, `resolve_suspect` records a new bug to check it: show it, and offer to start it with /bk-start.
+   - After **needs change**, offer to make the change now: read the draft it opened with `query`, show the change you would make, in full, and ask. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Save it with `save_draft` only once the user agrees, and approve it with /bk-approve only when they confirm. For a unit already finished, its new version can be started again with /bk-build once approved, to change the code.
+   - For a **defect**, needs change on an open defect means changing its file with the user, shown and agreed as above, and saving it with `save_draft`: the save records the decision. For a finished defect, `resolve_suspect` records a new defect to check it: show it, and offer to start it with /bk-build.
 
 ## Afterwards
 

package/antigravity/skills/bk-init/SKILL.md

@@ -5,42 +5,87 @@ description: "BuildKeel: Set up BuildKeel in this repository, with a new spec tr
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
 
-When you ask a question with choices, the user may see nothing you wrote before it: whenever a step says to show something and then ask, put it in the question itself, as it is, and never say it was shown above.
+Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
 
 Set up BuildKeel in this repository using the BuildKeel `manage` tool with `action: "init"`. Ask the user one question at a time, each with your recommendation, and wait for the answer before asking the next.
 
 The user typed: whatever follows /bk-init in the user's message (nothing, if they typed only /bk-init)
 
-Ask each question with your tool for asking a question with choices, if you have one, with your recommendation as the first choice, so the user can pick it with Enter, except where a step says to ask in prose. If the user typed nothing above, ask the first question straight away, before calling any tool.
+Ask each question with your tool for asking a question with choices, if you have one, with your recommendation as the first choice, so the user can pick it with Enter, except where a step says to ask in prose or in plain text.
 
-1. **Where the spec tree lives.** If the user gave a path above, use it as an existing spec tree and skip this question; if `manage` then reports there is no spec tree there, ask whether to create a new spec repository at that path instead. Otherwise ask:
-   - **In this repository**, in a `specs/` folder. Recommend this when this is the team's only repository, or when trying BuildKeel out.
-   - **An existing spec tree**, usually its own repository shared by several code repositories. Ask for its local path. If it is not cloned yet, tell the user to clone it first.
-   - **A new spec repository**, a repository of its own that several code repositories will share. Ask for its folder, outside this repository, such as `../specs`: a folder that does not exist yet, an empty folder, or an empty repository the user has cloned. Use `location: "new-repo"` with that `path`.
+## 1. Check the folder
 
-2. **The mode**, for a new spec tree only (an existing tree keeps its own, and `manage` says which). Ask, with a line on each:
-   - **Spec-driven** (the default, listed first): capability specs say how the system behaves, and each piece of work is a change to them, with no approvals or gates.
-   - **Full SDLC**: work goes through the team's stages, from business idea down, with approvals and gates.
+Before any question, call `manage` with `action: "init"` and nothing else. It only reads.
 
-   Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manage` below.
+- When it says the folder is not a git repository, ask before anything else, with your tool for asking a question with choices, so the user can pick an answer: **Run git init for me** (the default) or **Stop**. Only when the user agrees, call `manage` with `action: "init"`, `apply: true` and nothing else: it runs `git init`, so never run it yourself. Then say in one line that `git init` ran, before the next question. Ask nothing else until this is settled.
+- When it says the repository is already set up, show that, and stop.
 
-3. **Stamping their own commits.** Explain: while a unit of work is active, BuildKeel adds a line `BuildKeel-Unit: <id>` to commits the agent makes. If they agree, a git hook adds the same line to commits they make themselves, for example in a terminal. It changes nothing when no unit is active. Recommend yes. If the repository already manages its git hooks with another tool, nothing is installed and BuildKeel shows the lines to add.
+## 2. Where the spec tree lives
 
-4. Call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, `stampCommits` and, for a new tree, `mode`, without `apply`. Show the user the list it returns, as it is.
+If the user gave a path above, use it as an existing spec tree and skip this question; if `manage` then reports there is no spec tree there, ask whether to create a new spec repository at that path instead. Otherwise ask:
 
-5. **The process**, for a new Full SDLC spec tree. The list ends with the process as a table: each stage, its first ID and the documents it requires before work under it starts (by default a design document for an epic and a test plan for a story), then the bug and ad-hoc prefixes, each gate's mode, and how a task's own test plan is kept. Show it as it is. Then ask in prose, not with your tool for asking a question with choices, whether the team uses this process as it is, or how the team works: they can describe it in their own words, all at once, such as "we call stories features, every feature needs a design doc, epics need a security review, and the gates should only warn while we try it out".
-   - **Used as it is**: go on to the confirmation below.
-   - **Described in their words**: work out a `process` object from it, as in buildkeel.yaml's process section: stage names, a stage added between the business idea and the user story, the documents each stage requires, the team's own documents (say that each needs a template of its own later), ID prefixes, each gate's mode, and whether a task's own test plan is approved. Leave out what they did not mention: it keeps its default, and you ask nothing about it. Call `manage` again without `apply` with the `process`, and show the new table. Name anything they described that the process cannot express, such as a stage after the code is built, with the closest setting it has, such as the done gate's checks; never drop it silently, and never invent a setting.
+- **In this repository**, in a `specs/` folder. Recommend this when this is the team's only repository, or when trying BuildKeel out.
+- **An existing spec tree**, usually its own repository shared by several code repositories. Ask for its local path. If it is not cloned yet, tell the user to clone it first.
+- **A new spec repository**, a repository of its own that several code repositories will share. Ask for its folder, outside this repository, such as `../specs`: a folder that does not exist yet, an empty folder, or an empty repository the user has cloned. Use `location: "new-repo"` with that `path`.
 
-   Then ask, with your tool for asking a question with choices, showing the table. Never ask about a table the user has not seen. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
-   - **Set up with this process** (the default, listed first).
-   - **Change something.** Take in what they say, in their own words, work it into the `process`, call `manage` again without `apply`, and show the new table. Repeat until the user agrees.
-   - **Stop, and set up nothing.**
+## 3. The mode
 
-   A Spec-driven tree has no stages, and an existing spec tree keeps its own process: skip this question and ask the user to confirm the list.
+For a new spec tree only: an existing tree keeps its own, and `manage` says which. Ask, with a line on each:
 
-6. Only when the user confirms, call `manage` again with the same values (and the same `process`, if they adjusted it) and `apply: true`. Show the result as it is, including any lines the user must add to their hook manager, and, for a new spec repository, that it needs a remote and a push before others can use it.
+- **Spec-driven** (the default, listed first): capability specs say how the system behaves, and each piece of work is a change to them, with no approvals or gates.
+- **Full SDLC**: work goes through the team's stages, from business idea down, with approvals and gates.
 
-7. **The guide**, for a Spec-driven tree, new or existing: the result asks it. Ask **Guide me through my first change** (the default) or **Jump right in**, and record the answer with `manage`, `action: "guide"`, `guide: "on"` or `"off"`.
+Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manage` below.
+
+## 4. Stamping their own commits
+
+Explain: while a unit of work is active, BuildKeel adds a line `BuildKeel-Unit: <id>` to commits the agent makes. If they agree, a git hook adds the same line to commits they make themselves, for example in a terminal. It changes nothing when no unit is active. Recommend yes. If the repository already manages its git hooks with another tool, nothing is installed and BuildKeel shows the lines to add.
+
+Then call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, `stampCommits` and, for a new tree, `mode`, without `apply`. Show the list it returns, as it is, in your reply as normal text.
+
+## 5. The process, for a new Full SDLC spec tree
+
+Topics for this step, in this order:
+
+- **stages**: what each stage is called, and any stage added between the business idea and the user story, with where it sits.
+- **kinds**: whether a stage holds more than one kind of work, such as features and enhancements beside user stories. Each kind is numbered in its own sequence, has its own template and documents, and behaves as its stage does.
+- **prefixes**: the ID prefix and digits of each stage and kind, such as `US-001`, `FEAT-0001` or `PROJ-12`.
+- **documents**: what each stage and kind needs approved before work under it starts: a test plan, a design document, or a document of the team's own, such as a security review.
+- **test-plans**: whether a task's own test plan is recorded as it is saved (the default) or approved like any other plan.
+- **gates**: each gate's mode: block stops the action, warn lets it go ahead with a warning, off skips the check. The approve gate checks an artifact before it is approved: it follows its template, and its parent is approved. The start gate checks before work starts: everything above the unit is approved and not suspect, and its required documents are approved. The done gate checks before a unit is finished: its test cases pass. The lock gate checks before the agent edits approved versions and records.
+
+Work from the topics listed for this step. The user may answer in their own words, several topics at once or part of one. After each answer, say which topics it settled, with what you understood for each, and which are left; then ask the next one left, one topic per message. Where a topic has a default, list keeping it first, naming its actual value, and give examples where they help. Anything you work out that the user did not say is a proposal: ask it as that topic's question, with it as the default, and never use it without the user's answer. Ask about an unclear answer; name a conflicting one beside the earlier answer and ask which holds. Never guess. When every topic is settled, show all of it, as a review.
+
+The list shows the process as a table: BuildKeel's default, or the organization's when the tree takes its templates from one. Show it as it is, in your reply as normal text. Then ask in prose, not with your tool for asking a question with choices, whether the team uses this process as it is, or works differently and how: they can describe it in their own words, all at once or in part. If they only say it works differently, ask in one line how their team works.
+
+- **Used as it is**: every topic is settled. Pass `settled: ["all"]`, and go on to the review below.
+- **Works differently**: settle the topics their description covers, and ask each topic left, in the order above, with the default's actual value from the table as the first answer. Build `process` as in buildkeel.yaml's process section from what the user said or confirmed, nothing else. An added stage or kind needs a prefix: propose one, such as `FEAT` for feature, and say it is a suggestion they can change. When the user names a stage the default process does not have, ask whether it is a stage of its own, between two stages, or a kind of work beside one, such as features beside user stories, before you settle stages: a list of stage names in order does not say which. Name anything the process cannot express, such as a stage after the code is built, with the closest setting it has, such as the done gate's checks; never drop it silently, and never invent a setting. After each answer, call `manage` again without `apply`, with the same values as before, the `process` so far and every topic settled in `settled`: it lists the topics left.
+
+When no topic is left, call `manage` again without `apply` and show the whole table it returns, as it is, with its line on what each stage or kind the team added means, and ask whether to go ahead with it. Never ask about a table the user has not seen. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The answers: go ahead with this process (the default); change something, which you take in, then call `manage` again and show the whole table again, in the same layout; or stop, and write nothing.
+
+**Templates.** Once the user agrees the table, settle a template for each one the list says the process needs, one at a time, in the order listed. For each, ask: **Claude drafts it** (the default) or **I'll provide a file**. Nothing is left for later: if the user asks to leave one, say that the tree needs it to check what is drafted from it, and ask again with the same two answers.
+
+- **Claude drafts it**: call `get_template` for the closest built-in type: `story` for a kind at the user story stage, `epic` for a stage between the epic and the user story or a kind at one, `idea` for a kind at the business idea stage, `task` for a kind at the task stage, `design` for a document of the team's own. Change its `template:` line to the new type, and its description and sections to what the user said about it. Show it in full, and ask whether to use it or change something. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+- **I'll provide a file**: read the file the user names with your own tools, and pass its text. When `manage` says it fails the template check, show what is wrong, and ask: **Claude fixes it** (the default) or **Use another file**. Show a fixed template in full, and ask whether to use it. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+
+Pass each agreed template in `templates`, by type, and call `manage` again without `apply`: it checks each one. Nothing is written until every template the list names is given and passes.
+
+## 6. Numbering, for a new Spec-driven spec tree
+
+Topics for this step: **numbering**, how the tree's IDs read.
+
+Work from the topics listed for this step. The user may answer in their own words, several topics at once or part of one. After each answer, say which topics it settled, with what you understood for each, and which are left; then ask the next one left, one topic per message. Where a topic has a default, list keeping it first, naming its actual value, and give examples where they help. Anything you work out that the user did not say is a proposal: ask it as that topic's question, with it as the default, and never use it without the user's answer. Ask about an unclear answer; name a conflicting one beside the earlier answer and ask which holds. Never guess. When every topic is settled, show all of it, as a review.
+
+The list shows the tree's IDs, each with an example: changes, capability codes, requirements, scenarios, defects and ad-hoc units. Show them as they are, then ask in plain text whether to keep them (the default) or change them, with examples of other numbering, such as `RFC-0012` or `PROJ-12` for changes, or `AUTH-REQ1` for requirements. A change of change, defect or ad-hoc prefix or digits goes in `process`, such as `{ change: { prefix: RFC, width: 4 } }`; a change of the letters in requirement or scenario IDs goes in `markers`. Call `manage` again without `apply` with them, show the IDs it returns, and ask the user to confirm them. Pass `settled: ["numbering"]` once they keep or confirm the numbering.
+
+## 7. Confirm and set up
+
+Show the last list `manage` returned in full and ask whether to set up with it, change something or stop. An existing spec tree keeps its own process and numbering: just ask the user to confirm the list. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+
+Only when the user confirms, call `manage` again with the same values (the same `process`, `settled`, `templates` and `markers`, when there are any) and `apply: true`. Show the result as it is, including any lines the user must add to their hook manager, and, for a new spec repository, that it needs a remote and a push before others can use it.
+
+## 8. The guide
+
+For a Spec-driven tree, new or existing, the result asks it. Ask **Guide me through my first change** (the default) or **Jump right in**, and record the answer with `manage`, `action: "guide"`, `guide: "on"` or `"off"`.
 
 Do not create or edit any BuildKeel files yourself; the `manage` tool does all of it. If `manage` reports a problem, show it with its fix and ask how to continue.