@nusoft/nuos-build-catalogue 0.22.0 → 0.24.0

package/dist/commands/init.js

@@ -39,6 +39,11 @@ const PROTOCOL_FILES = [
     'wu-new.md',
     'persona-new.md',
     'plan-orientation.md',
+    'plan-architecture.md',
+    'plan-uiux.md',
+    'plan-maps.md',
+    'plan-initial-wu.md',
+    'plan-review.md',
     'build-wu.md',
 ];
 /**
@@ -52,6 +57,11 @@ const PROTOCOL_DESCRIPTIONS = {
     'wu-new': 'File a new work unit through a guided plain-English conversation',
     'persona-new': 'File a new persona by walking the seven dimensions conversationally',
     'plan-orientation': 'Phase A of planning — project description, tech stack, personas, the horizon map',
+    'plan-architecture': 'Phase B of planning — name the major modules and define what each one provides',
+    'plan-uiux': 'Phase C of planning — enumerate every surface and build the complete design system',
+    'plan-maps': 'Phase D of planning — map the journey from here to done with phases and near-term plan',
+    'plan-initial-wu': 'Phase E of planning — file the first 5–10 work units ordered by dependency',
+    'plan-review': 'End-to-end planning review — surfaces gaps, inconsistencies, and optimisations before building starts',
     'build-wu': 'Orchestrate a swarm of agents to build one work unit end-to-end',
 };
 const TOOLS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {

package/templates/protocols/build-wu.md

@@ -51,13 +51,25 @@ For the classified pattern, list the subtasks each agent will handle. Write this
 
 A typical full-feature decomposition:
 
-1. **Architect**: design the contract surface this WU produces; file a decision if a non-obvious choice exists; write the design brief in WU notes
+1. **Architect**: design the contract surface this WU produces — **using design-it-twice** (see below); file a decision for the chosen approach; write the design brief in WU notes
 2. **Coder**: implement against architect's brief; matches existing code idioms; smallest change that satisfies acceptance criteria
 3. **Tester**: writes one test per acceptance criterion + failure-path tests; runs them
 4. **Reviewer**: reads coder + tester output against spec, design system, decisions; flags drift
 
 Skip steps when context allows — implementation-only WUs skip the architect; bug-fix WUs use debugger instead of architect.
 
+### 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:
+
+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.
+
 ## Step 4 — Spawn the agents
 
 Use Claude Code's **Task tool**. Each spawn names the agent (`subagent_type`), the model (from `methodfile.json`'s `swarm.models` block — usually leave as default), and the precise input.

package/templates/protocols/plan-architecture.md

@@ -0,0 +1,99 @@
+# plan-architecture
+
+You are running **Phase B of the planning arc** — Architecture & Contracts. Phase A gave you a project description, tech stack, personas, and a horizon map. Phase B names the major pieces of the system and defines what each one promises to the others.
+
+By the end of this session the operator should have:
+
+- 3–7 module files in `docs/build/architecture/`
+- One contract file per module in `docs/build/contracts/`
+- 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.
+
+---
+
+## 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.
+
+---
+
+## Step 1 — Read the context (2 min)
+
+Before starting, read:
+- `docs/build/maps/01-the-horizon.md` — the destination
+- `docs/build/personas/` — who the system serves
+- `methodfile.json`'s `techStack` section — if `defined: true`, modules must be grounded in the actual stack
+
+Then open with:
+
+> "We've got the project oriented — you've described what you're building, who it's for, and where it's heading. Now let's name the major pieces. Not the code, not the screens — just the chunks of functionality that each have one clear job. Most projects have between three and seven. Some examples: 'the thing that handles payments', 'the thing that manages user accounts', 'the thing that sends notifications'. We'll name them in your words, and I'll write each one down."
+
+## Step 2 — Name the modules (30–45 min)
+
+Ask:
+
+> "What are the major pieces of this system? Take your time. Start with the one that feels most central."
+
+**For each module, ask three follow-up questions** (in conversation, not as a list):
+
+1. *"What does it do — in one sentence?"*
+2. *"What does it need from the rest of the system to do its job?"* (dependencies)
+3. *"What does it produce or make available for everything else?"* (what it provides)
+
+When you have the shape of a module, **write it immediately** as `docs/build/architecture/<module-name>.md` and its contract as `docs/build/contracts/<module-name>.md`. Use the templates at `docs/build/architecture/module-template.md` and `docs/build/contracts/contract-template.md`. Show the file path to the operator as you create it.
+
+After each module, ask: *"Is there another major piece, or does that cover the main shape of the system?"*
+
+**Completeness check:** when the operator seems done, look at the horizon map. Is there anything the map needs that no module provides? Surface it:
+
+> "Looking at the horizon map — [X] is supposed to happen, but none of the modules we've named clearly owns it. Is that covered by one of these, or is there a piece we've missed?"
+
+**Tech choices:** if the operator implies a technology choice ("it stores user data", "it sends emails", "it calls the payment API"), treat it as a potential decision. Ask: *"You mentioned [X] — have you decided how you'll handle that? If so, let's file it as a decision now."* File it as `docs/build/decisions/D-NNN-<slug>.md`.
+
+## Step 3 — Review the module map (5 min)
+
+When all modules are named, surface the full picture:
+
+> "Here's what we've got: [list modules with one-sentence summaries]. The dependency flow reads: [describe how they connect]. Does that match how you think about the system?"
+
+Adjust anything the operator wants to rename, merge, or split. Re-file as needed.
+
+## Step 4 — Open questions (5 min)
+
+Scan the conversation for anything the operator wasn't sure about. File each as Q-NNN in `docs/build/open-questions/`. Flag which ones affect Phase C (UI/UX) — those surface assumptions about the user-facing layer that Phase C will resolve.
+
+## 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`.
+
+---
+
+## What to do if it goes off-track
+
+- **Operator wants to define screens already:** redirect. *"We'll get to the surfaces in Phase C. Right now we're just naming the pieces that do the work."*
+- **Modules are too granular** (function-level rather than responsibility-level): zoom out. *"That feels like implementation detail. What's the higher-level piece it belongs to?"*
+- **More than 7 modules:** ask if any can be merged. More than 7 usually means either the system is genuinely large (valid) or the abstraction level is off (common).
+- **Operator says "I don't know" about dependencies:** file it as Q-NNN and continue. The contract can note the uncertainty.

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

@@ -0,0 +1,102 @@
+# plan-initial-wu
+
+You are running **Phase E of the planning arc** — Initial Work Units. The planning substrate is complete. Phase E translates the horizon map, architecture, and surfaces into the first set of concrete things to build.
+
+By the end of this session:
+
+- 5–10 work units are filed in `docs/build/work-units/`
+- They are ordered by dependency: things that other things need are filed (and built) first
+- Each work unit connects to at least one persona and one architecture module
+- The Phase E row in STATE.md is flipped to `✅ complete`
+- 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.
+
+---
+
+## Step 1 — Read the context (5 min)
+
+Before starting, read:
+- `docs/build/maps/02-phases.md` — the phases of work and what each milestone means
+- `docs/build/maps/03-near-term.md` — what's immediately next
+- `docs/build/architecture/` — the modules, for grounding each work unit
+- `docs/build/personas/` — to connect each work unit to a real person
+
+Open with:
+
+> "We've got the architecture, the design system, and the map. Now let's break the first wave of work into concrete pieces. A work unit is one thing: a feature, a surface, an infrastructure step — whatever has a clear outcome you can check. We'll file between 5 and 10 of them. Each will have an outcome, a walkthrough, and a list of things to check to know it's done. We'll order them so the things everything depends on come first."
+
+## Step 2 — Derive the first work units (30–40 min)
+
+Ask:
+
+> "Looking at what the near-term map says needs to happen first — what are the individual pieces? Don't list tasks; describe what will *exist and be usable* when each piece is done."
+
+For each work unit, **switch to the `wu-new` protocol** (invoke `/wu-new` if available; otherwise read `wu-new.md` and follow it). This ensures each work unit is filed correctly with outcome, walkthrough, and acceptance criteria.
+
+Between work units, check:
+
+> "Does [this WU] depend on anything that isn't filed yet? If so, let's file that dependency first."
+
+Aim for 5–10 work units covering the first meaningful phase of Map 2. Don't try to file the entire project — just enough that the swarm can start and the operator can see what's coming.
+
+## Step 3 — Order by dependency (5–10 min)
+
+When all work units are filed, look at the full set and ask:
+
+> "Which of these can start right now with no dependencies? Which ones need something else to be done first?"
+
+Update each work unit file with its dependency links. Update `docs/build/work-units/_index.md` statuses:
+- Anything with unmet dependencies → `🔵 proposed`
+- The first work unit with no unmet dependencies → `🟡 in flight`
+
+If multiple work units have no dependencies, pick the one that unblocks the most. Mark that one `🟡 in flight`; leave the others `🔵 proposed` with a note that they can start in parallel.
+
+## Step 4 — Run the planning arc review (required before closing)
+
+Before Phase E can close, run the full planning arc review. This is not optional.
+
+**Invoke `/plan-review`** (or read `.claude/commands/plan-review.md` and follow it). The review agent reads every artefact in the catalogue, then surfaces what's missing, unclear, inconsistent, or improvable — before a single line of code is written.
+
+Do not proceed to Step 5 until:
+- All blocker findings are fixed or explicitly escalated to the operator
+- All other findings are either fixed, filed as open questions, or deferred with a stated reason
+
+The review typically takes 10–20 minutes. It is the difference between a catalogue an agent can build against coherently and one that produces drift from the first spawn.
+
+## 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`.
+
+---
+
+## What to do if it goes off-track
+
+- **Too many work units:** file the first 5–10 and stop. The rest can be filed in later sessions as Map 3 updates. Trying to file 30 work units in Phase E stalls the arc indefinitely.
+- **Operator wants to skip work unit details:** at minimum get the outcome and 3 acceptance criteria. Without those, the coder has no brief. *"Just a sentence on what exists when it's done, and three yes-or-no checks. That's it."*
+- **Operator wants to start building immediately:** let them. *"Run `/end-of-session` to commit what we have, then `/build-wu [first WU handle]`. The swarm can start with what we've filed."*

package/templates/protocols/plan-maps.md

@@ -0,0 +1,85 @@
+# plan-maps
+
+You are running **Phase D of the planning arc** — Maps. The catalogue now has architecture, contracts, surfaces, and a complete design system. Phase D maps the journey from here to done: the major phases of work, what the world looks like at each milestone, and what is actually happening in the near term.
+
+By the end of this session:
+
+- Map 2 ("Phases of work") is filed at `docs/build/maps/02-phases.md`
+- Map 3 ("Near-term plan") is filed at `docs/build/maps/03-near-term.md`
+- 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.
+
+---
+
+## Step 1 — Read the context (5 min)
+
+Before starting, read:
+- `docs/build/maps/01-the-horizon.md` — the destination
+- `docs/build/work-units/` — any work units already filed (unlikely at this stage, but check)
+- `docs/build/open-questions/_index.md` — any blockers that might affect the timeline
+
+Open with:
+
+> "We've got the destination, the architecture, and the full design language. Now let's draw the path. Not hour-by-hour detail — the major stages from here to there, what's done at each milestone, and what we're actually working on this week or next. Two maps: one for the whole journey, one for right now."
+
+## Step 2 — Map 2: Phases of work (20–25 min)
+
+Ask:
+
+> "If you look at the project from start to shipped — what are the major stages? Most projects have three to six. Think about it in terms of what becomes *possible* at each stage, not the tasks inside each stage."
+
+For each stage the operator names, ask:
+
+1. *"What's true when this stage ends that wasn't true when it started? What can you demonstrate?"* (→ acceptance criterion)
+2. *"How would you verify that? Is there something you can run, click, or show?"* (→ verification gate — a specific test, URL, command, or file that proves the stage is done)
+
+**Write each phase as a row before moving to the next one.** The map should read as a narrative — a story of progress — not a task list. Use the template at `docs/build/maps/02-template.md`.
+
+After all phases are named, ask:
+
+> "Does every phase lead naturally to the next? Are there hidden dependencies — places where Phase [N] actually needs something from a later phase?"
+
+Write the final map to `docs/build/maps/02-phases.md`. Show the operator.
+
+## Step 3 — Map 3: Near-term plan (10–15 min)
+
+Ask:
+
+> "Zooming in — what's actually happening right now, or what will be once we file the first work units in Phase E? What's the first concrete thing that needs to exist?"
+
+Write Map 3 to `docs/build/maps/03-near-term.md` using `docs/build/maps/03-template.md`. This map is intentionally short-horizon and will be updated frequently. It should name:
+
+- What is actively being built (or will be, once Phase E files work units)
+- What is immediately next
+- Any blocker standing between now and the first shipped thing
+
+## 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."
+
+Then run `/end-of-session`.
+
+---
+
+## What to do if it goes off-track
+
+- **Operator wants to list individual tasks inside phases:** redirect to the outcome shape. *"Let's keep each phase as a destination — what's true, not what's done. The tasks inside each phase become work units in Phase E."*
+- **Operator can't name an acceptance criterion:** help them think from the outside in. *"Imagine showing this stage to someone who's been away for a month. What do you show them? What can they do that they couldn't before?"*
+- **No verification gate comes to mind:** that's a signal the phase boundaries are fuzzy. Tighten the acceptance criterion until a gate becomes obvious.
+- **Operator wants to skip Phase E and start building:** suggest Phase E first. *"Phase E is short — 60 minutes to file the first work units. After that, we know exactly which work unit is first and the swarm can start with a precise brief rather than 'build the project'."*

package/templates/protocols/plan-review.md

@@ -0,0 +1,134 @@
+# plan-review
+
+You are running the **planning arc review** — a full end-to-end audit of everything the planning arc produced before a single line of code is written.
+
+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`.
+
+By the end of this protocol:
+
+- Every gap, ambiguity, inconsistency, and optimisation opportunity in the planning catalogue has been surfaced
+- Each finding is either fixed immediately, filed as a Q-NNN open question, or explicitly deferred with a reason
+- The operator has confirmed the catalogue is complete enough to build against
+- Nothing unclear is hiding in the planning artefacts where an agent will silently make a wrong assumption
+
+---
+
+## Step 1 — Read the entire catalogue (do not skip anything)
+
+Before spawning the review agent, read every artefact produced by the planning arc:
+
+- `methodfile.json` — project metadata, tech stack, planning state
+- `docs/build/STATE.md` — current snapshot
+- All files in `docs/build/personas/` (not just `_index.md` — every persona file)
+- All files in `docs/build/architecture/`
+- All files in `docs/build/contracts/`
+- All files in `docs/build/ui-ux/`
+- All files in `docs/build/design-system/` (tokens, components, patterns, voice, accessibility)
+- All files in `docs/build/maps/`
+- All files in `docs/build/work-units/`
+- All files in `docs/build/decisions/`
+- `docs/build/open-questions/_index.md`
+- `docs/build/risks/_index.md`
+
+Also run the cross-agent memory search for any prior findings about this project:
+
+```bash
+nuos-catalogue memory search --query="planning gaps"
+nuos-catalogue memory search --query="open questions"
+```
+
+## Step 2 — Spawn the review agent
+
+Spawn an **architect** agent (Opus) with this exact brief:
+
+> You are reviewing the complete planning catalogue for **[project name]** before any implementation begins. Your job is to find what's missing, unclear, inconsistent, or improvable — so the agents that build this project have a complete, coherent brief to work from.
+>
+> Read every artefact provided below (personas, architecture, contracts, UI/UX surfaces, design system, maps, work units, decisions, open questions).
+>
+> Then run end to end through the entire project planning. Consider:
+> - **User journeys**: does the catalogue trace every complete path a user takes through the product? Are any paths incomplete, ambiguous, or contradictory?
+> - **Expectations and pain points**: do the personas clearly describe what users expect and what frustrates them? Would an agent reading these personas build something the real user would recognise?
+> - **Expected outcomes**: for each work unit, is the outcome unambiguous? Could two different agents read the same work unit and produce different things?
+> - **User experience**: does the design system actually govern the surfaces? Do the surfaces reference components that exist? Are there surfaces with no clear design language?
+> - **Every route**: are there user paths implied by the architecture that have no corresponding surface? Are there surfaces with no clear entry point?
+> - **Every journey**: does every persona have at least one complete journey through the product — from entry to outcome?
+> - **Every reason this tool will be used**: have all use cases been captured? Are there obvious use cases implied by the personas that have no work units?
+> - **Cross-artefact consistency**: do contracts match what modules claim to provide? Do work units reference personas and modules that exist? Do surfaces reference design-system components that are filed?
+>
+> Return your findings structured as four lists:
+>
+> **MISSING** — things the catalogue should contain but doesn't (e.g. a surface with no empty state, a persona with no journey, a module with no contract)
+>
+> **UNCLEAR** — things that are present but need more definition before an agent can act on them (e.g. an acceptance criterion that isn't binary, a design token with no stated value, a contract that says "appropriate response" without defining what appropriate means)
+>
+> **GAPS** — inconsistencies between artefacts (e.g. a work unit that consumes a contract that doesn't exist, a surface that uses a colour token not in the design system, an architecture module that nothing depends on and nothing depends on it)
+>
+> **OPTIMISE** — things that are present and correct but could be improved to produce better agent output (e.g. a persona that has seven dimensions but no acid-test scenario, a work unit with three acceptance criteria where five would give the tester better coverage, a map phase with no verification gate)
+>
+> For each finding: state what it is, which artefact it's in, and what specifically needs to change or be added. Be precise — vague findings produce vague fixes.
+
+Pass the full contents of every artefact as context. Do not summarise the artefacts — pass the full text.
+
+## Step 3 — Triage the findings with the operator
+
+When the review agent returns, surface the findings in plain English grouped by list. For each finding:
+
+1. Read it to the operator in plain language
+2. Ask: *"Fix it now, file it as an open question to address before we build, or defer it with a reason?"*
+3. Execute immediately:
+   - **Fix now**: make the change to the relevant artefact, show the operator
+   - **Open question**: file as Q-NNN in `docs/build/open-questions/`, add to `_index.md`
+   - **Defer**: note the reason in the relevant artefact's file (so the next agent to read it knows the gap was seen and deliberately left)
+
+Do not let findings disappear into conversation. Every finding must land somewhere in the catalogue before the review closes.
+
+If the review agent surfaces more than 10 findings, group them by severity before presenting:
+- **Blockers** (MISSING or GAPS that would cause an agent to build the wrong thing) — address these before any building starts, no exceptions
+- **Non-blockers** (UNCLEAR or OPTIMISE items that would improve quality but don't break the brief) — can be filed as Q-NNN and addressed in the first building sessions
+
+## Step 4 — Store the review
+
+After all findings are triaged, store a summary in cross-agent memory:
+
+```bash
+nuos-catalogue memory store \
+  --value="Planning review complete: [N] findings — [N] fixed, [N] filed as open questions, [N] deferred. Key issues: [one sentence summary of the most significant findings]" \
+  --agent=coordinator \
+  --key="planning-review"
+```
+
+Write a brief review entry to the current session log (it will be captured by `/end-of-session`).
+
+## Step 5 — Surface the result to the operator
+
+> "Planning review done. Here's what we found:
+>
+> - **[N] blockers** — [summary / "none"] 
+> - **[N] clarifications** — [summary / "none"]
+> - **[N] optimisations** — [summary / "none"]
+>
+> [If blockers were fixed]: Fixed [N] things in the catalogue directly.
+> [If open questions were filed]: Filed [N] open questions — these will surface in `/start-of-session` when we start building.
+> [If deferred]: Deferred [N] items — noted in the relevant artefacts.
+>
+> The catalogue is [complete and clear to build against / has [N] open questions that should be resolved in the first session before the swarm starts]."
+
+Return control to whatever invoked this protocol (typically `plan-initial-wu`, which will then proceed to close Phase E).
+
+---
+
+## If invoked standalone (mid-project)
+
+When `/plan-review` is called outside of the planning arc close — e.g. after a significant pivot, after a new persona is added, or when something feels off — run Steps 1–5 above, then:
+
+- Do not update planning progress in STATE.md (Phase E may already be complete)
+- Do update STATE.md's "What is currently in flight" and "Last updated"
+- Run `/end-of-session` to commit the findings and any fixes
+
+---
+
+## What never to do
+
+- **Never skip the full catalogue read.** A review based on summaries misses cross-artefact inconsistencies — which are the most damaging class of gap.
+- **Never let a finding sit in conversation.** If it's not filed or fixed before the review closes, it's lost.
+- **Never block building on OPTIMISE findings.** These are improvements, not prerequisites. File them, continue.

package/templates/protocols/plan-uiux.md

@@ -0,0 +1,247 @@
+# plan-uiux
+
+You are running **Phase C of the planning arc** — UI/UX + Design System. This phase does two things:
+
+1. **Surfaces** — names every page, screen, modal, or command the user ever touches, and defines what each one does.
+2. **Design system** — builds the shared visual and interaction language those surfaces use: colour tokens, type scale, spacing, radius, motion, components, patterns, voice, and accessibility commitments.
+
+By the end of this session:
+
+- Every user-facing surface is filed in `docs/build/ui-ux/`
+- The design system is **fully populated** in `docs/build/design-system/` — tokens have real values, components are defined with their variants, patterns are named. **No placeholders.**
+- 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.
+
+---
+
+## How to lead this conversation
+
+- **Walk the user's journey before building the system.** Understand every surface first; the design language emerges from what the surfaces need.
+- **Write surface files and design-system files as the conversation produces them.** Don't batch.
+- **Extract; don't impose.** The design language should come from the operator's intent and the project's character — not from generic defaults.
+- **The design system must be complete before the phase closes.** Colour tokens cannot be `#000000`. Components cannot be "TBD". If the operator says "I don't know the exact colour yet", help them decide now — make a reasoned provisional choice, write it down, and file it as a decision they can supersede later. Provisional is fine. Blank is not.
+
+---
+
+## Step 1 — Read the context (5 min)
+
+Before starting, read:
+- `docs/build/personas/` — who uses these surfaces
+- `docs/build/architecture/` — modules; surfaces call into these
+- `docs/build/maps/01-the-horizon.md` — the destination
+- `methodfile.json`'s `techStack` section — platform affects surface types (web vs. native vs. CLI)
+
+Open with:
+
+> "We've named the architecture — the major pieces and what they do. Now let's design what people actually see and touch. We'll go through every screen or page in your words, and then build the design language behind it: colours, type, spacing, and the building blocks every screen uses. Nothing left blank. Real values, real components — everything an agent needs to build the UI correctly on the first pass."
+
+## Step 2 — Enumerate all surfaces (10–15 min)
+
+Ask:
+
+> "Walk me through the experience from the very beginning. Someone opens your product for the first time — what do they see? Then what? Keep going until we get to everything."
+
+As the operator describes, build a running list of every distinct surface:
+- Full pages / screens
+- Modals and overlays
+- Empty states (often forgotten; usually the worst experience if undesigned)
+- Error states
+- Emails or notifications if the product sends them
+- Admin or back-office surfaces if they exist
+- CLI or command surface if there is one
+
+Surface any surfaces that were skipped:
+
+> "You mentioned [X] — does that have its own screen? What happens after [action] — is there a confirmation view?"
+
+Don't file surface files yet. Build the complete list first.
+
+## Step 3 — Walk each surface (20–30 min)
+
+For each surface in the list, ask in conversation:
+
+1. *"Which [persona name] uses this?"*
+2. *"What are they trying to do when they land here?"*
+3. *"What does the screen show — walk me through top to bottom."*
+4. *"What's the primary action — the one thing we most want them to do?"*
+5. *"What can go wrong — empty data, errors, edge cases?"*
+
+**File each surface immediately** at `docs/build/ui-ux/<surface-slug>.md` using `docs/build/ui-ux/surface-template.md`. Mark which architecture module(s) it calls into. Show the file path.
+
+## 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
+
+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?"
+
+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
+- **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`.
+
+## Step 5 — File the components (15–20 min)
+
+Look back across all surfaces filed in Step 3. Extract the recurring UI building blocks:
+
+> "Looking at the surfaces, the same pieces appear repeatedly: [list what you found — buttons, form fields, cards, navigation, modals, etc.]. These become your component library."
+
+For each component define:
+- What it renders
+- Its variants (e.g. Button: primary / secondary / ghost / destructive / disabled)
+- Which tokens it uses
+- Behaviour: hover, focus, loading, error state
+
+File each at `docs/build/design-system/components/<component-slug>.md` using `docs/build/design-system/components/_template.md`. Update `docs/build/design-system/components/_index.md`.
+
+At a minimum, file:
+- **Button** — most important; every interaction has one
+- **Input / form field** — text, select, checkbox, radio
+- **Card** — almost every product has content cards
+- **Navigation** — header, sidebar, or tab bar (whatever this product uses)
+- **Modal / dialog**
+- Any product-specific components that appear in two or more surfaces
+
+## Step 6 — File the patterns (10 min)
+
+Patterns are compositions of components that repeat across surfaces:
+
+> "Some combinations appear in multiple places — a form with a submit button, a list of cards with a header, an empty state with a CTA. Naming these prevents each agent from inventing its own."
+
+File patterns that appear in two or more surfaces at `docs/build/design-system/patterns/<pattern-slug>.md` using `docs/build/design-system/patterns/_template.md`. Update `docs/build/design-system/patterns/_index.md`.
+
+Common patterns:
+- **Form layout** — label + field + validation error + submit button
+- **Empty state** — icon/illustration + heading + body + CTA
+- **Page header** — title + subtitle + primary action
+- **Data table** — sortable columns, row actions, pagination if needed
+
+## Step 7 — Voice and accessibility (10 min)
+
+### Voice
+
+Ask:
+> "If the product spoke to users — in buttons, in error messages, in empty states — what would it sound like? Friendly and casual, professional and concise, encouraging and warm?"
+
+Establish:
+- Tone (e.g. "direct but warm — never corporate, never cutesy")
+- Vocabulary rules (words to use; words to avoid)
+- Tense and person ("You have N items" vs. "The user has N items")
+- Error message style (apologetic vs. matter-of-fact)
+- CTA writing style ("Get started" vs. "Start for free" vs. "Create account")
+
+Write to `docs/build/design-system/voice.md`.
+
+### Accessibility
+
+Establish non-negotiables:
+- Colour contrast standard (WCAG AA minimum; state if targeting AAA)
+- Keyboard navigation requirements
+- Screen reader labelling approach
+- Focus indicator style (don't accept "browser default" — name the actual style)
+
+Write to `docs/build/design-system/accessibility.md`.
+
+## Step 8 — Check: nothing left blank (5 min)
+
+Before closing, verify:
+- Every colour token has a real hex/hsl value — no `#000000` defaults
+- Every type token has a real font name and real rem size
+- Every component is filed with its variants named
+- Voice and accessibility are written prose, not placeholder headings
+
+If anything is still a placeholder, resolve it now. This check is non-negotiable — the whole point of Phase C is to produce a real design system, not a skeleton.
+
+## 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`.
+
+---
+
+## What to do if it goes off-track
+
+- **Operator says "I'll decide the colours later":** don't accept it. *"The design system is what stops every agent making up its own answer. Placeholder values mean every UI piece the swarm ships will need a rework pass. Let me suggest something reasonable based on what you've described — you just tell me if I'm wrong."* Make the provisional decision; file it as a decision they can supersede. Move on.
+- **Operator doesn't know component terminology:** use product language. *"The button that logs someone in — what does it look like? What colour is it?"* Extract components from their description.
+- **Too many surfaces:** narrow to surfaces that are genuinely distinct (different layout, different purpose). Modals that follow the same pattern don't need separate files — one modal component covers them.
+- **Mobile-first product:** let the constraint shape the language. Mobile-first means generous tap targets (min 44px), larger base type size, generous spacing. Note it in accessibility.md.
+- **Operator has existing brand guidelines:** ask them to share the primary colour and font. Use those as the starting point; fill the rest of the scale from them.

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

@@ -16,7 +16,17 @@ Read `docs/build/STATE.md`. Look at the **Planning progress** section:
 
   If yes, **switch to the `plan-orientation` protocol** (invoke `/plan-orientation` if available; otherwise read `.claude/commands/plan-orientation.md` and follow it). If no, point them at `docs/build/WELCOME.md` and `docs/build/GLOSSARY.md` so they can read about the catalogue first, then wait.
 
-- If **Phase A is in flight or any phase is mid-progress** (marked `🟡 in flight` in STATE.md's Planning progress section), route the operator back to the relevant `plan-*` protocol to continue planning. Read the most recent session log's "Resume hint" section to know exactly where to pick up.
+- If **any planning phase is in progress or marked `🟡 next`**, route to the appropriate protocol. Read the most recent session log's "Resume hint" to know exactly where to pick up within the phase.
+
+  | Phase | Protocol |
+  |---|---|
+  | A — Orientation | `plan-orientation` |
+  | B — Architecture & Contracts | `plan-architecture` |
+  | C — UI/UX + Design System | `plan-uiux` |
+  | D — Maps | `plan-maps` |
+  | E — Initial Work Units | `plan-initial-wu` |
+
+  Invoke the protocol with its slash command (e.g. `/plan-uiux`) if available; otherwise read `.claude/commands/<protocol>.md` and follow it. The "next" phase in STATE.md is the one to route to — if Phase B is `✅ complete` and Phase C is `🟡 next`, invoke `plan-uiux`.
 
 - If **all five planning phases are complete**, proceed with the normal session-start steps below.