buildkeel 0.4.0 → 0.6.0

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

@@ -11,6 +11,8 @@ Turn the conversation into a plan the team's process can build from, with the us
 
 The user typed: whatever follows /bk-capture in the user's message (nothing, if they typed only /bk-capture)
 
+**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 step 1, then "In a Spec-driven tree" at the end in place of steps 2 to 6.
 
 ## How each review goes
@@ -25,13 +27,16 @@ When later discussion in this capture would change something the user already ag
 
 ## 1. Say what you heard
 
-Before calling any tool, sum up the discussion in plain words, with no BuildKeel terms yet (no stages, IDs or templates):
+Once that check is done, and before any other tool call, sum up the discussion in plain words, with no BuildKeel terms yet (no stages, IDs or templates):
 
 - **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:
@@ -42,27 +47,45 @@ Then ask whether to go on, with the summary in that same reply. Show it in full
 
 Any other answer, such as a correction or a new thought, is more conversation: answer it as you would, and draft nothing.
 
+### A problem someone reported
+
+When the discussion is about a problem someone reported with how the system behaves, sort it once the user chooses to create the artifacts, before step 2.
+
+**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.
+
+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.
+
+A defect is recorded as /bk-new defect records one: `get_template` for `defect`, then `save_draft` with `type: "defect"`, `source: reported` and the parent agreed. A change in behavior or a gap goes on to step 2 as work to plan, with the reading the user confirmed.
+
 ## 2. Propose the plan
 
 1. Call the BuildKeel `query` tool with `view: "process"` for the stages and the documents each requires, and with `view: "tree"` for what exists. Read an existing artifact with `view: "artifact"` when you need to know what it covers.
 2. Work out the artifacts the work needs, level by level, from the business idea down to the tasks, in the team's stage names: which already exist, which are new, and the documents each stage requires, such as a design document for a new epic and a test plan for each new story. For each task, work out which of its story's test cases its tests will implement. A task whose tests implement none of them, such as a building block (a client, a data model, a migration), needs a test plan of its own, or it can never be finished: put it in the table.
 3. Recommend where the work fits in the tree, and say why: under an existing business idea or epic, or as something new.
 4. If the work changes how something already built behaves, and a document describes how it works today (such as EP-01's design document for password reset), the plan includes a new version of that document.
-5. If the work changes code that already exists, work out which files it will change, from the discussion and the code, and call `query` with `view: "describes"` and their `paths`. Where an artifact describes them, the work builds on it. Where nothing describes the behavior the work changes, the plan includes a **version 0**: one artifact, usually a story, describing only what the work touches, as it works today, before the change. The change is then its version 1, or an artifact under it. A version 0 is a proposal: the user can drop it.
+5. When a stage holds more than one kind of work (`view: "process"` lists the kinds at each stage), propose a kind for each new artifact at that stage, from where the work came from, and say why in the table: an enhancement when it improves existing behavior, a feature when it adds something new, as the team's kinds are named. The user confirms or changes each kind as part of the plan; never draft one as a kind the user has not agreed to. Each is drafted with its kind as `type`, from that kind's template, and numbered in that kind's sequence.
+6. If the work changes code that already exists, work out which files it will change, from the discussion and the code, and call `query` with `view: "describes"` and their `paths`. Where an artifact describes them, the work builds on it. Where nothing describes the behavior the work changes, the plan includes a **version 0**: one artifact, usually a story, describing only what the work touches, as it works today, before the change. The change is then its version 1, or an artifact under it. A version 0 is a proposal: the user can drop it.
 
 Show the plan as a table, top down, each row with a one-line purpose, and say where the work fits and why, in a sentence:
 
-| Level | Artifact | Status | Purpose |
-|---|---|---|---|
-| Business idea | BI-01 "Self-service account recovery" | exists | the goal this serves |
-| Epic | "Reset by text message" | new | the new capability |
-| Design document | of the new epic | new, required | how it is built |
-| Story | "Request a code by text" | new | one per user-facing behavior |
-| Test plan | one per story | new, required | covers every criterion |
-| Task | "SMS gateway client" | new | one per piece of code, with its repository |
-| Test plan | of "SMS gateway client" | new | its tests are none of the story's test cases |
-| Design document | EP-01-DD | new version | password reset now works differently |
-| Story | "Password reset" | version 0, then the change as version 1 | how reset by email works today, which nothing describes yet |
+| Level | Kind | Artifact | Status | Purpose |
+|---|---|---|---|---|
+| Business idea | business idea | BI-01 "Self-service account recovery" | exists | the goal this serves |
+| Epic | epic | "Reset by text message" | new | the new capability |
+| Design document | | of the new epic | new, required | how it is built |
+| Story | user story | "Request a code by text" | new | one per user-facing behavior |
+| Test plan | | one per story | new, required | covers every criterion |
+| Task | task | "SMS gateway client" | new | one per piece of code, with its repository |
+| Test plan | | of "SMS gateway client" | new | its tests are none of the story's test cases |
+| Design document | | EP-01-DD | new version | password reset now works differently |
+| Story | user story | "Password reset" | version 0, then the change as version 1 | how reset by email works today, which nothing describes yet |
+
+The Kind column names each artifact's kind; when every stage holds one kind, it is the stage's name, and you may leave the column out.
 
 Then ask, the same way, with the table and that sentence 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:
 
@@ -82,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.
@@ -92,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.
@@ -127,16 +168,23 @@ Version 0 describes what the code does today, as if BuildKeel had been used from
 - Reword what the code and the sources 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 work touches, not the whole area around it.
 - Keep each source as you read it: pass it to `save_draft` 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: the baseline commit names the code.
-- When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended, before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it with /bk-new bug once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
+- 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.
@@ -156,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

@@ -11,13 +11,15 @@ Finish a BuildKeel unit with the user. Finishing writes a permanent record of wh
 
 The user typed: whatever follows /bk-done in the user's message (nothing, if they typed only /bk-done)
 
+**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 for a change.
 
 ## Choose the unit
 
 If the user named a unit above, use it.
 
-If the user typed nothing, ask straight away, before calling any tool: "What do you want to finish?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+If the user typed nothing, ask straight away: "What do you want to finish?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
 
 1. **The active unit in this working tree** (the default, listed first).
 2. **Another unit, or a story or epic whose work is all done: type its ID.** If they pick this, ask for the ID.
@@ -27,17 +29,48 @@ 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 bug:** the result also says which stories its changes belong to. Ask where to attach it, with your tool for asking a question with choices: **the story it suggests** (the default), then each task it names, then **leave it standalone**. Pass the chosen ID in `attach` when you finish.
+   - **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.
 
-## A bug that is not a defect
+**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.
 
-When the unit is a bug, offer closing it without a fix beside finishing it, with your tool for asking a question with choices, whether or not it is started: **Finish <ID>** (the default when its regression test passes, or when the user has not said it is not a defect) or **Close without a fix**, for a bug that turns out not to be a defect (a duplicate, one that cannot be reproduced, behavior that works as intended, or a test that was wrong; the default when the user says so). To close, ask for the reason with the same tool, then for a duplicate which bug it duplicates, and for an optional note in the user's words. Call `finish_work` with `close` (`reason`, `duplicateOf`, `note`) and without `apply`, show what it says with the bug's title, and ask the user to confirm. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when they confirm, call it again with `apply: true`. Never close a bug the user has not confirmed in this conversation. When the test was wrong, offer to correct the test case as a new version of its test plan.
+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
+
+When the unit is a defect, offer closing it without a fix beside finishing it, with your tool for asking a question with choices, whether or not it is started: **Finish <ID>** (the default when its regression test passes, or when the user has not said it is not one) or **Close without a fix**, for a defect that turns out not to be one (a duplicate, one that cannot be reproduced, behavior that works as intended, a test that was wrong, or a change in behavior: the code does what the spec says, and the spec is what must change; the default when the user says so). To close, ask for the reason with the same tool, then for a duplicate which defect it duplicates, for a change in behavior the change, version or item that takes it over (draft it first if there is none yet, such as a change, or a story's next version, with /bk-new), and for an optional note in the user's words. Call `finish_work` with `close` (`reason`, `duplicateOf`, `takenOverBy`, `note`) and without `apply`, show what it says with the defect's title, and ask the user to confirm. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when they confirm, call it again with `apply: true`. Never close a defect the user has not confirmed in this conversation. When the test was wrong, offer to correct the test case as a new version of its test plan.
 
 ## Confirm
 
@@ -51,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 bug.
+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
 
@@ -63,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.
 
-Bugs and ad-hoc units finish as above.
+Defects and ad-hoc units finish as above.

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

@@ -7,17 +7,19 @@ 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.
 
-Review change impact in BuildKeel with the user. A suspect is a task, story, epic, bug or test case built against an older version of something that has changed since, in what it relies on. Deciding on a suspect is the user's choice: never record a decision they have not confirmed in this conversation.
+Review change impact in BuildKeel with the user. A suspect is a task, story, epic, defect or test case built against an older version of something that has changed since, in what it relies on. Deciding on a suspect is the user's choice: never record a decision they have not confirmed in this conversation.
 
 The user typed: whatever follows /bk-impact in the user's message (nothing, if they typed only /bk-impact)
 
+**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 as well.
 
 ## Choose what to review
 
 If the user named an artifact or test case above, use it.
 
-If the user typed nothing, ask straight away, before calling any tool: "What do you want to review?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+If the user typed nothing, ask straight away: "What do you want to review?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
 
 1. **Every suspect** (the default, listed first).
 2. **Type an ID:** an artifact with a new version in draft, to see what approving it would affect, or an artifact or test case to review on its own. If they pick this, ask for the ID.
@@ -33,14 +35,14 @@ Call the BuildKeel `impact` tool, with `id` if there is one. Show its result as
 
 For each suspect in the result, in order:
 
-1. Show what it is and what changed, in the same reply as the question in step 3, never in a choice's label or description. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. For a test case, read its plan with `query` (`view: "artifact"` and the plan's ID) and show the test case with the old and new text of what it covers. For a task, story, epic or bug, show its own text (`query`, `view: "artifact"`) with the old and new text of what changed above it. For a finished unit, show the commits and files its completion record lists.
+1. Show what it is and what changed, in the same reply as the question in step 3, never in a choice's label or description. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. For a test case, read its plan with `query` (`view: "artifact"` and the plan's ID) and show the test case with the old and new text of what it covers. For a task, story, epic or defect, show its own text (`query`, `view: "artifact"`) with the old and new text of what changed above it. For a finished unit, show the commits and files its completion record lists.
 2. Propose a decision, saying why in a sentence or two:
    - **Still valid** when the change does not affect what it says, builds or checks, such as a rewording, or a change to something it does not rely on in substance.
    - **Needs change** when what it says, builds or checks no longer matches the new text, such as a test case checking a 30-minute expiry when the criterion now says 15 minutes. For finished work, name the files that likely need to change.
 3. Ask the user to decide, in plain text at the end of that reply: your proposal first, then the other decision, then **Skip it for now**.
 4. Record only what the user chose: call `resolve_suspect` with the `id` and the `decision` (`still-valid` or `needs-change`), and show its result as it is.
    - After **needs change**, offer to make the change now: read the draft it opened with `query`, show the change you would make, in full, and ask. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Save it with `save_draft` only once the user agrees, and approve it with /bk-approve only when they confirm. For a unit already finished, its new version can be started again with /bk-build once approved, to change the code.
-   - For a **bug**, needs change on an open bug means changing its file with the user, shown and agreed as above, and saving it with `save_draft`: the save records the decision. For a finished bug, `resolve_suspect` records a new bug to check it: show it, and offer to start it with /bk-build.
+   - For a **defect**, needs change on an open defect means changing its file with the user, shown and agreed as above, and saving it with `save_draft`: the save records the decision. For a finished defect, `resolve_suspect` records a new defect to check it: show it, and offer to start it with /bk-build.
 
 ## Afterwards
 

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

@@ -11,36 +11,81 @@ Set up BuildKeel in this repository using the BuildKeel `manage` tool with `acti
 
 The user typed: whatever follows /bk-init in the user's message (nothing, if they typed only /bk-init)
 
-Ask each question with your tool for asking a question with choices, if you have one, with your recommendation as the first choice, so the user can pick it with Enter, except where a step says to ask in prose. If the user typed nothing above, ask the first question straight away, before calling any tool.
+Ask each question with your tool for asking a question with choices, if you have one, with your recommendation as the first choice, so the user can pick it with Enter, except where a step says to ask in prose or in plain text.
 
-1. **Where the spec tree lives.** If the user gave a path above, use it as an existing spec tree and skip this question; if `manage` then reports there is no spec tree there, ask whether to create a new spec repository at that path instead. Otherwise ask:
-   - **In this repository**, in a `specs/` folder. Recommend this when this is the team's only repository, or when trying BuildKeel out.
-   - **An existing spec tree**, usually its own repository shared by several code repositories. Ask for its local path. If it is not cloned yet, tell the user to clone it first.
-   - **A new spec repository**, a repository of its own that several code repositories will share. Ask for its folder, outside this repository, such as `../specs`: a folder that does not exist yet, an empty folder, or an empty repository the user has cloned. Use `location: "new-repo"` with that `path`.
+## 1. Check the folder
 
-2. **The mode**, for a new spec tree only (an existing tree keeps its own, and `manage` says which). Ask, with a line on each:
-   - **Spec-driven** (the default, listed first): capability specs say how the system behaves, and each piece of work is a change to them, with no approvals or gates.
-   - **Full SDLC**: work goes through the team's stages, from business idea down, with approvals and gates.
+Before any question, call `manage` with `action: "init"` and nothing else. It only reads.
 
-   Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manage` below.
+- When it says the folder is not a git repository, ask before anything else, with your tool for asking a question with choices, so the user can pick an answer: **Run git init for me** (the default) or **Stop**. Only when the user agrees, call `manage` with `action: "init"`, `apply: true` and nothing else: it runs `git init`, so never run it yourself. Then say in one line that `git init` ran, before the next question. Ask nothing else until this is settled.
+- When it says the repository is already set up, show that, and stop.
 
-3. **Stamping their own commits.** Explain: while a unit of work is active, BuildKeel adds a line `BuildKeel-Unit: <id>` to commits the agent makes. If they agree, a git hook adds the same line to commits they make themselves, for example in a terminal. It changes nothing when no unit is active. Recommend yes. If the repository already manages its git hooks with another tool, nothing is installed and BuildKeel shows the lines to add.
+## 2. Where the spec tree lives
 
-4. Call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, `stampCommits` and, for a new tree, `mode`, without `apply`. Show the user the list it returns, as it is, in your reply as normal text.
+If the user gave a path above, use it as an existing spec tree and skip this question; if `manage` then reports there is no spec tree there, ask whether to create a new spec repository at that path instead. Otherwise ask:
 
-5. **The process**, for a new Full SDLC spec tree. The list ends with the process as a table: each stage, its first ID and the documents it requires before work under it starts (by default a design document for an epic and a test plan for a story), then the bug and ad-hoc prefixes, each gate's mode, and how a task's own test plan is kept. Show it as it is. Then ask in prose, not with your tool for asking a question with choices, whether the team uses this process as it is, or how the team works: they can describe it in their own words, all at once, such as "we call stories features, every feature needs a design doc, epics need a security review, and the gates should only warn while we try it out".
-   - **Used as it is**: go on to the confirmation below.
-   - **Described in their words**: work out a `process` object from it, as in buildkeel.yaml's process section: stage names, a stage added between the business idea and the user story, the documents each stage requires, the team's own documents (say that each needs a template of its own later), ID prefixes, each gate's mode, and whether a task's own test plan is approved. Leave out what they did not mention: it keeps its default, and you ask nothing about it. Call `manage` again without `apply` with the `process`, and show the new table. Name anything they described that the process cannot express, such as a stage after the code is built, with the closest setting it has, such as the done gate's checks; never drop it silently, and never invent a setting.
+- **In this repository**, in a `specs/` folder. Recommend this when this is the team's only repository, or when trying BuildKeel out.
+- **An existing spec tree**, usually its own repository shared by several code repositories. Ask for its local path. If it is not cloned yet, tell the user to clone it first.
+- **A new spec repository**, a repository of its own that several code repositories will share. Ask for its folder, outside this repository, such as `../specs`: a folder that does not exist yet, an empty folder, or an empty repository the user has cloned. Use `location: "new-repo"` with that `path`.
 
-   Then ask whether to set up with it, with the table in that same reply. Never ask about a table the user has not seen. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The choices:
-   - **Set up with this process** (the default, listed first).
-   - **Change something.** Take in what they say, in their own words, work it into the `process`, call `manage` again without `apply`, and show the new table. Repeat until the user agrees.
-   - **Stop, and set up nothing.**
+## 3. The mode
 
-   A Spec-driven tree has no stages, and an existing spec tree keeps its own process: skip this question and ask the user to confirm the list. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+For a new spec tree only: an existing tree keeps its own, and `manage` says which. Ask, with a line on each:
 
-6. Only when the user confirms, call `manage` again with the same values (and the same `process`, if they adjusted it) and `apply: true`. Show the result as it is, including any lines the user must add to their hook manager, and, for a new spec repository, that it needs a remote and a push before others can use it.
+- **Spec-driven** (the default, listed first): capability specs say how the system behaves, and each piece of work is a change to them, with no approvals or gates.
+- **Full SDLC**: work goes through the team's stages, from business idea down, with approvals and gates.
 
-7. **The guide**, for a Spec-driven tree, new or existing: the result asks it. Ask **Guide me through my first change** (the default) or **Jump right in**, and record the answer with `manage`, `action: "guide"`, `guide: "on"` or `"off"`.
+Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manage` below.
+
+## 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. 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.
+
+## 5. The process, for a new Full SDLC spec tree
+
+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.
+
+## 6. Numbering, for a new Spec-driven spec tree
+
+Topics for this step: **numbering**, how the tree's IDs read.
+
+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 tree's IDs, each with an example: changes, capability codes, requirements, scenarios, defects and ad-hoc units. Show them as they are, then ask in plain text whether to keep them (the default) or change them, with examples of other numbering, such as `RFC-0012` or `PROJ-12` for changes, or `AUTH-REQ1` for requirements. A change of change, defect or ad-hoc prefix or digits goes in `process`, such as `{ change: { prefix: RFC, width: 4 } }`; a change of the letters in requirement or scenario IDs goes in `markers`. Call `manage` again without `apply` with them, show the IDs it returns, and ask the user to confirm them. Pass `settled: ["numbering"]` once they keep or confirm the numbering.
+
+## 7. Confirm and set up
+
+Show the last list `manage` returned in full and ask whether to set up with it, change something or stop. An existing spec tree keeps its own process and numbering: just ask the user to confirm the list. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+
+Only when the user confirms, call `manage` again with the same values (the same `process`, `settled`, `templates` and `markers`, when there are any) and `apply: true`. Show the result as it is, including any lines the user must add to their hook manager, and, for a new spec repository, that it needs a remote and a push before others can use it.
+
+## 8. The guide
+
+For a Spec-driven tree, new or existing, the result asks it. Ask **Guide me through my first change** (the default) or **Jump right in**, and record the answer with `manage`, `action: "guide"`, `guide: "on"` or `"off"`.
 
 Do not create or edit any BuildKeel files yourself; the `manage` tool does all of it. If `manage` reports a problem, show it with its fix and ask how to continue.