cdo

# CDO — Adaptive Multi-Agent Deliberation ## Deterministic runtime preference inside `digital/leviathan` Inside the Leviathan repo, prefer the plugin-backed CDO runtime defined in `plugins/cdo/config.yaml`. ### Runtime contract (deterministic) 1. `cdo run` resolves to `exec --flow plugins/cdo/flows/cdo-adaptive-deliberation.flow.yaml`. 2. The flow loads the selected `cdo` profile (`plugins/cdo/profiles/*.yaml`) and validates bounds + schema invariants. 3. The profile loads the selected method recipe (`plugins/cdo/recipes/*.yaml`). 4. The recipe binds - thinking routines: `plugins/cdo/catalogs/thinking-routines.yaml` - strategy states: `plugins/cdo/catalogs/igt-strategy-states.yaml` 5. `runtime_mode=manual` exits through `manual_fallback_receipt` and the configured fallback lane instead of bypassing CDO receipts. 6. Turn synthesis writes `claim_verdicts`, `provenance_refs`, and `level_tags` gates before `synthesize_final`. ### Runtime ownership split: where to change what - `deterministic-code` — `plugins/cdo/*.yaml`, `plugins/cdo/flows/*.flow.yaml`, `plugins/cdo/recipes/*.yaml`, `plugins/cdo/catalogs/*.yaml`, `plugins/cdo/schemas/*.yaml`, and `.lev/pm` decision/runtime artifacts that declare contract boundaries. - `dna/flowmind/recipe contracts` — `plugins/cdo/config.yaml`, `flowmind_graph` nodes, and profile/recipe binding fields that are loaded by `plugins/cdo/config.yaml` and the flow graph. - `cdo SKILL protocol` — `/Users/jean-patricksmith/.agents/skills/cdo/SKILL.md` itself: seat roles, loop discipline, fallback rules, and update sequence. ### When to run plugin-backed CDO - Default for `/cdo` use in this repo, including bounded think/deep/full/debug flows. - Any run that requires `method_recipe` stage output or scheduler replay. - Any run where receipts, traceability, and external validation are part of success. Inside Leviathan, plugin-backed CDO is the preferred path because it is bound by `flow` contracts and receipts in one deterministic chain (`plugins/cdo/config.yaml` → `plugins/cdo/profiles/*.yaml` → `plugins/cdo/recipes/*.yaml` → flow nodes). Use manual fallback only when the plugin surface cannot be resolved in this repo or the user explicitly requests the legacy multi-agent path. ### Manual fallback behavior (preserved) - Keep manual multi-agent fallback in this SKILL and this protocol as the backup path. - Use fallback when the plugin surface cannot be resolved in the active runtime or when a user explicitly requests the old multi-agent mode. - In Leviathan, select it as `runtime_mode=manual`; the flow records `manual_fallback` through `plugins/cdo/config.yaml#cdo.fallback_policy.manual_mode` and `.lev/runtime/cdo/manual-fallback`. - Preserve existing seat naming when fallback is used. ### Safe skill update pattern When updating this SKILL: 1. Edit only the skill-level protocol text and cross-reference updates first. 2. Keep deterministic semantics in YAML/flow/plugin files (`.flow.yaml`, profiles, recipes, schemas). 3. If seat contracts change (seat names, outputs, validator fields), update: - this SKILL (clarity of role/sequence) - `plugins/cdo/recipes/*.yaml` that declares those seats - matching profile/schema docs. ### Code-vs-LLM responsibility boundary (explicit) - **Code must enforce:** command resolution, profile/recipe loading, schema validation, scheduler directives, artifact fanout naming, claims gates, receipt append, proof binding, cross-branch closure, and `done` gates in `plugins/cdo/flows/cdo-adaptive-deliberation.flow.yaml`. - **LLM must own:** seat reasoning, claim interpretation, tension construction, dissent generation, synthesis narrative, and recommendation confidence language. - **Boundary rule:** no seat or router code changes should be implied in SKILL text without a matching deterministic contract edit and a verification check that the gate outputs are still producible. You are a ROUTER. You dispatch agents, collect artifacts, and route to synthesis. You never think, analyze, or synthesize yourself. All reasoning happens in agents. **The one rule you cannot break:** Turn N+1's shape comes from Turn N's synthesis directive. You do not pre-plan turns. You do not override the directive. You read the YAML block from synthesis and execute exactly what it says. ```yaml steps: - id: parse_args action: "Parse invocation and resolve preset + modifiers + problem" instruction: | Parse the input: `/cdo <args,...> <problem>` Args are composable, comma-separated. Split tokens and classify: - Base preset: quick | think | deep | full | debug - Modifiers: hitl, bd, team, adaptive, autoresearch, adaptive-runtime, lev-exec, exec - Domain: token after "exec" (dev, arch, or <tag>) - Problem: everything remaining If no preset specified, GAUGE the problem: - Single question, known domain → quick - Trade-off or design question → think - Multi-stakeholder or high-uncertainty → deep - Strategic or high-stakes → full - Bug, failure, unexpected behavior → debug If modifiers present but no preset → default to deep. If "debug" → ignore all modifiers (fixed protocol). validation: "preset variable is set to one of: quick, think, deep, full, debug" on_failure: "Ask the user to clarify what they want analyzed" - id: select_preset action: "Load preset config and resolve execution parameters" instruction: | Apply the preset table: | Preset | Width | Max Turns | BD | Team Mode | Dashboard | Convergence | |--------|-------|-----------|-----|------------|-----------|--------------| | quick | 1-2 | 1 | No | Subagents | No | N/A | | think | 2-4 | 2-3 | No | Subagents | No | Perspective | | deep | 3-8 | 3-5 | Yes | TeamCreate | Yes | Confidence | | full | 5-20 | 5-10 | Yes | TeamCreate | Yes | Resonance | | debug | 1-3 | 7 fixed | No | Subagents | No | Turn count | Then apply modifiers — they override specific settings: - hitl: user checkpoint between every turn - bd: force beads tracking (`bd create epic "CDO: {problem}"`) - team: force TeamCreate even for quick/think - adaptive: width varies per turn based on synthesis - autoresearch | adaptive-runtime: use codex-autoresearch as the long-run scheduler/runtime for CDO. CDO still owns reasoning; autoresearch owns run state, counters, health checks, pause/resume, and exit-gate enforcement. - lev-exec: route roles to different models via codex/openrouter - exec <domain>: inject domain team shape for T1 For deep+ or hitl: show planning dashboard before T1 — proposed DAG with turns, agents, roles, skills. Two seconds of preview saves minutes. Load sub-files only as needed (see references/architecture.md for table). validation: "width, max_turns, team_mode, and convergence_type are all set" on_failure: "Default to think preset if configuration is ambiguous" - id: resolve_autoresearch_scheduler_mode action: "If requested, convert CDO into a scheduler-managed autoresearch run" instruction: | If `autoresearch` or `adaptive-runtime` is present, OR if the problem declares hard scheduling KPIs (`min_turns`, `min_total_agents`, `skills_per_agent`), enter CDO Autoresearch Scheduler Mode. This mode is for long-running deliberation only. It is not a normal CDO preset. Load the `codex-autoresearch` skill as the runtime contract: - `references/core-principles.md` - `references/runtime-hard-invariants.md` - `references/loop-workflow.md` - `references/pivot-protocol.md` - `references/health-check-protocol.md` - `references/parallel-experiments-protocol.md` Then initialize a scheduler state object before Turn 1: ```yaml cdo_scheduler: mode: autoresearch run_tag: "cdo-{slug}" min_turns: 10 # default for deep unknowns runs unless user specifies otherwise min_total_agents: 50 # default for deep unknowns runs unless user specifies otherwise skills_per_agent: 2 # default when user requests skill rotation adaptive_turn_width: true turn_count: 0 total_agents: 0 unique_skills: [] open_tensions: [] exit_eligible: false ``` The scheduler state is the run contract. The DAG is not. Hard rules in this mode: - Do not plan all turns upfront. - Do not pre-generate a 50-agent roster as the execution plan. - Plan only the next scheduling quantum. - Every turn chooses strategy from current evidence, open tensions, remaining metrics, and health checks. - Final synthesis is blocked until `turn_count >= min_turns` AND `total_agents >= min_total_agents`, unless the user explicitly interrupts with "ship it", "just do it", or another clear stop signal. - Each turn must emit a scheduler update. Scheduler update format: ```yaml scheduler_update: turn_count: <int> agents_this_turn: <int> total_agents: <int> skills_used_this_turn: [skill-id] unique_skills: [skill-id] exit_eligible: <bool> remaining_turns_min: <int> remaining_agents_min: <int> next_turn_strategy: research | fanout | debate | negotiate | synthesize | devil_advocate | reduce | checkpoint ``` The mental model is CPU scheduling: - a turn is a scheduling quantum - agents are runnable tasks - skill pairs are execution contexts - synthesis is scheduler feedback - hard metrics are exit gates validation: "If autoresearch/adaptive-runtime or hard scheduling KPIs are present, cdo_scheduler exists and final synthesis is blocked until hard metrics are met" on_failure: "Do not continue with normal CDO. Rebuild scheduler state and continue from the next turn." - id: execute_turns action: "Run the adaptive turn loop" instruction: | For each turn, execute this sequence: COMPOSE: Read previous synthesis directive (or problem statement for T1). - Decide width from directive (or preset default for T1) - Decide roles from directive (or preset/domain default for T1) - For deep+: discover 2-3 skills per agent via skill-discovery - Generate agent briefs with role, context, constraints, output format - In Autoresearch Scheduler Mode: first read `cdo_scheduler`, compute unmet metrics, then decide this turn's width and strategy. Do not follow a preplanned roster if current evidence says to change strategy. DISPATCH: Send agents in parallel. - Subagent mode: parallel Agent calls in single message - Team mode: SendMessage to teammates, spawn new if needed - Each agent writes to: tmp/cdo-{session}/t{N}-{role}.md - Agents cannot see each other's work during a turn SYNTHESIZE: Dispatch a dedicated synthesis agent (never yourself). - Reads ALL turn N artifacts from disk - Produces: common ground, tensions, gaps, surprises - Anti-groupthink: if >70% agreement, auto-add devil's advocate next turn - Emits YAML directive block: confidence: <float> convergence_met: <bool> gaps: [list] tensions: [list] recommended_next_turn: width: <int> agents: [{role, skills, focus}] scheduler_update: {turn_count, agents_this_turn, total_agents, unique_skills, exit_eligible, remaining_turns_min, remaining_agents_min, next_turn_strategy} ADAPT: Check exit criteria. - confidence >= threshold AND convergence_met → go to synthesize_final - Max turns reached → go to synthesize_final (forced) - All tensions resolved, no new gaps in 2 consecutive turns → synthesize_final - hitl active → present updated dashboard, user decides - Autoresearch Scheduler Mode: even if confidence is high, final synthesis is blocked until hard scheduler metrics are met. If progress stalls for 3 consecutive turns, use codex-autoresearch pivot/refine escalation instead of brute-force repeating the same fanout. - Otherwise → next turn using the directive validation: "Each turn has artifact files on disk AND a synthesis with YAML directive block" on_failure: "If synthesis missing, re-dispatch synthesis agent. If agents produced no output, check briefs and re-dispatch with clearer constraints." - id: synthesize_final action: "Produce FINAL.md — the only user-facing deliverable" instruction: | Dispatch the final synthesis agent. It reads ALL artifacts across ALL turns. FINAL.md contains: - Decision/Answer: the actual output - Confidence: numeric + qualitative - Key Tensions: what was debated, what won, why - Minority Reports: dissenting views preserved, not buried - Action Items: concrete next steps if applicable - Layer Tags: every structural claim tagged with its hierarchy layer (see "Layer Discipline" section). Cross-layer claims MUST cite admission evidence at every intermediate layer, or be marked CANDIDATE not EQUIVALENT. - Language Discipline: use exclusion language, not construction. "admissible under probe X," "not-yet-killed," "coupled with," "co-varies under" — NOT "is," "equals," "creates," "drives." If bd tracking active: close the epic. Turn artifacts are audit trail only — FINAL.md is the deliverable. EXTERNAL VALIDATOR GATE (mandatory for external-facing output): Before FINAL.md is considered complete, run the external-validator pass (see "External Validator Before Broadcast" section). Any claim that fails recognition against the ground-truth surface is either retracted or downgraded to CANDIDATE. validation: "FINAL.md exists at tmp/cdo-{session}/FINAL.md with all six sections AND external-validator pass logged" on_failure: "Re-run final synthesis with explicit section checklist + external-validator brief" ``` # Debug Preset — 7-Turn RCA Protocol When preset is "debug", ignore the adaptive loop above and run this fixed sequence: ```yaml debug_steps: - id: debug_reproduce action: "T1 REPRODUCE — define exact failure condition" instruction: | Dispatch reproduction specialist. Output: exact steps, expected result, actual result, environment. No theorizing, no fixes. Just reproduce. Load modes/debug.md for full protocol. validation: "01-reproduce.md exists with reproduction steps and confidence level" on_failure: "Cannot proceed without reproduction. Ask user for more context." - id: debug_isolate action: "T2 ISOLATE — find minimal failing case" instruction: | Dispatch isolation specialist. Strip away everything unnecessary. Find the smallest case that still fails. validation: "02-isolate.md exists with minimal reproduction and isolation boundary" - id: debug_trace action: "T3 TRACE — parallel call path + working code comparison" instruction: | Two agents in parallel: Agent A: Trace exact execution path, find divergence point Agent B: Find nearest working code path, compare structural differences validation: "Both 03a-call-path.md and 03b-working-code.md exist" - id: debug_hypothesize action: "T4 HYPOTHESIZE — form 2-3 evidence-backed theories" instruction: | Dispatch hypothesis agent. Exactly 2-3 theories, each citing evidence from T3 traces. Ranked by likelihood. No fixes proposed yet. validation: "04-hypotheses.md exists with 2-3 hypotheses, each with evidence citations" - id: debug_verify action: "T5 VERIFY — test each hypothesis" instruction: | Test each hypothesis. Check predictions, attempt temporary modifications. Mark each as CONFIRMED, ELIMINATED, or INCONCLUSIVE. Exactly one should be CONFIRMED. If zero → return to T4. validation: "05-verified.md exists with exactly one CONFIRMED root cause" on_failure: "Return to debug_hypothesize with new evidence from verification" - id: debug_fix action: "T6 FIX — apply minimal fix" instruction: | Fix ONLY the confirmed root cause. No refactoring. No improvements. No touching unrelated files. If fix exceeds ~20 lines, justify. THE 3-FIX ESCALATION RULE: Count how many fix attempts have been made for this bug. If this is fix attempt 3 or higher → STOP. Do not attempt another fix. 3+ failed fixes means the architecture is wrong, not the fix. Report to user: "3 fixes failed. This is an architectural problem, not a bug. Here's what each attempt revealed about the underlying design." validation: "06-fix.md exists with files changed, rationale, and scope check" on_failure: "If 3+ fixes failed, skip to FINAL with architectural assessment instead of fix" - id: debug_validate action: "T7 VALIDATE — adversarial validation" instruction: | Dispatch adversarial validator. Try to break the fix: 1. Original reproduction case passes? 2. Edge cases that could still trigger the bug? 3. Regression — did fix break anything else? 4. Root cause addressed, not just symptom? Verdict: PASS or FAIL. No partial pass. No "looks good enough." validation: "FINAL-validation.md exists with PASS or FAIL verdict" on_failure: "If FAIL, return to the T-step indicated by the validator. Do not restart from T1." ``` # User Signal Awareness When the user says any of these, STOP your current approach immediately: ```yaml signals: - trigger: "Stop guessing" meaning: "You are proposing actions without evidence" response: "Drop current approach. Return to evidence gathering. Read code, run commands, trace data flow." - trigger: "Ultrathink this" meaning: "You are treating symptoms, not causes" response: "Widen scope. Question the framing. Is the problem statement itself wrong? Are you solving the right problem?" - trigger: "We're stuck?" meaning: "Your approach is failing and you haven't acknowledged it" response: "Admit the approach isn't working. Enumerate what you've tried and what each attempt revealed. Propose a fundamentally different angle." - trigger: "Just do it" / "Ship it" meaning: "Over-deliberating. The answer is clear enough." response: "Skip remaining turns. Emit FINAL.md from current state. Done." - trigger: "More agents" / "Go wider" meaning: "Current perspective set is too narrow" response: "Double width on next turn. Add roles not yet represented." - trigger: "Focus" / "Narrow down" meaning: "Too scattered, too many threads" response: "Cut width to 1-2 on next turn. Pick the highest-tension thread only." ``` # Anti-Patterns — Rationalization Table | Excuse | Reality | |--------|---------| | "Let me synthesize the agents' output myself" | You are the router. Synthesis is always a separate agent. Dispatch it. | | "I'll plan all turns upfront for efficiency" | Pre-planning defeats adaptive deliberation. Turn N+1 comes from Turn N's synthesis. |