@printpractical/cruze 0.0.13 → 0.0.15

package/skills/formats/reference/durable-docs.md

@@ -1,74 +0,0 @@
-# Vision, glossary, ADR and roadmap formats
-
-Templates: [../templates/vision.md](../templates/vision.md), [../templates/glossary.md](../templates/glossary.md), [../templates/adr.md](../templates/adr.md) and [../templates/roadmap.md](../templates/roadmap.md).
-
-## docs/vision.md
-
-What the product is for, and the intent every design answers to, for the product's whole life. Problem through Constraints fit on one page. The Principles and Must stay possible tables don't count against it: each row holds as much as its intent needs, and `Leave room for` keeps every need, one clause each, so no step has to guess what was meant.
-
-| Section | Holds |
-| --- | --- |
-| `## Problem` | The problem, in the user's words, in one short paragraph |
-| `## Users` | Who uses it and in what situation, one bullet each |
-| `## Goals` | Table of ID, Goal and Measure. Each goal is a row element with a `GOAL-<name>` ID, and its measure says how you would know it's met |
-| `## Non-goals` | What the product deliberately doesn't do, one bullet each with the reason |
-| `## Constraints` | Platforms, languages, dependencies, performance, security and legal limits, one bullet each |
-| `## Principles` | Table of ID, Principle and Why. Each is a row element with a `PRINCIPLE-<name>` ID: a rule every design follows, such as "state is the truth; events are hints". A design that departs from one amends it here first |
-| `## Must stay possible` | Table of ID, Capability, Likelihood, Why and Leave room for. Each is a row element with a `LATER-<name>` ID: a capability the product may need after this release. Likelihood is `likely` or `possible`. Leave room for says what no design may close off, never how to build it. A design that keeps a seam open for one cites it in a `Future` fact |
-| `## Feature map` | Managed. `### Implemented` is a table of Feature, Release and Summary. `### Future` is a table of Feature, Summary and Goals |
-
-- Principles and capabilities that must stay possible live here, not in a feature's settled decisions, which are archived when the feature lands. A project with none writes `None.` under the heading.
-- Feature-map entries are named by slug, such as `jump-hosts`. A future entry gets a folder ID only when its feature starts.
-- Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features update` corrects an entry's summary on either list, `cruze features drop` removes one from the future list, and `land` moves a finished feature to implemented, tagged with the release in progress.
-
-## docs/glossary.md
-
-The shared language, with no implementation detail. Anyone may add a term the moment it settles. The glossary is not approval-gated.
-
-```markdown
-## Console access
-
-**Hop**: One link in the chain from the user to a device console: an SSH connection or a serial line.
-_Avoid_: jump, leg
-
-**Console path**: The ordered hops that reach one device's console.
-_Avoid_: route, connection string
-```
-
-- Group terms under a `##` heading per bounded context, alphabetically within each group.
-- A definition is one or two sentences, in terms a domain expert would accept.
-- `_Avoid_:` lists synonyms to stop using, so code, docs and conversation converge on one word.
-- A term used in docs or code but missing here is a signal. Either the term is new and belongs here, or someone is inventing language.
-
-## docs/adr/<date>-<slug>.md
-
-Write one only when a decision is hard to reverse, would surprise a newcomer, and was a real trade-off. Everything else is a settled decision: in a feature or change, or at project scope in the architecture's `## Decisions`.
-
-```markdown
-# Console paths are ordered hop chains
-
-- Status: accepted
-- Date: 2026-09-24
-- Elements: ENT-inventory.console-path, PORT-access.hop-connector
-
-<One paragraph: the context, the decision, why it won, and the alternatives rejected.>
-```
-
-- The ID is `ADR-<file stem>`, such as `ADR-2026-09-24-hop-chains`.
-- `Status` is `accepted` or `superseded by ADR-<stem>`. A superseded ADR stays; the new ADR says what changed.
-- Review never re-raises a decision covered by an accepted ADR without new evidence. Proposing to contradict one must name it: "Contradicts ADR-<stem>, worth reopening because…".
-
-## docs/roadmap.md
-
-The current release, as an index. It changes only when a feature or standalone change starts, finishes or is reordered.
-
-| Section | Holds |
-| --- | --- |
-| `## Release` | The release name and one sentence on what it delivers |
-| `## Phases` | One `### Phase <n>: <name>` per phase, each a table of Item (slug), Kind (`feature` or `change`), Goals and Blocked by |
-| `## Coverage` | Table of Goal and the items that serve it. Every goal in scope has at least one item |
-| `## Status` | Managed: each started item's folder ID and state (`designing`, `building` or `landed`). `cruze new` adds the row and `cruze land` updates it |
-
-- Items are named by slug. The first item of a new project is the `foundation` standalone change, of the kind the user chose at architect.
-- `Blocked by` lists slugs that must land first. The blocking graph has no cycles.
-- A new release replaces `## Release` and `## Phases`. Landed items leave the roadmap once the release closes; the feature map in the vision keeps the record.

package/skills/formats/reference/specs.md

@@ -1,65 +0,0 @@
-# Specs format
-
-`docs/specs/<capability>.md` holds the living behaviour of one capability, meaning what the system does as seen from outside. Requirements say what must hold. Scenarios are worked examples that become behaviour tests. Nothing in a spec names classes, files or libraries; those belong in the architecture.
-
-Template: [../templates/spec.md](../templates/spec.md).
-
-## Spec file
-
-```markdown
-# Console access
-
-Opening consoles on configured devices and running commands on them.
-
-## REQ-access.open-console: Open a device console
-The CLI SHALL connect the user's terminal to the console of a configured device, through every hop of its console path, and restore the terminal when the session ends.
-
-### SCN-access.direct-serial: Console on a local serial port
-- GIVEN device `lab-router` has console path `serial /dev/ttyUSB0 115200`
-- WHEN the user runs `consolectl open lab-router`
-- THEN the terminal shows the device's console output within 2 seconds
-- AND pressing `Ctrl-]` then `q` closes the session and restores the terminal
-```
-
-- The file name is the capability, and the capability is the scope of every ID in it.
-- One `#` title, then a purpose paragraph of one to three sentences.
-- Each requirement is a `##` heading element, `REQ-<capability>.<name>: <Title>`. Its body states the requirement in one to three sentences containing `SHALL` or `MUST`. Use `SHALL NOT` or `MUST NOT` for behaviour that must never happen.
-- Each scenario is a `###` heading element under its requirement, `SCN-<capability>.<name>: <Title>`. A requirement has at least one.
-
-## Scenario grammar
-
-- Bullets in order: zero or more `GIVEN`, one `WHEN`, one or more `THEN`. `AND` continues the clause above it.
-- Use concrete values: names, inputs, outputs, limits and times. The expected values are the test's oracle, worked out by hand. They are never copied from running the code.
-- One behaviour per scenario. Failure behaviour gets its own scenario, including what state is left behind.
-- The CLI adds a managed `- Status:` item. A scenario is `built` once a landed change delivered it with a passing test that names its ID.
-
-## Spec delta
-
-A feature, or a standalone change, proposes behaviour changes in its `## Spec delta` section. Operation headings sit at `###` and scenarios at `####`:
-
-```markdown
-### ADDED CAPABILITY inventory: Device inventory
-Reading and validating the configured devices and their console paths.
-
-### ADDED REQ-access.jump-host-chain: Connect through jump hosts
-The CLI SHALL reach a device's console through every SSH hop in its console path, in order.
-
-#### SCN-access.serial-behind-jump-host: Serial console on a jump host
-- GIVEN ...
-
-### MODIFIED REQ-access.open-console: Open a device console
-The full new requirement text.
-
-#### SCN-access.direct-serial: Console on a local serial port
-- ...every scenario the requirement keeps, in full
-
-### REMOVED REQ-access.telnet: Telnet consoles
-- Reason: telnet support was dropped
-- Migration: configure an SSH hop to a terminal server instead
-```
-
-- `ADDED CAPABILITY` creates a new spec file, with its title and purpose paragraph. It is only needed for a capability that has no file yet.
-- `ADDED` introduces a new requirement with all its scenarios.
-- `MODIFIED` replaces a requirement's whole block, including every scenario it keeps. A scenario left out is removed, so no part of the work may cite it by ID (`cites-dropped`); describe it in words.
-- `REMOVED` retires a requirement and its scenarios, and needs a `Reason` and a `Migration`.
-- `land` shifts heading levels to fit the spec file and keeps the managed status of scenarios that were already built.

package/skills/formats/reference/work-items.md

@@ -1,100 +0,0 @@
-# Feature and change format
-
-Work in progress lives in `.cruze/`. A **feature** carries the design: its intent, its deltas and the ordered list of its changes. A **change** is one buildable slice: its scope, its test plan and its tasks. A small tweak is a **standalone change** that carries its own deltas. When work lands it is archived, and its deltas become part of the living docs.
-
-Templates: [../templates/feature.md](../templates/feature.md), [../templates/change.md](../templates/change.md) and [../templates/standalone-change.md](../templates/standalone-change.md).
-
-## IDs and folders
-
-- Features and standalone changes get an ID from `cruze new`: the creation date plus a slug, such as `2026-09-25-jump-hosts`. The CLI adds `-2` on a same-day clash.
-- A feature's changes are numbered inside the feature, as in `01-ssh-hop` and `02-serial-behind-hop`. The full reference is `<feature id>/<change>`.
-- Frontmatter holds `id`, `title` and, for features, `roadmap` (the roadmap item slug). A retry of an abandoned or superseded item adds `supersedes: <old id>`.
-
-## feature.md
-
-| Section | Holds |
-| --- | --- |
-| `## Intent` | The problem and outcome in the user's words, who it is for, constraints, and what is out of scope |
-| `## Settled decisions` | Decisions the user confirmed, one bullet each as `D<n>: <decision> (<reason>)`, including overrides of Cruze's advice |
-| `## Adopt or build` | Table of components that aren't domain logic, as Component, Decision (`adopt` or `build`), Choice and Reason |
-| `## Spec delta` | See [specs.md](specs.md) |
-| `## Architecture delta` | See [architecture.md](architecture.md) |
-| `## Changes` | Table of the ordered changes, as Change, Delivers, Builds, Removes (optional) and Depends on |
-| `## Progress` | Managed: state of each change, landed commits and the deviation log |
-
-## change.md
-
-| Section | Holds |
-| --- | --- |
-| `## Scope` | `- Delivers:` scenario and requirement IDs, `- Builds:` architecture IDs, `- Removes:` IDs retired by this change |
-| `## Test plan` | Table of Subject, Seam, Test file and Kind, one row per delivered scenario and per contract-tested port |
-| `## Tasks` | One task line per task, in build order |
-| `## Settled decisions` | Decisions made while planning this change, same format as the feature |
-| `## Risks` | What could break and the riskiest task, when there are any |
-| `## Progress` | Managed: ticked tasks with their commits, deviations and the bound branch |
-
-A standalone change adds `## Intent`, `## Adopt or build`, `## Spec delta` and `## Architecture delta` before its `## Scope`, in the same format as a feature's. Its scope covers every ID in its own deltas, plus any `planned` elements from the living docs that it builds.
-
-A feature is designed in two steps. Feature-scope `envision` writes the intent, settled decisions and spec delta, and leaves `## Architecture delta` as `None.` and the Changes table empty. `architect` writes the architecture delta and the changes. Until the Changes table has a row, `cruze validate` reports the feature as `not-designed` (a warning), skips the coverage rules, and `cruze approve` refuses it. A feature of more than 6 changes gets a `feature-size` warning: split it, because one design review can't hold it. A change outside the size band in `changes:` of `.cruze/config.yaml` gets `change-too-small` (it builds fewer than 3 elements, in a feature of several changes) or `change-too-large` (it delivers more than 30 scenarios), and a plan of more than 25 tasks gets `plan-too-large`. `cruze approve` refuses an item with one of these warnings standing (`size-unaccepted`) until the work is split or the user's acceptance is listed under `changes.exceptions`.
-
-`architect` writes a standalone change's design sections and its scope, and leaves the test plan table empty and the tasks section blank. Until `plan` fills them, `cruze validate` reports the change as `not-planned` (a warning), skips the task and test plan rules, and `cruze approve` refuses it.
-
-## Scope rules
-
-These rules close the gap between a design and what gets built. `cruze validate` checks them.
-
-- Every ID in a feature's deltas appears in the scope of exactly one of its changes. For a standalone change, that is its own scope. A `MODIFIED` or `REMOVED` requirement is covered by its ID or by one of its scenarios.
-- A scope may also name elements already in the living docs with status `planned`, such as the foundation change that builds elements the project architecture defined. An element with no status yet counts as planned: it appears only while the architecture has never been approved, so project-scope architect can write the foundation before that first approval.
-- The first change of a feature to land merges the feature's whole delta, so the living docs never cite something a later change hasn't merged yet. What this change delivers or builds becomes `built`. Everything else arrives as `planned`, including a `MODIFIED` element whose new text isn't built yet. Each later change flips what it builds to `built`.
-- A `REMOVED` operation applies when the change whose scope lists it under `Removes` lands.
-- Under a `MODIFIED` requirement, a scenario must be in some change's scope when it is new or its text changed. An unchanged scenario the requirement keeps needs no change.
-- If someone else edits an element after this feature merged it, their edit stands: while the feature's delta entry for that element is unchanged, later lands keep the living text, and approving the feature needs no rebase. When the feature's delta changes that element again, `cruze approve` refuses with `rebase-required` and `cruze land` with a conflict, rather than overwrite the edit. Resolve it with `rethink`.
-- The `Changes` table and each change's `Scope` agree. `plan` copies the row into the change and refines it; a disagreement is a validation error.
-
-## Test plan
-
-| Kind | Subject | Seam |
-| --- | --- | --- |
-| `behaviour` | a `SCN` ID | the use case it runs through, with a fake named for each driven port; or the inbound adapter, when the outcome is what that adapter shows, such as CLI output and exit codes |
-| `contract` | a `PORT` ID | the port, run against its fake and each real adapter |
-| `domain` | an `ENT` ID | the entity's own API, only for rules with real logic |
-| `smoke` | a `FLOW` ID | the real inbound adapter, end to end |
-
-Every delivered scenario has at least one `behaviour` row, and every port that a built adapter `Implements` has a `contract` row. The test file path is where the test will live. The subject ID appears in the test's name, or in a comment on the line directly above it when the language's names can't hold an ID. That is how `cruze trace` finds it.
-
-## Task lines
-
-```markdown
-- T1: `HopConnector` port in `src/access/app/ports/hop_connector.rs`, proves PORT-access.hop-connector
-- T2: `SshConnector` in `src/access/adapters/ssh_connector.rs`, proves PORT-access.hop-connector, SCN-access.ssh-through-jump-host
-```
-
-- Grammar: `- T<n>: <owner> in <path>[, <path>], proves <ID>[, <ID>]`. Owner and paths are in backticks.
-- One owner per task, and every path names a file the architecture assigns to that owner. Test support that no element owns, such as a shared fake, names its test file instead.
-- Every scenario the change delivers is proved by at least one task, and so is every `Builds` element. The exception is a `MOD`, which is proved by any task with a path inside the module's `Path`.
-- Tasks are design, not progress. Their checkboxes live in `## Progress`.
-
-## Progress
-
-The managed block the CLI maintains. `cruze approve` binds a change to the current branch, `cruze task done` ticks a task with its commit, `cruze task reopen` unticks one a rethink changed, `cruze task deviation` records a deviation, and `cruze land` records the date and the last commit of the change's work:
-
-```markdown
-<!-- cruze:managed -->
-## Progress
-- Branch: jump-hosts-ssh
-- [x] T1 (a1b2c3d)
-- [ ] T2
-- Deviation T1: moved `HopError` into `hop_connector.rs`; same owner, same module
-<!-- /cruze:managed -->
-```
-
-A deviation line records a task-level choice the agent made on its own. Anything larger goes through `rethink`.
-
-## Other files in a change folder
-
-- `manual-test.md`, written by `verify`: numbered steps a person runs against the real system, one section per delivered scenario, each with its expected result.
-- `approvals.json` and `journal.jsonl`, written only by the CLI.
-
-## Verification
-
-A change lands only after the user accepts it at `verify`, which records `cruze journal add verification --set result=accepted --set summary=<text> --item <ref>`. A later approval of the change keeps that acceptance only when the change's own design is unchanged. `cruze land --override <reason>` lands without it, and journals the reason.

package/skills/formats/templates/adr.md

@@ -1,7 +0,0 @@
-# <Decision, stated as a fact>
-
-- Status: accepted
-- Date: {{date}}
-- Elements: <IDs of the architecture elements this decision shapes>
-
-<One paragraph: the context that forced a decision, the decision, why it won, and the alternatives rejected.>

package/skills/formats/templates/change.md

@@ -1,29 +0,0 @@
----
-id: {{id}}
-title: {{title_quoted}}
----
-
-# Change: {{title}}
-
-## Scope
-
-- Delivers: <SCN and REQ IDs>
-- Builds: <architecture element IDs>
-
-## Test plan
-
-| Subject | Seam | Test file | Kind |
-| --- | --- | --- | --- |
-| <SCN ID> | <UC ID> with fake <PORT IDs> | `<path>` | behaviour |
-
-## Tasks
-
-- T1: `<owner>` in `<path>`, proves <IDs>
-
-## Settled decisions
-
-- D1: <decision> (<reason>)
-
-<!-- cruze:managed -->
-## Progress
-<!-- /cruze:managed -->

package/skills/formats/templates/glossary.md

@@ -1,8 +0,0 @@
-# Glossary
-
-The shared language of {{project_name}}. Terms are grouped by bounded context, alphabetically within each group. Add a term the moment it settles.
-
-## <Context name>
-
-**<Term>**: <One or two sentences a domain expert would accept.>
-_Avoid_: <synonyms to stop using>

package/skills/formats/templates/roadmap.md

@@ -1,32 +0,0 @@
-# Roadmap
-
-## Release
-
-<Release name>: <one sentence on what the release delivers.>
-
-## Phases
-
-### Phase 1: Foundation
-
-| Item | Kind | Goals | Blocked by |
-| --- | --- | --- | --- |
-| foundation | change | <GOAL IDs> | |
-
-### Phase 2: <name>
-
-| Item | Kind | Goals | Blocked by |
-| --- | --- | --- | --- |
-| <slug> | feature | <GOAL IDs> | foundation |
-
-## Coverage
-
-| Goal | Items |
-| --- | --- |
-| GOAL-<name> | <slugs> |
-
-<!-- cruze:managed -->
-## Status
-
-| Item | ID | State |
-| --- | --- | --- |
-<!-- /cruze:managed -->

package/skills/formats/templates/spec.md

@@ -1,11 +0,0 @@
-# <Capability title>
-
-<What this capability does, seen from outside, in one to three sentences.>
-
-## REQ-<capability>.<name>: <Requirement title>
-<The requirement in one to three sentences using SHALL or MUST.>
-
-### SCN-<capability>.<name>: <Scenario title>
-- GIVEN <starting state, with concrete values>
-- WHEN <the one action>
-- THEN <observable outcome, with concrete values>

package/skills/formats/templates/standalone-change.md

@@ -1,46 +0,0 @@
----
-id: {{id}}
-title: {{title_quoted}}
-roadmap: <roadmap item slug, when the change is on the roadmap>
----
-
-# Change: {{title}}
-
-## Intent
-
-<Why this change, in the user's words, and what it deliberately leaves out.>
-
-## Adopt or build
-
-| Component | Decision | Choice | Reason |
-| --- | --- | --- | --- |
-
-## Spec delta
-
-### MODIFIED REQ-<capability>.<name>: <Requirement title>
-<The full new requirement, with every scenario it keeps.>
-
-## Architecture delta
-
-None.
-
-## Scope
-
-- Delivers: <SCN and REQ IDs from the spec delta>
-- Builds: <architecture IDs from the delta, and planned elements this change builds>
-
-## Test plan
-
-| Subject | Seam | Test file | Kind |
-| --- | --- | --- | --- |
-
-## Tasks
-
-
-## Settled decisions
-
-- D1: <decision> (<reason>)
-
-<!-- cruze:managed -->
-## Progress
-<!-- /cruze:managed -->

package/skills/grilling/SKILL.md

@@ -1,90 +0,0 @@
----
-name: cruze-grilling
-description: How to interview the user until design decisions are settled. Questions go in rounds over a tree of decisions, facts are looked up rather than asked, each question carries a recommendation and shows what each option looks like, and challenges the user overrides are recorded. Use when a design step needs decisions from the user, when shaping an idea, vision, feature, architecture or plan with them, when the user steers toward something that breaks a rule, or when the user asks to be grilled or to stress-test a plan, and when showing the user review findings or a design to decide on.
----
-
-# Grilling
-
-Interview the user until you both understand the design the same way. Decisions are the user's. Facts are yours to find.
-
-## Running the interview
-
-1. List the open decisions this step must settle, as a tree in which each decision hangs off the ones it depends on. Take them from the sections of the document the step writes and from what the user has already said. Done when every section the step writes has its decisions listed.
-2. Settle the facts yourself. Anything the repository, the living docs, a `cruze` command or a primary source can answer is a fact, so look it up rather than asking. Where the agent can run a helper in parallel, send it to look while you ask about everything that doesn't depend on the answer.
-3. Find the frontier: every open decision whose prerequisites are settled. A question that depends on another open question waits for a later round.
-4. Ask the frontier as one round, in the format below. Every question shows what each option looks like and carries your recommended answer and the reason for it. Read [illustrating.md](illustrating.md) before the first round.
-5. Wait for the answers. Record each settled decision as described under Recording, then recompute the frontier.
-6. Repeat until the frontier is empty: every branch visited, and nothing silently assumed.
-7. Write the sections the step produces from the settled decisions, then summarize them, illustrated as [illustrating.md](illustrating.md) says, and ask the user to confirm that they match their understanding. Done when the user confirms. Decisions and glossary terms are recorded as they settle, and nothing is approved before the confirmation.
-
-## A round
-
-````markdown
-Where we are: architect for 2026-09-25-open-console, round 2. Settled: a console session may cross jump hosts, and credentials come from the vault.
-
-**Q4. Where the jump-host list lives**
-Per device in the device config, or as named hosts that devices reference. Named hosts avoid repeating a host's address and credentials across devices, but add a second lookup.
-
-```yaml
-# A: per device                    # B: named hosts (recommended)
-devices:                           jump_hosts:
-  core-sw-01:                        lab-gw: { address: 10.0.0.5 }
-    jump: { address: 10.0.0.5 }    devices:
-  core-sw-02:                        core-sw-01: { jump: lab-gw }
-    jump: { address: 10.0.0.5 }      core-sw-02: { jump: lab-gw }
-```
-
-Recommended: named hosts, because the lab config already shares two jump hosts across 30 devices.
-
-**Q5. What a refused second hop reports**
-...
-````
-
-- Number questions across the whole session, not per round, so an answer such as "Q7: yes" is never ambiguous.
-- Keep a round to what the user can answer in one reply, about 3 to 5 questions. When the frontier is bigger, ask first the questions that others depend on.
-- Ask about behaviour and trade-offs in the user's terms and the glossary's words, not about implementation mechanics. Where the trade-off is in the code's shape, show the shape.
-- When the user answers "you decide" or "I don't know", take your recommendation and record it with "(recommended; the user deferred)".
-- When an answer contradicts an earlier decision, point to that decision and ask which one stands.
-- When the user doubts part of the design, calling it rigid, heavy or messy, one option removes or shrinks it, with what that costs. One user called a status shape rigid, was offered more of it, and stopped a build over its unused fields a day later.
-- When making one answer hold needs new types, rules or error cases, and those need fixes of their own, stop before the next round. Show what the answer has grown beside the simplest alternative that meets the user's need, and let the user choose. One rethink grew four types over eleven questions before a review found five blockers in them; the alternative was 40% smaller.
-
-## What to ask and what to decide
-
-Ask the user when a choice affects any of these:
-
-- Scope: what is in and what is out.
-- A public contract, including the errors a caller sees.
-- The architecture: contexts, ports, dependency direction and the module map.
-- A dependency, always, through `.agents/skills/cruze-dependency-approval/SKILL.md`.
-- Security, privacy or compliance.
-- Compatibility, stored data or migration.
-- A commitment that is costly or hard to reverse.
-
-Decide yourself anything local and reversible, such as private names, file-local structure, internal representation and equivalent idioms. Pick the conventional option without asking. Uncertainty alone doesn't make a choice the user's: investigate first, and ask only when the evidence leaves two materially different valid outcomes.
-
-## Challenge, then defer
-
-When the user steers toward something that breaks a principle, an accepted ADR or a Cruze knowledge skill:
-
-1. Name the rule, the concrete risk in this project and a recommended alternative, once. For example: "I'd push back on reading the config inside the SSH adapter. cruze-hexagonal-design keeps adapters from calling other adapters, and here the SSH adapter would silently depend on the file format. I recommend passing the resolved hop into the adapter. Your call."
-2. The user decides, and their decision stands.
-3. Record the override. It becomes an ADR when it passes the ADR test in `.agents/skills/cruze-formats/reference/durable-docs.md`; otherwise it becomes a settled decision that names the rule and the reason: `D4: the SSH adapter reads jump-host config directly, overriding cruze-hexagonal-design's adapter rule (the user wants one file for the prototype)`.
-4. Never raise the same challenge again. Reviewers read the settled decisions and ADRs, so they won't either.
-
-Be direct and precise, peer to peer. Challenge only with a specific reason, and never agree without thinking.
-
-## Long-term intent
-
-The vision's `## Principles` and `## Must stay possible` hold what the product answers to beyond the work in hand. A step's own decisions are archived with its work, so long-term intent recorded there is lost. One project's "eventually" answers all went into feature decisions, and were archived with them.
-
-- **The user names something the product may need later,** in an answer or an aside, with words such as "eventually", "in the future" or "one day": propose a `LATER` row for it, with its likelihood, why, and what no design may close off. Ask it in the round.
-- **A decision touches a capability area:** once per area, ask about what it may grow into, as `.agents/skills/cruze-envision/possibilities.md` describes, unless the vision already records it.
-- **A decision departs from a `PRINCIPLE`:** name the principle, and ask whether it changes for the whole project. When it does, amend its row, with the new reason, before you record the decision. When it doesn't, the decision changes. Never record a decision that contradicts a principle the vision still states.
-- **Record it in the vision.** Edit `docs/vision.md` as the answers settle, show the user the rows that changed, and once they confirm, they approve it with `cruze approve vision`. A design that cites a row goes stale when it changes, and its next step re-checks it.
-
-## Recording
-
-- Record each decision as soon as it settles, not at the end.
-- Principles and capabilities that must stay possible go in the vision, as "Long-term intent" says, whatever step you are in.
-- The workflow step names the document. Features and changes keep decisions in `## Settled decisions` as `D<n>: <decision> (<reason>)`. At project scope, the vision keeps goals, non-goals and constraints in their own sections, and other project decisions go in the architecture's `## Decisions` as `D<n>` lines. A decision that passes the ADR test becomes an ADR.
-- Put a term in the glossary the moment it settles, following `.agents/skills/cruze-domain-language/SKILL.md`.

package/skills/grilling/illustrating.md

@@ -1,38 +0,0 @@
-# Illustrating a question
-
-The user decides from what they can picture. A question about a port's errors or a module's place is hard to answer from words alone, and the user is often coming back from other work. So every question, review exception and confirmation shows what each option looks like, and reads on its own without the conversation before it.
-
-## Reading cold
-
-- The user knows what the product should do, not the design's internals. Before a question about a part of the design, say in a sentence or two what that part is, what it does today and why the question comes up, and show it. Ask about what the user will notice, and explain the mechanism only as far as the choice needs. In one day of one project, the user asked four times what a question meant, from "what's the definition of a condition?" to "give me an ELI5".
-- Open each round, and each message of review exceptions, with one line saying where things stand: the work item, the step, and the earlier decisions this round builds on, such as `Where we are: architect for 2026-10-08-subscriptions, round 3. Settled: one stream per session, and events carry revisions.`
-- The user doesn't know the design's IDs by heart. Name each requirement, scenario, element, decision or task in plain words, and add its ID after them in parentheses only when the user may want to look it up: "a second set asking for a priority already taken is refused (SCN-configuration.reject-taken-priority)". Never let an ID stand alone or be what a sentence is about, as in "D11 forbids this". In one project, 197 of the 215 IDs in 75 questions stood alone, and the user misread what was asked.
-- Each question says what it decides and why it matters now, without pointing back to an earlier message.
-
-## Choosing the illustration
-
-Show each option, side by side, with the form that fits what the question decides:
-
-| The question decides | Show |
-| --- | --- |
-| What a user does or sees | The command they type and its exact output, or a plain-text sketch of the screen, using the scenario's concrete values |
-| A port, a use case's input and errors, or a public API | A code sketch in the project's language: the types and signatures, and the call a caller writes |
-| Where something lives: contexts, modules, dependency direction | A box-and-arrow diagram, or the directory tree with the files the option adds |
-| An order of steps, or what happens on failure | A numbered sequence or a plain-text sequence diagram, with the failure branch |
-| States and what moves between them | The states with their transitions, one per line |
-| A stored format or a config file | A sample of the file |
-| A dependency | The code with it and the code without it |
-
-Leave out the illustration only when the question is about a name, a number or the wording of a sentence, where it would repeat the words. A question asked through a pick-one tool carries it too: in each option's preview where the tool has one, otherwise in a message just before. One build asked through such a tool with only file and function names in its options, and the user had to ask what it meant.
-
-## Writing it
-
-- Use the design's names and the glossary's words, and the values of a real scenario, so the user sees this project's code, not a generic example.
-- A code sketch shows shape: types, signatures, the error variants, and one call site. Leave bodies out, writing `...` or the language's placeholder. Keep each option to about 15 lines.
-- Draw diagrams in plain text, so they read in a terminal, where Mermaid shows only as source. The documents keep their Mermaid diagrams; the illustration is for the conversation.
-- At envision, show behaviour only: interactions and screens, never code, since envision keeps implementation out.
-- Mark your recommended option in the illustration itself, and show the failure case when the options differ in how they fail.
-
-## After the answer
-
-A shape the user chose from a sketch is part of the decision. Write it into the document in that document's format: the port's `Operations`, the entity's facts, the module's `Path`, or the scenario's values. Build follows the documents, so the code comes out as the user saw it.

package/skills/improve/SKILL.md

@@ -1,51 +0,0 @@
----
-name: cruze-improve
-description: Improves the structure of existing code to meet Cruze's current standards, by surveying it for structure that departs from them or keeps causing friction, letting you pick any or all of the candidates, designing the target through an architecture rethink, and scheduling the moves as prefactor changes.
----
-
-# Improve
-
-Improve restructures code that already works, so it meets the standards Cruze holds new work to, such as a layout that is normal for the kind of system, or so it stops causing the same friction. It is design work with one approval gate, and it never changes behaviour: the behaviour tests are the safety net, and they pass unchanged at every step.
-
-Realign is different. It applies what each release's notes expect of existing code, and moves `standards:`. Improve runs whenever the user asks, whatever the version, and can take on structure that realign leaves alone, such as a layout the notes mark as new work only.
-
-## Steps
-
-1. **Check what it builds on.** Run `cruze status`. `docs/architecture.md` must be approved and current; when it isn't, stop and name `rethink`. Note the features and changes in flight, which step 8 schedules around. When the user names an area, such as a context or a module, keep to it.
-2. **Check the safety net.** Run `cruze trace --all`, and the full suite as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`. Done when both pass, and you have listed each module whose scenarios have no test. Moving such a module first needs tests that record what it does today.
-3. **Load the standards.** Read these, and follow them for the rest of this skill:
-   - `.agents/skills/cruze-hexagonal-design/SKILL.md`, `.agents/skills/cruze-hexagonal-design/shapes.md`, and the language file when one exists for the project's language
-   - `.agents/skills/cruze-behavioural-testing/SKILL.md`
-   - `.agents/skills/cruze-formats/reference/architecture.md`
-   - `.agents/skills/cruze-grilling/SKILL.md`
-4. **Survey.** Run the surveyor role from `.agents/skills/cruze-roles/SKILL.md` once for the system's layout, then once for each module in the module map, or in the user's area, giving it the module's `Path`. Run them in parallel where the agent can. Check each candidate's evidence against the files and the journal before you use it. Done when the layout and every module in scope have a report.
-5. **List the candidates** in one message, numbered, merging candidates that share a cause across modules. For each, give:
-   - the problem in one sentence, and its evidence;
-   - the standard it departs from, or the friction it causes;
-   - the target shape, sketched beside today's as `.agents/skills/cruze-grilling/illustrating.md` says;
-   - its size in prefactor changes, and its risk.
-
-   Recommend which to take and why, then ask the user to pick any or all of them.
-6. **Record each decision:** `cruze journal add disposition --set review=improve --set finding="<module or area>: <summary>" --set disposition=<fixed|waived|deferred> --set reason="<reason>" --set decided=user`. A picked candidate is `fixed`. The rest are `waived`, with the user's reason, or `deferred`. A recorded waiver is never raised again.
-7. **Design the target** for every picked candidate together, as a rethink at architecture level, following `.agents/skills/cruze-rethink/SKILL.md` with `kind=discovery` and `found_by=improve`:
-   - Amend `docs/architecture.md`: the module map and layers, the moved elements' `Module` and `File` facts, the `layers:` in `.cruze/config.yaml`, and a `D<n>` or an ADR for each structural decision. Change no requirement, scenario or port contract unless the user decided that in step 5.
-   - When a candidate changes an interface, such as a port or a module's public API, sketch two or three shapes as code, compare them, and recommend one before writing it.
-   - Before the rethink's walkthrough, run the design review from the roles skill on the diff, with `review=design`.
-   - Approve it as the rethink's architecture level says, with `--replan` for each built element that moves.
-8. **Schedule the moves.** Group the replanned elements into prefactor changes, as "A prefactor" in `.agents/skills/cruze-architect/tweak.md` describes, each sized as step 12 of `.agents/skills/cruze-architect/feature.md` says.
-   - Order them so each lands on its own and the code builds after every one: first the tests that record behaviour a module lacks, then one context or feature at a time.
-   - Put each on the roadmap, following `.agents/skills/cruze-roadmap/SKILL.md`. Run `cruze status --overlap --change <ref>`, and block it on every in-flight item it overlaps.
-   - Commit, with a message such as `docs: plan the <area> restructure`.
-
-Done when every candidate has a journaled disposition, the target architecture is approved, and every move is a prefactor change on the roadmap.
-
-## Rules
-
-- **Behaviour stays.** Wire formats, stored formats, messages, exit codes, and every approved scenario and its test stay as they are, unless the user decided otherwise in step 5.
-- **Small files stay.** Many small modules are the standard, so a candidate never merges files only to make a module deeper. Merging is a candidate when two modules own one responsibility, or one only forwards calls to another.
-- **Ports and adapters stay.** A restructure moves where the core, the ports and the adapters live, never whether a technology sits behind a port.
-- **The existing layout wins** until the user picks a candidate that changes it. Improve never restructures code the user didn't pick.
-
-## Next step
-
-`plan` for the first prefactor change. When the user picked nothing, `next`. Start it in a new session, so its context starts empty.

package/skills/land/SKILL.md

@@ -1,48 +0,0 @@
----
-name: cruze-land
-description: Lands a verified change by merging its deltas into the living docs with cruze land, updating the changelog, README and AGENTS.md, and committing or opening a pull request; also lands bug fixes from triage.
----
-
-# Land
-
-Land makes finished work part of the living model. `cruze land` merges the change's spec and architecture deltas into `docs/`, marks what it built, and archives the work when it is finished. This skill takes care of what people read around it: the changelog, the README and the pitfalls in `AGENTS.md`. Then it gets the work onto main.
-
-## Landing a change
-
-1. **Check it is ready.** Run `cruze next`. It must name `land` for this change. When it names `verify`, the change hasn't been accepted yet.
-2. **Bring in main.** Merge or rebase the branch onto an up-to-date main, and resolve conflicts.
-   - `journal.jsonl` files merge by keeping every line; `cruze init` sets that up in `.gitattributes`. When that file lacks the rule, keep both sides' lines.
-   - When an `approvals.json` conflicts, take main's version of it. Then run `cruze status`, and re-approve what it shows stale, as step 3 describes.
-   - Resolve code conflicts as usual, then run the full suite. When main came in without code conflicts, leave the full suite to CI.
-3. **Run `cruze status`.** When the change or its feature shows `upstream changed`, another branch landed changes to elements it cites. Then:
-   - Run `cruze diff <ref>` for each, show the user the diff of each changed element, and check that the change's code and tests still hold against it.
-   - When they still hold, re-approve the stale documents: the feature first, then the change. The change's verification carries over when its own design didn't change.
-   - When they don't hold, stop and offer `rethink`.
-4. **Run `cruze land`** and quote its report: what it merged, what is now built, and whether the work finished and was archived.
-   - A `merge-conflict` means someone changed an element this feature merged earlier. Stop and run `rethink`, which reconciles it.
-   - When the work finished, read the feature's row under `### Implemented` in `docs/vision.md` against its settled decisions and spec delta. When the summary no longer describes what landed, correct it with `cruze features update <slug> --summary <text>`.
-   - A `merge-invalid` means the merged docs, or the feature and changes being landed, wouldn't validate, such as a decision citing an ID the change removes. Nothing was written. Stop and run `rethink`.
-5. **Update the changelog.** Under `## [Unreleased]` in `CHANGELOG.md`, add one line per user-visible behaviour the change delivers, in the user's words, under `### Added`, `### Changed` or `### Removed`. Name the behaviour, not the code, including any rule a user can now run into that no scenario covers yet.
-6. **Update the README** when the change altered how someone installs, runs or uses the product. Run every command you add, to check it works.
-7. **Check the pitfalls.** Run `cruze journal list --event disposition --all --text | grep -i "<rubric item>"` for each rubric item this change's findings named, and `cruze journal list --event rethink --all` and `cruze journal list --event bug --all`; `--all` includes landed work, which the default leaves out. When findings under the same rubric item with the same root cause, or two defects with the same cause, have now happened twice, sort the lesson by what it is about:
-   - **This product:** its domain, its code's own conventions, or a tool or service only it uses, such as "an `ApiError` prints `<Code>: <message>`". Add one line under `## Known pitfalls` in `AGENTS.md` saying what to do instead.
-   - **Cruze's workflow, or practice that holds in any project:** how a delta, plan, task, test plan or review is written, or a rule of the language or its tooling, such as "a task lists the file that declares each new file". Record it with `cruze journal add lesson --set summary="<what happened twice>" --set instead="<what to do instead>" --set step=<the step that should have prevented it>`, and leave `AGENTS.md` alone: every session reads it, and `cruze feedback export` takes the lesson to Cruze, where the step itself gets fixed.
-
-   Keep `AGENTS.md` under one page. When the pitfalls outgrow it, propose to the user a `cruze check` rule or a knowledge-skill change for the oldest ones.
-8. **Commit** the land with a message such as `docs: land <change>`. `cruze land` keeps the Commands and Layout sections of `AGENTS.md` current, from `commands:` in `.cruze/config.yaml` and the built modules; when `commands:` is empty, the Commands section stays as it was.
-9. **Get it onto main.** Follow the project's convention in `AGENTS.md`. When it has none, ask the user whether they want pull requests or direct merges, and add their answer under `## Conventions`, such as "Changes land through pull requests." Open the pull request, or merge. CI must pass before the merge; when the project has no CI runner, run its steps locally with the project's commands.
-
-Done when the change is on main, or in an open pull request, and `cruze status` no longer lists it as in progress.
-
-## Landing a bug fix
-
-A fix from `triage` has no change folder, so `cruze land` doesn't run.
-
-1. Check that the fix commit has its failing-then-passing test, and that the full test suite, `cruze check` and `cruze trace --all` pass.
-2. Add a line under `### Fixed` in `CHANGELOG.md`: what the user saw, and that it is fixed.
-3. Check the pitfalls, as in step 7 above.
-4. Commit, then open the pull request or merge, as for a change.
-
-## Next step
-
-Once the work is on main, switch to an up-to-date main, run `cruze next` there, and name what it says. Start it in a new session, so its context starts empty. Before the merge, `cruze next` on the change's branch can name work that main doesn't hold yet. When a feature just finished and every roadmap item has landed, the next step is `roadmap`, to close the release.