dual-agent-collaboration

Codex × Claude Dual-Model Collaboration

Set the current model as primary and the other CLI model as peer reviewer. Primary is responsible for the result; peer provides independent judgment and does not jointly edit the same working tree.

Core invariants:

First verify "whether what is being done is what the user really wants," then verify "whether the solution and code are correct." Two models agreeing on the same wrong contract does not count as success.

"Collaboration" here by default means: primary completes research, implementation, and self-testing, peer reads the same set of raw evidence to independently challenge and cross-check, and primary then revises according to the findings. Peer does not directly code in the shared working tree; this is precisely how this Skill generalizes the existing "Codex does the main work, Claude Code independently cross-checks" process. If the user explicitly wants the two models to divide coding work, an independent worktree must be used, and merge review must be listed separately as a task; the default mode must not be reused to secretly write in parallel.

0. Completeness and Efficiency Boundaries

"All products can use it" means the Skill can be discovered and run across projects; it does not mean every trivial task is forced to use two models. Trigger proportionally:

• The user explicitly requests the two models to collaborate, cross-check, or "fix until ACK": use this Skill in full.
• Complex solutions, cross-module development, migration, security, important refactoring, pre-release acceptance: proactively use this Skill.
• Low-risk, clearly bounded, easily reversible small fixes: by default complete with a single model; unless the user names it, do not add four rounds of model calls just for formality.

Once this Skill is triggered, fully go through all four gates: Intent, Plan, Implementation, and Final; do not omit them on the grounds of "speeding up." High efficiency comes from:

• Automatically identifying primary and selecting the other CLI;
• Unifying handoff, schema, and commands so each project does not reinvent the prompts;
• Intent/Plan stopping wrong requirements or wrong approaches as early as possible;
• Plan continuing from Intent, and repair rounds continuing from Implementation, with cold starts only when de-anchoring is needed;
• Structured fail-closed behavior, avoiding repeated manual judgment on half-finished output;
• Using a state file to automatically determine the next gate, reducing manual session tracking and missed reviews.

By default, max reasoning is the quality baseline for full collaboration; only lower it via environment variables when the user explicitly prioritizes cost/latency, and disclose this in the final result. 30 minutes is the failure ceiling, not the expected duration.

1. Choose Roles

Current initiator	Peer	Invocation parameter
Codex	Claude Code latest Opus	--peer claude
Claude Code	Codex current high-quality configuration	--peer codex
Cannot determine	Let the script detect; if detection conflicts, specify explicitly	--peer auto

Use this Skill's scripts/invoke_peer.py. The script invokes the CLI using argv + stdin, not shell concatenation; peer runs in read-only mode, with recursion protection enabled.

First do a command construction precheck:

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer auto \
  --phase intent \
  --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --add-dir <external-evidence-dir> \
  --prompt-file <handoff.md> \
  --dry-run

If the CLI does not exist, is unauthenticated, times out, or does not return a structured conclusion, treat it as BLOCKED, and do not pretend that dual-model review has already happened.

--dry-run It only proves that the parameters have been assembled; it cannot prove that the CLI can start, that permissions are correct, or that the output can be parsed. The completion evidence for any gate must come from a real invocation.

It is recommended to use --task-id, and the wrapper places state into a persistent user state directory based on "project path hash + task id": macOS uses ~/Library/Application Support/CodePal/dual-agent-workflows/, Linux uses $XDG_STATE_HOME/codepal/dual-agent-workflows/ or ~/.local/state/.... All gates for the same task reuse a stable task id; different tasks must not reuse it. This way the repository is not polluted, and gates will not be lost due to system cleanup of /tmp or a restart. Only when the integrator already has its own state storage should --state-filebe used explicitly. State stores only the verdict, session ID, and report hash, not the handoff body.

2. Prepare a complete handoff

Read references/handoff-template.md, and provide a self-contained handoff for each gate. It must include:

• The user's original words and subsequent corrections, placed in <raw_user_request> markers, must be quoted verbatim; do not provide only the primary's summary.
• The expected business outcome, observable behavior, and out-of-scope items.
• Current facts and evidence paths; distinguish facts, inferences, and assumptions.
• Project protocols, relevant code/documentation, dirty worktree, and permission boundaries.
• Artifacts of the current stage: plan, diff, test results, migration rehearsal, or screenshots.
• Content that is still unverified and questions that need peer challenge.

Give the peer absolute paths or in-repository paths so it can directly read the original materials. The artifact manifest must contain at least one absolute path that actually exists. Do not just paste conclusions, and do not hint at an "expected ACK" in the handoff or leak the bug you suspect.

Before sending evidence, first check the project root's AGENTS.md、CLAUDE.md, security/privacy documentation, and user constraints:

• The user has explicitly requested this time that Claude and Codex collaborate, which is regarded as permitting invocation of both ends within the scope of the current task, but tokens, cookies, credentials, and unrelated personal data must still be excluded.
• If the primary triggers it proactively and discovers requirements prohibiting external models, single-vendor requirements, confidentiality, or data residency, it must first ask the user; if authorization is not obtained, do not invoke the peer.
• The handoff should remain a "minimum dataset sufficient for a complete review," prioritizing controlled paths and not copying unrelated repository content.

Claude's read boundary is by default --cwd. If any evidence is outside the cwd, its parent directory must be explicitly passed in:

--add-dir /absolute/read-only/evidence-directory

Claude still only opens Read/Grep/Glob, so add-dir does not grant write capability. If the peer cannot read the materials in the manifest, it must BLOCKED; it must not ignore this and continue to ACK.

Codex's read-only sandbox restricts writes but allows reading absolute paths in the manifest, so there is no --add-dir parameter. On first installation or when the Codex CLI version changes, a real read probe must be performed using temporary evidence outside the cwd; if it cannot read, then BLOCKED, and do not assume the behavior is unchanged.

The wrapper will enforce checking four machine markers:

<raw_user_request>...</raw_user_request>
<artifact_manifest>...</artifact_manifest>
<validation_evidence>...</validation_evidence>
<known_gaps>...</known_gaps>

Markers can only prevent omissions; they cannot judge whether the content is honest; the primary must still ensure that they contain the original facts.

If any of the following is missing, the final ACK must not be granted:

• The user's original words;
• Acceptable product outcomes;
• Key artifact paths;
• The diff and verification evidence for the implementation stage;
• Known limitations and unfinished items.

3. Run the four gates

Gate A：Intent

Before design or coding, have the peer independently answer:

1. What does the user really want, rather than what they literally asked for?
2. Which product assumptions are unverified?
3. Will the current boundary cause "technically correct, business ineffective"?
4. Which acceptance checks must use real data or user-visible behavior?

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer auto --phase intent --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --prompt-file <intent-handoff.md>

NOT_ACK When this happens, first revise the requirements contract. Do not start implementation. If the primary disagrees with a finding, refute it with the original evidence and continue the review; do not blindly follow peer authority.

Gate B：Plan

After Intent ACK, hand the accepted requirements contract, technical research, and complete plan to the same peer session for continued review:

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer <peer> --phase plan --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --session-id <intent-session-id> \
  --prompt-file <plan-handoff.md>

The Plan must cover the normal path, failure paths, migration/rollback, privacy, security, performance, real data validation, and the test matrix. The Peer must re-check against the user's original words, not just check that the plan is internally self-consistent.

Gate C：Implementation

The Primary independently codes, tests, and records evidence. By default, the Peer does not modify files, avoiding shared worktree conflicts and ambiguous responsibility. The Claude peer only has Read/Grep/Glob; the Codex peer uses sandbox_mode=read-only + approval_policy=never. When git diff is needed, the primary generates a read-only file in advance and adds it to the artifact manifest.

After implementation is complete, open anew cold-review session, do not continue the Plan session, to reduce anchoring effect. The Handoff must include:

• the original requirements and accepted contract;
• the plan and changed files;
• complete git diff readable paths;
• test commands, pass counts, and failure output;
• real data/visual/migration evidence;
• what was not done and why.

python3 <skill-dir>/scripts/invoke_peer.py \
  --peer auto --phase implementation --cwd <project-root> \
  --task-id <stable-project-task-id> \
  --add-dir <diff-or-evidence-dir> \
  --prompt-file <implementation-handoff.md>

The Peer reports findings by P0/P1/P2/note. After the Primary fixes them, continue the review using that implementation session ID, close old findings item by item, and require a fresh scan at the same time; do not merely confirm that a patch appears to exist.

Gate D：Final

Proceed to final only when all of the following conditions are met:

• Intent and Plan have been ACKed;
• Implementation has no unresolved P0/P1;
• the Primary has run the necessary validation itself;
• user-visible results and real data have been validated;
• out-of-scope has not been treated as "the user does not need it";
• unfinished items are clearly identified, not disguised as complete.

For high-risk tasks, mid-requirement changes, or when real acceptance overturns the approach, Final uses a new cold-review session; otherwise it may continue the implementation session.

The Wrapper uses --task-id to automatically locate the state (or the integrator explicitly passes --state-file), and the machine enforces the gate order:

• intent creates the workflow.
• plan only accepts ACKed intent, and must continue the intent session.
• The first round of implementation must be a new cold-review session; fix rounds must continue that implementation session.
• final only accepts intent / plan / implementation all ACKed.
• Once any gate is ACKed it cannot be overwritten; when the user corrects the requirements, use a new state file and restart from intent.

Finally, only three verdicts are accepted:

• ACK: the contract and current-stage evidence are sufficient, with no blocking findings.
• NOT_ACK: there are issues that need fixing or requirements that need to be redefined.
• BLOCKED: evidence, permission, CLI, or a user decision is missing, making an honest judgment impossible.

4. Handling the review loop

Each round follows:

peer finding
  → primary 用证据复核
  → 接受并修复，或有证据地拒绝
  → primary 自测
  → resume 同一审查 session 逐项关闭
  → 要求 fresh scan
  → ACK / NOT_ACK / BLOCKED

Rules:

• The Peer is not a voter; conclusions must come with files, behavior, or evidence.
• The primary must not outsource testing responsibility to the peer.
• Do not modify the same working tree in parallel. When peer coding is required, a separate worktree must be used, and the primary must review before merging; by default, do not do this.
• Do not write unfinished work as ACK because of tokens, time, or a stuck CLI.
• If the peer ends at a tool request, plan, or no verdict, it is unfinished; do not manually rewrite natural-language fragments into an ACK. Fix the invocation or continue the review, then obtain a structured report again.
• When requirements are overturned by user acceptance, return to Gate A, and the old ACK automatically becomes invalid.

5. CLI invocation and continued review

Script parameters:

--peer auto|claude|codex
--phase intent|plan|implementation|final
--cwd PROJECT_ROOT
--add-dir DIR           # 可重复；Claude 读取 cwd 外证据时必传
--task-id ID            # 推荐；按项目与任务自动隔离持久 state
--state-file PATH       # 高级用法；与 --task-id 二选一
--prompt-file PATH      # 与 --prompt / stdin 三选一
--prompt TEXT
--session-id ID         # 续审
--timeout-seconds 1800
--save-raw DIR          # 仅在确需保存完整 CLI 事件时使用
--dry-run

The output is unified JSON, containing at least:

{
  "peer": "claude",
  "phase": "implementation",
  "sessionId": "...",
  "verdict": "NOT_ACK",
  "report": {
    "summary": "...",
    "findings": []
  }
}

By default, raw CLI events are not persisted, because they may contain project content. Use this only when the user explicitly needs the complete review log: --save-raw, and place the directory in a safe location.

Model selection:

• Claude uses opus alias + max effort by default, and enables safe mode, disables custom MCP, and restricts to Read/Grep/Glob; on macOS, additionally use sandbox-exec to prohibit writing to cwd/evidence directories. Override with DUAL_AGENT_CLAUDE_MODEL、DUAL_AGENT_CLAUDE_EFFORT .
• Codex uses the local configured model by default, and forces max reasoning; override with DUAL_AGENT_CODEX_MODEL、DUAL_AGENT_CODEX_REASONING .
• Do not hardcode complete model version numbers that will become outdated. When delivering, report the actual model returned by the CLI or the requested model.

6. Completion conditions

When reporting to the user, state clearly:

• Who is the primary and who is the peer.
• Which gates were passed, and the final verdict of each gate.
• What the peer found, and how the primary handled it.
• Which verifications the primary ran itself.
• What is still unfinished or requires user acceptance.

If the primary determines, based on the principle of proportionality, that a low-risk task does not trigger this Skill, it must clearly explain to the user that "dual-model review was not enabled for this task" and the reason, and must not let the user mistakenly believe that collaboration has occurred.

When installing or modifying this Skill for the first time, Final must also have these observable evidence items:

• Codex primary → Claude peer completes real fresh and resume, and obtains a structured verdict and state changes.
• Claude primary → Codex peer completes real fresh and resume, and obtains a structured verdict and state changes.
• The contents of the central repository, Codex, and Claude Code directories are consistent.
• New CLI sessions in Codex and Claude Code can each discover and trigger this Skill.

If any item is only a dry-run, mock, or "theoretically supported," it must not be written as already completed.

The Final handoff must put the absolute paths of the central source directory and the two actual installation directories all into <artifact_manifest>. When the Claude peer reviews, it must also pass --add-dirfor each installation directory outside cwd, so the peer can compare file by file itself; if any directory is unreadable, BLOCKED。

The sole criterion for "the three copies are consistent" is: after excluding __pycache__/、*.pyc、*.pyo、.DS_Store , compare the full set of relative file paths and the SHA-256 of each file; directory size, mtime, or sampling must not be used as a substitute.

Installation or update uses a rollback-capable order:

1. In the same parent directory of each target directory, copy to a unique staging directory, and perform a content comparison first.
2. If an old version exists, atomically rename it to a unique backup; then atomically rename staging to the official directory.
3. Only delete the backup after both targets have been verified as consistent.
4. If any target fails, restore the backups of all replaced targets, clean up the staging area, and redo the three-way consistency check.

Do not directly overwrite a target directory that is in use, and do not deliver in a half-successful state.

This Skill includes an atomic distribution script; dry-run it first, then execute:

python3 <skill-dir>/scripts/install_skill.py \
  --source <central-skill-dir> \
  --target <codex-skill-dir> \
  --target <claude-skill-dir> \
  --dry-run

Remove --dry-run before staging, comparison, replacement, and rollback proceed. The script excludes the aforementioned generated artifacts and finally outputs the SHA-256 of the unified content manifest.

The official structure check command for this Skill is:

uv run --with pyyaml \
  <skill-creator-dir>/scripts/quick_validate.py \
  <dual-agent-collaboration-dir>

The expected output includes Skill is valid!; it only verifies the Skill structure and does not replace real CLI and new-session discovery testing.

Do not say "both models agree, so it must be correct." You may only say: two independent lines of reasoning completed a cross-review on the full evidence, and there are currently no known blockers.