@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/genome/skills/brood/references/intent.md

@@ -0,0 +1,35 @@
+# the intent phase — What is the intent?
+
+Extract the user's intent before creating files or decomposing the product into specifications.
+Keep this phase short. Ask exactly five core questions, one at a time, and do not write to disk.
+
+The harness has already asked the first question of this phase: how many questions the stack and
+product phases may ask - light (3), medium (5), thorough (10) or best judgement. Do not ask it
+again; this phase's own questions are not capped by it.
+
+## Questions
+
+1. **Problem** — What problem should this software solve?
+2. **Primary user** — Who is it mainly for?
+3. **Desired outcome** — What should that user be able to accomplish with it?
+4. **Success criterion** — What observable result would make the first version useful?
+5. **Initial boundary** — What should the first version deliberately leave out?
+
+Ask one focused follow-up only when an answer is too vague to summarize. Do not explore features,
+entities, technology, architecture, or testing yet; those belong to later phases.
+
+## Intent brief
+
+Summarize the answers in five short bullets:
+
+- Problem
+- Primary user
+- Desired outcome
+- Observable success criterion
+- Initial boundary and explicit exclusions
+
+Ask the user to confirm or correct the brief with one `ask_user` question, the five bullets passed whole as its
+`context` - the dialog shows only the question, its options and its `context`. The intent phase finishes only after
+explicit confirmation.
+Carry the confirmed brief into the stack and product phases so their questions refine it instead of restarting intent
+discovery.

package/genome/skills/brood/references/product.md

@@ -0,0 +1,101 @@
+# the product phase — What does it do?
+
+The whole product interview, in one phase, walked **feature by feature** - not section by
+section. There is no pass that fills in the definitions and then another that writes the
+functional specs. Each question is about the product: a feature, a step in a flow, a rule.
+Its answer becomes one spec change that touches whatever sections that answer needs - the
+concepts the feature introduces, a policy it needs, its functional spec - and every spec change
+is built the moment it is written.
+
+Carry the confirmed intent brief and the settled stack in. Do not restart either.
+
+## How many questions
+
+The questioning level caps this phase's questions (light 3, medium 5, thorough 10, or best
+judgement - `SKILL.md`, "How many questions"), and so sets how broad each is. Every level walks
+all the topics below: light in a few broad questions - the features and their order in one, what
+they do end to end in another, with what fits the brief proposed for the person to confirm or
+correct; thorough in narrow ones, a feature, rule or edge case each. The level limits the
+questions, never the spec changes:
+
+- **Every answer is a spec change**, at every level: written with `write_spec_diff` and built at
+  once, before the next question - `ask_user` refuses the next question until it is. A broad
+  answer covering several features is a change for each.
+- **What the questions leave open is yours** - the details under a broad answer, and everything
+  still open once the questions are over (the cap reached, or `end_questions` called). Each
+  feature, edge case and rule you decide is its own spec change, written with `write_spec_diff`
+  with no answer needed before it, and said in one line. Write as many as the product needs.
+  Decide from the intent brief and the answers so far; leave out what they do not call for rather
+  than invent scope.
+
+## One question, one answer, a spec change, a render
+
+Every iteration is exactly this, at every questioning level:
+
+1. **Ask one question** with `ask_user`, about the product: a feature, its trigger and outcome,
+   one of its edge cases or rules, the next step of a flow - as broad as the level says. Never bundle two, and never ask about
+   a spec section ("what concepts are there?", "what reqs apply?") - ask about what the product
+   does, and let the answer decide which sections change.
+2. **Turn the answer into a spec change** - one for each feature it covers - everything it calls for, across sections:
+   - a concept the feature introduces, into `***definitions***`, following `add-concept`, defined
+     in the same change as the functional spec that first uses it;
+   - a technology-free policy the answer states, into `***implementation reqs***`;
+   - the functional spec for the feature, or the change to one already written, following
+     `add-functional-spec`.
+   Write it as a git diff of the `.plain` file(s): `diff --git a/<file> b/<file>`,
+   `--- a/<file>`, `+++ b/<file>`, then the hunks with a few lines of unchanged context. Paths
+   are relative to the project root.
+3. **Write it with `write_spec_diff`.** It applies the diff and starts a render spec diff job for
+   it in the same call - whatever the change touches, a definition alone included. Write every
+   change the answer calls for before the next question - `ask_user` refuses it until then - and
+   any you decide yourself beside them. Move straight on to the next question; never wait for a
+   build.
+
+**One answer, at least one change.** A follow-up about the same feature - an edge case, a
+validation rule - is its own answer and its own change to that feature's spec. An answer that
+describes two features is two changes, both written before the next question. A change never
+carries both an answer and something you decided: what you decide is a change of its own.
+
+**Fix contradictions in place.** When a later answer refines or contradicts something already
+written, write the correction as its own diff with `fixes_earlier` set, before the next
+question. It is rendered like any other change.
+
+**Never edit the `.plain` files with `write` or `edit` in this phase.** A change that does not
+go through `write_spec_diff` is a change nothing renders.
+
+## What a change may contain
+
+- **`***definitions***`** - the concepts the change needs, each defined before, or in the same
+  change as, what first uses it.
+- **`***functional specs***`** - at most one new functionality per change: ≤200 lines of code
+  change, language-agnostic, in chronological build order, externally explicit where it has an
+  interface.
+- **`***implementation reqs***`** - only technology-free policy: an error-handling or retry
+  policy, an ordering guarantee, a data-format rule. The technology was settled in the stack
+  phase; an answer that needs a new technology is a stack answer - note it and steer back.
+
+Leave the `***test reqs***` as the testing phase wrote them, and write no `***acceptance tests***`.
+With conformance on, every change is built with its conformance tests - from the test reqs as they
+stand.
+
+## Topics (in order)
+
+1. **Product description** - propose a one-sentence description from the confirmed intent brief,
+   state it back in one line, and write it into the frontmatter as the first change.
+2. **Features, one at a time, in build order** - the smallest thing that is useful first, then
+   what builds on it. For each feature: one question for what triggers it and what comes out,
+   then one per edge case, validation rule or permission that is not obvious. Each answer is a
+   change: the first brings the feature's concepts and its functional spec; the follow-ups refine
+   them. A feature too large for one functional spec is split *with the user* - that is the next
+   question.
+3. **User flows** - walk the product from the user's side: what happens first, what next, and at
+   each decision point. Each missing step is a feature, taken the same way.
+4. **User interface (optional)** - skip entirely if there is none. Otherwise per screen or
+   interaction: what the user sees and what it does, still language- and framework-agnostic.
+5. **Anything else** - anything the user wants to add or change that has not been covered.
+
+## Reporting builds
+
+Report each build result between questions, in one sentence. A failed build does not stop the
+interview - note it and carry on, unless it shows the spec itself is wrong, in which case fix
+the spec with a diff and `fixes_earlier`.

package/genome/skills/brood/references/stack.md

@@ -0,0 +1,61 @@
+# the stack phase — What technologies should it use?
+
+Gather the technical stack **and** the project's structure/architecture. This phase affects only `***implementation reqs***`, and ends with the unit testing script every build needs — the rest of testing comes later. Run the core loop from `SKILL.md` for each topic below, in order: ask, then write the requirement into the `.plain` file with the ordinary file tools. Nothing is built in this phase. When the user has no preference, propose a sensible default that fits earlier answers and ask them to confirm.
+
+The questioning level caps this phase's questions (light 3, medium 5, thorough 10, or best
+judgement - `SKILL.md`, "How many questions"), and so sets how broad each is. Every level reaches
+all the topics, in order: light in a few broad questions - the stack, say, then storage and
+outside services together, then the remaining constraints, each with what fits the brief
+proposed; thorough a topic or two a question, with follow-ups. Every topic left unasked once the
+questions are over gets the default that fits the intent brief and the answers so far, written as a
+requirement like any other and named as your choice in the closing summary. The unit testing script
+is written whatever the level.
+
+## Author target for this phase
+
+Write each requirement into `***implementation reqs***`:
+
+- Shared, stack-wide reqs (language, framework, architecture, coding standards) go on the template module if one exists.
+- Module-specific reqs (e.g. a data-storage choice or an external integration only one module uses) go on the module that needs them.
+
+Do **not** add `***test reqs***` or `***acceptance tests***` in this phase — the test reqs belong to the testing phase, right after this one.
+
+## First: a stack from the standard library
+
+Before the topics, settle what kind of software each module is - a backend, a frontend, a
+command-line tool, a library - and offer the standard library's stacks for that kind (the stdlib
+rule, in `<plain-rules>`, lists them) that this machine can build: `<toolchains on this machine>`, in
+your instructions, says which languages it can build now. The agents use its toolchains and install
+none, so a stack in a language it lacks stops at its first build. Ask with `ask_user`: those stacks
+as options, the one that fits earlier answers first, and "Something else…" for a stack of the user's
+own. A stack the user names in a language the machine lacks: say what to install first and that
+`turri doctor` checks it, and ask whether to wait for that or choose another.
+
+- **A stack from the standard library.** Import it into the module's frontmatter as
+  `stdlib/<kind>/<stack>`, and read the templates it brings: the stack, its `stdlib/lang/<language>`
+  and its kind's `common` - the folder is in the stdlib rule. They settle topics 1, 2 and 5, error handling and
+  logging in topic 6, and the unit-test framework in topic 8: do not ask about those, and write no
+  requirement that restates them. Say in one line what the stack settles - its language, framework,
+  layout, how it reports errors and logs - so the user knows what they chose. Then walk only topics
+  3, 4, 6 (what the stack leaves open), 7, and the unit testing script in 8.
+- **Something else.** Walk every topic below. When the language is one the standard library has, its
+  `stdlib/lang/<language>` template can still be imported for the language-wide conventions.
+
+A user who wants something the stack settles done differently - another framework, another layout -
+has chosen something else: an import cannot be taken back in part.
+
+## Topics (in order)
+
+1. **Programming language** — e.g. Python, TypeScript, Java, Go. Author a language requirement at the appropriate scope (template if shared across modules, otherwise on the module). Review that requirement snippet.
+2. **Frameworks** — e.g. Flask, FastAPI, Next.js, Spring Boot, Express, React, Vue. Author framework requirement(s) and any framework-specific architectural conventions. Review the new framework reqs.
+3. **Data storage** — e.g. PostgreSQL, SQLite, file-based, in-memory, none. Author a storage requirement on the module that owns persistence (or the template if shared). Review that snippet.
+4. **External services or APIs** — anything the app talks to: auth providers, payment gateways, email/SMS, third-party APIs, internal services. Author one requirement per integration on the module that uses it. Review each integration snippet.
+5. **Project structure & architecture** — the architectural style and the layers/components the project should be organized into (managers, services, models, repositories, controllers, views, adapters, DTOs, …). Discuss naming conventions, directory layout, and the responsibilities/boundaries of each layer. If the user has no preference, propose a layout that fits the language, framework, and feature set, and confirm it. Author architecture/layering reqs in the template (if shared) and any module-specific deviations on the module. Review the architecture reqs and the resulting layer split.
+6. **Other constraints** — deployment target, OS requirements, performance needs, coding standards, security policies, observability — anything stack-wide that hasn't already been covered. Author each constraint as its own requirement at the appropriate scope. Review the new constraint snippets.
+7. **Anything else** — anything the user wants to add or change that hasn't already been covered.
+8. **Unit tests and their script** — last, once the stack is settled: the first build needs both.
+   - The unit-test framework, e.g. pytest, Jest, JUnit, Go's `testing` package. Suggest one that fits the language if the user has no preference. Author a `:UnitTests:` requirement in `***implementation reqs***` at the appropriate scope - e.g. "`:UnitTests:` should use pytest" plus how they are run. Review that snippet.
+   - The unit testing script. If turri already finds one - named by `unittests-script:` in `config.turri.yaml` at the project root (or in the stack's `config.turri.<stack>.yaml`, in a project whose parts are on different stacks), or the one `run_unittests*.sh` in the root or in `test_scripts/` - keep it. Otherwise generate `test_scripts/run_unittests_<language>.sh` (and any framework config it needs, e.g. `pytest.ini`) via `implement-unit-testing-script`. Do not link it from the specs. Without it, every build stops before it starts. Review the script's path and what it runs.
+   - The static checks, in that script: the formatter in check mode, the linter and the type checker the stack names, run with the unit tests and counting as they do - `implement-unit-testing-script` says which for each language. A unit testing script turri already finds that runs none is extended with them. There is no separate static checks script.
+
+When all topics are complete, summarize the full tech stack and the chosen architecture, and get an explicit overall confirmation before moving to the product phase.

package/genome/skills/brood/references/testing.md

@@ -0,0 +1,56 @@
+# the testing phase — How is what was built checked from the outside?
+
+Decide whether the project has conformance tests, and if it does, say in `***test reqs***` how they
+are written and run, and give it the script that runs them. This comes before the product phase, and
+nothing here is built: a change to the test reqs is not a spec diff, so it is written with the
+ordinary file tools, never `write_spec_diff`. What is settled here is what every build of the
+product phase follows - with conformance on, each spec change is built with its conformance tests.
+Run the core loop for each topic below, in order: ask, then write. When the user has no preference,
+propose a default that fits the stack and the intent brief and ask them to confirm.
+
+Conformance tests are black-box tests written from the spec: for each functional spec, tests that
+run the built software from the outside - as a command, over HTTP, through its public entry point -
+and check it does what the spec says, kept apart from the spec's acceptance tests. The harness runs
+the whole suite after every spec change, so they catch one change breaking another. They cost time
+and tokens on every build.
+
+## Author target for this phase
+
+- `***test reqs***` - one `:ConformanceTests:` requirement per fact, on the template if one exists
+  (shared by every module), otherwise on the module. Follow `genome/rules/test-reqs.md`.
+- `config.turri.yaml` at the project root - the `conformance-tests:` decision. Change only that key, and
+  create the file if there is none; everything else in it stays as it is. When the project has only a
+  `config.yaml`, copy it to `config.turri.yaml` first - and each `config.<name>.yaml` to
+  `config.turri.<name>.yaml` - and write the copy: `config.yaml` may be another tool's, and is never
+  written.
+- `test_scripts/` - the conformance testing script.
+
+Write no `***acceptance tests***`, no functional specs and no `***implementation reqs***` here.
+
+## Topics (in order)
+
+1. **Conformance on or off** - ask it explicitly, with what it costs and what it catches; it is a
+   recorded decision, never an inference. Ask it even when `config.turri.yaml` already has
+   `conformance-tests:` - offer what it says as the first option. Write it to `config.turri.yaml` as `conformance-tests: true` or
+   `conformance-tests: false`. Off: say that no conformance tests will be written or run until it
+   is turned on, and go to the end of the phase.
+2. **Framework** - e.g. pytest, JUnit, Jest, Go's `testing`; one that fits the stack. Author it as a
+   `:ConformanceTests:` requirement.
+3. **How the tests reach the software** - as a subprocess of the CLI, over HTTP against a server the
+   tests start, through the public entry point it exports. Author it.
+4. **Setup and outside services** - fixtures, test data, databases, third-party APIs: started for
+   real, faked, or mocked at the boundary. Author each decision as its own requirement.
+5. **How the whole suite is run** - the one command that discovers every test. Author it.
+6. **The conformance testing script** - if turri already finds one (named by
+   `conformance-tests-script:` in `config.turri.yaml`, or the one `run_conformance_tests*.sh` in the
+   project root or in `test_scripts/`), check it runs the suite the way the test reqs now say, and
+   keep it. Otherwise write `test_scripts/run_conformance_tests_<language>.sh` with
+   `implement-conformance-testing-script`, to match the test reqs. Never link it from the specs.
+   If `test_scripts/` would hold two of a kind, name the one to use in `config.turri.yaml`. In a
+   project whose parts are on different stacks, name each stack's script in its own
+   `config.turri.<stack>.yaml` (`conformance-tests-script:`), and tell the user to choose the stack
+   with `/stack <stack>` (`--stack <stack>` on the command line) before building that part.
+7. **Anything else** - anything about testing the user wants to add or change.
+
+Run `validate` on every module you changed. The product phase's first build needs the test reqs
+and the conformance testing script both there: without them it stops before it starts.

package/genome/skills/bud/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: bud
+description: >-
+  Add a feature to an existing ***plain project the way `brood` builds one: a short
+  feature-intent interview, then product questions one at a time - a trigger and its outcome, an
+  edge case, a rule - where every answer becomes one spec change, written as a git diff of the
+  .plain files and built the moment it is written, so the feature appears while the interview is
+  still going. A change that touches what is already specified or being built is a spec diff too: what
+  is left to build is worked out again from the spec. Use when the user wants to add a
+  feature to an existing project. Not for starting a new project (use `brood`, or `spawn`
+  to start fast) or for editing generated code (the .plain specs are the source of truth).
+allowed-tools: [read, write, edit, bash, ls, grep, find, write_spec_diff]
+metadata:
+  # What each phase does, in a line - shown under the skill's progress while it runs.
+  phases:
+    intent: "what the feature is for, who it serves, and what it leaves out"
+    scope: "finds where the feature goes in the spec, and what is built already"
+    product: "the feature, question by question - each answer starts a regenerate pulse"
+    review: "checks the changed spec holds together, then hands over"
+---
+
+# Bud
+
+Load the `***plain` syntax rules before writing anything - they are in the system prompt under
+`<plain-rules>`; read `genome/rules/<name>.md` for the full text of any rule you need to follow
+closely.
+
+## Role
+
+Act as a `***plain` spec writer adding one feature to specs that already exist - and, usually, to
+code already built from them, or being built. The only output is changes to `.plain` files, and
+every one of them is a **spec diff**: a git diff of the `.plain` files, written with
+`write_spec_diff`, which applies it and queues its render spec diff job. Never write code, and never
+change a `.plain` file by any other means. Frame every message in terms of specs: "I'll add this to
+the spec."
+
+This is `brood`'s product phase, scoped to one feature, on top of what is there: the stack,
+the testing setup and every earlier feature are settled - read them, build on them, restart none.
+
+## Question style
+
+- Ask with `ask_user`, one question per call, and pass `options` so the user picks rather than
+  types - concrete choices, plus the free-form catch-all the tool adds. Reserve `free_form: true`
+  for a genuinely open question.
+- Ask about the product - a trigger and its outcome, an edge case, a rule, a permission, a step of
+  a flow - never about a spec section ("which concepts?", "what reqs?"). Let the answer decide which
+  sections change.
+- Shape each question so any plausible answer maps to one spec change. Bad: "How should it work?"
+  Good: "When the title is empty, should saving be refused with `Title is required`, or saved as
+  `Untitled`?"
+- Short, direct sentences and plain words; never drop a detail the user needs to answer - split into
+  more sentences instead.
+
+## Steps
+
+### intent
+
+Read `references/intent.md` and ask its five core questions one at a time with `ask_user`. Ask at
+most one focused follow-up when an answer is too vague to summarize. If what the user has already
+said answers a question, confirm it in one line instead of asking.
+
+Write nothing to disk. Summarize the feature-intent brief - motivation, affected user, desired
+outcome, observable success criterion, boundary and explicit exclusions - and get explicit
+confirmation, the brief passed whole as `ask_user`'s `context`, which the dialog shows above the
+question. Carry the brief into every later step.
+
+### scope
+
+Keep this short: enough to ask the first product question, not a design on paper.
+
+1. Find the `.plain` file(s) the feature belongs to, and read them whole, following their `import`
+   and `requires` chains: every definition, implementation and test req, functional spec and
+   acceptance test the feature will sit beside. Read `config.turri.yaml` (or the old `config.yaml`,
+   when there is no `config.turri.yaml`) and the chosen stack's `config.turri.<stack>.yaml` for
+   whether conformance tests are on.
+2. Ask which module only if it is genuinely ambiguous; otherwise do not.
+3. Look at what is built and queued (`drift`), so you know which specs already have code and
+   which builds are still waiting - a change to either is still just a spec diff.
+
+Say in one line where the feature goes, and move on. Write nothing to disk.
+
+### product
+
+The feature, walked question by question. Run this loop until the user says the feature is fully
+covered:
+
+1. **Ask** one product question with `ask_user`.
+2. The user **answers**.
+3. **Make the spec change** the answer calls for, as one git diff of the `.plain` file(s) - across
+   every section it needs:
+   - a concept it introduces, into `***definitions***` - written the way `add-concept` says, and
+     defined in the same change as the functional spec that first uses it;
+   - a policy it states - error handling, a retry, a data format, a library not already in the
+     module or its imports - into `***implementation reqs***`, the way
+     `add-implementation-requirement` says;
+   - the functional spec it adds, or the change to one already written, the way
+     `add-functional-spec` says: its wording rules, its complexity check
+     (`analyze-if-func-spec-too-complex` - at most 200 lines of code; a spec too big is split *with
+     the user*, as the next question) and its conflict check (`analyze-func-specs`, over the new
+     spec and every existing one in the chain). Follow those skills for what the text is; the diff
+     is the only thing that writes it.
+   - with conformance tests on - test reqs of the module's own or imported, and a conformance
+     testing script turri finds - an acceptance test under its functional spec when the
+     answer states one concrete verification (`add-acceptance-test`), and a test req only when the
+     answer changes how conformance tests run (`add-test-requirement`). With conformance off, none.
+   Write it as a git diff: `diff --git a/<file> b/<file>`, `--- a/<file>`, `+++ b/<file>`, then the
+   hunks with a few lines of unchanged context, paths from the project root. A new functional spec
+   goes where it belongs in build order - after what it builds on, usually at the end.
+4. **Write it with `write_spec_diff`.** It applies the diff and queues a render spec diff job for
+   it; with conformance on, its conformance tests follow it. Say in one line what went into the
+   spec - "added `:Note:` and functional spec 7" - and what became of the build, as the tool says,
+   then ask the next question. Never wait for a build, and never ask the user to approve a change.
+
+**One answer, one change.** A follow-up about the same behavior - an edge case, a validation rule -
+is its own answer and its own change. An answer that describes two behaviors is two: write the
+first, then ask about the second. A change never carries anything the user was not asked about.
+
+**What already exists.** When an answer - or the conflict check - means changing something already
+specified: a definition, a req, a functional spec, built or still queued, the next question is
+about exactly that. Quote the existing text and offer: keep it (narrow what was just written),
+augment it (with the new wording in the question), or replace it. The answer is a spec diff like
+any other, written with `fixes_earlier`; when a concept changes, the same diff updates every spec
+that uses it, within what the user approved. Never rewrite earlier intent without asking. The queue
+master reworks the builds still queued around every such change - a queued build the change undoes
+is taken out, one it touches renders the spec as it now is.
+
+**Fix your own mistakes in place.** When a later answer refines or contradicts a change you wrote in
+this feature, write the correction as its own diff with `fixes_earlier`, before the next question.
+
+When the loop reaches the end of what the brief covers, ask whether the feature is fully covered.
+Yes: go to the review. No: the next question.
+
+### review
+
+A short consistency pass over what the feature changed, then the handover.
+
+1. Read the modified `.plain` file(s) whole, and check: every new concept defined before use, with
+   no cycles; build order right end to end - no spec depends on one after it; functional specs
+   language-agnostic; every external interface explicit (paths, methods, arguments, formats);
+   acceptance tests consistent with their functional specs.
+2. Run `validate` on every module the feature touched.
+3. Fix what either finds with a spec diff and `fixes_earlier` - never by editing the file. Ask the
+   user only when a fix is a decision the brief and the answers do not settle.
+
+Walk `references/checklist.md` once, as a self-audit. Then hand over in a few lines: the feature's
+spec changes in order, the builds they queued and how they stand (`drift`), and that any
+further change is asked for in the conversation - each one a spec diff, and what is left to build is
+worked out again from the spec. The next feature starts again from the intent.

package/genome/skills/bud/references/checklist.md

@@ -0,0 +1,44 @@
+# Bud Checklist
+
+Use this to verify the workflow was followed - never as a substitute for it. Walk it once in the
+review step, before the handover. A box counts only when the change is in the `.plain` files, not
+merely discussed; an unmet box is completed with a spec diff before finishing.
+
+## Intent
+
+- [ ] Asked the five core questions of `references/intent.md` one at a time - or confirmed in one
+  line what the user had already said - with at most one clarification for a vague answer.
+- [ ] Wrote nothing to disk before the brief was confirmed.
+- [ ] Summarized motivation, affected user, desired outcome, observable success criterion, and
+  boundary with explicit exclusions; got explicit confirmation.
+
+## Scope
+
+- [ ] Read the target `.plain` file(s) whole, with their `import` and `requires` chains, and the
+  config that says whether conformance tests are on.
+- [ ] Asked which module only when it was genuinely ambiguous.
+
+## Every product question
+
+- [ ] Asked exactly one question via `ask_user`, about the product - a trigger and outcome, an edge
+  case, a rule, a permission, a step of a flow - never about a spec section.
+- [ ] Turned the answer into exactly one spec change, across every section it needed, and wrote it
+  with `write_spec_diff` - never with `write` or `edit`.
+- [ ] Concepts defined in the same change as, or before, what first uses them; no cycles.
+- [ ] Every functional spec follows `add-functional-spec`'s rules, passed its complexity and
+  conflict checks, and sits in build order; one too big was split with the user.
+- [ ] Every change to something already specified - built or still queued - was put to the user
+  first (keep / augment / replace) and written as a diff with `fixes_earlier`.
+- [ ] Every correction of this feature's own changes was a diff with `fixes_earlier`, before the
+  next question.
+- [ ] `***test reqs***` and `***acceptance tests***` only with conformance tests on.
+- [ ] Asked whether the feature is fully covered before leaving the loop.
+
+## Review
+
+- [ ] Read the modified `.plain` file(s) whole and checked: concepts defined before use, no cycles,
+  build order right end to end, functional specs language-agnostic, every external interface
+  explicit, acceptance tests consistent with their functional specs.
+- [ ] Ran `validate` on every module touched, and fixed what it reported with spec diffs.
+- [ ] Handed over: the spec changes in order, the builds they queued and how they stand, and that
+  further changes are asked for in the conversation as spec diffs.

package/genome/skills/bud/references/intent.md

@@ -0,0 +1,30 @@
+# The intent step - what is the feature for?
+
+Extract the intent of this feature before choosing files or authoring specifications. Ask exactly
+five core questions, one at a time, and do not write to disk.
+
+## Questions
+
+1. **Motivation** — What problem or limitation should this feature address?
+2. **Affected user** — Who should benefit from or interact with this feature?
+3. **Desired outcome** — What should that user be able to accomplish after the feature exists?
+4. **Success criterion** — What observable result would prove the feature is useful and working?
+5. **Boundary** — What should this feature deliberately leave unchanged or out of scope?
+
+Ask one focused follow-up only when an answer is too vague to summarize. Do not choose concepts,
+spec wording, implementation technology, or tests yet - the product questions decide those, one
+spec change at a time.
+
+## Feature-intent brief
+
+Summarize the answers in five short bullets:
+
+- Motivation
+- Affected user
+- Desired outcome
+- Observable success criterion
+- Boundary and explicit exclusions
+
+Ask the user to confirm or correct the brief. The intent step finishes only after explicit
+confirmation. Carry the brief into the scope step, so it maps the intent onto existing modules
+instead of restarting the feature discussion.