buildkeel 0.3.0 → 0.5.0

package/antigravity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildkeel",
-  "version": "0.3.0",
+  "version": "0.5.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.5.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

@@ -9,24 +9,26 @@ BuildKeel keeps requirements, tests and code connected. Follow these rules in an
 
 Talk with the user as you would without BuildKeel, as a thinking partner, the way BuildKeel's session report describes: explain the options, trade-offs and pitfalls before you ask, ask in prose, recommend only what the evidence supports, and never push toward a plan or a BuildKeel step. Discussing ideas, weighing options, talking through architecture and reading code are free: leave BuildKeel's artifacts, stages, IDs and commands out of it.
 
-BuildKeel comes in when the user runs a BuildKeel command, or when you are about to change a file (see "Before changing code"). Once that is done, the conversation is free again. Start a BuildKeel command only when the user types it, except /bk-status and /bk-stats, which you may run on your own.
+BuildKeel comes in when the user runs a BuildKeel command, or when you are about to change a file (see "Before changing code"). Once that is done, the conversation is free again. Start a BuildKeel command only when the user types it, except /bk-status, /bk-settings and /bk-stats, which only read and which you may run on your own.
 
 ## The spec tree
 
-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.
+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. When the user changes behavior that looked wrong while building, the spec changes first: in Full SDLC, the next versions of everything it affects, approved before you build on them; in a Spec-driven tree, through the open change. /bk-build describes each path.
+
+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
 
-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:
+Every code change belongs to the active unit of this working tree: a task, a story built without tasks, a defect 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.
+When the user reports a defect, or a test fails in work that was finished, offer to record a defect with /bk-new defect, which sorts a report first. Call `get_context` when you need the unit's requirements, design and test cases again.
 
 Change files with your file editing tools, never through the shell (such as `sed -i`, `echo >` or `mv` over a file): BuildKeel checks each edit made with those tools, and an edit made around them escapes its checks.
 
@@ -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 defect's regression test carries the defect's ID, such as `[DEF-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,48 +5,53 @@ 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.
+**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, 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
 
 If the user named one artifact above, approve it as below. If they named several, approve them as a set (see "A set in one review").
 
-If the user typed nothing, ask straight away, before calling any tool: "What do you want to approve?" 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 approve?" 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 drafts from this conversation, in one review** (the default, listed first): offer this only when drafts were saved in this conversation, such as by /bk-capture, and name them in the choice.
 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,139 @@
 ---
 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, defect 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.
+**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.
 
-## Choose what to 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 in place of "Build a single unit" and "Build what is ready under a parent".
 
-If the user named a story, an epic or another parent above, build the ready units under it.
+## What to build
 
-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:
+What the user typed decides 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.
+- **A unit's ID**, such as a task, a story built without tasks, a defect, 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: "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.
 
-## List it and ask once
+### Words in place of an ID
 
-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.
+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 with /bk-new defect 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 defects 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, 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.
 
-## At the end
+## When a run stops
 
-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.
+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;
+- when agreed behavior looks wrong, as "Behavior that looks wrong" says.
 
 Do not create or edit spec tree files yourself: the BuildKeel tools write every record.
 
+## Behavior that looks wrong
+
+When what was agreed looks wrong while you build (a requirement, an acceptance criterion or a test case), stop and ask, whether or not the build started with this command: name it by ID, and say why it looks wrong. Offer **Keep it as agreed** and **Change it**, your recommendation first. Never build something else, and never edit the spec, without the answer.
+
+- **Kept:** build it as agreed, and do not raise it again in this build.
+- **Changed:** change the spec first. Save the whole changed story (or task) with `save_draft`, which opens its next version, and show it as any draft. 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. Then call the BuildKeel `impact` tool with its `id`: the preview names what the new version would make suspect, such as tasks and test plans. Draft the next version of each that must change too, and offer the set for approval with /bk-approve. Build nothing more on the unit until the set is approved; when the start gate is set to warn and the user says to carry on, go on, saying that you build against versions not yet approved. Once the set is approved, the unit is suspect: with the user's agreement, record that it now builds against the new versions with `resolve_suspect` (`decision: "still-valid"`), and go on against them.
+- **In code nothing describes yet** (`query` with `view: "describes"` finds no artifact): draft its version 0 first, describing the code as it is, as /bk-new does, then the change on top of it.
+
 ## In a Spec-driven tree
 
-A run builds one change's tasks, in order, on the change's branch.
+The units are open changes, defects and ad-hoc units, and no gate runs. Defects 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.
+   - **Behavior that looks wrong** stops the run too: name the requirement or scenario and why, and ask **Keep it as agreed** or **Change it**, your recommendation first. Kept: build it as agreed. Changed: a requirement of this change's own spec change is edited in place, as the next point says, with the follow-on edits to the proposal, design and tasks. A requirement as an archived change left it is changed through this change, with a spec change modifying it (the default), or through a separate change drafted with /bk-capture, as the user prefers. In code nothing describes yet, document it first as version 0 of a capability spec, then change it.
+   - **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.