@printpractical/cruze 0.0.1

package/skills/architect/project.md

@@ -0,0 +1,58 @@
+# Architect at project scope
+
+The result has four parts, reviewed together and shown at one walkthrough:
+
+- `docs/architecture.md`, the living model of the whole system, which the user approves.
+- The `layers:` rules in `.cruze/config.yaml`.
+- `docs/roadmap.md` for the first release, which the user approves as its own step.
+- The walking-skeleton change, designed and ready for `plan`. It is approved later, once `plan` has filled its test plan and tasks.
+
+## Design the architecture
+
+1. **Create it.** Run `cruze new architecture`. Follow its sections in order, one at a time, and grill the user on each section's material decisions before writing it.
+2. **Bounded contexts (`CTX`).** Group the vision's capabilities into contexts by which language and rules belong together. Most small systems have one to three. Each context has a `Purpose`, and a `Depends on` naming what it uses from other contexts. Regroup the glossary's terms under one `##` heading per context.
+3. **Domain model (`ENT`).** For each context, model the concepts the vision and glossary name, including invariants, relationships with cardinality, and `States` for anything whose valid operations depend on its state. Add the `VIEW-domain-model` class diagram.
+4. **Use cases (`UC`).** Write one per operation a caller can ask for in this release, each with its input, output, errors and the ports it uses.
+5. **Ports (`PORT`).** Define every capability the use cases need from outside, named by capability. Write each operation's contract, following `.agents/skills/cruze-hexagonal-design/contracts.md`. Add driving ports only where the hexagonal-design skill calls for them.
+6. **Adapters (`ADP`).** Name the technology behind each driven port and each inbound adapter that drives use cases. Run the researcher role on every adapter's technology first, and record the result in the adapter's `Adopts` fact. Take every new dependency to the user.
+7. **Flows (`FLOW`).** Write a `sequenceDiagram` for each of the 2 to 5 most important interactions, including their failure paths. Leave out `Serves` until scenarios exist.
+8. **Modules (`MOD`).** Give each context its hexagonal modules, and give the shared CLI shell and the composition root the `system` scope. Add a `system` module in the `composition` layer for the build and CI files, such as the package manifest and `.github/workflows/`, so the tasks that write them have an owner. Every source file must fall inside some module's `Path`, including namespace files that join a context's modules, such as `src/inventory/mod.rs` or `index.ts`; list them in a `composition` module's `Path` when no other module fits. Every module gets a `Path` and a `Layer`, and every element above gets its `Module` and `File`.
+9. **Dependency rules (`RULE`).** State what may import what, in one or two sentences each.
+10. **Cross-cutting concerns (`XC`).** Cover errors, configuration, logging, concurrency and security, plus build and delivery (CI, formatting, linting). Read `.agents/skills/cruze-hexagonal-design/runtime.md` for concurrency.
+11. **Decisions.** Write an ADR, with `cruze new adr <slug> --title "<title>"`, for each decision that passes the ADR test. Record the other project decisions as `D<n>` lines under `## Decisions`.
+12. **Overview (`VIEW-context`).** Draw the context diagram last, once the adapters and external systems are known.
+
+Done when `cruze validate` reports no errors in `docs/architecture.md`. At this stage it warns that elements have no status yet; approval adds the statuses.
+
+## Write the layer rules
+
+Fill `source`, `tests` and `layers:` in `.cruze/config.yaml` from the module map, following `.agents/skills/cruze-formats/reference/config.md`. Give each module's `Path` exactly one layer, and make each layer's `may_import` match the `RULE` elements. Done when `cruze validate` reports no config errors and no `module-layer` warnings.
+
+## Ignore build output
+
+Add the language's build output and tool caches to `.gitignore` now, such as `/target` for Rust or `node_modules/` for Node, so no later commit sweeps them in.
+
+## Plan the release
+
+1. **Create the roadmap.** Run `cruze new roadmap`. Agree the first release with the user: its name, and which features from the vision's feature map it delivers.
+2. **Order the work.** Phase 1 holds only the `walking-skeleton` change. Later phases hold the release's features. Done when the roadmap passes the rules in step 5 of `.agents/skills/cruze-roadmap/SKILL.md`.
+3. **Design the walking skeleton.** Run `cruze new change walking-skeleton --title "Walking skeleton"`. Then:
+   - Size the elements it builds for the skeleton. Anything the walking skeleton lists under `Builds` is marked built when it lands, so write those elements, such as the CLI adapter or the first entity, at the size the skeleton needs. Record their planned growth in `Future` facts; later features grow them through `MODIFIED` operations.
+   - Choose the thinnest end-to-end slice that crosses every layer: one real inbound adapter, one use case, the domain it needs, one driven adapter and the composition root. It also makes CI real: `cruze init` already runs `cruze validate`, `cruze check --ci` and `cruze trace --all` there, and the skeleton adds the language's format, lint, build and test steps. `plan` fills `commands:` in `.cruze/config.yaml` for it.
+   - Write its `## Intent`.
+   - In `## Adopt or build`, add a row for each tool it adds that no adapter owns, such as the test framework, linter or CI runner.
+   - Write the `## Spec delta` for the one capability it delivers, with scenarios.
+   - In `## Architecture delta`, link the new behaviour to the design: a `MODIFIED` operation for each use case that serves its requirements, adding them to `Serves`, and for each flow that runs its scenarios, adding them to its `Serves`. Each body is the element's full text from `docs/architecture.md` with that fact added.
+   - Fill `## Scope`. `Delivers` lists its scenarios. `Builds` lists the elements it modifies, the other architecture elements it builds, and every module whose first files it writes.
+   - Leave the test plan and tasks to `plan`.
+   - Done when `cruze validate` reports only the change's `not-planned` warning.
+
+## Review, walk through and approve
+
+1. Run the design review and the walkthrough from the skill's steps 6 and 7, over the architecture, the config, the roadmap and the walking skeleton together.
+2. When the user approves the design, run `cruze approve architecture`. It marks every element `planned`.
+3. Confirm the release ordering with the user, then run `cruze approve roadmap`.
+4. Add an `## Architecture` section to `README.md`: one sentence on the system's shape, the `VIEW-context` diagram, and a link to `docs/architecture.md`.
+5. Commit, with a message such as `docs: approve the architecture and roadmap`.
+
+Done when `cruze status` shows the vision, the architecture and the roadmap approved.

package/skills/architect/tweak.md

@@ -0,0 +1,22 @@
+# Architect at tweak scope
+
+A tweak changes existing behaviour without changing the architecture. The result is a standalone change with its intent, spec delta and scope, ready for `plan`. It has no design review and no walkthrough, because nothing structural changes; the plan review in `plan` covers it.
+
+1. **Name the behaviour.** Find the requirements and scenarios in `docs/specs/` that the tweak changes, and the use cases that `Serve` them. Done when you can name every one.
+2. **Check that it is a tweak.** Trace the new behaviour through `docs/architecture.md`. It is not a tweak when it needs a new requirement, which a use case would have to serve, or any new or changed element (an entity invariant, a use case's input or errors, a port operation, an adapter or a module). Tell the user, and continue at feature scope with [feature.md](feature.md), which puts the feature on the roadmap and creates its folder.
+3. **Create the change.** Run `cruze new change <slug> --title "<title>"`, adding `--roadmap <slug>` when the tweak is a roadmap item.
+4. **Settle the behaviour.** Grill the user on anything open: the exact new behaviour, its edge cases, and what a user now observes. Record decisions under the change's `## Settled decisions` as they settle.
+5. **Write the design sections,** and remove every template guide, including any unused `D1` line.
+   - `## Intent`: why, in the user's words, and what is out of scope.
+   - `## Adopt or build`: the table header only, since a tweak adds no components.
+   - `## Spec delta`: `MODIFIED` requirements with their full new bodies, including every scenario each one keeps.
+   - `## Architecture delta`: `None.`
+   - `## Scope`: `Delivers` lists every new or changed scenario. `Builds` stays empty unless the tweak builds `planned` elements.
+   - Leave the test plan and tasks to `plan`.
+6. **Confirm.** Summarize the new behaviour and ask the user to confirm it.
+
+## A prefactor
+
+A prefactor comes from an architecture-level rethink: the architecture already says what the code must become, and one or more built elements went back to `planned`. It changes structure, not behaviour. Create it as in step 3, then write its intent, set `## Spec delta` and `## Architecture delta` to `None.`, and list the replanned elements under `Builds`. The existing behaviour tests are its safety net: they must pass unchanged.
+
+Done when the user has confirmed, `cruze validate` reports only the change's `not-planned` warning, and the change is committed.

package/skills/architect/walkthrough.md

@@ -0,0 +1,29 @@
+# The design walkthrough
+
+The walkthrough is where the user comes to understand the design well enough to explain it without you. It is the one heavy gate before code. Show the design as it stands in the files, one part at a time, in the order below. Pause after each part for questions.
+
+At feature scope, show only what the feature adds, changes or removes, next to the current elements it touches. At project scope, show the whole architecture.
+
+## Order
+
+1. **What it does.** The intent in two sentences, then each requirement with its scenarios' titles.
+2. **Where it sits.** The `VIEW-context` diagram, or at feature scope, the contexts the feature touches.
+3. **The domain.** The domain-model class diagram, then each new or changed entity: its invariants, its states and who owns it.
+4. **How it runs.** For each key flow, show its `sequenceDiagram` and walk one scenario through it step by step, including one failure path. This is the part the user must be able to retell.
+5. **The seams.** Each new or changed port with its operations and their contracts, then the adapter behind each one and the library it adopts.
+6. **Dependencies.** Every new dependency, named out loud with its purpose and the approval behind it. Also the components you chose to build yourself, with the reason.
+7. **Where the code goes.** Each new element next to its module, file path and layer, and the layer rules those files must obey. At project scope, also the `layers:` in `.cruze/config.yaml`.
+8. **The slices.** The changes in order, with what each delivers and builds, and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
+9. **Decisions and review.** The settled decisions and ADRs, each review finding with its disposition, and the points where a fresh implementer could still build something different.
+
+## Showing diagrams
+
+Mermaid diagrams live in the documents, so point to the file and line of each one, and paste its source into the conversation. When the user can render Mermaid (an editor preview, or GitHub), say where to open it. Keep each diagram under 15 nodes; split a bigger picture instead of shrinking it.
+
+## Ending
+
+1. Ask the user to explain one flow back in their own words, or to name what they would still find surprising in the code. Treat their answer as the check that the walkthrough worked, and go back over any part they can't retell.
+2. Ask for approval in these words: "Do you approve this design?"
+3. A request for changes is not an approval. Apply the changes and run `cruze validate`. When they touch placement, dependency direction, adopt-or-build decisions, port contracts or flows, run a new design review on the diff alone. Then walk through only the parts that changed, and ask again.
+4. When the user rejects the design outright, don't approve anything. Ask what is wrong. When the problem is what to build, go back to `envision`; when it is the whole approach, restart this step's design; when the user wants to stop, leave the work unapproved and say how to resume.
+5. Done when the user says they approve.

package/skills/behavioural-testing/SKILL.md

@@ -0,0 +1,63 @@
+---
+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.
+---
+
+# 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.
+
+## Writing tests for a task
+
+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.
+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.
+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.
+
+## 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 |
+
+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.
+
+## Seams and fakes
+
+- A test reaches the system only through its seam. It never calls a private function, never replaces an internal collaborator, and never inspects storage behind a port instead of reading back through the use case.
+- Replace each driven port with a fake: a small in-memory implementation that honours the port's contract, such as `InMemoryDeviceCatalog`. Fake only ports, never your own domain types or use cases.
+- Assert outcomes: return values, errors, and state read back through the interface. Assert calls, their count or their order only when that is itself the contract, such as hops closed in reverse order, and observe it through effects the fake records.
+- Time, randomness and the environment are ports too. Inject a clock instead of reading the system time.
+- A fake earns trust from the contract tests it shares with the real adapter. Read [fakes.md](fakes.md) before writing one.
+
+## Expected values
+
+- Take expected values from an independent source: the scenario's worked example, a spec, or a known-good literal. Never compute the expected value the way the code does.
+- For a failure scenario, check both the error and the state left behind. After a refused second hop, the first hop is closed.
+- Where a plausible wrong outcome exists, assert that it didn't happen.
+
+## 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`.
+- 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.
+
+## What not to write
+
+- Tests of private functions, getters or plain data.
+- Tests that restate the implementation, including snapshots whose expected output was derived the same way the code derives it.
+- Mocks of internal collaborators, and assertions on calls that aren't part of a contract.
+
+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.
+- 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.

package/skills/behavioural-testing/examples.md

@@ -0,0 +1,102 @@
+# Good and bad tests
+
+The examples are in Rust, from a console-access tool. The shape is the same in any language.
+
+## Through the use case, with fakes
+
+Good. It drives the use case, fakes the ports, and checks what the caller sees:
+
+```rust
+// SCN-access.second-hop-refused
+#[test]
+fn second_hop_refused_closes_the_first_hop() {
+    let catalog = InMemoryDeviceCatalog::with(device("lab-router", ssh_via("jump-1")));
+    let connector = FakeHopConnector::new();
+    connector.refuse("lab-router");
+    let open = OpenConsole::new(&catalog, &connector);
+
+    let result = open.run("lab-router");
+
+    assert_eq!(result.unwrap_err(), OpenConsoleError::HopRefused { hop: 2 });
+    assert_eq!(connector.open_hops(), Vec::<String>::new());
+}
+```
+
+Bad. It mocks an internal collaborator and asserts on calls, so it breaks on refactors that keep the behaviour:
+
+```rust
+#[test]
+fn open_console_calls_resolver_then_connector() {
+    let mut resolver = MockPathResolver::new();
+    resolver.expect_resolve().times(1).returning(|_| Ok(path()));
+    // ...asserts that resolve() ran before connect()
+}
+```
+
+## Expected values from the spec
+
+Good. The expected value is the literal from the scenario:
+
+```rust
+// SCN-inventory.list-configured
+#[test]
+fn lists_devices_in_name_order() {
+    let catalog = InMemoryDeviceCatalog::with_names(&["lab-router", "core-switch"]);
+    assert_eq!(ListDevices::new(&catalog).run(), vec!["core-switch", "lab-router"]);
+}
+```
+
+Bad. It recomputes the expectation the way the code does, so it can never disagree with the code:
+
+```rust
+#[test]
+fn lists_devices_sorted() {
+    let names = vec!["lab-router", "core-switch"];
+    let mut expected = names.clone();
+    expected.sort();
+    assert_eq!(ListDevices::new(&catalog_of(&names)).run(), expected);
+}
+```
+
+## Reading back through the interface
+
+Good. It checks the effect through the port's own operation:
+
+```rust
+// SCN-inventory.add-device
+#[test]
+fn added_device_is_listed() {
+    let catalog = InMemoryDeviceCatalog::empty();
+    AddDevice::new(&catalog).run(new_device("lab-router")).unwrap();
+    assert_eq!(ListDevices::new(&catalog).run(), vec!["lab-router"]);
+}
+```
+
+Bad. It bypasses the interface to inspect storage:
+
+```rust
+#[test]
+fn add_device_writes_the_toml_file() {
+    AddDevice::new(&TomlCatalog::at(&path)).run(new_device("lab-router")).unwrap();
+    assert!(std::fs::read_to_string(&path).unwrap().contains("[lab-router]"));
+}
+```
+
+The file format is the TOML adapter's business. Its contract tests cover it, and they read back through `DeviceCatalog`.
+
+## A domain test that earns its place
+
+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();
+    session.opened().unwrap();
+    session.close();
+    assert_eq!(session.opened(), Err(SessionError::AlreadyClosed));
+}
+```
+
+Not worth writing: a test that `Device::name()` returns the name it was built with.

package/skills/behavioural-testing/fakes.md

@@ -0,0 +1,30 @@
+# Fakes and contract tests
+
+A fake is a real, working implementation of a driven port that keeps its state in memory. Behaviour tests use it in place of the real adapter. Contract tests keep it honest.
+
+## Writing a fake
+
+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.
+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)`.
+4. Record effects the contract makes observable, such as the order hops were closed in, so tests can assert them.
+5. Put the fake where every test can reach it, such as `tests/support/` or the language's test-only module, never in production code paths. One fake per port, shared by all tests.
+
+Done when the fake passes the port's contract tests.
+
+## Contract tests
+
+A contract test states the port's contract once and runs it against every implementation.
+
+1. Write the cases as a function or suite that takes a constructor for the implementation under test.
+2. Cover each operation's success, each failure the contract names, and the state after a failure.
+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.
+
+## What a fake is not
+
+- Not a mock that returns canned answers to expected calls. It behaves like the real thing, so a test can call it in any order.
+- Not a partial stub that fails on operations "the test doesn't use". Implement the whole port.
+- Not a place for logic the real adapter doesn't have. If a fake needs a rule, that rule probably belongs in the domain.

package/skills/build/SKILL.md

@@ -0,0 +1,62 @@
+---
+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.
+---
+
+# 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.
+
+## 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:
+   - `.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` and its feature's `feature.md`. Read the full body of every element the change builds, and every scenario it delivers. 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 full test suite, the formatter and the linter, using the project's commands.
+   - Run `cruze check` and `cruze trace`, and quote their results.
+   - Commit the progress record with a message such as `chore: record progress on <change>`.
+   - Done when all of them pass.
+
+## The task loop
+
+For task `T<n>`:
+
+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.
+3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task waits for that task.
+4. **Check.** Run `cruze check <the task's files>`, the formatter and the linter, and fix what they report. Run the tests the task touched, and the rest of the suite when they are 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.
+
+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.
+
+Done for a task when its tests pass, `cruze check` passes for its files, the commit exists and the task is ticked.
+
+## Deviations
+
+The plan is design. Within a task you decide only what is local and reversible.
+
+- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a private type, or two tasks' commits swapped for a reason. 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;
+  - a change to an approved scenario's behaviour, or to its test;
+  - a dependency the design doesn't name.
+
+  Explain what you found, with the evidence, and don't work around it. Completed tasks keep their commits.
+- Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`.
+
+## 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`.
+
+## Next step
+
+`verify`, once every task is ticked and the finishing checks pass.

package/skills/dependency-approval/SKILL.md

@@ -0,0 +1,48 @@
+---
+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.
+---
+
+# 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.
+
+## Asking
+
+1. Establish the need: the capability, and why the standard library and the project's already-approved dependencies don't provide it.
+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.
+
+```markdown
+**Dependency: `russh` for SSH hops**
+- Why not std or existing: the standard library has no SSH client, and no approved dependency 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.
+- 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 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.
+
+## 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 walking-skeleton 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.
+
+## 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.

package/skills/domain-language/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: cruze-domain-language
+description: How to build the project's shared language in docs/glossary.md and use it the same way in conversation, documents, IDs and code. Use when a new domain term comes up, when the user or a document uses a vague, overloaded or conflicting word, when naming an element, ID, type, module, function or test, or when writing or reviewing the glossary.
+---
+
+# Domain language
+
+Use one word per concept, everywhere: in conversation, specs, the architecture, IDs and code. `docs/glossary.md` holds those words, in the format given in `.agents/skills/cruze-formats/reference/durable-docs.md`.
+
+## While designing
+
+1. Read the glossary before the conversation starts, and use its words in your own questions and documents.
+2. When the user uses a term differently from the glossary, say so immediately: "The glossary defines a hop as one link in a console path, but you seem to mean the jump host itself. Which is it?"
+3. When a word is vague or overloaded, such as account, item, session, handle or data, propose one precise term and say what it excludes.
+4. Test a boundary between two concepts with a concrete edge case: "A device reachable over two console paths: is that one device or two?"
+5. When the user says how something works, check the living docs and the code. Point out any contradiction instead of choosing a side.
+6. Write a term into the glossary the moment it settles. The glossary isn't approval-gated, so adding a term never makes a design stale.
+
+Done when every domain noun in the documents this step writes is in the glossary or is a general programming term.
+
+## What belongs
+
+- Terms specific to this domain. General programming concepts, such as timeout, retry or cache, stay out unless the domain gives them a special meaning.
+- A definition says what the thing is, in one or two sentences a domain expert would accept. It never mentions types, files, tables or other implementation.
+- Pick one word per concept and list its synonyms under `_Avoid_`.
+- Group terms under their bounded context. A word that means different things in two contexts gets an entry in each, and the translation happens where the contexts meet.
+
+## Using the language
+
+- Element titles and ID names use glossary terms: `ENT-inventory.console-path`, not `ENT-inventory.route`.
+- Types, modules, functions and tests in code use the same words, in the language's naming style: `ConsolePath` in `console_path.rs`.
+- A word listed under `_Avoid_` in a new title, ID, type or test name is a review finding. Rename it, or settle the term with the user.
+- When a term is renamed, update the glossary and rename element titles freely. IDs keep their old wording, because an ID never changes. Code follows through a change like any other.
+
+## Terms and decisions
+
+The glossary holds language, not decisions. Record decisions as `.agents/skills/cruze-grilling/SKILL.md` describes.

package/skills/envision/SKILL.md

@@ -0,0 +1,29 @@
+---
+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.
+---
+
+# 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`.
+
+## 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 notes in `.cruze/notes/`. 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.
+
+## Rules
+
+- 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.
+- The vision stays within one page, excluding the feature map.
+- Only the CLI writes the feature map. Use `cruze features add` and `cruze features drop`.
+
+## Next step
+
+- After project scope: run `architect` at project scope.
+- After feature scope: run `architect "<feature>"`.

package/skills/envision/feature.md

@@ -0,0 +1,22 @@
+# Envision at feature scope
+
+The result is a feature folder whose `feature.md` holds the intent, the settled decisions and the spec delta, ready for `architect`. Formats: `.agents/skills/cruze-formats/reference/work-items.md` and `.agents/skills/cruze-formats/reference/specs.md`.
+
+1. **Check the project.** `cruze status` must show `docs/vision.md` approved. If it isn't, stop and run envision at project scope first.
+2. **Find the feature.** Look for it in the roadmap's phases and on the feature map's future list.
+   - When it isn't in the roadmap's phases, ask the user whether it belongs in this release. If it does, add it by following "Adding an item" in `.agents/skills/cruze-roadmap/SKILL.md`, and re-approve the roadmap. If it doesn't, put it on the future list with `cruze features add` and stop here.
+   - When its `Blocked by` items haven't landed (see the roadmap's `## Status`), tell the user. Continue only if they want to design ahead, and record that as a settled decision.
+3. **Create the folder.** When the feature has no folder yet, run `cruze new feature <slug> --title "<title>" --roadmap <slug>`, using its roadmap slug. When a folder exists, edit its `feature.md`.
+4. **Read the behaviour it touches.** Read the specs in `docs/specs/` for every capability the feature changes, so you know each requirement and scenario it builds on.
+5. **List the open decisions:**
+   - **Intent:** the problem and outcome in the user's words, who it is for, the constraints, and what is out of scope.
+   - **Requirements:** each behaviour the feature adds, changes or removes, and the capability it belongs to. It goes in an existing capability when the behaviour fits one; otherwise it starts a new capability.
+   - **Scenarios:** for each requirement, the main case, each edge and failure case a user will meet, and what they observe in each. Invent concrete edge cases to test the boundaries.
+6. **Grill in rounds** until every open decision is settled. Record decisions under `## Settled decisions` and terms in the glossary as they settle.
+7. **Write the spec delta.** Use `ADDED` for new requirements, `MODIFIED` for a requirement whose text or scenarios change (writing its full new body with every scenario it keeps), `REMOVED` with a `Reason` and `Migration` for retired behaviour, and `ADDED CAPABILITY` for a new capability.
+   - Name every ID with glossary terms. An ID is never reused.
+   - Done when every requirement has a scenario for its main case and one for each failure a user can meet.
+8. **Leave the design to architect.** Set `## Architecture delta` to `None.` and leave the Changes table with its header row only. Remove the remaining template guides.
+9. **Confirm.** Summarize the intent and each requirement with its scenarios, in plain words, and ask the user to confirm them. Apply any corrections.
+
+Done when the user has confirmed, `cruze validate` reports no errors for the feature, only its `not-designed` warning, and the feature is committed.

package/skills/envision/project.md

@@ -0,0 +1,20 @@
+# Envision at project scope
+
+The result is an approved `docs/vision.md` and a `docs/glossary.md` holding the terms that settled. Formats: `.agents/skills/cruze-formats/reference/durable-docs.md`.
+
+1. **Create the documents.** Run `cruze new vision` and `cruze new glossary` for whichever doesn't exist yet. When the vision exists and you are reworking it, edit it in place. Bounded contexts don't exist yet, so group the glossary's terms under one `##` heading naming the product's domain, such as `## Console access`. `architect` regroups them by context.
+2. **Draft from the input.** Fill every section you can from what the user already gave you, and mark every guess as a question for step 3.
+3. **List the open decisions,** section by section:
+   - **Problem:** the problem in the user's words, and who feels it.
+   - **Users:** each kind of user and the situation they are in.
+   - **Goals:** each goal as a `GOAL-<name>` row, with a measure that says how you would know it's met. A goal without a measure is still open.
+   - **Non-goals:** what the product deliberately doesn't do, and why. Ask about the tempting neighbours of each goal.
+   - **Constraints:** platforms, the implementation language, dependency policy, performance, security, privacy, licensing and legal limits.
+   - **Feature map:** the capabilities that deliver the goals, each a slug with a one-line summary and the goals it serves. They are what later `envision "<feature>"` runs pick up.
+4. **Grill in rounds** until every open decision is settled, following the grilling skill. As each domain term settles, add it to the glossary.
+5. **Write the vision.** Fill each section, and remove every template guide.
+6. **Fill the feature map.** For each capability, run `cruze features add <slug> --summary "<summary>" --goals <GOAL IDs>`. Put command syntax in backticks, such as `` `consolectl console <device>` ``, so it isn't read as a template guide. Running `add` again for the same slug replaces its entry in place. Done when every goal is served by at least one feature on the map.
+7. **Confirm.** Walk the user through the vision in one short summary: the problem, the goals with their measures, the non-goals, the constraints, and the feature map. Ask whether it matches their understanding, and apply any corrections.
+8. **Approve.** When the user approves, run `cruze approve vision` and quote its result. Commit, with a message such as `docs: envision the project`.
+
+Done when `cruze status` shows `docs/vision.md` approved and the glossary holds every domain term the vision uses.

package/skills/explore/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: cruze-explore
+description: Thinks an idea through with the user before any design, comparing options and sketching flows, and writes nothing until the user asks to capture it.
+---
+
+# Explore
+
+Explore is the optional thinking partner that can come before any other Cruze step. It turns a loose idea into clear options and, when the user wants, a captured note that the next step takes as input. It never writes a design, creates work or records an approval.
+
+## Steps
+
+1. **Frame the problem.** Ask what prompted the idea, who it affects, and what outcome would make it worthwhile. If the user starts from a solution, restate the problem underneath it and confirm it. Done when you can state the problem in one sentence the user agrees with.
+2. **Read what exists.** Read whichever of these exist: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, `docs/roadmap.md`, and the code the idea touches. Run `cruze status` to see work in flight. Use the glossary's words from here on, following `.agents/skills/cruze-domain-language/SKILL.md`.
+3. **Separate facts from guesses.** List what is known evidence, what is a hypothesis, and what is a preference. Look up any fact you can rather than asking the user for it.
+4. **Diverge.** Lay out two to four genuinely different approaches, including leaving things as they are when that is credible. For each, give what it changes, what it leaves alone, its benefits, its costs and failure modes, the assumptions it rests on, and what evidence would tell it apart from the others. Sketch an interaction as a Mermaid `sequenceDiagram` or `flowchart` when that makes a difference clearer.
+5. **Converge.** Compare the strongest options against the user's outcome, the vision's goals and constraints, and the architecture. Challenge assumptions and accidental scope growth, following the challenge rules in `.agents/skills/cruze-grilling/SKILL.md`. Recommend one option only when its trade-offs are understood. Otherwise recommend the smallest step that would settle the question, such as a spike, a measurement or a research question.
+6. **Offer to capture.** Summarize the problem, the options, the trade-offs, your recommendation and the open questions, then ask whether to capture them. When the user declines, stop here: the discussion itself was the result.
+
+## Capturing
+
+Only when the user says to capture:
+
+1. Run `cruze new note <slug> --title "<title>"` and write the note at the path it returns.
+2. Give the note these sections: `## Problem`, `## Options`, `## Recommendation` and `## Open questions`. Mark each statement as fact, hypothesis, preference or recommendation.
+3. Done when the note stands on its own for a reader who wasn't in the conversation.
+
+## Handing off
+
+Name the next step, and pass the note's path to it when there is one:
+
+| The idea is | Next step |
+| --- | --- |
+| A new project, or the project's first vision | `envision`, at project scope |
+| A new capability whose requirements aren't settled | `envision "<feature>"` |
+| A capability whose requirements are settled | `architect "<feature>"` |
+| A small change to existing behaviour | `architect "<tweak>"` |
+| A defect in built behaviour | `triage "<symptom>"` |
+| A decision already made that now looks wrong | `rethink` |
+| Not worth doing now | `cruze features add <slug> --summary <text> --goals <ids>`, with the user's agreement, to keep it on the future list |