buildkeel 0.3.0 → 0.4.0

package/antigravity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildkeel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": true,
   "homepage": "https://buildkeel.ai",
   "license": "SEE LICENSE IN LICENSE",

package/antigravity/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "buildkeel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "BuildKeel keeps requirements, tests and code connected, from the business idea down to the commit, and gives the agent that full picture before it writes anything.",
   "homepage": "https://buildkeel.ai"
 }

package/antigravity/rules/buildkeel.md

@@ -15,6 +15,8 @@ BuildKeel comes in when the user runs a BuildKeel command, or when you are about
 
 Read and change requirements, stories, tasks and test plans only through the BuildKeel tools: `query`, `get_context` and `get_template` to read, `save_draft` to write, `approve` only when the user confirms. Pass `workspace`, the absolute path of this project's folder, on every call to a BuildKeel tool. Never create or edit files in the spec tree yourself. Approved versions and records (`versions/`, `approvals/`, `completions/`, `repins/`) are never edited; to change an approved artifact, save the whole changed file with `save_draft`, which opens its next version. When BuildKeel reports suspects, offer to review them with /bk-impact; whether each is still valid or needs change is the user's decision.
 
+Nothing goes into the spec tree unseen. Before you save anything to it, show what changes, in full, in your reply, and ask in plain text at its end, never inside your question tool. Agreement saves it; anything else is feedback: discuss it, then list each point with how it was addressed, show the final version, and save only once the user agrees. When work would change a document the user agreed, say which, what and why, and take it through the same review, one edit at a time. Never add, change or remove a requirement, criterion, scenario or task on your own initiative. Report each tick in a line; do not ask about ticks.
+
 A team can rename the stages of its process and add stages of its own. When it has, BuildKeel's session report lists the stages as the team names them: use those names with the user, in each command's help, its questions and its output. A renamed stage is still that stage to BuildKeel (a "feature" is a user story), and the tools accept either name.
 
 ## Before changing code
@@ -22,8 +24,8 @@ A team can rename the stages of its process and add stages of its own. When it h
 Every code change belongs to the active unit of this working tree: a task, a story built without tasks, a bug or an ad-hoc unit. If there is none, before changing any file, ask the user how to go on, with your tool for asking a question with choices if you have one, recommending the choice that fits:
 
 1. **Capture what we discussed**: the user runs /bk-capture, which turns the conversation into the artifacts the team's process needs, to approve and then build. You cannot start it yourself: if they choose it, ask them to run it, and change nothing until a unit is active. Recommend it when the conversation shaped new work.
-2. **Start the unit it belongs to** with /bk-start <ID>, when the change is part of planned work.
-3. **Record it as an ad-hoc unit** with a short title you propose, and start it as /bk-adhoc does: for a small change that belongs to no planned work.
+2. **Start the unit it belongs to** with /bk-build <ID>, when the change is part of planned work.
+3. **Record it as an ad-hoc unit** with a short title you propose, and start it as /bk-build does for a description: for a small change that belongs to no planned work.
 4. **Go ahead without a unit.** Only the user can choose this: then call the BuildKeel `manage` tool with `action: "untracked"` first, and tell them the change will belong to no unit.
 
 When the user reports a defect, or a test fails in work that was finished, offer to record a bug with /bk-new bug. Call `get_context` when you need the unit's requirements, design and test cases again.
@@ -46,7 +48,7 @@ If the message has other trailer lines, such as `Co-Authored-By`, keep them all
 
 ## Tests
 
-When you write a test for a test case, put the test case's ID in square brackets in the test's name, such as `it("emails a reset link [US-012-TC3]", ...)`. A test may carry several IDs. The test cases that apply to the unit are in its context: its own plan's and its story's. A bug's regression test carries the bug's ID, such as `[BUG-005]`, and must fail without the fix.
+When you write a test for a test case, put the test case's ID in square brackets in the test's name, such as `it("emails a reset link [US-012-TC3]", ...)`. A test may carry several IDs, one per bracket: `[US-012-TC3] [US-012-TC4]`; a bracket holding several tags nothing. The test cases that apply to the unit are in its context: its own plan's and its story's. A bug's regression test carries the bug's ID, such as `[BUG-005]`, and must fail without the fix.
 
 A test written before BuildKeel may be matched to a test case instead of tagged; the unit's context lists those matches. When you change such a test, add its test case's ID to its name too; BuildKeel drops the match when the unit is finished.
 
@@ -63,10 +65,10 @@ Results are local to this working tree. A result goes stale when the code or the
 
 ## Finishing
 
-When the unit's work is committed and its test cases pass, finish it with /bk-done. Finishing writes a permanent completion record, so it is the user's decision: show what it will record and ask first.
+When the unit's work is committed and its test cases pass, finish it with /bk-done. Before you push, open a pull request or merge while a unit is active, tell the user it is not finished and to run /bk-done before merging, then go ahead. Finishing writes a permanent completion record, so it is the user's decision: show what it will record and ask first.
 
 ## Calling BuildKeel's tools
 
 BuildKeel's tools (`query`, `get_context`, `save_draft` and the rest) are on the MCP server named `buildkeel`. Call each one with your tool for calling an MCP tool (`call_mcp_tool`), with `ServerName` `buildkeel`, the tool's name as `ToolName`, and its arguments, `workspace` included. Read a tool's description first if you need its arguments. Never start BuildKeel's server or programs yourself, from a terminal or a script, and never read or write the spec tree's files to work around a tool; if a tool cannot be reached, tell the user. If you have no `call_mcp_tool` tool, BuildKeel's server is not connected to this conversation, which can happen in the first conversation after Antigravity opens: tell the user to start a new conversation, and do nothing else for the request.
 
-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.

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

@@ -5,13 +5,16 @@ description: "BuildKeel: Approve a draft or a new version after checking it, or
 
 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.
 
 Help the user approve a BuildKeel artifact. Approval is the user's decision: never approve anything they have not confirmed in this conversation.
 
 The user typed: whatever follows /bk-approve in the user's message (nothing, if they typed only /bk-approve)
 
-If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, it has nothing to approve: call `approve` once and show its answer as it is.
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, it has no approvals, and /bk-approve agrees what is under review:
+
+- **A document is under review** in this conversation, shown in full and waiting for the user's answer, such as a spec change during /bk-capture or a requirement while building: take /bk-approve as the user's agreement, as a reply of "approved" would be. Save it as that review says, and go on to the next step. Nothing is frozen: the change stays editable until it is finished.
+- **Nothing is under review:** call `approve` once, without `apply`, and show its answer as it is. It writes nothing.
 
 ## Choose what to approve
 
@@ -23,30 +26,30 @@ If the user typed nothing, ask straight away, before calling any tool: "What do
 2. **Show what is ready to approve** (the default when there are no drafts from this conversation).
 3. **Type an artifact ID.** If they pick this, ask for the ID.
 
-If they pick "Show what is ready", call the BuildKeel `query` tool with `view: "drafts"` and ask which to approve, showing its result as it is: what is ready to approve, and what is not ready yet with the reason. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Offer the ready ones as choices with the one you recommend first; several can be approved as a set. If nothing is ready, say what is blocking the drafts and stop.
+If they pick "Show what is ready", call the BuildKeel `query` tool with `view: "drafts"` and show its result as it is: what is ready to approve, and what is not ready yet with the reason. Then ask which to approve. 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. Offer the ready ones with the one you recommend first; several can be approved as a set. If nothing is ready, say what is blocking the drafts and stop.
 
 ## A set in one review
 
 1. Call the BuildKeel `approve` tool with `ids` set to every artifact in the set, without `apply`. A version 0, which describes code as it was before BuildKeel, is named with `@v0`, such as `US-draft-k3x9@v0`; when the change built on it is a new version of the same artifact, the set holds both, `US-draft-k3x9@v0` and `US-draft-k3x9`, and version 0 is approved first. It shows the whole set in the order it will be approved, parents and their documents first, with what each will become and anything that would not pass, and why. Show it as it is.
-2. Ask, with your tool for asking a question with choices, showing the set as `approve` gave it: **Approve them** (the default; if some would not pass, the rest are approved and those stay drafts with what needs them), **Fix what would not pass first** (then fix each with `save_draft`, one at a time with the user, and check the set again), or **Stop**. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+2. Ask, with the set in your reply as `approve` gave it: **Approve them** (the default; if some would not pass, the rest are approved and those stay drafts with what needs them), **Fix what would not pass first** (then fix each one at a time with the user: show the fix, and save it with `save_draft` once they agree; then check the set 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.
 3. Only when the user confirms, call `approve` again with the same `ids` and `apply: true`. Show the result as it is: it opens with what is now approved and what can start, then each approval, each its own record and commit.
 
 ## One artifact
 
 1. Call `query` with `view: "artifact"` and the ID, and show the user the artifact so they know what they are approving. For a new version of an approved artifact, also call `query` with `view: "artifact"`, the ID and `version` set to the approved version, and say what changed since then.
 2. Call the BuildKeel `approve` tool with the `id` and without `apply`. It runs the approve gate and does not write anything.
-   - If it is refused, show every failing check with its fix, as it is. Offer to fix the draft (save the fix with `save_draft`, passing the draft's `id`) or to approve the parent first. Do not approve anything else in its place without asking.
-   - Otherwise, show what approval will do (the permanent number it will get, references that change, the commit) and ask the user to confirm. For a version 0, say that it describes the code as it was before BuildKeel and what it leaves empty: approving it means a person has read it.
+   - If it is refused, show every failing check with its fix, as it is. Offer to fix the draft (show the fix, and once the user agrees, save it with `save_draft`, passing the draft's `id`) or to approve the parent first. Do not approve anything else in its place without asking.
+   - Otherwise, show what approval will do (the permanent number it will get, references that change, the commit) 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. For a version 0, say that it describes the code as it was before BuildKeel and what it leaves empty: approving it means a person has read it.
 3. Only when the user confirms, call `approve` again with the same `id` and `apply: true`. Show the result, which opens with what was approved: the permanent ID, the files written, the commit, and whether it was pushed. If the number is pending because the spec repo's remote could not be reached, say so plainly: the approval is recorded, work on it cannot start until it has its number, and the number is assigned the next time the remote can be reached.
 
 ## Its documents
 
-If the result says a task's own test plan was recorded with it, say so in a line: it needs no approval. If the result says the approved artifact has a document with a draft waiting, such as its test plan or design document, tell the user and ask whether to approve it now. If they agree, go through the same steps for the document's ID: show it, check it without `apply`, and approve it only after they confirm. Each approval is its own commit.
+If the result says a task's own test plan was recorded with it, say so in a line: it needs no approval. If the result says the approved artifact has a document with a draft waiting, such as its test plan or design document, tell the user and ask, in plain text, whether to approve it now. If they agree, go through the same steps for the document's ID: show it, check it without `apply`, and approve it only after they confirm. Each approval is its own commit.
 
 ## Afterwards
 
 Call `query` with `view: "drafts"` and show what is still waiting for approval, ready or not, as it is.
 
-If the approval result said approvals are not pushed, remind the user to push the spec repo when they are ready to share them. Then suggest the next step: approving something that is now ready, starting a unit that is ready with /bk-start, or building everything ready with /bk-build.
+If the approval result said approvals are not pushed, remind the user to push the spec repo when they are ready to share them. Then suggest the next step: approving something that is now ready, building a unit that is ready, or everything ready under a parent, with /bk-build.
 
 Do not create or edit spec tree files yourself: `approve` and `save_draft` do all writing, and approved versions and approval records are never edited.

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

@@ -1,61 +1,127 @@
 ---
 name: bk-build
-description: "BuildKeel: Build what is ready: start, build, test and finish each ready unit in turn, after one confirmation. Run as /bk-build [parent ID], e.g. US-001 to build its tasks, or EP-01; everything ready when left out, only when the user types it."
+description: "BuildKeel: Start a unit and build it: a task, story, bug or change by its ID, the ready units under a parent, or a small change described in words. Run as /bk-build [an ID, a parent's ID, or what to change in words], e.g. TK-001, US-001, or \"fix the footer link\", only when the user types it."
 ---
 
 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.
 
-Build every unit that is ready, one after another, with the user's one confirmation up front. Each unit still goes through its own start gate, gets its own branch, commits and completion record, and is tested before it is finished.
+Start a BuildKeel unit and build it with the user. Every code change belongs to exactly one unit, and the unit's context tells you what to build. Starting checks the unit is ready, switches to its branch and loads its context; the user then chooses how far to go: build everything, the next one only, or set it up and work together.
 
 The user typed: whatever follows /bk-build in the user's message (nothing, if they typed only /bk-build)
 
-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 instead of the sections before it.
+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 in place of "Build a single unit" and "Build what is ready under a parent".
 
-## Choose what to build
+## What to build
 
-If the user named a story, an epic or another parent above, build the ready units under it.
+What the user typed decides it:
 
-If the user typed nothing, ask straight away, before calling any tool: "What should I build?" Offer the choices with your tool for asking a question with choices, if you have one:
+- **A unit's ID**, such as a task, a story built without tasks, a bug, an ad-hoc unit or a change: start it and build it, as "Start it" and the sections after it say.
+- **A parent's ID**, such as a story built through tasks or an epic: build the units ready under it, as "Build what is ready under a parent" says.
+- **Words**, such as "fix the footer link": see "Words in place of an ID".
+- **Nothing:** ask straight away, before calling any tool: "What should I build?" Offer the choices with your tool for asking a question with choices, if you have one:
+  1. **The active unit** (the default, listed first), named with its ID and title: offer it only when this working tree has one.
+  2. **Show what can be started** (the default when there is no active unit). Call `query` with `view: "startable"` and show its result as it is. Then ask which to build, the ready ones offered with the one you recommend first, and, in Full SDLC, **Everything that is ready** as a choice too. If nothing is ready, say what is in the way and suggest the next step, such as approving with /bk-approve, and stop.
+  3. **Type an ID or describe the change.** If they pick this, ask for it.
 
-1. **Everything that is ready** (the default, listed first).
-2. **Only what is under one story or epic: type its ID.** If they pick this, ask for the ID.
+### Words in place of an ID
 
-## List it and ask once
+Call `query` with `view: "startable"`, and in a Spec-driven tree also with `view: "changes"`. Compare the words with the titles of the units that can start and of the open changes, ignoring case and counting the words they share. Then ask, with your tool for asking a question with choices:
+
+- **When a title matches:** **Build <ID> "<title>"** for the best match (the default), then any other close match, then **Record a new ad-hoc unit "<title>"**, with the title you propose from the words. Record no ad-hoc unit unless the user picks it.
+- **When nothing matches:** **Record the ad-hoc unit "<title>" and build it** (the default), with the title you propose, or **Type another description**.
+
+The title says what changes in a few words, such as "Fix the footer link". If the change is a defect in work that was planned and tested, suggest recording it as a bug with /bk-new bug instead, and go on as the user prefers.
+
+### Recording an ad-hoc unit
+
+An ad-hoc unit needs no approval: it gets its permanent ID straight away, its commits carry that ID, and it is finished with /bk-done like any other unit. Call the BuildKeel `save_draft` tool with `type: "adhoc"` and this content, with the title and a sentence or two saying what changes and why:
+
+```
+---
+id: {{id}}
+title: <title>
+---
+
+## Description
+
+<what changes and why>
+```
+
+It gives the unit its ID and commits it in the spec repo. If the number counter cannot be reached, the ID ends in letters and digits instead of a number; it is still permanent. Then start it with the new ID.
+
+## Start it
+
+If the unit is already the active unit in this working tree, it is not started again: call `get_context` for it and go on from there. Otherwise call the BuildKeel `start_work` tool with the unit's `id`.
+
+- **Refused by the start gate:** show every failing check with its fix, as it is. Offer the fix that comes first, such as approving the story or its test plan. Do not start anything else in its place without asking.
+- **Uncommitted changes:** show the files it lists. If it says some of them set BuildKeel up (such as `.buildkeel.yaml` or the spec tree's `buildkeel.yaml`), offer first **Commit them as setting BuildKeel up** (the default): commit only those files, with a message such as "Set up BuildKeel" and no `BuildKeel-Unit` line, then deal with any other files as below, and call `start_work` again. Every other change must belong to one unit, so ask the user what to do with them, offering these choices:
+  1. **Commit them to the active unit** (the default, when there is one). Show what will be committed, commit it with the message ending in `BuildKeel-Unit: <active unit ID>`, then call `start_work` again. When there is no active unit, ask which unit the changes belong to instead.
+  2. **Set them aside.** List the files again and ask for an explicit yes. Then run `git stash push --include-untracked -m "BuildKeel: set aside before starting <ID>"`, tell the user they can bring the changes back with `git stash pop`, and call `start_work` again.
+  3. **Leave them, and do not start.**
+
+  Never discard changes any other way.
+- **Started:** tell the user the branch and anything it warned about, such as a spec tree that is behind its remote.
+
+Keep the context in mind for the rest of the work, and call `get_context` again if you lose track of it. Do not create or edit spec tree files yourself.
+
+## Build a single unit
+
+Sum up the context: what to build, the acceptance criteria and the test cases, by ID. Then ask how to go on, with that summary in the 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. **Build it** (the default).
+2. **Set it up and work together**: build nothing yet; ask the user how to begin.
+
+To build it: write the code and the tests for its test cases, each test named with its test case ID in square brackets, one ID per bracket. Commit as you go, each message ending with `BuildKeel-Unit: <ID>`, and change files only with your file editing tools. Run the tests with a JUnit XML report and record it with the BuildKeel `test_results` tool. The run stops to ask, as "When a run stops" says. When the work is committed and its test cases pass, tell the user they can finish it with /bk-done; do not finish it yourself.
+
+## Build what is ready under a parent
+
+Each unit still goes through its own start gate, gets its own branch, commits and completion record, and is tested before it is finished.
 
 Call the BuildKeel `query` tool with `view: "startable"`. Take the units ready to start, at the lowest level: tasks, and stories that have no tasks (with a parent named, only those under it). Leave out bugs and ad-hoc units unless the user asks for them. Order them by parent, then by ID, so that a story's tasks are built in order.
 
 If nothing is ready, show what is waiting and why, as `query` gave it, suggest the next step (such as approving with /bk-approve), and stop.
 
-Otherwise show the list in order, and say how the run goes: each unit is started, built, tested and finished in turn; each gets its own branch, stacked on the one before so later units build on the earlier ones' code; and the run stops to ask when a gate refuses, a test fails and cannot be fixed, or a requirement is unclear. Then ask, with your tool for asking a question with choices, showing the list and how the run goes. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+Otherwise show the list in order, and say how the run goes: each unit is started, built, tested and finished in turn; each gets its own branch, stacked on the one before so later units build on the earlier ones' code; and the run stops to ask when a gate refuses, a test fails and cannot be fixed, or a requirement is unclear. Then ask, with the list and how the run goes 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. **Build them** (the default).
-2. **Change the list.** Take in what they say and show the list again.
-3. **Stop.**
+1. **Build them all** (the default).
+2. **Build the next one only**: the first unit is started, built, tested and finished, then the run stops and names the next.
+3. **Set it up and work together**: start the first unit, build nothing, and ask the user how to begin.
 
-## Build each unit in turn
+Any other answer, such as a change to the list, is taken in, and the list is shown again.
 
 For each unit, in order:
 
 1. **Start it.** Call `start_work` with its `id` and `run: true`; from the second unit on, also pass `stack: true`, so its branch starts from the branch of the unit just finished. If the start is refused, or there are uncommitted changes, stop the run: show the result as it is and ask the user how to go on.
-2. **Build it.** Work from the context `start_work` returned: the unit, its requirements, its design, and its test cases. Write the code and the tests for its test cases, each test named with its test case ID in square brackets. Commit as you go, each message ending with `BuildKeel-Unit: <ID>`, and change files only with your file editing tools. When a task needs a test case its own test plan does not have, add it, with `{{new}}` for its number and its `covers` line, and save the whole plan with `save_draft` and the plan's `id`: unless the result says the plan waits for approval, it is recorded at once as its next version, and the run goes on.
-3. **Test it.** Run the tests with a JUnit XML report and record it with the BuildKeel `test_results` tool. When a test fails, fix the code or the test and run them again. If it still fails after a real attempt, stop the run: name the failing test case and what you tried, and ask the user how to go on.
-4. **When a requirement is unclear** (two readings, a missing case, a conflict with the code), stop the run and ask the user one question, with your recommendation. Never guess a requirement.
-5. **Finish it.** Call `finish_work` without `apply`. If it says the tests have no current result, run them again and record them, once. If it is refused for any other reason, or lists commits without a `BuildKeel-Unit` line, stop the run and show it. Otherwise call `finish_work` with `apply: true`: the user's confirmation of the run covers finishing each unit that passes its done gate.
-6. Say in a line what was finished: the unit, its commits, its test cases passing, and its completion record. Then go on to the next unit.
+2. **Build it.** Work from the context `start_work` returned: the unit, its requirements, its design, and its test cases. Write the code and the tests for its test cases, each test named with its test case ID in square brackets, one ID per bracket. Commit as you go, each message ending with `BuildKeel-Unit: <ID>`, and change files only with your file editing tools. When a task needs a test case its own test plan does not have, the plan the user agreed changes: show the test case you would add, with its `covers` line and why it is needed, and ask before saving 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. Once the user agrees, add it with `{{new}}` for its number and save the whole plan with `save_draft` and the plan's `id`: unless the result says the plan waits for approval, it is recorded at once as its next version, and the run goes on.
+3. **Test it.** Run the tests with a JUnit XML report and record it with the BuildKeel `test_results` tool. When a test fails, fix the code or the test and run them again.
+4. **Finish it.** Call `finish_work` without `apply`. If it says the tests have no current result, run them again and record them, once. If it is refused for any other reason, or lists commits without a `BuildKeel-Unit` line, stop the run and show it. Otherwise call `finish_work` with `apply: true`: the user's choice to build covers finishing each unit that passes its done gate.
+5. Say in a line what was finished: the unit, its commits, its test cases passing, and its completion record. Then go on to the next unit.
 
-## At the end
+At the end, show a table of the run: each unit, its branch, its commits, and its completion record, or where the run stopped and why. The last branch holds the whole run: say that one pull request from it reviews all of it, or that each branch can have its own pull request, each based on the previous one and merged in order. If the completion records are not pushed, remind the user to push the spec repo.
 
-Show a table of the run: each unit, its branch, its commits, and its completion record, or where the run stopped and why. The last branch holds the whole run: say that one pull request from it reviews all of it, or that each branch can have its own pull request, each based on the previous one and merged in order. If the completion records are not pushed, remind the user to push the spec repo.
+## When a run stops
+
+A run stops and asks the user:
+
+- when a gate refuses: show the result as it is;
+- when a test fails and still fails after a real attempt to fix it: name the failing test case and what you tried, and ask how to go on;
+- when a requirement is unclear (two readings, a missing case, a conflict with the code): ask one question, with your recommendation. Never guess a requirement.
 
 Do not create or edit spec tree files yourself: the BuildKeel tools write every record.
 
 ## In a Spec-driven tree
 
-A run builds one change's tasks, in order, on the change's branch.
+The units are open changes, bugs and ad-hoc units, and no gate runs. Bugs and ad-hoc units are built as "Build a single unit" says. A change is built task by task, in order, on the change's branch:
+
+1. **The change.** Start it as "Start it" says, unless it is already active: `start_work` starts it, or says which working tree on this machine already holds it. If nothing can be started, suggest drafting a change with /bk-capture.
+2. **Choose how to build.** Sum up the change in a few lines, with its title: what the proposal changes, and the requirements it adds, modifies or removes by ID. Show its unticked tasks in order, each with how it is verified, and say how the run goes: each task is built, tested and ticked in turn, and the run stops to ask when a test fails and cannot be fixed, a requirement is unclear, or what was agreed would change. Then ask, with the list 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. **Build them all** (the default).
+   2. **Build the next one only**: build and tick the first unticked task, then stop and name the next.
+   3. **Set it up and work together**: build nothing; ask the user how to begin.
 
-1. **The change.** If the user named a change, start it with `start_work` unless it is already active. If they typed nothing and a change is active, build it. Otherwise ask, straight away, which change to build, offering **Show what can be started** (the default) and **Type a change ID**, then start the one they pick.
-2. **Ask once.** Call `get_context` for the change. Show its unticked tasks in order, each with how it is verified, and say how the run goes: each task is built, tested and ticked in turn, and the run stops to ask when a test fails and cannot be fixed or a requirement is unclear. Then ask, showing the list. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Build them** (the default), **Change the list**, **Stop**.
-3. **Each task in turn.** Write the code and its tests, each test named with the scenario ID it checks in square brackets, such as `[AUTH-R3-S1]`. Commit as you go, each message ending with `BuildKeel-Unit: <change ID>`, and add `BuildKeel-Task: <task number>` on the next line when a commit does exactly that one task. Run the tests with a JUnit XML report and record it with `test_results`. Once the task's stated verification passes, tick it: save the task list with `save_draft`, type `tasks` and the change's `id`, with its box changed to `[x]`. A failing test you cannot fix, or an unclear requirement, stops the run with one question and your recommendation.
-4. **At the end**, show each task with its commits and whether it is ticked, or where the run stopped and why. Do not finish the change yourself: offer /bk-done, which reviews the code against the change's requirements before it is archived.
+   When every task is ticked already, say so instead, and that the user can run /bk-done to finish the change.
+3. **Each task in turn.** Write the code and its tests, each test named with the scenario ID it checks in square brackets, one ID per bracket, such as `[AUTH-R3-S1]`. Commit as you go, each message ending with `BuildKeel-Unit: <change ID>`, and add `BuildKeel-Task: <task number>` on the next line when a commit does exactly that one task. Run the tests with a JUnit XML report and record it with `test_results`. Once the task's stated verification passes, tick it with `save_draft`, `type: "tasks"`, the change's `id` and `tick` set to its number, such as `["2.3"]`, and say so in a line, with the progress the result gives. Never ask before ticking. A failing test you cannot fix, or an unclear requirement, stops the run, as "When a run stops" says.
+   - **A change to what was agreed** stops the run too: a requirement or scenario to add, change or drop, a task's wording, or a task to add or remove. Say which file, what changes and why, show the change 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. Before adding a requirement to a change with more than half its tasks ticked, ask once first whether it belongs in this change or a new one, and draft nothing until the user answers. Save it only once the user agrees, then go on: one requirement with `save_draft`, `type: "spec-change"`, the change's `id`, its `capability` and `requirement` (`id` and `content` to replace it, `section` and `content` to add one, `id` and `drop` to take one out); a task list's wording as the whole file. Never change the spec on your own initiative, not even to make your own check pass.
+4. **At the end**, show each task with its commits and whether it is ticked, or where the run stopped and why. When the last tick's result says every task is done, pass on that the user can run /bk-done to finish the change. Do not finish the change yourself: /bk-done reviews the code against the change's requirements before it is archived.

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

@@ -5,7 +5,7 @@ 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.
 
@@ -13,6 +13,16 @@ The user typed: whatever follows /bk-capture in the user's message (nothing, if
 
 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):
@@ -24,10 +34,10 @@ 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.
@@ -54,11 +64,11 @@ Show the plan as a table, top down, each row with a one-line purpose, and say wh
 | 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 |
 
-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:
+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 +92,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 +100,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
 
@@ -124,9 +134,14 @@ Version 0 describes what the code does today, as if BuildKeel had been used from
 
 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 +150,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,7 +5,7 @@ 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.
 
@@ -31,17 +31,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 bug that is not a defect
 
-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 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. 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 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.
 
 ## 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).
@@ -57,10 +57,20 @@ Only when the user confirms, call `finish_work` again with `apply: true` (and th
 
 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.
+
+Bugs and ad-hoc units finish as above.

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

@@ -5,7 +5,7 @@ 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.
 
@@ -33,14 +33,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 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.
 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 **bug**, needs change on an open bug 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 bug, `resolve_suspect` records a new bug to check it: show it, and offer to start it with /bk-build.
 
 ## Afterwards