odd-studio 1.0.0

package/hooks/odd-git-safety.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# odd-git-safety.sh
+# ODD Studio — Git Safety Hook (PreToolUse: Bash)
+#
+# Intercepts dangerous git commands before they execute.
+# Protects against force-push, hard-reset, and branch deletion
+# that could destroy work in progress.
+#
+# Exit 0  → allow the command
+# Exit 2  → block the command (Claude will not execute it)
+# Stderr  → message shown to the user
+
+COMMAND="${CLAUDE_TOOL_INPUT:-}"
+
+# ── Helper ────────────────────────────────────────────────────────────────────
+block() {
+  echo "🔒 ODD GIT SAFETY BLOCK: $1" >&2
+  echo "" >&2
+  echo "$2" >&2
+  echo "" >&2
+  echo "To override: commit your work first, then re-run with explicit intent." >&2
+  exit 2
+}
+
+warn() {
+  echo "⚠️  ODD GIT SAFETY WARNING: $1" >&2
+  echo "$2" >&2
+  # Warnings don't block — they inform
+}
+
+# ── Only check git commands ───────────────────────────────────────────────────
+if ! echo "$COMMAND" | grep -qE '^\s*(git\s)'; then
+  exit 0
+fi
+
+# ── Force push ────────────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+push.*(--force|-f)(\s|$)'; then
+  block \
+    "Force push detected." \
+    "Force-pushing rewrites remote history and can permanently destroy teammates' work.
+ODD Studio never force-pushes. If you need to update a remote branch:
+  - Use: git push --force-with-lease  (safer — fails if remote has new commits)
+  - Or create a new branch for your changes"
+fi
+
+# ── Force push to main/master ─────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+push.*--force-with-lease.*(main|master)'; then
+  block \
+    "Force push to main/master detected." \
+    "ODD Studio never force-pushes to the main branch.
+This is a non-reversible operation on your primary branch.
+Create a PR and merge instead."
+fi
+
+# ── Hard reset ────────────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  # Check if there are uncommitted changes first
+  if git diff --quiet 2>/dev/null && git diff --cached --quiet 2>/dev/null; then
+    # Working tree is clean — allow hard reset
+    exit 0
+  else
+    block \
+      "Hard reset with uncommitted changes detected." \
+      "You have uncommitted changes that would be permanently lost.
+ODD Studio blocked this to protect your work.
+Options:
+  - git stash           (save changes temporarily)
+  - git commit -am 'WIP: saving before reset'  (commit first)
+  - git diff            (review what would be lost)"
+  fi
+fi
+
+# ── Discard all changes ───────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+checkout\s+--?\s*\.'; then
+  block \
+    "Discard all changes (git checkout -- .) detected." \
+    "This would permanently discard all uncommitted changes in your working tree.
+ODD Studio blocked this to protect your work.
+Options:
+  - git stash           (save changes temporarily)
+  - git diff            (review what would be lost)
+  - git commit -am 'WIP'  (commit first)"
+fi
+
+# ── git restore all ───────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+restore\s+\.'; then
+  block \
+    "Restore all files (git restore .) detected." \
+    "This would permanently discard all unstaged changes.
+Commit or stash your work first."
+fi
+
+# ── git clean ─────────────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+clean\s+.*-[a-zA-Z]*f'; then
+  block \
+    "git clean -f detected." \
+    "This permanently deletes untracked files with no recovery path.
+ODD Studio blocked this.
+Use git status to review untracked files before deleting them."
+fi
+
+# ── Force branch delete ───────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+branch\s+(-D|--delete --force)'; then
+  BRANCH=$(echo "$COMMAND" | grep -oE '(-D|--delete --force)\s+\S+' | awk '{print $2}')
+  warn \
+    "Force branch deletion: $BRANCH" \
+    "If this branch has unmerged commits they will be lost.
+Verify the branch is fully merged before deleting."
+  # Warning only — does not block. Claude will proceed but user is informed.
+fi
+
+# ── Amend published commits ───────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE 'git\s+commit.*--amend'; then
+  # Check if HEAD is pushed to a remote
+  if git log --oneline "@{u}..HEAD" 2>/dev/null | grep -q .; then
+    # HEAD has commits not on remote — amend is safe
+    exit 0
+  elif git rev-parse "@{u}" >/dev/null 2>&1; then
+    block \
+      "Amending a published commit." \
+      "This commit has been pushed to the remote.
+Amending it will require a force-push, which rewrites history.
+Instead: create a new commit with your changes."
+  fi
+fi
+
+# ── Skip hooks ────────────────────────────────────────────────────────────────
+if echo "$COMMAND" | grep -qE '(--no-verify|-n)\s'; then
+  block \
+    "--no-verify flag detected." \
+    "ODD Studio never skips pre-commit hooks (--no-verify).
+Hooks exist to protect build quality. If a hook is failing:
+  1. Read the error carefully
+  2. Fix the underlying issue
+  3. Commit cleanly"
+fi
+
+exit 0

package/hooks/odd-outcome-quality.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# odd-outcome-quality.sh
+# ODD Studio — Outcome Quality Gate (PostToolUse: Write)
+#
+# 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:-}"
+
+# ── Only check ODD docs ───────────────────────────────────────────────────────
+if ! echo "$FILE_PATH" | grep -qE 'docs/(outcomes|personas)/'; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+CONTENT=$(cat "$FILE_PATH")
+
+# ── Outcome quality check ─────────────────────────────────────────────────────
+if echo "$FILE_PATH" | grep -q 'docs/outcomes/'; then
+  MISSING=""
+
+  # Check for all six fields
+  echo "$CONTENT" | grep -qiE 'Field 1.*Persona|## Persona' || MISSING="$MISSING\n  • Field 1 (Persona) — not found"
+  echo "$CONTENT" | grep -qiE 'Field 2.*Trigger|## Trigger' || MISSING="$MISSING\n  • Field 2 (Trigger) — not found"
+  echo "$CONTENT" | grep -qiE 'Field 3.*Walkthrough|## Walkthrough' || MISSING="$MISSING\n  • Field 3 (Walkthrough) — not found"
+  echo "$CONTENT" | grep -qiE 'Field 4.*Verif|## Verif' || MISSING="$MISSING\n  • Field 4 (Verification) — not found"
+  echo "$CONTENT" | grep -qiE 'Field 5.*Contracts|## Contracts' || MISSING="$MISSING\n  • Field 5 (Contracts Exposed) — not found"
+  echo "$CONTENT" | grep -qiE 'Field 6.*Dep|## Dep' || MISSING="$MISSING\n  • Field 6 (Dependencies) — not found"
+
+  # Check for banned vocabulary
+  BANNED=$(echo "$CONTENT" | grep -iE '\b(user story|user stories|sprint|epic|backlog|api endpoint|database schema|database table|json payload|http request)\b' | head -5)
+
+  if [ -n "$MISSING" ] || [ -n "$BANNED" ]; then
+    echo "" >&2
+    echo "🎯 ODD OUTCOME QUALITY CHECK: $(basename "$FILE_PATH")" >&2
+    if [ -n "$MISSING" ]; then
+      echo "" >&2
+      echo "Incomplete outcome — missing fields:" >&2
+      echo -e "$MISSING" >&2
+      echo "" >&2
+      echo "An outcome with missing fields will produce an incomplete build." >&2
+      echo "Run *review-outcome in /odd to fix before proceeding." >&2
+    fi
+    if [ -n "$BANNED" ]; then
+      echo "" >&2
+      echo "Banned vocabulary detected:" >&2
+      echo "$BANNED" | while IFS= read -r line; do echo "  → $line" >&2; done
+      echo "" >&2
+      echo "ODD outcomes must be written in domain language only." >&2
+      echo "Translate technical terms back to what the user experiences." >&2
+    fi
+    echo "" >&2
+  fi
+fi
+
+# ── Persona quality check ─────────────────────────────────────────────────────
+if echo "$FILE_PATH" | grep -q 'docs/personas/'; then
+  MISSING_DIMS=""
+
+  echo "$CONTENT" | grep -qiE '## Identity|identity' || MISSING_DIMS="$MISSING_DIMS\n  • Identity dimension"
+  echo "$CONTENT" | grep -qiE '## Current Reality|current.?reality' || MISSING_DIMS="$MISSING_DIMS\n  • Current Reality dimension"
+  echo "$CONTENT" | grep -qiE '## Technical Context|technical.?context' || MISSING_DIMS="$MISSING_DIMS\n  • Technical Context dimension"
+  echo "$CONTENT" | grep -qiE '## Constraints|constraints' || MISSING_DIMS="$MISSING_DIMS\n  • Constraints dimension"
+  echo "$CONTENT" | grep -qiE '## Trigger Patterns|trigger.?patterns' || MISSING_DIMS="$MISSING_DIMS\n  • Trigger Patterns dimension"
+  echo "$CONTENT" | grep -qiE '## Success Definition|success.?definition' || MISSING_DIMS="$MISSING_DIMS\n  • Success Definition dimension"
+  echo "$CONTENT" | grep -qiE '## Failure Tolerance|failure.?tolerance' || MISSING_DIMS="$MISSING_DIMS\n  • Failure Tolerance dimension"
+
+  if [ -n "$MISSING_DIMS" ]; then
+    echo "" >&2
+    echo "👤 ODD PERSONA QUALITY CHECK: $(basename "$FILE_PATH")" >&2
+    echo "" >&2
+    echo "Thin persona — missing dimensions:" >&2
+    echo -e "$MISSING_DIMS" >&2
+    echo "" >&2
+    echo "A persona without all 7 dimensions produces outcomes designed for nobody in particular." >&2
+    echo "Run *review-persona in /odd to complete it." >&2
+    echo "" >&2
+  fi
+fi
+
+exit 0

package/hooks/odd-pre-build.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# odd-pre-build.sh
+# ODD Studio — Pre-Build Safety Check (PreToolUse: Bash)
+#
+# 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:-}"
+
+# ── 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
+  exit 0
+fi
+
+# ── Check git is clean before production builds ───────────────────────────────
+if echo "$COMMAND" | grep -qiE '(deploy|start:prod)'; then
+  if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+    echo "🏗️ ODD PRE-BUILD: Uncommitted changes before deploy." >&2
+    echo "" >&2
+    echo "You have uncommitted changes. ODD Studio recommends:" >&2
+    echo "  1. Review changes: git diff" >&2
+    echo "  2. Commit: git add -A && git commit -m 'describe what changed'" >&2
+    echo "  3. Then deploy" >&2
+    echo "" >&2
+    echo "Deploying from a dirty working tree makes it hard to roll back." >&2
+    exit 2
+  fi
+fi
+
+# ── Check ODD plan exists before first build ─────────────────────────────────
+if [ ! -f "docs/plan.md" ]; then
+  echo "🏗️ ODD PRE-BUILD: No Master Implementation Plan found." >&2
+  echo "" >&2
+  echo "docs/plan.md does not exist in this project." >&2
+  echo "ODD Studio recommends completing planning before building:" >&2
+  echo "  Open Claude Code → /odd → *plan" >&2
+  echo "" >&2
+  echo "Building without a plan means building the wrong thing." >&2
+  # Warning only for missing plan — don't block a legitimate build
+fi
+
+# ── Check for any unverified outcomes before building next phase ──────────────
+if [ -d "docs/outcomes" ]; then
+  UNVERIFIED=$(grep -rl "status.*draft\|Review Status.*DRAFT" docs/outcomes/ 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$UNVERIFIED" -gt 0 ]; then
+    echo "🏗️ ODD PRE-BUILD: $UNVERIFIED unverified outcome(s) detected." >&2
+    echo "" >&2
+    echo "Some outcomes are in DRAFT status and have not been reviewed." >&2
+    echo "Building from unreviewed outcomes produces systems that do not match your intentions." >&2
+    echo "" >&2
+    echo "Run *review-outcome in /odd for each draft outcome before building." >&2
+    echo "" >&2
+    # Warning only — does not block the build
+  fi
+fi
+
+exit 0

package/hooks/odd-session-save.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# odd-session-save.sh
+# ODD Studio — Session State Save (PostToolUse: Bash)
+#
+# After git commit commands, syncs project state to ruflo memory
+# 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:-}"
+
+# ── Only trigger on git commit ────────────────────────────────────────────────
+if ! echo "$COMMAND" | grep -qE 'git\s+commit'; then
+  exit 0
+fi
+
+STATE_FILE=".odd/state.json"
+
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+# ── Update last-commit timestamp in local state ───────────────────────────────
+LAST_COMMIT=$(git log -1 --format="%H %s" 2>/dev/null || echo "unknown")
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Use node to update the JSON cleanly (available since odd-studio requires node 18+)
+node -e "
+  const fs = require('fs');
+  const state = JSON.parse(fs.readFileSync('$STATE_FILE', 'utf8'));
+  state.lastCommit = '$LAST_COMMIT';
+  state.lastSaved = '$TIMESTAMP';
+  fs.writeFileSync('$STATE_FILE', JSON.stringify(state, null, 2));
+  console.log('state updated');
+" 2>/dev/null
+
+echo "💾 ODD session state saved. Resume with /odd in Claude Code." >&2
+
+exit 0

package/hooks/odd-ui-check.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# odd-ui-check.sh
+# ODD Studio — UI Quality Reminder (PostToolUse: Edit)
+#
+# After editing UI/frontend files, surfaces accessibility and
+# mobile-first reminders. Educational, not blocking.
+
+FILE_PATH="${CLAUDE_TOOL_RESULT_FILE:-}"
+
+# ── Only check frontend files ─────────────────────────────────────────────────
+if ! echo "$FILE_PATH" | grep -qiE '\.(tsx|jsx|html|svelte|vue)$'; then
+  exit 0
+fi
+
+# Only run ~20% of the time to avoid noise (sample by PID)
+if [ $(( $$ % 5 )) -ne 0 ]; then
+  exit 0
+fi
+
+CONTENT=""
+if [ -f "$FILE_PATH" ]; then
+  CONTENT=$(cat "$FILE_PATH")
+fi
+
+ISSUES=""
+
+# ── Accessibility checks ──────────────────────────────────────────────────────
+
+# img without alt
+if echo "$CONTENT" | grep -qE '<img[^>]+(?!alt=)'; then
+  if echo "$CONTENT" | grep -qE '<img' && ! echo "$CONTENT" | grep -qE '<img[^>]+alt='; then
+    ISSUES="$ISSUES\n  • <img> elements should have alt= attributes (screen reader accessibility)"
+  fi
+fi
+
+# Buttons without accessible text
+if echo "$CONTENT" | grep -qE '<button[^>]*>\s*<'; then
+  ISSUES="$ISSUES\n  • Buttons containing only icons need aria-label= for screen readers"
+fi
+
+# Interactive elements without focus management
+if echo "$CONTENT" | grep -qE 'onClick|onPress' && ! echo "$CONTENT" | grep -qE '(focus|tabIndex|onKeyDown|onKeyPress|role=)'; then
+  ISSUES="$ISSUES\n  • Interactive elements need keyboard support (onKeyDown or role= + tabIndex)"
+fi
+
+# Hardcoded colours instead of tokens
+if echo "$CONTENT" | grep -qE '(style=.*color:\s*#|style=.*background:\s*#)'; then
+  ISSUES="$ISSUES\n  • Hardcoded colours detected — use Tailwind tokens or CSS variables for theme consistency"
+fi
+
+# Non-responsive fixed widths
+if echo "$CONTENT" | grep -qE 'width:\s*[0-9]{3,}px'; then
+  ISSUES="$ISSUES\n  • Fixed pixel widths may break on mobile — prefer Tailwind responsive classes (w-full, max-w-*)"
+fi
+
+# ── Output coaching ───────────────────────────────────────────────────────────
+if [ -n "$ISSUES" ]; then
+  echo "" >&2
+  echo "🎨 ODD UI QUALITY REMINDER: $(basename "$FILE_PATH")" >&2
+  echo "" >&2
+  echo "Things to check before marking this UI outcome verified:" >&2
+  echo -e "$ISSUES" >&2
+  echo "" >&2
+  echo "Remember: every UI outcome must be verified on a mobile screen before it passes." >&2
+  echo "Resize your browser to 375px wide and walk through your verification steps." >&2
+  echo "" >&2
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "odd-studio",
+  "version": "1.0.0",
+  "description": "Outcome-Driven Development for Claude Code — a planning and build harness for domain experts building serious software with AI.",
+  "keywords": [
+    "claude-code",
+    "odd",
+    "outcome-driven-development",
+    "ai-development",
+    "no-code",
+    "claude",
+    "anthropic"
+  ],
+  "author": "ODD Studio",
+  "license": "MIT",
+  "bin": {
+    "odd-studio": "./bin/odd-studio.js"
+  },
+  "scripts": {
+    "prepare": "chmod +x bin/odd-studio.js hooks/*.sh",
+    "prepublishOnly": "npm run prepare",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "type": "module",
+  "files": [
+    "bin/",
+    "scripts/",
+    "skill/",
+    "hooks/",
+    "templates/",
+    ".claude-plugin/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "inquirer": "^10.0.0",
+    "fs-extra": "^11.2.0"
+  }
+}

package/scripts/install-skill.js

@@ -0,0 +1,30 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Installs the /odd skill into ~/.claude/skills/odd/
+ * Copies skill/ directory from the package root.
+ */
+export default async function installSkill(packageRoot, options = {}) {
+  const source = path.join(packageRoot, 'skill');
+  const destination = path.join(os.homedir(), '.claude', 'skills', 'odd');
+
+  if (!fs.existsSync(source)) {
+    throw new Error(`Skill source not found at ${source}`);
+  }
+
+  // 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);
+  }
+
+  await fs.copy(source, destination, { overwrite: true });
+
+  return { destination };
+}

package/scripts/postinstall.js

@@ -0,0 +1,28 @@
+// postinstall.js — runs after npm install
+// Only installs skill + hooks when running as a global install (npx or npm install -g).
+// Does NOT run during project-level npm install to avoid side effects.
+
+'use strict';
+
+// Detect if this is a global install or npx execution
+const isGlobal = process.env.npm_config_global === 'true';
+const isNpx = process.env.npm_lifecycle_script?.includes('npx');
+
+if (!isGlobal && !isNpx) {
+  // Project-level install — skip automatic setup
+  process.exit(0);
+}
+
+import('./install-skill.js')
+  .then(({ default: installSkill }) => {
+    const pkg = new URL('..', import.meta.url).pathname;
+    return installSkill(pkg.replace(/\/$/, ''));
+  })
+  .then(() => {
+    console.log('✓ ODD Studio: /odd skill installed into Claude Code');
+  })
+  .catch((e) => {
+    // Non-fatal — user can run odd-studio init manually
+    console.log('⚠ ODD Studio: Could not auto-install skill (' + e.message + ')');
+    console.log('  Run: npx odd-studio init  to complete setup.');
+  });

package/scripts/scaffold-project.js

@@ -0,0 +1,61 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES = path.resolve(__dirname, '..', 'templates');
+
+export default async function scaffoldProject(targetDir, projectName) {
+  await fs.ensureDir(targetDir);
+
+  // Copy templates
+  await fs.copy(TEMPLATES, targetDir, {
+    overwrite: false, // Never overwrite existing user files
+    filter: (src) => {
+      // Skip .gitkeep in non-empty directories
+      if (src.endsWith('.gitkeep')) {
+        const dir = path.dirname(src);
+        const destDir = dir.replace(TEMPLATES, targetDir);
+        return !fs.existsSync(destDir) || fs.readdirSync(destDir).length === 0;
+      }
+      return true;
+    },
+  });
+
+  // Patch CLAUDE.md with project name
+  const claudeMd = path.join(targetDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMd)) {
+    let content = await fs.readFile(claudeMd, 'utf8');
+    content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+    await fs.writeFile(claudeMd, content);
+  }
+
+  // Patch .odd/state.json with project name and timestamp
+  const stateFile = path.join(targetDir, '.odd', 'state.json');
+  if (fs.existsSync(stateFile)) {
+    const state = await fs.readJson(stateFile);
+    state.projectName = projectName;
+    state.initialisedAt = new Date().toISOString();
+    await fs.writeJson(stateFile, state, { spaces: 2 });
+  }
+
+  // Initialise git if not already a repo
+  const gitDir = path.join(targetDir, '.git');
+  if (!fs.existsSync(gitDir)) {
+    const { execSync } = await import('child_process');
+    try {
+      execSync('git init', { cwd: targetDir, stdio: 'ignore' });
+      execSync('git add -A', { cwd: targetDir, stdio: 'ignore' });
+      execSync(`git commit -m "Initial ODD Studio scaffold for ${projectName}"`, {
+        cwd: targetDir,
+        stdio: 'ignore',
+      });
+    } catch {
+      // Git init is best-effort — don't fail the whole install
+    }
+  }
+
+  return { targetDir };
+}

package/scripts/setup-hooks.js

@@ -0,0 +1,105 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const HOOKS_DEST = path.join(os.homedir(), '.claude', 'hooks');
+
+// The hooks odd-studio installs, keyed by filename
+const ODD_HOOKS = {
+  'odd-git-safety.sh': {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    timeout: 5,
+    statusMessage: '🔒 ODD git safety check...',
+  },
+  'odd-destructive-guard.sh': {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    timeout: 5,
+    statusMessage: '🛡️ ODD destructive command guard...',
+  },
+  'odd-outcome-quality.sh': {
+    event: 'PostToolUse',
+    matcher: 'Write',
+    timeout: 5,
+    statusMessage: '🎯 ODD outcome quality check...',
+  },
+  'odd-ui-check.sh': {
+    event: 'PostToolUse',
+    matcher: 'Edit',
+    timeout: 3,
+    statusMessage: '🎨 ODD UI quality reminder...',
+  },
+  'odd-session-save.sh': {
+    event: 'PostToolUse',
+    matcher: 'Bash',
+    timeout: 10,
+    statusMessage: '💾 ODD session save...',
+  },
+  'odd-pre-build.sh': {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    timeout: 5,
+    statusMessage: '🏗️ ODD build safety check...',
+  },
+};
+
+export default async function setupHooks(packageRoot, options = {}) {
+  const hooksSource = path.join(packageRoot, 'hooks');
+
+  // Copy hook scripts to ~/.claude/hooks/
+  await fs.ensureDir(HOOKS_DEST);
+  for (const hookFile of Object.keys(ODD_HOOKS)) {
+    const src = path.join(hooksSource, hookFile);
+    const dest = path.join(HOOKS_DEST, hookFile);
+    if (fs.existsSync(src)) {
+      await fs.copy(src, dest, { overwrite: true });
+      // Make executable
+      await fs.chmod(dest, 0o755);
+    }
+  }
+
+  // Read or initialise settings.json
+  await fs.ensureDir(path.dirname(SETTINGS_PATH));
+  let settings = {};
+  if (fs.existsSync(SETTINGS_PATH)) {
+    settings = await fs.readJson(SETTINGS_PATH);
+  }
+  if (!settings.hooks) settings.hooks = {};
+
+  // Build hook entries
+  const hooksByEvent = {};
+  for (const [hookFile, config] of Object.entries(ODD_HOOKS)) {
+    const { event, matcher, timeout, statusMessage } = config;
+    if (!hooksByEvent[event]) hooksByEvent[event] = {};
+    if (!hooksByEvent[event][matcher]) hooksByEvent[event][matcher] = [];
+    hooksByEvent[event][matcher].push({
+      type: 'command',
+      command: path.join(HOOKS_DEST, hookFile),
+      timeout,
+      statusMessage,
+    });
+  }
+
+  // Merge into existing hooks, tagged with odd-studio so we can upgrade cleanly
+  for (const [event, matchers] of Object.entries(hooksByEvent)) {
+    if (!settings.hooks[event]) settings.hooks[event] = [];
+    for (const [matcher, hookList] of Object.entries(matchers)) {
+      // Remove existing odd-studio hooks for this matcher (clean upgrade)
+      settings.hooks[event] = settings.hooks[event].filter(
+        (entry) => !(entry.matcher === matcher && entry._oddStudio)
+      );
+      settings.hooks[event].push({
+        matcher,
+        _oddStudio: true,
+        hooks: hookList,
+      });
+    }
+  }
+
+  await fs.writeJson(SETTINGS_PATH, settings, { spaces: 2 });
+
+  return { hookCount: Object.keys(ODD_HOOKS).length };
+}