odd-studio 3.7.6 → 3.7.8

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

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

package/hooks/odd-studio.sh

@@ -149,8 +149,8 @@ build-gate)
   fi
 
   if ! marker_valid ".odd/.odd-flow-agents-ready" 7200; then
-    echo "ODD STUDIO [build-gate]: Task agents blocked — odd-flow swarm not initialised." >&2
-    echo "Run the full 9-step swarm init sequence (see *build protocol step 7)." >&2
+    echo "ODD STUDIO [build-gate]: Executor agents blocked — odd-flow swarm not initialised." >&2
+    echo "Run the full swarm init sequence before dispatching Agent tool work." >&2
     exit 2
   fi
   exit 0
@@ -161,10 +161,10 @@ build-gate)
 # ─────────────────────────────────────────────────────────────────────────────
 # Two-marker system:
 #   1. .odd/.odd-flow-swarm-active  — created by *build, 24h TTL (session marker)
-#   2. .odd/.odd-flow-agent-token    — created by Task agents before each write batch, 120s TTL
+#   2. .odd/.odd-flow-agent-token   — created by hooks for active executor agents, 30m TTL
 #
 # The orchestrator (main conversation) can read files and coordinate, but CANNOT
-# write source code. Only Task agents can, and only after creating the agent token.
+# write source code. Only executor agents can, and only after a fresh agent token exists.
 # This prevents the LLM from bypassing swarm coordination by editing files directly.
 swarm-write)
   [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ] || exit 0
@@ -192,11 +192,11 @@ swarm-write)
     exit 0
   fi
 
-  # Gate 2: Agent write token must be fresh (120s TTL)
-  # Only Task agents create this token — the orchestrator must NOT.
-  if ! marker_valid ".odd/.odd-flow-agent-token" 120; then
+  # Gate 2: Agent write token must be fresh (30m TTL).
+  # The hooks mint and refresh this token for active executor agents.
+  if ! marker_valid ".odd/.odd-flow-agent-token" 1800; then
     echo "ODD STUDIO [swarm-write]: Source writes blocked — no agent write token." >&2
-    echo "Only Task agents can write source code. The orchestrator must dispatch work, not write code directly." >&2
+    echo "Dispatch build work with the Agent tool after swarm init. odd-flow agent_spawn only sets coordination metadata." >&2
     echo "File blocked: $FILE_PATH" >&2
     exit 2
   fi
@@ -391,15 +391,16 @@ store-validate)
 # ─────────────────────────────────────────────────────────────────────────────
 # PostToolUse: mcp__odd-flow__coordination_sync — completes swarm init
 # ─────────────────────────────────────────────────────────────────────────────
-# coordination_sync is the LAST step of the 9-step swarm init sequence.
+# coordination_sync is the LAST step of the swarm init sequence.
 # When it fires successfully in build phase, the swarm is initialised — so we
-# create all three markers atomically rather than relying on the orchestrator
+# create all required markers atomically rather than relying on the orchestrator
 # to remember a stray Bash `touch` step buried in a numbered list.
 #
 # Markers created:
 #   .odd-flow-swarm-active  — gates source writes (24h TTL)
-#   .odd-flow-agents-ready  — unblocks build-gate for Task agents
+#   .odd-flow-agents-ready  — unblocks build-gate for executor agents
 #   .odd-flow-phase-synced  — confirms agents have phase context
+#   .odd-flow-agent-token   — unlocks source writes for active executor agents
 sync-validate)
   [ "$TOOL_NAME" = "mcp__odd-flow__coordination_sync" ] || exit 0
   [ "$CURRENT_PHASE" = "build" ] || exit 0
@@ -407,6 +408,36 @@ sync-validate)
   touch .odd/.odd-flow-swarm-active 2>/dev/null
   touch .odd/.odd-flow-agents-ready 2>/dev/null
   touch .odd/.odd-flow-phase-synced 2>/dev/null
+  touch .odd/.odd-flow-agent-token 2>/dev/null
+  exit 0
+  ;;
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PreToolUse: Agent — mint write token for active executor dispatches
+# ─────────────────────────────────────────────────────────────────────────────
+agent-token-mint)
+  [ "$TOOL_NAME" = "Agent" ] || exit 0
+  [ "$CURRENT_PHASE" = "build" ] || exit 0
+
+  AGENT_PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty' | head -c 400 | tr '[:upper:]' '[:lower:]')
+  if echo "$AGENT_PROMPT" | grep -qiE '(session.brief|session-brief|generate.*brief|write.*brief|odd-sync|fix.*hook|update.*hook)'; then
+    exit 0
+  fi
+
+  marker_valid ".odd/.odd-flow-agents-ready" 7200 || exit 0
+  touch .odd/.odd-flow-agent-token 2>/dev/null
+  exit 0
+  ;;
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PostToolUse: Write|Edit — refresh write token after successful source writes
+# ─────────────────────────────────────────────────────────────────────────────
+agent-token-refresh)
+  [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ] || exit 0
+  [ "$CURRENT_PHASE" = "build" ] || exit 0
+  is_source_file "$FILE_PATH" || exit 0
+
+  touch .odd/.odd-flow-agent-token 2>/dev/null
   exit 0
   ;;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "3.7.6",
+  "version": "3.7.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/plugins/plugin-gates.js

@@ -20,7 +20,7 @@ const HALF_HOUR = 1800000;
 const TWO_HOURS = 7200000;
 const ONE_DAY = 86400000;
 const ONE_HOUR = 3600000;
-const TWO_MINUTES = 120000;
+const THIRTY_MINUTES = 1800000;
 
 function readMarker(name) {
   return resolve(process.cwd(), '.odd', name);
@@ -62,6 +62,7 @@ export function createBeforeHook(readState) {
 
     if (toolName === 'Agent' && state.currentPhase === 'build') {
       const prompt = (event.input?.prompt || '').slice(0, 300).toLowerCase();
+      const isSupportDispatch = prompt.match(/session.brief|session-brief|generate.*brief|write.*brief|odd-sync|fix.*hook|update.*hook/);
 
       if (!state.briefConfirmed && !prompt.match(/session.brief|session-brief|generate.*brief|write.*brief/)) {
         return { blocked: true, message: 'ODD BRIEF GATE: Build agents blocked — session brief not confirmed. Generate and confirm the brief first.' };
@@ -76,9 +77,13 @@ export function createBeforeHook(readState) {
       if (
         state.briefConfirmed &&
         !markerValid(readMarker('.odd-flow-agents-ready'), TWO_HOURS) &&
-        !prompt.match(/session.brief|session-brief|generate.*brief|odd-sync|fix.*hook|update.*hook/)
+        !isSupportDispatch
       ) {
-        return { blocked: true, message: 'ODD BUILD GATE: Task agents blocked — odd-flow swarm not initialised. Run the full swarm init sequence.' };
+        return { blocked: true, message: 'ODD BUILD GATE: Executor agents blocked — odd-flow swarm not initialised. Run the full swarm init sequence before dispatching Agent tool work.' };
+      }
+
+      if (state.briefConfirmed && !isSupportDispatch && markerValid(readMarker('.odd-flow-agents-ready'), TWO_HOURS)) {
+        touchMarker('.odd-flow-agent-token');
       }
     }
 
@@ -89,8 +94,8 @@ export function createBeforeHook(readState) {
 
       if (state.debugSession || markerValid(readMarker('.odd-quick-fix'), ONE_HOUR)) return;
 
-      if (!markerValid(readMarker('.odd-flow-agent-token'), TWO_MINUTES)) {
-        return { blocked: true, message: `ODD SWARM WRITE GATE: Source writes blocked — no agent write token. Only Task agents can write source code, not the orchestrator. File: ${filePath}` };
+      if (!markerValid(readMarker('.odd-flow-agent-token'), THIRTY_MINUTES)) {
+        return { blocked: true, message: `ODD SWARM WRITE GATE: Source writes blocked — no agent write token. Dispatch build work with the Agent tool after swarm init. odd-flow agent_spawn only sets coordination metadata. File: ${filePath}` };
       }
     }
 
@@ -127,6 +132,7 @@ export function createAfterHook(readState, readLastCommit, writeState) {
     if (toolName === 'Write' && isOutcomeFile(filePath)) warnings.push(...checkOutcomeQuality(filePath));
     if (toolName === 'Write' && isPersonaFile(filePath)) warnings.push(...checkPersonaQuality(filePath));
     if ((toolName === 'Write' || toolName === 'Edit') && isSrcFile(filePath)) {
+      if (state?.currentPhase === 'build') touchMarker('.odd-flow-agent-token');
       warnings.push(...checkCodeElegance(filePath));
       warnings.push(...checkSecurityBaseline(filePath));
     }
@@ -153,6 +159,7 @@ export function createAfterHook(readState, readLastCommit, writeState) {
       touchMarker('.odd-flow-swarm-active');
       touchMarker('.odd-flow-agents-ready');
       touchMarker('.odd-flow-phase-synced');
+      touchMarker('.odd-flow-agent-token');
     }
 
     if (warnings.length > 0) return { warnings };

package/scripts/hook-definitions.js

@@ -7,6 +7,7 @@ export const HOOK_GROUPS = [
     gates: [
       { name: 'brief-gate', timeout: 5, status: 'ODD brief gate...' },
       { name: 'build-gate', timeout: 5, status: 'ODD build gate...' },
+      { name: 'agent-token-mint', timeout: 5, status: 'ODD agent token...' },
     ],
   },
   {
@@ -38,6 +39,7 @@ export const HOOK_GROUPS = [
     event: 'PostToolUse',
     matcher: 'Write',
     gates: [
+      { name: 'agent-token-refresh', timeout: 5, status: 'ODD agent token refresh...' },
       { name: 'plan-complete-gate', timeout: 5, status: 'ODD plan complete gate...' },
     ],
   },
@@ -45,6 +47,7 @@ export const HOOK_GROUPS = [
     event: 'PostToolUse',
     matcher: 'Edit',
     gates: [
+      { name: 'agent-token-refresh', timeout: 5, status: 'ODD agent token refresh...' },
       { name: 'plan-complete-gate', timeout: 5, status: 'ODD plan complete gate...' },
     ],
   },

package/scripts/install-commands.js

@@ -47,13 +47,7 @@ export default async function installCommands(packageRoot, targetDir, options =
   const skillSource = path.join(packageRoot, 'skill');
   await fs.copy(skillSource, oddKnowledge, { overwrite: true });
 
-  // Rewrite the main SKILL.md path references for OpenCode
-  const mainSkill = path.join(oddKnowledge, 'SKILL.md');
-  if (fs.existsSync(mainSkill)) {
-    let content = await fs.readFile(mainSkill, 'utf8');
-    content = content.replace(/~\/\.claude\/skills\/odd\//g, '.opencode/odd/');
-    await fs.writeFile(mainSkill, content);
-  }
+  await rewriteSkillPaths(oddKnowledge);
 
   // Generate the /odd command that loads the main skill
   const oddCmd = [
@@ -76,3 +70,13 @@ export default async function installCommands(packageRoot, targetDir, options =
 
   return { destination: OC_COMMANDS, commandCount: COMMANDS.length };
 }
+
+async function rewriteSkillPaths(rootDir) {
+  const skillFiles = await fs.glob(path.join(rootDir, '**', 'SKILL.md'));
+  for (const filePath of skillFiles) {
+    let content = await fs.readFile(filePath, 'utf8');
+    content = content.replace(/~\/\.claude\/skills\/odd\//g, '.opencode/odd/');
+    content = content.replace(/\.claude\/skills\/odd\//g, '.opencode/odd/');
+    await fs.writeFile(filePath, content);
+  }
+}

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "odd"
-version: "3.7.6"
+version: "3.7.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

package/skill/docs/build/build-protocol.md

@@ -30,6 +30,57 @@ ODD Studio briefs the build AI with the full six-field specification, the releva
 
 The domain expert does not re-brief the AI, paste context, identify shared infrastructure, or check dependencies. ODD Studio handles all of that from odd-flow memory.
 
+### Step 2a — Build Execution Loop
+
+The orchestrator must execute the build. Do not stop at odd-flow swarm setup, and do not treat `mcp__odd-flow__agent_spawn` as the code-writing step. Those calls only register coordination metadata.
+
+After `coordination_sync` succeeds, run this loop:
+
+1. Read the active session brief and identify the outcomes in scope for this build session.
+2. For each in-scope outcome, break the work into concrete implementation stages. Use the smallest set that fits the outcome:
+   - data/contracts
+   - business logic/services
+   - UI/screens
+   - tests
+   - verification fixes
+3. Dispatch the real implementation work with the runtime executor agent tool. In Claude/Codex-style runtimes, this is the `Agent` tool. Use implementation agents for code changes and wait for each one to finish before moving to the next dependent stage.
+4. After each agent completes, inspect the returned summary, review the changed files, and decide the next stage:
+   - if the stage is complete, dispatch the next dependent stage
+   - if the stage exposed a gap or regression, dispatch a follow-up fix agent before continuing
+   - if stages are independent, you may dispatch them in parallel only when they do not write the same files
+5. Continue until the outcome implementation and tests are complete, then run the test gate below.
+
+**Executor prompt template**
+
+Use this shape for each implementation dispatch:
+
+```text
+You are implementing Stage [stage name] for Outcome [number]: [outcome name].
+
+Read first:
+- docs/plan.md
+- docs/outcomes/[active outcome file]
+- docs/session-brief-[n].md
+- docs/contract-map.md (if this stage produces or consumes contracts)
+- docs/ui/design-system.md (if this stage touches UI)
+- docs/build/code-excellence.md
+
+Rules:
+- Stay inside this stage and the active outcome only.
+- Design it twice: first working pass, then minimal pass.
+- Do not broaden scope or edit unrelated files.
+- Write or update tests for any pure business logic you introduce.
+- Report any spec gap in plain language before guessing.
+
+Deliver:
+- implement the stage
+- summarise files changed
+- report tests run and results
+- call out any follow-up stage the orchestrator should run next
+```
+
+For `*swarm`, run the same loop per independent outcome. Keep one executor agent per outcome track, then converge on QA and verification after implementation agents finish.
+
 ---
 
 ### Step 2b — Test

package/skill/docs/runtime/build-entry.md

@@ -60,5 +60,13 @@ When `coordination_sync` succeeds in build phase, the hook activates:
 - `.odd/.odd-flow-swarm-active`
 - `.odd/.odd-flow-agents-ready`
 - `.odd/.odd-flow-phase-synced`
+- `.odd/.odd-flow-agent-token`
 
 Do not manually touch these markers.
+
+**Important:** the odd-flow `agent_spawn` calls above are coordination metadata only. They register roles, contracts, and phase context in odd-flow, but they do not execute code changes themselves.
+
+After swarm initialisation completes, dispatch the actual build work with your runtime's executor agent tool:
+- In Claude/Codex-style runtimes, use the `Agent` tool for implementation work.
+- Treat odd-flow as the coordination layer and the `Agent` tool as the code-writing executor.
+- Do not stop after `coordination_sync`. The next action is to start the Build Execution Loop in `docs/build/build-protocol.md`.

package/skill/docs/startup/startup-protocol.md

@@ -20,7 +20,7 @@ If this is a new project, display this welcome message:
 
 ---
 
-Welcome to ODD Studio v3.7.6.
+Welcome to ODD Studio v3.7.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:
 
@@ -42,7 +42,7 @@ If this is a returning project, display this status message with real values fro
 
 ---
 
-Welcome back to ODD Studio v3.7.6.
+Welcome back to ODD Studio v3.7.8.
 
 **Project:** [project.name]
 **Current Phase:** [state.currentPhase]

package/skill/odd-build/SKILL.md

@@ -43,8 +43,8 @@ You are executing the ODD Studio `*build` command.
 
 Execute this flow:
 
-1. Read `docs/runtime/build-entry.md` from this ODD skill tree.
+1. Read `.claude/skills/odd/docs/runtime/build-entry.md`.
 2. Execute the build-entry checks exactly as written.
-3. Then read `docs/build/build-protocol.md` from this ODD skill tree and execute the build flow exactly as written.
+3. Then read `.claude/skills/odd/docs/build/build-protocol.md` and execute the build flow exactly as written.
 
 Do not spawn build agents or write source code before the brief gate passes.

package/skill/odd-debug/SKILL.md

@@ -137,7 +137,7 @@ If more than one strategy seems plausible, do not fix anything yet. Gather one m
 
 ## Fix Protocol
 
-After choosing the strategy, load `docs/build/debug-protocol.md` for the detailed investigation procedure for that strategy.
+After choosing the strategy, load `.claude/skills/odd/docs/build/debug-protocol.md` for the detailed investigation procedure for that strategy.
 
 When the fix is complete:
 

package/skill/odd-plan/SKILL.md

@@ -47,10 +47,10 @@ Execute this flow:
 
 1. Read `.odd/state.json`.
 2. Route to the next incomplete planning stage:
-   - no personas: `docs/planning/persona-architect.md`
-   - personas exist, no outcomes: `docs/planning/outcome-writer.md`
-   - outcomes exist, contracts not mapped: `docs/planning/systems-mapper.md`
-   - contracts mapped, plan not approved: `docs/planning/build-planner.md`
-   - plan approved, architecture/design docs incomplete: `docs/planning/build-planner.md`
+   - no personas: `.claude/skills/odd/docs/planning/persona-architect.md`
+   - personas exist, no outcomes: `.claude/skills/odd/docs/planning/outcome-writer.md`
+   - outcomes exist, contracts not mapped: `.claude/skills/odd/docs/planning/systems-mapper.md`
+   - contracts mapped, plan not approved: `.claude/skills/odd/docs/planning/build-planner.md`
+   - plan approved, architecture/design docs incomplete: `.claude/skills/odd/docs/planning/build-planner.md`
 3. Announce the stage and why it is next before loading the stage document.
 4. Follow the selected planning document exactly.

package/skill/odd-status/SKILL.md

@@ -42,5 +42,5 @@ You are executing the ODD Studio `*status` command.
 
 Execute this flow:
 
-1. Read `docs/runtime/status-protocol.md` from this ODD skill tree.
+1. Read `.claude/skills/odd/docs/runtime/status-protocol.md`.
 2. Execute the status protocol exactly as written.

package/skill/odd-swarm/SKILL.md

@@ -10,7 +10,7 @@ You are executing the ODD Studio `*swarm` command.
 
 Execute this flow:
 
-1. Read `docs/runtime/build-entry.md` from this ODD skill tree.
+1. Read `.claude/skills/odd/docs/runtime/build-entry.md`.
 2. Execute the build-entry checks and swarm initialisation exactly as written.
-3. Then read `docs/build/build-protocol.md` from this ODD skill tree.
+3. Then read `.claude/skills/odd/docs/build/build-protocol.md`.
 4. Execute the swarm build path for independent outcomes in the current phase.