odd-studio 2.4.0 → 2.5.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/hooks/odd-destructive-guard.sh

@@ -5,7 +5,10 @@
 # Blocks or warns on shell commands that could cause irreversible damage:
 # rm -rf, overwriting critical files, dropping databases, etc.
 
-COMMAND="${CLAUDE_TOOL_INPUT:-}"
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+if [ "$TOOL_NAME" != "Bash" ]; then exit 0; fi
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
 block() {
   echo "🛡️ ODD DESTRUCTIVE GUARD: $1" >&2

package/hooks/odd-git-safety.sh

@@ -10,7 +10,10 @@
 # Exit 2  → block the command (Claude will not execute it)
 # Stderr  → message shown to the user
 
-COMMAND="${CLAUDE_TOOL_INPUT:-}"
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+if [ "$TOOL_NAME" != "Bash" ]; then exit 0; fi
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
 # ── Helper ────────────────────────────────────────────────────────────────────
 block() {

package/hooks/odd-outcome-quality.sh

@@ -5,7 +5,10 @@
 # Runs after a file is written. If the file is in docs/outcomes/ or docs/personas/,
 # checks for completeness. Provides coaching — does not block.
 
-FILE_PATH="${CLAUDE_TOOL_RESULT_FILE:-}"
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+if [ "$TOOL_NAME" != "Write" ]; then exit 0; fi
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
 
 # ── Only check ODD docs ───────────────────────────────────────────────────────
 if ! echo "$FILE_PATH" | grep -qE 'docs/(outcomes|personas)/'; then

package/hooks/odd-pre-build.sh

@@ -5,7 +5,10 @@
 # Runs before npm run build, npm test, and deployment commands.
 # Checks that ODD project state is sane before the build proceeds.
 
-COMMAND="${CLAUDE_TOOL_INPUT:-}"
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+if [ "$TOOL_NAME" != "Bash" ]; then exit 0; fi
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
 # ── Only intercept build/deploy commands ─────────────────────────────────────
 if ! echo "$COMMAND" | grep -qE '(npm\s+run\s+(build|deploy|start:prod)|yarn\s+(build|deploy)|pnpm\s+(build|deploy))'; then

package/hooks/odd-session-save.sh

@@ -6,7 +6,10 @@
 # so that the next /odd session can resume from exactly this point.
 # Falls back to local .odd/state.json if ruflo is unavailable.
 
-COMMAND="${CLAUDE_TOOL_INPUT:-}"
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+if [ "$TOOL_NAME" != "Bash" ]; then exit 0; fi
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
 # ── Only trigger on git commit ────────────────────────────────────────────────
 if ! echo "$COMMAND" | grep -qE 'git\s+commit'; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "2.4.0",
+  "version": "2.5.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/install-excalidraw.js

@@ -0,0 +1,180 @@
+'use strict';
+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/
+ */
+export default async function installExcalidraw(packageRoot, options = {}) {
+  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);
+  }
+
+  // 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);
+
+  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/skill/docs/planning/build-planner.md

@@ -197,116 +197,288 @@ 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 — Collaborative 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 decision in the project must happen — and you and the domain expert will make it together.
 
-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.**
+**Phase 1: Research and Prepare**
 
-You already have the contract map. Now read everything else:
+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: Identify Realistic Options**
 
-**Make a concrete recommendation — not a list of options.**
+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.
 
-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.
+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.)
 
-Structure the recommendation as follows:
+**Phase 3: Create a Comparison Matrix**
+
+Present the options side-by-side, with specific reasoning tied to THIS project:
+
+---
+
+**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] |
+
+**Detailed reasoning for each option:**
+
+**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 B — [name]**
+- Why it fits: [specific evidence from your specification]
+- What it handles well: [capabilities]
+- 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]
+- Trade-off: [what you give up]
+- Example from your spec: [concrete reference]
 
 ---
 
-**My recommendation for [project name]:**
+**Always include Drizzle and Vitest in every option.**
+
+Regardless of the framework, database, or hosting choices, every stack includes:
+
+**Drizzle ORM** — the database layer that keeps the AI honest.
+
+"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."
+
+**Vitest** — automated checks for invisible behaviours.
+
+"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**
+
+Present the matrix and ask directly:
+
+"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?
+
+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?"
 
-[Name the complete stack — framework, database, hosting, any key third-party services such as payments, email, authentication]
+**Do not recommend. Offer. Let the domain expert choose.**
 
-**Why this stack:**
+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:
 
-For each component, give a specific reason tied to the specification. Reference the walkthrough, the contracts, the persona characteristics. For example:
+- 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."
 
-- "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."
+The domain expert has the final say. They should make that decision with full information, not because they feel pressured.
+
+**Phase 5: Record the Decision**
+
+When the domain expert has chosen, record their decision in CLAUDE.md and project memory.
+
+Append a technical decisions section to `CLAUDE.md`:
+
+```
+## Technical Stack
+
+**Chosen stack:**
+- Framework: [chosen]
+- Database: [chosen]
+- ORM: Drizzle
+- 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]
+- 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]
+
+**Domain expert decision notes:**
+[Any specific preferences, constraints, or reasoning the domain expert expressed]
+```
+
+**Store the decision in ruflo memory.**
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-tech-stack`
+- Namespace: `odd-project`
+- Value: the complete technical stack decision with reasoning tied to the specification
 
-**What I considered and rejected:**
+**Update `.odd/state.json`:**
+- Set `techStackDecided: true`
+- Set `techStack` to the chosen stack description (e.g., "Next.js 16 + Neon PostgreSQL + Vercel + Clerk")
+- Set `orm` to "Drizzle"
+- Set `testingFramework` to "Vitest"
+- Update `nextStep` to "Review UI and Design approach — type *build to continue"
 
-Name the alternatives that a reasonable person might suggest for this kind of project, and explain specifically why they do not fit this specification.
+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."
 
 ---
 
-**Always include in the recommendation: Drizzle and Vitest.**
+## 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.
 
-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.
+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.
 
-**Drizzle ORM** — always recommended as the database layer.
+**Phase 1: Understand Design Context**
 
-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.
+Read the full specification to identify design constraints:
 
-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."
+- **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.
 
-**Vitest** — always recommended as the testing framework.
+**Phase 2: Identify Realistic Design Approaches**
 
-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.
+Based on the specification, define 3-4 credible design strategies. Include:
 
-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."
+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
 
-**Invite genuine pushback.**
+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
 
-After presenting the recommendation, explicitly invite the domain expert to challenge it:
+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
 
-"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."
+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
 
-**Respond to challenges with reasoning, not capitulation.**
+Do NOT include absurd alternatives. Every option must be defensible based on your specification.
 
-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."
+**Phase 3: Generate Wireframes with Excalidraw**
 
-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.
+For each design approach, use the excalidraw skill to generate wireframes showing:
 
-**Record the decision in CLAUDE.md.**
+- 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)
 
-When consensus is reached, append a technical decisions section to `CLAUDE.md`:
+Call the excalidraw skill (via `/excalidraw` command) with a prompt like:
 
 ```
-## Technical Stack
+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.
 
-Chosen stack: [list each component]
-ORM: Drizzle
-Testing: Vitest
+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?"
 
-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
+**Do not push a recommendation. Let the domain expert choose based on the wireframes they see.**
 
-Considered and rejected:
-- [Alternative]: [why it does not fit this project]
+**Phase 5: Record the Design Decision**
+
+When the domain expert chooses, record the decision.
+
+Append to `CLAUDE.md`:
 
-Domain expert constraints applied: [any preferences or constraints the domain expert specified, or "none"]
 ```
+## Design Approach
 
-**Store the decision in ruflo memory.**
+**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-tech-stack`
+- Key: `odd-design-approach`
 - Namespace: `odd-project`
-- Value: the complete technical stack decision including chosen tools, ORM, testing framework, reasoning, and rejected alternatives
+- Value: the complete design decision with reasoning tied to the specification and wireframe references
 
-**Update `.odd/state.json`:**
-- Set `techStackDecided: true`
-- Set `techStack` to the chosen framework
-- 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 `.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: "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: "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."
 
 ---