odd-studio 3.3.6 → 3.3.8

package/README.md

@@ -27,27 +27,24 @@ ODD Studio is the companion tool to **The ODD Way to Build Software with Agentic
 Add the following into Terminal inside your project folder, NOT your system root folder.
 
 ```bash
-npx odd-studio init my-project
-cd my-project
+npx odd-studio init
 ```
 
 ### For OpenCode (with Ollama / local models)
 
 ```bash
-npx odd-studio init my-project --agent opencode
-cd my-project
+npx odd-studio init --agent opencode
 ```
 
 ### For Codex
 
 ```bash
-npx odd-studio init my-project --agent codex
-cd my-project
+npx odd-studio init --agent codex
 ```
 
-In Codex, start ODD with `/odd`.
-Use `/odd-status` when you want the current project state without entering the full planning or build flow.
-`AGENTS.md` remains supporting context, but the Codex plugin command is the primary entrypoint.
+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:
 
@@ -58,15 +55,13 @@ npx odd-studio upgrade --agent codex
 ### For Claude Code and OpenCode on the same machine
 
 ```bash
-npx odd-studio init my-project --agent both
-cd my-project
+npx odd-studio init --agent both
 ```
 
 ### For every supported agent on the same machine
 
 ```bash
-npx odd-studio init my-project --agent all
-cd my-project
+npx odd-studio init --agent all
 ```
 
 Everything is installed into your project folder. Nothing is written to your home directory or installed globally.
@@ -83,7 +78,7 @@ That single command:
 **Then open your project in your AI coding agent and start ODD:**
 ```
 Claude Code / OpenCode: /odd
-Codex: /odd
+Codex: `use ODD`
 ```
 
 ---
@@ -94,7 +89,7 @@ Codex: /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/`), slash-command entrypoints (`plugins/odd-studio/commands/`), 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.
 
@@ -107,7 +102,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, OpenCode, or Codex, 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.
 
 ---
 
@@ -164,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`, plugin-local skills, and slash commands such as `/odd` and `/odd-status`.
+**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`.
 
 ---
 
@@ -228,7 +223,7 @@ The AI proposes the stack based on your outcomes. You approve it based on conseq
 
 ## Project structure
 
-After `npx odd-studio init my-project`, your project looks like this:
+After `npx odd-studio init`, your project looks like this:
 
 ```
 my-project/
@@ -325,7 +320,6 @@ npx odd-studio export                    # Instructions for exporting the Sessio
 Run from inside your existing ODD project:
 
 ```bash
-cd my-project
 npx odd-studio@latest upgrade
 ```
 

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 in Codex: ` + chalk.cyan('/odd') + chalk.dim(' (use /odd-status to inspect state first)'));
+    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. Use /odd-status for a state-only check.'));
+      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.6
+const pkg = require('../package.json'); // v3.3.8
 
 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.6",
+  "version": "3.3.8",
   "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, safety gates, and Codex slash commands such as /odd and /odd-status.",
+    "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": "Run /odd to start or resume this ODD Studio project, or /odd-status to inspect the current state",
+    "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

@@ -2,5 +2,5 @@
 
 This plugin installs the ODD Studio planning and build harness into Codex as a project-local plugin.
 
-Primary entrypoints in Codex are `/odd` to start or resume and `/odd-status` to inspect the current project state.
-`AGENTS.md` can reinforce the workflow, but the plugin command is the canonical startup path.
+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.6",
+  "version": "3.3.8",
   "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.6"
+version: "3.3.8"
 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.6.
+Welcome to ODD Studio v3.3.8.
 
 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.6.
+Welcome back to ODD Studio v3.3.8.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]
@@ -75,7 +136,7 @@ Welcome back to ODD Studio v3.3.6.
 
 **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,8 +5,8 @@
 
 This project uses ODD Studio for planning and building. To activate the ODD coach:
 
-**In Codex:** Type `/odd` to start, or `/odd-status` to check the current state before resuming.
-If slash commands are unavailable in this workspace, `use ODD`, `start ODD`, or `begin ODD` are acceptable fallbacks.
+**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.
 
@@ -148,9 +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 an explicit ODD command.
-In Codex and OpenCode, the primary entrypoint is `/odd`. In Codex, `/odd-status` is the status-only entrypoint.
-If Codex slash commands are unavailable, treat `use ODD`, `start ODD`, or `begin ODD` as `/odd`, `ODD status` as `/odd-status`, and `ODD build` as `/odd-build`.
+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.