@printpractical/cruze 0.0.13 → 0.0.14

package/skills/build/SKILL.md

@@ -1,65 +1,61 @@
 ---
 name: cruze-build
-description: Builds the change bound to this branch task by task, each one test-first, checked with cruze check and committed, stopping to rethink when reality diverges from the design.
+description: Builds an approved feature test-first, one scenario at a time, with ports and adapters as the architecture maps them, stopping for the user only when a scenario or the public API has to change.
 ---
 
 # Build
 
-Build turns an approved plan into code, one task at a time. Each task starts with a failing test at the seam the plan names and ends as a green, checked commit. The design is settled, so build follows it. When the code shows the design is wrong, build stops and says so.
+Build turns an approved feature into working, tested code without asking the user anything, unless what they approved has to change. Each scenario starts as a failing behaviour test and ends as a green, checked commit.
 
 ## Steps
 
-1. **Pass the gate.** Run `cruze status --gate build` and quote its result.
-   - When it is blocked, stop, and show the reasons with the step that fixes them (`cruze next` names it).
-   - Override it only when the user explicitly asks, with `cruze status --gate build --override "<their reason>"`. The override is journaled.
-2. **Load the standards.** Read these, and follow them for every task:
+1. **Check the approval.** Run `cruze status`. The feature must be `approved`; when it is `unapproved` or `edited`, stop and run `shape` first.
+2. **Load the standards** and follow them throughout:
    - `.agents/skills/cruze-behavioural-testing/SKILL.md`
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`, and its language file when one exists for the project's language
    - `.agents/skills/cruze-dependency-approval/SKILL.md`
-3. **Read the plan and the design.** Read the change's `change.md`. Run `cruze show <ref>` and read its output: the full body of every element the change builds, every scenario it delivers, and the settled decisions. Read an element it lists as cited only when the task calls it, with `cruze show <ID>`, never `feature.md` or `docs/architecture.md` whole. Read a reference it lists at the sections the change's elements cite. Read `commands:` in `.cruze/config.yaml`.
-4. **Build each open task in order,** following the task loop below. Skip the tasks already ticked in `## Progress`.
-5. **Finish.** When every task is ticked:
-   - Run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`.
-   - Run `cruze check --ci` and `cruze trace`, and quote their results.
-   - When all of them pass, record the commit they ran at with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`. Verify quotes this instead of running the suite again.
-   - Commit the progress record with a message such as `chore: record progress on <change>`.
-   - Done when all of them pass and the checks are recorded.
+3. **Read the design:** the feature file, and the sections of `docs/architecture.md` its stack sketch touches. Done when you can name, for each scenario, the use case it runs and the ports it crosses.
+4. **Build the foundation first,** when this is the release's first feature. See "The foundation" below.
+5. **Build each scenario in order,** with the loop below.
+6. **Finish.** Run the formatter, the linter, the build and the full test suite, then `cruze check --ci` and `cruze trace <slug>`, and fix what they report. Set the feature's status line to `- Status: built`, and commit. Done when every one of them passes.
 
-## The task loop
+## The loop
 
-For task `T<n>`:
+For each scenario:
 
-1. **Read it.** Note its owner, its files, the IDs it proves, and the test plan rows for those IDs.
-2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect. When the task names a break, use it, or any break that compiles and turns the same assertion red.
-3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task, or another change, waits for it, even when the next change will need it.
-4. **Check.** Run `cruze check --ci <the task's files>`, the formatter and the linter, and fix what they report. Meet a budget as the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md` says, never by bending the code. Run the tests the task touched. When `commands:` has a `test_full`, run `test` too, since it is the fast tier. Otherwise run the rest of the suite only when it is quick.
-5. **Commit** with a Conventional Commit message naming the task, such as `feat(access): console session state machine (T2)`.
-6. **Tick it.** Run `cruze task done T<n>`, which records the commit. Its progress edit rides along in the next commit.
+1. **Red.** Write the behaviour test at the seam the testing skill names, carrying the scenario's ID in a comment or string, with the scenario's values as its expected values. Run it, and see it fail for the reason you expect.
+2. **Green.** Write the code that makes it pass, inside out: domain types, then the use case, then the port, then the adapter, then the wiring in the composition root. Each port the stack sketch names gets a fake that honours its contract, and a contract test that both the fake and the real adapter pass.
+3. **Check.** Run `cruze check --ci` on the files you touched, the formatter and the linter, and the tests near what you changed.
+4. **Commit** with a Conventional Commit message, such as `feat(export): write rows as CSV (SCN-export-csv.basic)`.
 
-A task with no behaviour of its own, such as a package manifest or a plain data type, has no red step. Build it, check it, commit it and tick it, and the first task whose test uses it covers it. Neither has a prefactor's task: run the tests its plan names under `## Risks` before the first task, and after each task, and they pass unchanged.
+Done for a scenario when its test passes, the checks pass and the commit exists.
 
-Done for a task when its tests pass, `cruze check --ci` passes for its files, the commit exists and the task is ticked.
+## Deciding as you go
 
-## Deviations
+Decide everything local yourself: private helpers, file splits, internal types, test fixtures, an ordinary library. Note any choice a reviewer or the user might question in the feature's `## Decisions`, one line with the reason. Ask nothing about these.
 
-The plan is design. Within a task you decide only what is local and reversible.
+Stop and run `shape` when the code needs any of these:
 
-- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a new file of the owner's module that splits off a responsibility, a `check.exceptions` entry with its reason, a private type, a fixture or harness added to the test support module that the task's tests need, or two tasks' commits swapped for a reason. The test support module is in every test-writing task's scope, so extend it rather than writing a private helper in a test file. Run `cruze task deviation T<n> "<what you did and why>"`.
-- **Stop and offer `rethink`** when the code needs any of these:
-  - a new element, port operation or scenario;
-  - a file outside the owner's module, other than the test support module;
-  - a change to an approved scenario's behaviour, or to its test;
-  - a dependency, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command.
+- a scenario's behaviour or message to change, or a new scenario;
+- a change to the public API the user approved;
+- a significant dependency the architecture doesn't name;
+- a port or a runtime change the architecture doesn't allow.
 
-  Explain what you found, with the evidence, and don't work around it. Completed tasks keep their commits.
-- **Settle a detail with the user,** as "Detail" in `.agents/skills/cruze-rethink/levels.md` says, when the code needs a limit, timeout, buffer size, message or error case the design doesn't give. Never offer a deviation instead: two projects settled 35 details as deviations.
-- **Read a deviation back before you record it.** One naming a value, text, error or outcome the design doesn't give is a detail; one saying the code can't keep a promise a port or use case makes is a rethink.
-- Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`, a detail included.
+Show the user what changed, as code or output, before and after, and get the approval again. Then carry on; finished scenarios keep their commits.
+
+## The foundation
+
+The first feature of a release also sets up what every later feature relies on:
+
+- the project's build, with the layers of `docs/architecture.md` as directories and `source`, `tests` and `layers` in `.cruze/config.yaml` matching them;
+- CI in `.github/workflows/ci.yml` that runs the formatter, the linter, the build, the full test suite, and a line coverage gate, such as `cargo llvm-cov --fail-under-lines 80`, alongside the Cruze checks already there;
+- `## Commands` and `## Layout` in `AGENTS.md`, filled in from what exists;
+- the project's test and lint commands added to what `review.command` in `.cruze/config.yaml` allows, as `.agents/skills/cruze-formats/config.md` shows, so the reviewer can run them.
 
 ## Protecting the check
 
-Never weaken, skip or delete a behaviour, contract or smoke test for an approved scenario, port or flow to get green. A failing one means the code is wrong, or the spec is. A wrong spec goes through `rethink`.
+Never weaken, skip or delete a test to get green. A failing test means the code is wrong, or the scenario is, and a wrong scenario goes through `shape`.
 
 ## Next step
 
-`verify`, once every task is ticked and the finishing checks pass. Start it in a new session, so its context starts empty: one session that ran plan, build, verify and land reached 745k tokens.
+`review`, once the finishing checks pass.

package/skills/dependency-approval/SKILL.md

@@ -1,55 +1,58 @@
 ---
 name: cruze-dependency-approval
-description: The rule that no dependency enters a Cruze project without the user's explicit approval, with how to ask for one and where to record it. Use when a design or plan would add a library, package, crate, framework, build or test tool, or vendored code; before editing a dependency manifest; when a build finds it needs something the design didn't name; and when reviewing a diff that changes dependency declarations.
+description: The rule for adding dependencies to a Cruze project, covering which need the user's approval, how to ask, and where each is recorded. Use when a design would add a library, package, crate, framework, tool or vendored code; before editing a dependency manifest; when build needs something the design didn't name; and when reviewing a diff that changes dependency declarations.
 ---
 
 # Dependency approval
 
-Every new dependency needs the user's explicit approval before it is declared or relied on. That includes runtime libraries, development and test tools, build plugins, and vendored or copied third-party code. Changing how it is acquired, such as vendoring, a git submodule or copying files, doesn't get around the rule.
+Adopt a mature library wherever the clean design uses one. Only a significant dependency needs the user's explicit approval before it is declared or relied on; adopt any other without asking, and record it. A stricter policy in the vision's `## Constraints` wins.
 
-## Asking
+## Significant
 
-1. Establish the need: the capability, and what the design looks like with the dependency and without it, using the standard library and the project's already-approved dependencies. Show both as short code sketches, following `.agents/skills/cruze-grilling/illustrating.md`.
-2. Choose a recommendation, following `.agents/skills/cruze-research/SKILL.md`, which also says where versions come from.
-3. Say where it will sit: the module that owns it, and the port that keeps it out of the core when it is infrastructure.
-4. Name the realistic alternatives, including writing it yourself and what owning that code would cost. Never offer a hand-written alternative for cryptography, TLS or a security protocol.
-5. Ask, then wait. Nothing is declared, installed or written against it until the user answers.
+A package new to the project is significant when any of these holds:
 
-## Weighing
+- It is hard to reverse: an async runtime, an application or UI framework, a database, or a wire or storage format with its code generator.
+- It brings native code or a build requirement: C or C++ bindings such as a `-sys` crate, a system library, or a toolchain the build must install.
+- Its licence isn't permissive, such as MIT, Apache-2.0, BSD or ISC.
+- It does security work: cryptography, TLS, authentication or sandboxing.
+- Research found a risk in its health or security record, or it breaks a vision constraint.
+- It arrives outside the registry: vendored or copied code, a git dependency or a submodule.
 
-- Recommend the option that gives the cleanest design: the one an experienced developer in the language would write, with the least code to own. A dependency, a new crate or package, or a feature of an approved dependency is not a cost in itself. Weigh its concrete costs: maintenance and release health, security record, licence, and build time or binary size where a stated constraint makes them matter.
-- "No new dependency" is never the reason for a choice. Name what the chosen option does better.
-- A structure the language requires for an idiom, such as a separate crate for a derive macro, is part of that idiom, not an extra cost.
-- When the clean design needs a dependency or feature nobody approved yet, ask for it. Hand-written code, a shell command or a less idiomatic construct that exists only to avoid asking is a design flaw.
+None of these needs approval or a record beyond the manifest: a feature of a package the project uses, declaring it in another crate, workspace member or target, or as a development dependency, and transitive dependencies. Version upgrades follow the project's upgrade policy; point out one that changes licensing, platforms or behaviour.
+
+## Asking
+
+For a significant dependency:
+
+1. Establish the need: the capability, and the design with it and without it, as short code sketches following `.agents/skills/cruze-asking/SKILL.md`.
+2. Choose a recommendation, following `.agents/skills/cruze-research/SKILL.md`, which also says where versions come from. Say which adapter owns it, and the port that keeps it out of the core when it is infrastructure.
+3. Name the realistic alternatives, including writing it yourself and what owning that code would cost. Never offer a hand-written alternative for cryptography, TLS or a security protocol.
+4. Ask, then wait. Nothing is declared, installed or written against it until the user answers.
 
 ```markdown
-**Dependency: `russh` for SSH hops**
-- Why not std or existing: the standard library has no SSH client, and no approved dependency provides one.
+**Dependency: `russh` for SSH hops** (significant: security protocol)
+- Why not std or existing: the standard library has no SSH client, and no dependency the project uses provides one.
 - Checked: <version from the registry> (released <date>), Apache-2.0, <release cadence>, pure Rust, <n> transitive crates.
-- Sits in: ADP-access.ssh-connector, behind PORT-access.hop-connector.
+- Sits in: the SSH transport adapter, behind the console transport port.
 - Alternatives: `ssh2` binds libssh2 (C, needs OpenSSL on macOS); shelling out to `ssh` loses error detail.
 Recommended: adopt `russh`. Approve?
 ```
 
-## What counts as approval
+The user approves by naming the dependency ("use serde"), or by approving an architecture whose Technology table names it.
+
+## Weighing
 
-- The user names the dependency ("use serde"), or approves a design whose `## Adopt or build` table or `Adopts` fact names it. Approving a feature doesn't cover a dependency its design doesn't name, so the design walkthrough lists every new dependency out loud.
-- An approval covers the package's ordinary transitive dependencies, and later use for the same purpose in the same package or workspace member.
-- It doesn't cover another workspace member, a different purpose, or turning on native code, a network service or new platform requirements. Ask again for those.
-- Routine version upgrades follow the project's upgrade policy, not this rule. Point out upgrades that change licensing, platforms or behaviour.
-- Researching, reading docs or source, and comparing options need no approval.
+- Recommend the cleanest design: the one an experienced developer in the language would write, with the least code to own. A dependency, crate or feature is not a cost in itself. Weigh concrete costs: release health, security record, licence, and build time or binary size where a constraint makes them matter.
+- "No new dependency" is never the reason for a choice. Name what the chosen option does better.
+- A structure the language requires for an idiom, such as a separate crate for a derive macro, is part of that idiom, not an extra cost.
+- Hand-writing commodity functionality is the user's call, not adopting a library: a parser, serializer, codec, stream combinator, CLI parser, retries, compression, or date and time handling. Code or a shell command that exists only to avoid a dependency is a design flaw.
 
 ## Recording
 
-- A feature or standalone change records it as a row in `## Adopt or build`: the component, `adopt`, the package, and the reason. The adapter that uses it carries an `Adopts` fact in the architecture delta.
-- At project scope, the adapter's `Adopts` fact in `docs/architecture.md` records it, and a dependency no adapter owns, such as a test framework or a build tool, goes in the foundation change's `## Adopt or build`. A choice that is hard to reverse, such as an async runtime, a framework or a database, also gets an ADR.
-- Choosing to build commodity functionality is also the user's call: a parser, serializer, protocol codec, CLI parser, URL or version handling, retries, compression, or date and time handling. Record it as a `build` row with the concrete reason for owning the code.
-- When a build finds it needs a dependency the design didn't name, stop the task and ask as above. An approval changes the design, so record it through the rethink step at feature level, or at change level for a standalone change. A refusal keeps the decision open: don't add the package provisionally, and don't hand-write a replacement unless the user chooses that.
+- The architecture's `## Technology` table records each significant dependency and each framework, with why. An ordinary library needs no record beyond the manifest.
+- Hand-writing commodity functionality is recorded in the feature's `## Decisions`, with the concrete reason for owning the code.
+- When build needs a significant package the architecture doesn't name, stop and ask as above. A refusal keeps the decision open: don't add the package provisionally, and don't hand-write a replacement unless the user chooses that.
 
 ## Checking
 
-Before a change is verified, compare the diff of every place dependencies are declared with the approvals recorded in the feature, the change and the architecture. That includes manifests such as `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `vcpkg.json` and `conanfile.*`, CMake `FetchContent` and `find_package` calls, `.gitmodules`, and third-party code copied into the tree.
-
-- Every new direct dependency has a record. An unrecorded one is a blocker, even when the build passes.
-- Lockfile churn alone isn't a new dependency.
-- Done when you can list each new direct dependency next to the row or fact that approved it.
+When reviewing a diff, compare every place dependencies are declared, such as `Cargo.toml` or `package.json`, CMake `FetchContent`, `.gitmodules` and copied third-party code, with the architecture's Technology table. A significant package without the user's approval is a blocker, even when the build passes.

package/skills/envision/SKILL.md

@@ -1,32 +1,37 @@
 ---
 name: cruze-envision
-description: Decides what to build with the user, either for the whole project (problem, users, goals, non-goals, constraints, feature map and glossary) or for one feature (intent and requirements with scenarios), by grilling in rounds on the gaps.
+description: Starts a project, or a major shift in one, by putting the user's vision on paper, breaking the release into features with what each needs, and designing the architecture map those features and the future ones fit into.
 ---
 
 # Envision
 
-Envision decides the what: the problem, who has it, and the behaviour that solves it. It takes whatever drafts the user brings as input, finds the gaps, and grills in rounds until the user confirms a shared understanding. Architecture, modules and code belong to `architect`.
+Envision runs at the start of a project, and again when the product changes direction or a release is done. It turns the user's idea into three things everything later reads: a vision with future features, the release broken into features, and an architecture map designed with all of them in view. The user approves two documents once each, and the agent decides everything else.
+
+Read `.agents/skills/cruze-asking/SKILL.md` before the first question, and `.agents/skills/cruze-formats/SKILL.md` before writing a document.
 
 ## Steps
 
-1. **Pick the scope.** It is project scope when `docs/vision.md` doesn't exist yet, or when the user asks to rework the project's goals. It is feature scope when the user names a feature. When unsure, ask. Done when you can say which.
-2. **Gather the input.** Read what the user gave you: pasted drafts, files they point to, and the notes `cruze show --notes` lists. Read whichever of `docs/vision.md`, `docs/glossary.md`, `docs/roadmap.md` and `docs/architecture.md` exist, and run `cruze status`.
-3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md` and `.agents/skills/cruze-domain-language/SKILL.md`, and follow them for the rest of this step.
-4. **Follow the scope's procedure.** For project scope, follow [project.md](project.md). For feature scope, follow [feature.md](feature.md). Each one ends with the user's confirmation.
-5. **Check the documents.** Run `cruze validate`. Done when it reports no errors in the documents this step wrote. At feature scope, expect one `not-designed` warning for the feature, which `architect` clears.
+1. **Take in what the user has.** The user's idea may be a sentence, a long document or a conversation. Read all of it, and the repository's README and code if there are any. When the user shares a document, keep it next to the docs, such as `docs/seed.md`, so nothing in it is lost. Done when you can say the product's purpose in one sentence.
+2. **Write the vision.** Run `cruze new vision` if `docs/vision.md` doesn't exist, then fill in the problem, users, terms, non-goals and constraints from what the user said, in their words. Leave the Release and Future features tables for steps 3 and 4. Mark anything you inferred rather than read, so the user can see it.
+3. **Ask what may come later,** as [possibilities.md](possibilities.md) says, and fill in `## Future features`. Done when the table holds every likely neighbour the user agreed to, each with what must stay possible.
+4. **Break the release into features,** as [breakdown.md](breakdown.md) says, and fill in the `## Release` table. Done when `cruze validate` reports no release problem.
+5. **Show the vision and the breakdown.** In one message: the product in two sentences; the release's features as a short table, with a plain-text diagram of what needs what; the future features in one line each; and every point you inferred. Ask one question: "Is anything missing, merged wrong, or in the wrong order?" Apply the answer. When the user approves, run `cruze approve vision`. Done when the vision is approved.
+6. **Design the architecture map,** as [architecture.md](architecture.md) says. Done when `docs/architecture.md` exists, `cruze validate` reports no problem in it, and `.cruze/config.yaml` has its `source`, `tests` and `layers`.
+7. **Show the architecture.** In one message, illustrated as `.agents/skills/cruze-asking/SKILL.md` says:
+   - a plain-text diagram of the ports and adapters, marking which serve future features;
+   - the runtime model in three lines: threads or tasks, the limits that matter, and what happens at shutdown;
+   - the core ports as code, with their errors;
+   - each technology choice and significant dependency, with why;
+   - every decision you took that the user might question.
 
-## Rules
+   Ask: "Do you approve this architecture, or what should change?" Apply changes and show what moved. When the user approves, run `cruze approve architecture`. Done when it is approved.
+8. **Write the README** for someone who has never heard of the project: what it is and who it is for, in the vision's words; its status, such as "designing the first release", with the release's features in one line each; a short paragraph and the overview diagram of how it is built, in plain text so it reads anywhere; and where the vision, architecture and features live. Leave out what isn't true yet, such as install or usage steps. Done when nothing in it contradicts the vision or the architecture.
+9. **Commit** the documents, the README and the config with a message such as `docs: envision <project>`.
 
-- Write in the user's terms and the glossary's words. Behaviour is described from outside the system: what a user does and what they observe.
-- Requirements and scenarios follow `.agents/skills/cruze-formats/reference/specs.md`. Every scenario uses concrete values: real names, real inputs, exact output. The scenarios become the tests, so their values are the expected results.
-- Keep implementation out: no modules, types, libraries or file formats unless the user names one as a constraint. When the user raises one, record it as a constraint or a settled decision and move on.
-- Problem through Constraints stay within one page. A principle or a capability that must stay possible takes as much as its intent needs: never shorten one to fit.
-- The product's long-term intent lives in the vision, in its Principles and Must stay possible tables, at either scope. Designs answer to it for the product's whole life, long after the conversation that settled it.
-- Only the CLI writes the feature map. Use `cruze features add`, `cruze features update` and `cruze features drop`.
+## A major shift or the next release
 
-## Next step
+When the vision exists, edit it rather than starting again: move built features out of `## Release`, add the next release's features and update what they need, and move future features in when they join. Change the architecture map only where the new features move a boundary. Then show what changed and approve as in steps 5 and 7, and bring the README's status up to date.
 
-- After project scope: run `architect` at project scope.
-- After feature scope: run `architect "<feature>"`.
+## Next step
 
-Start it in a new session, so its context starts empty.
+`shape` for the first feature of the release, which `cruze next` names.

package/skills/envision/architecture.md

@@ -0,0 +1,16 @@
+# Designing the architecture map
+
+The architecture map is what every feature's shape and build read first. It says where things live and how the system runs, for the whole release, and leaves room for the future features. Keep it to what changes how code is written: under 3,000 words.
+
+Read `.agents/skills/cruze-hexagonal-design/SKILL.md` and its language file, and `.agents/skills/cruze-dependency-approval/SKILL.md`. When a choice needs evidence, such as which library fits or whether a platform supports something, follow `.agents/skills/cruze-research/SKILL.md`.
+
+1. **Trace each release feature through a hexagon.** For each, name the inbound adapter it arrives through, the use case it runs, the domain it touches and what it needs from outside: storage, network, devices, time. Each thing it needs from outside is a port.
+2. **Check the future features against it.** For each, name what must stay possible and the boundary that keeps it so, such as a port that a second adapter could implement, or a type that doesn't assume one owner. Build nothing for them.
+3. **Write the ports.** For each, its operations as code in the project's language, each with its errors and every number it depends on: timeouts, limits, buffer sizes.
+4. **Write the runtime.** The threading or async model; where work queues, and what a full queue does; how a failed dependency is noticed and recovered from; what shutdown waits for and for how long. Follow `.agents/skills/cruze-hexagonal-design/runtime.md`.
+5. **Choose the technology.** The language and framework, and each significant dependency, through the dependency-approval skill. Record each with why in one line.
+6. **Write the layers** in prose, then as `layers:` in `.cruze/config.yaml`, with `source` and `tests` globs for the project's language, as `.agents/skills/cruze-formats/config.md` shows.
+7. **Draw the overview** as a Mermaid flowchart: inbound adapters, the core, the ports and the adapters behind them.
+8. **Record the decisions** that shape the whole system, one line each with the reason.
+
+Done when `cruze validate` reports no problem in `docs/architecture.md` or the config.

package/skills/envision/breakdown.md

@@ -0,0 +1,14 @@
+# Breaking the release into features
+
+A feature is a slice the user can see working: a command that answers, a screen that shows something, a device that changes state. The release's features, built in order, deliver what the vision promises.
+
+1. **Choose the foundation.** The first feature is the one everything else builds on and the user tries first. Pick the kind that fits, and say why when you show the breakdown:
+   - **Walking skeleton:** one real use case through every layer, from the inbound adapter to a driven adapter. It suits most systems.
+   - **Core component:** the component the others depend on, working for real through its own interface, such as a server with its command-line client. It suits a system of several components.
+   - **Product shell:** every screen or command the release offers, wired together over sample data. It suits settling look and flows before logic.
+2. **List the slices.** Walk the vision's promise from the user's side and cut it where the user could stop and try something. Name each feature with a slug the user would recognise, such as `sign-in` or `export-csv`.
+3. **Size each one** for one shape and one build: about 3 to 10 scenarios, the user's words for its behaviour fitting on a page. Split a bigger one along what the user can try first. Merge one that the user couldn't try without another.
+4. **Name what each needs.** A feature needs another when it can't be built or tried without it. Ordering for convenience isn't a need.
+5. **Order for the product, not the platform.** Put the features that prove the product's core purpose as early as their needs allow. Shared machinery, such as a plugin system, a scheduler or a generic store, goes in no feature of its own: it arrives inside the second feature that needs it. One project built six days of infrastructure and no product, and was restarted.
+
+Done when every promise of the release is in some feature, and the Release table lists them in build order with their needs.

package/skills/envision/possibilities.md

@@ -1,13 +1,12 @@
 # Exploring what may come later
 
-The user knows where the product is heading better than any document does, but rarely says it unprompted. Ask, so designs leave room for it and never close it off.
+The user knows where the product is heading better than any document does, but rarely says it unprompted. Ask, so the architecture leaves room for it and never closes it off.
 
-1. **Find the neighbours.** For each goal, user and capability in scope, name the capabilities that products in this domain commonly grow into, from what you know of the domain and its standards. Name them as the user would recognise them: single sign-on or multi-factor authentication next to sign-in, sync across devices next to local-only storage, teams and shared workspaces next to a single-user app, third-party plugins next to a fixed set of kinds, a second transport next to a local socket. Skip those the vision already records under `## Must stay possible` or `## Non-goals`.
-2. **Ask them as a round,** following `.agents/skills/cruze-grilling/SKILL.md`: whether the product may need each one, how likely, and why. Recommend an answer from what the user has said so far. Keep a round to 3 to 5, the likeliest first. "No" is a good answer too.
+1. **Find the neighbours.** For the product's users and the release's features, name what products in this domain commonly grow into, from what you know of the domain and its standards, as the user would recognise them: single sign-on next to sign-in, sync across devices next to local-only storage, teams next to a single-user app, plugins next to a fixed set of kinds, a second transport next to a local socket. Skip those the vision already records as future features or non-goals.
+2. **Ask them in one question:** which of these the product may need, the likeliest first, three to five of them, with your recommendation for each. "No" is a good answer too.
 3. **Record each answer:**
-   - **Likely or possible:** a `LATER-<name>` row under `## Must stay possible` in `docs/vision.md`, with the likelihood, why in the user's words, and what no design may close off. Say what must stay possible, never how to build it: the mechanism is decided when a feature builds it.
-   - **No, for a tempting neighbour of a goal:** a non-goal with the reason, so nobody proposes it again.
+   - **Yes or maybe:** a row in `## Future features`, with what it would let the user do and what no design may rule out. Say what must stay possible, never how to build it: the mechanism is decided when a feature builds it.
+   - **No, for a tempting neighbour:** a non-goal with the reason, so nobody proposes it again.
    - **No, otherwise:** nothing.
-4. **Check the principles.** For each new `LATER` row, check every `PRINCIPLE` row against it. When one would stand in its way, such as "every record has exactly one owner" against shared workspaces, settle with the user which one gives, and amend the principle or the row.
 
-Done when every capability in scope has had its neighbours asked about once, and each answer is recorded. The vision changed, so the user approves it again with `cruze approve vision`.
+Done when every answer is recorded.

package/skills/fix/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cruze-fix
+description: Takes a reported bug, from the user or an issue, from symptom to a merged fix, reproducing it with a failing test first, fixing the root cause, and reviewing the fix, going back to the user only when the fix changes approved behaviour.
+---
+
+# Fix
+
+A bug report becomes a failing test, then a fix, then a reviewed pull request. Most bugs are code that doesn't do what its feature's scenario says, and those need nothing from the user. Only when the fix would change what a scenario or the public API says does the user decide.
+
+## Steps
+
+1. **Capture the symptom** from the user or the issue: the exact steps, what happened (output, error, exit code), what the user expected, and the environment. Done when you can write the steps as commands.
+2. **Reproduce it** against the real system. Done when you can make it fail on demand and have quoted the output. When you can't, ask the user what differs in their environment, and stop until you can.
+3. **Find the scenario** in `docs/features/` that covers this behaviour, and classify the bug:
+   - **The code is wrong:** a scenario says what should happen, and the code does something else.
+   - **A scenario is missing:** no scenario covers this case, and the right behaviour is obvious from the feature, such as a crash where the feature already says what failure looks like.
+   - **The behaviour is the user's call:** the right behaviour isn't obvious, or the fix changes what a scenario or the public API says.
+4. **Find the root cause.** Trace the failing path until you can name the first wrong decision, not the place the error surfaces.
+5. **Write the failing test first** on a branch such as `fix/<slug>`, at the seam `.agents/skills/cruze-behavioural-testing/SKILL.md` names, carrying the scenario's ID. For a missing scenario, add it to the feature file first, in the same style as its neighbours. Run the test, and see it fail for this bug's reason.
+6. **Fix it** with the smallest change in the code that owns the wrong decision. Run `cruze check --ci`, `cruze trace` and the full suite.
+7. **Ask the user only when it is their call.** Show the bug, the behaviour you recommend, and the change to the feature as before and after, as `.agents/skills/cruze-asking/SKILL.md` says. Edit the feature, and run `cruze approve <slug>` once they agree. Do this on the same branch.
+8. **Review the fix:** run the code reviewer on the fix's diff, as `review` says, and fix what it finds.
+9. **Land it.** Commit with a message such as `fix(<scope>): <what the user saw>`, add a line under `### Fixed` in `CHANGELOG.md`, and open a pull request or merge as the project does.
+
+## Rules
+
+- A missing test is part of the cause. When the scenario had a test that passed anyway, say why it missed the bug, and strengthen it in the same fix.
+- Fix the cause only. Clean-ups you notice go to the user as suggestions.
+- Never change a scenario to match the code without the user's approval.
+- A bug found during other work and not fixed then becomes an issue in the project's tracker, such as GitHub: the symptom, how to reproduce it, the cause when known, and the scenario it breaks. `fix` starts from it later; an agent's memory is no place for it.
+
+## Next step
+
+`cruze next`, or the next bug.

package/skills/formats/SKILL.md

@@ -1,95 +1,47 @@
 ---
 name: cruze-formats
-description: The formats and templates of every Cruze project document. Use when reading, writing or reviewing any file under docs/ or .cruze/ in a Cruze project.
+description: The formats of every Cruze project document, with templates. Use when reading, writing or reviewing docs/vision.md, docs/architecture.md, docs/features/, or .cruze/config.yaml in a Cruze project.
 ---
 
 # Cruze document formats
 
-Every Cruze document is Markdown that people read and the `cruze` CLI parses. Write them exactly in these formats: `cruze validate` rejects documents that drift, and approvals, staleness and merges all depend on the structure.
+A Cruze project has three kinds of document, all Markdown that people read and `cruze` parses. Create each with `cruze new`, which starts it from its template ([vision](templates/vision.md), [architecture](templates/architecture.md) or [feature](templates/feature.md)), and replace every `<angle-bracket>` guide. `cruze validate` reports what drifts.
 
-## Where documents live
-
-| Path | Document | Written by |
+| Path | What it holds | Written by |
 | --- | --- | --- |
-| `docs/vision.md` | Problem, users, goals, non-goals, constraints, feature map | envision (project scope) |
-| `docs/glossary.md` | Domain terms and terms to avoid | any step, as terms settle |
-| `docs/architecture.md` | Contexts, domain model, use cases, ports, adapters, flows, modules, rules | architect (project scope), rethink, land |
-| `docs/adr/<date>-<slug>.md` | One decision that is hard to reverse, surprising and a real trade-off | architect, rethink |
-| `docs/specs/<capability>.md` | Living behaviour: requirements and scenarios | land, from spec deltas |
-| `docs/roadmap.md` | The current release: phases, items, coverage | architect (project scope), roadmap |
-| `.cruze/features/<id>/feature.md` | One feature: intent, deltas, its ordered changes | envision and architect (feature scope) |
-| `.cruze/features/<id>/changes/<NN-slug>/change.md` | One change of a feature: scope, test plan, tasks | plan |
-| `.cruze/changes/<id>/change.md` | A standalone change, carrying its own deltas | architect (tweak scope) |
-| `.cruze/config.yaml` | Project configuration | `cruze init`, architect |
-| `.cruze/notes/<date>-<slug>.md` | The user's input, envision's intake and its hand-off, an explore note, or research evidence. Free-form under a title and `- Kind:` (`input`, `intake`, `explore` or `research`) and `- About:` lines, which say the work it informs: `project`, feature slugs, or contexts | the user, envision, explore, research |
-
-Only the CLI writes `approvals.json`, `journal.jsonl` and anything under `.cruze/archive/`.
-
-## IDs
-
-An ID names one element for its whole life. Other documents cite it, tests carry it, and approvals hash it.
-
-- Grammar: `<KIND>-<name>` or `<KIND>-<scope>.<name>`. `scope` and `name` are lowercase words joined by single hyphens, such as `REQ-access.open-console`.
-- Elements that belong to a bounded context or a capability carry it as their scope. Elements outside every context, such as the CLI shell and the composition root, use the scope `system`.
-- IDs are named, never numbered, so parallel branches never race for the next number.
-- An ID is never reused, even after its element is removed. Rename the title freely; the ID stays.
-
-| Kind | Element | Lives in | Scope |
-| --- | --- | --- | --- |
-| `GOAL` | A goal of the product | vision | none |
-| `PRINCIPLE` | A rule every design follows | vision | none |
-| `LATER` | A capability that must stay possible after this release | vision | none |
-| `CTX` | Bounded context | architecture | none |
-| `ENT` | Domain concept: aggregate, entity, value object, domain service, policy or domain event | architecture | context |
-| `UC` | Use case (the application's driving API) | architecture | context |
-| `PORT` | Port, driven or driving | architecture | context |
-| `ADP` | Adapter | architecture | context |
-| `FLOW` | Interaction flow, as a sequence diagram | architecture | context |
-| `MOD` | Module: a directory or file with one role | architecture | context, or none for shared modules |
-| `RULE` | Dependency rule | architecture | none |
-| `VIEW` | Overview diagram | architecture | none |
-| `XC` | Cross-cutting concern | architecture | none |
-| `REQ` | Requirement | specs | capability |
-| `SCN` | Scenario of a requirement | specs | capability |
-| `ADR` | Decision record, named by its file stem | `docs/adr/` | none |
-
-## Elements
-
-- A **heading element** is a heading whose text is exactly `<ID>: <Title>`. It extends to the next heading of the same or a higher level.
-- A **row element** is a table row whose first cell is exactly an ID. Only the vision's goals, principles and must-stay-possible capabilities use rows.
-- Element facts are list items of the form `- Key: value`, directly in the element's body. Sub-items hold lists of values.
-- An element cites another by writing its ID anywhere in its body. Every ID a document mentions counts as cited.
-- A cited ID must exist, either in the living docs or in a delta of the same feature or change. Design at project scope cites only what it defines; the feature that adds scenarios links them to flows and use cases through `MODIFIED` operations.
-
-## Decisions
-
-A settled decision is a bullet `D<n>: <decision> (<reason>)` in the architecture's `## Decisions`, a feature or a change. Each document numbers its own from D1, and a feature or change is archived when it finishes, so a number means something only inside the document that records it.
-
-- Cite a decision by number only inside that document. The architecture cites its own. A feature cites its own, and a change cites its own and its feature's.
-- A delta's elements merge into the living docs, so they cite only a project decision that the work's own `## Settled decisions` doesn't also number. Write what any other decision settled into the element, or record it as an ADR and cite the ADR.
-- Code comments cite no decision by number. Say what was decided, or cite the element or ADR that holds it.
-- `cruze validate` and `cruze check` report a citation that breaks these rules as `decision-citation`, and `cruze approve` refuses a feature or standalone change whose delta has one (`decision-cited`).
-
-## Managed content
-
-The CLI owns some content so that routine bookkeeping never changes a design:
-
-- A block between `<!-- cruze:managed -->` and `<!-- /cruze:managed -->` is written only by the CLI.
-- A `- Status: planned` or `- Status: built` item in an element body is written only by the CLI. Elements that have code (`ENT`, `UC`, `PORT`, `ADP`, `FLOW`, `MOD`) and scenarios (`SCN`) carry one.
-- Both are excluded from every hash. Read them freely; change them only through `cruze` commands:
-  - `cruze approve` adds missing statuses to the architecture, sets built elements back to planned with `--replan`, and binds a change to its branch. With `--by-agent` it approves a change whose plan review closed, and with `--restamp-unchanged` it re-stamps work a rethink left unchanged, recording that the agent gave the approval.
-  - `cruze task` records progress, and `cruze features` edits the feature map.
-  - `cruze land` merges work, marks it built and fills the Commands and Layout sections of `AGENTS.md`.
-  - `cruze roadmap prune` and `cruze abandon` update the roadmap's status.
-
-## Reference files
-
-Read the one that matches the document in front of you:
-
-- [reference/architecture.md](reference/architecture.md) for `docs/architecture.md` and architecture deltas.
-- [reference/specs.md](reference/specs.md) for `docs/specs/`, requirements, scenarios and spec deltas.
-- [reference/work-items.md](reference/work-items.md) for `feature.md`, `change.md`, test plans and task lines.
-- [reference/durable-docs.md](reference/durable-docs.md) for vision, glossary, ADRs and the roadmap.
-- [reference/config.md](reference/config.md) for `.cruze/config.yaml`.
-
-Create documents with `cruze new`: `cruze new vision`, `glossary`, `architecture` or `roadmap` for the project documents, and `cruze new feature`, `change`, `adr` or `note <slug> --title <title>` for the rest. It starts each one from the matching file in `templates/` and fills the `{{placeholders}}`. Replace every `<angle-bracket>` guide.
+| `docs/vision.md` | The problem, users, terms, the release's features and what each needs, future features and what must stay possible, non-goals, constraints | envision |
+| `docs/architecture.md` | The map: an overview diagram, ports with their operations, adapters, the runtime model, technology, layers, decisions | envision; shape when a feature moves a boundary |
+| `docs/features/<slug>.md` | One feature: intent, behaviour as scenarios, public API as code, a stack sketch, decisions | shape; build marks it built |
+| `.cruze/config.yaml` | Project configuration; see [config.md](config.md) | `cruze init`, the foundation feature |
+
+Only `cruze approve` writes `.cruze/approvals.json`.
+
+## The vision's Release table
+
+`## Release` holds a table with the columns `Feature | Summary | Needs`, one row per feature of the release, in the order they should be built. Feature is the slug of its `docs/features/` file. Needs lists the slugs, comma-separated, of the features it can't be built without; leave it blank when there are none. `cruze next` picks the first feature not yet shaped whose needs are all built, and `cruze validate` refuses an unknown slug and a circle of needs.
+
+`## Future features` uses `Feature | Summary | Must stay possible`. These shape boundaries in the architecture; nothing is built for them until they join a release.
+
+## Features
+
+A feature file starts with its title and a status line:
+
+```markdown
+# Sign in
+
+- Status: shaped
+```
+
+The status is `shaped` until build finishes the feature, then `built`. The sections are `## Intent`, `## Behaviour`, `## Public API`, `## Stack sketch` and `## Decisions`, in that order.
+
+Each scenario under `## Behaviour` is a heading `### SCN-<slug>.<name>: <title>`, where `<slug>` is the feature's and `<name>` is lowercase words joined by hyphens, followed by Given, When and Then bullets in the user's words. A scenario ID is never reused, even after its scenario is removed, and the test that proves a scenario carries its ID in a comment or string, such as `// SCN-sign-in.wrong-password`. `cruze trace` fails when a built feature's scenario has no test, or a test names a scenario no feature defines.
+
+A later feature that changes an earlier one's behaviour edits that feature's file in place, and git keeps the history.
+
+## Approvals
+
+`cruze approve <vision|architecture|slug>` records a hash of the document's content as the user approved it. Any later edit shows it as `edited` in `cruze status` until it is approved again. The status line and a feature's `## Decisions` are left out of the hash, so marking a feature built or recording a decision never counts as an edit. Approve only on the user's word.
+
+## Size
+
+A document is for a person to read in one sitting. `cruze validate` warns past 1,500 words for the vision, 3,000 for the architecture and 2,500 for a feature. Cut what the agent decided that the user needn't read, or split the feature.

package/skills/formats/config.md

@@ -0,0 +1,47 @@
+# Configuration format
+
+`.cruze/config.yaml` configures the CLI for one project. `cruze init` creates it, and the foundation feature fills in `source`, `tests` and `layers` from `docs/architecture.md`.
+
+```yaml
+version: 2
+cruze: "0.0.14"
+project: "Console Access"
+
+source: ["src/**/*.rs"]
+tests: ["src/**/*.rs", "tests/**/*.rs"]
+
+check:
+  max_lines: 600
+  max_types: 12
+  exceptions:
+    - path: src/cli/args.rs
+      reason: the clap derive struct lists every flag in one place
+
+layers:
+  - name: domain
+    paths: ["src/domain/**"]
+    may_import: []
+  - name: app
+    paths: ["src/app/**"]
+    may_import: [domain]
+  - name: adapters
+    paths: ["src/adapters/**"]
+    may_import: [app, domain]
+
+review:
+  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*) Bash(cargo test:*)"]
+```
+
+| Key | Meaning |
+| --- | --- |
+| `version` | Format version, `2`. |
+| `cruze` | The Cruze version whose skills the project installed. `cruze install` writes it. |
+| `project` | The project name, quoted. |
+| `source` | Globs of the source files `cruze check` inspects. |
+| `tests` | Globs of the files `cruze trace` searches for scenario IDs. |
+| `check.max_lines`, `check.max_types` | Budgets per source file, lines and top-level types, that `cruze check` warns past: a backstop against a file that has outgrown one responsibility, never a size to design to. A Rust file's `#[cfg(test)]` modules don't count. |
+| `check.exceptions` | Files allowed past a budget, each with a `path` and a `reason`. |
+| `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
+| `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Without it, `cruze review` hands the prompt back for the calling agent to run in a helper of its own. |
+
+A source file belongs to the first layer whose paths match it, and `cruze check` fails an import into a layer its own layer may not import. A layer may import itself, and code outside the project, such as the standard library and dependencies, is always allowed. Keep every source file in a layer: `cruze check` warns on one that isn't.