odd-studio 3.3.1 → 3.3.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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": "3.3.1",
+  "version": "3.3.3",
   "author": {
     "name": "ODD Studio"
   },

package/README.md

@@ -45,8 +45,9 @@ npx odd-studio init my-project --agent codex
 cd my-project
 ```
 
-In Codex, ODD Studio is installed as a project-local plugin with visible plugin commands. After restarting Codex, type `/odd`.
-Once inside `/odd`, the same starred flow works there too, including commands like `*plan`, `*build`, and `*status`. You can also invoke the direct Codex commands such as `/odd-build`.
+In Codex, start ODD by saying `use ODD` or `start ODD`.
+Codex reads `AGENTS.md`, which routes the session to `plugins/odd-studio/skills/odd/SKILL.md`.
+Once ODD is active, the same starred flow works there too, including commands like `*plan`, `*build`, and `*status`.
 
 ### For Claude Code and OpenCode on the same machine
 
@@ -73,9 +74,10 @@ That single command:
 - Optionally installs Checkpoint security scanning (you'll be asked)
 - Initialises git with an initial commit
 
-**Then open your project in your AI coding agent and type:**
+**Then open your project in your AI coding agent and start ODD:**
 ```
-/odd
+Claude Code / OpenCode: /odd
+Codex: use ODD
 ```
 
 ---
@@ -92,14 +94,14 @@ All supported agents get the same methodology, the same safety enforcement, and
 
 ---
 
-## What happens when you type `/odd`
+## What happens when you start ODD
 
 Your AI coding agent loads the ODD orchestrator. It checks whether you have an existing project in progress (via your local `.odd/state.json` and odd-flow 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.
 
-From there, use the dedicated slash commands listed below — or type sub-commands directly inside `/odd`.
+From there, use the dedicated direct commands listed below in Claude Code or OpenCode, or type sub-commands inside the active ODD session.
 
 ---
 
@@ -157,7 +159,7 @@ ODD Studio installs safety gates that run automatically throughout your build. T
 **Claude Code:** Implemented as shell hooks registered in `.claude/settings.local.json` (project-local).
 **OpenCode:** Implemented as a JS plugin (`odd-studio-plugin.js`) in `.opencode/plugins/` (project-local).
 **Codex:** Implemented as a project-local plugin in `plugins/odd-studio/` with `hooks.json` and plugin-local skills.
-It also installs Codex plugin commands so `/odd` is directly discoverable in the composer.
+Codex starts through `AGENTS.md` instructions (`use ODD` / `start ODD`) rather than a guaranteed `/odd` composer command.
 
 ---
 
@@ -261,9 +263,9 @@ Only the config directories for your target agent are generated (`.claude/`, `.o
 
 ---
 
-## Slash commands
+## Direct Commands
 
-These are the top-level commands you can invoke in Claude Code, OpenCode, or Codex:
+These are the top-level direct commands you can invoke in Claude Code or OpenCode:
 
 | Command | What it does |
 |---------|-------------|
@@ -277,7 +279,7 @@ These are the top-level commands you can invoke in Claude Code, OpenCode, or Cod
 
 ## Sub-commands inside `/odd`
 
-Once inside `/odd`, you can also use these sub-commands:
+Once ODD is active, you can use these sub-commands in Claude Code, OpenCode, or Codex:
 
 ```
 *persona       Work on personas with Diana

package/bin/commands/init.js

@@ -217,10 +217,12 @@ function printNextSteps({ isClaude, isOpenCode, isCodex, projectName }) {
     console.log(`  ${stepN++}. Open your project: ` + chalk.cyan('opencode'));
   }
   if (isCodex) {
-    console.log(`  ${stepN++}. Restart Codex: ` + chalk.cyan('quit and reopen') + chalk.dim(' (activates the local ODD Studio plugin)'));
     console.log(`  ${stepN++}. Open your project in Codex`);
+    console.log(`  ${stepN++}. Start ODD by saying: ` + chalk.cyan('use ODD') + chalk.dim(' (Codex reads AGENTS.md automatically — no /odd command needed)'));
+  }
+  if (isClaude || isOpenCode) {
+    console.log(`  ${stepN++}. Start your ODD session: ` + chalk.cyan('/odd'));
   }
-  console.log(`  ${stepN++}. Start your ODD session: ` + chalk.cyan('/odd'));
   console.log();
 }
 

package/bin/odd-studio.js

@@ -15,7 +15,7 @@ import { registerUninstall } from './commands/uninstall.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const require = createRequire(import.meta.url);
-const pkg = require('../package.json'); // v3.3.1
+const pkg = require('../package.json'); // v3.3.3
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const deps = { PACKAGE_ROOT, print };

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.3.1",
+  "version": "3.3.3",
   "description": "Outcome-Driven Development planning and build harness for domain experts building serious software with AI.",
   "author": {
     "name": "ODD Studio"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.3.1",
+  "version": "3.3.3",
   "description": "Outcome-Driven Development for AI coding agents — a planning and build harness for domain experts building serious software with AI. Works with Claude Code, OpenCode, and Codex.",
   "keywords": [
     "claude-code",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "odd"
-version: "3.3.1"
+version: "3.3.3"
 description: "Outcome-Driven Development planning and build coach. Use /odd to start or resume an ODD project — building personas, writing outcomes, mapping contracts, creating a Master Implementation Plan, and directing a odd-flow-powered build. Designed for domain experts who are not developers. Works with Claude Code, OpenCode, and Codex."
 ---
 
@@ -35,7 +35,7 @@ Display this when no existing state is found:
 
 ---
 
-Welcome to ODD Studio v3.3.1.
+Welcome to ODD Studio v3.3.3.
 
 You are about to plan and build something real — using a methodology called Outcome-Driven Development. Before we write a single line of code, we are going to get precise about three things:
 
@@ -59,7 +59,7 @@ Display this when existing state is found. Replace the bracketed values with act
 
 ---
 
-Welcome back to ODD Studio v3.3.1.
+Welcome back to ODD Studio v3.3.3.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]

package/templates/AGENTS.md

@@ -1,6 +1,20 @@
-# {{PROJECT_NAME}} — OpenCode Configuration
+# {{PROJECT_NAME}} — Agent Configuration
 # Powered by ODD Studio (Outcome-Driven Development)
 
+## How to Start ODD
+
+This project uses ODD Studio for planning and building. To activate the ODD coach:
+
+**In Codex:** Say `use ODD` or `start ODD` — there is no `/odd` slash command in Codex.
+The agent will read the coaching protocol below and guide you through planning or building.
+
+**In OpenCode:** Type `/odd` to start.
+
+When activated, read the full coaching protocol:
+- `plugins/odd-studio/skills/odd/SKILL.md` (Codex) or `.opencode/commands/odd/SKILL.md` (OpenCode)
+
+Then execute the startup state check documented in that file.
+
 ## Project Context
 This project is built using Outcome-Driven Development. All build decisions flow from the
 outcomes documented in `docs/outcomes/` and the plan in `docs/plan.md`.
@@ -134,7 +148,9 @@ _Until then, the ODD defaults apply:_
 _This section is populated by Rachel during Step 9b of the planning phase._
 
 ## Session Start Protocol
-Every new session begins with:
+Every new session begins with the user saying **"use ODD"** or **"start ODD"**.
+When you see this, read the full coaching protocol from the skill file (see "How to Start ODD" above),
+then run the startup state check:
 ```
 Read docs/plan.md and docs/outcomes/. We are in Phase [X].
 Phase [A...] is complete and verified.