buildkeel 0.3.0 → 0.5.0

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

@@ -1,19 +1,70 @@
 ---
 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, only when the user types it."
+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`. It refuses while any change is open, naming each with its title: show that, and stop. Otherwise it lists what starting the conversion does and the process the tree would follow, and the process is settled as for a new Full SDLC tree, before any area is drafted. Each call below is `manage` with `action: "convert"` and `convert: "start"`.
+
+Topics for this step, in this order:
+
+- **stages**: what each stage is called, and any stage added between the business idea and the user story, with where it sits.
+- **kinds**: whether a stage holds more than one kind of work, such as features and enhancements beside user stories. Each kind is numbered in its own sequence, has its own template and documents, and behaves as its stage does.
+- **prefixes**: the ID prefix and digits of each stage and kind, such as `US-001`, `FEAT-0001` or `PROJ-12`.
+- **documents**: what each stage and kind needs approved before work under it starts: a test plan, a design document, or a document of the team's own, such as a security review.
+- **test-plans**: whether a task's own test plan is recorded as it is saved (the default) or approved like any other plan.
+- **gates**: each gate's mode: block stops the action, warn lets it go ahead with a warning, off skips the check. The approve gate checks an artifact before it is approved: it follows its template, and its parent is approved. The start gate checks before work starts: everything above the unit is approved and not suspect, and its required documents are approved. The done gate checks before a unit is finished: its test cases pass. The lock gate checks before the agent edits approved versions and records.
+
+Work from the topics listed for this step. The user may answer in their own words, several topics at once or part of one. After each answer, say which topics it settled, with what you understood for each, and which are left; then ask the next one left, one topic per message. Where a topic has a default, list keeping it first, naming its actual value, and give examples where they help. Anything you work out that the user did not say is a proposal: ask it as that topic's question, with it as the default, and never use it without the user's answer. Ask about an unclear answer; name a conflicting one beside the earlier answer and ask which holds. Never guess. When every topic is settled, show all of it, as a review.
+
+The list shows the process as a table: BuildKeel's default, or the organization's when the tree takes its templates from one. Show it as it is, in your reply as normal text. Then ask in prose, not with your tool for asking a question with choices, whether the team uses this process as it is, or works differently and how: they can describe it in their own words, all at once or in part. If they only say it works differently, ask in one line how their team works.
+
+- **Used as it is**: every topic is settled. Pass `settled: ["all"]`, and go on to the review below.
+- **Works differently**: settle the topics their description covers, and ask each topic left, in the order above, with the default's actual value from the table as the first answer. Build `process` as in buildkeel.yaml's process section from what the user said or confirmed, nothing else. An added stage or kind needs a prefix: propose one, such as `FEAT` for feature, and say it is a suggestion they can change. When the user names a stage the default process does not have, ask whether it is a stage of its own, between two stages, or a kind of work beside one, such as features beside user stories, before you settle stages: a list of stage names in order does not say which. Name anything the process cannot express, such as a stage after the code is built, with the closest setting it has, such as the done gate's checks; never drop it silently, and never invent a setting. After each answer, call `manage` again without `apply`, with the same values as before, the `process` so far and every topic settled in `settled`: it lists the topics left.
+
+When no topic is left, call `manage` again without `apply` and show the whole table it returns, as it is, with its line on what each stage or kind the team added means, and ask whether to go ahead with it. Never ask about a table the user has not seen. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The answers: go ahead with this process (the default); change something, which you take in, then call `manage` again and show the whole table again, in the same layout; or stop, and write nothing.
+
+**Templates.** Once the user agrees the table, settle a template for each one the list says the process needs, one at a time, in the order listed. For each, ask: **Claude drafts it** (the default) or **I'll provide a file**. Nothing is left for later: if the user asks to leave one, say that the tree needs it to check what is drafted from it, and ask again with the same two answers.
+
+- **Claude drafts it**: call `get_template` for the closest built-in type: `story` for a kind at the user story stage, `epic` for a stage between the epic and the user story or a kind at one, `idea` for a kind at the business idea stage, `task` for a kind at the task stage, `design` for a document of the team's own. Change its `template:` line to the new type, and its description and sections to what the user said about it. Show it in full, and ask whether to use it or change something. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+- **I'll provide a file**: read the file the user names with your own tools, and pass its text. When `manage` says it fails the template check, show what is wrong, and ask: **Claude fixes it** (the default) or **Use another file**. Show a fixed template in full, and ask whether to use it. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+
+Pass each agreed template in `templates`, by type, and call `manage` again without `apply`: it checks each one. Nothing is written until every template the list names is given and passes.
+
+Once the process and its templates are settled and the user agrees to go ahead, call it again with the same `process`, `settled` and `templates`, and `apply: true`: the conversion starts, and the templates are written with it.
+
+### 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 defects 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,29 +1,32 @@
 ---
 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, only when the user types it."
+description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a defect. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or defect 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).
+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 defect is the exception: it is recorded at once, with its permanent ID, and needs no approval (see "Defects" below).
 
 The user typed: whatever follows /bk-new in the user's message (nothing, if they typed only /bk-new)
 
-If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end instead of the sections before "Bugs".
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end instead of the sections before "Defects".
 
 ## If the user typed nothing
 
-Ask straight away, before calling any tool, with your tool for asking a question with choices if you have one. The question itself says what they could type, in one sentence, since some hosts show only the question and its choices: "What should I draft? For example: " followed by the examples.
+Ask straight away, with your tool for asking a question with choices if you have one. The question itself says what they could type, in one sentence, since some hosts show only the question and its choices: "What should I draft? For example: " followed by the examples.
 
-Take the examples word for word from BuildKeel's session report when it gives them ("Examples of what to draft, in the team's words"): they use the names this team gives its stages, which may not be the usual ones. Only when it gives none, use `story EP-01`, `stories from EP-01`, `test-plan US-001` and `bug TK-001`.
+Take the examples word for word from BuildKeel's session report when it gives them ("Examples of what to draft, in the team's words"): they use the names this team gives its stages, which may not be the usual ones. Only when it gives none, use `story EP-01`, `stories from EP-01`, `test-plan US-001` and `defect TK-001`.
 
 Offer two choices: **Suggest what to draft next** (the default, listed first) and **Type what to draft**; if they pick the second, ask what to draft. If they pick the suggestion, call the BuildKeel `query` tool with `view: "tree"`, propose the most useful next drafts (such as stories for an epic that has none, or a missing test plan), and ask which to draft. Then carry on below with their answer as the request.
 
 ## Work out what to draft
 
-- **The type**: idea, epic, story, task, test-plan, design (a design document) or bug, or a stage or document the team added (the user may use their team's own name for it). If it is not clear, ask. For a bug, follow "Bugs" below instead of the rest of this prompt.
+- **The type**: idea, epic, story, task, test-plan, design (a design document) or defect, or a stage, kind or document the team added (the user may use their team's own name for it). If it is not clear, ask. For a defect, follow "Defects" below instead of the rest of this prompt.
+- **The kind**, when the stage of the type holds more than one (`query` with `view: "process"` lists the kinds at each stage), and the user did not name one: propose one from where the work came from, and say why, such as an enhancement because it improves an existing export screen. Ask the user to confirm it or pick another, before drafting; never pick one without their answer. Draft it with the kind as the type, from that kind's template. For a breakdown, propose a kind for each child in the list of children, and the user confirms them there.
 - **The parent**: every type except a business idea has one: an artifact's parent is of the stage directly above it in the process (by default an epic's parent is a business idea, a story's an epic and a task's a story; with a stage added between epic and story, a story's parent is of that stage), and a test plan's parent is the artifact it tests. If the user did not name it, call the BuildKeel `query` tool with `view: "tree"`, suggest the likely parent, and ask.
 - **One draft or a breakdown**: a request such as "stories from EP-01" or "break EP-01 down" asks for a set of children of one parent. Anything else is a single draft.
 - **The user's own material**: if the user pasted text, named or uploaded a file, pointed to something in a tool you can read (such as an issue tracker or a wiki), or described the requirement, use it as the main input. Fit it to the template: put each part in the section it belongs to, keeping its meaning and wording; put what fits no section in the section for further material, such as Notes; and for each required section it does not cover, ask the user, one question at a time. Never invent a requirement, a criterion or a section to fill a gap, and never add a detail the material leaves open, such as how a notice reaches the customer: ask, or keep the wording as open as the material's.
@@ -55,7 +58,7 @@ Version 0 describes what code already does, as if BuildKeel had been used from t
 - Fill the template's sections 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. Reword what they say into the template's form, such as a ticket's description written as testable criteria; add nothing they do not support.
 - Describe only what the change touches.
 - Keep each source as you read it: pass it in `sources`, with where it came from, its key and link, and its text exactly as your tool returned it (description, fields and comments). Never copy code into a source.
-- When a source and the code disagree, or two sources do, 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 once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
+- When a source and the code disagree, or two sources do, ask the user which is intended before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded against it 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, such as who a story is for and why. Leave a required section empty when nothing supports it, without asking: `save_draft` lists what is empty, for the reviewer.
 
 The change that builds on it is then saved with `save_draft`, the version 0's draft ID as `id` and no `version`: that draft is its version 1. 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. Both are approved in one review with /bk-approve, version 0 first.
@@ -84,15 +87,28 @@ The process may require other documents of a stage, such as a team's threat mode
 - **For each task**, decide which of the story's test cases its tests will implement, and say so in the list you propose. If its tests will not be story test cases, draft the task's own test plan too (type `test-plan`, parent set to the task's draft ID), with test cases that cover the task, such as `covers: [{{id}}]`.
 - Before writing, show the user the list of children you propose (titles and a line each) and ask whether to go ahead or change it.
 
-## Bugs
+## Defects
+
+A defect is code that does not do what was agreed. Finishing it needs a regression test with the defect's ID in its name, such as `it("keeps reset links for 30 minutes [DEF-005]", ...)`.
+
+Once the user says a defect was reported (step 1), sort the report before going on, and record it here only when they confirm it is a defect; a change in behavior or a gap is drafted as that work instead.
+
+**Sorting a report.** When someone reports that the system does something wrong, check it before recording anything: what the spec says about that behavior now (in a Spec-driven tree, `query` with `view: "capabilities"` and the capability's `id`; otherwise the stories and their acceptance criteria, with `query`), and the code linked to it (`query` with `view: "describes"` and the files involved). Then propose one reading, labelled as yours, such as "My reading: a defect", with what it rests on:
+
+- **A defect**: the code does not do what the spec says. The code is fixed and the spec keeps its version. It is recorded as a defect with `source: reported`.
+- **A change in behavior**: the code does what the spec says, and the user wants something else. The spec changes and gets a new version: in a Spec-driven tree through a change, otherwise through a new version of the story, or a new item of the team's kind for it, such as an enhancement.
+- **A gap**: the spec says nothing about it. Settle with the user what it should do; that goes into the spec as a change in behavior.
+- **Nothing describes this code yet**: `describes` finds no artifact for it. In Full SDLC, draft version 0 of the story the code belongs to first, stating the intended behavior, and record the defect with that draft as its parent; both are reviewed and approved together, version 0 first. In a Spec-driven tree, ask **Record it standalone** (the default) or **Document this code first**, as version 0 of a capability spec, then link the defect to its requirement.
 
-A bug is a defect in work that was planned: it is recorded straight away with its permanent ID, needs no approval, and is worked on like any unit. Finishing it needs a regression test with the bug's ID in its name, such as `it("keeps reset links for 30 minutes [BUG-005]", ...)`.
+Ask with your tool for asking a question with choices, your reading first, then the other readings, so the user confirms or overrides it. Record nothing until they answer. A defect found while building, such as a failing test of the work under way, needs no sorting: it is a defect of that work.
 
-1. **Where it was found.** If the user named a task or story, use it. Otherwise ask, with your tool for asking a question with choices, offering **the active unit** first when there is one, then **another task or story: type its ID**, then **nowhere known yet** (a standalone bug, such as one a customer reported). A bug is attached to a task or a story, never to an epic or anything else.
-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.
+1. **Found while building, or reported.** Ask, with your tool for asking a question with choices: **Found while building** (a test failed, or it showed up during the work; the default when a unit is active) or **Reported** (by users, customers or testers; the default when no unit is active). Set `source` to `found` or `reported`.
+2. **Where it belongs.**
+   - **Found while building:** the task or story being built. If the user named one, use it. Otherwise offer **the active unit** first, then **another task or story: type its ID**. Then 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.
+   - **Reported:** the work it affects, of a kind the process allows as a defect's parent (a user story unless the team chose others). If the user named it, use it. Otherwise ask which files or behavior the report points to, call `query` with `view: "describes"` and those `paths`, and offer the parents it lists, the first as the default, then **another: type its ID**. When it says nothing describes that code, follow "Nothing describes this code yet" above, drafting version 0 as in "Version 0".
+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 defect records what someone saw. Write a title that names the defect, such as "Reset link expires after 3 minutes".
+4. Call `get_template` for `defect`, then `save_draft` with `type: "defect"` and the whole file: `id: {{id}}`, the title, `source`, `parent`, `testCase` when a test case found it, 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. A defect found while building has its permanent ID at once and can be started with /bk-build <ID>. A reported defect is a draft: it is approved with /bk-approve like any draft, gets its number then, and is started after that. 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
 
@@ -102,11 +118,11 @@ Do not create or edit spec tree files yourself; `save_draft` does all writing.
 
 ## In a Spec-driven tree
 
-What you draft is a change, or a file of an open change: its proposal, a spec change, its design or its tasks. Nothing is approved. A bug is recorded as in "Bugs", attached to the change whose work found it (its `parent` is the change's ID, its `testCase` the scenario whose test found it) or standalone; a fix that changes a requirement is made through a change.
+What you draft is a change, or a file of an open change: its proposal, a spec change, its design or its tasks. Nothing is approved. A defect is recorded as in "Defects", with its `source`, and needs no approval: one found while building is attached to the change whose work found it (its `parent` is the change's ID, its `testCase` the scenario whose test found it), and a reported one stands alone; a fix that changes a requirement is made through a change.
 
-- **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.
+- **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 `defect 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

@@ -5,7 +5,7 @@ description: "BuildKeel: Document code that existed before BuildKeel, area by ar
 
 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,19 +17,27 @@ 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**.
 
 If the user typed an area's name above, onboard that area. Ask one question at a time, each with your recommendation, and only for what you cannot work out. Two kinds of question carry no recommendation, because only the user knows the answer: which of two disagreeing sources is intended, and what a section nothing supports should say.
 
+Topics for this step, for each area, in this order:
+
+- **the artifacts** the area needs, and the kind of each where a stage holds more than one;
+- **each disagreement** between a source and the code, or between two sources;
+- **each required section** nothing supports.
+
+Work from the topics listed for this step. The user may answer in their own words, several topics at once or part of one. After each answer, say which topics it settled, with what you understood for each, and which are left; then ask the next one left, one topic per message. Where a topic has a default, list keeping it first, naming its actual value, and give examples where they help. Anything you work out that the user did not say is a proposal: ask it as that topic's question, with it as the default, and never use it without the user's answer. Ask about an unclear answer; name a conflicting one beside the earlier answer and ask which holds. Never guess. When every topic is settled, show all of it, as a review.
+
 ## Map the code
 
 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
 
@@ -48,24 +56,27 @@ Offer each area that is not onboarded yet as its own choice, in the map's order,
 
 Show a table of the artifacts the area needs, top down, in the team's stage names, each existing or to draft:
 
-| Level | Artifact | Version | From |
-|---|---|---|---|
-| Business idea | BI-01 "Self-service account recovery" | exists | |
-| Epic | "Password reset" | version 0 | the code, Confluence "Reset design" |
-| Design document | of that epic | version 1 | the code: no source has one |
-| Story | "Reset by email" | version 0 | the code, PAY-12 |
-| Test plan | of that story | version 1 | one test case per criterion |
-| Task | PAY-14 "Email template" | version 0 | finished in Jira |
-| Left out | PAY-31 "Reset by text" | | open in Jira: drafted with /bk-new when someone takes it up |
+| Level | Kind | Artifact | Version | From |
+|---|---|---|---|---|
+| Business idea | business idea | BI-01 "Self-service account recovery" | exists | |
+| Epic | epic | "Password reset" | version 0 | the code, Confluence "Reset design" |
+| Design document | | of that epic | version 1 | the code: no source has one |
+| Story | user story | "Reset by email" | version 0 | the code, PAY-12 |
+| Story | feature | "Reset by text" | version 0 | the code, PAY-20, labelled a feature |
+| Test plan | | of each story | version 1 | one test case per criterion |
+| Task | task | PAY-14 "Email template" | version 0 | finished in Jira |
+| Left out | | PAY-31 "Reset by security question" | | open in Jira: drafted with /bk-new when someone takes it up |
+
+When a stage holds more than one kind (`query` with `view: "process"` lists them), propose the kind of each artifact at that stage from where it came from, such as a ticket labelled a feature or a change to existing behavior, and say why in the table. The user confirms or changes each kind before anything is drafted; never pick one without their answer. Each is drafted with its kind as `type`, from that kind's template.
 
 Once the area's drafts are approved, or all but those waiting on a question left open, record every ticket you read for it with `manage`, `action: "map"`, `map: "tickets"`, the area and its `tickets`: each with its `key`, `link` and `title`, and either `outcome: "carried"` with the `artifact` it became (its approved ID), or `outcome: "left-out"` with `why`: `open`, `in-progress`, or `choice` when the team chose not to carry it over. Nothing read is left off the list.
 
 - Document every stage from the business idea down to the story, with the documents the process requires of each.
-- Tasks and bugs come in only when a source has them and they are finished: each as version 0, with its tracker key. Open or in-progress work is left out, and listed as such.
+- Tasks and defects come in only when a source has them and they are finished: each as version 0, with its tracker key. Open or in-progress work is left out, and listed as such.
 - 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
 
@@ -80,7 +91,7 @@ Only once the user agrees. Draft top down, parents before children, so each chil
 - 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. Offer both answers as equals and recommend neither: **The code is right; the ticket is out of date** and **The ticket is right; the code has a defect**. When the ticket is out of date, version 0 follows the code. When the code is wrong, see "Known defects" below. 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.
 - For each required section nothing supports, ask the user, one question at a time, with your tool for asking a question with choices: **Leave it empty** (listed first) or **Type it in**, and put no answer of your own in the choices. A version 0 may leave a section empty: the approval records it, and it can be filled in later.
 
-**Each finished task, and each bug fixed before BuildKeel**, is a version 0 too: `save_draft` with `type: "task"` or `"bug"`, `version: 0`, its `parent` the story or task it belongs to (a draft's ID is fine), and its tracker issue in `sources`. It is approved with the area, counts as done, and is linked to the commits before the baseline that name its key. Never record a bug that was already fixed as an open bug.
+**Each finished task, and each defect fixed before BuildKeel**, is a version 0 too: `save_draft` with `type: "task"` or `"defect"`, `version: 0`, its `parent` the story or task it belongs to (a draft's ID is fine), and its tracker issue in `sources`. It is approved with the area, counts as done, and is linked to the commits before the baseline that name its key. Never record a defect that was already fixed as an open defect.
 
 **Each version 1**, such as a design document or test plan no source has: draft it with `save_draft` and no `version`, from the code, as for any new artifact. It is held to its template, so it cannot leave a required section empty, and "Leave it empty" is never a choice for it. For each required section the code does not give, such as a design's context, ask the user, with what the code shows as a starting point they can accept or change: for code from before BuildKeel, "Built before BuildKeel; why is not recorded" is a fair answer when nobody knows.
 
@@ -88,7 +99,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,16 +107,16 @@ 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
 
-When the user says a drafted behavior is a defect, not what was intended: revise version 0 to state the intended behavior, and once the area is approved, record the defect as a bug against that story: `save_draft` with `type: "bug"`, `parent` set to the story's ID, `testCase` set to the test case that covers that criterion when the story's test plan has one, its Expected naming the criterion (its ID and text), and its Actual saying what the code does instead. Fixing it is then work like any bug, and a test matched to that test case is tagged as the fix changes it.
+When the user says a drafted behavior is a defect, not what was intended: revise version 0 to state the intended behavior, and once the area is approved, record the defect against that story: `save_draft` with `type: "defect"`, `parent` set to the story's ID, `testCase` set to the test case that covers that criterion when the story's test plan has one, its Expected naming the criterion (its ID and text), and its Actual saying what the code does instead. Fixing it is then work like any defect, and a test matched to that test case is tagged as the fix changes it.
 
 ## Version 0 under an existing artifact
 
@@ -121,15 +132,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.
-
-### Moving to Full SDLC
-
-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:
+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.
 
-- 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.
+### Moving to Full SDLC is not onboarding
 
-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-settings/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: bk-settings
+description: "BuildKeel: Show how this repository is set up: the mode, where the spec tree lives, the process and its gates, or the numbering, and each template with where it comes from. Changes nothing. Run as /bk-settings."
+---
+
+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.
+
+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: "settings"`.
+
+Show the user the result as it is, in your reply as normal text, with its table: do not summarize or reorder it.
+
+If the result says this repository is not set up for BuildKeel, tell the user how to set it up with /bk-init, and stop.
+
+Then offer, in plain text at the end of that reply, to show any one template in full, with an example from the list, such as the story or defect template. When the user names one, call `get_template` with its type and show it as it is.
+
+The settings are read here, never changed: they live in `buildkeel.yaml` and `templates/` in the spec tree. If the user wants to change one, say which file holds it, and that the change is made there and committed with the spec tree.

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

@@ -5,17 +5,19 @@ 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.
 
 The user typed: whatever follows /bk-stats in the user's message (nothing, if they typed only /bk-stats)
 
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
 ## Choose the period
 
 If the user typed a number of days, use it. If they typed off, on, delete or export, change the record as below.
 
-If the user typed nothing, ask straight away, before calling any tool: "Which period?" Offer the choices with your tool for asking a question with choices, if you have one:
+If the user typed nothing, ask straight away: "Which period?" Offer the choices with your tool for asking a question with choices, if you have one:
 
 1. **The last 30 days** (the default, listed first).
 2. **The last 7 days.**

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/{bug.md → defect.md}

@@ -1,10 +1,12 @@
 ---
-template: bug
-version: 2
-description: A defect. Attach it to the work and test case where it was found, or leave it standalone.
+template: defect
+version: 3
+description: "A defect: code that does not do what was agreed. Set source to reported (by users, customers or testers; approved before work on it starts) or found (while building or testing; the unit being built is its parent, with the test case that found it)."
 fields:
   title: { required: true }
+  source: { required: true }
   parent: { type: link }
+  requirement: {}
   testCase: {}
   severity: {}
   scope: { type: list }