buildkeel 0.2.0 → 0.4.0

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

@@ -1,11 +1,11 @@
 ---
 name: bk-done
-description: "BuildKeel: Finish the active unit, or a story or epic once everything under it is done: check its tests pass, then write its completion record. Run as /bk-done [ID], e.g. TK-001, or US-001 for a story built through tasks; the active unit when left out."
+description: "BuildKeel: Finish the active unit, or a story or epic once everything under it is done: check its tests pass, then write its completion record. Run as /bk-done [ID], e.g. TK-001, or US-001 for a story built through tasks; the active unit when left out, 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.
 
 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

@@ -1,11 +1,11 @@
 ---
 name: bk-impact
-description: "BuildKeel: Review what a change to an approved artifact affects: preview a new version before approving it, or decide on each suspect with the user. Run as /bk-impact [ID], e.g. US-001 to preview its new version in draft, or US-001-TC2 to review one suspect; every suspect when left out."
+description: "BuildKeel: Review what a change to an approved artifact affects: preview a new version before approving it, or decide on each suspect with the user. Run as /bk-impact [ID], e.g. US-001 to preview its new version in draft, or US-001-TC2 to review one suspect; every suspect when left out, 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.
 
 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
 

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

@@ -1,17 +1,17 @@
 ---
 name: bk-init
-description: "BuildKeel: Set up BuildKeel in this repository, with a new spec tree or an existing one. Run as /bk-init [path of an existing spec tree]."
+description: "BuildKeel: Set up BuildKeel in this repository, with a new spec tree or an existing one. Run as /bk-init [path of an existing spec tree], 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.
 
 Set up BuildKeel in this repository using the BuildKeel `manage` tool with `action: "init"`. Ask the user one question at a time, each with your recommendation, and wait for the answer before asking the next.
 
 The user typed: whatever follows /bk-init in the user's message (nothing, if they typed only /bk-init)
 
-Ask each question with your tool for asking a question with choices, if you have one, with your recommendation as the first choice, so the user can pick it with Enter. If the user typed nothing above, ask the first question straight away, before calling any tool.
+Ask each question with your tool for asking a question with choices, if you have one, with your recommendation as the first choice, so the user can pick it with Enter, except where a step says to ask in prose. If the user typed nothing above, ask the first question straight away, before calling any tool.
 
 1. **Where the spec tree lives.** If the user gave a path above, use it as an existing spec tree and skip this question; if `manage` then reports there is no spec tree there, ask whether to create a new spec repository at that path instead. Otherwise ask:
    - **In this repository**, in a `specs/` folder. Recommend this when this is the team's only repository, or when trying BuildKeel out.
@@ -26,14 +26,18 @@ Ask each question with your tool for asking a question with choices, if you have
 
 3. **Stamping their own commits.** Explain: while a unit of work is active, BuildKeel adds a line `BuildKeel-Unit: <id>` to commits the agent makes. If they agree, a git hook adds the same line to commits they make themselves, for example in a terminal. It changes nothing when no unit is active. Recommend yes. If the repository already manages its git hooks with another tool, nothing is installed and BuildKeel shows the lines to add.
 
-4. Call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, `stampCommits` and, for a new tree, `mode`, without `apply`. Show the user the list it returns, as it is.
+4. Call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, `stampCommits` and, for a new tree, `mode`, without `apply`. Show the user the list it returns, as it is, in your reply as normal text.
 
-5. **The process**, for a new Full SDLC spec tree. The list ends with the process as a table: each stage, and the documents it requires before work under it starts (by default a design document for an epic and a test plan for a story). Never ask about a table the user has not seen: ask, showing the table as it is. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+5. **The process**, for a new Full SDLC spec tree. The list ends with the process as a table: each stage, its first ID and the documents it requires before work under it starts (by default a design document for an epic and a test plan for a story), then the bug and ad-hoc prefixes, each gate's mode, and how a task's own test plan is kept. Show it as it is. Then ask in prose, not with your tool for asking a question with choices, whether the team uses this process as it is, or how the team works: they can describe it in their own words, all at once, such as "we call stories features, every feature needs a design doc, epics need a security review, and the gates should only warn while we try it out".
+   - **Used as it is**: go on to the confirmation below.
+   - **Described in their words**: work out a `process` object from it, as in buildkeel.yaml's process section: stage names, a stage added between the business idea and the user story, the documents each stage requires, the team's own documents (say that each needs a template of its own later), ID prefixes, each gate's mode, and whether a task's own test plan is approved. Leave out what they did not mention: it keeps its default, and you ask nothing about it. Call `manage` again without `apply` with the `process`, and show the new table. Name anything they described that the process cannot express, such as a stage after the code is built, with the closest setting it has, such as the done gate's checks; never drop it silently, and never invent a setting.
+
+   Then ask whether to set up with it, with the table in that same reply. Never ask about a table the user has not seen. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices:
    - **Set up with this process** (the default, listed first).
-   - **Adjust the process.** Ask what to change, one question at a time, with your recommendation: rename a stage (such as stories called "features"), add a stage between the business idea and the user story, change the documents a stage requires, or add a document of the team's own (it needs a template of its own later). Put the changes in a `process` object, as in buildkeel.yaml's process section, call `manage` again without `apply` with it, and show the new table. Repeat until the user agrees.
+   - **Change something.** Take in what they say, in their own words, work it into the `process`, call `manage` again without `apply`, and show the new table. Repeat until the user agrees.
    - **Stop, and set up nothing.**
 
-   A Spec-driven tree has no stages, and an existing spec tree keeps its own process: skip this question and ask the user to confirm the list.
+   A Spec-driven tree has no stages, and an existing spec tree keeps its own process: skip this question and ask the user to confirm the list. 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.
 
 6. Only when the user confirms, call `manage` again with the same values (and the same `process`, if they adjusted it) and `apply: true`. Show the result as it is, including any lines the user must add to their hook manager, and, for a new spec repository, that it needs a remote and a push before others can use it.
 

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

@@ -1,19 +1,43 @@
 ---
 name: bk-migrate
-description: "BuildKeel: Upgrade a spec tree in an older format to the one this BuildKeel uses, in one commit, without touching approved versions. Run as /bk-migrate."
+description: "BuildKeel: Move a Spec-driven tree to Full SDLC, area by area, or upgrade a spec tree in an older format, in one commit, without touching approved versions. Run as /bk-migrate, 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.
 
-Upgrade the spec tree to the format this version of BuildKeel uses. A tree in an older format can be read but not changed until it is migrated.
+Migrate the spec tree with the user: upgrade it to the format this version of BuildKeel uses when an update needs that, or move a Spec-driven tree to Full SDLC. Nothing is written without the user's confirmation.
 
-Call the BuildKeel `manage` tool with `action: "migrate"`, without `apply`, and show the result as it is.
+## Upgrade the format first
 
-- If it says there is nothing to migrate, or that the plugin needs an update first, say so and stop.
-- Otherwise it lists what changes: the working files and `buildkeel.yaml`, in one commit, with frozen versions and records left exactly as they are. Ask the user to confirm, with your tool for asking a question with choices: **Migrate** (the default) or **Not now**.
+Call the BuildKeel `manage` tool with `action: "migrate"`, without `apply`.
 
-Only when the user confirms, call `manage` again with `action: "migrate"` and `apply: true`, and show the result as it is. Remind the user to push the spec repo, and that teammates need this version of BuildKeel, or a later one, to work in the tree.
+- If it says the plugin needs an update first, say so and stop.
+- If it lists what changes (the working files and `buildkeel.yaml`, in one commit, with frozen versions and records left exactly as they are), show it as it is and ask, with your tool for asking a question with choices: **Migrate** (the default) or **Not now**. Only when the user confirms, call `manage` again with `action: "migrate"` and `apply: true`, and show the result as it is. Remind the user to push the spec repo, and that teammates need this version of BuildKeel, or a later one, to work in the tree. Then stop.
+- If it says there is nothing to migrate, go on below.
 
-Do not change spec tree files yourself; the `manage` tool does all of it.
+## Move a Spec-driven tree to Full SDLC
+
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree follows Full SDLC, say that the tree is up to date and there is nothing to move, and stop.
+
+In a Spec-driven tree, call `query` with `view: "onboarding"`. When it shows a conversion in progress, carry it on, as "Converting area by area" says. Otherwise, explain in a few lines what moving to Full SDLC means: work then goes through the team's stages, with approvals and gates, and the capability specs and archived changes are drafted into those stages, area by area, for the user to review and approve; the tree stays Spec-driven until every area is approved; and the move is one way. Then ask, with your tool for asking a question with choices: **Not now** (the default) or **Move this tree to Full SDLC**.
+
+If the user chooses to move it, call `manage` with `action: "convert"` and `convert: "start"`, without `apply`, and follow what it says: it refuses while any change is open, naming each with its title, and otherwise shows the process the tree will follow. Show it in your reply and ask the user to confirm, or to adjust the stages first. 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 once they confirm, call it again with `apply: true`.
+
+### Converting area by area
+
+`query` with `view: "onboarding"` shows the conversion area by area.
+
+1. **Map the areas.** Propose areas from the capability specs (`query`, `view: "capabilities"`), each holding one or more of them, as a table with what each covers. Ask the user to agree or change it, with the table 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. Write the map with `manage`, `action: "map"`, `map: "set"` and each area's `capabilities`.
+2. **For each area**, in the map's order, the next one as the default, with **Stop** as a choice:
+   - **Its sources** are its capability specs and the archived changes that wrote them (`query`, `view: "changes"`), each change kept as a source with its ID as the key. Call `query` with `view: "process"` for the stages and the documents each requires, and `view: "tree"` for what exists.
+   - **Propose** a table of the artifacts the area needs, top down, in the team's stage names: from the business idea down to the story, with the documents the process requires of each. Requirements become acceptance criteria and scenarios test cases, wherever they fit the stages; nothing maps one to one. Ask: **Draft them all** (the default), **Change the plan**, **Skip this area** or **Stop**, with the table 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.
+   - **Draft** top down, parents before children, each as version 0 with `save_draft` and `version: 0`, its sources in `sources`. Call `get_template` once for each type you draft. Add nothing the sources do not support; ask the user, one question at a time, about each required section nothing supports, with **Leave it empty** as a choice. A required document no source provides, such as a test plan, is drafted as version 1.
+   - **Review and approve:** show what was drafted as a table: ID, title, version, the sources kept, and the sections left empty. Call `approve` with `ids` set to all of them and `onboard: true`, without `apply`, and ask whether to approve them, with the table and the result 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. Call it again with `apply: true` only when the user confirms.
+   - **Place the scenarios:** once the area is approved, show a table of each scenario and the criterion or test case it became, ask the user to agree it, and record it with `manage`, `action: "convert"`, `convert: "place"` and `place`. Leave a scenario out (`drop`) only when the user says so. A test tagged with a scenario counts for what that scenario became, so existing tests need no matching.
+3. **Switch.** Once every area is converted, the view says so: call `manage` with `action: "convert"` and `convert: "finish"`, without `apply`, and ask the user to confirm the switch, with what it says 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. Only when they confirm, call it again with `apply: true`, and show the result as it is.
+
+The user can stop after any area: the next /bk-migrate carries on from there. While the conversion is in progress no change can be opened, and bugs and ad-hoc units work as usual. Before any area is approved, the conversion can be cancelled with `manage`, `action: "convert"` and `convert: "cancel"`, after the user confirms.
+
+Do not change spec tree files yourself; the BuildKeel tools do all of it.

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

@@ -1,11 +1,11 @@
 ---
 name: bk-new
-description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a bug. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or bug TK-001."
+description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a bug. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or bug TK-001, 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.
 
 Draft BuildKeel artifacts with the user. Everything you produce is a draft: drafting never approves anything, and every draft goes through the same checks and approval as one written by hand. A bug is the exception: it is recorded at once, with its permanent ID, and needs no approval (see "Bugs" below).
 
@@ -92,7 +92,7 @@ A bug is a defect in work that was planned: it is recorded straight away with it
 2. **The test case that found it**, when a test failed: call `query` with `view: "coverage"` and the unit's ID to see the test cases that apply there, and offer them, with **none** last. A standalone bug has none.
 3. **What is wrong.** Use the user's description, or ask for it in their own words: never offer descriptions you made up as choices, since a bug records what someone saw. Write a title that names the defect, such as "Reset link expires after 3 minutes".
 4. Call `get_template` for `bug`, then `save_draft` with `type: "bug"` and the whole file: `id: {{id}}`, the title, `parent` set to the unit's ID and `testCase` to the test case's ID when there are any, and the sections filled in (what is wrong, steps to reproduce, expected, actual). Leave out sections you know nothing about rather than inventing them.
-5. Show the result: the bug's ID, where it is attached, and that it can be started with /bk-start <ID>. If fixing it means a requirement must change, say so: that change is made as a new version of the story or task, approved as usual.
+5. Show the result: the bug's ID, where it is attached, and that it can be started with /bk-build <ID>. If fixing it means a requirement must change, say so: that change is made as a new version of the story or task, approved as usual.
 
 ## Finish
 
@@ -107,6 +107,6 @@ What you draft is a change, or a file of an open change: its proposal, a spec ch
 - **If the user typed nothing**, ask what to draft, offering **Suggest what to draft next** (the default) and **Type what to draft**. The question itself gives examples: `change for reset by text message`, `spec change for CH-012` and `bug CH-012`. For a suggestion, call `query` with `view: "changes"` and propose what an open change still lacks, such as tasks or a spec change its proposal names.
 - **Read before writing.** Call `query` with `view: "capabilities"`, and with the `id` of each capability the work touches. For a file of an open change, read the change with `view: "changes"` and its `id`. Call `get_template` for each file you draft.
 - **A new change**: draft its proposal, a spec change per capability it adds or modifies, a design only when it makes decisions worth recording, and tasks, and save them in one `save_draft` call with `type: "change"`, the proposal as `content` and the rest in `files`. Before saving a new capability, propose its code from its name and let the user change it.
-- **A file of an open change**: save it with `save_draft`, its type and the change's `id`. Then check the change's other files against it and propose the follow-on edits, such as a task for a new requirement.
+- **A file of an open change**: save it with `save_draft`, its type and the change's `id`; read it first with `query`, `view: "changes"`, the change's `id` and `file`. To change one requirement of a spec change, pass `capability` and `requirement` in place of `content`. Then check the change's other files against it and propose the follow-on edits, such as a task for a new requirement.
 - Ask one question at a time, for what you cannot work out. If the user asks to go one artifact at a time, save and show each before the next.
-- Finish by listing what was saved and anything `save_draft` lists as worth fixing, and offer /bk-start with the change's ID.
+- Finish by listing what was saved and anything `save_draft` lists as worth fixing, and offer /bk-build with the change's ID.

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

@@ -1,11 +1,11 @@
 ---
 name: bk-onboard
-description: "BuildKeel: Document code that existed before BuildKeel, area by area: map the code, then draft each area for people to review and approve. Run as /bk-onboard [an area to onboard, or nothing to choose]."
+description: "BuildKeel: Document code that existed before BuildKeel, area by area: map the code, then draft each area for people to review and approve. Run as /bk-onboard [an area to onboard, or nothing to choose], 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.
 
 Document the code that existed before BuildKeel with the user, one capability area at a time. People lead it: you propose and draft, the user corrects, completes and approves, and nothing is approved without them. They can stop after any area and carry on later; whatever they leave is documented as work touches it.
 
@@ -17,7 +17,7 @@ If BuildKeel's session report, or `query` with `view: "process"`, says this spec
 
 ## Choose what to do
 
-Call the BuildKeel `query` tool with `view: "onboarding"`; it changes nothing. Then ask straight away, with your tool for asking a question with choices if you have one, the default listed first, showing what the view said. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+Call the BuildKeel `query` tool with `view: "onboarding"`; it changes nothing. Then ask straight away, the default listed first, with what the view 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.
 
 - When there is a map: **Continue with an area**, **Adjust the map**, **Fill in what onboarding left empty** (only when the view lists anything), **Stop**. When the user continues, ask which area, as in "Choose an area" below.
 - When there is none: **Map the code** (the default), **Fill in what onboarding left empty** (only when the view lists anything), **Stop**.
@@ -28,8 +28,8 @@ If the user typed an area's name above, onboard that area. Ask one question at a
 
 1. Read the code's layout: its top-level folders, entry points, routes or handlers, and what the README says. Call `query` with `view: "tree"` for what the spec tree already holds.
 2. Propose capability areas: what the product does, in the words its users would use ("Password reset", "Invoicing"), not one area per folder. Give each the paths it covers, its repository when the tree serves several, and one line on what it does. Make them a table, with a column for the area, its paths and what it does, in the order you recommend onboarding them, and say why in a sentence.
-3. Ask: **Use this map** (the default), **Merge, split or rename areas**, or **Stop**, showing the table and that sentence, so the user sees what is mapped to what before choosing. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Take in each change, and ask again with the whole table.
-4. Once the user agrees, write the map with `manage`, `action: "map"`, `map: "set"` and the `areas`. Later changes to a written map use `map: "merge"`, `"split"` or `"rename"`. Then ask which area to onboard, as in "Choose an area", showing the table `manage` returns, as it is. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+3. Ask: **Use this map** (the default), **Merge, split or rename areas**, or **Stop**, with the table and that sentence in your reply, so the user sees what is mapped to what before choosing. 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. Take in each change, and ask again with the whole table.
+4. Once the user agrees, write the map with `manage`, `action: "map"`, `map: "set"` and the `areas`. Later changes to a written map use `map: "merge"`, `"split"` or `"rename"`. Then ask which area to onboard, as in "Choose an area", with the table `manage` returns, as it is, 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.
 
 ## Choose an area
 
@@ -65,7 +65,7 @@ Once the area's drafts are approved, or all but those waiting on a question left
 - A required document no source provides, such as a design document or a test plan, is drafted as version 1, under the normal rules, so that new work under the area can start as usual.
 - When an artifact in BuildKeel already describes part of the area, see "Version 0 under an existing artifact" below.
 
-Ask: **Draft them all** (the default), **Change the plan**, **Skip this area**, or **Stop**, showing the table. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+Ask: **Draft them all** (the default), **Change the plan**, **Skip this area**, or **Stop**, with the table 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.
 
 ### 3. Draft everything
 
@@ -88,7 +88,7 @@ A test plan has a test case for each acceptance criterion of its story. A finish
 
 ### 4. Review and approve
 
-Show what was drafted as a table: ID, title, version, the sources kept, and the sections left empty. Then offer to approve the area's drafts in one review: call `approve` with `ids` set to all of them and `onboard: true`, first without `apply`, and ask whether to approve them, showing the table and the result as it is. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Call it again with `apply: true` only when the user confirms. Each version 0 is approved first, and a finished task's version 0 is linked to the commits before the baseline that name its key.
+Show what was drafted as a table: ID, title, version, the sources kept, and the sections left empty. Then offer to approve the area's drafts in one review: call `approve` with `ids` set to all of them and `onboard: true`, first without `apply`, and ask whether to approve them, with the table and the result as it is 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. Call it again with `apply: true` only when the user confirms. Each version 0 is approved first, and a finished task's version 0 is linked to the commits before the baseline that name its key.
 
 ### 5. Existing tests
 
@@ -96,12 +96,12 @@ Once the area is approved:
 
 1. Run the tests with a JUnit XML report and record it with `test_results`, as the agent instructions describe.
 2. Call `query` with `view: "untested"` and the area's epic or story: it lists the test cases with no test, and the tests in the report that match no test case.
-3. Propose which existing tests implement which test cases, as a table, naming each test exactly as the report does. Ask the user to confirm or correct it, showing the table. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Then record each with `manage`, `action: "match"`, the test case's `id` and its `tests`. The code is never changed.
+3. Propose which existing tests implement which test cases, as a table, naming each test exactly as the report does. Ask the user to confirm or correct it, with the table 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. Then record each with `manage`, `action: "match"`, the test case's `id` and its `tests`. The code is never changed.
 4. Call `query` with `view: "untested"` again and show the gap report: the behavior with no test, and the tests that test no stated behavior.
 
 ### 6. Next
 
-Call `query` with `view: "onboarding"` and ask which area to onboard next, as in "Choose an area", showing where onboarding stands. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. When the view lists anything left empty, also offer **Fill in what onboarding left empty**; when it lists questions left open, also offer **Answer a question left open**: ask the question, with both readings as equals, and record the answer as above.
+Call `query` with `view: "onboarding"` and ask which area to onboard next, as in "Choose an area", with where onboarding stands 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. When the view lists anything left empty, also offer **Fill in what onboarding left empty**; when it lists questions left open, also offer **Answer a question left open**: ask the question, with both readings as equals, and record the answer as above.
 
 ## Known defects
 
@@ -121,15 +121,8 @@ Do not create or edit spec tree files yourself: `save_draft`, `approve` and `man
 
 ## In a Spec-driven tree
 
-Existing code is documented as capability specs, version 0, area by area. Map the code as "Map the code" says, each area to become one or more capabilities. For the area `query` with `view: "onboarding"` names next: read its code and what the user brings, then draft each capability spec (a purpose, requirements with scenarios, new IDs as `CODE-R{{new}}`, the code proposed from its name for the user to change) and show it whole. Only once the user confirms one, save it with `save_draft`, `type: "capability"`, `version: 0` and `area: <name>` in its frontmatter: it is written once, with who confirmed it. When sources disagree, ask as above, with **Not sure: leave it open** last; a question left open is recorded on the area with `manage`, `action: "map"`, `map: "question"`, and its requirement is left out of version 0. Answering one later (`map: "answer"`) is followed by a change that adds the requirement. Record the tickets read for the area with `map: "tickets"` as above, each carried one naming the capability spec it fed. Then offer the next area.
+Existing code is documented as capability specs, version 0, area by area. Map the code as "Map the code" says, each area to become one or more capabilities. For the area `query` with `view: "onboarding"` names next: read its code and what the user brings, then draft each capability spec (a purpose, requirements with scenarios, new IDs as `CODE-R{{new}}`, the code proposed from its name for the user to change) and show it whole. 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. Anything but agreement is feedback: discuss it, then list each point with how it was addressed, show the final version, and ask again. Only once the user confirms one, save it with `save_draft`, `type: "capability"`, `version: 0` and `area: <name>` in its frontmatter: it is written once, with who confirmed it. When sources disagree, ask as above, with **Not sure: leave it open** last; a question left open is recorded on the area with `manage`, `action: "map"`, `map: "question"`, and its requirement is left out of version 0. Answering one later (`map: "answer"`) is followed by a change that adds the requirement. Record the tickets read for the area with `map: "tickets"` as above, each carried one naming the capability spec it fed. Then offer the next area.
 
-### Moving to Full SDLC
+### Moving to Full SDLC is not onboarding
 
-When the user asks for approvals, stages or gates, or to convert the tree, offer **Move this tree to Full SDLC** (never as the default; the move is one way). Call `manage` with `action: "convert"` and `convert: "start"`, without `apply`, and follow what it says. Once a conversion is under way, `query` with `view: "onboarding"` shows it area by area: map the capability specs into areas, each area holding one or more, with `manage`, `action: "map"` and each area's `capabilities`, then for each area follow "Onboard an area" above, with these differences:
-
-- Its sources are its capability specs (`query`, `view: "capabilities"`) and the archived changes that wrote them (`view: "changes"`), each change kept as a source with its ID as the key. The code is not read at a baseline.
-- Draft the stages of `query` with `view: "process"`, top down: requirements become acceptance criteria, scenarios test cases, wherever they fit the stages. Nothing maps one to one.
-- Once the area is approved, show a table of each scenario and the criterion or test case it became, and record it with `manage`, `action: "convert"`, `convert: "place"` and `place`. Leave a scenario out (`drop`) only when the user says so.
-- Skip "Existing tests": a test tagged with a scenario counts for what that scenario became.
-
-Once every area is converted, the view says so: call `manage` with `action: "convert"` and `convert: "finish"`, without `apply`, and ask the user to confirm the switch, showing what it says. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+/bk-onboard only documents code. When the user asks to move the tree to Full SDLC, or for approvals, stages or gates, say that moving the tree is done with /bk-migrate, and convert nothing here. When `query` with `view: "onboarding"` shows a conversion in progress, say that /bk-migrate carries it on.

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

@@ -5,7 +5,7 @@ description: "BuildKeel: Show your own BuildKeel usage over a period: units fini
 
 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.
 
 Show the user their own use of BuildKeel in this spec tree, from the record kept on their machine. The record holds IDs, types, outcomes and times, never artifact text or code, and nothing is ever sent anywhere.
 

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

@@ -5,7 +5,7 @@ description: "BuildKeel: Show the overview: the tree with each artifact's state,
 
 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.
 
 Call the BuildKeel `query` tool with `view: "status"`.
 

package/antigravity/templates/epic.md

@@ -10,6 +10,7 @@ sections:
   Summary: { required: true }
   Scope: { required: true, tracked: true }
   Out of scope: { tracked: true }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---
 

package/antigravity/templates/idea.md

@@ -10,6 +10,7 @@ sections:
   Problem: { required: true, tracked: true }
   Goals: { required: true, tracked: true, items: { prefix: G, style: list } }
   Success measures: { tracked: true }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---
 

package/antigravity/templates/spec-driven/proposal.md

@@ -12,6 +12,7 @@ sections:
   Capabilities: { required: true }
   Impact: { required: true }
   Non-goals: { offered: "What the change deliberately leaves out, so nobody builds it by mistake." }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: { offered: "Background, links, and anything from a source that fits no other section." }
 ---
 

package/antigravity/templates/story.md

@@ -10,6 +10,7 @@ sections:
   Summary: { required: true }
   Story: { required: true, tracked: true }
   Acceptance criteria: { required: true, tracked: true, items: { prefix: AC, style: list } }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---
 

package/antigravity/templates/task.md

@@ -9,6 +9,7 @@ fields:
   scope: { type: list }
 sections:
   Description: { required: true, tracked: true }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---