buildkeel 0.2.0 → 0.3.0

package/antigravity/package.json

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

package/antigravity/plugin.json

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

@@ -1,15 +1,15 @@
 ---
 trigger: always_on
-description: How to work in a repository set up with BuildKeel (it has a .buildkeel.yaml file). Use it when the user asks you to change code or to move work forward, before committing, when writing or running tests, when finishing a unit of work, and whenever you read or change requirements, designs, stories, tasks or test plans.
+description: How to work in a repository set up with BuildKeel (it has a .buildkeel.yaml file). Use it when the user asks you to change code, before committing, when writing or running tests, when finishing a unit of work, and whenever you read or change requirements, designs, stories, tasks or test plans.
 ---
 
 BuildKeel keeps requirements, tests and code connected. Follow these rules in any repository that has a `.buildkeel.yaml` file.
 
 ## Conversation comes first
 
-Talk with the user as you would without BuildKeel. Follow where they take the conversation, stay curious rather than prescriptive, ask one question at a time with your recommendation, and never push for an output they did not ask for. When a question is about something you show, such as a table, a plan or a tool's result, the user sees it as they answer: Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Discussing ideas, weighing options, talking through architecture and reading code are free: leave BuildKeel's artifacts, stages, IDs and commands out of it.
+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, asks you to change code, or asks to move work forward, such as "let's plan this" or "build it". Then say how to structure what was discussed (see "Before changing code"). Once that is done, the conversation is free again.
+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.
 
 ## The spec tree
 
@@ -21,7 +21,7 @@ A team can rename the stages of its process and add stages of its own. When it h
 
 Every code change belongs to the active unit of this working tree: a task, a story built without tasks, a bug or an ad-hoc unit. If there is none, before changing any file, ask the user how to go on, with your tool for asking a question with choices if you have one, recommending the choice that fits:
 
-1. **Capture what we discussed** with /bk-capture: it turns the conversation into the artifacts the team's process needs, to approve and then build. Recommend it when the conversation shaped new work.
+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.
 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.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-adhoc
-description: 'BuildKeel: Record a small change as an ad-hoc unit and start it, so its commits trace to something. Run as /bk-adhoc "<the change>", e.g. "Fix typo in the reset email".'
+description: 'BuildKeel: Record a small change as an ad-hoc unit and start it, so its commits trace to something. Run as /bk-adhoc "<the change>", e.g. "Fix typo in the reset email", 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.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-approve
-description: "BuildKeel: Approve a draft or a new version after checking it, or a set of drafts, such as a captured plan, in one review. Run as /bk-approve [artifact IDs], e.g. US-draft-k3x9, US-001-TP, or several IDs for one review."
+description: "BuildKeel: Approve a draft or a new version after checking it, or a set of drafts, such as a captured plan, in one review. Run as /bk-approve [artifact IDs], e.g. US-draft-k3x9, US-001-TP, or several IDs for one review, 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.

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

@@ -1,6 +1,6 @@
 ---
 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."
+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."
 ---
 
 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.

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

@@ -1,17 +1,17 @@
 ---
 name: bk-capture
-description: "BuildKeel: Turn what you discussed into a plan: a plain summary, then the artifacts your process needs, drafted once you agree. Run as /bk-capture [which part of the conversation to capture; all of it when left out]."
+description: "BuildKeel: Turn what you discussed into a plan: a plain summary, then the artifacts your process needs, agreed one by one or all at once, as you choose. Run as /bk-capture [which part of the conversation to capture; all of it 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.
 
-Turn the conversation into a plan the team's process can build from. There are two checkpoints: nothing is drafted until the user agrees, and everything drafted stays a draft until it is approved.
+Turn the conversation into a plan the team's process can build from, with the user agreeing at each step: the summary, the list of what will be created, the pace, then each artifact. Nothing is saved that the user has not agreed to, and everything saved stays a draft until it is approved.
 
 The user typed: whatever follows /bk-capture in the user's message (nothing, if they typed only /bk-capture)
 
-If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow step 1, then "In a Spec-driven tree" at the end in place of steps 2 to 5.
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow step 1, then "In a Spec-driven tree" at the end in place of steps 2 to 6.
 
 ## 1. Say what you heard
 
@@ -20,8 +20,9 @@ Before calling any tool, sum up the discussion in plain words, with no BuildKeel
 - **What you set out to do**: the user's intent, in a sentence.
 - **The idea**: what it is, and who it is for.
 - **The approach**: the design choices and decisions discussed, and what was left open.
+- **Pitfalls and constraints raised**: each one the conversation surfaced, such as a limit, a failure to handle or a detail easy to get wrong, in the user's terms, marked settled or open. Leave the list out when nothing was raised; never add one the conversation did not raise.
 
-If the user typed something above, sum up that part of the conversation. If there is nothing to capture yet, say so, ask what they want to plan, and stop.
+If the user typed something above, sum up that part of the conversation. If there is nothing to capture yet, say so, ask what they want to plan, and stop. If the conversation was compacted, say that its earlier parts may be missing from the summary, and ask the user to add anything left out.
 
 Then ask, with your tool for asking a question with choices if you have one, showing the summary. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
 
@@ -39,9 +40,9 @@ Any other answer, such as a correction or a new thought, is more conversation: a
 4. If the work changes how something already built behaves, and a document describes how it works today (such as EP-01's design document for password reset), the plan includes a new version of that document.
 5. If the work changes code that already exists, work out which files it will change, from the discussion and the code, and call `query` with `view: "describes"` and their `paths`. Where an artifact describes them, the work builds on it. Where nothing describes the behavior the work changes, the plan includes a **version 0**: one artifact, usually a story, describing only what the work touches, as it works today, before the change. The change is then its version 1, or an artifact under it. A version 0 is a proposal: the user can drop it.
 
-Show the plan as a table, top down, and say where the work fits and why, in a sentence:
+Show the plan as a table, top down, each row with a one-line purpose, and say where the work fits and why, in a sentence:
 
-| Level | Artifact | Status | Why |
+| Level | Artifact | Status | Purpose |
 |---|---|---|---|
 | Business idea | BI-01 "Self-service account recovery" | exists | the goal this serves |
 | Epic | "Reset by text message" | new | the new capability |
@@ -55,19 +56,27 @@ Show the plan as a table, top down, and say where the work fits and why, in a se
 
 Then ask, the same way, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
 
-1. **Draft them all** (the default).
+1. **Looks right** (the default).
 2. **Place it somewhere else.** Ask where. The new artifact is drafted where the user says, with a link to the one you recommended (`related: [EP-01]`).
 3. **Change the plan.** Take in what they say and show the table again.
 4. **Keep talking.** Stop here; nothing is drafted.
 
-When the plan holds a version 0, offer **Draft them all, without the version 0** in place of the second choice; placing the work somewhere else is then a change to the plan. Without the version 0, the change is drafted as version 1 of a new artifact, as for any new work.
+When the plan holds a version 0, offer **Looks right, without the version 0** in place of the second choice; placing the work somewhere else is then a change to the plan. Without the version 0, the change is drafted as version 1 of a new artifact, as for any new work.
 
-## 3. Draft everything
+## 3. Ask the pace
 
-Only after the user agrees:
+Ask, every time, how the user wants to go through the drafts. Never assume it, and never carry it over from an earlier capture. The choices:
+
+1. **Step by step** (the default, listed first): each artifact is shown and agreed before the next is drafted.
+2. **All at once**: everything is drafted, then shown as a set.
+
+## 4. Draft
+
+### How to draft
 
 - Draft top down, parents before children, so each child names its parent's draft ID. Call `get_template` once for each type you draft, and follow it.
-- Fill each artifact from the conversation, keeping its meaning and the user's words. Put what fits no section in the section for further material, such as Notes. Never invent a requirement, a criterion or a decision that was not discussed; leave a required section out rather than fill it with a guess.
+- Fill each artifact from the conversation, keeping its meaning and the user's words. Turn each settled pitfall or constraint into the requirement, criterion or test case it calls for, in the artifact it belongs to. Put what fits no section in the section for further material, such as Notes.
+- Never invent a requirement, a criterion, a decision or a pitfall that was not discussed. What a draft needs and the conversation did not settle is a gap: see "Gaps" below.
 - Write `{{id}}` where the artifact's own ID goes and `{{new}}` as the number of each new entry, as `/bk-new` does: `- **{{id}}-AC{{new}}** ...` for criteria, `### {{id}}-TC{{new}} ...` for test cases.
 - Every story gets a test plan whose test cases cover all its criteria (`covers: [<story ID>-AC1]`). A task names its `repo` and, when you can tell, its `scope`. A task whose tests will not each be one of its story's test cases, such as a building block, gets its own test plan, with test cases that cover the task itself (`covers: [<task ID>]`): without one it cannot be finished.
 - A design document has no `id`; its `parent` is the artifact it describes. Add an offered section (`get_template` lists them) only when the discussion covered it.
@@ -75,6 +84,32 @@ Only after the user agrees:
 - A **version 0** in the plan is drafted before the change, by the rules below, with `save_draft` and `version: 0`. Name the paths it covers in its `scope`. Then draft the change: as its version 1, with `save_draft`, the version 0's draft ID as `id` and no `version`, holding the whole artifact as it will be after the change. Start from version 0's text as saved, with its entry IDs: keep the ID of every entry that stays, changed or not (a criterion whose limit changes keeps its ID), and write `{{new}}` only for an entry the change adds. Or, when the change is new work under it, as a new artifact whose `parent` is that draft ID.
 - Save each one with `save_draft`.
 
+### Step by step
+
+Go through the plan in this order, leaving out what already exists: a version 0 before the change built on it, then the business idea or epic, then its design document, then each story together with its test plan, then the tasks, with their own test plans, as one batch. For each one:
+
+1. Draft it against the artifacts already saved in this capture.
+2. Show it, with a line naming the pitfalls and constraints from the summary that it covers. Ask about each gap it has, as "Gaps" says, before going on.
+3. Ask, showing it. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Looks good, next** (the default), **Change something** (take in what they say and show it again), and **Draft the rest at once** (draft what is left in one go, then show it as a set).
+4. Save it with `save_draft` once the user agrees, before drafting the next.
+
+If the user stops partway, what they agreed to stays saved as drafts; draft nothing more.
+
+### All at once
+
+Draft everything, asking about gaps as you go, and save each one with `save_draft`. Then show what was drafted as a table: ID, title, and the pitfalls each covers.
+
+### Gaps
+
+A gap is what a draft needs that the conversation did not settle: a required section, a pitfall raised but left open, or a detail the artifact cannot do without. For each gap, tell the user what is missing and where, and ask, with no recommendation, since only the user knows. The choices, in this order:
+
+1. **Put it in the spec as stated**: write it as a requirement, criterion or test case, in the user's words.
+2. **Record it as an open question**: add it to the artifact's Open questions section, to settle later. It does not block approval.
+3. **Flesh it out now**: discuss it until the user settles it, then draft it.
+4. **Not relevant: leave it out.**
+
+A version 0 is the exception: list the sections it leaves empty, and ask nothing about them.
+
 ### Drafting a version 0
 
 Version 0 describes what the code does today, as if BuildKeel had been used from the start: the template's sections, filled from the code and from what the user brings about it, such as a ticket or a wiki page read through their own tools, a file, or what they say.
@@ -85,13 +120,13 @@ Version 0 describes what the code does today, as if BuildKeel had been used from
 - When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended, before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it with /bk-new bug once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
 - Supported means the code or a source says it. A plausible guess is not support: who a story is for and why, a business idea's problem and goals, or a design's context are rarely in the code. Leave a required section empty when nothing supports it, and do not ask about it here: `save_draft` lists what version 0 leaves empty, and the reviewer sees it.
 
-## 4. What the conversation left out
+## 5. What is left
 
-Show what was drafted as a table: ID, title, and what is still missing. Then, for each required section or field that `save_draft` named as missing, ask the user, one question at a time, and save the answer with `save_draft` and the draft's `id`. For example, if the design document requires a rollout plan the discussion never touched, ask how it will be rolled out. Show the table with the first question. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. A version 0 is the exception: list the sections it leaves empty, and ask nothing about them.
+List each pitfall or constraint from the summary that no saved artifact covers, and treat each as a gap, as above. Then show what was drafted as a table: ID, title, and its open questions, if any.
 
-## 5. Next step
+## 6. Next step
 
-Offer approval as the next step: /bk-approve shows the drafts from this capture as one set, with anything that would not pass, and approves them in one review once the user confirms, a version 0 before the change built on it. A task's own test plan is not in the set unless the process approves task plans: it is recorded when its task is approved. Do not approve anything yourself here.
+Agreeing to an artifact here does not approve it. Offer approval as the next step: /bk-approve shows the drafts from this capture as one set, with anything that would not pass, and approves them in one review once the user confirms, a version 0 before the change built on it. A task's own test plan is not in the set unless the process approves task plans: it is recorded when its task is approved. Do not approve anything yourself here.
 
 Do not create or edit spec tree files yourself; `save_draft` does all writing.
 
@@ -100,6 +135,9 @@ Do not create or edit spec tree files yourself; `save_draft` does all writing.
 The plan is one change: a proposal, a spec change for each capability whose behavior it alters, a design only when needed, and tasks. Nothing is approved.
 
 1. **Read the capability specs first.** Call `query` with `view: "capabilities"`, then with the `id` of each capability the work touches, so the change starts from how the system behaves now. Check `view: "changes"` for an open change that already covers the work.
-2. **Propose the change**, showing a table of the capabilities it adds or modifies, by code, with what changes in each, and say in a sentence whether it needs a design: only when it makes decisions worth recording, such as a new component, data, an interface or a trade-off. A change that alters no behavior, such as a refactor, says so and has no spec changes. For a new capability, propose a short code from its name, such as SMS, which the user can change before anything is saved. Then ask, the same way as in step 1, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Draft the change** (the default), **Change the plan**, **Keep talking**.
-3. **Draft the whole change** once the user agrees. Call `get_template` for proposal, spec-change, tasks and, when needed, design. Save them in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`. A modified requirement keeps its ID and holds its full new text; a removed one says why and what replaces it. Each task says how its completion is verified, and each group holds the tests and docs its work needs. If the user asked to go one artifact at a time, save the proposal first, then each other file with the change's `id`, showing each before the next.
-4. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Ask about what is missing, one question at a time. Then offer /bk-start with the change's ID as the next step.
+2. **Propose the change**, showing a table of the capabilities it adds or modifies, by code, with what changes in each, and say in a sentence whether it needs a design: only when it makes decisions worth recording, such as a new component, data, an interface or a trade-off. A change that alters no behavior, such as a refactor, says so and has no spec changes. For a new capability, propose a short code from its name, such as SMS, which the user can change before anything is saved. Then ask, the same way as in step 1, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Looks right** (the default), **Change the plan**, **Keep talking**.
+3. **Ask the pace**, as in step 3 above: **Step by step** (the default) or **All at once**, every time.
+4. **Draft the change.** Call `get_template` for proposal, spec-change, tasks and, when needed, design. Draft by "How to draft" and "Gaps" above: each settled pitfall becomes a requirement or scenario, and nothing is invented. A modified requirement keeps its ID and holds its full new text; a removed one says why and what replaces it. Each task says how its completion is verified, and each group holds the tests and docs its work needs.
+   - **Step by step:** show the proposal, with the pitfalls it covers, and save it once the user agrees, with `save_draft`, `type: "change"` and the proposal as `content`: that creates the change. Then each spec change, then the design if one is needed, then the tasks, each shown, agreed and saved in turn with `save_draft`, its `type` (`spec-change`, `design` or `tasks`) and the change's `id`. Offer **Looks good, next** (the default), **Change something** and **Draft the rest at once** at each step, as above.
+   - **All at once:** save them in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`, then show them.
+5. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Treat each pitfall from the summary that no file covers as a gap, and each missing part `save_draft` names. Then offer /bk-start with the change's ID as the next step.

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

@@ -1,6 +1,6 @@
 ---
 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.

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

@@ -1,6 +1,6 @@
 ---
 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.

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

@@ -1,6 +1,6 @@
 ---
 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.
@@ -11,7 +11,7 @@ Set up BuildKeel in this repository using the BuildKeel `manage` tool with `acti
 
 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.
@@ -28,9 +28,13 @@ Ask each question with your tool for asking a question with choices, if you have
 
 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.
 
-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, with your tool for asking a question with choices, showing the table. Never ask about a table the user has not seen. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
    - **Set up with this process** (the default, listed first).
-   - **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.

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

@@ -1,6 +1,6 @@
 ---
 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: 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, 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.

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

@@ -1,6 +1,6 @@
 ---
 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.

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

@@ -1,6 +1,6 @@
 ---
 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.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-start
-description: "BuildKeel: Start work on a task, story, bug or ad-hoc unit: check it is ready, switch to its branch and load its context. Run as /bk-start [unit ID], e.g. TK-001."
+description: "BuildKeel: Start work on a task, story, bug or ad-hoc unit: check it is ready, switch to its branch and load its context. Run as /bk-start [unit ID], e.g. 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.

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: {}
 ---