buildkeel 0.0.1 → 0.2.0

package/antigravity/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "buildkeel",
+  "version": "0.2.0",
+  "private": true,
+  "homepage": "https://buildkeel.ai",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module"
+}

package/antigravity/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "buildkeel",
+  "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/rules/buildkeel.md

@@ -0,0 +1,72 @@
+---
+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.
+---
+
+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.
+
+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.
+
+## The spec tree
+
+Read and change requirements, stories, tasks and test plans only through the BuildKeel tools: `query`, `get_context` and `get_template` to read, `save_draft` to write, `approve` only when the user confirms. Pass `workspace`, the absolute path of this project's folder, on every call to a BuildKeel tool. Never create or edit files in the spec tree yourself. Approved versions and records (`versions/`, `approvals/`, `completions/`, `repins/`) are never edited; to change an approved artifact, save the whole changed file with `save_draft`, which opens its next version. When BuildKeel reports suspects, offer to review them with /bk-impact; whether each is still valid or needs change is the user's decision.
+
+A team can rename the stages of its process and add stages of its own. When it has, BuildKeel's session report lists the stages as the team names them: use those names with the user, in each command's help, its questions and its output. A renamed stage is still that stage to BuildKeel (a "feature" is a user story), and the tools accept either name.
+
+## Before changing code
+
+Every code change belongs to the active unit of this working tree: a task, a story built without tasks, a bug or an ad-hoc unit. If there is none, before changing any file, ask the user how to go on, with your tool for asking a question with choices if you have one, recommending the choice that fits:
+
+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.
+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.
+
+When the user reports a defect, or a test fails in work that was finished, offer to record a bug with /bk-new bug. Call `get_context` when you need the unit's requirements, design and test cases again.
+
+Change files with your file editing tools, never through the shell (such as `sed -i`, `echo >` or `mv` over a file): BuildKeel checks each edit made with those tools, and an edit made around them escapes its checks.
+
+If BuildKeel says a change is outside the areas the active unit relates to, tell the user: carry on if it belongs to the unit, and otherwise ask which unit it belongs to.
+
+## Commits
+
+End every commit message with the active unit's trailer, after a blank line:
+
+```
+Add the reset endpoint
+
+BuildKeel-Unit: TK-047
+```
+
+If the message has other trailer lines, such as `Co-Authored-By`, keep them all in that last block with no blank line between them, so git reads them as trailers. Use the active unit's ID, never another unit's. Do not rewrite commits that are already made.
+
+## Tests
+
+When you write a test for a test case, put the test case's ID in square brackets in the test's name, such as `it("emails a reset link [US-012-TC3]", ...)`. A test may carry several IDs. The test cases that apply to the unit are in its context: its own plan's and its story's. A bug's regression test carries the bug's ID, such as `[BUG-005]`, and must fail without the fix.
+
+A test written before BuildKeel may be matched to a test case instead of tagged; the unit's context lists those matches. When you change such a test, add its test case's ID to its name too; BuildKeel drops the match when the unit is finished.
+
+Run the tests with a JUnit XML reporter, writing the report under `.buildkeel/` (git ignores it), and record each report with the BuildKeel `test_results` tool. For example:
+
+- Vitest: `npx vitest run --reporter=default --reporter=junit --outputFile.junit=.buildkeel/junit.xml`
+- Jest: `npx jest --reporters=default --reporters=jest-junit` with `JEST_JUNIT_OUTPUT_FILE=.buildkeel/junit.xml`
+- pytest: `pytest --junitxml=.buildkeel/junit.xml`
+- Node's test runner: `node --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=.buildkeel/junit.xml`
+- Go: `gotestsum --junitfile .buildkeel/junit.xml`
+- Maven and Gradle write JUnit XML already, under `target/surefire-reports/` and `build/test-results/`.
+
+Results are local to this working tree. A result goes stale when the code or the test plan changes, so run the tests again after changing code.
+
+## Finishing
+
+When the unit's work is committed and its test cases pass, finish it with /bk-done. Finishing writes a permanent completion record, so it is the user's decision: show what it will record and ask first.
+
+## Calling BuildKeel's tools
+
+BuildKeel's tools (`query`, `get_context`, `save_draft` and the rest) are on the MCP server named `buildkeel`. Call each one with your tool for calling an MCP tool (`call_mcp_tool`), with `ServerName` `buildkeel`, the tool's name as `ToolName`, and its arguments, `workspace` included. Read a tool's description first if you need its arguments. Never start BuildKeel's server or programs yourself, from a terminal or a script, and never read or write the spec tree's files to work around a tool; if a tool cannot be reached, tell the user. If you have no `call_mcp_tool` tool, BuildKeel's server is not connected to this conversation, which can happen in the first conversation after Antigravity opens: tell the user to start a new conversation, and do nothing else for the request.
+
+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.

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

@@ -0,0 +1,49 @@
+---
+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".'
+---
+
+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.
+
+Record a small change as a BuildKeel ad-hoc unit and start it. An ad-hoc unit needs no approval: it gets its permanent ID straight away, its commits carry that ID, and it is finished with /bk-done like any other unit.
+
+The user typed: whatever follows /bk-adhoc in the user's message (nothing, if they typed only /bk-adhoc)
+
+## Name the change
+
+If the user described the change above, use it.
+
+If the user typed nothing, ask straight away, before calling any tool: "What is the change?" Offer the choices with your tool for asking a question with choices, if you have one:
+
+1. **The change we were just discussing** (the default, listed first), with the title you propose for it. Offer this only when the conversation names a change.
+2. **Type a short description.** If they pick this, ask for it.
+
+The title says what changes in a few words, such as "Fix typo in the reset email". If the change is a defect in work that was planned and tested, suggest recording it as a bug with /bk-new bug instead, and go on as the user prefers.
+
+## Create and start it
+
+1. Call the BuildKeel `save_draft` tool with `type: "adhoc"` and this content, with the title and a sentence or two saying what changes and why:
+
+   ```
+   ---
+   id: {{id}}
+   title: <title>
+   ---
+
+   ## Description
+
+   <what changes and why>
+   ```
+
+   It gives the unit its ID and commits it in the spec repo. If the number counter cannot be reached, the ID ends in letters and digits instead of a number; it is still permanent.
+2. Call the BuildKeel `start_work` tool with the new ID.
+   - **Uncommitted changes:** show the files it lists. Files it says set BuildKeel up are committed on their own, as setting BuildKeel up, with no `BuildKeel-Unit` line, once the user agrees. For the rest, ask what to do, offering these choices: **commit them to the active unit** (the default, when there is one), with the message ending in `BuildKeel-Unit: <active unit ID>`; **set them aside**, after an explicit yes, with `git stash push --include-untracked -m "BuildKeel: set aside before starting <ID>"` (they come back with `git stash pop`); or **leave them, and do not start**. Then call `start_work` again. Never discard changes any other way.
+   - **Started:** tell the user the ID and the branch.
+
+## Make the change
+
+Make the change, and commit it with a message ending in `BuildKeel-Unit: <ID>`. If tests cover it, run them with a JUnit XML report and record it with the BuildKeel `test_results` tool. Then offer to finish it with /bk-done.
+
+Do not create or edit spec tree files yourself; `save_draft` writes the unit.

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

@@ -0,0 +1,52 @@
+---
+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."
+---
+
+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.
+
+Help the user approve a BuildKeel artifact. Approval is the user's decision: never approve anything they have not confirmed in this conversation.
+
+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").
+
+If the user typed nothing, ask straight away, before calling any tool: "What do you want to approve?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+
+1. **The drafts from this conversation, in one review** (the default, listed first): offer this only when drafts were saved in this conversation, such as by /bk-capture, and name them in the choice.
+2. **Show what is ready to approve** (the default when there are no drafts from this conversation).
+3. **Type an artifact ID.** If they pick this, ask for the ID.
+
+If they pick "Show what is ready", call the BuildKeel `query` tool with `view: "drafts"` and ask which to approve, showing its result as it is: what is ready to approve, and what is not ready yet with the reason. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Offer the ready ones as choices with the one you recommend first; several can be approved as a set. If nothing is ready, say what is blocking the drafts and stop.
+
+## A set in one review
+
+1. Call the BuildKeel `approve` tool with `ids` set to every artifact in the set, without `apply`. A version 0, which describes code as it was before BuildKeel, is named with `@v0`, such as `US-draft-k3x9@v0`; when the change built on it is a new version of the same artifact, the set holds both, `US-draft-k3x9@v0` and `US-draft-k3x9`, and version 0 is approved first. It shows the whole set in the order it will be approved, parents and their documents first, with what each will become and anything that would not pass, and why. Show it as it is.
+2. Ask, with your tool for asking a question with choices, showing the set as `approve` gave it: **Approve them** (the default; if some would not pass, the rest are approved and those stay drafts with what needs them), **Fix what would not pass first** (then fix each with `save_draft`, one at a time with the user, and check the set again), or **Stop**. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+3. Only when the user confirms, call `approve` again with the same `ids` and `apply: true`. Show the result as it is: it opens with what is now approved and what can start, then each approval, each its own record and commit.
+
+## One artifact
+
+1. Call `query` with `view: "artifact"` and the ID, and show the user the artifact so they know what they are approving. For a new version of an approved artifact, also call `query` with `view: "artifact"`, the ID and `version` set to the approved version, and say what changed since then.
+2. Call the BuildKeel `approve` tool with the `id` and without `apply`. It runs the approve gate and does not write anything.
+   - If it is refused, show every failing check with its fix, as it is. Offer to fix the draft (save the fix with `save_draft`, passing the draft's `id`) or to approve the parent first. Do not approve anything else in its place without asking.
+   - Otherwise, show what approval will do (the permanent number it will get, references that change, the commit) and ask the user to confirm. For a version 0, say that it describes the code as it was before BuildKeel and what it leaves empty: approving it means a person has read it.
+3. Only when the user confirms, call `approve` again with the same `id` and `apply: true`. Show the result, which opens with what was approved: the permanent ID, the files written, the commit, and whether it was pushed. If the number is pending because the spec repo's remote could not be reached, say so plainly: the approval is recorded, work on it cannot start until it has its number, and the number is assigned the next time the remote can be reached.
+
+## Its documents
+
+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
+
+Call `query` with `view: "drafts"` and show what is still waiting for approval, ready or not, as it is.
+
+If the approval result said approvals are not pushed, remind the user to push the spec repo when they are ready to share them. Then suggest the next step: approving something that is now ready, starting a unit that is ready with /bk-start, or building everything ready with /bk-build.
+
+Do not create or edit spec tree files yourself: `approve` and `save_draft` do all writing, and approved versions and approval records are never edited.

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

@@ -0,0 +1,61 @@
+---
+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."
+---
+
+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.
+
+Build every unit that is ready, one after another, with the user's one confirmation up front. Each unit still goes through its own start gate, gets its own branch, commits and completion record, and is tested before it is finished.
+
+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.
+
+If the user typed nothing, ask straight away, before calling any tool: "What should I build?" Offer the choices with your tool for asking a question with choices, if you have one:
+
+1. **Everything that is ready** (the default, listed first).
+2. **Only what is under one story or epic: type its ID.** If they pick this, ask for the ID.
+
+## List it and ask once
+
+Call the BuildKeel `query` tool with `view: "startable"`. Take the units ready to start, at the lowest level: tasks, and stories that have no tasks (with a parent named, only those under it). Leave out bugs and ad-hoc units unless the user asks for them. Order them by parent, then by ID, so that a story's tasks are built in order.
+
+If nothing is ready, show what is waiting and why, as `query` gave it, suggest the next step (such as approving with /bk-approve), and stop.
+
+Otherwise show the list in order, and say how the run goes: each unit is started, built, tested and finished in turn; each gets its own branch, stacked on the one before so later units build on the earlier ones' code; and the run stops to ask when a gate refuses, a test fails and cannot be fixed, or a requirement is unclear. Then ask, with your tool for asking a question with choices, showing the list and how the run goes. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. The choices:
+
+1. **Build them** (the default).
+2. **Change the list.** Take in what they say and show the list again.
+3. **Stop.**
+
+## Build each unit in turn
+
+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. 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.
+6. Say in a line what was finished: the unit, its commits, its test cases passing, and its completion record. Then go on to the next unit.
+
+## At the end
+
+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

@@ -0,0 +1,105 @@
+---
+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]."
+---
+
+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.
+
+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):
+
+- **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.
+
+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.
+
+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:
+
+1. **Create the artifacts** (the default, listed first).
+2. **Change something.** Take in what they say and show the summary again.
+3. **Keep talking.** Stop here: nothing is drafted, and the conversation goes on.
+
+Any other answer, such as a correction or a new thought, is more conversation: answer it as you would, and draft nothing.
+
+## 2. Propose the plan
+
+1. Call the BuildKeel `query` tool with `view: "process"` for the stages and the documents each requires, and with `view: "tree"` for what exists. Read an existing artifact with `view: "artifact"` when you need to know what it covers.
+2. Work out the artifacts the work needs, level by level, from the business idea down to the tasks, in the team's stage names: which already exist, which are new, and the documents each stage requires, such as a design document for a new epic and a test plan for each new story. For each task, work out which of its story's test cases its tests will implement. A task whose tests implement none of them, such as a building block (a client, a data model, a migration), needs a test plan of its own, or it can never be finished: put it in the table.
+3. Recommend where the work fits in the tree, and say why: under an existing business idea or epic, or as something new.
+4. If the work changes how something already built behaves, and a document describes how it works today (such as EP-01's design document for password reset), the plan includes a new version of that document.
+5. If the work changes code that already exists, work out which files it will change, from the discussion and the code, and call `query` with `view: "describes"` and their `paths`. Where an artifact describes them, the work builds on it. Where nothing describes the behavior the work changes, the plan includes a **version 0**: one artifact, usually a story, describing only what the work touches, as it works today, before the change. The change is then its version 1, or an artifact under it. A version 0 is a proposal: the user can drop it.
+
+Show the plan as a table, top down, and say where the work fits and why, in a sentence:
+
+| Level | Artifact | Status | Why |
+|---|---|---|---|
+| Business idea | BI-01 "Self-service account recovery" | exists | the goal this serves |
+| Epic | "Reset by text message" | new | the new capability |
+| Design document | of the new epic | new, required | how it is built |
+| Story | "Request a code by text" | new | one per user-facing behavior |
+| Test plan | one per story | new, required | covers every criterion |
+| Task | "SMS gateway client" | new | one per piece of code, with its repository |
+| Test plan | of "SMS gateway client" | new | its tests are none of the story's test cases |
+| Design document | EP-01-DD | new version | password reset now works differently |
+| Story | "Password reset" | version 0, then the change as version 1 | how reset by email works today, which nothing describes yet |
+
+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).
+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.
+
+## 3. Draft everything
+
+Only after the user agrees:
+
+- 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.
+- 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.
+- When the work changes how an existing capability works: save the new version of that capability's document with `save_draft` and its ID, and give the new artifact `changes: [<that document's ID>]`, so it cannot be finished until that version is approved.
+- A **version 0** in the plan is drafted before the change, by the rules below, with `save_draft` and `version: 0`. Name the paths it covers in its `scope`. Then draft the change: as its version 1, with `save_draft`, the version 0's draft ID as `id` and no `version`, holding the whole artifact as it will be after the change. Start from version 0's text as saved, with its entry IDs: keep the ID of every entry that stays, changed or not (a criterion whose limit changes keeps its ID), and write `{{new}}` only for an entry the change adds. Or, when the change is new work under it, as a new artifact whose `parent` is that draft ID.
+- Save each one with `save_draft`.
+
+### 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.
+
+- Reword what the code and the sources say into the template's form, such as a ticket's description written as testable criteria. Add nothing they do not support.
+- Describe only what the work touches, not the whole area around it.
+- Keep each source as you read it: pass it to `save_draft` in `sources`, with where it came from, its key and link, and its text exactly as your tool returned it (description, fields and comments). Never copy code into a source: the baseline commit names the code.
+- When a source and the code disagree, or two sources do (a ticket says a reset link lasts 30 minutes, the code makes it 60), ask the user which is intended, before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it with /bk-new bug once version 0 is approved. When the source is out of date, version 0 follows the code. Offer a third answer after those two, still with no recommendation: **Not sure: leave it open**. Then keep the question in the version 0 draft's front matter, under `openQuestions`, with an `id` (Q1, Q2, ...), what it is `about`, what the `code` does, what the `source` says and the `sources`' keys, and leave the part it concerns out of version 0: BuildKeel records who left it open, and version 0 waits for an answer before it can be approved. Someone who knows answers it later with /bk-onboard: add `answer: code` or `answer: source` to it, save the draft, and draft the part it concerns.
+- 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
+
+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.
+
+## 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. 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

@@ -0,0 +1,66 @@
+---
+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."
+---
+
+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.
+
+Finish a BuildKeel unit with the user. Finishing writes a permanent record of what was built, against which approved versions and with which test results, so it is the user's decision: never finish a unit they have not confirmed in this conversation.
+
+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.
+
+If the user typed nothing, ask straight away, before calling any tool: "What do you want to finish?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+
+1. **The active unit in this working tree** (the default, listed first).
+2. **Another unit, or a story or epic whose work is all done: type its ID.** If they pick this, ask for the ID.
+
+A story built through tasks, an epic, or a stage the team added above its stories, is never the active unit: it is finished once every unit under it is done and its own test cases pass, here or in the completion records of units finished in other repos.
+
+## Check it
+
+1. If the code changed since the tests last ran, run them again with a JUnit XML report (BuildKeel's instructions list the reporter for each test runner) and record the report with the BuildKeel `test_results` tool.
+2. Call the BuildKeel `finish_work` tool without `apply`, with `id` if the user named a unit. It runs the done gate and writes nothing.
+   - **Refused only because tests have no current result** (not run, or run before the code last changed): run the tests with a JUnit XML report, record it with `test_results`, and call `finish_work` without `apply` again. Do this once, without asking.
+   - **Refused by the done gate** for anything else: show every failing check with its fix, as it is, and where each test case stands. Offer the fix that comes first: commit uncommitted changes (ending the message with `BuildKeel-Unit: <ID>`), write a test that is missing its tag, fix a failing test, or run the tests again. Do not finish anything else in its place.
+   - **Not the active unit, or no active unit:** show the message and its fix.
+   - **A story or epic refused because work under it is open:** show every open unit with its fix, and where each test case stands. Offer to start the first open unit with /bk-start.
+   - **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:
+
+- If the result lists commits without a BuildKeel-Unit line, ask what to do with them:
+  1. **Count them all as <ID> work and finish** (the default).
+  2. **Choose which to leave out.** Then ask which ones, allowing several, and finish with those left out.
+  3. **Stop, and do not finish yet.**
+- Otherwise ask:
+  1. **Finish <ID>** (the default).
+  2. **Stop, and do not finish yet.**
+
+Only when the user confirms, call `finish_work` again with `apply: true` (and the same `id` if you passed one), with `exclude` listing the IDs of any commits they left out, and with `attach` when they chose where to attach a standalone bug.
+
+## Afterwards
+
+Show the result as it is: the completion record, the commit in the spec repo, and whether it was pushed. Remind the user to push the unit's branch and open a pull request as usual, and to push the spec repo when the record is not pushed. If test cases were left for the story, name them: the story cannot be finished until they pass.
+
+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

@@ -0,0 +1,53 @@
+---
+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."
+---
+
+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.
+
+Review change impact in BuildKeel with the user. A suspect is a task, story, epic, bug or test case built against an older version of something that has changed since, in what it relies on. Deciding on a suspect is the user's choice: never record a decision they have not confirmed in this conversation.
+
+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.
+
+If the user typed nothing, ask straight away, before calling any tool: "What do you want to review?" Offer the choices with your tool for asking a question with choices, if you have one, so the user can pick with the arrow keys and Enter:
+
+1. **Every suspect** (the default, listed first).
+2. **Type an ID:** an artifact with a new version in draft, to see what approving it would affect, or an artifact or test case to review on its own. If they pick this, ask for the ID.
+
+## Show the impact
+
+Call the BuildKeel `impact` tool, with `id` if there is one. Show its result as it is.
+
+- **A preview of a draft:** nothing is marked yet. Say what approving it would make suspect and which coverage gaps it would open, then stop. Offer to approve it with /bk-approve when the user is ready, or to change the draft first.
+- **Nothing suspect:** say so and stop.
+
+## Review each suspect, one at a time
+
+For each suspect in the result, in order:
+
+1. Show what it is and what changed with the question in step 3, never in a choice's label or description. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. For a test case, read its plan with `query` (`view: "artifact"` and the plan's ID) and show the test case with the old and new text of what it covers. For a task, story, epic or bug, show its own text (`query`, `view: "artifact"`) with the old and new text of what changed above it. For a finished unit, show the commits and files its completion record lists.
+2. Propose a decision, saying why in a sentence or two:
+   - **Still valid** when the change does not affect what it says, builds or checks, such as a rewording, or a change to something it does not rely on in substance.
+   - **Needs change** when what it says, builds or checks no longer matches the new text, such as a test case checking a 30-minute expiry when the criterion now says 15 minutes. For finished work, name the files that likely need to change.
+3. Ask the user to decide, 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

@@ -0,0 +1,42 @@
+---
+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]."
+---
+
+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.
+
+Set up BuildKeel in this repository using the BuildKeel `manage` tool with `action: "init"`. Ask the user one question at a time, each with your recommendation, and wait for the answer before asking the next.
+
+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.
+
+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. **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.
+
+   Pass the choice as `mode` (`spec-driven` or `full-sdlc`) in every call to `manage` below.
+
+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.**
+
+   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.
+
+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

@@ -0,0 +1,19 @@
+---
+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."
+---
+
+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.
+
+Upgrade the spec tree to the format this version of BuildKeel uses. A tree in an older format can be read but not changed until it is migrated.
+
+Call the BuildKeel `manage` tool with `action: "migrate"`, without `apply`, and show the result as it is.
+
+- If it says there is nothing to migrate, or that the plugin needs an update first, say so and stop.
+- Otherwise it lists what changes: the working files and `buildkeel.yaml`, in one commit, with frozen versions and records left exactly as they are. Ask the user to confirm, with your tool for asking a question with choices: **Migrate** (the default) or **Not now**.
+
+Only when the user confirms, call `manage` again with `action: "migrate"` and `apply: true`, and show the result as it is. Remind the user to push the spec repo, and that teammates need this version of BuildKeel, or a later one, to work in the tree.
+
+Do not change spec tree files yourself; the `manage` tool does all of it.