odd-studio 2.4.1 → 2.6.0

package/bin/odd-studio.js

@@ -41,8 +41,8 @@ program
 // ── init ──────────────────────────────────────────────────────────────────────
 program
   .command('init [project-name]')
-  .description('Scaffold a new ODD project and install the /odd skill into Claude Code')
-  .option('--skip-skill', 'Skip installing the /odd skill globally (advanced)')
+  .description('Scaffold a new ODD project and install /odd + excalidraw skills into Claude Code')
+  .option('--skip-skill', 'Skip installing the /odd and excalidraw skills globally (advanced)')
   .option('--skip-hooks', 'Skip installing safety hooks (not recommended)')
   .option('--yes', 'Accept all defaults without prompting')
   .action(async (projectName, options) => {
@@ -74,18 +74,24 @@ program
       process.exit(1);
     }
 
-    // 2. Install /odd skill
+    // 2. Install /odd skill and excalidraw skill
     if (!options.skipSkill) {
-      print.step(2, 5, 'Installing /odd skill into Claude Code...');
+      print.step(2, 5, 'Installing /odd skill and excalidraw skill into Claude Code...');
       const spinner2 = ora({ text: '', indent: 4 }).start();
       try {
-        const result = await installSkill(PACKAGE_ROOT);
+        const { default: installExcalidraw } = await import('../scripts/install-excalidraw.js');
+        await Promise.all([
+          installSkill(PACKAGE_ROOT),
+          installExcalidraw(PACKAGE_ROOT)
+        ]);
         spinner2.stop();
-        print.ok('Skill installed → ' + chalk.cyan(result.destination));
+        print.ok('/odd skill installed → ' + chalk.cyan('~/.claude/skills/odd/'));
+        print.ok('excalidraw skill installed → ' + chalk.cyan('~/.claude/skills/excalidraw/'));
       } catch (e) {
         spinner2.stop();
-        print.warn('Could not install skill automatically: ' + e.message);
+        print.warn('Could not install skills automatically: ' + e.message);
         print.info('Manual install: copy ' + chalk.dim('skill/') + ' to ' + chalk.dim('~/.claude/skills/odd/'));
+        print.info('excalidraw skill: available via ' + chalk.dim('/excalidraw') + ' command in Claude Code');
       }
     } else {
       print.step(2, 5, 'Skipping skill install (--skip-skill)');
@@ -198,10 +204,11 @@ program
 // ── upgrade ───────────────────────────────────────────────────────────────────
 program
   .command('upgrade')
-  .description('Upgrade the /odd skill and hooks to the latest version')
+  .description('Upgrade the /odd skill, excalidraw skill, and hooks to the latest version')
   .action(async () => {
     print.logo();
     const { default: installSkill } = await import('../scripts/install-skill.js');
+    const { default: installExcalidraw } = await import('../scripts/install-excalidraw.js');
     const { default: setupHooks } = await import('../scripts/setup-hooks.js');
 
     console.log(chalk.bold('  Upgrading ODD Studio...\n'));
@@ -214,6 +221,14 @@ program
       s1.fail('Skill update failed: ' + e.message);
     }
 
+    const s1b = ora({ text: 'Updating excalidraw skill...', indent: 4 }).start();
+    try {
+      await installExcalidraw(PACKAGE_ROOT, { force: true });
+      s1b.succeed('Excalidraw skill updated');
+    } catch (e) {
+      s1b.fail('Excalidraw skill update failed: ' + e.message);
+    }
+
     const s2 = ora({ text: 'Updating hooks...', indent: 4 }).start();
     try {
       await setupHooks(PACKAGE_ROOT, { force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Outcome-Driven Development for Claude Code — a planning and build harness for domain experts building serious software with AI.",
   "keywords": [
     "claude-code",

package/scripts/excalidraw-skill/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: excalidraw
+description: Wireframe and diagram generation for UI/design planning
+version: 1.1.0
+author: ODD Studio
+source: https://github.com/excalidraw/excalidraw
+tags:
+  - ui-design
+  - wireframing
+  - planning
+  - visualization
+---
+
+# Excalidraw Wireframe Generator
+
+Generate `.excalidraw` wireframe files that can be opened in excalidraw.com or the VS Code Excalidraw extension.
+
+## How This Skill Works
+
+When invoked, you MUST generate a valid `.excalidraw` JSON file. This is not a documentation skill — it is a generation skill. You produce output.
+
+## Output Format
+
+Every invocation produces a `.excalidraw` file saved to `docs/wireframes/` in the project directory. The file is valid Excalidraw JSON that can be:
+- Dragged into https://excalidraw.com for interactive editing
+- Opened in VS Code with the Excalidraw extension
+- Exported as PNG or SVG from either tool
+
+## Excalidraw JSON Schema
+
+An `.excalidraw` file is JSON with this structure:
+
+```json
+{
+  "type": "excalidraw",
+  "version": 2,
+  "source": "odd-studio",
+  "elements": [ ... ],
+  "appState": {
+    "gridSize": null,
+    "viewBackgroundColor": "#0a0a0f",
+    "theme": "dark"
+  },
+  "files": {}
+}
+```
+
+### Element Types
+
+Every element in the `elements` array has these common fields:
+
+```json
+{
+  "id": "unique-id",
+  "type": "rectangle|ellipse|diamond|text|line|arrow",
+  "x": 0,
+  "y": 0,
+  "width": 100,
+  "height": 50,
+  "angle": 0,
+  "strokeColor": "#495057",
+  "backgroundColor": "#1e1e2e",
+  "fillStyle": "solid",
+  "strokeWidth": 1,
+  "roughness": 0,
+  "opacity": 100,
+  "roundness": { "type": 3 },
+  "seed": 1001,
+  "version": 1,
+  "isDeleted": false,
+  "boundElements": null,
+  "link": null,
+  "locked": false
+}
+```
+
+**Rectangle** — Use for containers, cards, buttons, inputs, navigation bars, progress bars:
+- Set `roundness: { "type": 3 }` for rounded corners (cards, buttons)
+- Set `roundness: null` for sharp corners (sidebars, headers)
+- For buttons: small height (28-36), accent `backgroundColor`, `"transparent"` `strokeColor`
+- For cards: `backgroundColor: "#313244"`, `strokeColor: "#495057"`
+- For progress bars: two overlapping rectangles (background + fill)
+
+**Text** — Use for labels, headings, body text:
+```json
+{
+  "type": "text",
+  "text": "Your label here",
+  "fontSize": 14,
+  "fontFamily": 1,
+  "textAlign": "left",
+  "verticalAlign": "top"
+}
+```
+- Headings: `fontSize: 20-28`, `strokeColor: "#cdd6f4"`
+- Body text: `fontSize: 13-14`, `strokeColor: "#cdd6f4"`
+- Muted/secondary: `fontSize: 12-13`, `strokeColor: "#6c7086"`
+- Accent text: `strokeColor: "#a78bfa"` (or project accent colour)
+
+**Ellipse** — Use for avatars, status indicators:
+- Equal width/height for circles
+
+**Diamond** — Use for badges, decorative icons:
+- Good for achievement/badge indicators
+
+**Line** — Use for separators, connectors:
+```json
+{
+  "type": "line",
+  "points": [[0, 0], [200, 0]]
+}
+```
+
+**Arrow** — Use for flow indicators, data flow diagrams:
+```json
+{
+  "type": "arrow",
+  "points": [[0, 0], [200, 0]],
+  "startArrowhead": null,
+  "endArrowhead": "arrow"
+}
+```
+
+### Colour Palettes
+
+**Dark mode (Catppuccin Mocha — default for ODD Studio):**
+- Background: `#1e1e2e`
+- Surface/cards: `#313244`
+- Surface darker: `#181825`
+- Border: `#495057`
+- Muted surface: `#45475a`
+- Text primary: `#cdd6f4`
+- Text muted: `#6c7086`
+- Accent purple: `#a78bfa`
+- Success green: `#a6e3a1`
+- Warning amber: `#fab387`
+- Error red: `#f38ba8`
+- Canvas background: `#0a0a0f`
+
+**Light mode:**
+- Background: `#ffffff`
+- Surface/cards: `#f8f9fa`
+- Border: `#dee2e6`
+- Text primary: `#212529`
+- Text muted: `#6c757d`
+- Accent blue: `#3b82f6`
+- Canvas background: `#f5f5f5`
+
+### Layout Patterns
+
+**Desktop (1280x800):**
+- Sidebar: x=0, width=240, full height
+- Main content: x=280 (240 sidebar + 40 padding)
+- Content width: ~960px
+- Card grid: 3 columns at 300px each with 30px gaps
+
+**Mobile (375x812):**
+- Full-width cards with 16px padding each side (x=16, width=343)
+- Header bar: height=60, full width
+- Bottom tab bar: y=752, height=60, full width
+- Stack cards vertically with 16px gaps
+
+**Tablet (768x1024):**
+- 2-column card grid
+- Collapsible sidebar or top navigation
+
+### Wireframe Composition Rules
+
+1. **Always include a label** above each wireframe frame identifying it (e.g., "DESKTOP — Student Dashboard (1280x800)")
+2. **Use realistic content** — not "Lorem ipsum". Use domain-specific text from the specification.
+3. **Show the key outcome flow** — the most important screen the persona interacts with.
+4. **Include navigation** — sidebar on desktop, bottom tabs on mobile.
+5. **Show data states** — progress bars should show realistic percentages, cards should have real titles.
+6. **Use the project's accent colour** consistently for interactive elements (buttons, active tabs, links).
+7. **Keep `roughness: 0`** for clean wireframes. Use `roughness: 1` only if a hand-drawn sketch style is requested.
+
+### Generating Multiple Views
+
+When generating wireframes for Step 9b (UI & Design Decision), create separate files for each design approach:
+
+- `docs/wireframes/minimalist-dark.excalidraw` — dark mode, minimal, shadcn/ui
+- `docs/wireframes/dense-dashboard-light.excalidraw` — light mode, data-dense, tables
+- `docs/wireframes/minimal-accessible.excalidraw` — high contrast, large targets, WCAG AAA
+- `docs/wireframes/brand-driven.excalidraw` — custom palette, domain-specific visual language
+
+Each file should contain both desktop and mobile views side-by-side on the same canvas:
+- Desktop frame at x=0
+- Mobile frame at x=(desktop width + 120)
+
+### Seed Values
+
+Every element needs a unique `seed` value (integer). Use a simple incrementing counter:
+- Desktop elements: 1001, 1002, 1003...
+- Mobile elements: 2001, 2002, 2003...
+- Additional views: 3001, 3002, 3003...
+
+## Usage
+
+When the `/excalidraw` command is invoked with arguments, parse the arguments to understand:
+1. What to wireframe (which screen, which persona, which outcome)
+2. Which design approach (dark/light, minimal/dense, accessible, brand-driven)
+3. Which devices (desktop, mobile, tablet)
+
+Then generate the `.excalidraw` JSON file using the schema above and save it to `docs/wireframes/[design-approach-name].excalidraw`.
+
+After generating, tell the user:
+- The file path
+- How to open it: "Drag this file into excalidraw.com to view and edit interactively, or open it with the VS Code Excalidraw extension."

package/scripts/install-excalidraw.js

@@ -0,0 +1,29 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Installs the excalidraw skill into Claude Code.
+ *
+ * Copies the SKILL.md (with full generation logic) from the bundled
+ * excalidraw-skill directory to ~/.claude/skills/excalidraw/
+ */
+export default async function installExcalidraw(packageRoot, options = {}) {
+  const source = path.join(packageRoot, 'scripts', 'excalidraw-skill');
+  const destination = path.join(os.homedir(), '.claude', 'skills', 'excalidraw');
+
+  // Ensure ~/.claude/skills/ exists
+  await fs.ensureDir(path.join(os.homedir(), '.claude', 'skills'));
+
+  // If destination exists and not forcing, back it up
+  if (fs.existsSync(destination) && !options.force) {
+    const backup = destination + '.backup-' + Date.now();
+    await fs.move(destination, backup);
+  }
+
+  // Copy the excalidraw skill directory (contains SKILL.md with generation logic)
+  await fs.copy(source, destination);
+
+  return { destination };
+}

package/scripts/postinstall.js

@@ -17,11 +17,12 @@ const pkg = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
 
 Promise.all([
   import('./install-skill.js').then(({ default: installSkill }) => installSkill(pkg)),
+  import('./install-excalidraw.js').then(({ default: installExcalidraw }) => installExcalidraw(pkg)),
   import('./setup-hooks.js').then(({ default: setupHooks }) => setupHooks(pkg)),
   import('./setup-mcp.js').then(({ default: setupMcp }) => setupMcp()),
 ])
   .then(() => {
-    console.log('✓ ODD Studio: /odd skill, safety hooks, and ruflo memory installed into Claude Code');
+    console.log('✓ ODD Studio: /odd skill, excalidraw skill, safety hooks, and ruflo memory installed into Claude Code');
     console.log('  → Restart Claude Code now to activate ruflo memory and hooks.');
     console.log('  Run: npx odd-studio init [project-name]  to scaffold your first project.');
   })

package/scripts/scaffold-project.js

@@ -41,6 +41,18 @@ export default async function scaffoldProject(targetDir, projectName) {
     await fs.writeJson(stateFile, state, { spaces: 2 });
   }
 
+  // Create .vscode/extensions.json with recommended extensions
+  const vscodeDir = path.join(targetDir, '.vscode');
+  const extensionsFile = path.join(vscodeDir, 'extensions.json');
+  if (!fs.existsSync(extensionsFile)) {
+    await fs.ensureDir(vscodeDir);
+    await fs.writeJson(extensionsFile, {
+      recommendations: [
+        'pomdtr.excalidraw-editor'
+      ]
+    }, { spaces: 2 });
+  }
+
   // Initialise git if not already a repo
   const gitDir = path.join(targetDir, '.git');
   if (!fs.existsSync(gitDir)) {

package/skill/SKILL.md

@@ -250,17 +250,23 @@ Type `*build` to begin, or `*status` to see the full phase progress.
 
 Generate the IDE Session Brief. This is a standalone document that a developer or AI coding agent can use to execute a build session without needing to ask planning questions.
 
-Load `docs/plan.md` and all outcome files from `docs/outcomes/`. Generate `docs/session-brief.md` with:
+Load `docs/plan.md` and all outcome files from `docs/outcomes/`. Check `.odd/state.json` for the current `sessionBriefCount` (default 0 if not set). Generate `docs/session-brief-[N].md` where N is the current count.
+
+Include:
 
 - Project overview (one paragraph)
 - Active persona(s) for this session
 - Outcomes in scope (with full 6-field specification)
 - Contracts in play (what is produced, what is consumed)
+- Available from previous phases (contracts already built)
 - Verification steps for each outcome
 - Build sequence (which outcome to start, which depends on which)
 - Any known constraints or failure paths to handle
+- Changes from original plan (if any reconciliation has occurred)
+
+Increment `sessionBriefCount` in `.odd/state.json`.
 
-After writing the file, display: "Your Session Brief has been written to docs/session-brief.md. Open it in your IDE or share it with your build AI to begin the session."
+After writing the file, display: "Session Brief [N] has been written to docs/session-brief-[N].md. Open it in your IDE or share it with your build AI to begin the session."
 
 ---
 
@@ -587,7 +593,7 @@ At key moments in the methodology, proactively explain why the current step matt
 "Checkpoint runs automatically every time you confirm an outcome. It scans what was just built for security issues — exposed secrets, missing authentication checks, injection vulnerabilities — and briefs the build agent to fix anything it finds before you move on. You do not need to understand what it found or how it was fixed. Security is not a separate concern in ODD Studio. It is built into the rhythm of the build."
 
 **Phase complete:**
-"Phase complete. All outcomes in this phase have been verified and cleared by Checkpoint. The contracts they exposed are now available to the next phase. Well done — this is exactly how a well-planned build should progress."
+"Phase complete. All outcomes in this phase have been verified and cleared by Checkpoint. The plan has been reconciled with changes from this phase, and Session Brief [N] has been generated for the next phase. Review it at `docs/session-brief-[N].md` or type `*build` to continue. All previous session briefs are retained. Well done — this is exactly how a well-planned build should progress."
 
 ---
 

package/skill/docs/build/build-protocol.md

@@ -83,7 +83,182 @@ Three checks run:
 
 **Cross-persona check.** Confirm each persona sees what they should see and cannot access what they should not. Navigate as a customer to a page that should only be accessible to an organiser. Confirm it is blocked.
 
-When all three checks pass, the phase is complete. ODD Studio marks it so, updates ruflo memory, and confirms which phase is next.
+When all three checks pass, the phase is complete. ODD Studio runs the Phase Transition procedure.
+
+---
+
+## Phase Transition
+
+When a phase is complete and all integration checks pass, ODD Studio advances to the next phase. This is a four-step process: mark complete, reconcile the plan, generate the next numbered brief, and confirm with the domain expert.
+
+---
+
+### Transition Step 1: Mark the current phase complete
+
+Update `.odd/state.json`:
+- Set the current phase status to `"complete"`
+- Update `lastSessionDate`
+
+Store completion in ruflo memory:
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-phase-[phase-name]-complete`
+- Namespace: `odd-project`
+- Value: phase name, completion date, outcomes verified, integration checks passed
+
+---
+
+### Transition Step 2: Plan Reconciliation
+
+During the build, things change. Specification gaps are discovered. The domain expert requests new features. A contract turns out to need a different shape. An outcome gets split into two. A service that was planned for a later phase gets pulled forward because the current phase needed it.
+
+These changes happen *during* the build — they are recorded in ruflo memory as specification gaps, outcome updates, and contract changes. But `docs/plan.md` still reflects the original plan. If the next phase's brief is generated from a stale plan, it will conflict with reality.
+
+**Before generating the next phase's brief, reconcile the plan.**
+
+**2a. Gather all changes from the completed phase.**
+
+Read from ruflo memory all changes recorded during the phase:
+
+Call `mcp__ruflo__memory_search`:
+- Query: `phase [completed-phase-name] changes`
+- Namespace: `odd-project`
+
+Also check:
+- All outcome files in `docs/outcomes/` — compare current versions against the plan's original descriptions. Look for updated walkthroughs, new verification steps, changed contracts.
+- The contract map in ruflo memory (`odd-contract-map`) — compare against `docs/contract-map.md`. Look for new contracts, changed data shapes, removed dependencies.
+- Any `*outcome` edits made during the phase (specification gap fixes).
+- Any new outcomes added during the build that were not in the original plan.
+
+**2b. Classify each change.**
+
+For each change found, classify it:
+
+1. **Contained change** — affects only the completed phase. No impact on future phases. Example: a verification step was reworded, a UI layout was adjusted, an error message was improved.
+
+2. **Contract change** — a contract's shape, name, or data flow was altered. This affects any future outcome that consumes this contract. Example: the mastery level contract now includes a `confidence_score` field that wasn't in the original plan.
+
+3. **New outcome** — a new outcome was identified during the build that needs to be added to a future phase. Example: during Phase 1, the domain expert realised students need a "review mistakes" feature that wasn't originally planned.
+
+4. **Moved outcome** — an outcome originally in a later phase was partially or fully built during this phase because it was needed earlier than planned. Example: basic parent notifications were built in Phase 1 because the teacher dashboard needed to reference them.
+
+5. **Removed or deferred outcome** — an outcome was removed from scope or moved to a later phase. Example: the gamification system was deprioritised to focus on core learning.
+
+6. **Dependency change** — a dependency between phases changed. Example: Phase 3 no longer depends on Phase 2's grouping feature because the parent dashboard was redesigned to use individual student data instead.
+
+**2c. Update `docs/plan.md`.**
+
+For each change that is NOT contained (types 2-6), update `docs/plan.md`:
+
+- **Contract changes**: Update the contract descriptions in the plan. Note what changed and why.
+- **New outcomes**: Add them to the appropriate phase. Re-run the dependency logic — does this new outcome depend on something that hasn't been built yet? If so, assign it to the correct phase.
+- **Moved outcomes**: Update their phase assignment. Mark what was already built and what remains.
+- **Removed/deferred outcomes**: Move them to a "Deferred" section at the bottom of the plan, with the reason.
+- **Dependency changes**: Update the phase dependency descriptions.
+
+Add a **Change Log** section at the bottom of `docs/plan.md`:
+
+```markdown
+## Change Log
+
+### After Phase [completed phase name] — [date]
+- [Change type]: [description of what changed and why]
+- [Change type]: [description]
+- [Change type]: [description]
+```
+
+**2d. Store the reconciled plan in ruflo memory.**
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-plan`
+- Namespace: `odd-project`
+- Value: the full updated Master Implementation Plan
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-plan-reconciliation-phase-[phase-name]`
+- Namespace: `odd-project`
+- Value: summary of all changes made during reconciliation, with classification and reasoning
+
+**2e. Present the reconciliation to the domain expert.**
+
+"Before I generate the next phase's brief, I need to account for what changed during the build. Here is what I found:
+
+**Changes that affect future phases:**
+- [list each non-contained change with its classification and impact]
+
+**Changes contained to the completed phase (no impact on future phases):**
+- [list contained changes — for information only]
+
+**Updated plan:**
+- [summary of how `docs/plan.md` was updated]
+- [any outcomes added, moved, removed, or deferred]
+- [any contract shapes that changed]
+
+Does this reconciliation look correct? Are there any other changes from this phase that I missed?"
+
+Wait for the domain expert to confirm before proceeding to Step 3.
+
+---
+
+### Transition Step 3: Generate the next numbered Session Brief
+
+Session briefs are numbered sequentially. The first brief is `session-brief-0.md`. Each subsequent phase gets the next number.
+
+Read `.odd/state.json` to get the current `sessionBriefCount`. The next brief is `docs/session-brief-[N].md` where N is the current count.
+
+Generate the brief from the **reconciled** `docs/plan.md` (not the original plan). The brief must reflect any changes from Transition Step 2.
+
+The brief follows the same structure as Step 10, with these additions:
+
+- **"Available From Previous Phases"** section listing all contracts and infrastructure produced by completed phases
+- **"Changes From Original Plan"** section listing any reconciliation changes that affect this phase — new outcomes added, contracts that changed shape, dependencies that shifted. If none: "No changes — this phase matches the original plan."
+
+Save to `docs/session-brief-[N].md`.
+
+Store in ruflo memory:
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-session-brief-[N]`
+- Namespace: `odd-project`
+- Value: the contents of the new session brief
+
+Update `.odd/state.json`:
+- Set `currentBuildPhase` to the next phase
+- Increment `sessionBriefCount`
+
+---
+
+### Transition Step 4: Confirm the transition
+
+"Phase [completed phase name] is complete. All outcomes verified. All integration checks passed.
+
+[If reconciliation found changes]: The plan has been updated to reflect [N] changes from this phase. Review the updated plan at `docs/plan.md`.
+
+Session Brief [N] has been generated for Phase [next phase name]: [phase description]. This phase contains [n] outcomes: [list outcome names].
+
+[If changes affect this phase]: Note: this phase has been updated since the original plan — [brief summary of what changed].
+
+All previous session briefs are retained:
+[list: session-brief-0.md through session-brief-[N-1].md]
+
+Type `*build` to begin Phase [next phase name], or review the Session Brief at `docs/session-brief-[N].md` first."
+
+---
+
+### Transition Step 5: If this was the final phase
+
+If no phases remain, the project build is complete. Update `.odd/state.json`:
+- Set `currentPhase` to `"complete"`
+- Set `buildComplete` to `true`
+
+Confirm:
+
+"All phases are complete. Every outcome has been verified and every integration check has passed. Your project is built.
+
+Session briefs retained: [list all numbered briefs].
+Plan reconciliation history: [list all reconciliation entries from the change log].
+
+Review the full system end-to-end against your original personas. Does Alex experience what you documented? Does Sarah see what you specified? Does Jennifer receive what you described? If yes, your ODD project is done."
 
 ---
 

package/skill/docs/planning/build-planner.md

@@ -197,99 +197,142 @@ This is not a test. It is a check that the plan makes intuitive sense to the dom
 
 ---
 
-## Step 9: Technical Architecture
+## Step 9: Technical Architecture — Component-by-Component Decision-Making
 
-The plan is structurally complete. Before the Session Brief is written and the build begins, one more conversation must happen — the most consequential technical decision in the project.
+The plan is structurally complete. Before the Session Brief is written and the build begins, the most consequential technical decisions in the project must happen — and you and the domain expert will make them together, one layer at a time.
 
-Until now, every question you asked was a domain question. You were drawing out knowledge the domain expert already held. This step is different. You — Rachel — are now the expert. The domain expert is listening, evaluating, and ultimately deciding, but the recommendation comes from you.
+This step is fundamentally different from the previous eight. Until now, you drew out knowledge the domain expert already held. Now you bring technical expertise to the table. But expertise does not mean autonomous decision-making. It means presenting options with clear trade-offs, then stepping back while the domain expert chooses.
 
-**Read the full specification before making any recommendation.**
+**Do NOT present a matrix of pre-bundled stacks.** Technology choices are independent — the domain expert should be able to choose Next.js with Supabase and NextAuth, or SvelteKit with Neon and Clerk, or any other valid combination. Each layer is its own decision.
 
-You already have the contract map. Now read everything else:
+**Phase 1: Research and Prepare**
+
+Read the full specification to understand the constraints:
 - Every persona: their context, technical confidence, devices, volume
 - Every walkthrough: load implications, real-time requirements, data complexity, integration needs
 - Every contract: data relationships, how deeply interconnected the outcomes are
 - The phase structure: scale and depth of what is being built
 
-Do not generate a generic recommendation. Generate a recommendation specific to this project, with evidence drawn from the specification.
+**Phase 2: Walk Through Each Decision — One at a Time**
 
-**Make a concrete recommendation — not a list of options.**
+Present each technology layer as its own decision. For each layer, present 3-4 credible options with trade-offs tied to THIS project's specification. Wait for the domain expert to choose before moving to the next layer.
 
-Do not say "here are some technologies you might consider." Say "this is what I recommend, and here is why." Name specific tools. Justify each one using what the specification reveals.
+**The sequence:**
 
-Structure the recommendation as follows:
+1. Framework
+2. Database
+3. Authentication
+4. Hosting & Deployment
+5. Specialist Services (if needed — email, payments, real-time, etc.)
 
----
+For each layer, follow this pattern:
 
-**My recommendation for [project name]:**
+---
 
-[Name the complete stack — framework, database, hosting, any key third-party services such as payments, email, authentication]
+**Decision [N]: [Layer Name]**
 
-**Why this stack:**
+"Now we choose your [layer]. Based on your specification, here are the realistic options:"
 
-For each component, give a specific reason tied to the specification. Reference the walkthrough, the contracts, the persona characteristics. For example:
+**[Option A]**
+- What it is: [one sentence]
+- Why it fits your project: [specific evidence from the specification — reference a persona, outcome, or contract]
+- Trade-off: [what you give up — cost, complexity, lock-in, learning curve]
 
-- "Your data is deeply relational — [Outcome A] produces a record that [Outcome B], [Outcome C], and [Outcome D] all consume, with different fields from each. A relational database handles this natively."
-- "Your [persona]'s walkthrough requires real-time availability counts — the number must update immediately when another user acts. This requires [specific approach]."
-- "You have [n] outcomes with payment flows. [Specific service] handles PCI compliance natively, removing an entire category of security implementation from the build."
+**[Option B]**
+- What it is: [one sentence]
+- Why it fits your project: [specific evidence from the specification]
+- Trade-off: [what you give up]
 
-**What I considered and rejected:**
+**[Option C]**
+- What it is: [one sentence]
+- Why it fits your project: [specific evidence from the specification]
+- Trade-off: [what you give up]
 
-Name the alternatives that a reasonable person might suggest for this kind of project, and explain specifically why they do not fit this specification.
+"Which of these fits best for your project? Are there constraints I don't know about that rule any of these out?"
 
 ---
 
-**Always include in the recommendation: Drizzle and Vitest.**
+**Do not recommend. Offer. Let the domain expert choose.**
 
-Regardless of the other stack choices, these two tools are always part of every recommendation. Do not present alternatives for them unless the domain expert raises a specific existing constraint.
+Wait for their answer. Record it. Move to the next layer.
 
-**Drizzle ORM** — always recommended as the database layer.
+If the domain expert raises a concern:
+- If the concern reveals a constraint you missed: "You are right — I did not weight [constraint] heavily enough. Let me revise."
+- If the concern is a misunderstanding: "I want to clarify — [option] actually handles [capability] this way."
+- If the concern reveals a preference: "That preference carries a trade-off: [concrete consequence]. If you are comfortable with that, we proceed."
 
-Drizzle defines the database structure in the same language as the rest of the project. The build agents know exactly what fields exist, what types they hold, and what relationships connect them — because that knowledge lives in the codebase, not in a separate database that agents can only observe indirectly. Drizzle also handles migrations: every change to the database structure is recorded as a versioned, reversible change and committed to git alongside the code that depends on it. If a field is renamed or a relationship removed, the migration records it — the build agents do not guess.
+**Important rules for each decision:**
+- Never bundle choices together. Framework is independent of database is independent of auth.
+- Never exclude valid combinations. If someone wants Next.js + Supabase + NextAuth, that is a valid stack.
+- Always tie reasoning to the specification. "This fits because Outcome 2.1 requires real-time updates for 90 students" — not "This is popular."
+- If a previous choice constrains the next (e.g., choosing Supabase for database means Supabase Auth is available as an auth option), mention it as context but do not force it.
 
-Explain to the domain expert: "Drizzle is the tool that keeps the AI honest about your data. Without it, build agents are making educated guesses about what is in your database. With it, they know exactly what is there, and every change to that structure is tracked the same way as every change to the code. Drizzle also means that if something goes wrong with the database, we can reverse the last change precisely — the same way git lets us reverse the last code change."
+**Phase 3: Confirm the Fixed Layers**
 
-**Vitest** — always recommended as the testing framework.
+After all choices are made, explain the two components that are included in every ODD Studio project regardless of choice:
 
-Every outcome has a verification checklist — steps the domain expert follows in the browser to confirm the outcome works. But some behaviours cannot be verified by clicking: business rules that run invisibly, calculations, access control logic, the rule that prevents one organiser from editing another's event. Vitest runs automated checks for these. It uses the same configuration as the project's build tooling — no separate setup, no configuration conflict. It runs tests in parallel and completes in seconds. It supports TypeScript natively, so tests share the same type definitions as the code they test.
+**Drizzle ORM** — the database layer that keeps the AI honest.
 
-Explain to the domain expert: "Vitest runs the checks that you cannot run by clicking through the browser — the business rules and calculations that happen invisibly inside the system. Every time an outcome is built, Vitest runs these checks automatically. If a rule that was working correctly breaks because of a new change somewhere else, Vitest catches it before you reach the verification step. Think of it as a safety net underneath the verification you do yourself."
+"Drizzle is the tool that ensures the build agents always know the exact shape of your data. Every field, every type, every relationship lives in your codebase as versioned migrations. When something goes wrong, we can reverse the last change precisely — the same way git lets us reverse code changes. Without Drizzle, agents are guessing about your database. With it, they know."
 
-**Invite genuine pushback.**
+**Vitest** — automated checks for invisible behaviours.
 
-After presenting the recommendation, explicitly invite the domain expert to challenge it:
+"Vitest runs the business rules and calculations you cannot verify by clicking — access control logic, pricing calculations, workflow state transitions. Every outcome built triggers Vitest automatically. If a rule breaks because of a change somewhere else, Vitest catches it before you reach the verification step."
 
-"That is my recommendation based on everything in your specification. I want you to push back if anything does not fit. If you have experience with a different stack, or a constraint I do not know about — a team that uses a specific technology, a budget that rules something out, a compliance requirement — tell me now. This decision is harder to change after the build starts than before."
+These are not negotiable. They exist because the build agents need them, not because of preference.
 
-**Respond to challenges with reasoning, not capitulation.**
+**Phase 4: Summarise and Confirm**
 
-If the domain expert suggests an alternative, engage with it seriously:
-- If the alternative is genuinely suitable: "You are right — [reason]. I had not weighted [factor] heavily enough. Let me revise the recommendation."
-- If the alternative creates a risk: "I understand the preference for [alternative]. I want to make sure you understand the specific trade-off it creates for this project: [concrete consequence tied to the specification]. If you are comfortable with that trade-off, we proceed with [alternative]. If not, [original recommendation] avoids it."
+After all decisions are made, present the complete stack as a summary:
 
-Do not abandon a recommendation simply because the domain expert expresses a preference. The domain expert has the final say — but they should make that decision with full information.
+"Here is the technical stack you have chosen, decision by decision:
 
-**Record the decision in CLAUDE.md.**
+- **Framework**: [chosen] — because [reason from their decision]
+- **Database**: [chosen] — because [reason from their decision]
+- **ORM**: Drizzle (fixed — build agent requirement)
+- **Auth**: [chosen] — because [reason from their decision]
+- **Hosting**: [chosen] — because [reason from their decision]
+- **Testing**: Vitest (fixed — build agent requirement)
+- [Any specialist services]: [chosen] — because [reason from their decision]
 
-When consensus is reached, append a technical decisions section to `CLAUDE.md`:
+Does this look right? Any second thoughts before I record it?"
 
-```
-## Technical Stack
+Wait for confirmation. If they want to change a layer, go back to that specific decision — do not re-run the entire sequence.
+
+**Phase 5: Record the Decision**
 
-Chosen stack: [list each component]
-ORM: Drizzle
-Testing: Vitest
+When the domain expert confirms, record the complete stack in CLAUDE.md and project memory.
 
-Reasoning:
-- [Component]: [why, tied to the specification]
-- [Component]: [why, tied to the specification]
-- Drizzle: type-safe database layer with versioned migrations — build agents always know the exact shape of the data and every change is tracked
-- Vitest: fast, co-located testing with native TypeScript support — catches business rule regressions automatically before verification
+Append a technical decisions section to `CLAUDE.md`:
 
-Considered and rejected:
-- [Alternative]: [why it does not fit this project]
+```
+## Technical Stack
 
-Domain expert constraints applied: [any preferences or constraints the domain expert specified, or "none"]
+**Chosen stack:**
+- Framework: [chosen]
+- Database: [chosen]
+- ORM: Drizzle
+- Auth: [chosen]
+- Testing: Vitest
+- Hosting: [chosen]
+- [Other services]: [chosen]
+
+**Decision reasoning (tied to specification):**
+- Framework: [why, with reference to specific outcome or persona]
+- Database: [why, with reference to specific outcome or persona]
+- Auth: [why, with reference to specific outcome or persona]
+- Hosting: [why, with reference to specific outcome or persona]
+- Drizzle: type-safe database layer with versioned migrations — build agents always know the exact shape of the data and every change is tracked alongside code changes
+- Vitest: automated testing for invisible business rules — catches regressions before verification
+
+**Alternatives considered (per layer):**
+- Framework: [rejected options and why — specific constraint from the specification]
+- Database: [rejected options and why]
+- Auth: [rejected options and why]
+- Hosting: [rejected options and why]
+
+**Domain expert decision notes:**
+[Any specific preferences, constraints, or reasoning the domain expert expressed across the decisions]
 ```
 
 **Store the decision in ruflo memory.**
@@ -297,30 +340,177 @@ Domain expert constraints applied: [any preferences or constraints the domain ex
 Call `mcp__ruflo__memory_store`:
 - Key: `odd-tech-stack`
 - Namespace: `odd-project`
-- Value: the complete technical stack decision including chosen tools, ORM, testing framework, reasoning, and rejected alternatives
+- Value: the complete technical stack decision with per-layer reasoning tied to the specification
 
 **Update `.odd/state.json`:**
 - Set `techStackDecided: true`
-- Set `techStack` to the chosen framework
+- Set `techStack` to the chosen stack description (e.g., "Next.js 16 + Supabase + NextAuth + Vercel")
 - Set `orm` to "Drizzle"
 - Set `testingFramework` to "Vitest"
-- Update `nextStep` to "Set up the project — type *build to scaffold the project and configure your services"
+- Update `nextStep` to "Review UI and Design approach — type *build to continue"
 
-Confirm to the user: "Technical stack recorded in CLAUDE.md and project memory. Every build agent will read this before writing a line of code. When you type *build, I will scaffold the project and guide you through connecting your services."
+Confirm to the user: "Technical stack chosen and recorded. Every build agent will read this before writing a line of code."
+
+---
+
+## Step 9b: UI & Design Decision — Collaborative Visual Planning
+
+With the technical stack decided, the next decision shapes how your personas experience the system: the design approach, layout strategy, visual language, and component philosophy.
+
+This step mirrors Step 9's collaborative structure — you will identify design options, generate wireframes for visual review, and choose the approach that best serves your personas and your domain.
+
+**Phase 1: Understand Design Context**
+
+Read the full specification to identify design constraints:
+
+- **Personas**: Who is using this? What is their technical confidence? Do they need minimal, focused interfaces or rich, data-dense dashboards?
+- **Outcomes**: Which outcomes have screens the persona interacts with? What information must be present, and what can be secondary?
+- **Devices**: Desktop, mobile, tablet, kiosk? Are there accessibility or compliance requirements?
+- **Volume**: High-frequency routine use or occasional intensive sessions? Does interface consistency matter more than density?
+- **Domain language**: Is this a specialized domain with particular conventions (e.g., clinical, financial, legal)? The UI should speak that language.
+
+**Phase 2: Identify Realistic Design Approaches**
+
+Based on the specification, define 3-4 credible design strategies. Include:
+
+1. **Minimalist + Dark (Recommended Default)**
+   - Dark background (slate/zinc), single accent colour, clear borders
+   - Single-column on mobile, grid on desktop
+   - Component library: shadcn/ui + Geist
+   - Philosophy: clarity through space and type
+
+2. **Dense Dashboard + Light**
+   - Light background, information-rich tables and charts
+   - Multi-column layouts designed for desktop-first use
+   - Keyboard shortcuts, advanced filters, inline editing
+   - Philosophy: power users who live in the interface
+
+3. **Minimal + Accessible**
+   - WCAG AAA compliance (not just AA)
+   - High contrast, large touch targets, full keyboard navigation
+   - Screen-reader optimized semantic HTML
+   - Philosophy: inclusive design that serves all personas equally
+
+4. **Brand-Driven + Custom**
+   - Custom design system (if the domain demands visual distinction)
+   - Domain-specific visual language (e.g., clinical software → muted greens, financial → professional grays)
+   - Hand-crafted components specific to this domain
+   - Philosophy: interface as part of the brand experience
+
+Do NOT include absurd alternatives. Every option must be defensible based on your specification.
+
+**Phase 3: Generate Wireframes with Excalidraw**
+
+For each design approach, use the excalidraw skill to generate wireframes showing:
+
+- One key outcome flow (the most important persona interaction)
+- Layout: how information is organized, where navigation lives, how forms and data are presented
+- Component style: buttons, inputs, cards, modals — representative of the chosen approach
+- Mobile variant (if relevant to specification)
+
+Call the excalidraw skill (via `/excalidraw` command) with a prompt like:
+
+```
+Generate wireframes for [Design Approach Name] for our [project name] platform.
+
+Context:
+- Primary persona: [name], a [role]
+- Key outcome: [outcome name] — [one-sentence description of what they do]
+- Approach philosophy: [brief description of this design approach]
+- Devices: [desktop/mobile/both]
+- Visual style: [dark/light, minimalist/dense, etc.]
+
+Show:
+1. Desktop layout of the main interaction
+2. Mobile layout (if applicable)
+3. Key UI components (buttons, inputs, cards) in this style
+4. Navigation pattern
+
+Keep wireframes simple — focus on layout and information hierarchy, not pixel-perfect design.
+```
+
+The excalidraw skill will generate interactive wireframes you can review, iterate on, and export.
+
+**Phase 4: The Domain Expert Reviews and Decides**
+
+Present the wireframes side-by-side and ask:
+
+"I have generated wireframes for four design approaches. Each matches a different priority from your specification:
+
+- **Option A** prioritizes clarity and simplicity — perfect if your personas are occasional users or if the domain is already complex.
+- **Option B** is information-dense — best if your personas spend hours in the system and need to see patterns and relationships at once.
+- **Option C** emphasizes accessibility — ensures every persona, regardless of ability, can use the system equally.
+- **Option D** is custom and domain-specific — creates a visual identity that positions your platform as specialized.
+
+Review the wireframes. Tell me:
+- Which design approach feels most natural for how [persona name] would work?
+- Are there any constraints I missed — device types, accessibility requirements, team design preferences?
+- If you could describe the 'feel' of the interface in three words, what would they be?"
+
+**Do not push a recommendation. Let the domain expert choose based on the wireframes they see.**
+
+**Phase 5: Record the Design Decision**
+
+When the domain expert chooses, record the decision.
+
+Append to `CLAUDE.md`:
+
+```
+## Design Approach
+
+**Chosen design approach:**
+[Design approach name]
+
+**Reasoning (tied to specification):**
+- [Persona]: [why this design serves them, with specific reference to an outcome]
+- [Persona]: [why this design serves them]
+- Information architecture: [how the chosen approach organizes information for this domain]
+- Component library: [shadcn/ui + custom theming OR domain-specific components]
+- Accessibility: [WCAG AA / AAA / custom standards]
+
+**Alternatives considered:**
+- [Option X]: [why it did not fit — specific constraint from the specification]
+- [Option Y]: [why it did not fit — specific constraint from the specification]
+
+**Domain expert decision notes:**
+[Any specific preferences, constraints, or reasoning the domain expert expressed]
+```
+
+Store in ruflo memory:
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-design-approach`
+- Namespace: `odd-project`
+- Value: the complete design decision with reasoning tied to the specification and wireframe references
+
+Update `.odd/state.json`:
+- Set `designApproachDecided: true`
+- Set `designApproach` to the chosen approach name
+- Update `nextStep` to "Type *export to generate the Session Brief, or *build to scaffold and start Phase A"
+
+Confirm to the user: "Design approach chosen and recorded. [Design approach name] will guide all screens in this project. Every build agent will reference these wireframes when implementing the UI."
 
 ---
 
 ## Step 10: Session Brief Export
 
-After the plan is approved, generate the Session Brief — the document a developer or build AI reads at the start of each build session.
+After the plan is approved, generate the first Session Brief — the document a developer or build AI reads at the start of each build session.
+
+**Session briefs are numbered.** Every phase gets its own brief, and all briefs are retained so the project has a complete history:
 
-The Session Brief is saved to `docs/session-brief.md`.
+- `docs/session-brief-0.md` — Phase A (Foundation)
+- `docs/session-brief-1.md` — Phase B (first outcomes)
+- `docs/session-brief-2.md` — Phase C
+- ...and so on.
+
+The first brief generated here is always `docs/session-brief-0.md`.
 
 Structure:
 
 ```markdown
-# Session Brief — [Project Name] — Phase [X]: [Phase Name]
+# Session Brief [N] — [Project Name] — Phase [X]: [Phase Name]
 Generated: [date]
+Phase: [N] of [total]
 
 ## Overview
 [One paragraph describing the project, its domain, and its primary personas]
@@ -334,6 +524,9 @@ Generated: [date]
 ## Contracts In Play
 [Shared contracts needed for this phase, contracts produced by this phase, contracts consumed from previous phases]
 
+## Available From Previous Phases
+[Contracts and infrastructure produced by completed phases — "None" for Phase A]
+
 ## Verification Steps
 [For each outcome: the complete verification checklist from the outcome specification]
 
@@ -345,9 +538,13 @@ Generated: [date]
 
 ## Not In Scope
 [Explicit list of things that are NOT to be built in this phase, to prevent scope creep]
+
+## Changes From Original Plan
+[If this brief was generated after a plan reconciliation: list what changed and why.
+"None — this is the original plan" for the first brief.]
 ```
 
-After writing the Session Brief, confirm: "Session Brief written to docs/session-brief.md. This is the primary input for your build agents. Share it with Claude or any other build AI to start the session."
+After writing the Session Brief, confirm: "Session Brief 0 written to docs/session-brief-0.md. This is the primary input for your build agents."
 
 ---
 
@@ -365,14 +562,15 @@ Confirm to the user: "Master Implementation Plan saved to project memory. All bu
 Also store the Session Brief:
 
 Call `mcp__ruflo__memory_store`:
-- Key: `odd-session-brief-phase-[phase-name]`
+- Key: `odd-session-brief-0`
 - Namespace: `odd-project`
-- Value: the contents of `docs/session-brief.md`
+- Value: the contents of `docs/session-brief-0.md`
 
 Then update `.odd/state.json`:
 - Set `planApproved: true`
 - Populate `planPhases` with the array of phase names in build order
 - Set `currentBuildPhase` to Phase A
+- Set `sessionBriefCount` to 1
 - Update `nextStep` to "Type *build — ODD Studio will scaffold the project, connect your services, and begin Phase A"
 
 ---