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. - `plan` and `judge` runs: before you rely on the plugin as the judge, read `plugins/cdo/profiles/` and the completion_gate in the adaptive deliberation flow. Check whether a profile carries the wave plan and whether the gate checks the run's own acceptance criteria. Cite what you read. See references/wave-planner.md (Execution backends). 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. **Plan mode (`plan` modifier) is the one exception to pre-planning.** The user approves a multi-wave plan before T1. That plan is a forecast, not a contract: before each wave, the synthesis directive and the judge's unmet criteria keep, amend or replace the planned wave, and the dashboard shows planned versus actual. The directive still wins. See references/wave-planner.md. ```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, plan, judge, modes, reality - 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 "plan" → also set "judge". 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 - plan: before T1, plan up to 10 waves (or the user's number) as a DAG, attach 1-5 discovered skills to each node, show the Wave Plan dashboard, and run only after explicit approval. Load references/wave-planner.md. - judge: after each wave, an independent judge checks the frozen acceptance criteria. Not satisfied and budget remains → run another wave aimed at the unmet criteria. Load engine/convergence.md (Type 5). - modes: run reasoning modes as bounded operators on pivotal questions, with an independent claim audit before synthesis. Load references/reasoning-operators.md. - reality: measure what is built against the stated vision, then plan and refine the bridge. Load references/reality-check.md. For deep+ or hitl: show planning dashboard before T1 — proposed DAG with turns, agents, roles, skills. Two seconds of preview saves minutes. With plan: show the Wave Plan dashboard instead (every wave, node, skill, criterion, the judge and the budget) and wait for explicit approval. 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) - Discover skills before every turn or wave for deep+, plan, or any multi-wave run (dispatch/skill-injection.md): 2-3 per agent by default, or the node's planned count of 1-5. In plan mode, start from the planned wave, then apply the directive and the judge's unmet criteria. - 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. The advocate attacks with evidence. A checked null is a valid result, and a challenge without evidence is rejected, not kept for balance. - 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. - judge active (plan or judge): the judge decides, not confidence or agreement. Dispatch it on the frozen acceptance criteria (engine/convergence.md, Type 5). Satisfied → go to synthesize_final. Not satisfied and budget remains → next wave, aimed at the unmet criteria. Budget exhausted → synthesize_final, reported as unmet. The confidence and agreement exits below apply only without a judge. - 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 - Judge Verdict (plan or judge only): each acceptance criterion as met or unmet, with evidence; a run that ended on budget says so - Wave Plan (plan only): the approved plan, then planned versus actual for each wave - 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 (plus the judge verdict when a judge ran, and the wave plan in plan mode) 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: