buildkeel 0.4.0 → 0.5.0

package/antigravity/package.json

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

package/antigravity/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "buildkeel",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "BuildKeel keeps requirements, tests and code connected, from the business idea down to the commit, and gives the agent that full picture before it writes anything.",
   "homepage": "https://buildkeel.ai"
 }

package/antigravity/rules/buildkeel.md

@@ -9,11 +9,11 @@ BuildKeel keeps requirements, tests and code connected. Follow these rules in an
 
 Talk with the user as you would without BuildKeel, as a thinking partner, the way BuildKeel's session report describes: explain the options, trade-offs and pitfalls before you ask, ask in prose, recommend only what the evidence supports, and never push toward a plan or a BuildKeel step. Discussing ideas, weighing options, talking through architecture and reading code are free: leave BuildKeel's artifacts, stages, IDs and commands out of it.
 
-BuildKeel comes in when the user runs a BuildKeel command, or when you are about to change a file (see "Before changing code"). Once that is done, the conversation is free again. Start a BuildKeel command only when the user types it, except /bk-status and /bk-stats, which you may run on your own.
+BuildKeel comes in when the user runs a BuildKeel command, or when you are about to change a file (see "Before changing code"). Once that is done, the conversation is free again. Start a BuildKeel command only when the user types it, except /bk-status, /bk-settings and /bk-stats, which only read and which you may run on your own.
 
 ## The spec tree
 
-Read and change requirements, stories, tasks and test plans only through the BuildKeel tools: `query`, `get_context` and `get_template` to read, `save_draft` to write, `approve` only when the user confirms. Pass `workspace`, the absolute path of this project's folder, on every call to a BuildKeel tool. Never create or edit files in the spec tree yourself. Approved versions and records (`versions/`, `approvals/`, `completions/`, `repins/`) are never edited; to change an approved artifact, save the whole changed file with `save_draft`, which opens its next version. When BuildKeel reports suspects, offer to review them with /bk-impact; whether each is still valid or needs change is the user's decision.
+Read and change requirements, stories, tasks and test plans only through the BuildKeel tools: `query`, `get_context` and `get_template` to read, `save_draft` to write, `approve` only when the user confirms. Pass `workspace`, the absolute path of this project's folder, on every call to a BuildKeel tool. Never create or edit files in the spec tree yourself. Approved versions and records (`versions/`, `approvals/`, `completions/`, `repins/`) are never edited; to change an approved artifact, save the whole changed file with `save_draft`, which opens its next version. When BuildKeel reports suspects, offer to review them with /bk-impact; whether each is still valid or needs change is the user's decision. When the user changes behavior that looked wrong while building, the spec changes first: in Full SDLC, the next versions of everything it affects, approved before you build on them; in a Spec-driven tree, through the open change. /bk-build describes each path.
 
 Nothing goes into the spec tree unseen. Before you save anything to it, show what changes, in full, in your reply, and ask in plain text at its end, never inside your question tool. Agreement saves it; anything else is feedback: discuss it, then list each point with how it was addressed, show the final version, and save only once the user agrees. When work would change a document the user agreed, say which, what and why, and take it through the same review, one edit at a time. Never add, change or remove a requirement, criterion, scenario or task on your own initiative. Report each tick in a line; do not ask about ticks.
 
@@ -21,14 +21,14 @@ A team can rename the stages of its process and add stages of its own. When it h
 
 ## Before changing code
 
-Every code change belongs to the active unit of this working tree: a task, a story built without tasks, a bug or an ad-hoc unit. If there is none, before changing any file, ask the user how to go on, with your tool for asking a question with choices if you have one, recommending the choice that fits:
+Every code change belongs to the active unit of this working tree: a task, a story built without tasks, a defect or an ad-hoc unit. If there is none, before changing any file, ask the user how to go on, with your tool for asking a question with choices if you have one, recommending the choice that fits:
 
 1. **Capture what we discussed**: the user runs /bk-capture, which turns the conversation into the artifacts the team's process needs, to approve and then build. You cannot start it yourself: if they choose it, ask them to run it, and change nothing until a unit is active. Recommend it when the conversation shaped new work.
 2. **Start the unit it belongs to** with /bk-build <ID>, when the change is part of planned work.
 3. **Record it as an ad-hoc unit** with a short title you propose, and start it as /bk-build does for a description: for a small change that belongs to no planned work.
 4. **Go ahead without a unit.** Only the user can choose this: then call the BuildKeel `manage` tool with `action: "untracked"` first, and tell them the change will belong to no unit.
 
-When the user reports a defect, or a test fails in work that was finished, offer to record a bug with /bk-new bug. Call `get_context` when you need the unit's requirements, design and test cases again.
+When the user reports a defect, or a test fails in work that was finished, offer to record a defect with /bk-new defect, which sorts a report first. Call `get_context` when you need the unit's requirements, design and test cases again.
 
 Change files with your file editing tools, never through the shell (such as `sed -i`, `echo >` or `mv` over a file): BuildKeel checks each edit made with those tools, and an edit made around them escapes its checks.
 
@@ -48,7 +48,7 @@ If the message has other trailer lines, such as `Co-Authored-By`, keep them all
 
 ## Tests
 
-When you write a test for a test case, put the test case's ID in square brackets in the test's name, such as `it("emails a reset link [US-012-TC3]", ...)`. A test may carry several IDs, one per bracket: `[US-012-TC3] [US-012-TC4]`; a bracket holding several tags nothing. The test cases that apply to the unit are in its context: its own plan's and its story's. A bug's regression test carries the bug's ID, such as `[BUG-005]`, and must fail without the fix.
+When you write a test for a test case, put the test case's ID in square brackets in the test's name, such as `it("emails a reset link [US-012-TC3]", ...)`. A test may carry several IDs, one per bracket: `[US-012-TC3] [US-012-TC4]`; a bracket holding several tags nothing. The test cases that apply to the unit are in its context: its own plan's and its story's. A defect's regression test carries the defect's ID, such as `[DEF-005]`, and must fail without the fix.
 
 A test written before BuildKeel may be matched to a test case instead of tagged; the unit's context lists those matches. When you change such a test, add its test case's ID to its name too; BuildKeel drops the match when the unit is finished.
 

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

@@ -11,6 +11,8 @@ Help the user approve a BuildKeel artifact. Approval is the user's decision: nev
 
 The user typed: whatever follows /bk-approve in the user's message (nothing, if they typed only /bk-approve)
 
+**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, it has no approvals, and /bk-approve agrees what is under review:
 
 - **A document is under review** in this conversation, shown in full and waiting for the user's answer, such as a spec change during /bk-capture or a requirement while building: take /bk-approve as the user's agreement, as a reply of "approved" would be. Save it as that review says, and go on to the next step. Nothing is frozen: the change stays editable until it is finished.
@@ -20,7 +22,7 @@ If BuildKeel's session report, or `query` with `view: "process"`, says this spec
 
 If the user named one artifact above, approve it as below. If they named several, approve them as a set (see "A set in one review").
 
-If the user typed nothing, ask straight away, before calling any tool: "What do you want to approve?" 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 approve?" 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 drafts from this conversation, in one review** (the default, listed first): offer this only when drafts were saved in this conversation, such as by /bk-capture, and name them in the choice.
 2. **Show what is ready to approve** (the default when there are no drafts from this conversation).

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

@@ -1,6 +1,6 @@
 ---
 name: bk-build
-description: "BuildKeel: Start a unit and build it: a task, story, bug or change by its ID, the ready units under a parent, or a small change described in words. Run as /bk-build [an ID, a parent's ID, or what to change in words], e.g. TK-001, US-001, or \"fix the footer link\", only when the user types it."
+description: "BuildKeel: Start a unit and build it: a task, story, defect or change by its ID, the ready units under a parent, or a small change described in words. Run as /bk-build [an ID, a parent's ID, or what to change in words], e.g. TK-001, US-001, or \"fix the footer link\", only when the user types it."
 ---
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
@@ -11,16 +11,18 @@ Start a BuildKeel unit and build it with the user. Every code change belongs to
 
 The user typed: whatever follows /bk-build in the user's message (nothing, if they typed only /bk-build)
 
+**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 "Build a single unit" and "Build what is ready under a parent".
 
 ## What to build
 
 What the user typed decides it:
 
-- **A unit's ID**, such as a task, a story built without tasks, a bug, an ad-hoc unit or a change: start it and build it, as "Start it" and the sections after it say.
+- **A unit's ID**, such as a task, a story built without tasks, a defect, an ad-hoc unit or a change: start it and build it, as "Start it" and the sections after it say.
 - **A parent's ID**, such as a story built through tasks or an epic: build the units ready under it, as "Build what is ready under a parent" says.
 - **Words**, such as "fix the footer link": see "Words in place of an ID".
-- **Nothing:** ask straight away, before calling any tool: "What should I build?" Offer the choices with your tool for asking a question with choices, if you have one:
+- **Nothing:** ask straight away: "What should I build?" Offer the choices with your tool for asking a question with choices, if you have one:
   1. **The active unit** (the default, listed first), named with its ID and title: offer it only when this working tree has one.
   2. **Show what can be started** (the default when there is no active unit). Call `query` with `view: "startable"` and show its result as it is. Then ask which to build, the ready ones offered with the one you recommend first, and, in Full SDLC, **Everything that is ready** as a choice too. If nothing is ready, say what is in the way and suggest the next step, such as approving with /bk-approve, and stop.
   3. **Type an ID or describe the change.** If they pick this, ask for it.
@@ -32,7 +34,7 @@ Call `query` with `view: "startable"`, and in a Spec-driven tree also with `view
 - **When a title matches:** **Build <ID> "<title>"** for the best match (the default), then any other close match, then **Record a new ad-hoc unit "<title>"**, with the title you propose from the words. Record no ad-hoc unit unless the user picks it.
 - **When nothing matches:** **Record the ad-hoc unit "<title>" and build it** (the default), with the title you propose, or **Type another description**.
 
-The title says what changes in a few words, such as "Fix the footer link". If the change is a defect in work that was planned and tested, suggest recording it as a bug with /bk-new bug instead, and go on as the user prefers.
+The title says what changes in a few words, such as "Fix the footer link". If the change is a defect in work that was planned and tested, suggest recording it with /bk-new defect instead, and go on as the user prefers.
 
 ### Recording an ad-hoc unit
 
@@ -79,7 +81,7 @@ To build it: write the code and the tests for its test cases, each test named wi
 
 Each unit still goes through its own start gate, gets its own branch, commits and completion record, and is tested before it is finished.
 
-Call the BuildKeel `query` tool with `view: "startable"`. Take the units ready to start, at the lowest level: tasks, and stories that have no tasks (with a parent named, only those under it). Leave out bugs and ad-hoc units unless the user asks for them. Order them by parent, then by ID, so that a story's tasks are built in order.
+Call the BuildKeel `query` tool with `view: "startable"`. Take the units ready to start, at the lowest level: tasks, and stories that have no tasks (with a parent named, only those under it). Leave out defects and ad-hoc units unless the user asks for them. Order them by parent, then by ID, so that a story's tasks are built in order.
 
 If nothing is ready, show what is waiting and why, as `query` gave it, suggest the next step (such as approving with /bk-approve), and stop.
 
@@ -107,13 +109,22 @@ A run stops and asks the user:
 
 - when a gate refuses: show the result as it is;
 - when a test fails and still fails after a real attempt to fix it: name the failing test case and what you tried, and ask how to go on;
-- when a requirement is unclear (two readings, a missing case, a conflict with the code): ask one question, with your recommendation. Never guess a requirement.
+- when a requirement is unclear (two readings, a missing case, a conflict with the code): ask one question, with your recommendation. Never guess a requirement;
+- when agreed behavior looks wrong, as "Behavior that looks wrong" says.
 
 Do not create or edit spec tree files yourself: the BuildKeel tools write every record.
 
+## Behavior that looks wrong
+
+When what was agreed looks wrong while you build (a requirement, an acceptance criterion or a test case), stop and ask, whether or not the build started with this command: name it by ID, and say why it looks wrong. Offer **Keep it as agreed** and **Change it**, your recommendation first. Never build something else, and never edit the spec, without the answer.
+
+- **Kept:** build it as agreed, and do not raise it again in this build.
+- **Changed:** change the spec first. Save the whole changed story (or task) with `save_draft`, which opens its next version, and show it as any draft. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Then call the BuildKeel `impact` tool with its `id`: the preview names what the new version would make suspect, such as tasks and test plans. Draft the next version of each that must change too, and offer the set for approval with /bk-approve. Build nothing more on the unit until the set is approved; when the start gate is set to warn and the user says to carry on, go on, saying that you build against versions not yet approved. Once the set is approved, the unit is suspect: with the user's agreement, record that it now builds against the new versions with `resolve_suspect` (`decision: "still-valid"`), and go on against them.
+- **In code nothing describes yet** (`query` with `view: "describes"` finds no artifact): draft its version 0 first, describing the code as it is, as /bk-new does, then the change on top of it.
+
 ## In a Spec-driven tree
 
-The units are open changes, bugs and ad-hoc units, and no gate runs. Bugs and ad-hoc units are built as "Build a single unit" says. A change is built task by task, in order, on the change's branch:
+The units are open changes, defects and ad-hoc units, and no gate runs. Defects and ad-hoc units are built as "Build a single unit" says. A change is built task by task, in order, on the change's branch:
 
 1. **The change.** Start it as "Start it" says, unless it is already active: `start_work` starts it, or says which working tree on this machine already holds it. If nothing can be started, suggest drafting a change with /bk-capture.
 2. **Choose how to build.** Sum up the change in a few lines, with its title: what the proposal changes, and the requirements it adds, modifies or removes by ID. Show its unticked tasks in order, each with how it is verified, and say how the run goes: each task is built, tested and ticked in turn, and the run stops to ask when a test fails and cannot be fixed, a requirement is unclear, or what was agreed would change. Then ask, with the list 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:
@@ -123,5 +134,6 @@ The units are open changes, bugs and ad-hoc units, and no gate runs. Bugs and ad
 
    When every task is ticked already, say so instead, and that the user can run /bk-done to finish the change.
 3. **Each task in turn.** Write the code and its tests, each test named with the scenario ID it checks in square brackets, one ID per bracket, such as `[AUTH-R3-S1]`. Commit as you go, each message ending with `BuildKeel-Unit: <change ID>`, and add `BuildKeel-Task: <task number>` on the next line when a commit does exactly that one task. Run the tests with a JUnit XML report and record it with `test_results`. Once the task's stated verification passes, tick it with `save_draft`, `type: "tasks"`, the change's `id` and `tick` set to its number, such as `["2.3"]`, and say so in a line, with the progress the result gives. Never ask before ticking. A failing test you cannot fix, or an unclear requirement, stops the run, as "When a run stops" says.
+   - **Behavior that looks wrong** stops the run too: name the requirement or scenario and why, and ask **Keep it as agreed** or **Change it**, your recommendation first. Kept: build it as agreed. Changed: a requirement of this change's own spec change is edited in place, as the next point says, with the follow-on edits to the proposal, design and tasks. A requirement as an archived change left it is changed through this change, with a spec change modifying it (the default), or through a separate change drafted with /bk-capture, as the user prefers. In code nothing describes yet, document it first as version 0 of a capability spec, then change it.
    - **A change to what was agreed** stops the run too: a requirement or scenario to add, change or drop, a task's wording, or a task to add or remove. Say which file, what changes and why, show the change 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. Before adding a requirement to a change with more than half its tasks ticked, ask once first whether it belongs in this change or a new one, and draft nothing until the user answers. Save it only once the user agrees, then go on: one requirement with `save_draft`, `type: "spec-change"`, the change's `id`, its `capability` and `requirement` (`id` and `content` to replace it, `section` and `content` to add one, `id` and `drop` to take one out); a task list's wording as the whole file. Never change the spec on your own initiative, not even to make your own check pass.
 4. **At the end**, show each task with its commits and whether it is ticked, or where the run stopped and why. When the last tick's result says every task is done, pass on that the user can run /bk-done to finish the change. Do not finish the change yourself: /bk-done reviews the code against the change's requirements before it is archived.

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,7 +27,7 @@ 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.
@@ -42,27 +44,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:
 
@@ -127,7 +147,7 @@ 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

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.
@@ -33,11 +35,11 @@ A story built through tasks, an epic, or a stage the team added above its storie
    - **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.
+   - **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.
 
-## A bug that is not a defect
+## A defect closed without a fix
 
-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.
+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 +53,7 @@ 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, and with `attach` when they chose where to attach a standalone defect.
 
 ## Afterwards
 
@@ -73,4 +75,4 @@ A change is finished by archiving it, and need not be the active unit. With none
    - 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.
 
-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. 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.
+
+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: **Claude drafts it** (the default) or **I'll provide a file**. Nothing is left for later: if the user asks to leave one, say that the tree needs it to check what is drafted from it, and ask again with the same two answers.
+
+- **Claude drafts it**: call `get_template` for the closest built-in type: `story` for a kind at the user story stage, `epic` for a stage between the epic and the user story or a kind at one, `idea` for a kind at the business idea stage, `task` for a kind at the task stage, `design` for a document of the team's own. Change its `template:` line to the new type, and its description and sections to what the user said about it. Show it in full, and ask whether to use it or change something. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+- **I'll provide a file**: read the file the user names with your own tools, and pass its text. When `manage` says it fails the template check, show what is wrong, and ask: **Claude fixes it** (the default) or **Use another file**. Show a fixed template in full, and ask whether to use it. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+
+Pass each agreed template in `templates`, by type, and call `manage` again without `apply`: it checks each one. Nothing is written until every template the list names is given and passes.
+
+## 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.

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

@@ -23,7 +23,34 @@ If BuildKeel's session report, or `query` with `view: "process"`, says this spec
 
 In a Spec-driven tree, call `query` with `view: "onboarding"`. When it shows a conversion in progress, carry it on, as "Converting area by area" says. Otherwise, explain in a few lines what moving to Full SDLC means: work then goes through the team's stages, with approvals and gates, and the capability specs and archived changes are drafted into those stages, area by area, for the user to review and approve; the tree stays Spec-driven until every area is approved; and the move is one way. Then ask, with your tool for asking a question with choices: **Not now** (the default) or **Move this tree to Full SDLC**.
 
-If the user chooses to move it, call `manage` with `action: "convert"` and `convert: "start"`, without `apply`, and follow what it says: it refuses while any change is open, naming each with its title, and otherwise shows the process the tree will follow. Show it in your reply and ask the user to confirm, or to adjust the stages first. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only once they confirm, call it again with `apply: true`.
+If the user chooses to move it, call `manage` with `action: "convert"` and `convert: "start"`, without `apply`. It refuses while any change is open, naming each with its title: show that, and stop. Otherwise it lists what starting the conversion does and the process the tree would follow, and the process is settled as for a new Full SDLC tree, before any area is drafted. Each call below is `manage` with `action: "convert"` and `convert: "start"`.
+
+Topics for this step, in this order:
+
+- **stages**: what each stage is called, and any stage added between the business idea and the user story, with where it sits.
+- **kinds**: whether a stage holds more than one kind of work, such as features and enhancements beside user stories. Each kind is numbered in its own sequence, has its own template and documents, and behaves as its stage does.
+- **prefixes**: the ID prefix and digits of each stage and kind, such as `US-001`, `FEAT-0001` or `PROJ-12`.
+- **documents**: what each stage and kind needs approved before work under it starts: a test plan, a design document, or a document of the team's own, such as a security review.
+- **test-plans**: whether a task's own test plan is recorded as it is saved (the default) or approved like any other plan.
+- **gates**: each gate's mode: block stops the action, warn lets it go ahead with a warning, off skips the check. The approve gate checks an artifact before it is approved: it follows its template, and its parent is approved. The start gate checks before work starts: everything above the unit is approved and not suspect, and its required documents are approved. The done gate checks before a unit is finished: its test cases pass. The lock gate checks before the agent edits approved versions and records.
+
+Work from the topics listed for this step. The user may answer in their own words, several topics at once or part of one. After each answer, say which topics it settled, with what you understood for each, and which are left; then ask the next one left, one topic per message. Where a topic has a default, list keeping it first, naming its actual value, and give examples where they help. Anything you work out that the user did not say is a proposal: ask it as that topic's question, with it as the default, and never use it without the user's answer. Ask about an unclear answer; name a conflicting one beside the earlier answer and ask which holds. Never guess. When every topic is settled, show all of it, as a review.
+
+The list shows the process as a table: BuildKeel's default, or the organization's when the tree takes its templates from one. Show it as it is, in your reply as normal text. Then ask in prose, not with your tool for asking a question with choices, whether the team uses this process as it is, or works differently and how: they can describe it in their own words, all at once or in part. If they only say it works differently, ask in one line how their team works.
+
+- **Used as it is**: every topic is settled. Pass `settled: ["all"]`, and go on to the review below.
+- **Works differently**: settle the topics their description covers, and ask each topic left, in the order above, with the default's actual value from the table as the first answer. Build `process` as in buildkeel.yaml's process section from what the user said or confirmed, nothing else. An added stage or kind needs a prefix: propose one, such as `FEAT` for feature, and say it is a suggestion they can change. When the user names a stage the default process does not have, ask whether it is a stage of its own, between two stages, or a kind of work beside one, such as features beside user stories, before you settle stages: a list of stage names in order does not say which. Name anything the process cannot express, such as a stage after the code is built, with the closest setting it has, such as the done gate's checks; never drop it silently, and never invent a setting. After each answer, call `manage` again without `apply`, with the same values as before, the `process` so far and every topic settled in `settled`: it lists the topics left.
+
+When no topic is left, call `manage` again without `apply` and show the whole table it returns, as it is, with its line on what each stage or kind the team added means, and ask whether to go ahead with it. Never ask about a table the user has not seen. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. The answers: go ahead with this process (the default); change something, which you take in, then call `manage` again and show the whole table again, in the same layout; or stop, and write nothing.
+
+**Templates.** Once the user agrees the table, settle a template for each one the list says the process needs, one at a time, in the order listed. For each, ask: **Claude drafts it** (the default) or **I'll provide a file**. Nothing is left for later: if the user asks to leave one, say that the tree needs it to check what is drafted from it, and ask again with the same two answers.
+
+- **Claude drafts it**: call `get_template` for the closest built-in type: `story` for a kind at the user story stage, `epic` for a stage between the epic and the user story or a kind at one, `idea` for a kind at the business idea stage, `task` for a kind at the task stage, `design` for a document of the team's own. Change its `template:` line to the new type, and its description and sections to what the user said about it. Show it in full, and ask whether to use it or change something. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+- **I'll provide a file**: read the file the user names with your own tools, and pass its text. When `manage` says it fails the template check, show what is wrong, and ask: **Claude fixes it** (the default) or **Use another file**. Show a fixed template in full, and ask whether to use it. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool.
+
+Pass each agreed template in `templates`, by type, and call `manage` again without `apply`: it checks each one. Nothing is written until every template the list names is given and passes.
+
+Once the process and its templates are settled and the user agrees to go ahead, call it again with the same `process`, `settled` and `templates`, and `apply: true`: the conversion starts, and the templates are written with it.
 
 ### Converting area by area
 
@@ -38,6 +65,6 @@ If the user chooses to move it, call `manage` with `action: "convert"` and `conv
    - **Place the scenarios:** once the area is approved, show a table of each scenario and the criterion or test case it became, ask the user to agree it, and record it with `manage`, `action: "convert"`, `convert: "place"` and `place`. Leave a scenario out (`drop`) only when the user says so. A test tagged with a scenario counts for what that scenario became, so existing tests need no matching.
 3. **Switch.** Once every area is converted, the view says so: call `manage` with `action: "convert"` and `convert: "finish"`, without `apply`, and ask the user to confirm the switch, with what it says in your reply. Show it in full in your reply, as normal text: the document, table or list itself. End the message with your question in plain text, and take the user's next message as the answer. Never put what you show inside your question tool. Only when they confirm, call it again with `apply: true`, and show the result as it is.
 
-The user can stop after any area: the next /bk-migrate carries on from there. While the conversion is in progress no change can be opened, and bugs and ad-hoc units work as usual. Before any area is approved, the conversion can be cancelled with `manage`, `action: "convert"` and `convert: "cancel"`, after the user confirms.
+The user can stop after any area: the next /bk-migrate carries on from there. While the conversion is in progress no change can be opened, and defects and ad-hoc units work as usual. Before any area is approved, the conversion can be cancelled with `manage`, `action: "convert"` and `convert: "cancel"`, after the user confirms.
 
 Do not change spec tree files yourself; the BuildKeel tools do all of it.