Bridge Commons: Shared Contract

This document defines the shared contract that all bridge adapters implement. Every bridge reads this document and conforms to the schemas, status semantics, artifact format, and pre-flight ordering defined here.

What Bridges Are

Bridges are reference adapters — they define how to dispatch tasks to specific AI runtimes (Claude Code sub-agents, Gemini CLI, Codex CLI, OpenCode). Each bridge:

• Is a reference document, not a runnable skill
• Is read by orchestrating skills (e.g., deep-council) via the Read tool
• Has its instructions embedded into Task agent prompts — not invoked separately
• Returns a structured report conforming to this contract
• Is non-blocking — unavailability produces SKIPPED, not a failure

Pre-Flight SOP

Every bridge executes these checks in order before dispatching. Deviate only where a bridge's specific connection chain differs.

Check ordering

1. Primary connection — preferred execution path (Task tool, HTTP server, MCP)
2. Secondary connection — CLI fallback
3. Tertiary connection — API fallback (if applicable to this bridge)
4. Authentication — verify credentials for the selected path
5. Multi-agent capability — detect and record; degrade gracefully if absent
6. Timeout estimation — calculate from scope + intensity

If none of steps 1–3 succeed → return status: SKIPPED immediately. Never block the calling orchestrator.

HALTED vs SKIPPED

HALTED→SKIPPED conversion is an orchestrator responsibility. Bridges return HALTED when user input is required; the orchestrator decides whether to wait (interactive) or convert to SKIPPED (non-interactive). This conversion policy must appear in the orchestrator's output — auto_skipped_halted_bridges is a required field on any council report that auto-converts HALTED bridges.

Timeout Estimation

Calculate per request from scope and intensity. Never hardcode.

Apply any bridge-specific multiplier on top (e.g., OpenCode applies 1.5× for provider routing overhead).

final_timeout = base_timeout × intensity_multiplier × bridge_multiplier

Wrap every CLI invocation with timeout {final_timeout} or equivalent.

Input Schema

All bridges accept this standard input:

{
  "bridge_input": {
    "session_id": "unique identifier for this session",
    "scope": "files, topics, or description of what to work on",
    "task_description": "what the agent should do",
    "task_type": "review | planning | implementation | analysis | research | audit",
    "domains": ["domain1", "domain2"],
    "context_summary": "brief description of context",
    "intensity": "quick | standard | thorough"
  }
}

task_type drives how agent prompts are framed:

Execution Capability Profile

Dispatch capability is derived from task_type. Orchestrators pass task_type; bridges resolve the capability profile locally and then translate it into runtime-specific flags, agents, or sandbox values.

Bridges MUST follow this process:

1. Derive capability_profile from task_type
2. Resolve bridge-specific invocation settings from that profile
3. Inject the resolved settings into the final command or tool call
4. Record the resolved profile in the bridge output

Bridges MUST NOT treat runtime-specific controls as global policy. Values such as CLI permission flags, sandbox modes, agent names, or tool allowlists are implementation details of the selected bridge and must be chosen through this shared profile rather than hardcoded as the only execution mode.

Agent Prompt Template

Construct one prompt per domain in bridge_input.domains. Resolve {expert_role}, {focus_areas}, and {standards} from domain-registry using the Lookup Protocol in domain-registry/README.md. If no registry entry substantially covers the domain concern, synthesize a session-based virtual expert rather than falling back to a mismatched role. Adapt framing based on task_type:

You are a {expert_role}.

SCOPE: {scope}
TASK: {task_description}
CONTEXT: {context_summary}
INTENSITY: {intensity}
DOMAIN: {domain}

Focus areas: {focus_areas}
Standards:   {standards}

Return your output as JSON:
{
  "agent": "{expert_role}",
  "domain": "{domain}",
  "outputs": [
    {
      "id": "",
      "type": "finding | recommendation | plan-item | implementation-note | observation",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW | INFO | null",
      "title": "Short title",
      "description": "Detailed description",
      "evidence": "Specific reference",
      "action": "Recommended action"
    }
  ],
  "cross_domain_signals": [
    {
      "domain": "name of another domain that should examine this finding",
      "reason": "why this domain needs to weigh in"
    }
  ],
  "summary": "Brief summary",
  "confidence": "high | medium | low"
}

`cross_domain_signals` is optional. Use it when your findings have implications that fall outside your domain and require a different domain expert's perspective. Leave empty (`[]`) if no cross-domain expansion is needed.

Output Item Types

Severity Scale

Verdict Logic

Apply only when task_type is review, analysis, or audit. Set null for all other task types.

For review and analysis:

For audit (compliance-calibrated — unmet requirements warrant stricter verdicts):

Output Schema

{
  "bridge": "claude | gemini | codex | opencode",
  "model_family": "anthropic/claude | google/gemini | openai/codex | multi-provider",
  "connection_used": "native-dispatch | cli | api | http-api | mcp",
  "session_id": "...",
  "task_type": "review | planning | implementation | analysis | research",
  "capability_profile": "inspect | modify",
  "status": "COMPLETED | SKIPPED | HALTED | ABORTED",
  "skip_reason": "...",
  "halt_reason": "...",
  "halt_message": "Advisory text to surface to the user",
  "domains_covered": ["domain1", "domain2"],
  "debate_rounds": 2,
  "outputs": [
    {
      "id": "X001",
      "type": "finding | recommendation | plan-item | implementation-note | observation",
      "severity": "CRITICAL | HIGH | MEDIUM | LOW | INFO | null",
      "status": "confirmed | revised | withdrawn | disputed | discovered",
      "title": "Short title",
      "description": "Detailed description",
      "evidence": "Specific reference — file, line, quote",
      "action": "Recommended action or next step",
      "domain": "Which domain this belongs to",
      "agent": "Which agent or reviewer produced this"
    }
  ],
  "withdrawn_outputs": [...],
  "disputed_outputs": [
    {
      "output": {...},
      "unresolved_challenge": "Challenge text that was not resolved"
    }
  ],
  "verdict": "PASS | FAIL | CONCERNS | null",
  "confidence": "high | medium | low",
  "prompt_size_chars_r1": null,
  "prompt_size_chars_r2": null,
  "model_validation_warnings": []
}

Output ID prefixes: C (claude), G (gemini), X (codex), O (opencode).

Status placement rules:

• confirmed: appears in outputs array
• revised: appears in outputs array (updated finding, supersedes earlier version)
• discovered: appears in outputs array (emerged during challenge rounds)
• withdrawn: appears in withdrawn_outputs array (not in outputs)
• disputed: appears in disputed_outputs array (also retained in outputs with disputed status)

debate_rounds: number of rounds completed (0 for quick/consolidation-only, 1+ for debate mode). null when status is not COMPLETED.

Output Deduplication

When multiple agents within a bridge produce similar outputs:

1. Assign unique IDs to all outputs first
2. Identify near-identical outputs (same domain, similar title and description)
3. Keep the highest-severity version; discard the duplicate
4. Record the merge in the JSONL event log

Post-Analysis Protocol

After the initial parallel analysis, every bridge runs a post-analysis protocol before returning results. Two approaches are available — select based on intensity:

Note: These round counts apply to the bridge-commons Post-Analysis Protocol — the iterative debate used within individual bridges (Gemini, Codex, OpenCode). They are distinct from the debate-protocol skill's round counts, which govern the standalone 5-phase protocol. The two systems have different purposes and calibrations:

• Bridge Post-Analysis Protocol: lightweight, stateless-compatible, 1–3 rounds
• debate-protocol 5-phase: full adversarial, DA obligations, Phase 3 challenge loop, 3–5 rounds

For Claude with Agent Teams, this entire section is superseded by the full debate-protocol skill, which provides the same structure with async SendMessage between teammates.

Roles

Domain experts are determined by the orchestrating skill (deep-council, deep-review, etc.) before the bridge is called — the bridge receives them via bridge_input.domains and executes. Bridges do not perform domain selection.

Spawn these roles in parallel at the start of each round:

The total number of parallel agents per round = len(active_domains) + 2 (one expert per domain, plus Challenger and Integration Checker).

The initial domain list is not fixed for the lifetime of a session. During each round, domain experts and the Integration Checker may signal that additional domains need to examine a finding. The orchestrator adds those domains to the active list before the next round, spawning fresh experts for them. See Between Rounds — Orchestrator Synthesis below.

Round 1 — Initial Analysis (always runs, parallel)

All roles run simultaneously with no inter-agent communication. Each produces independent findings using the Agent Prompt Template above.

The orchestrator (bridge dispatcher or deep-council) collects all Round 1 outputs and moves to the between-rounds step.

Between Rounds — Orchestrator Synthesis

The orchestrator reviews all outputs from the previous round and builds a context packet for the next round:

1. Collect cross_domain_signals from all outputs — identify domains not yet in the active domain list
2. Add any new domains to the active domain list; these experts will be spawned fresh in the next round
3. Identify open challenges from the Challenger that weren't responded to
4. Identify conflicts between Domain Experts (same issue, different conclusions)
5. Identify gaps (cross-cutting concerns not addressed by any active domain)
6. Group challenges by target domain so experts receive only what's directed at them

Domain expansion rule: A domain in cross_domain_signals that is already active → assign challenges to that existing expert. A domain not yet active → spawn a new expert for it in the next round, providing the relevant finding as their starting context.

Context packet format:

{
  "round": 2,
  "active_domains": ["...current domain list including any newly added..."],
  "newly_added_domains": [
    {
      "domain": "name of newly added domain",
      "trigger_finding_id": "X001",
      "reason": "why this domain was added"
    }
  ],
  "previous_findings": ["...all outputs from previous round..."],
  "open_challenges": [
    {
      "challenge_id": "CH001",
      "target_finding_id": "X001",
      "challenge_text": "This finding assumes X but the evidence shows Y instead",
      "directed_at_domain": "domain name"
    }
  ],
  "synthesis": "Round 1: 5 findings. 2 challenged. 1 new domain added. Gap: coverage expanded."
}

If no open challenges, no conflicts, and no new domains to add → stop early (convergence). Do not run additional rounds.

Round N — Challenge & Response

Existing domain experts, Challenger, and Integration Checker re-run with the context packet. Newly added domain experts run for the first time with a focused prompt scoped to their trigger finding.

Existing domain expert prompt addition:

Previous findings from your domain:
{their_previous_round_outputs}

Challenges directed at your findings:
{challenges_targeting_this_domain}

For each challenge:
- If you agree: withdraw or revise the finding (update severity or description)
- If you disagree: provide evidence-backed defense
- Mark each output with status: confirmed | revised | withdrawn
- If you identify additional domains that should examine your findings, include cross_domain_signals

Newly added domain expert prompt (first appearance in Round N):

You are a {expert_role}.

SCOPE: {scope}
CONTEXT: {context_summary}

You have been brought in because a finding in another domain has implications for yours.

Trigger finding:
{the finding that produced the cross_domain_signal for this domain}

Reason you were added:
{cross_domain_signal.reason}

Analyze this finding from your domain's perspective. Produce your own findings.
Include cross_domain_signals if you identify further domain expansion needed.

Challenger prompt addition:

All domain expert findings from previous round:
{all_previous_findings}

Your previous challenges and expert responses:
{challenge_history}

For each challenge:
- If the expert defended convincingly: withdraw your challenge
- If the defense is insufficient: escalate (raise severity, add evidence)
- Challenge findings from any newly added domain experts
- Add new challenges for findings you haven't challenged yet

Integration Checker prompt addition:

All findings and challenges from previous round, including newly added domain experts:
{all_previous_findings_and_challenges}

Add new cross-component findings that emerge from the ongoing debate.
Focus on: interface gaps revealed by challenges, cascading impacts of revised findings,
and cross-cutting issues that span the newly added domains.

Termination Conditions

Stop running rounds when any of these is true:

Finding States

After debate completes, tag each output with a status field:

Withdrawn findings are excluded from the final outputs array but recorded in withdrawn_outputs.

Context Passing Between Rounds

Since non-Claude bridges lack async messaging, context flows explicitly — the orchestrator embeds the full context packet in each Round N prompt:

For bridges with session continuity (OpenCode HTTP, Codex MCP), the Round 2 prompt only needs to include the context packet — the session already has Round 1 history. For stateless bridges, embed the full previous-round findings in the prompt.

Stateless Context Size Limit

Maximum embedded context for stateless Round N prompts: 32,000 characters (combined previous-round findings + context packet).

When previous-round outputs would exceed this limit:

1. Summarize each finding to: id, title, severity, description only (drop evidence, action, agent)
2. If still over limit: retain CRITICAL and HIGH findings verbatim; reduce MEDIUM/LOW to one-line summaries ("id: title (severity)")
3. Annotate the Round N prompt with: "NOTE: Prior round context summarized due to size (>32k chars). Full outputs in .outputs/bridges/ artifact."
4. Record approximate prompt size per round in the bridge output as prompt_size_chars_r{n} (e.g., prompt_size_chars_r2: 28500)

Bridges MUST NOT silently truncate. Silent truncation produces Round N responses that are indistinguishable from valid full-context responses and corrupts multi-model confirmation reliability.

Consolidation (after final round)

After debate terminates, the orchestrator runs a final consolidation:

1. Collect all confirmed, revised, and discovered outputs — these form the final outputs array
2. Collect withdrawn outputs into withdrawn_outputs
3. Collect disputed outputs into disputed_outputs with the unresolved challenge noted
4. Apply verdict logic from the Verdict Logic section above
5. Add any remaining cross-domain outputs (domain: "cross-domain", agent: "consolidation")

For quick intensity, the consolidation is the entire protocol — skip all debate rounds and go directly here after Round 1.

Artifact Format

Every bridge saves two files per execution for auditability.

JSONL event log

Path: .outputs/bridges/{bridge}-{YYYYMMDD-HHMMSS}-{session_id}.jsonl

Write events as they occur — one JSON object per line:

{"event": "bridge_start", "bridge": "{bridge}", "session_id": "{session_id}", "timestamp": "{ISO-8601}"}
{"event": "preflight", "step": "availability_check", "result": "found", "path": "{path}"}
{"event": "preflight", "step": "timeout_estimate", "value_seconds": "{n}"}
{"event": "dispatch", "mode": "multi-agent", "domains": ["{domain1}", "{domain2}"]}
{"event": "output", "id": "{id}", "severity": "{severity}", "title": "{title}"}
{"event": "bridge_complete", "status": "COMPLETED", "verdict": "{verdict}", "output_count": "{n}", "timestamp": "{ISO-8601}"}

Markdown summary

Path: .outputs/bridges/{bridge}-{YYYYMMDD-HHMMSS}-{session_id}.md

YAML frontmatter + human-readable summary:

---
bridge: {bridge}
session_id: {session_id}
timestamp: {ISO-8601}
task_type: {task_type}
domains: [{domain1}, {domain2}]
verdict: {verdict}
status: {status}
---

Directory creation

mkdir -p .outputs/bridges

CLI Error Handling

Common patterns across all CLI-based bridges:

Invalid or unparseable output → attempt to extract structured content; if unrecoverable, return SKIPPED.

Two-Layer Debate Architecture

The full deep-council execution involves two distinct debate layers. Understanding the distinction prevents confusing the intra-bridge analysis with the cross-bridge synthesis.

deep-council
│
├── Layer 2: Intra-Bridge Analysis (runs inside each bridge, before returning to council)
│   │
│   ├── bridge-claude
│   │     Full 5-phase debate-protocol (DA + IC + domain experts via Agent Teams or Task tool)
│   │     Richest intra-bridge analysis — async messaging, multi-round adversarial
│   │
│   ├── bridge-gemini
│   │     Post-Analysis Protocol rounds (sequential, stateless prompts)
│   │     Lighter — no async messaging, 1–3 rounds via re-prompting
│   │
│   ├── bridge-codex
│   │     Post-Analysis Protocol rounds (sequential, stateless prompts)
│   │     Same pattern as gemini
│   │
│   └── bridge-opencode
│         Single-model:  Post-Analysis Protocol rounds (same as gemini/codex)
│         Multi-model:   N parallel model invocations → mini-synthesis within bridge
│                        → becomes its own mini-council before reporting to Layer 1
│
└── Layer 1: Cross-Bridge Synthesis Debate (deep-council Step 6 Stage B)
      Debate Coordinator Task agent challenges aggregated findings from ALL bridges
      DA asks: "Did all bridges agree because they're all right, or shared bias/prompting?"
      IC checks cross-bridge integration implications
      2–3 challenge rounds (standard/thorough)
      Output: confirmed / downgraded / disputed / withdrawn / integration findings

Why the asymmetry exists: bridge-claude has native sub-agent dispatch (Task tool, Agent Teams) — it can run truly parallel, async-communicating agents. CLI bridges (gemini, codex, opencode) are single-process invocations — they can only achieve multi-round analysis through sequential re-prompting, which is the Post-Analysis Protocol.

Multi-model opencode fills the gap: With 2+ models configured in .bridge-settings.json, bridge-opencode spawns one invocation per model in parallel — each model produces independent findings, and a mini-synthesis deduplicates and elevates multi-model-confirmed findings. This gives bridge-opencode a Layer 2 that is closer in depth to bridge-claude, without requiring native sub-agent dispatch.

The two layers are complementary, not redundant:

• Layer 2 (intra-bridge) maximizes what each model family can find on its own
• Layer 1 (cross-bridge) challenges whether different model families genuinely agree or just share the same blind spot

Bridge Settings

Bridges read suite configuration from .bridge-settings.json in the project root. This file is owned by the skill suite — it is not OpenCode's config, Gemini's config, or any CLI tool's config.

{
  "bridges": {
    "claude":   { "enabled": true },
    "gemini":   { "enabled": true },
    "codex":    { "enabled": true,  "model": null },
    "opencode": {
      "enabled": true,
      "model":  null,
      "models": []
    }
  },
  "reasoning_level": "medium",
  "updated": "{ISO-8601}",
  "ttl_hours": 24
}

opencode.models array — controls multi-model dispatch for bridge-opencode:

Models must use provider/model format as required by OpenCode (e.g., glm/glm-4-7, not just glm).

model (singular): legacy single-model override — ignored when models array has entries.

Model identifier validation: During bridge availability checks, if a model identifier is specified in .bridge-settings.json, bridges SHOULD perform a lightweight validation probe (e.g., codex models list, opencode auth list) to confirm the identifier is resolvable. If a model cannot be resolved:

• Emit a warning in the bridge output (not SKIPPED — the bridge itself may still work with the provider's default model)
• Record: "model_validation_warnings": [{"model": "...", "reason": "not found in provider model list"}]
• Continue execution with the provider's default model if the specified model is invalid

This prevents silent capability reduction when committed model identifiers become stale.

Notes

• Bridges do not modify source files unless capability_profile resolves to modify from task_type = implementation
• Bridges do not make external network calls beyond what their connected runtime provides
• SKIPPED is always non-blocking — orchestrators must handle it gracefully
• HALTED requires explicit user input (interactive) or orchestrator conversion to SKIPPED (non-interactive) — never silently dropped
• All fields in the output schema are required; use null where not applicable

Input Field Aliases (Deprecated)

session_id and scope are the canonical bridge-commons field names. The following aliases exist in deep-council Step 4 for backward compatibility and will be removed in a future version:

Bridges MUST accept both forms. New orchestrators SHOULD use canonical names only.