odd-studio 3.3.5 → 3.3.7

package/README.md

@@ -45,9 +45,15 @@ npx odd-studio init my-project --agent codex
 cd my-project
 ```
 
-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`.
+In Codex, start ODD with a natural-language kickoff such as `use ODD`, `start ODD`, or `begin ODD`.
+For a state check, use `ODD status`. To continue building, use `ODD build`.
+ODD now ships Codex skill-discovery metadata so these prompts can match the plugin directly instead of relying only on `AGENTS.md`.
+
+If this project was originally set up for Claude Code or OpenCode and you want to add Codex later, run:
+
+```bash
+npx odd-studio upgrade --agent codex
+```
 
 ### For Claude Code and OpenCode on the same machine
 
@@ -77,7 +83,7 @@ That single command:
 **Then open your project in your AI coding agent and start ODD:**
 ```
 Claude Code / OpenCode: /odd
-Codex: use ODD
+Codex: `use ODD`
 ```
 
 ---
@@ -88,7 +94,7 @@ Codex: use ODD
 |-------|-------------------|---------------|
 | **Claude Code** | Project-local skills (`.claude/skills/`), hooks (`.claude/settings.local.json`), odd-flow MCP (`.mcp.json`) | Claude (Opus, Sonnet, Haiku) |
 | **OpenCode** | Project-local commands (`.opencode/commands/`), JS plugin (`.opencode/plugins/`), odd-flow MCP (`opencode.json`) | Any provider — Ollama (Qwen3-Coder, MiniMax M2.7, DeepSeek), OpenAI, Anthropic, Google, Groq, and 75+ more |
-| **Codex** | Project-local plugin (`plugins/odd-studio/`), local marketplace registration (`.agents/plugins/marketplace.json`), plugin MCP (`plugins/odd-studio/.mcp.json`) | Codex |
+| **Codex** | Project-local plugin (`plugins/odd-studio/`), skill-discovery metadata in `SKILL.md`, local marketplace registration (`.agents/plugins/marketplace.json`), plugin MCP (`plugins/odd-studio/.mcp.json`) | Codex |
 
 All supported agents get the same methodology, the same safety enforcement, and the same odd-flow-powered cross-session memory. The only difference is the delivery mechanism.
 
@@ -101,7 +107,7 @@ Your AI coding agent loads the ODD orchestrator. It checks whether you have an e
 - **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 direct commands listed below in Claude Code or OpenCode, or type sub-commands inside the active ODD session.
+From there, use the dedicated direct commands in Claude Code or OpenCode, natural-language ODD prompts in Codex, or type sub-commands inside the active ODD session once ODD is active.
 
 ---
 
@@ -158,8 +164,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.
-Codex starts through `AGENTS.md` instructions (`use ODD` / `start ODD`) rather than a guaranteed `/odd` composer command.
+**Codex:** Implemented as a project-local plugin in `plugins/odd-studio/` with `hooks.json`, plugin-local skills, and Codex skill-discovery metadata for prompts such as `use ODD`, `ODD status`, and `ODD build`.
 
 ---
 

package/bin/commands/init.js

@@ -218,7 +218,7 @@ function printNextSteps({ isClaude, isOpenCode, isCodex, projectName }) {
   }
   if (isCodex) {
     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)'));
+    console.log(`  ${stepN++}. Start ODD in Codex: ` + chalk.cyan('use ODD') + chalk.dim(' (or say ODD status to inspect state first)'));
   }
   if (isClaude || isOpenCode) {
     console.log(`  ${stepN++}. Start your ODD session: ` + chalk.cyan('/odd'));

package/bin/commands/status.js

@@ -43,7 +43,7 @@ export function registerStatus(program, deps) {
       }
 
       print.blank();
-      console.log(chalk.dim('  Open your AI coding agent and type /odd to resume.'));
+      console.log(chalk.dim('  Open your AI coding agent and resume with /odd in Claude/OpenCode or by saying use ODD in Codex. Say ODD status in Codex for a state-only check.'));
       print.blank();
     });
 }

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.5
+const pkg = require('../package.json'); // v3.3.7
 
 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.3",
+  "version": "3.3.7",
   "description": "Outcome-Driven Development planning and build harness for domain experts building serious software with AI.",
   "author": {
     "name": "ODD Studio"
@@ -21,7 +21,7 @@
   "interface": {
     "displayName": "ODD Studio",
     "shortDescription": "Guide planning, build sequencing, and verification with Outcome-Driven Development",
-    "longDescription": "Use ODD Studio to plan around personas, outcomes, contracts, and phased delivery, then run a disciplined build and verification flow with odd-flow memory and safety gates.",
+    "longDescription": "Use ODD Studio to plan around personas, outcomes, contracts, and phased delivery, then run a disciplined build and verification flow with odd-flow memory, safety gates, and Codex-native skill matching for prompts such as use ODD, ODD status, and ODD build.",
     "developerName": "ODD Studio",
     "category": "Coding",
     "capabilities": [
@@ -32,7 +32,7 @@
     "websiteURL": "https://github.com/odd-studio/odd-studio",
     "privacyPolicyURL": "https://github.com/odd-studio/odd-studio",
     "termsOfServiceURL": "https://github.com/odd-studio/odd-studio",
-    "defaultPrompt": "Start or resume an ODD Studio planning and build session for this project",
+    "defaultPrompt": "Use ODD to start or resume this ODD Studio project, or say ODD status to inspect the current state",
     "brandColor": "#111111",
     "screenshots": []
   }

package/codex-plugin/README.md

@@ -1,3 +1,6 @@
 # ODD Studio for Codex
 
 This plugin installs the ODD Studio planning and build harness into Codex as a project-local plugin.
+
+Primary entrypoints in Codex are natural-language prompts such as `use ODD`, `start ODD`, `ODD status`, and `ODD build`.
+This plugin includes Codex skill-discovery metadata so ODD can be matched from those prompts. `AGENTS.md` reinforces the workflow, but the goal is native skill pickup rather than a fake slash-command surface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.3.5",
+  "version": "3.3.7",
   "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/scripts/install-codex-commands.js

@@ -5,6 +5,7 @@ import { COMMANDS } from './command-definitions.js';
 import { CODEX_PLUGIN_NAME } from './assets.js';
 
 const CODEX_ODD_ROOT = `plugins/${CODEX_PLUGIN_NAME}/skills/odd/`;
+const CODEX_COMMAND_PREFIX = `/${CODEX_PLUGIN_NAME}:`;
 
 export default async function installCodexCommands(pluginDest) {
   const commandsDest = path.join(pluginDest, 'commands');
@@ -26,7 +27,7 @@ function buildMainCommand(cmd) {
     `description: "${cmd.description}"`,
     '---',
     '',
-    '# /odd',
+    `# ${CODEX_COMMAND_PREFIX}${cmd.name}`,
     '',
     'You are now operating as the ODD Studio coach.',
     '',
@@ -44,7 +45,7 @@ function buildSubcommand(cmd) {
     `description: "${cmd.description}"`,
     '---',
     '',
-    `# /${cmd.name}`,
+    `# ${CODEX_COMMAND_PREFIX}${cmd.name}`,
     '',
     rewriteBody(cmd.body),
     '',

package/skill/SKILL.md

@@ -1,7 +1,68 @@
 ---
 name: "odd"
-version: "3.3.5"
+version: "3.3.7"
 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."
+metadata:
+  priority: 10
+  pathPatterns:
+    - '.odd/state.json'
+    - 'docs/plan.md'
+    - 'docs/outcomes/**'
+    - 'docs/personas/**'
+    - 'docs/contract-map.md'
+    - 'docs/session-brief*.md'
+    - 'AGENTS.md'
+  bashPatterns:
+    - '\bnpx\s+odd-studio\s+status\b'
+    - '\bnpx\s+odd-studio\s+upgrade\b'
+    - '\bnpx\s+odd-studio\s+export\b'
+  promptSignals:
+    phrases:
+      - "use odd"
+      - "start odd"
+      - "begin odd"
+      - "resume odd"
+      - "continue odd"
+      - "odd studio"
+      - "outcome-driven development"
+      - "odd status"
+      - "odd build"
+      - "odd plan"
+      - "show odd status"
+      - "resume odd project"
+    allOf:
+      - [odd, status]
+      - [odd, build]
+      - [odd, plan]
+      - [outcome, driven]
+    anyOf:
+      - "odd"
+      - "outcome-driven"
+      - "persona"
+      - "outcome"
+      - "contract map"
+      - "phase brief"
+    noneOf: []
+    minScore: 5
+retrieval:
+  aliases:
+    - odd
+    - odd studio
+    - outcome-driven development
+    - odd kickoff
+    - odd coach
+  intents:
+    - start odd
+    - resume odd project
+    - show odd status
+    - continue odd planning
+    - continue odd build
+  entities:
+    - personas
+    - outcomes
+    - contracts
+    - master implementation plan
+    - phase brief
 ---
 
 # ODD Studio — Outcome-Driven Development Coach
@@ -35,7 +96,7 @@ Display this when no existing state is found:
 
 ---
 
-Welcome to ODD Studio v3.3.5.
+Welcome to ODD Studio v3.3.7.
 
 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:
 
@@ -49,7 +110,7 @@ Once your personas, outcomes, and contracts are documented, we generate a Master
 
 This process takes longer than just asking Claude to "build a platform". It is also the reason projects built this way actually work — and why projects that skip it usually get rebuilt from scratch.
 
-Ready? Type `/odd-plan` (or `*plan`) to begin, or `/odd-help` (or `*help`) to see all available commands.
+Ready? Type `*plan` to begin, or `*help` to see all available commands.
 
 ---
 
@@ -59,7 +120,7 @@ Display this when existing state is found. Replace the bracketed values with act
 
 ---
 
-Welcome back to ODD Studio v3.3.5.
+Welcome back to ODD Studio v3.3.7.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]
@@ -75,7 +136,7 @@ Welcome back to ODD Studio v3.3.5.
 
 **What's next:** [state.nextStep]
 
-Type `/odd-plan` (or `*plan`) to continue planning, `/odd-build` (or `*build`) to enter build mode, or `/odd-status` (or `*status`) for full detail.
+Type `*plan` to continue planning, `*build` to enter build mode, or `*status` for full detail.
 
 ---
 
@@ -129,7 +190,7 @@ Route to the correct planning stage based on current state:
 - If plan is approved but `techStackDecided` is false: explain the transition to technical architecture, then load `docs/planning/build-planner.md` and activate Rachel for Step 9.
 - If `techStackDecided` is true but `designApproachDecided` is false: explain the transition to design, then load `docs/planning/build-planner.md` and activate Rachel for Step 9b.
 - If `designApproachDecided` is true but `architectureDocGenerated` is not true: explain the transition to document generation, then load `docs/planning/build-planner.md` and activate Rachel for Step 9d. Rachel will generate `docs/architecture.md` and `docs/ui/design-system.md` — the authoritative reference documents that build agents read before writing any code.
-- If `architectureDocGenerated` is true: congratulate the user and suggest `/odd-build` or `*export`.
+- If `architectureDocGenerated` is true: congratulate the user and suggest `*build` or `*export`.
 
 Always announce which stage you are routing to and why before loading the sub-document.
 
@@ -341,7 +402,7 @@ Checkpoint: clear.
 
 **Next:** [next outcome name and one-sentence description]
 
-Type `/odd-build` to begin, or `/odd-status` to see the full phase progress.
+Type `*build` to begin, or `*status` to see the full phase progress.
 
 ---
 
@@ -438,7 +499,10 @@ Display this reference:
 
 **ODD Studio Commands**
 
-You can use either format: `*command` (within an `/odd` session) or `/odd-command` (as a direct slash command).
+You can use either format:
+- `*command` within an active ODD session
+- direct slash commands in hosts that support them
+- natural-language kickoff phrases in Codex such as `use ODD`, `start ODD`, `ODD status`, or `ODD build`
 
 | Within `/odd` | Direct command | What it does |
 |---|---|---|

package/skill/odd-build/SKILL.md

@@ -2,6 +2,39 @@
 name: "odd-build"
 version: "1.0.0"
 description: "ODD Studio build command. Reads project state from odd-flow memory and executes the *build protocol from the ODD Studio coach. Use /odd-build to start or continue a build session."
+metadata:
+  priority: 9
+  pathPatterns:
+    - '.odd/state.json'
+    - 'docs/plan.md'
+    - 'docs/outcomes/**'
+    - 'docs/session-brief*.md'
+  promptSignals:
+    phrases:
+      - "odd build"
+      - "start odd build"
+      - "continue odd build"
+      - "begin odd build"
+      - "resume odd build"
+    allOf:
+      - [odd, build]
+    anyOf:
+      - "build"
+      - "phase"
+      - "verification"
+      - "outcome"
+    noneOf: []
+    minScore: 5
+retrieval:
+  aliases:
+    - odd build
+    - build with odd
+  intents:
+    - start odd build
+    - continue odd build
+  entities:
+    - current build phase
+    - phase brief
 ---
 
 # /odd-build

package/skill/odd-plan/SKILL.md

@@ -2,6 +2,41 @@
 name: "odd-plan"
 version: "1.0.0"
 description: "ODD Studio planning command. Start or continue the planning phase — personas, outcomes, contracts, and Master Implementation Plan."
+metadata:
+  priority: 9
+  pathPatterns:
+    - '.odd/state.json'
+    - 'docs/plan.md'
+    - 'docs/personas/**'
+    - 'docs/outcomes/**'
+    - 'docs/contract-map.md'
+  promptSignals:
+    phrases:
+      - "odd plan"
+      - "start odd planning"
+      - "continue odd planning"
+      - "begin odd planning"
+      - "resume odd planning"
+    allOf:
+      - [odd, plan]
+    anyOf:
+      - "persona"
+      - "outcome"
+      - "contract"
+      - "plan"
+    noneOf: []
+    minScore: 5
+retrieval:
+  aliases:
+    - odd plan
+    - plan with odd
+  intents:
+    - start odd planning
+    - continue odd planning
+  entities:
+    - persona
+    - outcome
+    - contract map
 ---
 
 # /odd-plan

package/skill/odd-status/SKILL.md

@@ -2,6 +2,38 @@
 name: "odd-status"
 version: "1.0.0"
 description: "ODD Studio status command. Show full project state, phase progress, and what comes next."
+metadata:
+  priority: 9
+  pathPatterns:
+    - '.odd/state.json'
+    - 'docs/plan.md'
+    - 'docs/session-brief*.md'
+  promptSignals:
+    phrases:
+      - "odd status"
+      - "show odd status"
+      - "resume odd status"
+      - "where are we in odd"
+      - "what is the odd status"
+    allOf:
+      - [odd, status]
+    anyOf:
+      - "status"
+      - "progress"
+      - "phase"
+      - "resume"
+    noneOf: []
+    minScore: 5
+retrieval:
+  aliases:
+    - odd status
+    - odd progress
+  intents:
+    - show odd status
+    - inspect odd progress
+  entities:
+    - current phase
+    - next step
 ---
 
 # /odd-status

package/templates/AGENTS.md

@@ -5,13 +5,13 @@
 
 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 Codex:** Type `use ODD`, `start ODD`, or `begin ODD` to start.
+Use `ODD status` to check the current state before resuming, or `ODD build` to continue the build flow.
 
 **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)
+- `plugins/odd-studio/skills/odd/SKILL.md` (Codex) or `.opencode/odd/SKILL.md` (OpenCode)
 
 Then execute the startup state check documented in that file.
 
@@ -148,8 +148,10 @@ _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 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),
+Every new session begins with an explicit ODD kickoff.
+In OpenCode, the primary entrypoint is `/odd`. In Codex, the primary triggers are `use ODD`, `start ODD`, or `begin ODD`.
+Treat `ODD status` as the status check and `ODD build` as the build kickoff.
+When you see one of these triggers, read the full coaching protocol from the skill file (see "How to Start ODD" above),
 then execute the startup state check from that skill exactly as written.
 
 Do not skip straight to persona naming or build questions.