odd-studio 2.5.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "2.5.0",
+  "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

@@ -2,15 +2,15 @@
 import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
-import { execSync } from 'child_process';
 
 /**
  * Installs the excalidraw skill into Claude Code.
  *
- * This creates a wrapper skill that calls the excalidraw system to generate wireframes.
- * The skill is installed to ~/.claude/skills/excalidraw/
+ * 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
@@ -22,159 +22,8 @@ export default async function installExcalidraw(packageRoot, options = {}) {
     await fs.move(destination, backup);
   }
 
-  // Create the excalidraw skill wrapper directory
-  await fs.ensureDir(destination);
-
-  // Create the SKILL.md manifest
-  const skillManifest = `---
-name: excalidraw
-description: Wireframe and diagram generation for UI/design planning
-version: 1.0.0
-author: ODD Studio
-source: https://github.com/excalidraw/excalidraw
-tags:
-  - ui-design
-  - wireframing
-  - planning
-  - visualization
----
-
-# Excalidraw Wireframe Generator
-
-Generate interactive wireframes and diagrams for design planning, prototyping, and visual communication.
-
-## Installation
-
-This skill is automatically installed by ODD Studio during project initialization.
-
-## Usage
-
-Use the excalidraw skill to generate wireframes for design review:
-
-\`\`\`
-/excalidraw
-
-Generate wireframes for [Design Approach Name] for our [project name] platform.
-
-Context:
-- Primary persona: [name], a [role]
-- Key outcome: [outcome name] — [description]
-- Approach philosophy: [design approach philosophy]
-- Devices: [device types]
-- Visual style: [style description]
-
-Show:
-1. Desktop layout
-2. Mobile layout (if applicable)
-3. Key UI components
-4. Navigation pattern
-\`\`\`
-
-## When to Use
-
-- **Step 9b of Build Planning**: Generate wireframes for different design approach options
-- **UI Design Review**: Create visual mockups for domain expert feedback
-- **System Architecture Documentation**: Diagram system flows and component relationships
-- **Accessibility Planning**: Sketch layouts with accessibility requirements in mind
-
-## Features
-
-- Interactive canvas — edit and iterate on wireframes in real-time
-- Infinite canvas — zoom and pan without limits
-- Collaboration-ready — export diagrams for sharing with team members
-- Library support — use common UI patterns and components
-- Multiple export formats — PNG, SVG, JSON for further editing
-
-## Integration with ODD Studio
-
-Excalidraw is deeply integrated into the ODD planning workflow:
-
-1. **Step 9 (Technical Architecture)**: Plan database and framework choices
-2. **Step 9b (UI & Design Decision)**: Generate 3-4 design approach wireframes using excalidraw
-3. **Step 10 (Session Brief)**: Include wireframe references in the build specification
-4. **Build Phase**: Build agents reference wireframes when implementing UI
-
-## Notes
-
-- Wireframes generated in Step 9b are stored as \`.excalidraw\` files in \`docs/wireframes/\`
-- Each design approach option gets its own wireframe file
-- Domain expert selects preferred design from the wireframes
-- Selected design is recorded in \`CLAUDE.md\` under \`Design Approach\`
-`;
-
-  await fs.writeFile(path.join(destination, 'SKILL.md'), skillManifest);
-
-  // Create a README for setup instructions
-  const readmeContent = `# Excalidraw Skill for ODD Studio
-
-This skill enables interactive wireframe and diagram generation within the ODD planning workflow.
-
-## What Is Excalidraw?
-
-Excalidraw is a virtual whiteboard application for creating hand-drawn style diagrams, wireframes, and architectural sketches. It's simple, intuitive, and designed for collaborative design planning.
-
-## Auto-Installed Components
-
-When you run \`npx odd-studio init\`, this skill is automatically installed with:
-
-- Claude Code integration configuration
-- ODD Studio-specific prompts and templates
-- Wireframing guidelines for design approach decisions
-- Export templates for Session Brief integration
-
-## Using Excalidraw in ODD Studio
-
-### Step 9b: Design Planning
-
-When Rachel (the Build Planner) reaches Step 9b (UI & Design Decision), you'll generate wireframes for each design approach option:
-
-\`\`\`
-/excalidraw
-
-Generate wireframes for [Design Approach] for [project name].
-
-Context:
-- Primary persona: [name]
-- Key outcome: [outcome]
-- Approach: [philosophy]
-- Devices: [device types]
-
-Show: Desktop layout, mobile (if applicable), key components, navigation
-\`\`\`
-
-### Exporting Wireframes
-
-Export each set of wireframes as:
-- **Interactive .excalidraw file** — for iterating and refining
-- **PNG image** — for sharing with domain expert
-- **SVG vector** — for including in documentation
-
-Save wireframes to \`docs/wireframes/[design-approach-name]/\`
-
-### In the Session Brief
-
-Reference wireframes in the Session Brief under the UI section:
-
-\`\`\`markdown
-## Design Approach
-
-[Design approach name]
-
-See wireframes at: docs/wireframes/[design-approach-name]/
-\`\`\`
-
-## Browser-Based
-
-Excalidraw works in any modern browser. If you have a local Excalidraw instance running, Claude Code will use it. Otherwise, the skill links to the official web version.
-
-## Documentation
-
-- Official Excalidraw docs: https://excalidraw.com/
-- Excalidraw GitHub: https://github.com/excalidraw/excalidraw
-- ODD Studio integration guide: See \`SKILL.md\`
-`;
-
-  await fs.writeFile(path.join(destination, 'README.md'), readmeContent);
+  // Copy the excalidraw skill directory (contains SKILL.md with generation logic)
+  await fs.copy(source, destination);
 
   return { destination };
 }

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,12 +197,14 @@ This is not a test. It is a check that the plan makes intuitive sense to the dom
 
 ---
 
-## Step 9: Technical Architecture — Collaborative Decision-Making
+## Step 9: Technical Architecture — Component-by-Component Decision-Making
 
-The plan is structurally complete. Before the Session Brief is written and the build begins, the most consequential technical decision in the project must happen — and you and the domain expert will make it together.
+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.
 
 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.
 
+**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.
+
 **Phase 1: Research and Prepare**
 
 Read the full specification to understand the constraints:
@@ -211,59 +213,63 @@ Read the full specification to understand the constraints:
 - Every contract: data relationships, how deeply interconnected the outcomes are
 - The phase structure: scale and depth of what is being built
 
-**Phase 2: Identify Realistic Options**
+**Phase 2: Walk Through Each Decision — One at a Time**
 
-Based on this project's specification, identify 3-4 realistic technology stacks. Do NOT include absurd alternatives that no reasonable person would suggest. Include only credible options that would work for this kind of project.
+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.
 
-For each option, identify:
-- Core framework (Next.js, SvelteKit, Remix, Astro, etc.)
-- Database (PostgreSQL + Drizzle, MongoDB, Supabase, etc.)
-- Hosting (Vercel, AWS, self-hosted, etc.)
-- Authentication method (Clerk, Auth0, NextAuth, etc.)
-- Any specialized services (Stripe for payments, Resend for email, etc.)
+**The sequence:**
 
-**Phase 3: Create a Comparison Matrix**
+1. Framework
+2. Database
+3. Authentication
+4. Hosting & Deployment
+5. Specialist Services (if needed — email, payments, real-time, etc.)
 
-Present the options side-by-side, with specific reasoning tied to THIS project:
+For each layer, follow this pattern:
 
 ---
 
-**Technical Stack Options for [project name]:**
-
-| Component | Option A | Option B | Option C |
-|-----------|----------|----------|----------|
-| **Framework** | Next.js (App Router) | SvelteKit | Remix |
-| **Database + ORM** | PostgreSQL + Drizzle | MongoDB | Supabase (PostgreSQL) |
-| **Hosting** | Vercel | AWS Lambda | Self-hosted |
-| **Testing** | Vitest | Jest | Vitest |
-| **Best for** | [reason specific to spec] | [reason specific to spec] | [reason specific to spec] |
-| **Trade-off** | [specific cost] | [specific cost] | [specific cost] |
+**Decision [N]: [Layer Name]**
 
-**Detailed reasoning for each option:**
+"Now we choose your [layer]. Based on your specification, here are the realistic options:"
 
-**Option A — [name]**
-- Why it fits: [specific evidence from your specification: personas, walkthroughs, contracts]
-- What it handles well: [capabilities aligned to your outcomes]
-- Trade-off: [what you give up — complexity, cost, learning curve, etc.]
-- Example from your spec: [concrete reference to a outcome or persona that this solves for]
+**[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]
 
-**Option B — [name]**
-- Why it fits: [specific evidence from your specification]
-- What it handles well: [capabilities]
+**[Option B]**
+- What it is: [one sentence]
+- Why it fits your project: [specific evidence from the specification]
 - Trade-off: [what you give up]
-- Example from your spec: [concrete reference]
 
-**Option C — [name]**
-- Why it fits: [specific evidence from your specification]
-- What it handles well: [capabilities]
+**[Option C]**
+- What it is: [one sentence]
+- Why it fits your project: [specific evidence from the specification]
 - Trade-off: [what you give up]
-- Example from your spec: [concrete reference]
+
+"Which of these fits best for your project? Are there constraints I don't know about that rule any of these out?"
 
 ---
 
-**Always include Drizzle and Vitest in every option.**
+**Do not recommend. Offer. Let the domain expert choose.**
+
+Wait for their answer. Record it. Move to the next layer.
 
-Regardless of the framework, database, or hosting choices, every stack includes:
+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."
+
+**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.
+
+**Phase 3: Confirm the Fixed Layers**
+
+After all choices are made, explain the two components that are included in every ODD Studio project regardless of choice:
 
 **Drizzle ORM** — the database layer that keeps the AI honest.
 
@@ -273,30 +279,29 @@ Regardless of the framework, database, or hosting choices, every stack includes:
 
 "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."
 
-**Phase 4: The Domain Expert Decides**
+These are not negotiable. They exist because the build agents need them, not because of preference.
 
-Present the matrix and ask directly:
+**Phase 4: Summarise and Confirm**
 
-"I have identified three realistic technical stacks for your project. Each solves different constraints from your specification. Review them: the trade-offs are real, not cosmetic. Which approach best matches your priorities?
+After all decisions are made, present the complete stack as a summary:
 
-Tell me:
-- Which option resonates with you, and why?
-- Are there constraints I do not know about — a team preference, a budget limit, a compliance requirement — that rules out any option?
-- Do you have experience with any of these that would make you more confident with one option?"
-
-**Do not recommend. Offer. Let the domain expert choose.**
+"Here is the technical stack you have chosen, decision by decision:
 
-Listen to their choice. If they choose one of the options as presented, move to Phase 5. If they raise a concern about an option, address it:
+- **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]
 
-- If the concern reveals a constraint you missed: "You are right — I did not weight [constraint] heavily enough. Let me revise the options."
-- If the concern is a misunderstanding: "I want to clarify — [component] in [Option X] actually handles [capability] this way, because of [specific feature]."
-- If the concern reveals a preference: "I understand the preference for [alternative]. This choice carries a trade-off: [concrete consequence]. If you are comfortable with that, we proceed. If not, [other option] avoids it."
+Does this look right? Any second thoughts before I record it?"
 
-The domain expert has the final say. They should make that decision with full information, not because they feel pressured.
+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**
 
-When the domain expert has chosen, record their decision in CLAUDE.md and project memory.
+When the domain expert confirms, record the complete stack in CLAUDE.md and project memory.
 
 Append a technical decisions section to `CLAUDE.md`:
 
@@ -307,22 +312,27 @@ Append a technical decisions section to `CLAUDE.md`:
 - Framework: [chosen]
 - Database: [chosen]
 - ORM: Drizzle
+- Auth: [chosen]
 - Testing: Vitest
 - Hosting: [chosen]
 - [Other services]: [chosen]
 
-**Reasoning (tied to specification):**
-- [Component]: [why, with reference to specific outcome or persona]
-- [Component]: [why, with reference to specific outcome or persona]
+**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:**
-- [Option X]: [why it did not fit — specific constraint from the specification]
-- [Option Y]: [why it did not fit — specific constraint from the specification]
+**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]
+[Any specific preferences, constraints, or reasoning the domain expert expressed across the decisions]
 ```
 
 **Store the decision in ruflo memory.**
@@ -330,16 +340,16 @@ Append a technical decisions section to `CLAUDE.md`:
 Call `mcp__ruflo__memory_store`:
 - Key: `odd-tech-stack`
 - Namespace: `odd-project`
-- Value: the complete technical stack decision with reasoning tied to the specification
+- 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 stack description (e.g., "Next.js 16 + Neon PostgreSQL + Vercel + Clerk")
+- 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 "Review UI and Design approach — type *build to continue"
 
-Confirm to the user: "Technical stack chosen and recorded. [Stack name] will be used for this project. Every build agent will read this before writing a line of code."
+Confirm to the user: "Technical stack chosen and recorded. Every build agent will read this before writing a line of code."
 
 ---
 
@@ -484,15 +494,23 @@ Confirm to the user: "Design approach chosen and recorded. [Design approach name
 
 ## 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.
 
-The Session Brief is saved to `docs/session-brief.md`.
+**Session briefs are numbered.** Every phase gets its own brief, and all briefs are retained so the project has a complete history:
+
+- `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]
@@ -506,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]
 
@@ -517,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."
 
 ---
 
@@ -537,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"
 
 ---