buildkeel 0.4.0 → 0.5.0

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

@@ -1,29 +1,32 @@
 ---
 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, only when the user types it."
+description: "BuildKeel: Draft an artifact, break a parent down into drafts of its children, or record a defect. Run as /bk-new <type> [parent ID] [what to draft], e.g. story EP-01, stories from EP-01, or defect 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.
 
 Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
 
-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).
+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 defect is the exception: it is recorded at once, with its permanent ID, and needs no approval (see "Defects" 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".
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
+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 "Defects".
 
 ## 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.
+Ask straight away, 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`.
+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 `defect 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 type**: idea, epic, story, task, test-plan, design (a design document) or defect, or a stage, kind or document the team added (the user may use their team's own name for it). If it is not clear, ask. For a defect, follow "Defects" below instead of the rest of this prompt.
+- **The kind**, when the stage of the type holds more than one (`query` with `view: "process"` lists the kinds at each stage), and the user did not name one: propose one from where the work came from, and say why, such as an enhancement because it improves an existing export screen. Ask the user to confirm it or pick another, before drafting; never pick one without their answer. Draft it with the kind as the type, from that kind's template. For a breakdown, propose a kind for each child in the list of children, and the user confirms them there.
 - **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.
@@ -55,7 +58,7 @@ Version 0 describes what code already does, as if BuildKeel had been used from t
 - Fill the template's sections from the code and from what the user brings about it, such as a ticket or a wiki page read through their own tools, a file, or what they say. Reword what they say into the template's form, such as a ticket's description written as testable criteria; add nothing they do not support.
 - Describe only what the change touches.
 - Keep each source as you read it: pass it in `sources`, with where it came from, its key and link, and its text exactly as your tool returned it (description, fields and comments). Never copy code into a source.
-- When a source and the code disagree, or two sources do, ask the user which is intended before drafting that part. Only the user knows, so recommend neither answer, and offer both as equals: **The code is right; the source is out of date** and **The source is right; the code has a defect**. When the code is wrong, version 0 states the intended behavior, and the defect is recorded as a bug against it once version 0 is approved. When the source is out of date, version 0 follows the code. 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.
+- 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 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.
@@ -84,15 +87,28 @@ The process may require other documents of a stage, such as a team's threat mode
 - **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
+## Defects
+
+A defect is code that does not do what was agreed. Finishing it needs a regression test with the defect's ID in its name, such as `it("keeps reset links for 30 minutes [DEF-005]", ...)`.
+
+Once the user says a defect was reported (step 1), sort the report before going on, and record it here only when they confirm it is a defect; a change in behavior or a gap is drafted as that work instead.
+
+**Sorting a report.** When someone reports that the system does something wrong, check it before recording anything: what the spec says about that behavior now (in a Spec-driven tree, `query` with `view: "capabilities"` and the capability's `id`; otherwise the stories and their acceptance criteria, with `query`), and the code linked to it (`query` with `view: "describes"` and the files involved). Then propose one reading, labelled as yours, such as "My reading: a defect", with what it rests on:
+
+- **A defect**: the code does not do what the spec says. The code is fixed and the spec keeps its version. It is recorded as a defect with `source: reported`.
+- **A change in behavior**: the code does what the spec says, and the user wants something else. The spec changes and gets a new version: in a Spec-driven tree through a change, otherwise through a new version of the story, or a new item of the team's kind for it, such as an enhancement.
+- **A gap**: the spec says nothing about it. Settle with the user what it should do; that goes into the spec as a change in behavior.
+- **Nothing describes this code yet**: `describes` finds no artifact for it. In Full SDLC, draft version 0 of the story the code belongs to first, stating the intended behavior, and record the defect with that draft as its parent; both are reviewed and approved together, version 0 first. In a Spec-driven tree, ask **Record it standalone** (the default) or **Document this code first**, as version 0 of a capability spec, then link the defect to its requirement.
 
-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]", ...)`.
+Ask with your tool for asking a question with choices, your reading first, then the other readings, so the user confirms or overrides it. Record nothing until they answer. A defect found while building, such as a failing test of the work under way, needs no sorting: it is a defect of that work.
 
-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-build <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.
+1. **Found while building, or reported.** Ask, with your tool for asking a question with choices: **Found while building** (a test failed, or it showed up during the work; the default when a unit is active) or **Reported** (by users, customers or testers; the default when no unit is active). Set `source` to `found` or `reported`.
+2. **Where it belongs.**
+   - **Found while building:** the task or story being built. If the user named one, use it. Otherwise offer **the active unit** first, then **another task or story: type its ID**. Then 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.
+   - **Reported:** the work it affects, of a kind the process allows as a defect's parent (a user story unless the team chose others). If the user named it, use it. Otherwise ask which files or behavior the report points to, call `query` with `view: "describes"` and those `paths`, and offer the parents it lists, the first as the default, then **another: type its ID**. When it says nothing describes that code, follow "Nothing describes this code yet" above, drafting version 0 as in "Version 0".
+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 defect records what someone saw. Write a title that names the defect, such as "Reset link expires after 3 minutes".
+4. Call `get_template` for `defect`, then `save_draft` with `type: "defect"` and the whole file: `id: {{id}}`, the title, `source`, `parent`, `testCase` when a test case found it, 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. A defect found while building has its permanent ID at once and can be started with /bk-build <ID>. A reported defect is a draft: it is approved with /bk-approve like any draft, gets its number then, and is started after that. 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
 
@@ -102,9 +118,9 @@ 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.
+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 defect is recorded as in "Defects", with its `source`, and needs no approval: one found while building is attached to the change whose work found it (its `parent` is the change's ID, its `testCase` the scenario whose test found it), and a reported one stands alone; 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.
+- **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 `defect 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`; read it first with `query`, `view: "changes"`, the change's `id` and `file`. To change one requirement of a spec change, pass `capability` and `requirement` in place of `content`. Then check the change's other files against it and propose the follow-on edits, such as a task for a new requirement.

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

@@ -24,6 +24,14 @@ Call the BuildKeel `query` tool with `view: "onboarding"`; it changes nothing. T
 
 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.
 
+Topics for this step, for each area, in this order:
+
+- **the artifacts** the area needs, and the kind of each where a stage holds more than one;
+- **each disagreement** between a source and the code, or between two sources;
+- **each required section** nothing supports.
+
+Work from the topics listed for this step. The user may answer in their own words, several topics at once or part of one. After each answer, say which topics it settled, with what you understood for each, and which are left; then ask the next one left, one topic per message. Where a topic has a default, list keeping it first, naming its actual value, and give examples where they help. Anything you work out that the user did not say is a proposal: ask it as that topic's question, with it as the default, and never use it without the user's answer. Ask about an unclear answer; name a conflicting one beside the earlier answer and ask which holds. Never guess. When every topic is settled, show all of it, as a review.
+
 ## 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.
@@ -48,20 +56,23 @@ Offer each area that is not onboarded yet as its own choice, in the map's order,
 
 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 |
+| Level | Kind | Artifact | Version | From |
+|---|---|---|---|---|
+| Business idea | business idea | BI-01 "Self-service account recovery" | exists | |
+| Epic | epic | "Password reset" | version 0 | the code, Confluence "Reset design" |
+| Design document | | of that epic | version 1 | the code: no source has one |
+| Story | user story | "Reset by email" | version 0 | the code, PAY-12 |
+| Story | feature | "Reset by text" | version 0 | the code, PAY-20, labelled a feature |
+| Test plan | | of each story | version 1 | one test case per criterion |
+| Task | task | PAY-14 "Email template" | version 0 | finished in Jira |
+| Left out | | PAY-31 "Reset by security question" | | open in Jira: drafted with /bk-new when someone takes it up |
+
+When a stage holds more than one kind (`query` with `view: "process"` lists them), propose the kind of each artifact at that stage from where it came from, such as a ticket labelled a feature or a change to existing behavior, and say why in the table. The user confirms or changes each kind before anything is drafted; never pick one without their answer. Each is drafted with its kind as `type`, from that kind's template.
 
 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.
+- Tasks and defects 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.
 
@@ -80,7 +91,7 @@ Only once the user agrees. Draft top down, parents before children, so each chil
 - 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 finished task, and each defect fixed before BuildKeel**, is a version 0 too: `save_draft` with `type: "task"` or `"defect"`, `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 defect that was already fixed as an open defect.
 
 **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.
 
@@ -105,7 +116,7 @@ Call `query` with `view: "onboarding"` and ask which area to onboard next, as in
 
 ## 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.
+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 against that story: `save_draft` with `type: "defect"`, `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 defect, and a test matched to that test case is tagged as the fix changes it.
 
 ## Version 0 under an existing artifact
 

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

@@ -0,0 +1,18 @@
+---
+name: bk-settings
+description: "BuildKeel: Show how this repository is set up: the mode, where the spec tree lives, the process and its gates, or the numbering, and each template with where it comes from. Changes nothing. Run as /bk-settings."
+---
+
+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.
+
+Whenever a step says to show something and ask about it, write it out in your reply as normal text and end that reply with the question in plain text, calling no tool after it: the user may see nothing you wrote before a tool call. Use your tool for asking a question with choices only for a quick choice with nothing to read, and put in the question itself anything the user needs to choose.
+
+Call the BuildKeel `query` tool with `view: "settings"`.
+
+Show the user the result as it is, in your reply as normal text, with its table: do not summarize or reorder it.
+
+If the result says this repository is not set up for BuildKeel, tell the user how to set it up with /bk-init, and stop.
+
+Then offer, in plain text at the end of that reply, to show any one template in full, with an example from the list, such as the story or defect template. When the user names one, call `get_template` with its type and show it as it is.
+
+The settings are read here, never changed: they live in `buildkeel.yaml` and `templates/` in the spec tree. If the user wants to change one, say which file holds it, and that the change is made there and committed with the spec tree.

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

@@ -11,11 +11,13 @@ Show the user their own use of BuildKeel in this spec tree, from the record kept
 
 The user typed: whatever follows /bk-stats in the user's message (nothing, if they typed only /bk-stats)
 
+**Before anything else**, call the BuildKeel `query` tool with `view: "process"`, and do not show its result. If it says this repository is not set up for BuildKeel, tell the user so, and that /bk-init sets it up, then stop: ask nothing else. Otherwise go on straight away.
+
 ## 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:
+If the user typed nothing, ask straight away: "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.**

package/antigravity/templates/{bug.md → defect.md}

@@ -1,10 +1,12 @@
 ---
-template: bug
-version: 2
-description: A defect. Attach it to the work and test case where it was found, or leave it standalone.
+template: defect
+version: 3
+description: "A defect: code that does not do what was agreed. Set source to reported (by users, customers or testers; approved before work on it starts) or found (while building or testing; the unit being built is its parent, with the test case that found it)."
 fields:
   title: { required: true }
+  source: { required: true }
   parent: { type: link }
+  requirement: {}
   testCase: {}
   severity: {}
   scope: { type: list }

package/package.json

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