buildkeel 0.4.0 → 0.6.0

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

@@ -9,6 +9,8 @@ Whenever a step says to show something and ask about it, write it out in your re
 
 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.
 
+It starts without the setup check other commands run first: a tree in an older format is one that check would send to /bk-init, and bringing it to the current format is this command's work.
+
 ## Upgrade the format first
 
 Call the BuildKeel `manage` tool with `action: "migrate"`, without `apply`.
@@ -23,7 +25,34 @@ If BuildKeel's session report, or `query` with `view: "process"`, says this spec
 
 In a Spec-driven tree, call `query` with `view: "onboarding"`. When it shows a conversion in progress, carry it on, as "Converting area by area" says. Otherwise, explain in a few lines what moving to Full SDLC means: work then goes through the team's stages, with approvals and gates, and the capability specs and archived changes are drafted into those stages, area by area, for the user to review and approve; the tree stays Spec-driven until every area is approved; and the move is one way. Then ask, with your tool for asking a question with choices: **Not now** (the default) or **Move this tree to Full SDLC**.
 
-If the user chooses to move it, call `manage` with `action: "convert"` and `convert: "start"`, without `apply`, and follow what it says: it refuses while any change is open, naming each with its title, and otherwise shows the process the tree will follow. Show it in your reply and ask the user to confirm, or to adjust the stages first. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only once they confirm, call it again with `apply: true`.
+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: **The agent 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.
+
+- **The agent 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: **The agent 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
 
@@ -38,6 +67,6 @@ If the user chooses to move it, call `manage` with `action: "convert"` and `conv
    - **Place the scenarios:** once the area is approved, show a table of each scenario and the criterion or test case it became, ask the user to agree it, and record it with `manage`, `action: "convert"`, `convert: "place"` and `place`. Leave a scenario out (`drop`) only when the user says so. A test tagged with a scenario counts for what that scenario became, so existing tests need no matching.
 3. **Switch.** Once every area is converted, the view says so: call `manage` with `action: "convert"` and `convert: "finish"`, without `apply`, and ask the user to confirm the switch, with what it says in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when they confirm, call it again with `apply: true`, and show the result as it is.
 
-The user can stop after any area: the next /bk-migrate carries on from there. While the conversion is in progress no change can be opened, and bugs and ad-hoc units work as usual. Before any area is approved, the conversion can be cancelled with `manage`, `action: "convert"` and `convert: "cancel"`, after the user confirms.
+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.
 
 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 found while building is the exception: it is recorded at once, with its permanent ID, and needs no approval; a defect reported by users, customers or testers is drafted and approved like the rest (see "Defects" below). In a Spec-driven tree every defect is recorded at once.
 
 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-build <ID>. If fixing it means a requirement must change, say so: that change is made as a new version of the story or task, approved as usual.
+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,9 +118,9 @@ 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. Every defect is recorded at once, as in "Defects", with its `source`, its permanent ID and 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). For a reported one, ask which requirement it affects: ask which files or behavior the report points to, call `query` with `view: "describes"` and those `paths`, and offer, with your tool for asking a question with choices, the requirements the changes it lists became (the first as the default), then **another: type its ID**, then **leave it standalone**. Put the chosen one in its frontmatter as `requirement: AUTH-R3`; a standalone one has none. 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`; 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.

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

@@ -13,6 +13,8 @@ What describes code from before BuildKeel is version 0 of its artifact: the arti
 
 The user typed: whatever follows /bk-onboard in the user's message (nothing, if they typed only /bk-onboard)
 
+**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 in place of "Onboard an area" and the sections after it.
 
 ## Choose what to do
@@ -24,6 +26,14 @@ Call the BuildKeel `query` tool with `view: "onboarding"`; it changes nothing. T
 
 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.
@@ -48,20 +58,23 @@ 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.
 
@@ -80,7 +93,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 +101,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, 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.
+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. Once it is approved, when the area has finished tasks and Build-ready tasks is on, call `manage` with `action: "backfill"` and `ids` set to those tasks: it drafts each one's as-built record from its linked commits. Say what each delivered, read from those commits, show the records, and write them with `apply: true` and `delivered` once the user agrees.
 
 ### 5. Existing tests
 
@@ -105,7 +118,7 @@ Call `query` with `view: "onboarding"` and ask which area to onboard next, as in
 
 ## 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
 

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

@@ -0,0 +1,56 @@
+---
+name: bk-pause
+description: "BuildKeel: Pause where you are, to come back in a new session or on another machine: the work on a unit or change, or an exploration with no unit, kept as a thread. Run as /bk-pause [nothing, or an ID], e.g. TK-013; the active unit when left out."
+---
+
+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.
+
+Pause the work with the user, so that it can be picked up again in this session, in a new one, or on another machine, by them or a teammate. It is one step wherever they come back: never ask where they will come back. Phrases such as "let's stop here" or "I'm switching machines" mean the same as this command. Nothing is ever discarded.
+
+The user typed: whatever follows /bk-pause in the user's message (nothing, if they typed only /bk-pause)
+
+**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.
+
+## What is paused
+
+- **A unit or change is active** (or the user named one): its work is paused, as "Pausing work" says.
+- **Nothing is active:** the conversation is an exploration, kept as a thread, as "Keeping a thread" says.
+
+## Pausing work
+
+1. **Uncommitted changes.** Run `git status` in the code repo. When files are changed, list them and ask, with your tool for asking a question with choices: **Commit them as work in progress** (the default), committed with the message `WIP: <what they hold>` ending with `BuildKeel-Unit: <the unit's ID>`, or **Leave them as they are**, named in the pause record. Never discard or stash anything.
+2. **Working notes.** Draft the working notes since the last checkpoint or pause, and check them, as below, steps 1 and 2.
+
+   **Working notes.** At this checkpoint, draft the working notes since the last checkpoint or pause: what the work learned that the code and the spec do not say. Each is one of these: a decision and why (with `replaces` naming an earlier decision it replaces), a constraint or pitfall, a dead end (what was tried, and why it failed), an open question, or the next step. Rulings are kept already. Give each its source: the user's own words, copied exactly, as `quote`; a `file` and `line`; or a `record`, such as a requirement, a finding or a commit. Never record an inference about a person, such as what they seem to prefer. With nothing new to note, leave notes out.
+   1. **BuildKeel's check:** call `save_draft` with `type: "working-notes"`, the unit's or change's `id` and the `notes`, without `apply`. It says which pass, and drops the rest with the reason.
+   2. **The note checker:** give it the notes that passed in one batch, with their sources and nothing else, started in the note checker role as `query` with `view: "settings"` names it. When it cannot be started, follow "When agents can't be started": check each yourself as the checker would, and say the notes were checked here. Keep only the notes it supports, and tell the user each one dropped, with why.
+   3. **Keep them** as this step says. At a checkpoint, the result lists what was kept: show that list in the same reply, without asking first; the user may ask to correct or drop any of it. A pause shows them first, and keeps them once the user agrees.
+3. **The pause.** Call `manage` with `action: "pause"`, the `id` when the user named one, `notes` with the notes the checker supports, and `next` with the next step in a sentence. Show what it would record, in full, with the working notes and their sources, and ask. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only once the user agrees, call it again with `apply: true`.
+4. **Push.** Say what the result says about pushing, and offer to push both the code repo and the spec repo (one push when the spec tree is in the code repo), so the work can be resumed on another machine. The user may decline: then say it can only be resumed on this machine until they push.
+5. **Done.** Say in a line that it is paused, and that /bk-resume with its ID resumes it.
+
+**When agents can't be started,** the same everywhere:
+1. **Say why, once,** in a line: you have no tool for starting agents here, it is turned off, or the model tier the settings name is not available.
+2. **Retry once** when an agent started but failed, before treating agents as unavailable.
+3. **Follow the step's switch:** off, nothing happens; ask, the offer says it would run here, without a fresh reader; auto, or a step with no switch (an implementer or a reviewer), do it here and say so in a line.
+4. **Label what you did here** as done here, not by an independent agent: in what you show, and in the record (`by: "author"` for a review), and present a question or proposal as your own reading.
+5. **Never count it where independence is the point:** a final review done here does not satisfy the review-findings check, so say the work was not independently reviewed.
+
+## Keeping a thread
+
+An exploration with no unit is kept as a thread: its ID, such as TH-004, stays with it, and it has no stages and no approval. First call `manage` with `action: "pause"` and no `id`: it says what the Threads switch asks for.
+
+- **ask**, the default: the steps below, saving only once the user agrees.
+- **auto:** the same steps, but save it with `apply: true` without asking, then show it in full and say its ID.
+- **off:** save nothing. Say so in a line, and suggest /bk-capture when the idea is ready. Open threads stay, and can still be resumed, captured or dropped.
+
+1. **Draft it** from the whole conversation. If BuildKeel said this conversation was compacted and the exploration is not saved, read the whole transcript on disk first, and build the thread from it rather than from the summary; then pass `fromTranscript: true`. When this pause adds to a thread resumed in this conversation, use its ID. Its `content` follows the thread template (`get_template` with `type: "thread"`): the intent and the idea; the approaches, and which way the discussion is leaning; decisions and constraints; dead ends and open questions; the next thing to discuss; and, apart from your proposals, the user's own words, each a bullet with their words in quotes, exactly as they wrote them. Add the code read, as pointers, and any spike, with its branch or the files it left. Write "None yet" in a section the conversation has nothing for. Give the decisions, constraints, dead ends and open questions as `notes` too, each with its source, as working notes are. Never record an inference about a person.
+2. **Check it:** call `save_draft` with `type: "thread"`, a short `title` (or the `id` of the thread it adds to), the `content` and the `notes`, without `apply`. It checks each of the user's words and each note's source, and leaves out what does not hold, with the reason: tell the user each. Give the notes that pass to the note checker, as "Pausing work" says, and keep only those it supports.
+3. **Show it** in full, and ask. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only once the user agrees, call it again with `apply: true`, and tell the user the thread's ID. With Threads set to auto, save it first, then show it with its ID.
+4. **Push.** Offer to push the spec repo, so the thread can be resumed on another machine or by a teammate. Threads are visible to the team once pushed.
+
+When the user drops an idea instead, ask for the reason in their words, then call `save_draft` with `type: "thread"`, its `id` and `drop` set to the reason: it is closed, and can still be found.
+
+Do not create or edit spec tree files yourself: the BuildKeel tools write every record.

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

@@ -0,0 +1,35 @@
+---
+name: bk-resume
+description: "BuildKeel: Resume paused work: a unit, a change or a thread, by its ID, or pick from what is paused, the most recent first. Run as /bk-resume [nothing, or an ID], e.g. TK-013 or TH-004, 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.
+
+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.
+
+Resume paused work with the user: a unit or change, where it was left, or a thread, the exploration it holds.
+
+The user typed: whatever follows /bk-resume in the user's message (nothing, if they typed only /bk-resume)
+
+**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.
+
+## What to resume
+
+- **Nothing:** call `query` with `view: "paused"` and show the list as it is: each one with who paused it, when, and its next step, the most recent first. Ask which to resume, the most recent as the default. With nothing paused, say so.
+- **An ID:** resume that one.
+
+If the spec tree is behind its remote, say so and offer to pull it first (the default), so that work paused on another machine is here.
+
+## A unit or change
+
+Call `start_work` with its `id`.
+
+- **Paused by someone else, or on another machine:** the result says whose work it was and when it was paused. Ask the user to confirm, in their words, such as "Take over Priya's work on TK-013, paused two hours ago?" Only once they confirm, call `start_work` again with `takeOver: true`: the work moves to them, and the handover is recorded. If they decline, change nothing.
+- **Uncommitted changes:** handle them as /bk-build does.
+- **Started:** show the brief it returns first: where things stand, the decisions and dead ends, the open questions, the next step, and any files left uncommitted on another machine. Then go on as /bk-build goes on with a unit or change it has started: ask how to build what is left.
+
+## A thread
+
+Call `query` with `view: "threads"` and its `id`. Show its brief: the idea, the approaches, the decisions and dead ends, the open questions, and the next thing to discuss, with whose thread it is when someone else kept it. Then let the conversation go where the user takes it: a thread has no stages and no approval. Pausing again adds to it, and capturing it with /bk-capture closes it.
+
+Do not create or edit spec tree files yourself: the BuildKeel tools write every record.

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

@@ -0,0 +1,56 @@
+---
+name: bk-review
+description: "BuildKeel: Review the work on a unit or change with fresh reviewers: spec compliance by ID, code quality, and tests that try to break it. The active unit by default. Run as /bk-review [an ID, or a range of commits], e.g. TK-001, CH-012 or main..HEAD; 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.
+
+Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
+
+Review work with the user, by fresh reviewers who did not write it and do not see this conversation. A review changes no code: it finds, and the user decides what to do about each finding.
+
+The user typed: whatever follows /bk-review in the user's message (nothing, if they typed only /bk-review)
+
+**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.
+
+## What to review
+
+What the user typed decides it:
+
+- **Nothing:** the active unit in this working tree, or in a Spec-driven tree the active change. With neither, ask straight away what to review, offering the units and changes with work on them, from `query` with `view: "status"`.
+- **A unit's or change's ID**, such as TK-001 or CH-012: that unit or change, its own commits only.
+- **A range of commits**, such as `main..HEAD`: those commits. A range belongs to no unit, so its review is shown and never recorded, and there is no spec to judge it against: only the quality reviewer and the break-it agent run.
+
+## Review it
+
+Say in a line what is reviewed: the unit or change, or the range, and how many commits. Then review it with `kind: "on-demand"`.
+
+A review is done by three fresh agents: the spec reviewer, the quality reviewer and the break-it agent. None of them is the agent that wrote the code, and none sees this conversation.
+
+1. **The packages.** Call `review` with `action: "input"`, the `id` (and in a change, the `task` when one task is reviewed), and the `kind` of this review: `kind: "after-task"` in a run, `kind: "final"` at finishing, `kind: "on-demand"` when the user asks. It says which reviewers to start, and only those: each reviewer that is switched on, and at finishing only the commits since the last review, with one spec-compliance review of the whole change when its tasks were reviewed in a run. It writes each one's package, the diff and the reviewer's view, to a folder, and prepares the break-it agent's worktree when break-it runs. When it says nothing is to be reviewed, review nothing, and say so in a line, with why.
+2. **The reviewers.** Call `query` with `view: "settings"`, if you have not in this conversation: it names the agent to start for each role, with the model and effort to pass on this host. Start the reviewers the input names: after a task, the spec reviewer and the quality reviewer; at finishing, the final spec reviewer and the final quality reviewer; and the break-it agent. Give each the folder the input names for it and nothing else, and the break-it agent its worktree too. They can run at the same time.
+3. **Record each report as it is,** with `review`, `action: "record"`, the same `id` (and `task`), the `reviewer` (spec, quality or break-it), the `kind` of this review, and the report's lists: its verdicts, findings, proposed additions, what was done well and its verdict, or the break-it agent's failing tests. Never change a finding's severity or wording.
+4. **When a reviewer cannot be started,** follow "When agents can't be started": review it here, as each reviewer's instructions would, and record each report with `by: "author"`. Say in a line that it was reviewed by the author, so it does not count as an independent review.
+5. **Answer each finding.** Check it against the code first: never accept a finding only because a reviewer made it. Then answer it with `review`, `action: "answer"` and the `finding`'s ID:
+   - **fixed,** with the `commit` that fixed it;
+   - **parked,** once the user agrees to handle it later: record it as a defect found while building the unit with /bk-new defect (in Spec-driven mode, linked to the change), then answer with `parkedAs` set to its ID;
+   - **rejected,** with the `evidence`: the code, a test or the spec that shows it is wrong. Show the user each finding you reject, with its evidence.
+
+   A Low finding may stay open: name it at the end.
+6. **The break-it agent's failing tests** count only through their test. For each, ask the user, recommending one: **a defect found while building** (record it as in "parked", with the test as its regression test) or **a question about the spec**, where the agreed behavior is what is wrong. Tests that pass are discarded, never committed.
+7. **Proposed additions to the spec** are behavior the spec is silent on. Show them apart, never as a requirement not met: the user decides whether to add each, and an addition goes through the same review as any change to the spec.
+
+**When agents can't be started,** the same everywhere:
+1. **Say why, once,** in a line: you have no tool for starting agents here, it is turned off, or the model tier the settings name is not available.
+2. **Retry once** when an agent started but failed, before treating agents as unavailable.
+3. **Follow the step's switch:** off, nothing happens; ask, the offer says it would run here, without a fresh reader; auto, or a step with no switch (an implementer or a reviewer), do it here and say so in a line.
+4. **Label what you did here** as done here, not by an independent agent: in what you show, and in the record (`by: "author"` for a review), and present a question or proposal as your own reading.
+5. **Never count it where independence is the point:** a final review done here does not satisfy the review-findings check, so say the work was not independently reviewed.
+
+For a range, skip recording: show each reviewer's report as it is, and stop there.
+
+## Show it
+
+Show each reviewer's report in a few lines: the verdicts by ID, the findings by severity with their files and lines, the failing tests, the proposed additions, and the quality reviewer's verdict. Then say what you checked against the code for each High and Medium finding, and ask the user how to answer them, one at a time, with your recommendation first: fix it now, park it as a defect, or reject it with its evidence. 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.
+
+Do not create or edit spec tree files yourself: the BuildKeel tools write every record.

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, the checks, agents and thread offer, 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, and the copy paths in this repository's `.buildkeel.yaml`. 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

@@ -11,11 +11,13 @@ Show the user their own use of BuildKeel in this spec tree, from the record kept
 
 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/templates/adr.md

@@ -0,0 +1,31 @@
+---
+template: adr
+version: 1
+description: An architecture decision record, for a decision that is hard to reverse, surprising without its context, and the result of a real trade-off. Once accepted it is never edited; a new ADR replaces it.
+fields:
+  title: { required: true }
+  replaces: { type: link }
+  shapes: { type: list }
+sections:
+  Context: { required: true }
+  Decision: { required: true }
+  Alternatives: { required: true }
+  Consequences: { required: true }
+  Notes: { offered: "Background, links, and anything from a source that fits no other section." }
+---
+
+## Context
+
+<!-- The situation and the forces at play that made a decision necessary. -->
+
+## Decision
+
+<!-- What was decided, in one or two sentences. -->
+
+## Alternatives
+
+<!-- One line per alternative weighed, with why it was not chosen. -->
+
+## Consequences
+
+<!-- What becomes easier and what becomes harder, including what the team now has to live with. List the requirements and designs it shapes in the shapes field. -->

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 }

package/antigravity/templates/design.md

@@ -1,6 +1,6 @@
 ---
 template: design
-version: 1
+version: 2
 description: How a stage's work is built, and the decisions behind it. Fill in what applies; add an offered section only when the work needs it.
 fields:
   parent: { required: true, type: link }
@@ -11,6 +11,7 @@ sections:
   Design: { required: true, tracked: true }
   Decisions: { tracked: true }
   Risks and trade-offs: {}
+  Approaches: { offered: "The approaches considered, the one chosen and why, and the non-goals and things to avoid, from the conversation only." }
   Architecture: { tracked: true, offered: "The components, how they connect, and where each one runs." }
   Data: { tracked: true, offered: "What is stored, its shape, and how it changes over time." }
   Interfaces: { tracked: true, offered: "The APIs, events and contracts other code relies on." }

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

@@ -1,6 +1,6 @@
 ---
 template: proposal
-version: 1
+version: 2
 description: Why a change is made, what it changes, and which capabilities it adds or alters. Its spec changes say exactly how behavior changes.
 fields:
   title: { required: true }
@@ -11,6 +11,7 @@ sections:
   What changes: { required: true }
   Capabilities: { required: true }
   Impact: { required: true }
+  Approaches: { offered: "The approaches considered, the one chosen and why, and the non-goals and things to avoid, from the conversation only." }
   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." }