buildkeel 0.1.0 → 0.3.0

package/antigravity/package.json

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

package/antigravity/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "buildkeel",
-  "version": "0.1.0",
+  "version": "0.3.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

@@ -1,15 +1,15 @@
 ---
 trigger: always_on
-description: How to work in a repository set up with BuildKeel (it has a .buildkeel.yaml file). Use it when the user asks you to change code or to move work forward, before committing, when writing or running tests, when finishing a unit of work, and whenever you read or change requirements, designs, stories, tasks or test plans.
+description: How to work in a repository set up with BuildKeel (it has a .buildkeel.yaml file). Use it when the user asks you to change code, before committing, when writing or running tests, when finishing a unit of work, and whenever you read or change requirements, designs, stories, tasks or test plans.
 ---
 
 BuildKeel keeps requirements, tests and code connected. Follow these rules in any repository that has a `.buildkeel.yaml` file.
 
 ## Conversation comes first
 
-Talk with the user as you would without BuildKeel. Follow where they take the conversation, stay curious rather than prescriptive, ask one question at a time with your recommendation, and never push for an output they did not ask for. When a question is about something you show, such as a table, a plan or a tool's result, the user sees it as they answer: Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Discussing ideas, weighing options, talking through architecture and reading code are free: leave BuildKeel's artifacts, stages, IDs and commands out of it.
+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, asks you to change code, or asks to move work forward, such as "let's plan this" or "build it". Then say how to structure what was discussed (see "Before changing code"). Once that is done, the conversation is free again.
+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.
 
 ## The spec tree
 
@@ -21,7 +21,7 @@ A team can rename the stages of its process and add stages of its own. When it h
 
 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:
 
-1. **Capture what we discussed** with /bk-capture: it turns the conversation into the artifacts the team's process needs, to approve and then build. Recommend it when the conversation shaped new work.
+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-start <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-adhoc does: 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.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-adhoc
-description: 'BuildKeel: Record a small change as an ad-hoc unit and start it, so its commits trace to something. Run as /bk-adhoc "<the change>", e.g. "Fix typo in the reset email".'
+description: 'BuildKeel: Record a small change as an ad-hoc unit and start it, so its commits trace to something. Run as /bk-adhoc "<the change>", e.g. "Fix typo in the reset email", 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.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-approve
-description: "BuildKeel: Approve a draft or a new version after checking it, or a set of drafts, such as a captured plan, in one review. Run as /bk-approve [artifact IDs], e.g. US-draft-k3x9, US-001-TP, or several IDs for one review."
+description: "BuildKeel: Approve a draft or a new version after checking it, or a set of drafts, such as a captured plan, in one review. Run as /bk-approve [artifact IDs], e.g. US-draft-k3x9, US-001-TP, or several IDs for one review, 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,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)
 
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, it has nothing to approve: call `approve` once and show its answer as it is.
+
 ## Choose what to approve
 
 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").
@@ -39,7 +41,7 @@ If they pick "Show what is ready", call the BuildKeel `query` tool with `view: "
 
 ## Its documents
 
-If the result says the approved artifact has a document with a draft waiting, such as its test plan or design document, tell the user and ask whether to approve it now. If they agree, go through the same steps for the document's ID: show it, check it without `apply`, and approve it only after they confirm. Each approval is its own commit.
+If the result says a task's own test plan was recorded with it, say so in a line: it needs no approval. If the result says the approved artifact has a document with a draft waiting, such as its test plan or design document, tell the user and ask whether to approve it now. If they agree, go through the same steps for the document's ID: show it, check it without `apply`, and approve it only after they confirm. Each approval is its own commit.
 
 ## Afterwards
 

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

@@ -1,6 +1,6 @@
 ---
 name: bk-build
-description: "BuildKeel: Build what is ready: start, build, test and finish each ready unit in turn, after one confirmation. Run as /bk-build [parent ID], e.g. US-001 to build its tasks, or EP-01; everything ready when left out."
+description: "BuildKeel: Build what is ready: start, build, test and finish each ready unit in turn, after one confirmation. Run as /bk-build [parent ID], e.g. US-001 to build its tasks, or EP-01; everything ready when left out, only when the user types it."
 ---
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
@@ -11,6 +11,8 @@ Build every unit that is ready, one after another, with the user's one confirmat
 
 The user typed: whatever follows /bk-build in the user's message (nothing, if they typed only /bk-build)
 
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end instead of the sections before it.
+
 ## Choose what to build
 
 If the user named a story, an epic or another parent above, build the ready units under it.
@@ -37,7 +39,7 @@ Otherwise show the list in order, and say how the run goes: each unit is started
 For each unit, in order:
 
 1. **Start it.** Call `start_work` with its `id` and `run: true`; from the second unit on, also pass `stack: true`, so its branch starts from the branch of the unit just finished. If the start is refused, or there are uncommitted changes, stop the run: show the result as it is and ask the user how to go on.
-2. **Build it.** Work from the context `start_work` returned: the unit, its requirements, its design, and its test cases. Write the code and the tests for its test cases, each test named with its test case ID in square brackets. Commit as you go, each message ending with `BuildKeel-Unit: <ID>`, and change files only with your file editing tools.
+2. **Build it.** Work from the context `start_work` returned: the unit, its requirements, its design, and its test cases. Write the code and the tests for its test cases, each test named with its test case ID in square brackets. Commit as you go, each message ending with `BuildKeel-Unit: <ID>`, and change files only with your file editing tools. When a task needs a test case its own test plan does not have, add it, with `{{new}}` for its number and its `covers` line, and save the whole plan with `save_draft` and the plan's `id`: unless the result says the plan waits for approval, it is recorded at once as its next version, and the run goes on.
 3. **Test it.** Run the tests with a JUnit XML report and record it with the BuildKeel `test_results` tool. When a test fails, fix the code or the test and run them again. If it still fails after a real attempt, stop the run: name the failing test case and what you tried, and ask the user how to go on.
 4. **When a requirement is unclear** (two readings, a missing case, a conflict with the code), stop the run and ask the user one question, with your recommendation. Never guess a requirement.
 5. **Finish it.** Call `finish_work` without `apply`. If it says the tests have no current result, run them again and record them, once. If it is refused for any other reason, or lists commits without a `BuildKeel-Unit` line, stop the run and show it. Otherwise call `finish_work` with `apply: true`: the user's confirmation of the run covers finishing each unit that passes its done gate.
@@ -48,3 +50,12 @@ For each unit, in order:
 Show a table of the run: each unit, its branch, its commits, and its completion record, or where the run stopped and why. The last branch holds the whole run: say that one pull request from it reviews all of it, or that each branch can have its own pull request, each based on the previous one and merged in order. If the completion records are not pushed, remind the user to push the spec repo.
 
 Do not create or edit spec tree files yourself: the BuildKeel tools write every record.
+
+## In a Spec-driven tree
+
+A run builds one change's tasks, in order, on the change's branch.
+
+1. **The change.** If the user named a change, start it with `start_work` unless it is already active. If they typed nothing and a change is active, build it. Otherwise ask, straight away, which change to build, offering **Show what can be started** (the default) and **Type a change ID**, then start the one they pick.
+2. **Ask once.** Call `get_context` for the change. 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 or a requirement is unclear. Then ask, showing the list. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Build them** (the default), **Change the list**, **Stop**.
+3. **Each task in turn.** Write the code and its tests, each test named with the scenario ID it checks in square brackets, 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: save the task list with `save_draft`, type `tasks` and the change's `id`, with its box changed to `[x]`. A failing test you cannot fix, or an unclear requirement, stops the run with one question and your recommendation.
+4. **At the end**, show each task with its commits and whether it is ticked, or where the run stopped and why. Do not finish the change yourself: offer /bk-done, which reviews the code against the change's requirements before it is archived.

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

@@ -1,16 +1,18 @@
 ---
 name: bk-capture
-description: "BuildKeel: Turn what you discussed into a plan: a plain summary, then the artifacts your process needs, drafted once you agree. Run as /bk-capture [which part of the conversation to capture; all of it when left out]."
+description: "BuildKeel: Turn what you discussed into a plan: a plain summary, then the artifacts your process needs, agreed one by one or all at once, as you choose. Run as /bk-capture [which part of the conversation to capture; all of it when left out], only when the user types it."
 ---
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
 
 When you ask a question with choices, the user may see nothing you wrote before it: whenever a step says to show something and then ask, put it in the question itself, as it is, and never say it was shown above.
 
-Turn the conversation into a plan the team's process can build from. There are two checkpoints: nothing is drafted until the user agrees, and everything drafted stays a draft until it is approved.
+Turn the conversation into a plan the team's process can build from, with the user agreeing at each step: the summary, the list of what will be created, the pace, then each artifact. Nothing is saved that the user has not agreed to, and everything saved stays a draft until it is approved.
 
 The user typed: whatever follows /bk-capture in the user's message (nothing, if they typed only /bk-capture)
 
+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.
+
 ## 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):
@@ -18,8 +20,9 @@ Before calling any tool, sum up the discussion in plain words, with no BuildKeel
 - **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.
+- **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.
 
-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 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, with your tool for asking a question with choices if you have one, showing the summary. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
 
@@ -37,9 +40,9 @@ Any other answer, such as a correction or a new thought, is more conversation: a
 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.
 
-Show the plan as a table, top down, and say where the work fits and why, in a sentence:
+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 | Why |
+| 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 |
@@ -53,19 +56,27 @@ Show the plan as a table, top down, and say where the work fits and why, in a se
 
 Then ask, the same way, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
 
-1. **Draft them all** (the default).
+1. **Looks right** (the default).
 2. **Place it somewhere else.** Ask where. The new artifact is drafted where the user says, with a link to the one you recommended (`related: [EP-01]`).
 3. **Change the plan.** Take in what they say and show the table again.
 4. **Keep talking.** Stop here; nothing is drafted.
 
-When the plan holds a version 0, offer **Draft them all, without the version 0** in place of the second choice; placing the work somewhere else is then a change to the plan. Without the version 0, the change is drafted as version 1 of a new artifact, as for any new work.
+When the plan holds a version 0, offer **Looks right, without the version 0** in place of the second choice; placing the work somewhere else is then a change to the plan. Without the version 0, the change is drafted as version 1 of a new artifact, as for any new work.
+
+## 3. Ask the pace
+
+Ask, every time, how the user wants to go through the drafts. Never assume it, and never carry it over from an earlier capture. The choices:
 
-## 3. Draft everything
+1. **Step by step** (the default, listed first): each artifact is shown and agreed before the next is drafted.
+2. **All at once**: everything is drafted, then shown as a set.
 
-Only after the user agrees:
+## 4. Draft
+
+### 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.
-- Fill each artifact from the conversation, keeping its meaning and the user's words. Put what fits no section in the section for further material, such as Notes. Never invent a requirement, a criterion or a decision that was not discussed; leave a required section out rather than fill it with a guess.
+- Fill each artifact from the conversation, keeping its meaning and the user's words. Turn each settled pitfall or constraint into the requirement, criterion or test case it calls for, in the artifact it belongs to. Put what fits no section in the section for further material, such as Notes.
+- Never invent a requirement, a criterion, a decision or a pitfall that was not discussed. What a draft needs and the conversation did not settle is a gap: see "Gaps" below.
 - Write `{{id}}` where the artifact's own ID goes and `{{new}}` as the number of each new entry, as `/bk-new` does: `- **{{id}}-AC{{new}}** ...` for criteria, `### {{id}}-TC{{new}} ...` for test cases.
 - Every story gets a test plan whose test cases cover all its criteria (`covers: [<story ID>-AC1]`). A task names its `repo` and, when you can tell, its `scope`. A task whose tests will not each be one of its story's test cases, such as a building block, gets its own test plan, with test cases that cover the task itself (`covers: [<task ID>]`): without one it cannot be finished.
 - 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.
@@ -73,6 +84,32 @@ Only after the user agrees:
 - 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`.
 
+### 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:
+
+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, showing it. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Looks good, next** (the default), **Change something** (take in what they say and show it again), 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.
+
+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, and save each one with `save_draft`. Then show what was drafted as a table: ID, title, and the pitfalls each covers.
+
+### 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:
+
+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.
+3. **Flesh it out now**: discuss it until the user settles it, then draft it.
+4. **Not relevant: leave it out.**
+
+A version 0 is the exception: list the sections it leaves empty, and ask nothing about them.
+
 ### Drafting a version 0
 
 Version 0 describes what the code does today, as if BuildKeel had been used from the start: the template's sections, filled from the code and from what the user brings about it, such as a ticket or a wiki page read through their own tools, a file, or what they say.
@@ -80,15 +117,27 @@ 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.
+- 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.
 - 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.
 
-## 4. What the conversation left out
+## 5. What is left
 
-Show what was drafted as a table: ID, title, and what is still missing. Then, for each required section or field that `save_draft` named as missing, ask the user, one question at a time, and save the answer with `save_draft` and the draft's `id`. For example, if the design document requires a rollout plan the discussion never touched, ask how it will be rolled out. Show the table with the first question. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. A version 0 is the exception: list the sections it leaves empty, and ask nothing about them.
+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.
 
-## 5. Next step
+## 6. Next step
 
-Offer approval as the next step: /bk-approve shows the drafts from this capture as one set, with anything that would not pass, and approves them in one review once the user confirms, a version 0 before the change built on it. Do not approve anything yourself here.
+Agreeing to an artifact here does not approve it. Offer approval as the next step: /bk-approve shows the drafts from this capture as one set, with anything that would not pass, and approves them in one review once the user confirms, a version 0 before the change built on it. 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. Do not approve anything yourself here.
 
 Do not create or edit spec tree files yourself; `save_draft` does all writing.
+
+## In a Spec-driven tree
+
+The plan is one change: a proposal, a spec change for each capability whose behavior it alters, a design only when needed, and tasks. Nothing is approved.
+
+1. **Read the capability specs first.** Call `query` with `view: "capabilities"`, then with the `id` of each capability the work touches, so the change starts from how the system behaves now. Check `view: "changes"` for an open change that already covers the work.
+2. **Propose the change**, showing a table of the capabilities it adds or modifies, by code, with what changes in each, and say in a sentence whether it needs a design: only when it makes decisions worth recording, such as a new component, data, an interface or a trade-off. A change that alters no behavior, such as a refactor, says so and has no spec changes. For a new capability, propose a short code from its name, such as SMS, which the user can change before anything is saved. Then ask, the same way as in step 1, showing the table and that sentence. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices: **Looks right** (the default), **Change the plan**, **Keep talking**.
+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, as above.
+   - **All at once:** save them in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`, then show them.
+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-start with the change's ID as the next step.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-done
-description: "BuildKeel: Finish the active unit, or a story or epic once everything under it is done: check its tests pass, then write its completion record. Run as /bk-done [ID], e.g. TK-001, or US-001 for a story built through tasks; the active unit when left out."
+description: "BuildKeel: Finish the active unit, or a story or epic once everything under it is done: check its tests pass, then write its completion record. Run as /bk-done [ID], e.g. TK-001, or US-001 for a story built through tasks; the active unit when left out, only when the user types it."
 ---
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
@@ -11,6 +11,8 @@ 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)
 
+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.
@@ -33,6 +35,10 @@ A story built through tasks, an epic, or a stage the team added above its storie
    - **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 bug that is not a defect
+
+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. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. 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.
+
 ## Confirm
 
 Ask the user with your tool for asking a question with choices, the default first, showing what the result said. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
@@ -54,3 +60,7 @@ Show the result as it is: the completion record, the commit in the spec repo, an
 If the result names the next unit ready under the same parent, offer to start it, with your tool for asking a question with choices: **Start <ID>** (the default), or **Not now**. If the user agrees, call `start_work` with its `id` and `stack: true`, so its branch starts from this unit's branch and has this work before it is merged, and carry on as /bk-start does. Otherwise call `query` with `view: "startable"`, show what can be started next, and offer to start it with /bk-start, or to build everything ready with /bk-build.
 
 Do not create or edit spec tree files yourself: `finish_work` writes the record, and completion records are never edited.
+
+## 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: review the code against the change, report it labeled as your judgment, and ask **Fix first** or **Finish anyway**, fix first being the default when anything is reported missing. Nothing blocks the finish but uncommitted work. Bugs and ad-hoc units finish as above.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-impact
-description: "BuildKeel: Review what a change to an approved artifact affects: preview a new version before approving it, or decide on each suspect with the user. Run as /bk-impact [ID], e.g. US-001 to preview its new version in draft, or US-001-TC2 to review one suspect; every suspect when left out."
+description: "BuildKeel: Review what a change to an approved artifact affects: preview a new version before approving it, or decide on each suspect with the user. Run as /bk-impact [ID], e.g. US-001 to preview its new version in draft, or US-001-TC2 to review one suspect; every suspect when left out, only when the user types it."
 ---
 
 BuildKeel's tools are on the MCP server `buildkeel`: call each one with `call_mcp_tool` (`ServerName` `buildkeel`, `ToolName` the tool's name), passing `workspace`, the absolute path of this project's folder. Never read or write the spec tree's files instead. If you have no `call_mcp_tool` tool, tell the user to start a new conversation and stop: never run BuildKeel's server or programs yourself.
@@ -11,6 +11,8 @@ Review change impact in BuildKeel with the user. A suspect is a task, story, epi
 
 The user typed: whatever follows /bk-impact in the user's message (nothing, if they typed only /bk-impact)
 
+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.
@@ -38,9 +40,14 @@ For each suspect in the result, in order:
 3. Ask the user to decide, with your tool for asking a question with choices: 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`, change it with `save_draft`, show the user the result, and approve it with /bk-approve only when they confirm. For a unit already finished, its new version can be started again with /bk-start once approved, to change the code.
+   - For a **bug**, needs change on an open bug means changing its file with the user 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-start.
 
 ## Afterwards
 
 Call `impact` without `id` and say how many suspects are left. If a test plan is still written against an older version of its story, suggest updating it to cover any new criteria.
 
 Do not create or edit spec tree files yourself: `resolve_suspect` and `save_draft` do all writing, and re-pin records are never edited.
+
+## In a Spec-driven tree
+
+Suspects are tests tagged with a scenario, and archived changes, built against a requirement that a later capability version modified or removed. With an open change's ID, `impact` previews what archiving it would make suspect: decide each then or after it is archived, as its result says, passing that change in `change` to `resolve_suspect`. Needs change adds a task to revisit it: in the previewed change, or after archiving, in an open change the user picks (draft a new change with `save_draft` first if they want one). Show the task it added.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-init
-description: "BuildKeel: Set up BuildKeel in this repository, with a new spec tree or an existing one. Run as /bk-init [path of an existing spec tree]."
+description: "BuildKeel: Set up BuildKeel in this repository, with a new spec tree or an existing one. Run as /bk-init [path of an existing spec tree], 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,24 +11,36 @@ 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. 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. If the user typed nothing above, ask the first question straight away, before calling any tool.
 
 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`.
 
-2. **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. **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.
 
-3. Call `manage` with `action: "init"`, the `location` (`this-repo`, `existing` or `new-repo`), the `path` if there is one, and `stampCommits`, without `apply`. Show the user the list it returns, as it is.
+   Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manage` below.
 
-4. **The process**, for a new spec tree. The list ends with the process as a table: each stage, 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). Never ask about a table the user has not seen: ask, showing the table as it is. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+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.
+
+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.
+
+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.
+
+   Then ask, with your tool for asking a question with choices, showing the table. Never ask about a table the user has not seen. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
    - **Set up with this process** (the default, listed first).
-   - **Adjust the process.** Ask what to change, one question at a time, with your recommendation: rename a stage (such as stories called "features"), add a stage between the business idea and the user story, change the documents a stage requires, or add a document of the team's own (it needs a template of its own later). Put the changes in a `process` object, as in buildkeel.yaml's process section, call `manage` again without `apply` with it, and show the new table. Repeat until the user agrees.
+   - **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.**
 
-   An existing spec tree keeps its own process: skip this question and ask the user to confirm the list.
+   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.
+
+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.
 
-5. 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.
+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"`.
 
 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

@@ -1,6 +1,6 @@
 ---
 name: bk-migrate
-description: "BuildKeel: Upgrade a spec tree in an older format to the one this BuildKeel uses, in one commit, without touching approved versions. Run as /bk-migrate."
+description: "BuildKeel: Upgrade a spec tree in an older format to the one this BuildKeel uses, in one commit, without touching approved versions. Run as /bk-migrate, only when the user types it."
 ---
 
 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.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-new
-description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a bug. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or bug TK-001."
+description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a bug. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or bug TK-001, only when the user types it."
 ---
 
 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,6 +11,8 @@ Draft BuildKeel artifacts with the user. Everything you produce is a draft: draf
 
 The user typed: whatever follows /bk-new in the user's message (nothing, if they typed only /bk-new)
 
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end instead of the sections before "Bugs".
+
 ## If the user typed nothing
 
 Ask straight away, before calling any tool, with your tool for asking a question with choices if you have one. The question itself says what they could type, in one sentence, since some hosts show only the question and its choices: "What should I draft? For example: " followed by the examples.
@@ -53,7 +55,7 @@ Version 0 describes what code already does, as if BuildKeel had been used from t
 - Fill the template's sections from the code and from what the user brings about it, such as a ticket or a wiki page read through their own tools, a file, or what they say. Reword what they say into the template's form, such as a ticket's description written as testable criteria; add nothing they do not support.
 - Describe only what the change touches.
 - Keep each source as you read it: pass it in `sources`, with where it came from, its key and link, and its text exactly as your tool returned it (description, fields and comments). Never copy code into a source.
-- When a source and the code disagree, or two sources do, ask the user which is intended before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it once version 0 is approved. When the source is out of date, version 0 follows the code.
+- When a source and the code disagree, or two sources do, ask the user which is intended before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
 - Supported means the code or a source says it; a plausible guess is not support, such as who a story is for and why. Leave a required section empty when nothing supports it, without asking: `save_draft` lists what is empty, for the reviewer.
 
 The change that builds on it is then saved with `save_draft`, the version 0's draft ID as `id` and no `version`: that draft is its version 1. Start from version 0's text as saved, with its entry IDs: keep the ID of every entry that stays, changed or not (a criterion whose limit changes keeps its ID), and write `{{new}}` only for an entry the change adds. Both are approved in one review with /bk-approve, version 0 first.
@@ -63,7 +65,7 @@ The change that builds on it is then saved with `save_draft`, the version 0's dr
 A test plan belongs to one artifact (its `parent`), and every test case has a `covers:` line saying what it checks. A test plan has no `id` field: its frontmatter is only its `parent`, and it is named after that artifact, such as `US-001-TP`.
 
 - **A story's plan** covers the story's acceptance criteria, such as `covers: [{{id}}-AC1]`. Every criterion must be covered, or the plan cannot be approved.
-- **A task's plan** covers the task itself (its ID, such as `covers: [TK-047]`) and/or its story's criteria. The story's test cases already apply to the task. Draft a plan for the task whenever its tests will not each be one of those story test cases: a building block such as a token store or a data model, a migration, or a refactor. A task without a plan of its own can be finished only when at least one of its tests is tagged with a story test case and passes.
+- **A task's plan** covers the task itself (its ID, such as `covers: [TK-047]`) and/or its story's criteria. Unless the process approves task plans, it is recorded, not approved: each save that passes its checks, once the task is approved, becomes its next version. The story's test cases already apply to the task. Draft a plan for the task whenever its tests will not each be one of those story test cases: a building block such as a token store or a data model, a migration, or a refactor. A task without a plan of its own can be finished only when at least one of its tests is tagged with a story test case and passes.
 - **An epic's plan** (its integration test plan) covers stories under the epic, or their criteria.
 - **A business idea's plan** (its end-to-end test plan) covers epics under the idea, or the idea's goals.
 
@@ -94,6 +96,17 @@ A bug is a defect in work that was planned: it is recorded straight away with it
 
 ## Finish
 
-List every draft you saved, with its ID and title, and anything `save_draft` reported as still missing. Offer to fix what is missing or to revise any draft. Remind the user that drafts are approved with /bk-approve.
+List every draft you saved, with its ID and title, and anything `save_draft` reported as still missing. Offer to fix what is missing or to revise any draft. Remind the user that drafts are approved with /bk-approve; a task's own test plan, when `save_draft` says it is recorded, needs no approval.
 
 Do not create or edit spec tree files yourself; `save_draft` does all writing.
+
+## In a Spec-driven tree
+
+What you draft is a change, or a file of an open change: its proposal, a spec change, its design or its tasks. Nothing is approved. A bug is recorded as in "Bugs", attached to the change whose work found it (its `parent` is the change's ID, its `testCase` the scenario whose test found it) or standalone; a fix that changes a requirement is made through a change.
+
+- **If the user typed nothing**, ask what to draft, offering **Suggest what to draft next** (the default) and **Type what to draft**. The question itself gives examples: `change for reset by text message`, `spec change for CH-012` and `bug CH-012`. For a suggestion, call `query` with `view: "changes"` and propose what an open change still lacks, such as tasks or a spec change its proposal names.
+- **Read before writing.** Call `query` with `view: "capabilities"`, and with the `id` of each capability the work touches. For a file of an open change, read the change with `view: "changes"` and its `id`. Call `get_template` for each file you draft.
+- **A new change**: draft its proposal, a spec change per capability it adds or modifies, a design only when it makes decisions worth recording, and tasks, and save them in one `save_draft` call with `type: "change"`, the proposal as `content` and the rest in `files`. Before saving a new capability, propose its code from its name and let the user change it.
+- **A file of an open change**: save it with `save_draft`, its type and the change's `id`. Then check the change's other files against it and propose the follow-on edits, such as a task for a new requirement.
+- Ask one question at a time, for what you cannot work out. If the user asks to go one artifact at a time, save and show each before the next.
+- Finish by listing what was saved and anything `save_draft` lists as worth fixing, and offer /bk-start with the change's ID.

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

@@ -1,6 +1,6 @@
 ---
 name: bk-onboard
-description: "BuildKeel: Document code that existed before BuildKeel, area by area: map the code, then draft each area for people to review and approve. Run as /bk-onboard [an area to onboard, or nothing to choose]."
+description: "BuildKeel: Document code that existed before BuildKeel, area by area: map the code, then draft each area for people to review and approve. Run as /bk-onboard [an area to onboard, or nothing to choose], 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.
@@ -13,6 +13,8 @@ What describes code from before BuildKeel is version 0 of its artifact: the arti
 
 The user typed: whatever follows /bk-onboard in the user's message (nothing, if they typed only /bk-onboard)
 
+If BuildKeel's session report, or `query` with `view: "process"`, says this spec tree is Spec-driven, follow "In a Spec-driven tree" at the end in place of "Onboard an area" and the sections after it.
+
 ## Choose what to do
 
 Call the BuildKeel `query` tool with `view: "onboarding"`; it changes nothing. Then ask straight away, with your tool for asking a question with choices if you have one, the default listed first, showing what the view said. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
@@ -56,6 +58,8 @@ Show a table of the artifacts the area needs, top down, in the team's stage name
 | Task | PAY-14 "Email template" | version 0 | finished in Jira |
 | Left out | PAY-31 "Reset by text" | | open in Jira: drafted with /bk-new when someone takes it up |
 
+Once the area's drafts are approved, or all but those waiting on a question left open, record every ticket you read for it with `manage`, `action: "map"`, `map: "tickets"`, the area and its `tickets`: each with its `key`, `link` and `title`, and either `outcome: "carried"` with the `artifact` it became (its approved ID), or `outcome: "left-out"` with `why`: `open`, `in-progress`, or `choice` when the team chose not to carry it over. Nothing read is left off the list.
+
 - Document every stage from the business idea down to the story, with the documents the process requires of each.
 - Tasks and bugs come in only when a source has them and they are finished: each as version 0, with its tracker key. Open or in-progress work is left out, and listed as such.
 - A required document no source provides, such as a design document or a test plan, is drafted as version 1, under the normal rules, so that new work under the area can start as usual.
@@ -73,7 +77,7 @@ Only once the user agrees. Draft top down, parents before children, so each chil
 - Name the paths it covers in its `scope`: an epic and a story always do.
 - Keep each source as you read it: pass it in `sources`, with where it came from, its key and link, and its text exactly as your tool returned it (description, fields and comments). Never copy code into a source.
 - Before drafting, go through every behavior each source states, such as each sentence of a ticket's description, and check it against the code. Each place they differ is a disagreement, however small: a ticket saying "rounded to the nearest cent" where the code rounds down is one. Ask about each, one at a time, before drafting that part; never take one side silently.
-- When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended before drafting that part. Offer both answers as equals and recommend neither: **The code is right; the ticket is out of date** and **The ticket is right; the code has a defect**. When the ticket is out of date, version 0 follows the code. When the code is wrong, see "Known defects" below.
+- When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended before drafting that part. Offer both answers as equals and recommend neither: **The code is right; the ticket is out of date** and **The ticket is right; the code has a defect**. When the ticket is out of date, version 0 follows the code. When the code is wrong, see "Known defects" below. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
 - For each required section nothing supports, ask the user, one question at a time, with your tool for asking a question with choices: **Leave it empty** (listed first) or **Type it in**, and put no answer of your own in the choices. A version 0 may leave a section empty: the approval records it, and it can be filled in later.
 
 **Each finished task, and each bug fixed before BuildKeel**, is a version 0 too: `save_draft` with `type: "task"` or `"bug"`, `version: 0`, its `parent` the story or task it belongs to (a draft's ID is fine), and its tracker issue in `sources`. It is approved with the area, counts as done, and is linked to the commits before the baseline that name its key. Never record a bug that was already fixed as an open bug.
@@ -97,7 +101,7 @@ Once the area is approved:
 
 ### 6. Next
 
-Call `query` with `view: "onboarding"` and ask which area to onboard next, as in "Choose an area", showing where onboarding stands. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. When the view lists anything left empty, also offer **Fill in what onboarding left empty**.
+Call `query` with `view: "onboarding"` and ask which area to onboard next, as in "Choose an area", showing where onboarding stands. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. When the view lists anything left empty, also offer **Fill in what onboarding left empty**; when it lists questions left open, also offer **Answer a question left open**: ask the question, with both readings as equals, and record the answer as above.
 
 ## Known defects
 
@@ -114,3 +118,18 @@ When the version in force leaves out behavior that version 0 describes, also dra
 The onboarding view lists the artifacts still as onboarding left them, with each section they leave empty. When it lists none, say that nothing was left empty, and stop: what the user says next is conversation, not a request for a new artifact. Otherwise ask which to fill in, the first listed as the default. For each empty section, ask the user, one question at a time, with **Leave it empty** as a choice. Save the whole artifact with the sections filled in, with `save_draft` and its `id`, and `completes: <the version in force>` in its frontmatter: that next version only completes it, so nothing built on it becomes suspect. Offer to approve it with /bk-approve.
 
 Do not create or edit spec tree files yourself: `save_draft`, `approve` and `manage` do all writing.
+
+## In a Spec-driven tree
+
+Existing code is documented as capability specs, version 0, area by area. Map the code as "Map the code" says, each area to become one or more capabilities. For the area `query` with `view: "onboarding"` names next: read its code and what the user brings, then draft each capability spec (a purpose, requirements with scenarios, new IDs as `CODE-R{{new}}`, the code proposed from its name for the user to change) and show it whole. Only once the user confirms one, save it with `save_draft`, `type: "capability"`, `version: 0` and `area: <name>` in its frontmatter: it is written once, with who confirmed it. When sources disagree, ask as above, with **Not sure: leave it open** last; a question left open is recorded on the area with `manage`, `action: "map"`, `map: "question"`, and its requirement is left out of version 0. Answering one later (`map: "answer"`) is followed by a change that adds the requirement. Record the tickets read for the area with `map: "tickets"` as above, each carried one naming the capability spec it fed. Then offer the next area.
+
+### Moving to Full SDLC
+
+When the user asks for approvals, stages or gates, or to convert the tree, offer **Move this tree to Full SDLC** (never as the default; the move is one way). Call `manage` with `action: "convert"` and `convert: "start"`, without `apply`, and follow what it says. Once a conversion is under way, `query` with `view: "onboarding"` shows it area by area: map the capability specs into areas, each area holding one or more, with `manage`, `action: "map"` and each area's `capabilities`, then for each area follow "Onboard an area" above, with these differences:
+
+- Its sources are its capability specs (`query`, `view: "capabilities"`) and the archived changes that wrote them (`view: "changes"`), each change kept as a source with its ID as the key. The code is not read at a baseline.
+- Draft the stages of `query` with `view: "process"`, top down: requirements become acceptance criteria, scenarios test cases, wherever they fit the stages. Nothing maps one to one.
+- Once the area is approved, show a table of each scenario and the criterion or test case it became, and record it with `manage`, `action: "convert"`, `convert: "place"` and `place`. Leave a scenario out (`drop`) only when the user says so.
+- Skip "Existing tests": a test tagged with a scenario counts for what that scenario became.
+
+Once every area is converted, the view says so: call `manage` with `action: "convert"` and `convert: "finish"`, without `apply`, and ask the user to confirm the switch, showing what it says. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.