@printpractical/cruze 0.0.13 → 0.0.15

package/dist/domain/versions/cruze_version.js

@@ -36,15 +36,9 @@ export function versionSkew(cli        , recorded                    )
  * after `version:`, so the file's comments and layout survive.
  */
 export function withRecordedVersion(configText        , version        )         {
-  return withVersionLine(configText, "cruze", version);
-}
-
-/** The config text with a top-level version key, such as `cruze:` or `standards:`, set in place. */
-export function withVersionLine(configText        , key                       , version        )         {
-  const line = `${key}: ${JSON.stringify(version)}`;
-  const existing = new RegExp(`^${key}:.*$`, "m");
-  if (existing.test(configText)) return configText.replace(existing, line);
-  const anchor = key === "standards" ? /^cruze:.*$/m.exec(configText) ?? /^version:.*$/m.exec(configText) : /^version:.*$/m.exec(configText);
+  const line = `cruze: ${JSON.stringify(version)}`;
+  if (/^cruze:.*$/m.test(configText)) return configText.replace(/^cruze:.*$/m, line);
+  const anchor = /^version:.*$/m.exec(configText);
   if (anchor === null) return `${line}\n${configText}`;
   const end = anchor.index + anchor[0].length;
   return `${configText.slice(0, end)}\n${line}${configText.slice(end)}`;

package/dist/main.js

@@ -10,7 +10,7 @@ import { ProcessAgentRunner } from "./adapters/outbound/process_agent_runner.js"
 import { SystemClock } from "./adapters/outbound/system_clock.js";
 import { DefaultAnswerPrompter, TerminalPrompter } from "./adapters/outbound/terminal_prompter.js";
 
-// A reader that stops early, such as `cruze journal list | head`, closes the pipe; that is not an error worth a stack trace.
+// A reader that stops early, such as `cruze status --text | head`, closes the pipe; that is not an error worth a stack trace.
 process.stdout.on("error", (error                       ) => {
   if (error.code === "EPIPE") process.exit(0);
   throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
   "license": "Apache-2.0",
   "author": "Chris Buchter",

package/skills/asking/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: cruze-asking
+description: When to ask the user and when to decide, and how to show a question so the user can answer it cold, with plain words, code sketches and diagrams. Use before asking the user anything during envision, shape, build, review or fix.
+---
+
+# Asking the user
+
+The user's time is the scarcest thing in the project. Every question costs them a context switch, and a long run of questions turns into rubber-stamping: in one project the user answered 71% of 187 design questions with a bare "agree". So ask little, ask what only the user can answer, and show it so it can be answered at a glance.
+
+## What to ask and what to decide
+
+Ask when a choice changes something the user will see or live with:
+
+- behaviour a user of the product will notice, including what they see when something fails;
+- a public API: anything another program, person or team calls, types, or reads;
+- scope: what is in a feature and what is out;
+- a significant dependency, through `.agents/skills/cruze-dependency-approval/SKILL.md`;
+- security, privacy, stored data, compatibility, or a commitment that is costly to reverse.
+
+Decide everything else yourself: internal structure, private names, which module owns what, internal types, file layout, equivalent idioms, limits and timeouts with an obvious value. Pick the conventional option. Uncertainty alone doesn't make a choice the user's: investigate first. Then list the decisions a user might question in the document's `## Decisions`, one line each with the reason, so the user sees them when they approve, without being asked.
+
+## How many
+
+At most one question round per step, of five questions or fewer, before you show the document. When a choice has a sensible default, take it and list it under Decisions instead of asking. When the user defers ("you decide"), decide, and don't ask again.
+
+## Showing a question
+
+The user knows what the product should do, not the design's internals, and is often coming back from other work.
+
+- **Say where things stand** in one line first: the step and the feature, such as "Shaping export-csv."
+- **Explain the part before asking about it:** what it is, what it does, and why the question comes up now.
+- **Use plain words.** Name a scenario or decision by what it says, and add its ID after it in parentheses only when the user may want to look it up. Never let an ID stand alone.
+- **Show each option** with the form that fits:
+
+| The question decides | Show |
+| --- | --- |
+| What a user does or sees | The command and its exact output, or a sketch of the screen, with real values |
+| A public API or a port | A code sketch in the project's language: types, signatures, errors, and one call |
+| Where something lives | A box-and-arrow diagram, or the directory tree |
+| An order of steps, or what happens on failure | A numbered sequence with the failure branch |
+| A stored format or config | A sample of the file |
+| A dependency | The code with it and without it |
+
+- **Keep sketches short:** shape only, bodies left out, about 15 lines per option. Draw diagrams in plain text, which reads in a terminal; documents keep their Mermaid.
+- **Mark your recommendation** and why, in one line.
+
+A shape the user chose from a sketch is part of the decision: write it into the document, so build makes it as the user saw it.
+
+## Challenge, then defer
+
+When the user steers toward something that breaks the architecture or a standard, name the rule, the concrete risk here and your alternative, once. Then the user decides, and their decision stands.

package/skills/behavioural-testing/SKILL.md

@@ -1,30 +1,28 @@
 ---
 name: cruze-behavioural-testing
-description: The testing standard for a Cruze project, covering which tests to write, the seam each one drives, the ID it carries, and fakes instead of mocks. Use when writing a change's test plan, when writing, changing or fixing a test, when building a fake for a port, when deciding whether a unit test is warranted, or when reviewing tests.
+description: The testing standard for a Cruze project, covering which tests to write, the seam each one drives, the ID it carries, and fakes instead of mocks. Use when writing, changing or fixing a test, when building a fake for a port, when deciding whether a unit test is warranted, or when reviewing tests.
 ---
 
 # Behavioural testing
 
-Behaviour is the contract. Every scenario in the specs becomes a test that drives the system through a use case and checks what a caller would see. Tests pin behaviour, not structure, so the code behind them can be rewritten freely.
+Behaviour is the contract. Every scenario in a feature becomes a test that drives the system through a use case and checks what a caller would see. Tests pin behaviour, not structure, so the code behind them can be rewritten freely.
 
-## Writing tests for a task
+## Writing tests for a feature
 
-1. Find the test plan rows whose Subject the task proves. Done when you know the seam, test file and kind of every test the task needs.
-2. Write one test at its seam, carrying its subject ID. Take the inputs and expected values from the scenario's GIVEN, WHEN and THEN.
+1. For each scenario, pick its seam from the table below. Done when you know the seam, test file and kind of every test the feature needs.
+2. Write one test at its seam, carrying the scenario's ID. Take the inputs and expected values from the scenario's GIVEN, WHEN and THEN.
 3. Run it and watch it fail for the reason you expect (red). A test that passes before the code exists proves nothing, so fix the test. A test that guards a race or an ordering must be seen failing against code that has the flaw: run the racing work concurrently, on a multi-threaded runtime where there is one, and wait for a signal the system gives, such as a watch having opened, never for a fixed sleep.
 4. Write the least code that makes it pass (green). Then write the next test. Work in tracer bullets, one test and one slice of code at a time, never all the tests first.
-5. Done when every test plan row whose Subject the task proves has a passing test carrying that ID, and each test fails when the behaviour it checks is removed. Tasks that prove only a `UC`, `ADP` or `MOD` are proved by the rows of the scenarios and ports they serve.
+5. Done when every scenario has a passing test carrying its ID, every port with a real adapter has contract tests, and each test fails when the behaviour it checks is removed.
 
 ## The four kinds
 
-These match the test plan in `.agents/skills/cruze-formats/reference/work-items.md`.
-
 | Kind | Subject | Seam | When |
 | --- | --- | --- | --- |
-| `behaviour` | `SCN` | The use case's API with a fake for each driven port, or the inbound adapter when the outcome is what that adapter shows, such as CLI output, an exit code or an HTTP status | One or more per scenario, always |
-| `contract` | `PORT` | The same cases run against the fake and every real adapter | Every driven port that has a real adapter |
-| `domain` | `ENT` | The entity's own API | Only for real logic: state machines, calculations, invariants with edge cases |
-| `smoke` | `FLOW` | The real inbound adapter, wired by the real composition root | The top 1 to 3 flows |
+| `behaviour` | a scenario | The use case's API with a fake for each driven port, or the inbound adapter when the outcome is what that adapter shows, such as CLI output, an exit code or an HTTP status | One or more per scenario, always |
+| `contract` | a port | The same cases run against the fake and every real adapter | Every driven port that has a real adapter |
+| `domain` | a domain type | The entity's own API | Only for real logic: state machines, calculations, invariants with edge cases |
+| `smoke` | the main path | The real inbound adapter, wired by the real composition root | The top 1 to 3 paths through the system |
 
 A behaviour test drives a use case, not a single domain type, so it keeps passing when rules move between entities. In a library with no use cases, the seam is the library's public API. Write a domain test only when a rule's edge cases are too many to reach through use cases one by one.
 
@@ -51,9 +49,9 @@ A behaviour test drives a use case, not a single domain type, so it keeps passin
 
 ## Protecting the check
 
-- Behaviour, contract and smoke tests for approved scenarios, ports and flows are the safety net. Never edit one to get green. When one fails, either the code is wrong, or the spec is. A wrong spec or design goes through the rethink step, and the test changes only with the delta that changes its subject: a spec delta for a `SCN`, an architecture delta for a `PORT` or `FLOW`.
+- Behaviour, contract and smoke tests for approved scenarios and ports are the safety net. Never edit one to get green. When one fails, either the code is wrong, or the scenario is. A wrong scenario goes back through shape, and the test changes only after the user approves the changed scenario.
 - Domain tests are disposable. Rewrite or delete them along with the code they test.
-- Never skip a test, delete one, or weaken an assertion to finish a task. Verify flags any diff to a safety-net test that has no matching delta.
+- Never skip a test, delete one, or weaken an assertion to finish. Review flags any weakened safety-net test.
 
 ## What not to write
 
@@ -65,6 +63,6 @@ Side-by-side examples are in [examples.md](examples.md).
 
 ## Naming and tracing
 
-- Every test carries its subject ID where `.agents/skills/cruze-formats/reference/work-items.md` says, such as `// SCN-access.direct-serial` on the line above it.
+- Every behaviour test carries its scenario's ID in a comment or string, such as `// SCN-open-serial.attach` on the line above it. A test name alone doesn't count, since `cruze trace` looks for the literal ID.
 - A scenario may need several tests, and each of them carries its ID. One test covers one scenario.
-- `cruze trace` checks scenarios only: it fails when a scenario the change delivers has no test carrying its ID, or when a test cites a scenario nobody defined. Run it before calling a change's tests complete, and quote its result. For the `contract`, `domain` and `smoke` rows, list each subject ID next to the test that carries it.
+- `cruze trace <slug>` fails when one of the feature's scenarios has no test carrying its ID, or when a test cites a scenario no feature defines. Run it before calling a feature's tests complete, and quote its result.

package/skills/behavioural-testing/examples.md

@@ -7,7 +7,7 @@ The examples are in Rust, from a console-access tool. The shape is the same in a
 Good. It drives the use case, fakes the ports, and checks what the caller sees:
 
 ```rust
-// SCN-access.second-hop-refused
+// SCN-ssh-hops.second-hop-refused
 #[test]
 fn second_hop_refused_closes_the_first_hop() {
     let catalog = InMemoryDeviceCatalog::with(device("lab-router", ssh_via("jump-1")));
@@ -89,7 +89,6 @@ The file format is the TOML adapter's business. Its contract tests cover it, and
 Good. A state machine with real rules, tested through the entity's own API:
 
 ```rust
-// ENT-access.console-session
 #[test]
 fn a_closed_session_cannot_reopen() {
     let mut session = ConsoleSession::opening();

package/skills/behavioural-testing/fakes.md

@@ -4,7 +4,7 @@ A fake is a real, working implementation of a driven port that keeps its state i
 
 ## Writing a fake
 
-1. Read the port's `Operations`, with `cruze show <PORT ID>`. The fake implements every operation with the guarantees and failures listed there, and nothing more. That includes every way the real adapter ends on its own, such as a session closed when its stream ends or its server shuts down.
+1. Read the port's operations in `docs/architecture.md`. The fake implements every operation with the guarantees and failures listed there, and nothing more. That includes every way the real adapter ends on its own, such as a session closed when its stream ends or its server shuts down.
 2. Keep state in plain in-memory structures: a map for a catalog, a list for recorded effects, a settable value for a clock.
 3. Give tests a way to arrange state and to inject each failure the contract lists. Use a constructor that takes the initial state, and a method such as `fail_next_with(HopError::Refused)`. When a use case writes through the port, also let a test stall an operation, and fail one that writes several things partway through, so each partial failure and cancellation can be tested from every state it can leave.
 4. Record effects the contract makes observable, such as the order hops were closed in, so tests can assert them.
@@ -21,7 +21,7 @@ A contract test states the port's contract once and runs it against every implem
 3. Run the suite against the fake in the ordinary test run.
 4. Run it against each real adapter too. When the real adapter needs something external, such as an SSH server, a serial device or a database, use a local stand-in (a test server, a pseudo-terminal, a container), and mark the run so CI can provide it.
 
-When the contract changes, the port's `Operations` change first through a delta, then the contract suite, then the fake and the adapters.
+When the contract changes, the port's operations in `docs/architecture.md` change first, then the contract suite, then the fake and the adapters.
 
 ## What a fake is not
 

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