odd-studio 1.0.1 → 2.0.0

package/package.json

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

package/skill/SKILL.md

@@ -176,6 +176,22 @@ Initialise the ruflo swarm for parallel build execution. See the full Ruflo Swar
 
 ---
 
+### `*agent`
+
+Create a custom agent for a domain-specific concern. The domain expert describes what they need in plain language. ODD Studio configures the agent, assigns it to the swarm, and includes its reports in the verification output alongside the QA agent's report.
+
+Common use cases: brand voice (flag text that does not match the platform's tone), compliance (check every outcome against a regulatory standard), accessibility (review every screen against WCAG).
+
+The domain expert does not write agent code. They describe the concern:
+
+> "Every piece of text a customer sees should sound like it comes from a small, friendly independent bookshop. Flag anything that sounds corporate or uses jargon."
+
+ODD Studio creates the agent from that description. It runs on every relevant outcome and reports in domain language.
+
+After collecting the description, call `mcp__ruflo__agent_spawn` with the custom role and the domain expert's description as instructions. Confirm the agent is active and will run during the next `*build` or `*swarm` session.
+
+---
+
 ### `*export`
 
 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.
@@ -199,16 +215,24 @@ After writing the file, display: "Your Session Brief has been written to docs/se
 Load coaching content from chapter n of the ODD methodology book. Route to the appropriate file in `docs/chapters/`. If the chapter file does not exist, explain what that chapter covers conceptually and offer to explore it through dialogue.
 
 Chapter reference:
-- Chapter 1: Why features fail and outcomes succeed
-- Chapter 2: Persona depth — beyond demographics
-- Chapter 3: Writing outcomes that actually specify behaviour
-- Chapter 4: The walkthrough as specification
-- Chapter 5: Contracts — the grammar of system connections
-- Chapter 6: The Master Implementation Plan
-- Chapter 7: Build Protocol — how AI agents work from your plan
-- Chapter 8: Verification in the domain expert's language
-- Chapter 9: UI excellence for non-designers
-- Chapter 10: Handling change without breaking the plan
+- Chapter 1: It's All About Clarity
+- Chapter 2: The Right Division of Labour
+- Chapter 3: Features Aren't Enough
+- Chapter 4: Outcomes Should Be Specific
+- Chapter 5: Personas Are Load-Bearing
+- Chapter 6: Every Outcome Has a Contract
+- Chapter 7: Design the Outcome Twice
+- Chapter 8: The Master Implementation Plan
+- Chapter 9: Start from Zero
+- Chapter 10: The Build Protocol
+- Chapter 11: Verification Is Your Job
+- Chapter 12: Building One Outcome
+- Chapter 13: Concurrent Outcomes and the Swarm
+- Chapter 14: The Things That Scare You
+- Chapter 15: Good Interfaces Are Specified, Not Designed
+- Chapter 16: Managing Change
+- Chapter 17: The Swarm in Depth
+- Chapter 18: Conclusion
 
 ---
 
@@ -245,7 +269,8 @@ Display this reference:
 | `*contracts` | Map contracts with Theo |
 | `*phase-plan` | Build the Master Implementation Plan with Rachel |
 | `*ui` | Load UI excellence principles |
-| `*swarm` | Initialise ruflo swarm manually |
+| `*swarm` | Build all independent outcomes in the current phase simultaneously |
+| `*agent` | Create a custom agent for a domain-specific concern |
 | `*export` | Generate IDE Session Brief |
 | `*chapter [n]` | Load methodology coaching for chapter n |
 | `*why` | Explain why the current step matters |

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

@@ -1,532 +1,110 @@
 # ODD Studio — Build Protocol
 
-The Build Protocol is the discipline that turns a well-written ODD plan into working software. Without it, builds drift. With it, every session starts from a known position, every outcome produces verified software, and every phase ends with a coherent, integrated system.
-
-The protocol has 4 levels. They nest: sessions contain phases, phases contain outcomes, phases end with integration. You apply the right level at the right moment — you do not skip levels and you do not invent your own steps.
-
----
-
-## Level 1 — Session Protocol
-
-### Why sessions need a protocol
-
-Claude Code does not remember yesterday. Every time you open a new conversation, you are talking to someone who has never heard of your project. If you start typing "can you add the approval button to the teacher dashboard", you will get a response from someone who does not know what approval means in your domain, what the teacher dashboard is, or what state the code is in.
-
-The Session Protocol solves this. It takes 3 minutes to run and saves 15 minutes of confused AI behaviour.
-
----
-
-### Step 1 — Re-orient Claude Code at the start of every session
-
-Open Claude Code. Before you describe any work, paste this block and fill in the blanks:
-
-```
-I am continuing work on [PROJECT NAME].
-
-This is an Outcome-Driven Development project. My ODD plan is in [PATH TO PLAN FILE].
-
-Please read the plan now so you understand the domain, the personas, the outcomes, and the contracts.
-
-My last session note is below. Read it carefully.
-
-[PASTE YOUR LAST HANDOVER NOTE HERE]
-
-The code is in [PATH TO CODEBASE]. The current state is:
-- Last completed outcome: [OUTCOME NAME OR "none"]
-- Current phase: [PHASE NAME]
-- Outstanding issues: [DESCRIBE IN DOMAIN LANGUAGE OR "none"]
-
-Before we build anything, confirm you have read the plan and the handover note.
-```
-
-Do not skip the confirmation step. If Claude Code summarises what it read and the summary is wrong, correct it before proceeding.
-
----
-
-### Step 2 — Restore session state with Ruflo
-
-If you are using Ruflo for swarm coordination (recommended for phases with 3+ outcomes), restore state immediately after re-orienting:
-
-```
-Restore the Ruflo session state for this project using:
-- mcp__ruflo__session_restore with session key 'odd-[project-name]-session'
-- mcp__ruflo__memory_retrieve with key 'odd-project-state'
-
-Report back what you find.
-```
-
-Ruflo memory persists between sessions. It stores what agents built, what contracts were published, and what decisions were made. Claude Code reads this and resumes from where the swarm left off.
-
-If `memory_retrieve` returns nothing, the project is starting fresh or state was not saved. Proceed with your handover note as the source of truth.
-
----
-
-### Step 3 — The handover note system
-
-At the end of every session, you write a handover note. It takes 15 seconds. It saves the next session from 15 minutes of confusion.
-
-**The handover note template:**
-
-```
-SESSION NOTE — [DATE] [TIME]
-
-Completed this session:
-- [List outcomes or sub-tasks completed, in plain language]
-
-State of the code:
-- Last committed outcome: [OUTCOME NAME]
-- Uncommitted work: [DESCRIBE OR "none"]
-- Build is: passing / broken / partially broken
-
-Open issues:
-- [Describe any problem that was not resolved, in domain language]
-- [Example: "The fee calculation rounds to the wrong decimal in the invoice preview"]
-
-Next session should start with:
-- [The first thing to do, described clearly]
-- [Any Claude Code instruction that needs to be given immediately]
-
-Anything Claude Code needs to know:
-- [Rules discovered during this session, e.g. "Do not use server actions for the invoice endpoint — use API routes instead"]
-```
-
-Save this note as a text file in your project folder (e.g. `/docs/session-notes/2026-03-17.md`). You will paste the relevant note into your session start template every time.
-
----
-
-### Step 4 — Close a session cleanly
-
-Before you close Claude Code, do three things in order:
-
-**1. Commit what works.**
-
-Ask Claude Code:
-```
-Commit everything that is currently verified and working. Use the format:
-"Outcome [N] [name] — verified"
-or if mid-outcome:
-"WIP: [describe what is done in plain language]"
-
-Do not commit broken code without labelling it WIP.
-```
-
-**2. Write your handover note.**
-
-Fill in the template above. Do not skip this. You will not remember tomorrow what you know now.
-
-**3. Save state to Ruflo.**
-
-```
-Save the current project state to Ruflo memory using:
-- mcp__ruflo__memory_store with key 'odd-project-state'
-
-Include: last completed outcome, current phase, any open issues, and the file path of today's session note.
-```
-
----
-
-## Level 2 — Phase Protocol
-
-### What a phase is
-
-A phase is a group of outcomes that, taken together, produce a coherent capability. The Session Protocol tells you how to start and stop. The Phase Protocol tells you how to build a group of outcomes without the pieces colliding.
-
----
-
-### Step 1 — Verify previous phase dependencies
-
-Before building anything in this phase, ask:
-
-```
-Read the ODD plan. List every contract this phase depends on that was built in a previous phase.
-
-For each contract, verify:
-1. Does the code or database schema for this contract exist?
-2. Does it match what the plan specifies?
-
-Report back as a table: Contract | Exists | Matches Plan | Gap (if any)
-```
-
-Do not start building until every dependency is confirmed. If a contract is missing or wrong, fix it before proceeding. A phase built on a false assumption will require expensive rework.
-
----
-
-### Step 2 — Identify shared infrastructure for this phase
-
-Look at the outcomes in this phase. Some will share infrastructure: the same database table, the same authentication check, the same email provider, the same API endpoint.
-
-If you try to build each outcome independently, two agents will build the same table differently. They will not connect. This is the "two architects, one door" problem.
-
-Ask:
-
-```
-Read the outcomes in Phase [N]. Identify all shared infrastructure:
-- Shared database tables or schemas
-- Shared API endpoints
-- Shared authentication logic
-- Shared email or notification services
-- Shared UI components used by multiple outcomes
-
-List each shared item and which outcomes use it.
-```
-
----
-
-### Step 3 — Brief the Coordinator agent
-
-When using Ruflo for a phase with multiple outcomes, the Coordinator agent runs first. Its job is to read all the outcome contracts and publish shared technical contracts before any building begins.
-
-Initialise the swarm:
-
-```
-Initialise a Ruflo swarm for Phase [N] of [PROJECT NAME]:
-mcp__ruflo__swarm_init with topology hierarchical and max-agents 6
-
-Then spawn a Coordinator agent:
-mcp__ruflo__agent_spawn with type hierarchical-coordinator and name "phase-[N]-coordinator"
-
-Brief the Coordinator with:
-- The ODD plan (attach file path)
-- The list of outcomes in this phase
-- The list of shared infrastructure identified above
-- The instruction: "Read all outcome contracts. Publish shared technical contracts — database schemas, API shapes, component interfaces — to Ruflo memory before any other agent begins work."
-```
-
-Wait for the Coordinator to confirm contracts are published before proceeding to parallel building.
-
----
-
-### Step 4 — Verify shared infrastructure before building outcomes
-
-After the Coordinator has published contracts:
-
-```
-Retrieve the shared contracts from Ruflo:
-mcp__ruflo__memory_retrieve with key 'odd-phase-[N]-contracts'
-
-Confirm the contracts match the ODD plan. If anything is missing or wrong, correct it now.
-```
-
-Then proceed to Level 3 for each outcome.
-
----
-
-### Step 5 — After all outcomes: run Integration Protocol
-
-When all outcomes in the phase are individually verified, run Level 4. Do not skip it. Individual outcomes that pass their own verification steps can still fail to connect.
-
----
-
-## Level 3 — Outcome Protocol
-
-### Step 1 — Decide whether to stage the build
-
-Some outcomes are simple: one screen, one action, one data change. Build them in one shot.
-
-Some outcomes involve more than 2 context shifts. A context shift is any moment where the work moves from one layer to another: from database to API, from API to UI, from UI to email notification, from one persona's view to another's.
-
-**Rule: if an outcome has more than 2 context shifts, stage the build.**
-
-Staging means you build in sub-steps and verify each one before moving to the next. You tell Claude Code:
-
-```
-Build this outcome in stages. First build only the data layer. Verify it. Then build the API layer. Verify it. Then build the UI.
-```
-
-This is slower but it is almost always faster overall — because a bug found at the UI layer that originates in the data layer requires rebuilding everything above it.
-
----
-
-### Step 2 — Give Claude Code the full outcome brief
-
-Paste all 6 fields of the outcome directly into Claude Code. Do not paraphrase. Do not summarise. The exact language in the outcome document is the specification.
-
-```
-Build the following outcome. Do not begin until you have read all 6 fields.
-
-OUTCOME NAME: [name]
-PERSONA: [persona name and description]
-TRIGGER: [what causes this outcome to begin]
-EXPERIENCE: [what the persona does and sees, in full]
-CONTRACTS CONSUMED: [list of contracts this outcome uses as inputs]
-CONTRACTS EXPOSED: [list of contracts this outcome produces as outputs]
-
-Stack: Next.js App Router, TypeScript, Tailwind CSS v4, shadcn/ui, Framer Motion, PostgreSQL/Prisma, NextAuth.js.
-
-Build the full outcome. Use the domain language throughout — file names, variable names, component names must reflect the domain, not generic terms.
-```
-
----
-
-### Step 3 — Ruflo parallel building
-
-For outcomes that are large enough to benefit from parallelism, spawn 3 agents simultaneously after the Coordinator has published contracts:
-
-```
-Spawn three agents in parallel:
-
-1. Backend agent (mcp__ruflo__agent_spawn, type coder, name "outcome-[N]-backend"):
-   Brief: "Implement the data layer for Outcome [N] per the shared contracts. Build: Prisma schema, database migrations, API routes or server actions. Use domain language for all names."
-
-2. UI agent (mcp__ruflo__agent_spawn, type coder, name "outcome-[N]-ui"):
-   Brief: "Implement the UI for Outcome [N] per the shared contracts and the full outcome walkthrough. Use shadcn/ui components, Tailwind CSS v4, Framer Motion for interactions. Mobile-first. WCAG 2.1 AA."
-
-3. QA agent (mcp__ruflo__agent_spawn, type tester, name "outcome-[N]-qa"):
-   Brief: "Write verification tests for Outcome [N]. Follow the walkthrough exactly. Return results in domain language — describe failures as '[persona] cannot [action]', not as error codes."
-
-Sync state between agents using mcp__ruflo__coordination_sync.
-```
-
-Wait for all three agents to return before running the shape check.
-
----
-
-### Step 4 — Shape check
-
-Before running a full verification walkthrough, do a fast shape check:
-
-```
-Check the shape of what was built for Outcome [N]:
-1. List all files created or modified.
-2. Confirm file names use domain language (not generic names like "form.tsx" or "handler.ts").
-3. Confirm a test file exists for this outcome.
-4. Confirm the Prisma schema (if applicable) uses domain field names.
-
-Return: Pass / Needs fix for each item, with specific details.
-```
-
-Fix shape issues before verifying behaviour. A correctly-shaped codebase is far easier to debug.
+The Build Protocol is the discipline that turns a well-written ODD plan into working software. ODD Studio handles all the mechanics — context, contracts, phase tracking, re-briefing, committing. The domain expert does one thing: verify that what was built is right for real users, and describe failures in plain language.
 
 ---
 
-### Step 5 — Verification walkthrough
-
-The walkthrough in your outcome document is the script for verification. Run it literally, step by step. Do not improvise.
-
-For each step in the walkthrough:
+## The Session Rhythm
 
-```
-Verify Step [N]: [copy the step text from the outcome document]
-
-Expected: [what should happen]
-Actual: [what actually happened]
-Result: Pass / Fail / Missing
-```
-
-Run every step even if an earlier step fails. Collect all failures before asking Claude Code to fix anything.
+Every build session follows the same three steps. The tool manages continuity between sessions through ruflo memory. The domain expert never re-briefs the AI, tracks state manually, or writes handover notes.
 
 ---
 
-### Step 6 — Describing failures in domain language
-
-This is where most non-technical builders struggle. They describe failures using technical terms they do not fully understand, and Claude Code misdiagnoses the problem.
-
-**Bad failure description:**
-"The API is returning a 500 error on the POST endpoint and the state is not updating."
-
-**Good failure description:**
-"When the mentor clicks Approve on a student's application, nothing changes on screen. The application stays in Pending. If I refresh the page, the application is still Pending — so the approval did not save. The success message appeared briefly but then disappeared."
+### Step 1 — Open the project
 
-The good description tells Claude Code:
-- What persona performed the action
-- What the action was in domain terms
-- What should have changed
-- What actually changed (or did not)
-- Whether the problem is display-only or persisted to data
+Type `/odd`.
 
-Always describe failures from the persona's point of view. If you saw an error message, copy it exactly. If you saw nothing, say you saw nothing.
+ODD Studio reads the full project state from ruflo memory — personas, outcomes, contracts, phase order, verification status. It reports exactly where the build stands and what comes next. If the last session ended three days ago or three weeks ago, the state is the same. The domain expert does not need to remember anything.
 
 ---
 
-### Step 7 — Re-verify the entire outcome after fixes
+### Step 2 — Build
 
-When Claude Code fixes a failure, re-run the entire walkthrough from step 1. Not just the step that failed.
-
-Fixes frequently introduce new problems. A fix to the approval logic may break the notification email. A fix to the UI display may break the mobile layout. You will not catch these if you only re-run the failed step.
-
----
-
-### Step 8 — Commit when verified
-
-```
-Commit this outcome. Message format:
-"Outcome [N] [name] — verified"
-
-Include all files related to this outcome. Do not include files from other outcomes in the same commit.
-```
-
-Save state to Ruflo:
-
-```
-mcp__ruflo__memory_store with key 'odd-build-state'
-Include: outcome [N] complete, contracts exposed, date, any decisions made during build.
-```
-
----
+For a single outcome: type `*build`.
 
-## Level 4 — Integration Protocol
+For multiple independent outcomes in the current phase: type `*swarm`.
 
-### When to run it
+ODD Studio briefs the build AI with the full six-field specification, the relevant contracts, and the context from previous outcomes. The domain expert waits. The build takes minutes.
 
-Run the Integration Protocol after all outcomes in a phase are individually verified. Do not run it after each outcome — it is designed for the seams between outcomes, and those seams only become visible when all the pieces exist.
+The domain expert does not re-brief the AI, paste context, identify shared infrastructure, or check dependencies. ODD Studio handles all of that from ruflo memory.
 
 ---
 
-### Handshake test
+### Step 3 — Verify
 
-For every pair of outcomes where one exposes a contract and the other consumes it, run a handshake test:
+When ODD Studio reports the build is complete, the verification checklist is on screen.
 
-```
-Handshake test: Outcome [A] → Outcome [B]
+Follow each step in order. Follow them as the persona — not as yourself reviewing a system, but as the specific person in the specific situation the outcome was written for.
 
-Contract: [name the contract being passed]
+**Record each step: pass / fail / missing.**
 
-Test:
-1. Perform the action in Outcome A that produces the contract data.
-2. Navigate to Outcome B.
-3. Confirm the data produced in Outcome A is visible and correct in Outcome B.
+**Verify the failure paths.** These are not optional. They are where the AI made assumptions — what to show when the event is full, what to do when payment fails, what happens when the session expires. The happy path is what the AI builds most reliably. The failure paths are where assumptions accumulate.
 
-Expected: [describe in domain language what should appear]
-Actual: [what appeared]
-Result: Pass / Fail
-```
+**An outcome is verified when every step passes on a single complete run** — not when each step has passed at some point across multiple attempts.
 
 ---
 
-### Data flow trace
+### Describing failures
 
-Pick your most important domain entity (the thing your system revolves around: the application, the booking, the order, the assessment). Follow it through every outcome that touches it:
+When a step fails, describe it in domain language — what the person sees, what should happen instead. Not technical causes. Not error codes.
 
-```
-Trace the [ENTITY] through all outcomes in Phase [N]:
+**Good descriptions:**
+- "The confirmation email arrives but there is no calendar invitation. I cannot add the event to my calendar from the email."
+- "When I try to book an event that already has no remaining places, the booking goes through without any warning."
+- "After I cancel my booking, my account still shows it as upcoming. It only disappears when I refresh the page."
 
-For each outcome that touches this entity:
-1. How does the entity enter this outcome?
-2. What changes to it?
-3. How does it leave this outcome?
-4. Is the data consistent at every stage?
-
-Report any inconsistency.
-```
-
----
-
-### Cross-persona check
-
-If your phase involves more than one persona, verify that each persona sees what they should see and cannot see what they should not:
-
-```
-Cross-persona check for Phase [N]:
-
-For each persona:
-1. Log in as this persona (or simulate their session).
-2. Confirm they can see everything the plan specifies they should see.
-3. Confirm they cannot see data belonging to other personas.
-4. Confirm they cannot perform actions reserved for other personas.
-
-Report as: Persona | Can see [X] | Cannot see [Y] | Pass/Fail
-```
-
----
-
-### Fix failures and re-run
-
-Describe any integration failures in domain language (same rule as outcome failures). Ask Claude Code to fix them. Then re-run the handshake tests for every outcome affected by the fix — not just the test that failed.
+Collect all failures from the verification run and send them in a single message. ODD Studio re-briefs the AI with the failures and triggers a fix. After the fix, re-verify from step one — all steps, not just the ones that failed.
 
 ---
 
-### Phase commit
-
-```
-Commit Phase [N] completion. Message format:
-"Phase [N] [name] — integrated and verified"
+### Confirming
 
-This commit should contain only the integration fixes, not the individual outcome builds (those were committed separately).
-```
+When all steps pass on a single complete run, type `confirm`.
 
-Save phase state to Ruflo:
-```
-mcp__ruflo__memory_store with key 'odd-phase-[N]-complete'
-Include: all outcomes completed, contracts exposed by this phase, integration test results.
-```
+ODD Studio commits the verified state, updates ruflo memory, and presents the next outcome. The domain expert did not write a commit message, update a status file, or identify what comes next. The tool handled all of that.
 
 ---
 
-## Common Build Problems
+## Integration Protocol
 
-### "The AI built the wrong thing"
+After all outcomes in a phase are individually verified, ODD Studio runs the Integration Protocol automatically. The domain expert does not initiate this — the post-phase hook triggers it when the last outcome in the phase is confirmed.
 
-This happens when the brief was too short or used generic language. Do not say "it built the wrong thing" to Claude Code — this tells it nothing useful.
+Three checks run:
 
-Instead, describe what you expected and what appeared:
+**Handshake check.** For each pair of outcomes that share a contract, confirm the data passing between them is correct in domain terms. Does the organiser's view show the correct customer details from the booking? Does the refund outcome have access to the payment details the booking outcome recorded?
 
-```
-This is not the correct build. Here is what I expected:
+**Data flow trace.** Follow one entity — a customer, a booking, an event — through every outcome in the phase. Confirm the data is consistent. The customer's name should be the same everywhere. The booking reference should appear wherever it should appear.
 
-Persona: [name]
-Action: [what they do]
-Expected result: [what should appear, step by step]
+**Cross-persona check.** Confirm each persona sees what they should see and cannot access what they should not. Navigate as a customer to a page that should only be accessible to an organiser. Confirm it is blocked.
 
-What appeared instead:
-[Describe what you see on screen or in the code]
-
-Please read the outcome document again in full, then rebuild to match it exactly.
-```
+When all three checks pass, the phase is complete. ODD Studio marks it so, updates ruflo memory, and confirms which phase is next.
 
 ---
 
-### "The build broke something that was working"
-
-Before asking Claude Code to fix the new breakage, understand what changed:
+## Handling failures
 
-```
-Something that was working is now broken. Before making any changes:
+### Verification failure
 
-1. Run git log --oneline -10 to show recent commits.
-2. Run git diff HEAD~1 to show what changed in the last commit.
-3. Tell me in plain language what files changed and what the changes were.
+A step fails. Describe what you see and what should happen instead. One message for all failures. ODD Studio routes the fix to the AI and triggers re-verification.
 
-I will then describe what is now broken, and we will trace the cause.
-```
+### Specification gap
 
-Only after you understand what changed should you attempt a fix. Fixing without understanding the cause usually breaks something else.
+Verification reveals not a specific failure but a wrong assumption about what the outcome should do — a case that was never specified, a requirement that was invisible until the system was working.
 
----
-
-### "The AI keeps making the same mistake"
-
-If Claude Code makes the same mistake twice, the solution is a rule in CLAUDE.md, not repeated correction.
+This is not a verification failure. It is a specification gap. Type `*outcome` to open the relevant outcome and update the field that was wrong. ODD Studio saves the updated specification to ruflo memory and re-briefs the AI with the corrected version. Then rebuild and re-verify.
 
-Ask:
-```
-You have now made this mistake twice: [describe the mistake in domain language].
+### When something is consistently wrong
 
-Write a clear rule for CLAUDE.md that prevents this from happening again.
-The rule should describe the correct approach, not just forbid the wrong one.
-```
-
-Then add the rule to CLAUDE.md. Claude Code reads this file at the start of every session.
+If the same outcome fails verification repeatedly, the most likely cause is a specification problem — a walkthrough that left a case ambiguous, a verification step that cannot actually be passed as written. Return to `*outcome`, update the specification, and rebuild from the corrected version.
 
 ---
 
-### "Two outcomes were built at the same time and they do not connect"
-
-This is the "two architects, one door" problem. It happens when parallel agents build overlapping things without agreeing on the shared interface first.
+## Red flags
 
-The fix is always the same: define the shared contract explicitly, then have both sides conform to it.
+**"The build looks fine."** Fine is not verified. Fine means a visual scan was performed. An outcome that looks fine has not had its failure paths tested.
 
-```
-Two outcomes do not connect at [the seam point — e.g. the student record].
+**"I tested the main flow."** The happy path was checked. The failure paths — where the AI made assumptions — were not.
 
-Please:
-1. Show me exactly how Outcome A produces this data (the shape of what it writes or returns).
-2. Show me exactly how Outcome B expects to receive this data (the shape it reads).
-3. Identify the difference.
-4. Write a shared contract definition that both can conform to.
-5. Update both outcomes to use this shared contract.
-```
+**Describing failures in technical language.** "The API returns a 500 error" is a technical description. "When I try to book, the page shows a generic error message instead of telling me the event is full" is a domain description. Use the second.
 
-Save the fixed contract to Ruflo so future agents can read it:
-```
-mcp__ruflo__memory_store with key 'odd-contract-[contract-name]'
-```
+**Skipping verification steps.** A step skipped because it seems fine is a step that has not been verified. The outcome is verified when all steps pass on the same complete run.