odd-studio 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "odd-studio",
+  "description": "Outcome-Driven Development — a planning and build harness for domain experts building serious software with AI. Installs the /odd skill, safety hooks, and project scaffolding into Claude Code.",
+  "version": "1.0.0",
+  "author": {
+    "name": "ODD Studio"
+  },
+  "skills": [
+    "odd"
+  ],
+  "hooks": [
+    "odd-git-safety",
+    "odd-destructive-guard",
+    "odd-outcome-quality",
+    "odd-ui-check",
+    "odd-pre-build",
+    "odd-session-save"
+  ]
+}

package/README.md

@@ -0,0 +1,229 @@
+# ODD Studio
+
+**Outcome-Driven Development for Claude Code.**
+
+A planning and build harness for domain experts who are building serious software with AI — and want to understand exactly what they're doing and why.
+
+---
+
+## What this is
+
+ODD Studio turns Claude Code into a guided coach that takes you through every stage of building a real software system: from understanding your users, to specifying what the system must do, to directing an AI to build it correctly, to verifying that what was built matches what you intended.
+
+You don't need to write code. You need to understand your domain. That's the skill that matters now.
+
+> *"The AI is the most capable junior engineer who ever lived. It can build anything you describe. It will build exactly what you describe. It will not tell you that what you described is the wrong thing to build. That judgement remains entirely yours."*
+
+ODD Studio is the companion tool to **[Book Title]** — the book that teaches Outcome-Driven Development from first principles. Every step in the tool references the relevant chapter. You'll understand the method as you use it, not just follow instructions.
+
+---
+
+## Install
+
+```bash
+npx odd-studio init my-project
+```
+
+That's it. This single command:
+
+- Scaffolds your project structure (`docs/`, `.odd/`, `CLAUDE.md`)
+- Installs the `/odd` skill into Claude Code
+- Installs six safety hooks into your Claude Code settings
+- Initialises git with an initial commit
+- Prints your three next steps
+
+**Then:**
+
+```bash
+cd my-project
+claude .
+```
+
+Inside Claude Code, type:
+
+```
+/odd
+```
+
+---
+
+## What happens when you type `/odd`
+
+Claude Code loads the ODD orchestrator. It checks whether you have an existing project in progress (via your local `.odd/state.json` and ruflo memory) and either:
+
+- **New project:** Welcomes you, explains what you're about to build together, and starts with the first question: *Who uses this system, and what do they actually need?*
+- **Returning project:** Shows you exactly where you left off and resumes from there. Nothing is lost between sessions.
+
+---
+
+## The five stages
+
+ODD Studio guides you through five stages, in order. You cannot skip ahead — each stage is the foundation for the next.
+
+```
+Stage 1 — Personas
+  Who uses your system? Under what constraints?
+  Built by: Diana (Persona Architect)
+  Output: docs/personas/[name].md for each user type
+
+Stage 2 — Outcomes
+  What must the system make possible, for whom, when, and how?
+  Built by: Marcus (Outcome Writer)
+  Output: docs/outcomes/[name].md for each workflow
+
+Stage 3 — Contracts
+  What does each outcome produce that others depend on?
+  Built by: Theo (Systems Mapper)
+  Output: docs/contract-map.md
+
+Stage 4 — Master Implementation Plan
+  What gets built in what order, and why?
+  Built by: Rachel (Build Planner)
+  Output: docs/plan.md
+
+Stage 5 — Build
+  Direct Claude Code to build outcome by outcome, verify each one,
+  and integrate them into a working system.
+  Powered by: ruflo swarm (parallel specialist agents)
+```
+
+At every step, the tool explains why the step matters — not just what to do.
+
+---
+
+## The safety layer
+
+ODD Studio installs six hooks into Claude Code that run automatically throughout your build:
+
+| Hook | When | What it does |
+|------|------|-------------|
+| `odd-git-safety` | Before any bash command | Blocks force-push, hard-reset with uncommitted changes, `git checkout -- .`, `--no-verify` |
+| `odd-destructive-guard` | Before any bash command | Blocks `rm -rf` on project docs, `.env` commits, database drops without warning |
+| `odd-outcome-quality` | After writing to `docs/outcomes/` | Checks all 6 outcome fields are present; flags banned technical vocabulary |
+| `odd-ui-check` | After editing frontend files | Surfaces accessibility reminders; prompts mobile verification |
+| `odd-pre-build` | Before `npm run build` or deploy | Warns on uncommitted changes before deploy; flags unreviewed outcomes |
+| `odd-session-save` | After `git commit` | Saves project state to `.odd/state.json` for session continuity |
+
+These hooks inform and protect — they don't block legitimate work. The git hooks block genuinely destructive actions (force-push onto main, committing secrets). Everything else warns and coaches.
+
+---
+
+## The build layer (ruflo)
+
+When you're ready to build, ODD Studio initialises a ruflo swarm — a team of parallel specialist agents that build your outcomes concurrently:
+
+- **Coordinator** — reads your contracts, publishes shared technical contracts before parallel building begins (solves the "two architects, one door" problem)
+- **Backend agent** — implements data layer and business logic per your outcome specifications
+- **UI agent** — implements the frontend using shadcn/ui, Tailwind CSS v4, and Framer Motion, against WCAG 2.1 AA accessibility standards
+- **QA agent** — runs your verification steps and reports failures in your language, not technical error messages
+
+Ruflo memory ensures continuity across Claude Code sessions — every agent knows the full project state.
+
+---
+
+## Default tech stack
+
+ODD Studio configures a considered default stack that handles 90% of projects well:
+
+| Layer | Technology | Why |
+|-------|-----------|-----|
+| Framework | Next.js (App Router) + TypeScript | Server-rendered, fast, well-supported |
+| Styling | Tailwind CSS v4 | Consistent design without custom CSS |
+| Components | shadcn/ui | Beautiful, accessible, you own the code |
+| Primitives | Radix UI | Keyboard navigation and ARIA built in |
+| Animation | Framer Motion | Micro-interactions without complexity |
+| Database | PostgreSQL via Prisma | Reliable, type-safe, good migrations |
+| Auth | NextAuth.js | Handles the complexity you don't want to |
+| Payments | Stripe | The right choice for most use cases |
+| Email | Resend | Modern, reliable, developer-friendly |
+| Deploy | Vercel | Zero-configuration deployment |
+
+The AI proposes the stack based on your outcomes. You approve it based on consequences, not technical details. If your outcomes require something different (offline-capable, specific hosting requirements, existing systems to integrate with), tell the AI in domain terms and it will adapt.
+
+---
+
+## Project structure
+
+After `odd-studio init`, your project looks like this:
+
+```
+my-project/
+├── CLAUDE.md                    ← ODD build rules for Claude Code
+├── .odd/
+│   └── state.json               ← Project state (updated automatically)
+└── docs/
+    ├── plan.md                  ← Master Implementation Plan
+    ├── contract-map.md          ← Contracts and dependency graph
+    ├── personas/                ← One file per user type
+    │   └── example-persona.md  ← Example to learn from (then delete)
+    ├── outcomes/                ← One file per workflow
+    │   └── example-outcome.md  ← Example to learn from (then delete)
+    └── ui/                     ← UI specifications per outcome
+```
+
+---
+
+## Commands inside `/odd`
+
+```
+*plan          Start or resume planning (routes to the right stage)
+*build         Start or resume building with ruflo swarm
+*status        Show full project state
+*persona       Jump to persona creation
+*outcome       Jump to outcome writing
+*contracts     Jump to contract mapping
+*phase-plan    Jump to implementation planning
+*ui            Load UI excellence layer briefing
+*swarm         Initialise ruflo swarm for parallel build
+*export        Generate IDE Session Brief → docs/session-brief.md
+*chapter [n]   Load coaching from relevant book chapter
+*why           Explain why the current step matters
+*kb            Load full ODD knowledge base
+*help          Show all commands
+*reset         Clear state and start over (asks for confirmation)
+```
+
+---
+
+## Other CLI commands
+
+```bash
+odd-studio status    # Show current planning state for this project
+odd-studio upgrade   # Update the /odd skill and hooks to latest version
+odd-studio export    # Instructions for exporting the Session Brief
+```
+
+---
+
+## What you'll learn
+
+By the time you've built your first system with ODD Studio, you'll understand:
+
+- Why your users' constraints — not their preferences — determine good software design
+- Why the connections between features matter more than the features themselves
+- How to describe what you want precisely enough that an AI builds it correctly
+- How to verify that what was built matches what you intended
+- How to direct a build across multiple sessions without losing context
+- How to catch problems before they become expensive to fix
+
+These are the skills that make you effective at building with AI — permanently, not just for this project.
+
+---
+
+## The book
+
+ODD Studio implements the methodology from **[Book Title]**. Each step in the tool references the chapter that explains the underlying principle. The book and the tool are the same learning experience — you can start with either.
+
+---
+
+## Requirements
+
+- Node.js 18+
+- Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
+- ruflo MCP configured in Claude Code (for swarm build features)
+
+---
+
+## License
+
+MIT

package/bin/odd-studio.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+'use strict';
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs-extra';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+
+// ─── Visual helpers ──────────────────────────────────────────────────────────
+
+const print = {
+  logo: () => {
+    console.log(chalk.bold.cyan('\n  🎯 ODD Studio'));
+    console.log(chalk.dim('  Outcome-Driven Development for Claude Code\n'));
+  },
+  step: (n, total, msg) => console.log(chalk.dim(`  [${n}/${total}]`) + ' ' + msg),
+  ok: (msg) => console.log(chalk.green('  ✓ ') + msg),
+  warn: (msg) => console.log(chalk.yellow('  ⚠ ') + msg),
+  err: (msg) => console.log(chalk.red('  ✗ ') + msg),
+  info: (msg) => console.log(chalk.dim('  → ') + msg),
+  blank: () => console.log(),
+};
+
+// ─── CLI definition ───────────────────────────────────────────────────────────
+
+program
+  .name('odd-studio')
+  .description('Outcome-Driven Development harness for Claude Code')
+  .version(pkg.version);
+
+// ── 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)')
+  .option('--skip-hooks', 'Skip installing safety hooks (not recommended)')
+  .option('--yes', 'Accept all defaults without prompting')
+  .action(async (projectName, options) => {
+    print.logo();
+
+    const { default: installSkill } = await import('../scripts/install-skill.js');
+    const { default: setupHooks } = await import('../scripts/setup-hooks.js');
+    const { default: scaffoldProject } = await import('../scripts/scaffold-project.js');
+
+    // Resolve project directory
+    const targetDir = projectName
+      ? path.resolve(process.cwd(), projectName)
+      : process.cwd();
+
+    const resolvedName = projectName || path.basename(process.cwd());
+
+    console.log(chalk.bold(`  Setting up: ${chalk.cyan(resolvedName)}\n`));
+
+    // 1. Scaffold project structure
+    print.step(1, 3, 'Creating project structure...');
+    const spinner1 = ora({ text: '', indent: 4 }).start();
+    try {
+      await scaffoldProject(targetDir, resolvedName);
+      spinner1.stop();
+      print.ok('Project scaffolded at ' + chalk.cyan(targetDir));
+    } catch (e) {
+      spinner1.stop();
+      print.err('Failed to scaffold project: ' + e.message);
+      process.exit(1);
+    }
+
+    // 2. Install /odd skill
+    if (!options.skipSkill) {
+      print.step(2, 3, 'Installing /odd skill into Claude Code...');
+      const spinner2 = ora({ text: '', indent: 4 }).start();
+      try {
+        const result = await installSkill(PACKAGE_ROOT);
+        spinner2.stop();
+        print.ok('Skill installed → ' + chalk.cyan(result.destination));
+      } catch (e) {
+        spinner2.stop();
+        print.warn('Could not install skill automatically: ' + e.message);
+        print.info('Manual install: copy ' + chalk.dim('skill/') + ' to ' + chalk.dim('~/.claude/skills/odd/'));
+      }
+    } else {
+      print.step(2, 3, 'Skipping skill install (--skip-skill)');
+      print.warn('Remember to install the skill manually for /odd to work in Claude Code.');
+    }
+
+    // 3. Setup hooks
+    if (!options.skipHooks) {
+      print.step(3, 3, 'Installing safety hooks into Claude Code settings...');
+      const spinner3 = ora({ text: '', indent: 4 }).start();
+      try {
+        const result = await setupHooks(PACKAGE_ROOT);
+        spinner3.stop();
+        print.ok('Hooks installed → ' + result.hookCount + ' hooks active');
+      } catch (e) {
+        spinner3.stop();
+        print.warn('Could not install hooks automatically: ' + e.message);
+        print.info('Manual install: add entries from ' + chalk.dim('hooks/') + ' to ~/.claude/settings.json');
+      }
+    } else {
+      print.step(3, 3, 'Skipping hooks (--skip-hooks)');
+      print.warn('Safety hooks not installed. Git guardrails and quality gates will not run.');
+    }
+
+    // ── Done ──
+    print.blank();
+    console.log(chalk.bold.green('  ✓ ODD Studio is ready.\n'));
+
+    console.log(chalk.bold('  Next steps:'));
+    console.log(chalk.dim('  ─────────────────────────────────────────'));
+    if (projectName) {
+      console.log('  1. ' + chalk.cyan(`cd ${projectName}`));
+    }
+    console.log('  ' + (projectName ? '2' : '1') + '. Open Claude Code: ' + chalk.cyan('claude .'));
+    console.log('  ' + (projectName ? '3' : '2') + '. Start your ODD session: ' + chalk.cyan('/odd'));
+    print.blank();
+
+    console.log(chalk.dim('  ODD Studio implements Outcome-Driven Development.'));
+    console.log(chalk.dim('  At every step, you\'ll understand why — not just what to do.'));
+    print.blank();
+  });
+
+// ── status ────────────────────────────────────────────────────────────────────
+program
+  .command('status')
+  .description('Show the ODD planning status for the current project')
+  .action(async () => {
+    print.logo();
+    const stateFile = path.resolve(process.cwd(), '.odd', 'state.json');
+    if (!fs.existsSync(stateFile)) {
+      print.warn('No ODD state found in this directory.');
+      print.info('Run ' + chalk.cyan('odd-studio init') + ' to initialise a project, or ' + chalk.cyan('cd') + ' into an existing ODD project.');
+      process.exit(0);
+    }
+    const state = await fs.readJson(stateFile);
+    console.log(chalk.bold('  Project: ') + chalk.cyan(state.projectName || 'unnamed'));
+    console.log(chalk.bold('  Phase:   ') + (state.currentPhase || 'Not started'));
+    console.log(chalk.bold('  Step:    ') + (state.currentStep || 'Not started'));
+    print.blank();
+    if (state.personas?.length) {
+      console.log(chalk.bold('  Personas (' + state.personas.length + '):'));
+      state.personas.forEach(p => console.log('    ' + chalk.green('✓ ') + p));
+    }
+    if (state.outcomes?.length) {
+      console.log(chalk.bold('  Outcomes (' + state.outcomes.length + '):'));
+      state.outcomes.forEach(o => {
+        const icon = o.status === 'verified' ? chalk.green('✓') : o.status === 'reviewed' ? chalk.yellow('◑') : chalk.dim('○');
+        console.log('    ' + icon + ' ' + o.name + chalk.dim(' [' + (o.status || 'draft') + ']'));
+      });
+    }
+    print.blank();
+    console.log(chalk.dim('  Open Claude Code and type /odd to resume.'));
+    print.blank();
+  });
+
+// ── upgrade ───────────────────────────────────────────────────────────────────
+program
+  .command('upgrade')
+  .description('Upgrade the /odd skill and hooks to the latest version')
+  .action(async () => {
+    print.logo();
+    const { default: installSkill } = await import('../scripts/install-skill.js');
+    const { default: setupHooks } = await import('../scripts/setup-hooks.js');
+
+    console.log(chalk.bold('  Upgrading ODD Studio...\n'));
+
+    const s1 = ora({ text: 'Updating /odd skill...', indent: 4 }).start();
+    try {
+      await installSkill(PACKAGE_ROOT, { force: true });
+      s1.succeed('Skill updated');
+    } catch (e) {
+      s1.fail('Skill update failed: ' + e.message);
+    }
+
+    const s2 = ora({ text: 'Updating hooks...', indent: 4 }).start();
+    try {
+      await setupHooks(PACKAGE_ROOT, { force: true });
+      s2.succeed('Hooks updated');
+    } catch (e) {
+      s2.fail('Hooks update failed: ' + e.message);
+    }
+
+    print.blank();
+    print.ok('Upgrade complete.');
+    print.blank();
+  });
+
+// ── export ────────────────────────────────────────────────────────────────────
+program
+  .command('export')
+  .description('Export the IDE Session Brief from current project state')
+  .action(async () => {
+    print.logo();
+    const stateFile = path.resolve(process.cwd(), '.odd', 'state.json');
+    if (!fs.existsSync(stateFile)) {
+      print.err('No ODD state found. Run odd-studio init first.');
+      process.exit(1);
+    }
+    print.info('Open Claude Code and run: ' + chalk.cyan('/odd') + ' then ' + chalk.cyan('*export'));
+    print.info('The Session Brief will be saved to ' + chalk.cyan('docs/session-brief.md'));
+    print.blank();
+  });
+
+program.parse();

package/hooks/odd-destructive-guard.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# odd-destructive-guard.sh
+# ODD Studio — Destructive Command Guard (PreToolUse: Bash)
+#
+# Blocks or warns on shell commands that could cause irreversible damage:
+# rm -rf, overwriting critical files, dropping databases, etc.
+
+COMMAND="${CLAUDE_TOOL_INPUT:-}"
+
+block() {
+  echo "🛡️ ODD DESTRUCTIVE GUARD: $1" >&2
+  echo "" >&2
+  echo "$2" >&2
+  exit 2
+}
+
+warn() {
+  echo "⚠️  ODD DESTRUCTIVE GUARD WARNING: $1" >&2
+  echo "$2" >&2
+}
+
+# ── rm -rf ────────────────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)'; then
+  TARGET=$(echo "$COMMAND" | grep -oE 'rm\s+-[a-zA-Z]+\s+\S+' | awk '{print $3}')
+
+  # Always block rm -rf on common dangerous targets
+  if echo "$TARGET" | grep -qE '^(/|~|\$HOME|\.\.)'; then
+    block \
+      "rm -rf on root-level or parent directory: $TARGET" \
+      "This would recursively delete critical system or project files.
+ODD Studio always blocks rm -rf on potentially dangerous paths."
+  fi
+
+  # Block rm -rf on the project docs/ directory
+  if echo "$TARGET" | grep -qE '(docs|personas|outcomes|plan\.md|contract-map)'; then
+    block \
+      "rm -rf on ODD project documentation: $TARGET" \
+      "This would destroy your persona, outcome, and plan documents.
+These are your build specifications — deleting them means losing your planning work.
+If you genuinely need to remove a file, delete it specifically by name."
+  fi
+
+  # Block rm -rf on .claude/
+  if echo "$TARGET" | grep -qE '\.claude'; then
+    block \
+      "rm -rf on .claude/ directory." \
+      "This would remove your Claude Code skills, hooks, and settings.
+Run 'odd-studio upgrade' to update, or edit settings manually."
+  fi
+
+  # Warn (don't block) on other rm -rf
+  warn \
+    "rm -rf detected: $COMMAND" \
+    "Ensure this is intentional — recursive deletion cannot be undone."
+fi
+
+# ── Overwriting .env files ────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE '>\s*\.env(\s|$)'; then
+  block \
+    "Overwriting .env file detected." \
+    "ODD Studio never overwrites .env files — they contain credentials.
+Edit .env manually or use a specific key: echo 'KEY=value' >> .env"
+fi
+
+# ── Committing secrets ────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+(add|commit).*\.env'; then
+  block \
+    "Attempting to commit .env file." \
+    "ODD Studio never commits .env files — they contain credentials.
+Add .env to .gitignore if it isn't already:
+  echo '.env' >> .gitignore"
+fi
+
+# ── Dropping databases ────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qiE '(drop\s+database|dropdb|DROP\s+TABLE.*CASCADE)'; then
+  warn \
+    "Database destructive operation detected: $COMMAND" \
+    "Ensure you are targeting the development database, not production.
+ODD Studio recommends confirming the DATABASE_URL before destructive DB operations."
+fi
+
+# ── Killing all node processes ────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'kill\s+-9\s+(all|-1|0)'; then
+  warn \
+    "kill -9 all processes detected." \
+    "This terminates all processes for your user, including any development servers.
+Use kill -9 <PID> to target a specific process."
+fi
+
+# ── curl | bash (pipe to shell) ───────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE '(curl|wget).*\|\s*(bash|sh|zsh)'; then
+  warn \
+    "Pipe-to-shell pattern detected: $COMMAND" \
+    "Executing remote scripts directly is a security risk.
+Consider downloading and reviewing the script before executing."
+fi
+
+exit 0