@nusoft/nuos-build-catalogue 0.22.0 → 0.23.0

package/dist/commands/init.js

@@ -39,6 +39,10 @@ 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',
     'build-wu.md',
 ];
 /**
@@ -52,6 +56,10 @@ 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',
     '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.23.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,90 @@
+# 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 — Close
+
+Update STATE.md:
+- Phase E row → `✅ complete (YYYY-MM-DD)`
+- "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-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.