@nusoft/nuos-build-catalogue 0.25.0 → 0.27.0

package/templates/protocols/build-wu.md

@@ -4,7 +4,7 @@ You are the **swarm coordinator** for a project using the NuOS Build Method cata
 
 **You orchestrate. You do not implement directly.** Your value is routing — picking the right agents, the right models, the right order — and aggregating their outputs into a coherent next action for the operator.
 
-**The operator is most likely a domain expert, not a software engineer.** Plain English in everything you surface back to them. Translate agent jargon into outcomes.
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset) for what you surface back to the operator. The orchestration itself — agents, order, gates — does not change with mode.
 
 ---
 
@@ -60,15 +60,9 @@ Skip steps when context allows — implementation-only WUs skip the architect; b
 
 ### Design-it-twice (required for every architect pass)
 
-The architect step is **not a single-pass activity**. Before the architect's brief is written and before the coder is spawned, the architect must:
+Before the architect's brief lands and the coder spawns, the architect must produce **two structurally different designs** (not syntactic variants — e.g. state machine vs event sourcing, sync vs async, logic-in-module vs logic-in-caller), write both into the WU notes with tradeoffs, then pick one with a stated reason.
 
-1. **Produce two fundamentally different designs** for the contract surface — not variations of the same approach, but structurally different choices. Examples of structural difference: one design uses a state machine, the other uses event sourcing; one design puts logic in the module, the other pushes it to the caller; one design is synchronous, the other asynchronous.
-2. **Write both designs into the WU notes**, including: what each optimises for, what it trades away, what breaks if you choose it.
-3. **Pick one and state why** — specifically, what the winning design handles better than the losing design doesn't.
-
-Only after this comparison is documented should the coder be spawned. The spawn prompt to the architect must explicitly request two designs: *"Produce two structurally different designs for [contract surface]. Write both into the WU notes with their tradeoffs. Then commit to one with a stated reason."*
-
-A single-design architect pass is drift — the failure mode where an agent satisfices on the first plausible idea. The design-it-twice step is what catches blind spots before they reach code. Skipping it saves 10 minutes and costs hours in rework.
+Spawn prompt to the architect must request this explicitly: *"Produce two structurally different designs for [contract surface]. Write both into WU notes with tradeoffs. Then commit to one with a stated reason."* A single-design pass is drift — the satisficing failure mode design-it-twice exists to catch.
 
 ## Step 4 — Spawn the agents
 
@@ -88,13 +82,13 @@ Use Claude Code's **Task tool**. Each spawn names the agent (`subagent_type`), t
 
 Omit `null` fields. If `techStack.defined` is `false` or the section is absent, note it in the swarm audit entry and suggest the operator define the stack (`/plan-orientation` or edit `methodfile.json` directly) before the next swarm run — agents generating code without a known stack default to generic patterns that often need rework.
 
-**Vitest pre-flight (JS/TS projects only).** Before spawning the coder, check `methodfile.json`'s `testing` block. If `testing.framework` is `vitest` and `testing.enforced` is `true`, verify the implementation repo has vitest installed and a `vitest.config.ts` (or `.js`/`.mts`) present. If either is missing, before any agent runs:
+**Vitest pre-flight (JS/TS projects).** If `methodfile.json` has `testing.framework: "vitest"` with `testing.enforced: true`, and the implementation repo lacks either vitest or a `vitest.config.ts`/`.js`/`.mts`:
 
-1. Surface to the operator in one line: *"Vitest is the declared test runner but isn't wired up in the implementation repo yet. I'll install it (`npm i -D vitest @vitest/coverage-v8`) and drop a minimal `vitest.config.ts` before the coder starts. OK?"*
-2. On confirmation: (a) run `npm i -D vitest @vitest/coverage-v8` in the implementation repo; (b) copy the harness's `vitest.config.ts` template into the repo root and `example.test.ts` into `tests/example.test.ts` (create the directory if missing). The templates ship inside the installed harness package at `node_modules/@nusoft/nuos-build-catalogue/templates/testing/` — read them from there; if the harness is being run from a checkout, they're at `<harness-repo>/templates/testing/`; (c) add a `"test": "vitest run"` script to the implementation repo's `package.json` if absent; (d) run `npx vitest run` once to confirm the wiring works.
-3. Record the setup in the swarm audit entry under a `## Setup` section so the next swarm doesn't repeat the check.
+1. Ask the operator in one line: *"Vitest is declared but not wired up. Install + drop a minimal config before the coder starts?"*
+2. On confirmation: (a) `npm i -D vitest @vitest/coverage-v8`; (b) copy `vitest.config.ts` to repo root and `example.test.ts` to `tests/` from the harness's `templates/testing/` (resolved via `node_modules/@nusoft/nuos-build-catalogue/templates/testing/`, or `<harness-repo>/templates/testing/` for checkouts); (c) add `"test": "vitest run"` to `package.json` if absent; (d) run `npx vitest run` to confirm.
+3. Record under `## Setup` in the swarm audit entry.
 
-If `testing.framework` is not vitest (e.g. the project is Python), skip this pre-flight — the existing "match the project's idiom" rule applies.
+If `testing.framework` is not vitest, skip — match the project's existing idiom.
 
 **Spawn in parallel where possible.** If two agents can work independently (e.g. tester writing tests while reviewer reads design), spawn them in the same message. Sequential when an agent's output is the next agent's input (architect → coder).
 
@@ -193,57 +187,13 @@ Every decision made by any agent during the swarm MUST land in the catalogue bef
 - **Never run the swarm to completion in the background.** Surface progress, ask for confirmation on important choices, treat the operator as the decider on anything non-routine.
 - **Never use Opus for every agent.** The default routing in `methodfile.json` exists for a reason — architect + debugger use Opus; coder/tester/reviewer use Sonnet. Override only when an agent genuinely needs more reasoning and you can justify it.
 
-## Cost guidance
-
-A typical full-feature swarm spawning architect (Opus, ~30 min) + coder (Sonnet, ~1 hr) + tester (Sonnet, ~30 min) + reviewer (Sonnet, ~15 min) consumes substantially less of the operator's coding-tool plan budget than running the same work as a continuous Opus conversation. The 80/20 split — heavy reasoning for design and debugging only, lighter models for implementation and verification — is the lever. If a single work unit's swarm is consuming an unusual share of the day's plan budget, surface that to the operator before continuing; the WU is probably bigger than scoped.
-
 ---
 
 ## Verification gates
 
-To prevent a swarm from spiralling into runaway cost or quality drift, observe these gates. They are protocol-level discipline, not enforced by tooling — your job as coordinator is to honour them.
-
-### Retry cap on REQUEST CHANGES loops
-
-If the reviewer returns REQUEST CHANGES, re-spawn the coder ONCE to address the findings, then run the tester + reviewer cycle a second time. If the third reviewer pass still returns REQUEST CHANGES:
-
-- STOP the swarm
-- Escalate to the operator with a plain-English summary: *"After three attempts the reviewer still flags X. Likely either the design is wrong or the spec is under-specified. How would you like to proceed?"*
-
-Don't loop indefinitely. A third reviewer rejection is a signal — the work unit's design, contract, or acceptance criteria need clarification, not more code.
-
-### Time ceiling per agent
-
-If a single agent's run is taking substantially longer than its rough budget (architect >1 hr, coder >2 hrs, tester >1 hr, reviewer >30 min):
-
-- Don't kill the agent — that loses its in-flight work
-- Surface the duration to the operator
-- Ask whether to continue, redirect, or escalate to a different agent (e.g. if coder is stuck, route to debugger)
-
-### Architectural drift detection
-
-If the coder or tester surfaces a design choice that wasn't in the architect's brief (or no architect was spawned because this was meant to be implementation-only):
-
-- STOP the implementation
-- Escalate to the architect agent with the surfaced choice
-- Wait for the architect's brief or decision file before re-spawning the coder
-
-This is the load-bearing gate. Coders making design calls inline is the failure mode that produces drift between intent and implementation; the swarm pattern's whole value is preventing it.
-
-### Coherence check at midpoint
-
-For full-feature swarms (architect → coder → tester → reviewer), after the coder finishes and before the tester spawns, do a quick check:
-
-- Is what the coder produced visibly consistent with what the architect specified?
-- Are the file paths / module boundaries the architect named present in the coder's output?
-- Are the contracts the architect filed still the ones the coder is consuming?
-
-If anything looks misaligned, escalate to the operator before spending more tokens on the tester.
-
-### Vitest test gate (JS/TS projects)
-
-Step 5.5 above defines the gate in full. Restated as a verification rule: a JS/TS work unit cannot promote with reviewer APPROVE unless `vitest run` exits 0 AND every source file the WU touched has at least one test file referencing it. The reviewer runs the gate; the coordinator enforces the outcome. This is the load-bearing gate for code quality — drift here means shipping untested behaviour.
-
-### Recording gate triggers
+Protocol-level discipline (not tooling-enforced). Honour these alongside the retry/test gates already specified in Step 5 / 5.5.
 
-Every gate trigger gets recorded in the swarm audit entry under a `## Gate triggers` section. Even if the swarm continues, the trigger is logged. This builds the audit trail for the operator to review when reasoning about whether the swarm pattern is paying off.
+- **Time ceiling per agent.** If a run exceeds its rough budget (architect >1h, coder >2h, tester >1h, reviewer >30m), don't kill the agent (loses in-flight work) — surface the duration and ask whether to continue, redirect, or escalate (e.g. coder stuck → debugger).
+- **Architectural drift.** If the coder or tester surfaces a design choice not in the architect's brief, STOP, route to the architect for a decision before re-spawning. Coders making design calls inline is the failure mode the swarm exists to prevent.
+- **Midpoint coherence check** (full-feature swarms). After coder finishes, before tester spawns: are file paths and contracts the architect named present in the coder's output? If misaligned, escalate before spending tester tokens.
+- **Record gate triggers.** Every trigger goes in the audit entry under `## Gate triggers`, even if the swarm continued — builds the audit trail.

package/templates/protocols/end-of-session.md

@@ -2,7 +2,7 @@
 
 You are ending a session on a project that uses the **NuOS Build Method catalogue**. Your job is to capture everything that happened, update the project's snapshot, write a session log, and commit. **Without this, work is lost. The whole catalogue is built on the assumption that every period of work gets captured before it closes.**
 
-**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Use the operator's words where possible; translate technical jargon into domain language when writing things down.
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset).
 
 ---
 
@@ -67,7 +67,13 @@ Create `docs/build/sessions/YYYY-MM-DD-short-slug.md`. The entry includes:
 
 Add a row to `sessions/_index.md`.
 
-### 8. Verify nothing is lost
+### 8. Regenerate HTML companion views (if any visual register changed)
+
+If anything in `ui-ux/`, `design-system/`, `maps/`, or `architecture/` was edited this session, run `nuos-catalogue render` to refresh the companion HTML views (`_view.html` in each of those directories). These are generated artefacts — the markdown stays canonical — but they need to stay in sync so the operator's next review opens current views. Stage the refreshed `_view.html` files for the commit alongside the markdown.
+
+If none of those registers changed, skip this step.
+
+### 9. Verify nothing is lost
 
 Before committing, scan:
 
@@ -78,7 +84,7 @@ Before committing, scan:
 - Cross-references resolve (no dead links)
 - Dates are right
 
-### 9. Commit
+### 10. Commit
 
 Single commit. Message format:
 

package/templates/protocols/persona-new.md

@@ -2,7 +2,7 @@
 
 You are filing a new **persona** for a project that uses the **NuOS Build Method catalogue**. A persona is one specific person the project serves — not a market segment, not a demographic. One person with a name, a situation, and a reason to need what's being built.
 
-**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Walk the operator through the persona in conversation — don't read out a form.
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset). The seven dimensions are filed in full regardless of mode.
 
 ---
 

package/templates/protocols/plan-architecture.md

@@ -9,16 +9,18 @@ By the end of this session the operator should have:
 - Decisions filed for every non-obvious technology or structural choice
 - The Phase B row in STATE.md's Planning progress table flipped to `✅ complete`
 
-The whole session takes about 60–90 minutes. **The operator is most likely a domain expert, not a software engineer.** Plain English throughout. A "module" is just a major piece with one clear responsibility. A "contract" is the plain-English promise that piece makes to everything else.
+The whole session takes about 60–90 minutes (longer in coaching mode, shorter in developer mode).
+
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset).
 
 ---
 
 ## How to lead this conversation
 
-- **Lead the operator; don't quiz them.** Walk them through naming each piece, one at a time.
-- **Write each module and contract as the conversation produces it.** Don't accumulate and write at the end.
-- **If a technology choice surfaces, file a decision immediately.** Saying "we'll use PostgreSQL" in conversation and not filing it is drift.
-- **Refer to the horizon map.** The modules are the mechanism that gets to the destination — check every module earns its place by pointing at something in the map.
+- Walk through naming pieces one at a time; don't quiz.
+- File each module + contract as the conversation produces it.
+- Tech choice surfacing in conversation → file a decision *now* (drift kills the catalogue).
+- Check every module earns its place by pointing at something in the horizon map.
 
 ---
 
@@ -69,25 +71,9 @@ Scan the conversation for anything the operator wasn't sure about. File each as
 
 ## Step 5 — Close (2 min)
 
-Update STATE.md:
-- Phase B row → `✅ complete (YYYY-MM-DD)`
-- Phase C row → `🟡 next`
-- Refresh "Last updated"
-
-Tell the operator:
-
-> "You've got the architecture substrate:
->
-> - **[N] modules** in `docs/build/architecture/` — the major pieces
-> - **[N] contracts** in `docs/build/contracts/` — what each piece promises
-> - **[N] decisions** in `docs/build/decisions/` — the choices already made
-> - **STATE.md** updated
->
-> Next session: **Phase C — UI/UX + Design System** (~60–90 min). We'll name every screen and surface the user touches, then build the complete design language: colours, type, spacing, components, patterns, voice, and accessibility. By the end, the design system is real — no placeholders.
->
-> Run `/end-of-session` to commit everything."
-
-Then run `/end-of-session`.
+Update STATE.md: Phase B → `✅ complete (YYYY-MM-DD)`, Phase C → `🟡 next`, refresh "Last updated".
+
+Summarise to the operator: [N] modules + contracts filed, [N] decisions, STATE.md updated. Next session is **Phase C — UI/UX + Design System** (~60–90 min) producing a real design system, no placeholders. Then run `/end-of-session`.
 
 ---
 

package/templates/protocols/plan-initial-wu.md

@@ -11,7 +11,9 @@ By the end of this session:
 - STATE.md names the first work unit as `🟡 in flight`
 - `methodfile.json`'s `planning.completedAt` is set to today's date
 
-This session takes about 60 minutes. **The operator is most likely a domain expert, not a software engineer.** Plain English throughout.
+This session takes about 60 minutes (longer in coaching mode, shorter in developer mode).
+
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset).
 
 ---
 
@@ -67,31 +69,9 @@ The review typically takes 10–20 minutes. It is the difference between a catal
 
 ## Step 5 — Close
 
-Update STATE.md:
-- Phase E row → `✅ complete (YYYY-MM-DD)` (only after `plan-review` has completed)
-- "Active work unit" → the first `🟡 in flight` work unit handle and title
-- "What is currently in flight" → one sentence describing what the swarm will tackle first
-- Refresh "Last updated"
-
-Update `methodfile.json`:
-- Set `planning.completedAt` to today's date (ISO format: YYYY-MM-DD)
-
-Tell the operator:
-
-> "Planning is done. You have:
->
-> - **[N] work units** filed and ordered — [first WU title] is first
-> - **The planning arc is complete**
->
-> Every session from here follows the same loop:
->
-> `/start-of-session` → work → `/end-of-session`
->
-> When you're ready to build, run `/build-wu [handle]` — the swarm coordinator reads the work unit, designs the approach (twice — two options, then a pick), spawns the right agents, and runs it to completion.
->
-> Run `/end-of-session` to commit everything and close the planning arc."
-
-Then run `/end-of-session`.
+Update STATE.md (only after `plan-review` has completed): Phase E → `✅ complete (YYYY-MM-DD)`; "Active work unit" → first `🟡 in flight` WU handle + title; "What is currently in flight" → one sentence on what the swarm tackles first; refresh "Last updated". Set `methodfile.json` → `planning.completedAt` to today's ISO date.
+
+Tell the operator: planning arc complete, [N] work units filed and ordered, [first WU title] is first. From here the loop is `/start-of-session` → work → `/end-of-session`; when ready to build, `/build-wu <handle>` runs the swarm. Then run `/end-of-session`.
 
 ---
 

package/templates/protocols/plan-maps.md

@@ -9,7 +9,9 @@ By the end of this session:
 - Each phase in Map 2 has a clear acceptance criterion and a verification gate
 - The Phase D row in STATE.md is flipped to `✅ complete`
 
-This session takes about 45 minutes. **The operator is most likely a domain expert, not a software engineer.** Plain English throughout.
+This session takes about 45 minutes (longer in coaching mode, shorter in developer mode).
+
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset).
 
 ---
 
@@ -57,23 +59,9 @@ Write Map 3 to `docs/build/maps/03-near-term.md` using `docs/build/maps/03-templ
 
 ## Step 4 — Close (5 min)
 
-Update STATE.md:
-- Phase D row → `✅ complete (YYYY-MM-DD)`
-- Phase E row → `🟡 next`
-- Refresh "Last updated"
-
-Tell the operator:
-
-> "The maps are in:
->
-> - **Map 2** — the full journey from here to done, with acceptance criteria and verification gates per stage
-> - **Map 3** — what's happening right now and what's immediately next
->
-> Next session: **Phase E — Initial Work Units** (~60 min). We'll file the first 5–10 concrete things to build, ordered by dependency. After that, the planning arc is done and the swarm can start.
->
-> Run `/end-of-session` to commit everything."
+Update STATE.md: Phase D → `✅ complete (YYYY-MM-DD)`, Phase E → `🟡 next`, refresh "Last updated".
 
-Then run `/end-of-session`.
+Summarise: Map 2 (full journey with per-stage gates) and Map 3 (near-term plan) filed. Next session is **Phase E — Initial Work Units** (~60 min); after that the planning arc closes and the swarm can start. Then run `/end-of-session`.
 
 ---
 

package/templates/protocols/plan-orientation.md

@@ -8,20 +8,22 @@ You are running **Phase A of the planning arc** for a project that just adopted
 - Initial open questions captured for anything they couldn't yet answer
 - The Phase A row in STATE.md's Planning progress table flipped to `✅ complete`
 
-The whole session should take about 30 minutes. **The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Never use a term like "work unit" or "contract" without defining it the first time. Read [`docs/build/GLOSSARY.md`](../../docs/build/GLOSSARY.md) once before you start so your vocabulary matches the catalogue's.
+The whole session takes about 30 minutes (longer in coaching mode, shorter in developer mode).
+
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset). If `null`, send the operator back to `/start-of-session` first to pick.
+
+Read [`docs/build/GLOSSARY.md`](../../docs/build/GLOSSARY.md) once before you start so your vocabulary matches the catalogue's.
 
 ---
 
 ## How to lead this conversation
 
-- **Lead the operator. Don't quiz them.** They aren't here to fill in a form; you're walking them through producing something they can use.
-- **Translate the answers into catalogue artefacts as you go.** They don't need to know the artefact shape — you do.
-- **One question at a time.** If they answer two at once, capture both and move on.
-- **Use their words wherever possible.** Translate jargon out, not in.
-- **If they don't know something, file an open question and move on.** Don't stall.
-- **Save as you go.** Don't accumulate answers and write everything at the end — write each artefact when the conversation produces it.
-
-**Drift discipline:** every decision made in conversation must be filed before the session ends. If the operator says "let's go with X" and X is an architectural commitment, file a decision file in `docs/build/decisions/` *now*, not later. Decisions made in chat that don't reach the catalogue are drift, and drift is the failure mode that makes the catalogue worthless.
+- Lead the operator; don't quiz them. Walk them through producing something they can use.
+- Translate answers into catalogue artefacts as you go — they don't need to know the artefact shape.
+- One question at a time. If they answer two at once, capture both and move on.
+- Use their words. Translate jargon out, not in.
+- "I don't know" → file an open question; move on. Don't stall.
+- Save each artefact when the conversation produces it; don't batch-write at the end. Any in-conversation decision (architectural commitment, tech choice) gets filed to `docs/build/decisions/` *now* — drift kills the catalogue.
 
 ---
 
@@ -122,27 +124,9 @@ Pass over the conversation looking for anything the operator wasn't sure about.
 
 ## Step 7 — Close (2 min)
 
-Update STATE.md:
-
-- Set the **Planning progress** Phase A row to `✅ complete (YYYY-MM-DD)`
-- Set the Phase B row to `🟡 next` (so the next `/start-of-session` knows where to route)
-- Refresh the "Last updated" date
-
-Then tell the operator what they now have:
-
-> "You've got your first catalogue substrate:
->
-> - **Tech stack** defined in `methodfile.json` — (or flagged as an open question if not yet settled)
-> - **[N] personas** in `docs/build/personas/` — these anchor every later decision
-> - **Map 1** at `docs/build/maps/01-the-horizon.md` — the whole-project picture
-> - **[N] open questions** in `docs/build/open-questions/` — these are what we'll resolve as planning continues
-> - **STATE.md** updated to reflect Phase A is done
->
-> Next session, we move to **Phase B — Architecture & Contracts** (about 60-90 minutes). We'll name the major pieces of your project and what each one provides to the others.
->
-> For now, run `/end-of-session` to commit everything. The catalogue's search index will refresh in the background, and next session can pick up from here."
+Update STATE.md: Phase A row → `✅ complete (YYYY-MM-DD)`; Phase B row → `🟡 next`; refresh "Last updated".
 
-Then run `/end-of-session` to close out.
+Summarise to the operator what they now have — tech stack, [N] personas, Map 1, [N] open questions, STATE.md updated — and tell them the next session is **Phase B — Architecture & Contracts** (~60-90 min). Then run `/end-of-session`.
 
 ---
 

package/templates/protocols/plan-review.md

@@ -4,6 +4,8 @@ You are running the **planning arc review** — a full end-to-end audit of every
 
 This runs automatically at the end of Phase E. It can also be invoked at any point mid-project (e.g. after a significant pivot, after adding a new persona, or when something feels off) with `/plan-review`.
 
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset). The audit is exhaustive regardless of mode; only how findings are reported back changes.
+
 By the end of this protocol:
 
 - Every gap, ambiguity, inconsistency, and optimisation opportunity in the planning catalogue has been surfaced

package/templates/protocols/plan-uiux.md

@@ -12,7 +12,9 @@ By the end of this session:
 - Decisions are filed for every non-obvious design choice
 - The Phase C row in STATE.md is flipped to `✅ complete`
 
-This session takes 60–90 minutes. **The design system is not a nice-to-have.** Every agent that ships UI code — coder, reviewer, tester — reads the design system to know what "correct" looks like. A placeholder design system means every agent invents its own answer and every piece of UI needs a rework pass.
+This session takes 60–90 minutes (longer in coaching mode, shorter in developer mode). **The design system is not a nice-to-have.** Every agent that ships UI code — coder, reviewer, tester — reads it to know what "correct" looks like. A placeholder design system means every agent invents its own answer and every piece of UI needs a rework pass.
+
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset).
 
 ---
 
@@ -72,72 +74,38 @@ For each surface in the list, ask in conversation:
 
 ## Step 4 — Extract the design language (20–25 min)
 
-When all surfaces are filed, say:
-
-> "Now let's build the design language that governs all of them. This is where everything you've described gets translated into a shared set of values — colours, type, spacing — that we can hand to every agent so they're all building the same thing."
-
-Walk through the following as conversation. Make provisional decisions wherever the operator isn't sure, and file them as decisions they can supersede.
-
-### Colour tokens
+Transition to the operator: now the design language that governs every surface — values handed to every agent so they all build the same thing. Make provisional decisions when the operator isn't sure; file them as decisions they can supersede.
 
-Ask:
-> "What's the character of this product? Serious and professional, playful and bright, calm and considered, bold and high-energy? How do you want people to feel when they use it?"
+Walk through each token group below as conversation — open with the character/feel question, then capture the values. **Every token gets a real value, not a placeholder.**
 
-Establish and write **real hex or hsl values** for:
-- **Brand primary** — the main action colour (buttons, links, active states)
-- **Brand secondary** — accent colour if needed
+### Colour — `docs/build/design-system/tokens-colour.md`
+Open: *"What's the character of this product — serious/professional, playful, calm, bold? How should people feel using it?"* Then capture, with real hex/hsl values:
+- **Brand primary** (main action colour) + **brand secondary** if needed
 - **Neutral scale** — 5–7 steps: background, surface, border, muted text, body text, heading
-- **Semantic colours** — success, warning, error, info (four colours, real values)
-
-Write to `docs/build/design-system/tokens-colour.md`. Show the operator the file before moving on.
-
-### Type scale
-
-Ask:
-> "What's the reading experience? Are people scanning data or reading long prose? Mobile-first or desktop-first?"
-
-Establish:
-- **Font family** — system stack, a specific Google Font, or custom (real name, not "sans-serif")
-- **Size scale** — xs through 3xl (real rem values, not "small/medium/large")
-- **Weight variants** — regular / medium / semibold / bold (real numeric weights)
-- **Line height** — compact for data, comfortable for prose (real values)
-
-Write to `docs/build/design-system/tokens-typography.md`.
-
-### Spacing & layout
-
-Ask:
-> "How dense is this? Tight information display, or generous whitespace?"
-
-Establish:
-- **Spacing scale** — a consistent step sequence (e.g. 4/8/12/16/20/24/32/40/48/64 px — real values)
-- **Max content width** if applicable
-- **Grid or column structure** if the product uses one
-
-Write to `docs/build/design-system/tokens-spacing.md`.
-
-### Radius & elevation
-
-Ask:
-> "Sharp corners or rounded? Flat design or layered with shadows and depth?"
-
-Establish:
-- **Border radius** — none / sm / md / lg / full with real px values
-- **Shadow scale** — if the product uses depth, 2–4 named shadow levels with real values
-
-Write to `docs/build/design-system/tokens-radius-elevation.md`.
-
-### Motion
-
-Ask:
-> "Does this product have meaningful transitions — things appearing, sliding, fading? Or is it mostly static?"
-
-Establish:
-- **Transition durations** — instant / fast / base / slow (real ms values)
-- **Easing curves** — real CSS easing values
-- **Reduced-motion policy** — what happens when `prefers-reduced-motion` is set
-
-Write to `docs/build/design-system/tokens-motion.md`.
+- **Semantic** — success, warning, error, info
+
+### Typography — `docs/build/design-system/tokens-typography.md`
+Open: *"Scanning data or reading prose? Mobile-first or desktop-first?"* Capture:
+- **Font family** (real name — system stack, specific Google Font, or custom)
+- **Size scale** xs → 3xl (real rem values)
+- **Weight variants** (real numeric weights)
+- **Line height** (compact for data, comfortable for prose)
+
+### Spacing — `docs/build/design-system/tokens-spacing.md`
+Open: *"Tight density or generous whitespace?"* Capture:
+- **Spacing scale** (real step sequence, e.g. 4/8/12/16/20/24/32/40/48/64 px)
+- **Max content width** + **grid/column structure** if used
+
+### Radius & elevation — `docs/build/design-system/tokens-radius-elevation.md`
+Open: *"Sharp corners or rounded? Flat or layered?"* Capture:
+- **Border radius** (none / sm / md / lg / full — real px values)
+- **Shadow scale** if depth is used (2–4 named levels, real values)
+
+### Motion — `docs/build/design-system/tokens-motion.md`
+Open: *"Meaningful transitions or mostly static?"* Capture:
+- **Transition durations** instant / fast / base / slow (real ms values)
+- **Easing curves** (real CSS easing values)
+- **Reduced-motion policy** for `prefers-reduced-motion`
 
 ## Step 5 — File the components (15–20 min)
 
@@ -213,28 +181,9 @@ If anything is still a placeholder, resolve it now. This check is non-negotiable
 
 ## Step 9 — Close
 
-Update STATE.md:
-- Phase C row → `✅ complete (YYYY-MM-DD)`
-- Phase D row → `🟡 next`
-- Refresh "Last updated"
-
-Tell the operator:
-
-> "The design system is done:
->
-> - **[N] surfaces** in `docs/build/ui-ux/` — every screen defined
-> - **Colour, type, spacing, radius, motion tokens** — real values, ready to use
-> - **[N] components** in `docs/build/design-system/components/` — the building blocks
-> - **[N] patterns** in `docs/build/design-system/patterns/` — recurring compositions
-> - **Voice + accessibility** committed
->
-> Every agent that builds UI reads this design system. The reviewer will reject output that doesn't conform. That's the mechanism: consistent product instead of random output.
->
-> Next session: **Phase D — Maps** (~45 min). We'll map the journey from here to done.
->
-> Run `/end-of-session` to commit everything."
-
-Then run `/end-of-session`.
+Update STATE.md: Phase C → `✅ complete (YYYY-MM-DD)`, Phase D → `🟡 next`, refresh "Last updated".
+
+Summarise to the operator: [N] surfaces, real token values (colour, type, spacing, radius, motion), [N] components, [N] patterns, voice + accessibility committed. Every UI-building agent reads this; the reviewer rejects non-conforming output. Next session is **Phase D — Maps** (~45 min). Then run `/end-of-session`.
 
 ---
 

package/templates/protocols/start-of-session.md

@@ -2,7 +2,19 @@
 
 You are starting a session on a project that uses the **NuOS Build Method catalogue**. Your job is to read where the project is right now and tell the operator in plain English, then propose the next action and wait for confirmation.
 
-**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. If you must use a term like "work unit" or "persona", spell it out the first time per session.
+## Step 0 — Operator mode
+
+Read `methodfile.json`'s `operator.mode`:
+
+- Set to `"coaching"` / `"standard"` / `"developer"` → adopt that tone per `docs/build/OPERATOR-MODES.md`. Skip to Step 1.
+- `null` → run the picker below before doing anything else.
+
+**Picker (first run only).** Tell the operator this is a one-time setup, then offer the three modes in your own words from `OPERATOR-MODES.md`:
+- **Coaching** — new to software development; learning the process while building.
+- **Standard** — domain expert; comfortable with files and instructions; not a working dev. *(Most common — recommend if they're unsure.)*
+- **Developer** — experienced engineer; wants terse protocols.
+
+On their answer: write the choice to `methodfile.json` as `operator.mode` (string) and stamp `operator.modeSelectedAt` with today's ISO date. Confirm in one line: *"Saved. Change any time with `nuos-catalogue mode <name>`."* Continue to Step 1.
 
 ---
 

package/templates/protocols/wu-new.md

@@ -2,7 +2,7 @@
 
 You are filing a new **work unit** for a project that uses the **NuOS Build Method catalogue**. A work unit is one concrete thing the project will build. The catalogue's value compounds as work units accumulate notes — every session adds to the record of what was attempted, what worked, what didn't, what was learned.
 
-**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Use their words. Define any term you use that isn't obvious from context.
+**Mode:** honour `methodfile.json`'s `operator.mode` per `docs/build/OPERATOR-MODES.md` (default `standard` if unset).
 
 ---
 

package/templates/starter-kit/CLAUDE.md

@@ -6,50 +6,22 @@
 
 {{PROJECT_NAME}} is {{PROJECT_TAGLINE}}.
 
-This project runs **the NuOS Build Method** — see [the canonical strategic note](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) for the discipline, and [the harness contract](https://github.com/DarrenJCoxon/nuos/blob/main/docs/contracts/method-harness.md) for how the catalogue plugs into NuOS when wired.
+This project runs **the NuOS Build Method**. The discipline lives in [`THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md); the harness contract is in [`method-harness.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/contracts/method-harness.md).
 
-## At the start of every session — always
+## Session bookends
 
-Run the start-of-session protocol. The single command is:
+- **Start every session** with `/start-of-session` — follow [docs/build/START-OF-SESSION.md](docs/build/START-OF-SESSION.md) exactly.
+- **End every session** with `/end-of-session` — follow [docs/build/END-OF-SESSION.md](docs/build/END-OF-SESSION.md) exactly. **Work that isn't written down is work that's lost.**
 
-> "Run start-of-session"
+## Maps hold the operational plan
 
-When asked to do this, follow [docs/build/START-OF-SESSION.md](docs/build/START-OF-SESSION.md) exactly. It will:
+`docs/build/maps/` is the canonical operational plan. **Story-level detail lives in maps**, not in fragmented planning docs. Each phase step has an acceptance criterion and a verification gate (a specific file/grep/test that proves the step is done). After STATE.md, identify the active map's active step and **run the gate before doing more work**.
 
-1. Read [docs/build/STATE.md](docs/build/STATE.md) — the always-current project snapshot
-2. Read the most recent entry in [docs/build/sessions/](docs/build/sessions/)
-3. Identify the active work unit and read it in full
-4. Surface any blocking open questions or risks
-5. Confirm the state and propose the next concrete action
+If you find yourself writing *"likely"*, *"presumably"*, *"should be"* — stop. The hedge word indicates a skipped verification. Run the gate, replace the hedge with the result, then continue.
 
-## At the end of every session — always
+## Design it twice
 
-Run the end-of-session protocol. The single command is:
-
-> "Run end-of-session"
-
-When asked to do this, follow [docs/build/END-OF-SESSION.md](docs/build/END-OF-SESSION.md) exactly. It will:
-
-1. Update the active work unit's notes with what was done
-2. Update [docs/build/STATE.md](docs/build/STATE.md) to reflect current state
-3. Write a new session log entry in [docs/build/sessions/](docs/build/sessions/)
-4. Update any decisions, open questions, or risks that emerged
-5. Update the relevant `_index.md` files
-6. Verify nothing is lost
-
-If a session ends without the end-of-session protocol being run, work may be lost. Always run it.
-
-## The canonical operational plan lives in maps
-
-The `docs/build/maps/` directory holds the canonical operational plan for this project. **Story-level detail lives in maps**, not in fragmented planning docs. Each phase step in a map has an acceptance criterion and a verification gate (a specific file/grep/test in the target repo that proves the step is done).
-
-When a session starts, after reading STATE.md, identify the active map and read the active phase step. The verification gate names exactly what to run to know whether the step is complete. **Run the gate before doing more work.**
-
-If you find yourself writing *"likely"*, *"presumably"*, *"should be"* in code or planning text, **stop**. The hedge word indicates a verification step was skipped. Run the gate, replace the hedge with the result, then continue.
-
-**Before generating non-trivial implementation, produce at least two fundamentally different designs, evaluate each, then pick.** This is Ousterhout's "design it twice" applied to agent-led work. Agents satisfice on the first plausible idea; the structured comparison is what catches blind spots before they reach code. Record the alternatives in the WU's notes (or a D-NNN decision file).
-
-These are two of the five agentic-age patterns codified in [`THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) §post-Phase-3 epistemic discipline. The discipline isn't borrowed from agile; it's shaped for the specific failure modes of LLM-driven building.
+Before generating non-trivial implementation, produce at least two fundamentally different designs, evaluate each, then pick. Agents satisfice on the first plausible idea; the structured comparison catches blind spots before they reach code. Record the alternatives in the WU's notes or a D-NNN decision file.
 
 ## The single rule