odd-studio 3.7.5 → 3.7.7

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

@@ -126,11 +126,7 @@ Collect all failures from the verification run and send them in a single message
 
 When all steps pass on a single complete run, type `confirm`.
 
-ODD Studio runs Checkpoint — a security scan of everything built in this outcome. The domain expert does not trigger this, read the results, or action any findings. It happens automatically.
-
-If Checkpoint finds no issues, ODD Studio commits the verified state, updates odd-flow memory, and presents the next outcome.
-
-If Checkpoint finds security issues, ODD Studio briefs the build agent with the findings and triggers a fix. The domain expert waits. Once the fix is complete, Checkpoint runs again. When it is clear, the outcome is committed and the next outcome is presented.
+ODD Studio commits the verified state, updates odd-flow memory, and presents the next outcome.
 
 The domain expert did not write a commit message, update a status file, identify security issues, or decide what comes next. The tool handled all of that.
 

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

@@ -0,0 +1,41 @@
+# Confirm Protocol
+
+The domain expert types `confirm` when all verification steps for the current outcome have passed on a single complete run.
+
+## Verification gate
+
+Before `confirm` can execute:
+
+1. Every numbered verification step from the session brief must have been presented in order
+2. Each step must have been tested
+3. The domain expert must have confirmed each step passes
+4. `verificationConfirmed` must be `true` in `.odd/state.json`
+
+This is enforced by the verify gate. `verificationConfirmed` must be reset to `false` at the start of each new outcome's verification.
+
+## What verification looks like
+
+- Present each verification step in order
+- For browser-testable steps, use Playwright to check the UI
+- For multi-user steps, note them as deferred only with explicit agreement
+- For absence checks, verify the UI does not contain the element
+- Report each step as PASS / FAIL / DEFERRED
+
+## Execute in order
+
+1. Commit the verified state via git with message: `feat: verified [outcome name] — [phase]`
+2. Call `mcp__odd-flow__memory_store` key `odd-outcome-[name]` with status `verified`, namespace `odd-project`
+3. Update `.odd/state.json`: mark outcome as verified and set `nextStep`
+4. Call `mcp__odd-flow__memory_store` key `odd-project-state`, namespace `odd-project`, value set to the full updated `.odd/state.json`
+
+Then display:
+
+---
+
+**[Outcome name] — verified and committed.**
+
+**Next:** [next outcome name and one-sentence description]
+
+Type `*build` to begin, or `*status` to see the full phase progress.
+
+---

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

@@ -0,0 +1,45 @@
+# Export Protocol
+
+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.
+
+1. Read `sessionBriefCount` from `.odd/state.json` (default 0 if not set).
+2. Read `docs/plan.md` to identify which phase has outcomes not yet briefed.
+3. Load all outcome files from `docs/outcomes/` for that phase.
+4. Generate `docs/session-brief-[N].md` following the Session Brief structure in `docs/planning/build-planner.md` Step 10.
+
+The brief must include:
+
+1. Overview
+2. Active Personas This Phase
+3. Outcomes In Scope, with the complete six-field specification for each outcome
+4. Available From Previous Phases
+5. New Tables Required This Phase
+6. Build Sequence
+7. Known Failure Paths
+8. Not In Scope
+9. Infrastructure Notes
+10. Design System Reminder
+11. Changes From Original Plan
+
+Validation gate before presenting the brief:
+
+- Every outcome has its full walkthrough
+- Every outcome has its complete verification checklist
+- Every outcome has its contracts listed with field names
+- The brief is at least 200 lines long
+
+If the brief fails validation, regenerate it.
+
+Present the brief to the domain expert and wait for confirmation. If they request changes, update it and re-present.
+
+Once confirmed:
+
+- increment `sessionBriefCount`
+- update `currentBuildPhase`
+- update `currentPhase` to `build`
+- set `briefConfirmed: true`
+- store the brief in odd-flow memory with key `odd-session-brief-[N]`, namespace `odd-project`
+
+Then display:
+
+`Session Brief [N] confirmed and written to docs/session-brief-[N].md. Build gate unlocked. The build can now begin.`

package/skill/docs/chapters/chapter-10.md

@@ -8,7 +8,7 @@ The Build Protocol is the repeating rhythm of every session. It is deliberately
 
 - **The tool handles the mechanics. You handle the judgment.** ODD Studio loads context from odd-flow, reads the contract map, identifies the next outcome to build, briefs the AI, waits for the result, and presents you with a verification checklist. Your job is to follow that checklist as the persona and judge whether the result is correct.
 
-- **The session rhythm is: /odd, *build, verify, confirm. If verification fails: *debug, then verify again.** `/odd` loads the skill and restores project state from odd-flow. `*build` starts the next outcome. You verify the result against the checklist. If it fails, `*debug` classifies the failure and keeps the fix inside the active outcome. `confirm` runs Checkpoint (a security scan of what was just built), commits the verified outcome, and advances to the next one. That is it.
+- **The session rhythm is: /odd, *build, verify, confirm. If verification fails: *debug, then verify again.** `/odd` loads the skill and restores project state from odd-flow. `*build` starts the next outcome. You verify the result against the checklist. If it fails, `*debug` classifies the failure and keeps the fix inside the active outcome. `confirm` commits the verified outcome and advances to the next one. That is it.
 
 - **Re-briefing is automatic.** You do not need to remind the AI what your project is, what has been built, or what comes next. odd-flow stores all of this. ODD Studio reads it at the start of every session. If you find yourself explaining context, something is wrong with the state — not with the process.
 
@@ -22,7 +22,7 @@ The Build Protocol is the repeating rhythm of every session. It is deliberately
 
 - Building without verifying. Typing `confirm` without following the verification checklist is the fastest way to accumulate hidden defects. Every unverified outcome is a risk to every outcome that depends on it.
 
-- Worrying about security implementation. Checkpoint runs automatically before verification is completed and before commit. It scans for exposed secrets, missing authentication checks, insecure session shortcuts, and dangerous rendering or transport shortcuts in what was just built. If it finds something, the build returns to controlled debugging instead of drifting into ad hoc fixes.
+- Worrying about security implementation before the domain behaviour is even verified. Keep security requirements in the outcomes and treat code-level warnings as implementation hygiene, not as a separate parallel workflow.
 
 - Batching multiple outcomes into one build. Each outcome has its own verification checklist for a reason. Mixing them makes it impossible to know which outcome caused a failure.
 

package/skill/docs/chapters/chapter-11.md

@@ -10,15 +10,13 @@ Automated tests confirm the code does what it was told. Verification confirms it
 
 - **Verification is done as the persona.** You are not checking as yourself — you are checking as the persona in their situation. If the persona is on a phone with limited time, verify on a phone. If the persona is a first-time user, approach the interface as if you have never seen it.
 
-## What You Verify vs. What Checkpoint Verifies
+## What You Verify
 
-There are two kinds of correctness in a verified outcome. You are responsible for one. Checkpoint handles the other.
+There are two broad kinds of correctness in a verified outcome: domain correctness and implementation hygiene. Your job is the first one.
 
 **You verify domain correctness.** Does this outcome do what the persona needs it to do? Does the email contain the right information? Does the booking flow make sense to a first-time user? Does the error message explain what went wrong in plain language? Only you can answer these questions. No tool can.
 
-**Checkpoint verifies security correctness.** Did the build introduce an exposed credential? Is there a path that bypasses authentication? Could an input be used to extract data it should not be able to reach? Checkpoint scans for these automatically every time you type `confirm`. You do not need to think about them. They are not part of your verification checklist.
-
-This division of labour is deliberate. You are good at judging whether something is right for your users. You are not expected to know what an injection vulnerability looks like in code. Checkpoint is good at finding those. Neither replaces the other.
+Implementation hygiene still matters, but it is handled through code review, tests, and security baseline warnings during the build. It does not replace verification, and verification does not replace it.
 
 ## Three Rules of Verification
 

package/skill/docs/chapters/chapter-12.md

@@ -16,13 +16,13 @@ No new principles here. Everything has been introduced in earlier chapters. This
 
 **Step 5: Failure handling.** When you describe a failure, ODD Studio handles the fix. It re-reads the specification, makes the correction, and presents the checklist again. You verify again from the beginning — a partial re-verification does not count.
 
-**Step 6: confirm.** When every step passes, you type `confirm`. Before committing, ODD Studio runs Checkpoint — a security scan of what was just built. If Checkpoint finds anything, the build agent fixes it quietly and Checkpoint runs again. You see "Checkpoint clear" when it passes. ODD Studio then commits the verified outcome to git, updates odd-flow with the new project state, and advances the plan to the next outcome. The cycle is complete.
+**Step 6: confirm.** When every step passes, you type `confirm`. ODD Studio commits the verified outcome to git, updates odd-flow with the new project state, and advances the plan to the next outcome. The cycle is complete.
 
 ## What You Do vs. What the Tool Does
 
 **You do:** verify the result as the persona. Describe failures in domain language. Confirm when satisfied.
 
-**The tool does:** load context, brief the AI, run the build, present the checklist, handle fixes, run Checkpoint, brief the build agent on any security findings, commit, update state.
+**The tool does:** load context, brief the AI, run the build, present the checklist, handle fixes, commit, update state.
 
 ## Red Flags
 

package/skill/docs/chapters/chapter-14.md

@@ -22,17 +22,13 @@ The feeling that security is "too technical" is understandable but incorrect. Se
 
 - Security treated as a separate phase. Security outcomes are not an add-on. They belong in the same phase as the outcomes they constrain. The "view grades" permission outcome and the "block unauthorised grade access" prohibition outcome should be built and verified together.
 
-## Checkpoint: The Security Layer You Do Not Have to Think About
+## Implementation Hygiene
 
 Domain security — who can see what, who can do what — is your responsibility. You specify it as outcomes and verify it as the persona.
 
-Implementation security is a different category. It covers things like: a credential accidentally left in the code by the AI, a route that can be reached without authentication because the AI made a wrong assumption, an input field that accepts data it should reject. These are not failures of specification. They are failures of implementation that you would have no way to spot by reading code or clicking through a verification checklist.
+Implementation hygiene is a different category. It covers things like exposed secrets, missing authentication checks, unsafe inputs, or insecure shortcuts. These are not failures of specification. They are implementation mistakes that need disciplined review during the build.
 
-This is what Checkpoint handles. Every time you type `confirm`, Checkpoint scans what was just built. It looks for exposed secrets, missing authentication checks, unsafe inputs, and known vulnerability patterns. If it finds something, it briefs the build agent with specific fix instructions in plain language. The fix happens, Checkpoint scans again, and the cycle repeats until it is clean. You see one message: "Checkpoint clear." Then the outcome is committed.
-
-You do not need to understand what Checkpoint found. You do not need to review the fix. That is not your job. Your job is the domain. Checkpoint's job is the implementation layer.
-
-The result is that every committed outcome in your project has been verified twice: once by you for domain correctness, and once by Checkpoint for implementation security. Neither check replaces the other, and neither is optional.
+ODD Studio keeps those concerns visible through security baseline warnings, tests, and explicit debugging when something looks wrong. Your job is still the domain. The build workflow's job is to keep implementation quality visible without replacing verification.
 
 ## Two Types of Security Work
 
@@ -44,18 +40,18 @@ To be precise about the division:
 - Verify that direct URL access is blocked, not just hidden
 - Ensure data deletion outcomes exist wherever data is collected
 
-**Checkpoint's security work** (done automatically at `confirm`):
+**Implementation hygiene work** (done during build and review):
 - Detect exposed credentials and secrets in code
 - Detect missing or bypassed authentication checks
-- Detect injection vulnerabilities and unsafe inputs
-- Detect known vulnerability patterns from security databases
+- Detect unsafe rendering, storage, and transport shortcuts
+- Fix anything suspicious before the outcome is treated as complete
 
-Do both. Neither is enough alone.
+Do both. Neither domain verification nor implementation hygiene is enough alone.
 
 ## What This Means for You
 
 For every outcome that involves access to data or actions restricted to certain personas, write the corresponding prohibition outcome. Then verify both: check that the right persona can do the thing, and check that the wrong persona cannot.
 
-You already know who should see what in your system. Write it down in outcome format. Checkpoint will handle the rest of the security picture automatically.
+You already know who should see what in your system. Write it down in outcome format. Then verify the boundary and keep the implementation disciplined during the build.
 
 Next: Chapter 15 shows that interface quality is a specification problem — and gives you five principles to specify it.

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

@@ -0,0 +1,64 @@
+# Build Entry Protocol
+
+When `*build` is called, execute these checks in order before beginning:
+
+1. Check that `planApproved` is true in `.odd/state.json`. If not, explain that the plan must be approved before building, and offer `*plan` to complete it.
+2. Check that `techStackDecided` is true. If not, explain that the technical architecture decision must be made first, and route to `*phase-plan` to complete it with Rachel.
+3. Check that `designApproachDecided` is true. If not, explain that the design approach must be decided before building, and route to `*design` to complete it with Rachel.
+4. Check that `servicesConfigured` is true. If not, run the Project Setup Protocol below before proceeding.
+5. **Model check (advisory only).** If running on Opus, display: "**Model advisory:** The build phase runs well on Sonnet — faster and cheaper. Switch with `/model` if you prefer." Do not block or repeat if already shown this session.
+6. **Phase Brief check — HARD GATE.** Read `sessionBriefCount` from `.odd/state.json` (default 0 if not set). Check whether `docs/session-brief-[sessionBriefCount].md` exists.
+
+If the brief does NOT exist:
+- Run `*export` now to generate it
+- Wait for the brief to be fully written to disk
+- Present it to the domain expert for review
+- Wait for explicit confirmation
+- Only after confirmation: set `briefConfirmed: true` in `.odd/state.json`
+- Do NOT proceed until `briefConfirmed` is true
+- Do NOT spawn build agents, write code, create files, or modify the codebase in any way
+
+If the brief exists but `briefConfirmed` is not true in state:
+- Present it to the domain expert
+- Wait for confirmation
+- Set `briefConfirmed: true` in `.odd/state.json`
+
+7. **Initialise the odd-flow swarm — mandatory first action.**
+
+The swarm must be initialised before loading source files or planning build work. Execute the Swarm Initialisation section below in full, then proceed.
+
+8. Load `docs/build/build-protocol.md` and `docs/build/code-excellence.md` from this ODD skill tree.
+9. Confirm to the user which phase is being worked on and which outcomes are in scope.
+10. Begin the Build Protocol for the current phase.
+
+## Project Setup Protocol
+
+Run when `servicesConfigured` is false.
+
+1. **Scaffold.** If `package.json` exists, skip to step 2. If not: scaffold into a sibling directory, then rsync across excluding `.git`, `docs/`, and `node_modules/`. Fix `package.json name` after rsync.
+2. **Install deps.** Read `testingFramework` from `.odd/state.json` (default `Vitest`). Install the chosen testing stack plus production deps.
+3. **Scaffold test harness.** Create the correct config for the chosen testing stack. For Vitest, create `vitest.config.ts`, `tests/setup.ts`, `tests/setup.test.ts`, and the `test` / `test:watch` scripts.
+4. **Generate `.env.local`.** Write placeholders with comments explaining where each real value comes from.
+5. **Wait.** Display the credential list and wait for the user to confirm they have filled everything in.
+6. **Verify.** Kill port 3000 if needed, run `npm run dev`, and translate any setup failures into plain language. Repeat until the server starts cleanly.
+7. **Mark done.** Set `servicesConfigured: true` in `.odd/state.json` and confirm the development server is running.
+
+## Swarm Initialisation
+
+When `*swarm` or `*build` is called with an approved plan, execute this sequence:
+
+1. Store project state with `mcp__odd-flow__memory_store` key `odd-project-state`, namespace `odd-project`.
+2. Store shared contracts with `mcp__odd-flow__memory_store` key `odd-contract-map`, namespace `odd-project`.
+3. Create the phase task with `mcp__odd-flow__task_create`.
+4. Spawn the coordinator agent with `mcp__odd-flow__agent_spawn`.
+5. Spawn the backend agent with `mcp__odd-flow__agent_spawn`.
+6. Spawn the UI agent with `mcp__odd-flow__agent_spawn`.
+7. Spawn the QA agent with `mcp__odd-flow__agent_spawn`.
+8. Finalise with `mcp__odd-flow__coordination_sync`.
+
+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`
+
+Do not manually touch these markers.

package/skill/docs/runtime/shared-commands.md

@@ -0,0 +1,65 @@
+# Shared Commands
+
+## `*persona`
+
+Jump directly to persona work regardless of current state. Load `docs/planning/persona-architect.md` and activate Diana.
+
+## `*outcome`
+
+Jump directly to outcome writing. Check that at least one approved persona exists first. Then load `docs/planning/outcome-writer.md` and activate Marcus.
+
+## `*contracts`
+
+Jump directly to contract mapping. Check that at least one approved outcome exists. Then load `docs/planning/systems-mapper.md` and activate Theo.
+
+## `*phase-plan`
+
+Jump directly to implementation planning. Check that contracts have been mapped. Then load `docs/planning/build-planner.md` and activate Rachel.
+
+## `*ui`
+
+Load the UI excellence briefing from `docs/ui/design-system.md`.
+
+## `*agent`
+
+Create a custom agent for a domain-specific concern. Collect the concern in plain language, then call `mcp__odd-flow__agent_spawn` with the custom role and instructions.
+
+## `*chapter [n]`
+
+Load the requested chapter from `docs/chapters/`.
+
+## `*why`
+
+Explain why the current step matters in 3 to 5 paragraphs using the current state from `.odd/state.json`.
+
+## `*help`
+
+Show the ODD command list and vocabulary reminder.
+
+## `*kb`
+
+Load `docs/kb/odd-kb.md` into context and confirm it is available.
+
+## `*reset`
+
+Ask for confirmation before clearing state. If confirmed, clear `.odd/state.json`, overwrite odd-flow state with an empty project state, and tell the user to type `*plan` to start again.
+
+## Planning sequence
+
+Enforce this sequence:
+
+1. Personas
+2. Outcomes
+3. Contracts
+4. Plan
+5. Stack + Design + Architecture docs
+6. Services
+7. Phase brief
+
+## Educational coaching
+
+At key persona, outcome, contract, and phase milestones, briefly explain why the current step matters. Do not deliver coaching unprompted during the build phase.
+
+## Vocabulary enforcement
+
+If the user uses banned vocabulary, gently correct it once and move on.

package/skill/docs/runtime/status-protocol.md

@@ -0,0 +1,11 @@
+# Status Protocol
+
+Display the full current project state. Pull from both `.odd/state.json` and odd-flow memory (`mcp__odd-flow__memory_retrieve` key `odd-project-state`). Show:
+
+- Project name and description
+- All personas (name, role, acid-test status)
+- All outcomes (name, phase assignment, build status: not started / in progress / verified)
+- Contract map summary (how many contracts exposed, how many consumed, any orphans)
+- Master Implementation Plan summary (phases, outcomes per phase)
+- Current build position (phase, outcome, last verified outcome)
+- odd-flow swarm status if a swarm is active

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

@@ -0,0 +1,90 @@
+# Startup Protocol
+
+Before doing anything else, run this state check silently:
+
+1. Check whether `.odd/state.json` exists in the current working directory.
+2. Check whether `docs/plan.md` exists.
+3. Attempt to retrieve project state from odd-flow memory:
+   - Call `mcp__odd-flow__memory_retrieve` with key `odd-project-state`, namespace `odd-project`
+4. **Reconciliation — strict, no silent merging.** If both local and odd-flow state exist, compare them field-by-field. Specifically check `currentBuildPhase`, `currentPhase`, `briefConfirmed`, `sessionBriefCount`, `personas.length`, and `outcomes.length`. If ANY of these disagree:
+   - **STOP.** Do not display the welcome or status message yet.
+   - Show the user a side-by-side diff of the disagreeing fields (local value vs odd-flow value).
+   - Ask explicitly: "Local state and odd-flow state have drifted. Which should I trust as authoritative? Type `local`, `odd-flow`, or `inspect` to see the full diff."
+   - On `local`: store the full local `state.json` to odd-flow with `mcp__odd-flow__memory_store` and proceed.
+   - On `odd-flow`: write the odd-flow value to `.odd/state.json` and proceed.
+   - On `inspect`: print the full diff and ask again.
+   - Do NOT use heuristics like "richer wins" or "later phase wins" — they hide bugs. The user decides.
+5. If local exists and odd-flow does not: store local to odd-flow immediately. If odd-flow exists and local does not: write odd-flow to local immediately.
+
+If this is a new project, display this welcome message:
+
+---
+
+Welcome to ODD Studio v3.7.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:
+
+**Who you are building for.** Not "users" — specific people, with specific situations, specific frustrations, and specific definitions of success. We call these Personas.
+
+**What those people need to be able to do.** Not features, not screens — Outcomes. Each outcome is a complete piece of behaviour: what triggers it, what happens step by step, what success looks like, and what can go wrong.
+
+**How the outcomes connect to each other.** Every outcome produces something and consumes something. We map these Contracts before we build, so the AI agents never make conflicting assumptions.
+
+Once your personas, outcomes, and contracts are documented, we generate a Master Implementation Plan: a phased, sequenced build order that respects every dependency. Then we start building.
+
+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 `*plan` to begin, or `*help` to see all available commands.
+
+---
+
+If this is a returning project, display this status message with real values from `.odd/state.json`:
+
+---
+
+Welcome back to ODD Studio v3.7.7.
+
+**Project:** [project.name]
+**Current Phase:** [state.currentPhase]
+**Last Session:** [state.lastSessionDate]
+
+**Progress:**
+- Personas: [personas.length] documented ([personas.approved] approved)
+- Outcomes: [outcomes.length] written ([outcomes.approved] approved)
+- Contracts: [contractsMapped ? "Mapped" : "Not yet mapped"]
+- Master Plan: [planApproved ? "Approved" : "Not yet created"]
+- Technical Stack: [techStackDecided ? techStack : "Not yet decided"]
+- Design Approach: [designApproachDecided ? designApproach : "Not yet decided"]
+
+**What's next:** [state.nextStep]
+
+Type `*plan` to continue planning, `*build` to enter build mode, `*debug` to investigate a failing outcome without leaving the ODD flow, or `*status` for full detail.
+
+---
+
+## Mandatory odd-flow checkpoints
+
+These are non-negotiable tool executions. You MUST call these odd-flow tools — not describe them, not summarise them. Actually invoke the tool at each gate.
+
+| Gate | Tool call required | When |
+|---|---|---|
+| Persona approved | `mcp__odd-flow__memory_store` key `odd-persona-[name]` namespace `odd-project` | Immediately after Diana marks a persona approved |
+| Outcome approved | `mcp__odd-flow__memory_store` key `odd-outcome-[name]` namespace `odd-project` | Immediately after Marcus marks an outcome approved |
+| Contract map complete | `mcp__odd-flow__memory_store` key `odd-contract-map` namespace `odd-project` | Immediately after Theo completes the contract map |
+| Plan approved | `mcp__odd-flow__memory_store` key `odd-plan` namespace `odd-project` | Immediately after Rachel's plan is approved |
+| Design approach decided | `mcp__odd-flow__memory_store` key `odd-design-approach` namespace `odd-project` | Immediately after Rachel's design conversation completes |
+| Phase brief confirmed | `mcp__odd-flow__memory_store` key `odd-session-brief-[N]` namespace `odd-project` | After domain expert confirms the phase brief, before building starts |
+| State update (all stages) | Write updated `.odd/state.json` | After every persona, outcome, or plan approval |
+| Session start | `mcp__odd-flow__memory_retrieve` key `odd-project-state` namespace `odd-project` | Before displaying any welcome or status message |
+| Build work complete | `mcp__odd-flow__memory_store` key `odd-project-state` namespace `odd-project` | After any build, fix, or debugging work completes |
+| Session end | `mcp__odd-flow__memory_store` key `odd-project-state` namespace `odd-project` | Before ending any session |
+
+## Session end protocol
+
+Before any session ends — whether the user says goodbye, the context is running low, or the conversation is closing — you MUST:
+
+1. Read the current `.odd/state.json`
+2. Call `mcp__odd-flow__memory_store` with key `odd-project-state`, namespace `odd-project`, value set to the full contents of `.odd/state.json`
+3. Confirm to the user: "Session state saved to odd-flow."
+
+If odd-flow is not available, continue without it and tell the user that cross-session memory will not persist this session.

package/skill/odd-build/SKILL.md

@@ -41,8 +41,10 @@ retrieval:
 
 You are executing the ODD Studio `*build` command.
 
-Read these two files now:
-1. `.claude/skills/odd/SKILL.md` — the full ODD Studio coach and build protocol
-2. `.claude/skills/odd/docs/build/build-protocol.md` — the Build Protocol detail
+Execute this flow:
 
-Then execute the `*build` protocol exactly as documented in those files, starting from the state check.
+1. Read `.claude/skills/odd/docs/runtime/build-entry.md`.
+2. Execute the build-entry checks 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

@@ -47,7 +47,7 @@ You are executing the ODD Studio `*debug` command.
 
 `*debug` activates a lightweight build session optimised for debugging, hotfixes, and security remediation work. It bypasses the full 9-step swarm init that `*build` requires — there is no agent dispatch, no task creation, no swarm spawn. The orchestrator writes code directly.
 
-This is not a shortcut around ODD. The brief-gate, verify-gate, commit-gate, and outcome verification protocol are all still enforced. What is relaxed is the agent-token requirement in `swarm-write` — the requirement that forces every source write through a background Task agent. That requirement exists to enable parallel multi-agent outcome builds. For a single targeted fix it is pure ceremony.
+This is not a shortcut around ODD. The brief gate, verify gate, and outcome verification protocol are still enforced. What is relaxed is the agent-token requirement in `swarm-write` — the requirement that forces every source write through a background Task agent. That requirement exists to enable parallel multi-agent outcome builds. For a single targeted fix it is pure ceremony.
 
 **When to use `*debug` instead of `*build`:**
 - Fixing a failing test suite
@@ -99,8 +99,6 @@ Call `mcp__odd-flow__memory_store`:
 - Value: full contents of `.odd/state.json`
 - upsert: true
 
-This single store call satisfies the `commit-gate` requirement (via `store-validate` hook) for subsequent commits in this session.
-
 ### Step 5 — Confirm to user
 
 Display:
@@ -110,7 +108,7 @@ Display:
 Debug session active.
 
 Source writes are unlocked. No agent dispatch required.
-Brief gate, verify gate, and commit gate remain enforced.
+Brief gate and verify gate remain enforced.
 
 State stored to odd-flow. Ready to investigate.
 
@@ -139,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-deploy/SKILL.md

@@ -8,7 +8,12 @@ description: "ODD Studio deploy command. Verify all outcomes are confirmed, then
 
 You are executing the ODD Studio `*deploy` command.
 
-Read this file now:
-- `.claude/skills/odd/SKILL.md` — the full ODD Studio coach
+Execute this flow:
 
-Then execute the `*deploy` protocol exactly as documented, starting from the state check.
+1. Read `.odd/state.json` and confirm:
+   - all outcomes in the current phase are verified
+   - the git working tree is clean
+   - the domain expert confirms they are ready to deploy
+2. If any outcome is unverified, display which ones remain and route to `*status`.
+3. If all outcomes are verified, run `vercel --prod`.
+4. After deployment, display the production URL, update deployment fields in `.odd/state.json`, and store the deployment record in odd-flow memory.

package/skill/odd-plan/SKILL.md

@@ -43,7 +43,14 @@ retrieval:
 
 You are executing the ODD Studio `*plan` command.
 
-Read this file now:
-- `.claude/skills/odd/SKILL.md` — the full ODD Studio coach and planning protocol
+Execute this flow:
 
-Then execute the `*plan` protocol exactly as documented, starting from the state check.
+1. Read `.odd/state.json`.
+2. Route to the next incomplete planning stage:
+   - 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

@@ -40,7 +40,7 @@ retrieval:
 
 You are executing the ODD Studio `*status` command.
 
-Read this file now:
-- `.claude/skills/odd/SKILL.md` — the full ODD Studio coach
+Execute this flow:
 
-Then execute the `*status` protocol exactly as documented, starting from the state check.
+1. Read `.claude/skills/odd/docs/runtime/status-protocol.md`.
+2. Execute the status protocol exactly as written.

package/skill/odd-swarm/SKILL.md

@@ -8,8 +8,9 @@ description: "ODD Studio swarm command. Build all independent outcomes in the cu
 
 You are executing the ODD Studio `*swarm` command.
 
-Read these two files now:
-1. `.claude/skills/odd/SKILL.md` — the full ODD Studio coach and build protocol
-2. `.claude/skills/odd/docs/build/build-protocol.md` — the Build Protocol detail
+Execute this flow:
 
-Then execute the `*swarm` protocol exactly as documented in those files, starting from the state check.
+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 `.claude/skills/odd/docs/build/build-protocol.md`.
+4. Execute the swarm build path for independent outcomes in the current phase.

package/templates/.odd/state.json

@@ -20,6 +20,7 @@
   "sessionBriefCount": 0,
   "briefConfirmed": false,
   "verificationConfirmed": false,
+  "debugSession": false,
   "swarmActive": false,
   "buildPhase": null,
   "currentBuildPhase": null,
@@ -28,9 +29,6 @@
   "debugTarget": null,
   "debugSummary": null,
   "debugStartedAt": null,
-  "checkpointStatus": "unknown",
-  "lastCheckpointAt": null,
-  "checkpointFindings": 0,
   "securityBaselineVersion": "2026-04-12",
   "notes": ""
 }