@printpractical/cruze 0.0.11 → 0.0.12

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.11 is the eleventh preview. A change no longer loops between build, verify and rethink over edge cases: a code review finding blocks only when ordinary use reaches a failure that loses data, crashes, hangs or spins, a verify after a send-back reviews only the code changed since, and a missing limit, message or error case is settled as a detail inside build or verify. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.12 is the twelfth preview. Designs are easier to see and keep lean: the walkthrough shows the types each caller passes and the decisions you didn't make, reviews cut fields nothing reads, questions use plain words and explain a part before asking about it, and a rethink designs for the features ahead. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.11/printpractical-cruze-0.0.11.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.12/printpractical-cruze-0.0.12.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.11
+npm install -g --install-links github:PrintPractical/cruze#v0.0.12
 ```
 
 ### 2. Set up a repository
@@ -61,7 +61,7 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.11/printpractical-cruze-0.0.11.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.12/printpractical-cruze-0.0.12.tgz
 ```
 
 `init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:

package/dist/domain/skill_budget.js

@@ -11,7 +11,7 @@ export const MAX_FILE_WORDS = 2100;
  * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
  * is the maintainer's decision, with the reason in the commit that raises it.
  */
-export const BUNDLE_WORD_BUDGET = 44800;
+export const BUNDLE_WORD_BUDGET = 45450;
 
 /** Data the CLI reads or renders, rather than instructions an agent reads. */
 const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;

package/package.json

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

package/skills/architect/walkthrough.md

@@ -12,9 +12,9 @@ Write it in the glossary's terms, as what callers can do and what happens when t
 2. **What it touches.** Each new external system, and each new dependency named with its purpose and the approval behind it. Also each component you chose to build yourself, with the reason.
 3. **What it looks like.** Illustrated as `.agents/skills/cruze-grilling/illustrating.md` says:
    - A plain-text diagram of the main scenario crossing the design: the inbound adapter, the use case, the domain elements and the ports, marking what is new.
-   - A code sketch, in the project's language, of what the new and changed elements look like: the port operations and use case signatures with their errors, the main entity, and the call an inbound adapter makes.
+   - A code sketch, in the project's language, of what the new and changed elements look like: the port operations and use case signatures with their errors, the main entity, and the call each kind of caller makes, a component in the same process included, with the types it passes as they will be declared. One project approved orchestrators that passed JSON values inside the daemon, which no sketch showed, and rejected it at build a day later.
 4. **The slices.** The changes in order, one line each, saying what each delivers and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
-5. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode.
+5. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode. Then, one line each, every decision the design takes that no answer of the user's settled, carried-over ones included, and every value the system's own components pass each other untyped or encoded, such as a JSON value. Approval rests on this overview: one feature's documents ran to 25,000 words.
 
 ## The documents
 

package/skills/grilling/SKILL.md

@@ -20,7 +20,7 @@ Interview the user until you both understand the design the same way. Decisions
 ## A round
 
 ````markdown
-Where we are: architect for 2026-09-25-open-console, round 2. Settled: D1 (a console session may cross jump hosts), D2 (credentials come from the vault).
+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.
@@ -45,6 +45,8 @@ Recommended: named hosts, because the lab config already shares two jump hosts a
 - 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
 

package/skills/grilling/illustrating.md

@@ -4,8 +4,9 @@ The user decides from what they can picture. A question about a port's errors or
 
 ## Reading cold
 
-- 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: D2 (one stream per session), D4 (events carry revisions).`
-- Say what an ID means in plain words the first time a message uses it, such as `SCN-configuration.reject-taken-priority (a second set asking for a priority already taken is refused)`.
+- 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
@@ -22,7 +23,7 @@ Show each option, side by side, with the form that fits what the question decide
 | 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.
+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
 

package/skills/realign/notes/0.0.12.md

@@ -0,0 +1,31 @@
+# Realign notes: 0.0.12
+
+## New work only
+
+### walkthrough-types: The walkthrough shows the types each caller passes, and the decisions the user didn't make
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/walkthrough.md`, "The overview", items 3 and 5
+
+### design-needed-fields: A field serves a need only when something reads it
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, item 3
+
+### design-typed-inside: Values passed inside the system are typed
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/design-rubric.md`, item 13
+
+### grilling-shrink: Doubt gets an option that shrinks the design, and a growing answer gets a simpler alternative
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/SKILL.md`, "A round"
+
+### plain-questions: Questions name things in plain words, with an ID only beside them, and illustrate pick-one options too
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/illustrating.md`, "Reading cold" and "Choosing the illustration"
+
+### grilling-context: Questions explain the part of the design they ask about before asking
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-grilling/illustrating.md`, "Reading cold"
+
+### rethink-forward: A feature or architecture rethink designs for the features ahead, as architect does
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/SKILL.md`, "Steps", steps 3 and 4

package/skills/realign/notes.md

@@ -14,6 +14,7 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 - [0.0.9](notes/0.0.9.md)
 - [0.0.10](notes/0.0.10.md)
 - [0.0.11](notes/0.0.11.md)
+- [0.0.12](notes/0.0.12.md)
 
 ## Format
 

package/skills/rethink/SKILL.md

@@ -15,8 +15,8 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
    - **Discovery:** it is new information no step could have had.
 
    Tell the user the level and the kind in one line, and let them correct it.
-3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md`. At feature or architecture level, also read `.agents/skills/cruze-hexagonal-design/SKILL.md`. Also read the format reference for the document you will amend: `.agents/skills/cruze-formats/reference/architecture.md`, `specs.md`, `work-items.md` or `durable-docs.md`.
-4. **Amend that level,** following the level's section in [levels.md](levels.md). Settle any decision the amendment needs with the user, and record it as that level records decisions.
+3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md`. At feature or architecture level, also read `.agents/skills/cruze-hexagonal-design/SKILL.md`, `.agents/skills/cruze-research/SKILL.md` and `.agents/skills/cruze-dependency-approval/SKILL.md`. Also read the format reference for the document you will amend: `.agents/skills/cruze-formats/reference/architecture.md`, `specs.md`, `work-items.md` or `durable-docs.md`.
+4. **Amend that level,** following the level's section in [levels.md](levels.md). Settle any decision the amendment needs with the user, and record it as that level records decisions. At feature level and above, design the amendment as architect designs a feature, following the Rules in `.agents/skills/cruze-architect/SKILL.md`: read the vision's principles and capabilities that must stay possible, the feature map and the roadmap, and design for the features ahead while building only what the work in hand needs. Each option you offer says how the features ahead would use it, which capabilities it keeps open, and what it does to a running device or service, such as across a restart, an upgrade or a downgrade. In one architecture rethink, the user had to ask whether an option would still work for the apps the product plans to host, and point out that refusing to start after a downgrade could brick a router.
 5. **Keep completed work.** A ticked task stays ticked unless the amendment changes its owner, its files, or what it proves. Reopen each task that changed with `cruze task reopen T<n> "<what changed>"`. Its commits stay in history, and build redoes the task.
 6. **Re-approve what went stale.** Run `cruze status` and work from the top down. The amended document comes first, and the user approves it as its level says. Then take each feature or change it lists as `upstream changed`, whose own text you didn't edit:
    - Run `cruze diff <ref>`. It shows each changed element's approved and current text, and whether the work's delta needs a rebase. Check the work still holds against it. When it doesn't, amend it too, and the user approves it as an amended document.

package/skills/rethink/levels.md

@@ -4,7 +4,7 @@
 
 A detail settles a limit, timeout, buffer size, message or error case that an element of the work in progress doesn't give, with no new element, port operation or dependency, and no change to an approved scenario. Build and verify run it without leaving their step: one message length settled as a full rethink took 75 minutes.
 
-1. Ask the user, recommending a value and saying what the code then does.
+1. Ask the user, recommending a value and showing what the code then does, as `.agents/skills/cruze-grilling/illustrating.md` says.
 2. Amend the element where it lives, in the delta or `docs/architecture.md`, adding at most one failure scenario and its test plan row for a new error case. Run `cruze validate`; done when it reports no errors.
 3. Commit the text with the code and its test, naming the task. Tasks stay ticked.
 4. The user approves the amended document. Re-stamp what went stale, and record the rethink with `level=detail`, as the skill's steps 6 and 7 say.

package/skills/roles/design-rubric.md

@@ -4,7 +4,7 @@ The design reviewer's rubric for a design: the architecture at project scope, or
 
 1. **Behaviour.** Every requirement has at least one scenario. Every scenario has concrete values, one WHEN, and a THEN a person could check. Failure behaviour the user will meet has its own scenario.
 2. **Seams.** Every scenario can be driven through a use case, or through an inbound adapter when the outcome is what that adapter shows. Every driven port the use case needs can be faked.
-3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities. The layout is the one normal for the kind of system and the language, and every layer, module, package or target split beyond a context's `core` and its adapters has a recorded reason. Every element, fact and value serves a requirement in scope, or a `Future` fact the feature map or a `LATER` capability calls for. Anything reserved for a need nobody stated is a finding, and so is anything built, rather than left room for, for a `LATER` capability.
+3. **Placement.** Every new or changed element with code has a `Module` whose `Layer` fits its role and a `File` with a real path. No generic modules, and no file is likely to hold two responsibilities. The layout is the one normal for the kind of system and the language, and every layer, module, package or target split beyond a context's `core` and its adapters has a recorded reason. Every element, fact and value serves a requirement in scope, or a `Future` fact the feature map or a `LATER` capability calls for. Anything reserved for a need nobody stated is a finding, and so is anything built, rather than left room for, for a `LATER` capability. A field or value serves a need only when a person, a tool or another element reads it in a scenario or a `LATER` row; a scenario that only checks it is written doesn't count. A design carried over from an earlier build or a seed is checked the same way: one project built a clock port and timestamp parsing for a status field nothing read.
 4. **Direction.** Every dependency points inward and is allowed by the `RULE` elements and the `layers:` in `.cruze/config.yaml`.
 5. **Adopt or build.** Every component that isn't domain logic has an adopt-or-build decision with a reason, and every new dependency is named with the features the design uses. Every type, trait, macro, framework or tool the design names from outside the project comes from a dependency and feature the design approves, declared by each crate, package or target that uses it, test support included, and allowed by the import rules in `XC` and the `layers:` in `.cruze/config.yaml`. A choice whose reason is avoiding a dependency, a crate or a feature, where the idiomatic design needs one, is a concern: name the idiomatic design. Every command the design spells out, such as a CI step, is spelled as that version's `--help` or source shows it. A claim the design relies on that the research left unverified is a blocker.
 6. **Contracts.** Every new or changed port's `Operations` state what each operation guarantees, how it fails, and who owns cleanup. Check each use case and each port operation for the values build would otherwise have to pick: a named error for every failure a caller can meet, where a panic, an `expect` or "caller error" counts as missing; a number for every timeout, limit, buffer and poll interval; what a caller observes after each state transition, and what happens to queued or in-flight work at it; and one owner for every message a scenario quotes. Each one missing is a blocker: two projects settled 35 of them during build, as deviations.
@@ -38,3 +38,4 @@ The design reviewer's rubric for a design: the architecture at project scope, or
    - each settled decision of the design that states long-term intent, such as "eventually" or "later": it is a `LATER` row in the vision, since the decision is archived when the work lands.
 
    A departure from a principle with no amendment, a `likely` capability closed off, or a design resting on an open hand-off row, is a blocker; a `possible` one closed off is a concern.
+13. **Typed inside.** Each value one of the system's own components passes another in the same process has its own type, as the standards' domain rules say. A serialization format between them, such as a JSON value, a raw frame or an untyped map, is a concern even when an ADR gives the reason, so the walkthrough brings it to the user.

package/src/domain/skill_budget.ts

@@ -11,7 +11,7 @@ export const MAX_FILE_WORDS = 2100;
  * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
  * is the maintainer's decision, with the reason in the commit that raises it.
  */
-export const BUNDLE_WORD_BUDGET = 44800;
+export const BUNDLE_WORD_BUDGET = 45450;
 
 /** Data the CLI reads or renders, rather than instructions an agent reads. */
 const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;