buildkeel 0.1.0 → 0.2.0

package/antigravity/package.json

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

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

@@ -11,6 +11,8 @@ Turn the conversation into a plan the team's process can build from. There are t
 
 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 5.
+
 ## 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):
@@ -80,7 +82,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.
+- 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
@@ -89,6 +91,15 @@ Show what was drafted as a table: ID, title, and what is still missing. Then, fo
 
 ## 5. 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.
+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: **Draft the change** (the default), **Change the plan**, **Keep talking**.
+3. **Draft the whole change** once the user agrees. Call `get_template` for proposal, spec-change, tasks and, when needed, design. Save them in one `save_draft` call with `type: "change"`, the proposal as `content`, and the others in `files`. 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. If the user asked to go one artifact at a time, save the proposal first, then each other file with the change's `id`, showing each before the next.
+4. **Show what was saved**: the change's ID, its files, the IDs given, and anything `save_draft` lists as worth fixing. Ask about what is missing, one question at a time. Then offer /bk-start with the change's ID as the next step.

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

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

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

@@ -18,17 +18,25 @@ Ask each question with your tool for asking a question with choices, if you have
    - **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, 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:
    - **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.
    - **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-new/SKILL.md

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

@@ -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.

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

@@ -11,6 +11,8 @@ Start work on a BuildKeel unit with the user. Every code change belongs to exact
 
 The user typed: whatever follows /bk-start in the user's message (nothing, if they typed only /bk-start)
 
+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 the unit
 
 If the user named a unit above, use it.
@@ -36,3 +38,7 @@ Call the BuildKeel `start_work` tool with the unit's `id`.
 - **Started:** tell the user the branch and anything it warned about, such as a spec tree that is behind its remote. Then give a short summary of the context it returned: what to build, the acceptance criteria, and the test cases, by ID. Propose how to begin, and ask before writing code.
 
 Keep the context in mind for the rest of the work, and call `get_context` again if you lose track of it. Do not create or edit spec tree files yourself.
+
+## In a Spec-driven tree
+
+The units are open changes, bugs and ad-hoc units, and no gate runs: `start_work` starts the unit, or says which working tree on this machine already holds it. If nothing can be started, suggest drafting a change with /bk-capture. When a change starts, sum up its context in a few lines: what the proposal changes, the requirements it adds, modifies or removes by ID, how many of its tasks are done, and the next unticked task. Propose starting with that task, or running /bk-build for all of them, and ask before writing code.

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

@@ -24,7 +24,7 @@ If the user typed nothing, ask straight away, before calling any tool: "Which pe
 
 ## Show it
 
-Call the BuildKeel `query` tool with `view: "stats"` and `days` (leave `days` out for all of it). Show the result as it is: it opens with what the period comes to, then the details.
+Call the BuildKeel `query` tool with `view: "stats"` and `days` (leave `days` out for all of it). Show the result as it is: it opens with what the period comes to, then the details. In a Spec-driven tree it counts changes and what finishing them reported, in place of gate figures.
 
 ## Change the record
 

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

@@ -14,3 +14,5 @@ Show the user the result as it is, keeping its indentation, which shows the hier
 If it lists claims on this machine, end by saying that a claim can be released before its unit is finished. Release one only when the user asks for it: call the BuildKeel `manage` tool with `action: "release"` and the unit's `id`, and show the result.
 
 If the result says this repository is not set up for BuildKeel, tell the user how to set it up with /bk-init.
+
+In a Spec-driven tree, the result ends with an offer to review the active change. Ask, with your tool for asking a question with choices: **Review <ID> now** (the default) or **Not now**. To review, call `finish_work` without `apply`, review as its result says, and report your judgment; do not finish the change unless the user asks.

package/antigravity/templates/design.md

@@ -19,6 +19,7 @@ sections:
   Operations: { offered: "How it is deployed, monitored and supported." }
   Rollout and rollback: { offered: "How it is released, and how it is undone if something goes wrong." }
   Testing approach: { offered: "How the design is tested beyond the test cases in its test plans." }
+  Open questions: { offered: "Questions that can safely wait, each with who answers it and by when. A question whose answer would change the specs or tasks is answered first." }
   Notes: { offered: "Background, links, and anything from a source that fits no other section." }
 ---
 

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

@@ -0,0 +1,28 @@
+---
+template: capability
+version: 1
+description: How one lasting behavior of the system works now. A purpose, then requirements, each with scenarios a test can check. Changed only by finishing a change.
+fields:
+  title: { required: true }
+sections:
+  Purpose: { required: true }
+  Requirements: { required: true, tracked: true, items: { prefix: R, style: heading, children: { prefix: S, style: heading } } }
+---
+
+## Purpose
+
+<!-- What this capability covers and why it exists, in one or two sentences. -->
+
+## Requirements
+
+<!--
+One heading per requirement, with its ID and a short name. Under it, the behavior in one or two sentences using SHALL or MUST, at most 500 characters.
+Then one heading per scenario, with its ID and a short name, and a WHEN line and a THEN line a test can check. Every requirement has at least one scenario.
+
+### AUTH-R3 Reset link expires
+The system SHALL expire a reset link 30 minutes after it is sent.
+
+#### AUTH-R3-S1 Expired link
+- **WHEN** a user opens a reset link 31 minutes after it was sent
+- **THEN** they are told the link expired and offered a new one
+-->

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

@@ -0,0 +1,39 @@
+---
+template: proposal
+version: 1
+description: Why a change is made, what it changes, and which capabilities it adds or alters. Its spec changes say exactly how behavior changes.
+fields:
+  title: { required: true }
+  capabilities: { type: list }
+  noSpecChanges: { type: boolean }
+sections:
+  Why: { required: true }
+  What changes: { required: true }
+  Capabilities: { required: true }
+  Impact: { required: true }
+  Non-goals: { offered: "What the change deliberately leaves out, so nobody builds it by mistake." }
+  Notes: { offered: "Background, links, and anything from a source that fits no other section." }
+---
+
+## Why
+
+<!-- The problem or the opportunity, and why it is worth doing now. One or two short paragraphs. -->
+
+## What changes
+
+<!-- One line per change in behavior, interface or data. Mark each change that breaks existing users or callers with **BREAKING**. -->
+
+## Capabilities
+
+<!--
+Each capability the change adds or alters, by code, with what changes in it. The capabilities field lists the same codes.
+
+- **AUTH** (modified): reset links expire after 30 minutes.
+- **SMS** (new): sending one-time codes by text message.
+
+A change that alters no behavior, such as a refactor, says so here, sets noSpecChanges: true, and has no spec changes.
+-->
+
+## Impact
+
+<!-- The code, APIs, dependencies, data and systems the change affects. -->

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

@@ -0,0 +1,43 @@
+---
+template: spec-change
+version: 1
+description: How a change alters one capability's requirements. Existing requirements are named by ID, so a rename keeps its ID.
+fields:
+  capability: { required: true }
+  title: {}
+  base: {}
+sections:
+  Purpose: { offered: "For a new capability: what it covers and why it exists, in one or two sentences." }
+  Added: { tracked: true, items: { prefix: R, style: heading, children: { prefix: S, style: heading } } }
+  Modified: { tracked: true, items: { prefix: R, style: heading, children: { prefix: S, style: heading } } }
+  Removed: { tracked: true, items: { prefix: R, style: heading } }
+---
+
+<!-- The capability field names the capability by its code. For a new capability, also give its title (title: Text messages) and add a Purpose section. Leave out Added, Modified or Removed when the change has nothing in it. -->
+
+## Added
+
+<!--
+New requirements, each with its scenarios, written as the capability spec writes them.
+
+### AUTH-R3 Reset link expires
+The system SHALL expire a reset link 30 minutes after it is sent.
+
+#### AUTH-R3-S1 Expired link
+- **WHEN** a user opens a reset link 31 minutes after it was sent
+- **THEN** they are told the link expired and offered a new one
+-->
+
+## Modified
+
+<!-- Existing requirements by ID, each with its full new text and every scenario it keeps or gains, not only what differs. A new name under the same ID renames it. -->
+
+## Removed
+
+<!--
+Requirements that no longer apply, by ID, each with why and what users or callers do instead.
+
+### AUTH-R1 Sign in with a security question
+**Reason**: security questions are replaced by email codes.
+**Migration**: users set up email codes at their next sign-in.
+-->

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

@@ -0,0 +1,17 @@
+---
+template: tasks
+version: 1
+description: The work of a change, as numbered tasks in groups ordered so that each builds on the ones before. A task is ticked once its verification passes.
+fields:
+  parent: { required: true, type: link }
+---
+
+## 1. <What this group delivers>
+
+<!--
+One checkbox per task, numbered within its group, each saying what is done and how its completion is verified.
+Each group includes the tests and documentation its own work needs. Tick a task only once its verification passed.
+
+- [ ] 1.1 Add the issue time to reset tokens. Verify: token tests for a new and an old token.
+- [ ] 1.2 Refuse links older than 30 minutes. Verify: the "Expired link" scenario test (AUTH-R3-S1).
+-->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildkeel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Keeps requirements, tests and code connected, and gives the coding agent the full picture before it writes anything.",
   "homepage": "https://buildkeel.ai",
   "license": "SEE LICENSE IN LICENSE",