buildkeel 0.5.0 → 0.6.0

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

@@ -31,9 +31,12 @@ Once that check is done, and before any other tool call, sum up the discussion i
 
 - **What you set out to do**: the user's intent, in a sentence.
 - **The idea**: what it is, and who it is for.
-- **The approach**: the design choices and decisions discussed, and what was left open.
+- **The approaches**: the ways weighed, the one chosen and why, or that only one was discussed.
+- **The design choices**: the decisions discussed, and what was left open.
 - **Pitfalls and constraints raised**: each one the conversation surfaced, such as a limit, a failure to handle or a detail easy to get wrong, in the user's terms, marked settled or open. Leave the list out when nothing was raised; never add one the conversation did not raise.
 
+Keep what the user said apart from what you proposed, so they can tell them apart: mark each point "you said" or "I proposed". When this session resumed a thread with /bk-resume, draw on the thread's brief and on the conversation since, and say which thread it is.
+
 If the user typed something above, sum up that part of the conversation. If there is nothing to capture yet, say so, ask what they want to plan, and stop. If the conversation was compacted, say that its earlier parts may be missing from the summary, and ask the user to add anything left out.
 
 Then ask whether to go on, with the summary in that same reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices:
@@ -102,6 +105,15 @@ Ask, every time, how the user wants to go through the drafts. Never assume it, a
 
 ## 4. Draft
 
+Before drafting, call `query` with `view: "planning"`, once in this capture: it says, by the team's switches, what to do about edge-case suggestions and design options, off, ask or auto. Follow it as "Edge-case suggestions" and "Design options" say.
+
+**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.
+
 ### How to draft
 
 - Draft top down, parents before children, so each child names its parent's draft ID. Call `get_template` once for each type you draft, and follow it.
@@ -112,26 +124,35 @@ Ask, every time, how the user wants to go through the drafts. Never assume it, a
 - A design document has no `id`; its `parent` is the artifact it describes. Add an offered section (`get_template` lists them) only when the discussion covered it.
 - When the work changes how an existing capability works: save the new version of that capability's document with `save_draft` and its ID, and give the new artifact `changes: [<that document's ID>]`, so it cannot be finished until that version is approved.
 - A **version 0** in the plan is drafted before the change, by the rules below, with `save_draft` and `version: 0`. Name the paths it covers in its `scope`. Then draft the change: as its version 1, with `save_draft`, the version 0's draft ID as `id` and no `version`, holding the whole artifact as it will be after the change. Start from version 0's text as saved, with its entry IDs: keep the ID of every entry that stays, changed or not (a criterion whose limit changes keeps its ID), and write `{{new}}` only for an entry the change adds. Or, when the change is new work under it, as a new artifact whose `parent` is that draft ID.
-- Save each one with `save_draft`, and only once the user has agreed to it.
+- **Approaches.** Fill the design document's Approaches section from the conversation: the approaches considered, the one chosen and why, and the non-goals and things to avoid. When no other approach was weighed, say so there. Add no approach, reason or goal the conversation did not raise. When the set has no design document, show the approaches as working notes on the top new artifact, in the same review, and once the user agrees, save them after it with `save_draft`, `type: "working-notes"`, its ID, `apply: true` and each one's source (the user's words as `quote`).
+- **Edge-case suggestions.** After drafting each story's test plan, and before showing it, have edge-case suggestions look for the cases nobody has written yet, as the planning view says: when it runs, start the edge-cases agent, in the edge-case suggestions role as `query` with `view: "settings"` names it, with the plan, the criteria it covers and the team's practices (`get_context` with `role: "planning"` and the story's ID), and nothing else. When it cannot be started, follow "When agents can't be started": look for them yourself, and label them as your own reading. Show its proposals in the same review as the plan: at most five, ranked by risk, each with the criterion it belongs to, the case and a one-line reason, and how many more it found at lower risk, to show if the user asks. The user answers once, such as "add 1 and 3", "all" or "none": add those to the plan, and ask nothing more about them. It proposes nothing a practice already covers.
+- Save each one with `save_draft`, with `capture: true`, and only once the user has agreed to it.
 
 ### Step by step
 
-Go through the plan in this order, leaving out what already exists: a version 0 before the change built on it, then the business idea or epic, then its design document, then each story together with its test plan, then the tasks, with their own test plans, as one batch. For each one:
+Go through the plan in this order, leaving out what already exists: a version 0 before the change built on it, then the business idea or epic, then its design document, then each story together with its test plan, then the tasks, with their own test plans, as one batch. Before the tasks, follow "Design options" when they are due. For each one:
 
 1. Draft it against the artifacts already saved in this capture.
 2. Show it, with a line naming the pitfalls and constraints from the summary that it covers. Ask about each gap it has, as "Gaps" says, before going on.
 3. Ask, with it in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices: **Looks good, next** (the default), **Change something** (feedback, as "How each review goes" says: the points with how each was addressed, then the final version), and **Draft the rest at once** (draft what is left in one go, then show it as a set).
 4. Save it with `save_draft` once the user agrees, before drafting the next.
+5. **The approaches, when the set has no design document:** right after saving the top new artifact, show the approaches weighed as working notes on it (each a decision, with the user's words as its `quote`), and keep them once the user agrees with `save_draft`, `type: "working-notes"`, its ID and `apply: true`. Keep them out of its Notes section: working notes are what later work and reviews find.
 
 If the user stops partway, what they agreed to stays saved as drafts; draft nothing more.
 
 ### All at once
 
-Draft everything, asking about gaps as you go. Show the set in full, each artifact with the pitfalls it covers, then a table of them all: title and the pitfalls each covers. Take the set through the review: feedback on any of them is answered as "How each review goes" says, with the final version of each artifact it changed. Once the user agrees, save them with `save_draft`, top down, each child naming the draft ID its parent was given.
+Draft everything, asking about gaps as you go. Show the set in full, each artifact with the pitfalls it covers, then a table of them all: title and the pitfalls each covers. Take the set through the review: feedback on any of them is answered as "How each review goes" says, with the final version of each artifact it changed. Once the user agrees, save them with `save_draft`, top down, each child naming the draft ID its parent was given. When the set has no design document, show the approaches as working notes on the top new artifact in the same review, and keep them after it is saved, as step 5 of "Step by step" says.
+
+### Design options
+
+Design options are due before the tasks are drafted, for the interface the set's work shares most, when three or more tasks would use it or it crosses from one code repository to another. Then do as the planning view says: offer them once in one line (ask), start them and say why in one line (auto), or nothing (off). The offer is a line of plain text at the end of your reply, on its own: never in your tool for asking a question with choices, and never together with a gap or another question. If the user declines the offer, offer nothing more in this capture, and draft the tasks against it as discussed. The user can ask for design options for any interface at any time.
+
+When they run, start as many designer agents as the settings give for design options (2 by default), in the designers role as `query` with `view: "settings"` names it, at the same time, each with the interface, the work that uses it, and its own angle: the smallest interface, then one built for the most common use, then the most flexible one, then others of your choosing. When they cannot be started, follow "When agents can't be started": draft the designs yourself, and label them as your own. Compare them on how much each hides behind a small interface, where changes and defects would collect, and where the seams go, and recommend one, saying why. Record the one chosen and those set aside in the Approaches section, as approaches, with the user's reason for the choice.
 
 ### Gaps
 
-A gap is what a draft needs that the conversation did not settle: a required section, a pitfall raised but left open, or a detail the artifact cannot do without. For each gap, tell the user what is missing and where, and ask, with no recommendation, since only the user knows. The choices, in this order:
+A gap is what a draft needs that the conversation did not settle: a required section, a pitfall raised but left open, or a detail the artifact cannot do without. For each gap, tell the user what is missing and where, and ask, with no recommendation, since only the user knows. Ask about one gap at a time, and wait for the answer before the next: never several gaps in one question, or in one use of your tool for asking a question with choices. The choices, in this order:
 
 1. **Put it in the spec as stated**: write it as a requirement, criterion or test case, in the user's words.
 2. **Record it as an open question**: add it to the artifact's Open questions section, to settle later. It does not block approval.
@@ -150,13 +171,20 @@ Version 0 describes what the code does today, as if BuildKeel had been used from
 - When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended, before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded against it with /bk-new defect once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
 - Supported means the code or a source says it. A plausible guess is not support: who a story is for and why, a business idea's problem and goals, or a design's context are rarely in the code. Leave a required section empty when nothing supports it, and do not ask about it here: `save_draft` lists what version 0 leaves empty, and the reviewer sees it.
 
-## 5. What is left
+## 5. Close
+
+1. **The readiness check.** Call `query` with `view: "readiness"` and `ids` set to every artifact agreed in this capture, and do as its line says, by the team's switch: offer the check in one line of plain text, on its own, saying why (ask), run it and say why in one line (auto), or say nothing about it (off). Small work is skipped, with a line saying so. When it runs, or the user agrees to it or asks for it ("run the readiness check"), start the readiness readers as the result says, one round only. When they cannot be started, follow "When agents can't be started": ask the questions yourself, from each reader's angle, labeled as your own reading. Merge the questions more than one reader asked into one, naming the readers who asked it. Sort the questions:
+   - **already answered** in the set or the conversation: show the answer as an edit to the artifact it belongs in, and save it once the user agrees;
+   - **minor:** settle it yourself, and show it labeled "my call", as an edit taken through the same review;
+   - **the user's to answer:** list them all together, the most important first, then ask them one at a time, each with your recommendation.
 
-List each pitfall or constraint from the summary that no saved artifact covers, and treat each as a gap, as above. Then show what was drafted as a table: ID, title, and its open questions, if any.
+   It changes nothing the user has not agreed to.
+2. **Gaps.** List each pitfall or constraint from the summary that no saved artifact covers, and treat each as a gap, as above. Then show what was drafted as a table: ID, title, and its open questions, if any.
+3. **A resumed thread.** When this capture started from a thread, close it with `save_draft`, `type: "thread"`, its `id` and `captured` set to the top artifact saved, and say so in a line: the thread links to what it became.
 
 ## 6. Approve them, or leave them as drafts
 
-Agreeing to an artifact here does not approve it: approving is a separate choice, with permanent numbers and frozen versions. Once the last artifact is agreed, ask in plain text, at the end of the reply with the table: **Approve them now** (the default), or **Leave them as drafts**, for another approver to approve later with /bk-approve.
+Agreeing to an artifact here does not approve it: approving is a separate choice, with permanent numbers and frozen versions. Once the close is done, ask in plain text, at the end of the reply with the table: **Approve them now** (the default), or **Leave them as drafts**, for another approver to approve later with /bk-approve.
 
 - **Approve them now:** call the BuildKeel `approve` tool with `ids` set to every artifact agreed in this capture, without `apply`. Name a version 0 with `@v0`, such as `US-draft-k3x9@v0`, and keep the version built on it in the set too. A task's own test plan is not in the set unless the process approves task plans: it is recorded when its task is approved. Show the set as `approve` gives it, in the order it will be approved, with what each will become and anything that would not pass, and why. Then ask: **Approve them** (the default; any that would not pass stay drafts), **Fix what would not pass first** (each fix shown and saved with `save_draft` once the user agrees, then the set checked again), or **Stop**. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when the user confirms, call `approve` again with the same `ids` and `apply: true`, and show the result as it is.
 - **Leave them as drafts:** approve nothing. Say that the drafts wait for /bk-approve, which shows them as one set.
@@ -176,6 +204,10 @@ The plan is one change: a proposal, a spec change for each capability whose beha
    - **A new title.** When the revision changes what the change is about, show its current title beside the one you propose, and ask whether to change it. Change it only when the user agrees: the proposal is saved with the new title, and the change's folder is renamed with it. If the user says the title still fits, keep it.
 3. **Ask the pace**, as in step 3 above: **Step by step** (the default) or **All at once**, every time.
 4. **Draft the change.** Call `get_template` for proposal, spec-change, tasks and, when needed, design. Draft by "How to draft" and "Gaps" above: each settled pitfall becomes a requirement or scenario, and nothing is invented. A modified requirement keeps its ID and holds its full new text; a removed one says why and what replaces it. Each task says how its completion is verified, and each group holds the tests and docs its work needs.
-   - **Step by step:** show the proposal, with the pitfalls it covers, and save it once the user agrees, with `save_draft`, `type: "change"` and the proposal as `content`: that creates the change. Then each spec change, then the design if one is needed, then the tasks, each shown, agreed and saved in turn with `save_draft`, its `type` (`spec-change`, `design` or `tasks`) and the change's `id`. Offer **Looks good, next** (the default), **Change something** and **Draft the rest at once** at each step, and answer feedback as "How each review goes" says.
-   - **All at once:** show the whole change in full and take it through the review. Once the user agrees, save it in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`.
-5. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Treat each pitfall from the summary that no file covers as a gap, and each missing part `save_draft` names. Then offer /bk-build with the change's ID as the next step.
+   - **Approaches.** Fill the proposal's Approaches section from the conversation, as "How to draft" says, and its Non-goals with what the change deliberately leaves out.
+   - **Edge-case suggestions for scenarios.** After drafting each spec change, have edge-case suggestions look for the scenarios nobody has written yet, as "How to draft" says for a test plan, with the change's requirements and their scenarios, and show its proposals in the same review.
+   - **Design options**, before the tasks, as "Design options" says.
+   - **Step by step:** show the proposal, with the pitfalls it covers, and save it once the user agrees, with `save_draft`, `type: "change"`, `capture: true`, the proposal as `content`, and, when this capture started from a thread, `thread` with its ID: that creates the change, which names the thread. Then each spec change, then the design if one is needed, then the tasks, each shown, agreed and saved in turn with `save_draft`, its `type` (`spec-change`, `design` or `tasks`) and the change's `id`. Offer **Looks good, next** (the default), **Change something** and **Draft the rest at once** at each step, and answer feedback as "How each review goes" says.
+   - **All at once:** show the whole change in full and take it through the review. Once the user agrees, save it in one `save_draft` call with `type: "change"`, `capture: true`, the proposal as `content`, the others in `files`, and `thread` when it started from one.
+5. **Close**, as step 5 above says, with `query`, `view: "readiness"` and the change's `id` for the readiness check; a thread the change names is closed with it.
+6. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Treat each pitfall from the summary that no file covers as a gap, and each missing part `save_draft` names. Then name the change with its title, and offer /bk-build with the change's ID as the next step. Nothing in a Spec-driven tree is approved.

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

@@ -29,13 +29,44 @@ A story built through tasks, an epic, or a stage the team added above its storie
 ## Check it
 
 1. If the code changed since the tests last ran, run them again with a JUnit XML report (BuildKeel's instructions list the reporter for each test runner) and record the report with the BuildKeel `test_results` tool.
-2. Call the BuildKeel `finish_work` tool without `apply`, with `id` if the user named a unit. It runs the done gate and writes nothing.
+2. Draft the unit's working notes since the last checkpoint, and check them, as "Working notes" below says, steps 1 and 2; and draft what its context adds to them: departures from the plan (spec changes made while building included), known limitations, follow-ups with their IDs, and notes for the next person who touches the code, each from this conversation or the records, never invented.
+3. Call the BuildKeel `finish_work` tool without `apply`, with `id` if the user named a unit, `notes` with the notes the checker supports, and `context` with what it adds (`departures`, `limitations`, `followUps`, `forNext`). It runs the done gate and writes nothing.
+   - **A check on the tests not run yet:** when the result says the revert check, or mutation testing, has not run yet, run it first, once, without asking, then call `finish_work` without `apply` again. For the revert check: call `manage` with `action: "revert-check"`, run the unit's tagged tests in the worktree it prepares, from that directory, with a JUnit XML report written there (it links the dependencies the main checkout has installed: never install, update or remove a package through a link, and install in the worktree only where it says to), and record it with `test_results` and `purpose: "revert-check"`; when the tests cannot run there, remove the worktree with `remove: true` and say why. For mutation testing: run the command the result names, and record its report with `test_results` and `purpose: "mutation"`.
    - **Refused only because tests have no current result** (not run, or run before the code last changed): run the tests with a JUnit XML report, record it with `test_results`, and call `finish_work` without `apply` again. Do this once, without asking.
    - **Refused by the done gate** for anything else: show every failing check with its fix, as it is, and where each test case stands. Offer the fix that comes first: commit uncommitted changes (ending the message with `BuildKeel-Unit: <ID>`), write a test that is missing its tag, fix a failing test, or run the tests again. Do not finish anything else in its place.
    - **Not the active unit, or no active unit:** show the message and its fix.
    - **A story or epic refused because work under it is open:** show every open unit with its fix, and where each test case stands. Offer to start the first open unit with /bk-build.
-   - **Ready:** show what finishing will record: the commits, the files, each test case's result, and any test cases left for the story. For a story or epic: the units under it and where each test case passed.
-   - **A standalone defect:** the result also says which stories its changes belong to. Ask where to attach it, with your tool for asking a question with choices: **the story it suggests** (the default), then each task it names, then **leave it standalone**. Pass the chosen ID in `attach` when you finish.
+   - **The final review not run yet:** when the result says the unit has no final review, review it now, before showing anything else, as "The final review" says, then call `finish_work` without `apply` again. It always runs, whatever the settings say of reviews after each task.
+   - **Ready:** show what finishing will record: the commits, the files, each test case's result, the findings and how each was answered, the context part (decisions, those replaced, departures, dead ends, limitations, follow-ups and notes for the next person), and any test cases left for the story. For a story or epic: the units under it and where each test case passed.
+   - **A standalone defect,** in a Spec-driven tree: the result names the requirements the files it changed implement. Ask which requirement to link it to, with your tool for asking a question with choices: **the requirement it suggests** (the default), then each other one it names, then **leave it standalone**. Pass the chosen requirement in `link` when you finish.
+
+## The final review
+
+Review the whole unit, or the whole change, with `kind: "final"`, as follows. In a Spec-driven tree, the reviewers judge the change's code against its requirements, scenarios and design.
+
+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.
+
+A High or Medium finding still open is shown with the finish, which reports it: offer **Fix first** as the default. Fix it as the build's fix loop does, then preview again.
 
 ## A defect closed without a fix
 
@@ -53,7 +84,16 @@ Ask the user, the default first, with what the result said in your reply. Show i
   1. **Finish <ID>** (the default).
   2. **Stop, and do not finish yet.**
 
-Only when the user confirms, call `finish_work` again with `apply: true` (and the same `id` if you passed one), with `exclude` listing the IDs of any commits they left out, and with `attach` when they chose where to attach a standalone defect.
+Only when the user confirms, call `finish_work` again with `apply: true` (and the same `id` if you passed one), with `exclude` listing the IDs of any commits they left out, with `link` when they chose a requirement for a standalone defect, and with the same `notes` and `context` as the preview. If it is refused because the preview was not seen or something changed since, call it again without `apply`, show the new result, and ask again.
+
+### Working notes
+
+Finishing is a checkpoint.
+
+**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.
 
 ## Afterwards
 
@@ -65,14 +105,15 @@ Do not create or edit spec tree files yourself: `finish_work` writes the record,
 
 ## In a Spec-driven tree
 
-A change is finished by archiving it, and need not be the active unit. With none named and none active, `finish_work` lists the open changes: ask which to finish, allowing several, those with every task ticked first. Call `finish_work` without `apply` (with `ids` for several) and follow its result step by step:
+A change is finished by archiving it, and need not be the active unit. With none named and none active, `finish_work` lists the open changes: ask which to finish, allowing several, those with every task ticked first. Call `finish_work` without `apply` (with `ids` for several; for one change, with `notes` and `context` drafted as "Check it" step 2 says) and follow its result step by step:
 
-1. **Unticked tasks first.** When it lists unticked tasks, check each against the code and the test results before showing anything else. Say in a line each which now pass their verification, and offer to tick them. Tick those the user agrees to with `save_draft`, `type: "tasks"`, the change's `id` and `tick`, then preview again.
-2. **Review and show.** Review the code against the change, and report it labeled as your judgment. In the same reply, show what finishing will write, as the result gives it: the capability specs after the merge, with the requirements the change adds or modifies in full and the others by name.
-3. **Ask.** End that reply with the choice, in plain text: **Fix first** or **Finish anyway**, fix first being the default when anything is reported missing. When your review finds a gap where the code is right and the spec is not, also offer **Reword the spec, then finish**. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Nothing blocks the finish but uncommitted work.
+1. **Checks on the tests.** When the result says the revert check, or mutation testing, has not run yet, run it first, once, without asking, as "Check it" says above, then preview again.
+2. **Unticked tasks first.** When it lists unticked tasks, check each against the code and the test results before showing anything else. Say in a line each which now pass their verification, and offer to tick them. Tick those the user agrees to with `save_draft`, `type: "tasks"`, the change's `id` and `tick`, then preview again.
+3. **The final review, and show.** Review the change as "The final review" says, if it has no final review yet. Then show each requirement and scenario as met, partly met or not met with its evidence, the findings with how each was answered, and the break-it agent's failing tests. In the same reply, show what finishing will write, as the result gives it: its context part, the capability specs after the merge, with the requirements the change adds or modifies in full and the others by name.
+4. **Ask.** End that reply with the choice, in plain text: **Fix first** or **Finish anyway**, fix first being the default when a High or Medium finding is open or anything is reported missing. When your review finds a gap where the code is right and the spec is not, also offer **Reword the spec, then finish**. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Nothing blocks the finish but uncommitted work.
    - **Fix first:** help fix it.
    - **Reword the spec:** show the requirement's new text in full, with why, and save it only once the user agrees, with `save_draft`, `type: "spec-change"`, the change's `id`, its `capability` and `requirement`.
    - After any commit or change, call `finish_work` without `apply` again, and ask on the new preview, never on the old one.
-4. **Finish.** Call `finish_work` with `apply: true` as the result says. When the change was finished anyway with tasks or gaps left open, the result lists them: offer a follow-up change holding them. If the user agrees, draft it as /bk-capture drafts a change, from its proposal, through the review; if not, they stay recorded with the archived change.
+5. **Finish.** Call `finish_work` with `apply: true` as the result says, with `review` holding a line per change that sums up the final review as you showed it, and, when one change is finished, the same `notes` and `context` as its preview, as "Check it" and "Working notes" above say: its context part is shown in the preview and kept with its archive. When the change was finished anyway with tasks or gaps left open, the result lists them: offer a follow-up change holding them. If the user agrees, draft it as /bk-capture drafts a change, from its proposal, through the review; if not, they stay recorded with the archived change.
 
 Defects and ad-hoc units finish as above.

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

@@ -39,7 +39,7 @@ Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manag
 
 ## 4. Stamping their own commits
 
-Explain: while a unit of work is active, BuildKeel adds a line `BuildKeel-Unit: <id>` to commits the agent makes. If they agree, a git hook adds the same line to commits they make themselves, for example in a terminal. It changes nothing when no unit is active. Recommend yes. If the repository already manages its git hooks with another tool, nothing is installed and BuildKeel shows the lines to add.
+Explain: while a unit of work is active, BuildKeel adds a line `BuildKeel-Unit: <id>` to commits the agent makes. Stamping is on by default: setup installs a git hook that adds the same line to commits they make themselves, for example in a terminal. It changes nothing when no unit is active, and can be turned off later, which uninstalls the hook. If the repository already manages its git hooks with another tool, nothing is installed and BuildKeel shows the lines to add. Ask, with your tool for asking a question with choices: **Stamp my commits** (the default, listed first) or **Don't stamp them**. Pass `stampCommits: false` only when they turn it off.
 
 Then call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, `stampCommits` and, for a new tree, `mode`, without `apply`. Show the list it returns, as it is, in your reply as normal text.
 
@@ -63,10 +63,10 @@ The list shows the process as a table: BuildKeel's default, or the organization'
 
 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.
+**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.
 
-- **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.
+- **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.
 

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`.
@@ -43,10 +45,10 @@ The list shows the process as a table: BuildKeel's default, or the organization'
 
 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.
+**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.
 
-- **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.
+- **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.
 

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

@@ -7,7 +7,7 @@ BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mc
 
 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 defect is the exception: it is recorded at once, with its permanent ID, and needs no approval (see "Defects" 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)
 
@@ -118,7 +118,7 @@ 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 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.
+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 `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.

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
@@ -99,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
 

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

@@ -1,6 +1,6 @@
 ---
 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."
+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.
@@ -15,4 +15,4 @@ If the result says this repository is not set up for BuildKeel, tell the user ho
 
 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.
+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/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/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." }