@printpractical/cruze 0.0.1

package/skills/formats/templates/roadmap.md

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

package/skills/formats/templates/spec.md

@@ -0,0 +1,11 @@
+# <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

@@ -0,0 +1,46 @@
+---
+id: {{id}}
+title: {{title}}
+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/formats/templates/vision.md

@@ -0,0 +1,37 @@
+# {{project_name}}
+
+## Problem
+
+<The problem, in the user's words, in one short paragraph.>
+
+## Users
+
+- <Who, and in what situation they use it.>
+
+## Goals
+
+| ID | Goal | Measure |
+| --- | --- | --- |
+| GOAL-<name> | <What the product achieves for its users.> | <How you would know it's met.> |
+
+## Non-goals
+
+- <What the product deliberately doesn't do, and why.>
+
+## Constraints
+
+- <Platform, language, dependency, performance, security or legal limit.>
+
+<!-- cruze:managed -->
+## Feature map
+
+### Implemented
+
+| Feature | Release | Summary |
+| --- | --- | --- |
+
+### Future
+
+| Feature | Summary | Goals |
+| --- | --- | --- |
+<!-- /cruze:managed -->

package/skills/grilling/SKILL.md

@@ -0,0 +1,66 @@
+---
+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 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.
+---
+
+# 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 carries your recommended answer and the reason for it.
+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 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
+**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.
+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 7 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.
+- 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.
+
+## 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.
+
+## Recording
+
+- Record each decision as soon as it settles, not at the end.
+- 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/hexagonal-design/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: cruze-hexagonal-design
+description: The architecture standard for a Cruze project, covering hexagonal ports and adapters with domain-driven design, the owner of each rule, dependency direction, many small modules and composition. Use when designing or reviewing the architecture or an architecture delta, when placing a new element in the module map, when naming a port, adapter or module, when writing code that adds a type, file or import between modules, or when reviewing code for layering and structure.
+---
+
+# Hexagonal design
+
+The system is a hexagon. A domain and an application form the core, and adapters reach the outside world through ports. Every rule has one owner, dependencies point inward, and the module map in `docs/architecture.md` says where each owner lives. Designs, plans, code and reviews are all held to this standard.
+
+## Placing an owner
+
+Follow these steps whenever a design or a task introduces behaviour, such as a rule, a workflow, a mapping or an integration.
+
+1. Describe one representative operation in the caller's terms before choosing any structure. Done when you can say who calls, with what, and what they get back or see fail.
+2. Search the living docs and the code for an existing owner of the same behaviour. Reuse or extend it when it is correct. Done when you can name the owner, or can say that none exists.
+3. Name the owner by what it means, in the glossary's terms. A rule or invariant goes to a domain concept (`ENT`), a workflow to a use case (`UC`), a capability the application needs to a port (`PORT`), and a technology to an adapter (`ADP`).
+4. Place it in the module map. Its `Module` names a `MOD` whose `Layer` matches its role, and its `File` names the real path. Done when every new element has both, and its module's layer may import everything the element uses.
+5. Check the direction of every new dependency against the `RULE` elements and the `layers:` in `.cruze/config.yaml`. Done when no dependency points outward.
+6. Name the tests that will prove it, following `.agents/skills/cruze-behavioural-testing/SKILL.md`. When a plausible wrong outcome exists, make sure a scenario step rules it out, such as `AND the first hop is closed`.
+
+Stop when the behaviour and its boundaries are covered. A pure library needs no application layer or ports, so don't invent layers to complete the recipe.
+
+## Priorities
+
+When two rules pull apart, the earlier one wins. Prefer the simplest design that keeps all of them, and never simplify by merging responsibilities that mean different things.
+
+1. Domain rules and invariants have the right owner.
+2. Use-case boundaries are explicit.
+3. Dependencies point inward.
+4. Concepts and modules are cohesive.
+5. Each behaviour has one authoritative implementation.
+6. Infrastructure and runtime resources have clear owners.
+7. The design is simple within those boundaries.
+8. Runtime cost is low where the workload makes it matter.
+
+## Layers
+
+| Layer | Owns | May depend on |
+| --- | --- | --- |
+| `domain` | Concepts, state, rules, invariants and domain errors (`ENT`) | Domain code, the standard library, and approved libraries with no infrastructure in them, such as an error-derive crate |
+| `application` | Use cases (`UC`) and the ports they define (`PORT`) | The domain |
+| `adapter` | Inbound adapters that drive use cases, and outbound adapters that implement driven ports (`ADP`) | Application, domain and third-party libraries |
+| `composition` | Constructing adapters, injecting them, starting the runtime | Everything |
+
+`cruze check` enforces imports between the project's own layers. It allows every third-party import, so review checks that infrastructure libraries appear only in adapters.
+
+Layers are dependency boundaries, not runtime hops. A port can be a plain function call. Add a task, thread, channel or process only for a concrete ownership, concurrency, isolation or backpressure need, and read [runtime.md](runtime.md) first.
+
+### Domain
+
+- Identify domain logic by meaning, not complexity. A one-line rule about what the domain means still belongs in the domain.
+- Model each concept with the smallest building block that fits: value object, entity, aggregate, domain service or policy, domain error, or a domain event when the event means something to the domain. Each is an `ENT` with the matching `Kind`; domain errors live with the concept that raises them.
+- Prefer meaningful types over primitives when a value has identity, constraints or units, such as `DeviceName` rather than a string. Make invalid states unrepresentable where practical, and enforce each invariant in the type that owns it.
+- Keep aggregates small. Data being related is not a reason to group it.
+- The domain imports no transport, persistence, serialization format, framework, OS API, telemetry SDK, retry or connection handling. Pass information in rather than handing the domain an infrastructure handle.
+- Domain behaviour is synchronous unless asynchrony is part of the domain itself.
+
+### Application
+
+- Write one use case per independently meaningful operation, such as `OpenConsole` or `ListDevices`, not one large service.
+- A use case loads state through ports, calls domain behaviour, sequences effects, decides what a partial failure means, and translates port failures into use-case failures. The workflow stays visible in that one operation instead of spreading across pass-through services.
+- A domain rule stays in the domain even when only one use case uses it.
+- Add command buses, query buses or CQRS machinery only for a concrete need.
+
+### Ports
+
+- A driven port names a capability the application needs, not a technology: `DeviceCatalog`, `Clock` and `HopConnector`, not `TomlFile`, `TokioTimer` or `Ssh2Client`.
+- The application owns each port's contract and shapes it around what the core needs, never mirroring an SDK. Read [contracts.md](contracts.md) before writing a port's `Operations`.
+- A port that keeps a technology out of the core is justified with one adapter. An interface over an internal policy with one strategy is not.
+- Declare a driving port only when several inbound adapters share it or the application promises a stable contract. Otherwise an inbound adapter calls the use case directly.
+- Name each thing once. Never produce `Foo`, `FooPort`, `FooService` and `FooImpl` families.
+
+### Adapters
+
+- Inbound adapters (CLI, HTTP, RPC, message consumers) decode input, validate it at the protocol level, map it to use-case input, call the use case and map the result back. They stay thin, with no domain rules and no workflow.
+- Outbound adapters hold everything technology-specific: serialization, persistence layout, framing, retries and backoff, connections, SDK types and OS calls. They translate technology failures before those cross into the core.
+- An adapter never calls an unrelated adapter to get around the application.
+
+### Composition
+
+- One composition root constructs the concrete adapters and runtime resources, injects them through constructors or parameters, and starts the application.
+- Domain and application code never construct an adapter. There are no service locators, hidden lookups, mutable globals or implicit runtime dependencies.
+
+## Many small modules
+
+- Give each responsibility its own module, grouped by domain concept, with the hexagonal roles inside. A file may hold a few closely related types.
+- When a file passes its budget (`check:` in `.cruze/config.yaml`, enforced by `cruze check`) or gains a second responsibility, split it into a submodule named for what it owns.
+- Entry-point and namespace files, such as `main`, `lib.rs`, `mod.rs` and `index.ts`, hold only wiring and declarations.
+- Don't create generic modules such as `utils`, `helpers`, `common`, `services`, `models`, `types` or `manager`. Shared behaviour belongs with the concept that owns it.
+- Duplication is semantic. Two implementations of one rule are duplication even when the text differs, so consolidate them in the owner, not in a helper.
+- Structure follows the module map, never a per-language template. Write idiomatic code for the language and use its standard tooling. [languages/rust.md](languages/rust.md) and [languages/cpp.md](languages/cpp.md) add rules for those languages.
+- In an existing codebase, its established layout and naming win over these structure rules. Ownership and dependency direction still apply.
+
+## Representations and errors
+
+- Keep transport, application, domain and persistence representations separate when their meaning differs. Map them explicitly at the boundary, with one owner per mapping. Don't copy a type only to have one per layer.
+- Domain errors describe domain failures, application errors describe use-case failures, and adapter errors describe infrastructure failures. Translate at each boundary and never expose an SDK's error type through a port. Expected failures are values the caller handles, not crashes.
+
+## Warning signs
+
+Reconsider ownership when a design or a diff shows any of these:
+
+- An entry-point or namespace file gains behaviour.
+- A module gains a second responsibility you could describe on its own.
+- A handler holds a domain rule or orchestrates a workflow.
+- Domain code imports infrastructure or framework types, or technology starts shaping the domain model.
+- Application code constructs an adapter.
+- Logic that already exists is implemented again, or a change keeps a private copy of shared behaviour.
+- An interface mirrors its only implementation, or a chain of components only forwards calls.
+- Commodity infrastructure is being hand-written although a mature library does it. Follow `.agents/skills/cruze-research/SKILL.md`.
+
+These are review signals, not automatic failures. When one could be checked mechanically, propose a `cruze check` rule or a linter setting instead of repeating the finding.
+
+## Further reading
+
+- [contracts.md](contracts.md): writing a port's `Operations`, a public API, an IPC protocol or a stored format.
+- [runtime.md](runtime.md): concurrency, long-lived resources (connections, sessions, devices, subprocesses), state machines, cancellation or a hot path.
+- [fundamentals.md](fundamentals.md): choosing a data structure, a state representation or an abstraction mechanism; defining equality or ordering; bounding loops, retries and fan-out.
+- `.agents/skills/cruze-dependency-approval/SKILL.md`: before any design or code adds a dependency.

package/skills/hexagonal-design/contracts.md

@@ -0,0 +1,68 @@
+# Contracts and composition
+
+A contract tells a caller how to use a capability correctly without reading its implementation. A signature alone is not a contract. Apply this to the seams the work touches: ports, use cases other code calls, public APIs, IPC and stored formats. Don't specify every private helper or an imagined future caller.
+
+## Design from the caller
+
+1. Name the real callers: another module, a library user, a CLI user, a plugin, a peer process, or a reader of stored data. A language's `public` keyword doesn't make something a supported API.
+2. Write a short usage example in the caller's terms: the outcome, the collaborators needed, valid inputs, and how the caller handles each result and failure.
+3. Decide what the caller must not need to know. Expose a capability, not a concrete SDK's operations or your internal data layout.
+4. State the obligations from the table below that apply, including what is deliberately left unspecified. Ask the user about any uncertain obligation that matters instead of inventing a guarantee.
+5. Show the composition: the entry point, the domain decisions, the collaborators, the effects and who owns each resource. Pick the language mechanism (trait, interface, function type) only after this.
+
+A concrete function or type can be a fine seam. Use a port to keep a technology out of the core, even with one adapter. Don't put an interface on every internal operation, and don't turn a module into a plugin system for callers that don't exist.
+
+## Obligations
+
+In a `PORT` element, each item under `Operations` gives the signature in the project's language, then the rows below that apply.
+
+| Concern | What the caller can rely on |
+| --- | --- |
+| Provides and requires | Operations offered, capabilities consumed, preconditions |
+| Inputs and state | Valid values, invariants, allowed call sequences, where input is trusted |
+| Results and effects | What success means, when effects become visible or durable |
+| Failure | Which failures the caller can tell apart, partial progress, the state left behind, whether a retry is safe |
+| Ownership | What is borrowed, copied or retained, and who releases it |
+| Execution | Ordering, concurrency, reentrancy, deadlines and resource limits |
+| Lifecycle | Startup, cancellation, completion and shutdown duties |
+| Compatibility | Source, binary, wire, stored-data or behavioural promises actually made |
+| Freedom | Ordering, representation or diagnostics the caller must not assume |
+
+Add compatibility machinery (versioning, extension points, binary stability) only for a concrete reason: existing callers, stored data, peers that upgrade independently, or an explicit requirement. Name the supported callers or versions when it matters.
+
+A contract lives in one place: the `PORT` or `UC` element in `docs/architecture.md`, a schema, or a header. Deltas replace that element's body rather than writing a second competing definition.
+
+## Compose guarantees, not just types
+
+Suppose an operation saves a document and then notifies subscribers. It must decide what a failed notification means after a successful save. Matching types don't make the pair atomic. The use case owns that outcome and any compensating step; adapters implement the capabilities and translate technical failures.
+
+- Name the owner of each decision, effect, transaction and resource.
+- Check that what one component guarantees meets what the next one requires.
+- Keep business sequencing and recovery in the use case. The composition root wires components and decides no business policy.
+- Avoid ambient transactions, service locators, implicit subscriptions, mutable globals, and background work that callers can discover only by reading code.
+- Separate what a component owns from what it borrows. A reusable component never shuts down its caller's runtime or closes a borrowed connection.
+- Treat retry permission, deadlines and partial success as behaviour the caller sees, not details an adapter picks.
+
+A `FLOW` element shows the composition for a key scenario. Its `Failure paths` say what each failure leaves behind.
+
+## IPC and stored formats
+
+When a seam crosses processes or persists data, decide the protocol behaviour that applies:
+
+- Framing, encoding, field meanings, numeric ranges, and size limits.
+- Handling of unknown, missing or duplicate fields, unknown variants, malformed data and trailing input. A serialization library's defaults are not a policy.
+- Correlation, ordering, concurrent requests, reconnects and backpressure.
+- Delivery, retries, duplicate handling, and how long an idempotency guarantee lasts.
+- Whether cancellation stops the local wait, asks the peer to cancel, or confirms termination, and what effects may remain after a timeout or disconnect.
+- Compatibility, only for the peer versions or stored formats you must support. In-memory layout is not a wire format.
+
+A peer may commit a request and then lose the reply, so a timeout doesn't prove a rollback. Decide whether the outcome can be queried, a retry is safe, or the caller sees an unknown outcome. A request ID alone doesn't give exactly-once execution.
+
+## Evidence that a contract holds
+
+- Take expected values from worked examples, independent of the implementation's algorithm.
+- Cover a representative success, invalid input, and the important failures and state histories. Assert effects the caller can observe, not private call chains.
+- Run one set of contract tests against the fake and every real adapter. Evidence from a fake alone says nothing about the real dependency.
+- Where a format or API is promised to outside callers, compile or run a representative caller against it.
+
+Ask two questions of every contract test. What plausible wrong implementation would fail it? Would a different correct implementation pass it without copying these internals?

package/skills/hexagonal-design/fundamentals.md

@@ -0,0 +1,50 @@
+# Engineering fundamentals
+
+Use these to test material engineering choices in a design, a plan, code or a review. Keep the search bounded by the work at hand: the seams it touches, its scenarios, and the failure and workload risks that are credible. Stop when those have decisions backed by evidence.
+
+## Workload before structure
+
+- Before choosing a data structure, describe the operations that dominate the real workload: input size and its upper bound, the mix of lookups, inserts, deletes and scans, ordering and duplicate rules, how it's mutated, concurrency, latency target and memory budget.
+- State the expected, worst-case or amortized cost that matters, and the skewed or hostile inputs that change it.
+- Enforce bounds at trust boundaries, before allocation, indexing, recursion, conversion and arithmetic. Account for overflow, truncation, empty input and limits across concurrent work.
+- Choose by the operations you need: a contiguous sequence for ordered scans and indexing, a hash map or set for keyed lookup, an ordered map for sorted traversal and ranges, a heap for repeated minimum or maximum, a queue for FIFO work. A small bounded scan beats an index that costs more to maintain than it saves.
+
+## States and transitions
+
+- Represent a closed set of states with the language's strongest practical type: an enum, sum type or tagged union. Keep each state's data on its variant, instead of coordinating booleans, nulls and loose fields.
+- Define the legal transitions in one visible operation or table. Construction and deserialization validate the state, mutation rejects illegal transitions, and exhaustive matching forces a decision when a state is added.
+- When states cross a stored, wire or public boundary, change their serialized names, values or unknown-state handling only on purpose, with the migration decided.
+
+## The cheapest abstraction that works
+
+- Start concrete when there is one behaviour and one representation. Extract a function when only an operation varies. Use an enum for a closed set of variants, generics for compile-time variation, an interface or trait for open substitution, and dynamic dispatch only when runtime variety requires it.
+- Name the alternatives and their costs: a direct collaborator or an interface, a closed enum or plugin dispatch, a generic algorithm or two concrete functions.
+- Add an abstraction for a current variation point, boundary, invariant or test seam, not for an imagined second implementation. Equally, merge duplicated domain rules that must change together.
+
+## Standard machinery first
+
+- Use the language's standard algorithms, collections, parsing and resource-management constructs when their contracts fit.
+- Check the real contract: ordering and stability, comparator requirements, invalidation on mutation, allocation, errors, partial results and complexity.
+- Write a direct loop when it makes stateful control flow clearer, or when the standard operation can't meet a demonstrated bound. Say why, and test the edge cases.
+
+## Equality, hashing and ordering
+
+- Define domain identity before implementing equality. Equal values hash equally, and an ordering agrees with equality wherever an ordered collection relies on it.
+- Keep keys stable while they sit in a hash or ordered collection. Never base identity on mutable, transient, locale-dependent or process-specific data unless that is the contract.
+- Decide the edge cases the language won't decide for you: case and Unicode normalization, `NaN` and signed zero, absent values, identity versus value equality, and tie-breaks.
+
+## Termination, fan-out and resources
+
+- Every loop, recursion, retry, poll, queue, stream and background task has a termination or cancellation condition. Where progress isn't guaranteed, give a maximum count, depth or duration.
+- Bound fan-out and buffering by the workload and the capacity downstream: concurrency limits, queue sizes, backpressure, overload behaviour and who sees the failure.
+- Pair every acquired resource with an owner and a release path across success, error, cancellation and partial initialization. That includes memory, file descriptors, sockets, locks, transactions, temporary files, subscriptions, timers, tasks and external quotas.
+
+## Duplicated literals
+
+- Give a literal one home when it encodes a domain fact or must change in step with others: states, event kinds, protocol fields, units, limits, error codes, paths, header names and serialization keys. That home is a typed value, a named constant, a schema or a config entry, at the boundary that owns it.
+- Leave incidental repetition alone: log messages, test descriptions, fixture text and one-off explanations are clearer in place.
+- Before extracting a literal, name the future change the extraction keeps consistent.
+
+## Findings
+
+Each material finding gives the evidence, the workload or invariant affected, and a concrete alternative. "Use a deque, because removing from the front of this array is linear at the stated queue bound" is a finding. "Improve performance" is not.

package/skills/hexagonal-design/languages/cpp.md

@@ -0,0 +1,37 @@
+# C++
+
+These add to the hexagonal design rules for C++ projects. The module map decides the layout; this file never does.
+
+## Files
+
+- Organize headers and sources by the concept they own. Public headers sit under `include/<project>/` only when an outside caller needs them; a type private to one source file has no header.
+- `main.cpp` is the composition root: it constructs adapters and use cases, injects dependencies and starts the application.
+- Don't create `Domain.hpp`, `Services.cpp`, `Models.hpp` or `Utils.cpp` catch-alls.
+- Domain headers expose no application, adapter, framework, OS or third-party infrastructure types.
+
+## Modelling
+
+- Use modern C++ with value semantics, `enum class` for closed sets, small domain classes and value objects with validating constructors.
+- Use free functions or concrete classes when behaviour needs no polymorphism. Don't create `IFoo`, `Foo` and `FooImpl` without a substitution purpose.
+- Prefer composition over deep inheritance.
+
+## Ports and ownership
+
+- Ports are narrow abstract interfaces owned by the application, used where runtime substitution is useful. They never mirror a third-party SDK.
+- Use RAII for every resource. Pass lightweight owned objects by value, transferred exclusive ownership as `std::unique_ptr`, and shared ownership as `std::shared_ptr` only when ownership really is shared. Required dependencies owned elsewhere are references. No raw owning pointers or manual `new` and `delete`.
+- Inject dependencies explicitly and wire them in `main.cpp`.
+
+## Errors
+
+- Represent expected domain and application failures explicitly: `std::expected` from C++23, or a small result type the project owns on older standards. Exceptions are not a substitute for modelling failures.
+- Catch third-party exceptions in the adapter and translate them. Never let them cross a port.
+
+## Concurrency
+
+- Use threads, executors or queues only when they buy real runtime value, and make shutdown explicit.
+- Keep shared mutable state and lock scope small. Avoid needless queues, context switches, allocations and copies on hot paths.
+
+## Dependencies and tooling
+
+- Prefer the standard library, then mature libraries, subject to `.agents/skills/cruze-dependency-approval/SKILL.md`. Weigh portability and build-system impact.
+- Use the project's build system and its own tooling. Format with `clang-format` and lint with `clang-tidy` when the project configures them.

package/skills/hexagonal-design/languages/rust.md

@@ -0,0 +1,40 @@
+# Rust
+
+These add to the hexagonal design rules for Rust projects. The module map decides the layout; this file never does.
+
+## Modules
+
+- `main.rs` is the composition root and stays thin. `lib.rs` and every `mod.rs` hold only module declarations, visibility and deliberate re-exports, and `lib.rs` exposes the use cases, ports and domain types that tests drive.
+- Name modules for the concept they own. Don't put domain definitions in a `mod.rs`, and don't create `domain.rs`, `services.rs`, `models.rs` or `utils.rs` catch-alls.
+- Where the layer rules need a hard boundary, a Cargo workspace with one crate per layer makes the compiler enforce it. The walking-skeleton change decides this.
+
+## Modelling
+
+- Use structs for entities and aggregates, enums for closed alternatives and states, and newtypes for primitives with meaning (`struct DeviceName(String)`).
+- Use concrete functions and types for single-strategy behaviour. Use traits for ports and for strategies that really vary. A struct doesn't need a trait of its own.
+- Prefer APIs that keep invariants: validating constructors (`TryFrom`, `parse`), private fields, and no public setters that skip a rule.
+
+## Ports and injection
+
+- Ports are traits owned by the application layer. Adapter types never appear in their signatures.
+- Inject through constructors or parameters. Prefer generics (static dispatch). Use `Box<dyn Trait>` or `Arc<dyn Trait>` only when you need to choose at runtime or store mixed implementations.
+
+## Errors
+
+- Define structured error enums with `thiserror` for the domain, each use case and each adapter, and convert between them at the boundaries.
+- `anyhow` belongs only in the composition root and binaries, where no caller inspects the error. Never return it from a port or a domain function.
+- No `unwrap`, `expect` or `panic!` for conditions that can happen in production. Tests may use them.
+
+## Async and concurrency
+
+- Use Tokio when the project needs async. Keep the domain synchronous.
+- Call async functions directly. Spawn a task only when it owns a resource, runs concurrently, handles events or isolates failure, and give every long-lived task an explicit shutdown.
+- Prefer ownership and borrowing over shared synchronization. Use a channel when one task owning the state makes things simpler, and a `Mutex` when shared state is simpler. Don't build an actor only to avoid a lock.
+
+## Dependencies and tooling
+
+- Common choices, still subject to `.agents/skills/cruze-dependency-approval/SKILL.md`: `serde` at serialization boundaries (never as a reason to couple domain types to a format), `tracing` for instrumentation, `clap` for CLI parsing, `thiserror` for errors.
+- Add dependencies with `cargo add`, so the version comes from the registry.
+- No `unsafe` unless the user approves it or an unavoidable low-level boundary needs it, with a `// SAFETY:` comment giving the reason.
+- Format with `cargo fmt`, lint with `cargo clippy -- -D warnings`, and test with `cargo test`.
+- Behaviour, contract and smoke tests live in `tests/` and reach the code through the library's public API. They share fakes through `tests/support/mod.rs`, which each test file declares with `mod support;`. Domain tests sit in a `#[cfg(test)] mod tests` beside the code and need no fakes.

package/skills/hexagonal-design/runtime.md

@@ -0,0 +1,48 @@
+# Runtime ownership
+
+Runtime architecture decides how work executes and who owns resources. It is independent of the hexagonal layers: a port is not a thread, and a use case is not a task. Record runtime decisions in an `XC-concurrency` element under the architecture's cross-cutting concerns, and in the `Operations` contracts of the ports involved.
+
+## Choose the execution model
+
+Pick the simplest model that meets the ownership, concurrency, lifecycle, isolation and performance needs: direct calls, async calls, tasks, an event loop, actors, a worker pool, dedicated threads, state machines or a pipeline. State the concrete need before adding a task, channel, queue or scheduler hop.
+
+Stateless transformation and ordinary domain computation get no task or actor of their own.
+
+## Resource owners
+
+Every long-lived, mutable, stateful or exclusive resource has one named owner. This covers sockets, connections, sessions, hardware devices, subprocesses, mutable runtime state and shared caches.
+
+- Say how the resource is created, accessed, mutated, failed and shut down, and what final cleanup happens.
+- For background work, say how it is cancelled and whether shutdown drains, rejects or abandons work in flight.
+- A dedicated task or component can own a resource when that buys exclusive ownership, serialized mutation, event handling, lifecycle control or failure isolation. A lock is simpler for plain shared in-process state. Message passing is not always better.
+- Bound every queue, and say what happens on overload.
+- For repeated operations on a resource, use `registry -> resolved handle -> resource`, with the registry named for what it holds, such as `SessionRegistry`. The registry discovers, creates, registers and hands out handles. Routine work goes through the handle, not back through the registry.
+
+## State machines
+
+- Use an explicit state machine when the valid operations depend on the current state. Explicit states and transitions replace combinations of boolean flags.
+- State with domain meaning, such as a console session being `opening`, `open` or `closed`, belongs in the domain as an `ENT` with a `States` fact.
+- State that exists because of a protocol, transport, OS, hardware interface or runtime lifecycle belongs to the adapter or runtime component that owns that concern.
+
+## Failures, retries and cancellation
+
+- Technical retry and backoff live in an outbound adapter. Whether an operation is safe to repeat, and the use case's deadline, are part of the core contract.
+- Never retry non-idempotent work blindly, and never stack retries at several layers.
+- Stopping a wait, dropping a future, requesting cancellation, ending a task and cancelling remotely are different events. Say which one an operation promises, what effects may remain, and how completion is observed.
+- When a caller needs a guaranteed or fallible finish, give it an explicit `close` or `shutdown` operation. Destruction alone can't report failure.
+
+## Cross-cutting infrastructure
+
+Centralize repeated tracing and context propagation, authentication metadata, instrumentation, protocol error mapping and serialization conventions in middleware, wrappers or a dedicated adapter component. Record each as an `XC` element. Business policy, such as an authorization decision, stays in the core even when it recurs.
+
+## Performance
+
+- On a hot path, look for avoidable allocations, copies, serialization, queue hops, scheduler transitions, repeated lookups and repeated policy evaluation.
+- Resolve an expensive decision once, for as long as its result stays valid, and say what invalidates it.
+- Measure the real workload before adding complex optimization. Clean layering doesn't justify runtime overhead, and speculative performance doesn't justify erasing an ownership boundary.
+
+## Tests these decisions need
+
+- A device session owned by one task: test acquisition failure, overload, cancellation and cleanup.
+- A state machine: test each rejected transition and the behaviour of each terminal state.
+- A cached handle: test what happens after the resource is removed or replaced.

package/skills/land/SKILL.md

@@ -0,0 +1,43 @@
+---
+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 tests.
+3. **Run `cruze status`.** When the change or its feature shows `upstream changed`, another branch landed changes to elements it cites. Then:
+   - 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.
+   - A `merge-invalid` means the merged docs wouldn't validate. 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`, `cruze journal list --event rethink` and `cruze journal list --event bug`. When findings under the same rubric item with the same root cause, or two defects with the same cause, have now happened twice, add one line under `## Known pitfalls` in `AGENTS.md` saying what to do instead. 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. 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.