buildkeel 0.0.1 → 0.2.0

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

@@ -0,0 +1,112 @@
+---
+name: bk-new
+description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a bug. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or bug TK-001."
+---
+
+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.
+
+Draft BuildKeel artifacts with the user. Everything you produce is a draft: drafting never approves anything, and every draft goes through the same checks and approval as one written by hand. A bug is the exception: it is recorded at once, with its permanent ID, and needs no approval (see "Bugs" below).
+
+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.
+
+Take the examples word for word from BuildKeel's session report when it gives them ("Examples of what to draft, in the team's words"): they use the names this team gives its stages, which may not be the usual ones. Only when it gives none, use `story EP-01`, `stories from EP-01`, `test-plan US-001` and `bug TK-001`.
+
+Offer two choices: **Suggest what to draft next** (the default, listed first) and **Type what to draft**; if they pick the second, ask what to draft. If they pick the suggestion, call the BuildKeel `query` tool with `view: "tree"`, propose the most useful next drafts (such as stories for an epic that has none, or a missing test plan), and ask which to draft. Then carry on below with their answer as the request.
+
+## Work out what to draft
+
+- **The type**: idea, epic, story, task, test-plan, design (a design document) or bug, or a stage or document the team added (the user may use their team's own name for it). If it is not clear, ask. For a bug, follow "Bugs" below instead of the rest of this prompt.
+- **The parent**: every type except a business idea has one: an artifact's parent is of the stage directly above it in the process (by default an epic's parent is a business idea, a story's an epic and a task's a story; with a stage added between epic and story, a story's parent is of that stage), and a test plan's parent is the artifact it tests. If the user did not name it, call the BuildKeel `query` tool with `view: "tree"`, suggest the likely parent, and ask.
+- **One draft or a breakdown**: a request such as "stories from EP-01" or "break EP-01 down" asks for a set of children of one parent. Anything else is a single draft.
+- **The user's own material**: if the user pasted text, named or uploaded a file, pointed to something in a tool you can read (such as an issue tracker or a wiki), or described the requirement, use it as the main input. Fit it to the template: put each part in the section it belongs to, keeping its meaning and wording; put what fits no section in the section for further material, such as Notes; and for each required section it does not cover, ask the user, one question at a time. Never invent a requirement, a criterion or a section to fill a gap, and never add a detail the material leaves open, such as how a notice reaches the customer: ask, or keep the wording as open as the material's.
+- **What it should cover**: for a single draft, if the user has not said what it is about, ask before writing. Offer suggestions drawn from the parent, but do not choose the requirement for them. A breakdown needs no such question: its scope is the parent's.
+- **Code nothing describes yet**: when the artifact changes how code that already exists behaves, such as a story or task that changes something already built, work out which files it will change and call `query` with `view: "describes"` and their `paths`. If nothing describes the behavior it changes, say so in one sentence, and ask with your tool for asking a question with choices: **Draft a version 0 of what it changes first** (the default, listed first): how that code works today, so the change has a "before"; or **Draft only the new artifact**. With version 0, draft it first (see "Version 0" below), then the requested artifact: as its version 1 when it changes the same behavior, or under it.
+
+Ask one question at a time, with your recommendation, and only for what you cannot work out.
+
+## Read before writing
+
+1. Call `get_template` for the type. Your draft must contain every field and section the template declares, in that structure.
+2. Call `query` with `view: "artifact"` and the parent's ID, and read it. For a breakdown, also read the parent's own parent when it helps.
+3. Read the user's material, if any: the file, the pasted text, or what your tools return for the issue or page they named.
+
+## Write each draft
+
+- Fill every section with real content. Remove the template's guidance comments.
+- Write `{{id}}` wherever the artifact's own ID goes: `id: {{id}}`. BuildKeel assigns the ID.
+- Write each new numbered entry with `{{new}}` as its number: `- **{{id}}-AC{{new}}** ...` or `### {{id}}-TC{{new}} ...`. BuildKeel numbers them in order. When you revise an artifact, keep the ID of every entry that already has one, and write `{{new}}` for entries you add: a removed entry's ID is never given to a new one.
+- Set `parent` to the parent's ID. BuildKeel pins it to the parent's approved version.
+- Keep each **Summary** to two or three sentences that stand on their own: it is what the agent later reads about this artifact when working further down.
+- Acceptance criteria are specific and testable, one behavior each.
+- Save it with `save_draft` (type and content). To change a draft you already saved, pass its `id`.
+
+## Version 0
+
+Version 0 describes what code already does, as if BuildKeel had been used from the start, so a change to it has a "before". Draft it with `save_draft` and `version: 0`; to add one to an artifact that already exists, pass its `id` too. Name the paths it covers in its `scope`.
+
+- 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. 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.
+
+## Test plans
+
+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. 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.
+
+To see what a plan covers and what it leaves out, call `query` with `view: "coverage"` and the artifact's ID.
+
+## Design documents
+
+A design document says how an artifact's work is built, usually an epic's. It belongs to one artifact (its `parent`), has no `id` field, and is named after it, such as `EP-01-DD`. Its template keeps a short skeleton: fill in what applies, and add an offered section (`get_template` lists them, such as Rollout and rollback) only when the work needs it. The summary, context and design are required: ask for whichever the user's material does not give.
+
+The process may require other documents of a stage, such as a team's threat model: draft them the same way, with their own template.
+
+## Breakdowns
+
+- **Stories from an epic**: draft several stories that together deliver the epic's scope, each with acceptance criteria. For each story, also draft its test plan with `save_draft` (type `test-plan`, parent set to the story's draft ID), with test cases written as `### {{id}}-TC{{new}} ...` and a `covers:` line listing the acceptance criteria each one checks. Every acceptance criterion must be covered by at least one test case.
+- **Epics from a business idea**, or **tasks from a story**: draft the children the same way. A task names the code repository it is built in (`repo`) and, when you can tell, the paths it will touch (`scope`). Tasks are drafted from a story's latest approved version when it has one.
+- **For each task**, decide which of the story's test cases its tests will implement, and say so in the list you propose. If its tests will not be story test cases, draft the task's own test plan too (type `test-plan`, parent set to the task's draft ID), with test cases that cover the task, such as `covers: [{{id}}]`.
+- Before writing, show the user the list of children you propose (titles and a line each) and ask whether to go ahead or change it.
+
+## Bugs
+
+A bug is a defect in work that was planned: it is recorded straight away with its permanent ID, needs no approval, and is worked on like any unit. Finishing it needs a regression test with the bug's ID in its name, such as `it("keeps reset links for 30 minutes [BUG-005]", ...)`.
+
+1. **Where it was found.** If the user named a task or story, use it. Otherwise ask, with your tool for asking a question with choices, offering **the active unit** first when there is one, then **another task or story: type its ID**, then **nowhere known yet** (a standalone bug, such as one a customer reported). A bug is attached to a task or a story, never to an epic or anything else.
+2. **The test case that found it**, when a test failed: call `query` with `view: "coverage"` and the unit's ID to see the test cases that apply there, and offer them, with **none** last. A standalone bug has none.
+3. **What is wrong.** Use the user's description, or ask for it in their own words: never offer descriptions you made up as choices, since a bug records what someone saw. Write a title that names the defect, such as "Reset link expires after 3 minutes".
+4. Call `get_template` for `bug`, then `save_draft` with `type: "bug"` and the whole file: `id: {{id}}`, the title, `parent` set to the unit's ID and `testCase` to the test case's ID when there are any, and the sections filled in (what is wrong, steps to reproduce, expected, actual). Leave out sections you know nothing about rather than inventing them.
+5. Show the result: the bug's ID, where it is attached, and that it can be started with /bk-start <ID>. If fixing it means a requirement must change, say so: that change is made as a new version of the story or task, approved as usual.
+
+## 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; 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

@@ -0,0 +1,135 @@
+---
+name: bk-onboard
+description: "BuildKeel: Document code that existed before BuildKeel, area by area: map the code, then draft each area for people to review and approve. Run as /bk-onboard [an area to onboard, or nothing to choose]."
+---
+
+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.
+
+Document the code that existed before BuildKeel with the user, one capability area at a time. People lead it: you propose and draft, the user corrects, completes and approves, and nothing is approved without them. They can stop after any area and carry on later; whatever they leave is documented as work touches it.
+
+What describes code from before BuildKeel is version 0 of its artifact: the artifact as it would read had BuildKeel been used from the start, drafted from the code and from the material the user brings.
+
+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.
+
+- When there is a map: **Continue with an area**, **Adjust the map**, **Fill in what onboarding left empty** (only when the view lists anything), **Stop**. When the user continues, ask which area, as in "Choose an area" below.
+- When there is none: **Map the code** (the default), **Fill in what onboarding left empty** (only when the view lists anything), **Stop**.
+
+If the user typed an area's name above, onboard that area. Ask one question at a time, each with your recommendation, and only for what you cannot work out. Two kinds of question carry no recommendation, because only the user knows the answer: which of two disagreeing sources is intended, and what a section nothing supports should say.
+
+## Map the code
+
+1. Read the code's layout: its top-level folders, entry points, routes or handlers, and what the README says. Call `query` with `view: "tree"` for what the spec tree already holds.
+2. Propose capability areas: what the product does, in the words its users would use ("Password reset", "Invoicing"), not one area per folder. Give each the paths it covers, its repository when the tree serves several, and one line on what it does. Make them a table, with a column for the area, its paths and what it does, in the order you recommend onboarding them, and say why in a sentence.
+3. Ask: **Use this map** (the default), **Merge, split or rename areas**, or **Stop**, showing the table and that sentence, so the user sees what is mapped to what before choosing. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Take in each change, and ask again with the whole table.
+4. Once the user agrees, write the map with `manage`, `action: "map"`, `map: "set"` and the `areas`. Later changes to a written map use `map: "merge"`, `"split"` or `"rename"`. Then ask which area to onboard, as in "Choose an area", showing the table `manage` returns, as it is. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+
+## Choose an area
+
+Offer each area that is not onboarded yet as its own choice, in the map's order, so the user picks among all of them, never between your pick and stopping alone. Mark the next one in the map's order as the default, and add **Stop**. When there are more areas than your host's choices allow, list the first ones and let the user type another area's name.
+
+## Onboard an area
+
+### 1. Find out what there is
+
+- Call `query` with `view: "onboarding"`. When the area is partly done, call `query` with `view: "describes"` and its files: draft only what nothing describes yet.
+- Read the code under the area's paths as it was at the baseline commit, which `buildkeel.yaml` names for each repository (`git show <baseline>:<path>`): version 0 describes the code before BuildKeel.
+- Call `query` with `view: "process"` for the stages and the documents each requires, and `view: "tree"` for where the area fits, such as under an existing business idea or epic.
+- Ask the user what they have about this area: a project or epic in their issue tracker, wiki pages, documents, or what they know. Read what they point to through their own tools; BuildKeel connects to no other tool. When you cannot reach it, ask them to paste it, and do not suggest setting up a connection. If they have nothing, draft from the code and from what they tell you.
+
+### 2. Propose what the area needs
+
+Show a table of the artifacts the area needs, top down, in the team's stage names, each existing or to draft:
+
+| Level | Artifact | Version | From |
+|---|---|---|---|
+| Business idea | BI-01 "Self-service account recovery" | exists | |
+| Epic | "Password reset" | version 0 | the code, Confluence "Reset design" |
+| Design document | of that epic | version 1 | the code: no source has one |
+| Story | "Reset by email" | version 0 | the code, PAY-12 |
+| Test plan | of that story | version 1 | one test case per criterion |
+| 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.
+- When an artifact in BuildKeel already describes part of the area, see "Version 0 under an existing artifact" below.
+
+Ask: **Draft them all** (the default), **Change the plan**, **Skip this area**, or **Stop**, showing the table. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting.
+
+### 3. Draft everything
+
+Only once 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.
+
+**Each version 0**, with `save_draft` and `version: 0`:
+
+- Fill the template's sections from the code and the sources, rewording what they say into the template's form, such as a ticket's description written as testable criteria. Add nothing they do not support. 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, and a design's context are rarely in the code or a ticket: write a story's Story section only from a source or the user that says who wants it and why, and otherwise ask, as below.
+- 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. 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.
+
+**Each version 1**, such as a design document or test plan no source has: draft it with `save_draft` and no `version`, from the code, as for any new artifact. It is held to its template, so it cannot leave a required section empty, and "Leave it empty" is never a choice for it. For each required section the code does not give, such as a design's context, ask the user, with what the code shows as a starting point they can accept or change: for code from before BuildKeel, "Built before BuildKeel; why is not recorded" is a fair answer when nobody knows.
+
+A test plan has a test case for each acceptance criterion of its story. A finished task's test cases, if it has any, come from its sources.
+
+### 4. Review and approve
+
+Show what was drafted as a table: ID, title, version, the sources kept, and the sections left empty. Then offer to approve the area's drafts in one review: call `approve` with `ids` set to all of them and `onboard: true`, first without `apply`, and ask whether to approve them, showing the table and the result as it is. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Call it again with `apply: true` only when the user confirms. Each version 0 is approved first, and a finished task's version 0 is linked to the commits before the baseline that name its key.
+
+### 5. Existing tests
+
+Once the area is approved:
+
+1. Run the tests with a JUnit XML report and record it with `test_results`, as the agent instructions describe.
+2. Call `query` with `view: "untested"` and the area's epic or story: it lists the test cases with no test, and the tests in the report that match no test case.
+3. Propose which existing tests implement which test cases, as a table, naming each test exactly as the report does. Ask the user to confirm or correct it, showing the table. Put what you show in the question itself, after a question of one sentence: your question tool shows tables and formatting. Then record each with `manage`, `action: "match"`, the test case's `id` and its `tests`. The code is never changed.
+4. Call `query` with `view: "untested"` again and show the gap report: the behavior with no test, and the tests that test no stated behavior.
+
+### 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**; 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
+
+When the user says a drafted behavior is a defect, not what was intended: revise version 0 to state the intended behavior, and once the area is approved, record the defect as a bug against that story: `save_draft` with `type: "bug"`, `parent` set to the story's ID, `testCase` set to the test case that covers that criterion when the story's test plan has one, its Expected naming the criterion (its ID and text), and its Actual saying what the code does instead. Fixing it is then work like any bug, and a test matched to that test case is tagged as the fix changes it.
+
+## Version 0 under an existing artifact
+
+An artifact made in BuildKeel can get its version 0 later: how its code worked at the baseline commit. Draft it with `save_draft`, the artifact's `id` and `version: 0`, from the code at the baseline (`git show <baseline>:<path>`), by the same rules. Its ID never changes.
+
+When the version in force leaves out behavior that version 0 describes, also draft the next version with the complete picture: the version in force wherever the two overlap, version 0 only where the version in force says nothing, and both checked against today's code. Give it `completes: <the version in force>` in its frontmatter: it changes no code, so nothing built on the version in force becomes suspect, and the criteria it adds are coverage gaps until the test plan covers them. Approve version 0 and that version in one review, version 0 first (`<ID>@v0`, then `<ID>`). When the version in force already describes everything, draft only version 0.
+
+## Fill in what onboarding left empty
+
+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

@@ -0,0 +1,44 @@
+---
+name: bk-start
+description: "BuildKeel: Start work on a task, story, bug or ad-hoc unit: check it is ready, switch to its branch and load its context. Run as /bk-start [unit ID], e.g. TK-001."
+---
+
+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.
+
+Start work on a BuildKeel unit with the user. Every code change belongs to exactly one unit, and the unit's context tells you what to build.
+
+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.
+
+If the user typed nothing, ask straight away, before calling any tool: "What do you want to start?" Offer the choices with your tool for asking a question with choices, if you have one:
+
+1. **Show what can be started** (the default, listed first).
+2. **Type a unit ID.** If they pick this, ask for the ID.
+
+If they pick the first choice, call the BuildKeel `query` tool with `view: "startable"` and show its result as it is. Then ask which unit to start, offering the ready ones as choices with the one you recommend first. If nothing is ready, say what is in the way and suggest the next step, such as approving with /bk-approve.
+
+## Start it
+
+Call the BuildKeel `start_work` tool with the unit's `id`.
+
+- **Refused by the start gate:** show every failing check with its fix, as it is. Offer the fix that comes first, such as approving the story or its test plan. Do not start anything else in its place without asking.
+- **Uncommitted changes:** show the files it lists. If it says some of them set BuildKeel up (such as `.buildkeel.yaml` or the spec tree's `buildkeel.yaml`), offer first **Commit them as setting BuildKeel up** (the default): commit only those files, with a message such as "Set up BuildKeel" and no `BuildKeel-Unit` line, then deal with any other files as below, and call `start_work` again. Every other change must belong to one unit, so ask the user what to do with them, offering these choices:
+  1. **Commit them to the active unit** (the default, when there is one). Show what will be committed, commit it with the message ending in `BuildKeel-Unit: <active unit ID>`, then call `start_work` again. When there is no active unit, ask which unit the changes belong to instead.
+  2. **Set them aside.** List the files again and ask for an explicit yes. Then run `git stash push --include-untracked -m "BuildKeel: set aside before starting <ID>"`, tell the user they can bring the changes back with `git stash pop`, and call `start_work` again.
+  3. **Leave them, and do not start.**
+
+  Never discard changes any other way.
+- **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

@@ -0,0 +1,38 @@
+---
+name: bk-stats
+description: "BuildKeel: Show your own BuildKeel usage over a period: units finished, time to done, what the gates caught, suspects decided. Kept on this machine only. Run as /bk-stats [days], e.g. 30; or off, on, delete or export to change the record."
+---
+
+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.
+
+Show the user their own use of BuildKeel in this spec tree, from the record kept on their machine. The record holds IDs, types, outcomes and times, never artifact text or code, and nothing is ever sent anywhere.
+
+The user typed: whatever follows /bk-stats in the user's message (nothing, if they typed only /bk-stats)
+
+## Choose the period
+
+If the user typed a number of days, use it. If they typed off, on, delete or export, change the record as below.
+
+If the user typed nothing, ask straight away, before calling any tool: "Which period?" Offer the choices with your tool for asking a question with choices, if you have one:
+
+1. **The last 30 days** (the default, listed first).
+2. **The last 7 days.**
+3. **All of it.**
+4. **Change the record:** turn recording off or on, delete it, or export it.
+
+## 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. In a Spec-driven tree it counts changes and what finishing them reported, in place of gate figures.
+
+## Change the record
+
+Only on the user's request, with the BuildKeel `manage` tool and `action: "usage"`:
+
+- **Off:** `usage: "off"`. Nothing new is recorded; everything else works as before.
+- **On:** `usage: "on"`.
+- **Delete:** say that it deletes the record on this machine and cannot be undone, and ask for an explicit yes; then `usage: "delete"`.
+- **Export:** ask where to write the file, suggesting `~/buildkeel-usage.jsonl`, then `usage: "export"` with that `path`.
+
+Show the result as it is.

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

@@ -0,0 +1,18 @@
+---
+name: bk-status
+description: "BuildKeel: Show the overview: the tree with each artifact's state, work in progress, claims, coverage gaps, unpushed approvals, commits with no unit, and what can be started next. Run as /bk-status."
+---
+
+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.
+
+Call the BuildKeel `query` tool with `view: "status"`.
+
+Show the user the result as it is, keeping its indentation, which shows the hierarchy. Do not summarize or reorder it. If it lists problems or files changed outside BuildKeel, show them with their fixes.
+
+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/adhoc.md

@@ -0,0 +1,15 @@
+---
+template: adhoc
+version: 2
+description: A small change recorded so that every commit traces to a unit of work.
+fields:
+  title: { required: true }
+  scope: { type: list }
+sections:
+  Description: { required: true }
+  Notes: { offered: "Links, and anything that fits no other section." }
+---
+
+## Description
+
+<!-- What changed and why, in a sentence or two. -->

package/antigravity/templates/bug.md

@@ -0,0 +1,33 @@
+---
+template: bug
+version: 2
+description: A defect. Attach it to the work and test case where it was found, or leave it standalone.
+fields:
+  title: { required: true }
+  parent: { type: link }
+  testCase: {}
+  severity: {}
+  scope: { type: list }
+sections:
+  Description: { required: true, tracked: true }
+  Steps to reproduce: {}
+  Expected: {}
+  Actual: {}
+  Notes: { offered: "Logs, links, and anything from a report that fits no other section." }
+---
+
+## Description
+
+<!-- What is wrong. -->
+
+## Steps to reproduce
+
+<!-- Numbered steps. -->
+
+## Expected
+
+<!-- What should happen. -->
+
+## Actual
+
+<!-- What happens instead. -->

package/antigravity/templates/design.md

@@ -0,0 +1,48 @@
+---
+template: design
+version: 1
+description: How a stage's work is built, and the decisions behind it. Fill in what applies; add an offered section only when the work needs it.
+fields:
+  parent: { required: true, type: link }
+sections:
+  Summary: { required: true }
+  Context: { required: true }
+  Goals and non-goals: {}
+  Design: { required: true, tracked: true }
+  Decisions: { tracked: true }
+  Risks and trade-offs: {}
+  Architecture: { tracked: true, offered: "The components, how they connect, and where each one runs." }
+  Data: { tracked: true, offered: "What is stored, its shape, and how it changes over time." }
+  Interfaces: { tracked: true, offered: "The APIs, events and contracts other code relies on." }
+  Security and privacy: { offered: "Who can do what, which data is sensitive, and how it is protected." }
+  Performance and scale: { offered: "The expected load, the limits, and how the design meets them." }
+  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." }
+---
+
+## Summary
+
+<!-- Two or three sentences: what is built and how. Approved with the document, and what the agent reads about it when working under it. -->
+
+## Context
+
+<!-- What exists today, and why this work is needed. -->
+
+## Goals and non-goals
+
+<!-- What the design must achieve, and what it deliberately leaves out. -->
+
+## Design
+
+<!-- How it works: the parts, what each does, and how they fit together. -->
+
+## Decisions
+
+<!-- One entry per decision: ### 1. <the choice>, then why, and the alternatives considered. -->
+
+## Risks and trade-offs
+
+<!-- What could go wrong or is given up, and how that is handled. -->

package/antigravity/templates/epic.md

@@ -0,0 +1,30 @@
+---
+template: epic
+version: 1
+description: A body of work that delivers part of a business idea, broken down into user stories.
+fields:
+  title: { required: true }
+  parent: { required: true, type: link }
+  scope: { type: list }
+sections:
+  Summary: { required: true }
+  Scope: { required: true, tracked: true }
+  Out of scope: { tracked: true }
+  Notes: {}
+---
+
+## Summary
+
+<!-- Two or three sentences. Approved with the epic, and what the agent reads about it when working on its stories' tasks. -->
+
+## Scope
+
+<!-- What this epic delivers. -->
+
+## Out of scope
+
+<!-- What it deliberately leaves out. -->
+
+## Notes
+
+<!-- Background and links. Changes here never make other work suspect. -->

package/antigravity/templates/idea.md

@@ -0,0 +1,34 @@
+---
+template: idea
+version: 1
+description: A business idea, the top of the lineage. States the problem worth solving and how success is measured.
+fields:
+  title: { required: true }
+  scope: { type: list }
+sections:
+  Summary: { required: true }
+  Problem: { required: true, tracked: true }
+  Goals: { required: true, tracked: true, items: { prefix: G, style: list } }
+  Success measures: { tracked: true }
+  Notes: {}
+---
+
+## Summary
+
+<!-- Two or three sentences. Approved with the idea, and what the agent reads about it when working on anything below it. -->
+
+## Problem
+
+<!-- Who has the problem, how often, and what it costs them today. -->
+
+## Goals
+
+<!-- One entry per goal, each an outcome that can be measured after release, with an ID: - **BI-01-G1** Customers recover their own accounts. -->
+
+## Success measures
+
+<!-- How you will know the goals are met. -->
+
+## Notes
+
+<!-- Background and links. Changes here never make other work suspect. -->

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