Controller Modes (1.x legacy)

This page preserves 1.x behaviour and commands, not the native 2.x setup. Use the 2.x guide for current installation and usage.

Controller mode records who owns orchestration, review, and verification during task-run. Under the resolved execution mode, --primary and --reviewer also route the draft and review runtimes while the capability map continues to provide task requirements and fallback routes.

Flags

Use these flags with python3 -m bridges.orchestrator task-run:

Flag	Values	Meaning
--execution-mode	solo, duo, triad	Declares the collaboration shape. Defaults to duo, or triad when --triad is set.
--controller	codex, claude, antigravity	Declares the runtime agent accountable for orchestration metadata. Defaults to codex.
--primary	codex, claude, antigravity	Declares the primary runtime agent for the task packet.
--reviewer	codex, claude, antigravity	Declares the review runtime agent for the task packet.
--verifier	codex, claude, antigravity	Records the verification agent for audit metadata.
--solo-role-gates	strict, standard, off	Sets solo-mode gate strictness. Defaults to standard.

Invalid values are rejected by the CLI parser. Use --mcp-strict and --skills-strict when controller declarations must also fail fast on missing providers or skill specs.

Runtime Override Semantics

--primary and --reviewer override the draft and review runtime agents for task-run under the resolved execution mode; duo is the default when no mode is supplied. The capability map still supplies required skills, MCP requirements, output contracts, quality gates, and fallback routes.

• solo: --primary controls the draft runtime; reviewer is not forced unless the task still requires an independent review gate.
• duo: --primary controls draft and --reviewer controls review.
• triad: --primary controls draft, --reviewer controls review, and --verifier records the preferred verification runtime. The third audit chooses a distinct available runtime outside draft/review when possible; with the default Codex/Claude duo, that distinct runtime is Antigravity.

Fallback behavior is explicit: if a declared runtime fails preflight, the result includes Runtime agent '<agent>' unavailable and Runtime routed agent '<from>' to '<to>'.

Worker Delegation Semantics

Controller mode and worker orchestration are separate layers. Controller mode chooses runtime accountability for the task-run; worker orchestration decides whether that controller creates a limited worker_plan before merge and final review.

Use --worker-mode, --worker-adapter, and --max-workers to create and limit the worker_plan. The canonical adapter names are generic_prompt, codex_subagent, and claude_cowork.

Native Codex subagent or Claude cowork execution is an adapter detail. Task IDs, skills, MCP evidence, artifacts, and quality gates remain unchanged when the adapter changes or degrades.

Codex-Primary Mode

Use Codex-primary mode when implementation control, reproducibility, or diff inspection is the main risk.

python3 -m bridges.orchestrator task-run \
  --task-id I7 \
  --paper-type methods \
  --topic llm-bias \
  --cwd . \
  --execution-mode duo \
  --controller codex \
  --primary codex \
  --reviewer claude \
  --mcp-strict \
  --skills-strict

Expected gates:

• Codex owns command evidence, tests, and write-set discipline.
• Claude reviews research framing, hidden assumptions, prose quality, and reviewer-facing risk.
• Blocking disagreements are recorded before downstream use.

Claude-Primary Mode

Use Claude-primary mode when scholarly argument, manuscript structure, rebuttal strategy, or peer-review simulation is the main risk.

python3 -m bridges.orchestrator task-run \
  --task-id F3 \
  --paper-type empirical \
  --topic ai-in-education \
  --cwd . \
  --execution-mode duo \
  --controller claude \
  --primary claude \
  --reviewer codex \
  --mcp-strict \
  --skills-strict

Expected gates:

• Claude owns argument continuity, citation risk, and reviewer self-critique.
• Codex reviews artifact paths, contract conformance, reproducibility notes, and implementation assumptions.
• Claims without evidence become gap notes, not invented support.

Strict Validation

For controller-aware runs, strict validation means:

• --execution-mode, --controller, --primary, --reviewer, --verifier, and --solo-role-gates must use supported values.
• --mcp-strict blocks when required MCP providers are unavailable.
• --skills-strict blocks when required skill specs are missing.
• --skip-validation is only for rapid iteration; it disables strict MCP/skill checks and skips the artifact validator gate.

Controller metadata is written into the task packet so later review can see who controlled, drafted, reviewed, and verified the run.