buildkeel 0.1.0 → 0.3.0

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

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

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

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

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

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

package/antigravity/templates/design.md

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

package/antigravity/templates/epic.md

@@ -10,6 +10,7 @@ sections:
   Summary: { required: true }
   Scope: { required: true, tracked: true }
   Out of scope: { tracked: true }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---
 

package/antigravity/templates/idea.md

@@ -10,6 +10,7 @@ sections:
   Problem: { required: true, tracked: true }
   Goals: { required: true, tracked: true, items: { prefix: G, style: list } }
   Success measures: { tracked: true }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---
 

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,40 @@
+---
+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." }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
+  Notes: { offered: "Background, links, and anything from a source that fits no other section." }
+---
+
+## Why
+
+<!-- The problem or the opportunity, and why it is worth doing now. One or two short paragraphs. -->
+
+## What changes
+
+<!-- One line per change in behavior, interface or data. Mark each change that breaks existing users or callers with **BREAKING**. -->
+
+## Capabilities
+
+<!--
+Each capability the change adds or alters, by code, with what changes in it. The capabilities field lists the same codes.
+
+- **AUTH** (modified): reset links expire after 30 minutes.
+- **SMS** (new): sending one-time codes by text message.
+
+A change that alters no behavior, such as a refactor, says so here, sets noSpecChanges: true, and has no spec changes.
+-->
+
+## Impact
+
+<!-- The code, APIs, dependencies, data and systems the change affects. -->

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

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

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

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

package/antigravity/templates/story.md

@@ -10,6 +10,7 @@ sections:
   Summary: { required: true }
   Story: { required: true, tracked: true }
   Acceptance criteria: { required: true, tracked: true, items: { prefix: AC, style: list } }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---
 

package/antigravity/templates/task.md

@@ -9,6 +9,7 @@ fields:
   scope: { type: list }
 sections:
   Description: { required: true, tracked: true }
+  Open questions: { offered: "Questions left open, each with what it is about, to settle later. They do not block approval: the approval summary lists them." }
   Notes: {}
 ---