odd-studio 1.0.1 → 2.1.0

package/bin/odd-studio.js

@@ -62,7 +62,7 @@ program
     console.log(chalk.bold(`  Setting up: ${chalk.cyan(resolvedName)}\n`));
 
     // 1. Scaffold project structure
-    print.step(1, 3, 'Creating project structure...');
+    print.step(1, 4, 'Creating project structure...');
     const spinner1 = ora({ text: '', indent: 4 }).start();
     try {
       await scaffoldProject(targetDir, resolvedName);
@@ -76,7 +76,7 @@ program
 
     // 2. Install /odd skill
     if (!options.skipSkill) {
-      print.step(2, 3, 'Installing /odd skill into Claude Code...');
+      print.step(2, 4, 'Installing /odd skill into Claude Code...');
       const spinner2 = ora({ text: '', indent: 4 }).start();
       try {
         const result = await installSkill(PACKAGE_ROOT);
@@ -88,13 +88,13 @@ program
         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.step(2, 4, '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...');
+      print.step(3, 4, 'Installing safety hooks into Claude Code settings...');
       const spinner3 = ora({ text: '', indent: 4 }).start();
       try {
         const result = await setupHooks(PACKAGE_ROOT);
@@ -106,10 +106,29 @@ program
         print.info('Manual install: add entries from ' + chalk.dim('hooks/') + ' to ~/.claude/settings.json');
       }
     } else {
-      print.step(3, 3, 'Skipping hooks (--skip-hooks)');
+      print.step(3, 4, 'Skipping hooks (--skip-hooks)');
       print.warn('Safety hooks not installed. Git guardrails and quality gates will not run.');
     }
 
+    // 4. Configure ruflo MCP server (cross-session memory)
+    print.step(4, 4, 'Configuring ruflo memory server...');
+    const spinner4 = ora({ text: '', indent: 4 }).start();
+    try {
+      const { default: setupMcp } = await import('../scripts/setup-mcp.js');
+      const mcpResult = await setupMcp();
+      spinner4.stop();
+      if (mcpResult.mcpJsonUpdated || mcpResult.settingsUpdated) {
+        print.ok('Ruflo MCP server configured — cross-session memory enabled');
+      } else {
+        print.ok('Ruflo MCP server already configured');
+      }
+    } catch (e) {
+      spinner4.stop();
+      print.warn('Could not configure ruflo automatically: ' + e.message);
+      print.info('Manual setup: add ruflo to ~/.mcp.json and enable in ~/.claude/settings.json');
+      print.info('See: https://github.com/ruvnet/ruflo for installation instructions');
+    }
+
     // ── Done ──
     print.blank();
     console.log(chalk.bold.green('  ✓ ODD Studio is ready.\n'));
@@ -188,6 +207,15 @@ program
       s2.fail('Hooks update failed: ' + e.message);
     }
 
+    const s3 = ora({ text: 'Checking ruflo MCP configuration...', indent: 4 }).start();
+    try {
+      const { default: setupMcp } = await import('../scripts/setup-mcp.js');
+      const mcpResult = await setupMcp();
+      s3.succeed(mcpResult.mcpJsonUpdated || mcpResult.settingsUpdated ? 'Ruflo MCP configured' : 'Ruflo MCP already configured');
+    } catch (e) {
+      s3.fail('Ruflo MCP check failed: ' + e.message);
+    }
+
     print.blank();
     print.ok('Upgrade complete.');
     print.blank();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "1.0.1",
+  "version": "2.1.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/postinstall.js

@@ -13,16 +13,19 @@ if (!isGlobal && !isNpx) {
   process.exit(0);
 }
 
-import('./install-skill.js')
-  .then(({ default: installSkill }) => {
-    const pkg = new URL('..', import.meta.url).pathname;
-    return installSkill(pkg.replace(/\/$/, ''));
-  })
+const pkg = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
+
+Promise.all([
+  import('./install-skill.js').then(({ default: installSkill }) => installSkill(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 installed into Claude Code');
+    console.log('✓ ODD Studio: /odd skill, safety hooks, and ruflo memory installed into Claude Code');
+    console.log('  Run: npx odd-studio init [project-name]  to scaffold your first project.');
   })
   .catch((e) => {
     // Non-fatal — user can run odd-studio init manually
-    console.log('⚠ ODD Studio: Could not auto-install skill (' + e.message + ')');
+    console.log('⚠ ODD Studio: Could not complete setup (' + e.message + ')');
     console.log('  Run: npx odd-studio init  to complete setup.');
   });

package/scripts/setup-mcp.js

@@ -0,0 +1,68 @@
+'use strict';
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+
+const MCP_JSON_PATH = path.join(os.homedir(), '.mcp.json');
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+
+const RUFLO_SERVER_ENTRY = {
+  type: 'stdio',
+  command: 'npx',
+  args: ['ruflo@latest', 'mcp', 'start'],
+  env: {},
+};
+
+/**
+ * Configures the ruflo MCP server so that cross-session memory works.
+ *
+ * Two writes required:
+ *   1. ~/.mcp.json — defines the server (npx ruflo@latest mcp start)
+ *   2. ~/.claude/settings.json — adds "ruflo" to enabledMcpjsonServers
+ *
+ * Both are idempotent: existing entries are left untouched.
+ */
+export default async function setupMcp() {
+  const result = { mcpJsonUpdated: false, settingsUpdated: false };
+
+  // ── 1. Add ruflo to ~/.mcp.json ────────────────────────────────────────────
+  let mcpConfig = { mcpServers: {} };
+  if (fs.existsSync(MCP_JSON_PATH)) {
+    try {
+      mcpConfig = await fs.readJson(MCP_JSON_PATH);
+    } catch {
+      // Corrupt file — start fresh but preserve any valid content
+      mcpConfig = { mcpServers: {} };
+    }
+  }
+  if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+
+  if (!mcpConfig.mcpServers.ruflo) {
+    mcpConfig.mcpServers.ruflo = RUFLO_SERVER_ENTRY;
+    await fs.writeJson(MCP_JSON_PATH, mcpConfig, { spaces: 2 });
+    result.mcpJsonUpdated = true;
+  }
+
+  // ── 2. Enable ruflo in ~/.claude/settings.json ─────────────────────────────
+  await fs.ensureDir(path.join(os.homedir(), '.claude'));
+  let settings = {};
+  if (fs.existsSync(SETTINGS_PATH)) {
+    try {
+      settings = await fs.readJson(SETTINGS_PATH);
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!Array.isArray(settings.enabledMcpjsonServers)) {
+    settings.enabledMcpjsonServers = [];
+  }
+
+  if (!settings.enabledMcpjsonServers.includes('ruflo')) {
+    settings.enabledMcpjsonServers.push('ruflo');
+    await fs.writeJson(SETTINGS_PATH, settings, { spaces: 2 });
+    result.settingsUpdated = true;
+  }
+
+  return result;
+}

package/skill/SKILL.md

@@ -176,6 +176,22 @@ Initialise the ruflo swarm for parallel build execution. See the full Ruflo Swar
 
 ---
 
+### `*agent`
+
+Create a custom agent for a domain-specific concern. The domain expert describes what they need in plain language. ODD Studio configures the agent, assigns it to the swarm, and includes its reports in the verification output alongside the QA agent's report.
+
+Common use cases: brand voice (flag text that does not match the platform's tone), compliance (check every outcome against a regulatory standard), accessibility (review every screen against WCAG).
+
+The domain expert does not write agent code. They describe the concern:
+
+> "Every piece of text a customer sees should sound like it comes from a small, friendly independent bookshop. Flag anything that sounds corporate or uses jargon."
+
+ODD Studio creates the agent from that description. It runs on every relevant outcome and reports in domain language.
+
+After collecting the description, call `mcp__ruflo__agent_spawn` with the custom role and the domain expert's description as instructions. Confirm the agent is active and will run during the next `*build` or `*swarm` session.
+
+---
+
 ### `*export`
 
 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.
@@ -199,16 +215,24 @@ After writing the file, display: "Your Session Brief has been written to docs/se
 Load coaching content from chapter n of the ODD methodology book. Route to the appropriate file in `docs/chapters/`. If the chapter file does not exist, explain what that chapter covers conceptually and offer to explore it through dialogue.
 
 Chapter reference:
-- Chapter 1: Why features fail and outcomes succeed
-- Chapter 2: Persona depth — beyond demographics
-- Chapter 3: Writing outcomes that actually specify behaviour
-- Chapter 4: The walkthrough as specification
-- Chapter 5: Contracts — the grammar of system connections
-- Chapter 6: The Master Implementation Plan
-- Chapter 7: Build Protocol — how AI agents work from your plan
-- Chapter 8: Verification in the domain expert's language
-- Chapter 9: UI excellence for non-designers
-- Chapter 10: Handling change without breaking the plan
+- Chapter 1: It's All About Clarity
+- Chapter 2: The Right Division of Labour
+- Chapter 3: Features Aren't Enough
+- Chapter 4: Outcomes Should Be Specific
+- Chapter 5: Personas Are Load-Bearing
+- Chapter 6: Every Outcome Has a Contract
+- Chapter 7: Design the Outcome Twice
+- Chapter 8: The Master Implementation Plan
+- Chapter 9: Start from Zero
+- Chapter 10: The Build Protocol
+- Chapter 11: Verification Is Your Job
+- Chapter 12: Building One Outcome
+- Chapter 13: Concurrent Outcomes and the Swarm
+- Chapter 14: The Things That Scare You
+- Chapter 15: Good Interfaces Are Specified, Not Designed
+- Chapter 16: Managing Change
+- Chapter 17: The Swarm in Depth
+- Chapter 18: Conclusion
 
 ---
 
@@ -245,7 +269,8 @@ Display this reference:
 | `*contracts` | Map contracts with Theo |
 | `*phase-plan` | Build the Master Implementation Plan with Rachel |
 | `*ui` | Load UI excellence principles |
-| `*swarm` | Initialise ruflo swarm manually |
+| `*swarm` | Build all independent outcomes in the current phase simultaneously |
+| `*agent` | Create a custom agent for a domain-specific concern |
 | `*export` | Generate IDE Session Brief |
 | `*chapter [n]` | Load methodology coaching for chapter n |
 | `*why` | Explain why the current step matters |