mikeng-io/agent-skills/bridge-commons

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",
    "mode": "review | audit | brainstorm | design | research | synthesis",
    "local_council_required": false,
    "context_policy": "minimal-non-leading | packetized-summary | full-context | targeted-challenge",
    "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.

Council Capability Profile

When local_council_required: true, a bridge must run the richest local council its runtime supports, or explicitly report degraded mode. It must not silently collapse into a single-answer reviewer.

Local council options:

• Agent Council: multiple role-framed agents inside the bridge/runtime.
• Model Council: multiple configured models inside the same runtime/toolchain.
• Runtime-native review: the best available local equivalent when full council mechanics are unavailable.

Bridge outputs must record:

{
  "local_council_type": "agent-council | model-council | runtime-native-review | none",
  "local_council_degraded": false,
  "degradation_reason": null,
  "diversity_sources": ["role", "model", "runtime", "toolchain"],
  "runtime": "codex | claude-code | opencode | gemini | other",
  "toolchain": [],
  "exchange_mode": "coordinator-mediated | session-continuity | direct-async | stateless-replay"
}

For brainstorm/design mode, bridges emit proposals and questions in addition to findings. For review/audit mode, findings remain primary.

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 | proposal | question | constraint | assumption | risk | experiment",
      "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": []
}