causal-conductor

An econometrics-flavored orchestration overlay for oh-my-opencode-slim.

It turns the omo-slim orchestrator into a contract-first, delegation-by-default causal-analysis conductor: it gathers context by dispatching recon agents before it writes a plan, routes verification of your numbers to an independent reviewer, and runs robustness specs in parallel — instead of doing everything itself in one expensive context.

It is a thin config overlay: a few prompt + preset files dropped into your OpenCode config directory. It does not fork or vendor omo-slim — you keep installing stock omo-slim and getting its upstream updates.

Why

A capable orchestrator model, left to its own devices, just does the whole job itself: reads every script, runs the analysis, and reviews its own output. That wastes the orchestrator's context window on discovery, and — worse for econometrics — means nobody independent ever checks the numbers.

causal-conductor changes the default path:

1. Recon before the contract. Before drafting a plan, the orchestrator dispatches @explorer (your data schema + current code) and @librarian (prior work + literature) in parallel, and builds the contract from what they return. It only reads a file inline when it's a single named file it's about to edit.
2. Route the numbers to review. Estimates go to @oracle for result-verification / analysis-review / wrong-number-debugging — totals reconciled to source, joins and leakage checked, magnitudes and identification sanity-checked. A clean run is not a correct number.
3. Parallel robustness. Bounded execution and robustness/placebo/subsample specs go to @fixer, one per spec, then get reconciled.
4. Visible contract spine. The orchestrator still drafts a <spine_contract>, waits for your approval, and verifies against it before finishing — delegation stays in the open, never a hidden background swarm.

The contract is enforced (not just prompted)

This package ships the contract two layers deep:

1. Prompt (overlay/) — the orchestrator drafts a <spine_contract> and is told to wait for your approval.
2. Plugin (plugin/, causal-conductor-spine) — a standalone OpenCode plugin that structurally blocks writes. Its tool.execute.before hook throws on any edit/write/multi_edit and on obviously mutating bash (rm/mv/ cp, file redirects, sed -i, destructive git, package installs, …) until a contract is approved (canWrite). It installs next to stock oh-my-opencode-slim — no fork — because OpenCode runs every plugin's tool.execute.before, so this gate fires alongside omo-slim.

The state machine: no contract → writes blocked → you approve → writes allowed (scoped) → <spine_verified>passed</spine_verified> → finish reminder unlocks — and the next substantive turn re-blocks writes until a fresh contract is approved for the next phase.

What's hard vs. soft. The write gate and the push gate are hard: writes throw until approval, and git push throws in managed sessions even with an approved contract — pushing stays your explicit call (/spine allow-push grants exactly one). Verification and "finish" are reminder-enforced by default: the plugin injects per-state reminders (draft → implement → finish), keeps reminding the orchestrator to route @fixer output through @oracle until the oracle completes a review, and accepts <spine_verified>passed</spine_verified> from the orchestrator's own final checks. Set CAUSAL_CONDUCTOR_REQUIRE_ORACLE to make that structural too: the plugin then refuses to accept verification while a fixer run lacks an oracle review (dispatch) or an explicit VERDICT: pass (verdict — the @oracle lane ends every review with a VERDICT: line, see overlay/…/causal-spine/oracle_append.md). All gate state is persisted per session, so compaction and restarts cannot drop an owed review or an approved contract. The bash gate scans the command line, not quoted interpreter code: an Rscript -e '…' / python -c "…" one-liner can still write files (deliberate — parsing quoted code produced false blocks on read-only analysis one-liners). The gate keeps the default tool paths honest; it is not a sandbox.

/spine commands

• /spine or /spine status — contract, review-cycle, verdict, and drift status
• /spine approve — approve the latest drafted contract (deterministic; bypasses intent detection)
• /spine allow-push — permit exactly one git push
• /spine reset — clear the approved contract and gates
• /spine help

Configuration (env vars)

Variable	Default	Purpose
CAUSAL_CONDUCTOR_GATED_AGENT	orchestrator	Which agent's sessions the spine manages
CAUSAL_CONDUCTOR_SPINE_DIR	OpenCode data dir	Where per-session spine state persists
CAUSAL_CONDUCTOR_FIXER_AGENT / _ORACLE_AGENT	fixer / oracle	Lane names for the review cycle
CAUSAL_CONDUCTOR_REQUIRE_ORACLE	off	dispatch/1: oracle completion required before verified; verdict: explicit VERDICT: pass required (fail never satisfies)
CAUSAL_CONDUCTOR_ORACLE_NUDGE_DISABLED	—	Silence the routing reminder (the gate above still works)
CAUSAL_CONDUCTOR_EXTRA_WRITE_TOOLS	—	Comma-separated extra tools the write gate covers (MCP fs tools, …)
CAUSAL_CONDUCTOR_PUSH_GATE_DISABLED	—	Disable the git-push gate
CAUSAL_CONDUCTOR_EXPLORER_NUDGE_DISABLED / _THRESHOLD	— / 5	@explorer delegation nudge kill / broad-op threshold
CAUSAL_CONDUCTOR_SUPPRESS_SKILLS_DISABLED	—	Disable the duplicate-skill-body suppressor
CAUSAL_CONDUCTOR_DEBUG (alias _SUPPRESS_DEBUG)	—	Per-turn debug logs
CAUSAL_CONDUCTOR_AUDIT_DB / _AUDIT_URL / _AUDIT_MODEL, OLLAMA_API_KEY	see audit section	Session-audit source and lessons endpoint/model

Soft mode is still available: skip step 3 of the installer (don't register the plugin) and you get the prompt-only contract — a strong convention without the hard gate. Installing the plugin makes it real.

Requirements

• OpenCode with oh-my-opencode-slim installed.
• causal-powers skills installed — the preset references its skill names (question-framing, result-verification, analysis-review, …). Without it those skills silently no-op.
• Provider auth for the models in the preset (defaults: a flagship orchestrator + an independent reviewer model). Swap them for providers you have.

Install

git clone https://github.com/lancegui/causal-conductor
cd causal-conductor
./install.sh

install.sh:

• copies the prompt overlay into ~/.config/opencode/oh-my-opencode-slim/ (non-destructive — new files only),
• installs the causal-spine preset if you have no oh-my-opencode-slim.jsonc yet (else prints the merge step), and
• prints the one line to add to your opencode.jsonc plugin array to enable the enforced contract (plugin/ is pre-built — no build tool needed). Skip that line for prompt-only / soft mode.

Then edit the model ids in the preset to providers you've authenticated, and restart OpenCode — plugins, prompts, and presets load at session start only.

See DESIGN.md for why it works this way.

What goes where

File	Installs to	Purpose
overlay/oh-my-opencode-slim/orchestrator.md	~/.config/opencode/oh-my-opencode-slim/orchestrator.md	Replaces the orchestrator prompt (contract spine + recon-delegation)
overlay/oh-my-opencode-slim/causal-spine/orchestrator_append.md	same path under causal-spine/	Appends the causal lane mapping (preset-scoped)
preset/causal-spine.jsonc	merge into oh-my-opencode-slim.jsonc	Models, skills, MCP wiring for the 5 lanes
plugin/ (pre-built dist/)	register its path in opencode.jsonc plugin array	The enforced contract write-gate (causal-conductor-spine)

The prompt files rely on omo-slim's built-in prompt override (loadAgentPrompt): {agent}.md replaces an agent's prompt, {preset}/{agent}_append.md appends, both read from the config dir at runtime — no rebuild. The plugin is a standard standalone OpenCode plugin loaded next to omo-slim; its gate composes with omo-slim because OpenCode runs every plugin's tool.execute.before.

How it works (the lanes)

Lane	Model role	Job in this preset
orchestrator	flagship	Contract, routing, reconciliation, final synthesis
@explorer	fast/cheap	Map data schema + current code/pipeline
@librarian	fast/cheap + web	Prior work, literature, method/package docs
@oracle	strong, read-only	Verify the numbers; review identification
@fixer	fast	Bounded execution; parallel robustness specs

Nightly session audit ("optskills")

scripts/session-audit.mjs reads recent sessions from OpenCode's local sqlite store (read-only) and reports where the tokens went — per-tool payloads, duplicate skill-body loads, and fixer runs that never saw an @oracle review:

bun scripts/session-audit.mjs --sessions 5        # table for the last 5 sessions
bun scripts/session-audit.mjs --since 24h --json  # machine-readable

With --lessons it sends the audit to a configurable LLM endpoint and appends at most five sharpened, actionable lessons to docs/LESSONS.md. The model and endpoint are env config (defaults shown are examples — swap freely): CAUSAL_CONDUCTOR_AUDIT_MODEL (glm-5.2), CAUSAL_CONDUCTOR_AUDIT_URL (https://ollama.com/api/chat), OLLAMA_API_KEY (required for --lessons).

Run it nightly via cron:

0 2 * * * OLLAMA_API_KEY=... bun ~/Developer/causal-conductor/scripts/session-audit.mjs --since 24h --lessons >> ~/.local/share/opencode/audit.log 2>&1

Credits

Built on top of oh-my-opencode-slim by alvinunreal (MIT). The orchestrator.md prompt is derived from omo-slim's orchestrator prompt. See NOTICE.

License

MIT — see LICENSE.