Collaborative Loop

Collaborative Loop: Sequential Drive / Validate / Act

Overview

Sequential pair-programming loop between Claude and Codex CLI. Claude PRODUCES an analysis with numbered findings, Codex VALIDATES each finding individually (CONFIRM/REJECT), Claude RE-EVALUATES the validation decisions, and only findings where both models agree proceed to implementation. After fixes, Codex reviews the changes and the loop repeats until clean.

Core principle: Claude never acts on its own unvalidated output. Every finding passes through bilateral consensus before implementation.

Trigger Phrases

"collaborate with codex", "have codex review my changes", "drive and review loop", "iterative improvement", "produce-validate-act", "collaborative loop"

Invocation

collaborative-loop [--max-rounds N] [--type code|plan|architecture|design] [target files...]

| Argument | Default | Description | |----------|---------|-------------| | --max-rounds | 3 | Maximum fix-review iteration rounds | | --type | (auto-detected) | Artifact type override | | target files | (branch diff) | Specific files to analyze |

Step 1: Preflight

Read ${CLAUDE_PLUGIN_ROOT}/skills/shared/prerequisites.md and execute the preflight check.

Invoke /codex:setup via the Skill tool. Two failure modes:

1. Command not recognized (plugin not installed) — print install instructions from prerequisites and ABORT. Do not continue to Step 2.
2. Setup reports failure (CLI missing, auth expired) — report the specific error from /codex:setup and ABORT.

On success, proceed to Step 2.

Liveness Check

After /codex:setup succeeds, verify the Codex broker can actually complete work (not just accept connections). /codex:setup --json already reports whether the CLI is installed and auth is valid; the liveness step dispatches a trivial task to confirm end-to-end dispatch works.

Invoke /codex:rescue --fresh via the Skill tool with a minimal prompt such as Reply with OK. Cap the wait at 90 seconds for this probe specifically — the 15-min response-generation threshold does not apply to a liveness probe (if it can't echo "OK" in 90s it's dead). If the task dispatches but hangs past 90 seconds or returns empty output, the runtime's connection is likely dead (WebSocket TTL expired — see "WebSocket Connection Limit" in prerequisites.md). If the Skill tool itself errors (e.g., permission denial, disable-model-invocation), that is NOT a dead runtime — see the "Skill-gate Rejection" and "Skill-tool Fallback" paths in prerequisites.md. Dead-runtime recovery:

1. Ask the user to close all Codex instances and restart the Codex app/CLI
2. Re-run /codex:setup — the companion will establish a fresh connection
3. Repeat the liveness check

Only proceed to Step 2 after the liveness check passes.

Runtime Failure Policy

The collaborative loop requires BOTH collaborators. If Codex fails at any point during the workflow (script error, empty output):

1. Do NOT fall back to a Claude subagent as reviewer -- self-review defeats the purpose
2. Attempt Direct CLI Fallback (see prerequisites.md) before stopping — construct a self-contained prompt with all context inlined and run via codex exec
3. Only STOP the loop if both companion and CLI fallback fail
4. Report the failure clearly with the exact error and suggest remediation (re-run /codex:setup, check auth, check OpenAI API status)

Hang Detection

Codex tasks can legitimately run for 30+ minutes on complex analyses. Do NOT use a hard timeout. Use /codex:status (Skill tool) to assess health — never PID-based checks on Windows (see "Task Health Verification" in ${CLAUDE_PLUGIN_ROOT}/skills/shared/prerequisites.md).

Tier 1 — Task health check (within 60 seconds of dispatch):

After dispatching a Codex task, verify it is making progress within 60 seconds using /codex:status (Skill tool). If status reports the task as failed or the runtime pipe is gone, follow the Auto-Retry Protocol in prerequisites.md.

Tier 2 — Starting-stuck detection (5-minute threshold):

If the task phase stays starting for >5 minutes without advancing to running or showing any log entries, run Diagnostic Escalation from prerequisites.md. This catches dead connections (WebSocket limit, 403 errors) quickly.

Tier 3 — Response-generation awareness (critical):

After tool calls go quiet, Codex is composing its response. Max wait: 15 minutes of silence (reduced from prior guidance — session data shows silence >10 min is almost always a dead task, not slow generation). After 15 minutes, escalate to Direct CLI Fallback. See "Response-Generation Awareness" in prerequisites.md.

When a genuine failure is detected:

1. Cancel the stalled task via /codex:cancel or the companion
2. Run Diagnostic Escalation from prerequisites.md — check for connection errors before blindly retrying
3. If diagnostics reveal a connection issue → report to user with specific remediation, do NOT retry
4. If no connection issue → re-run /codex:setup and retry (max 2 companion retries)
5. If companion retries fail → escalate to Direct CLI Fallback (see prerequisites.md). Construct a self-contained prompt with all context inlined and run via codex exec
6. If both companion and CLI fail, STOP the loop and report diagnostics:

`` Codex failed via both companion (N retries) and direct CLI. Diagnostics: Remediation: Check OpenAI API status, verify auth (codex auth login), check network. ``

Step 2: Detect Context

Read ${CLAUDE_PLUGIN_ROOT}/skills/shared/artifact-detection.md and follow the detection procedure.

Parse Arguments

• --max-rounds N (default: 3)
• --type code|plan|architecture|design (default: auto-detect from files)
• Remaining positional arguments are target files

Resolve Target Files

If no target files provided:

1. Detect base branch: check for main, then master, then git remote show origin default
2. Run git diff ...HEAD --name-only to find changed files
3. If zero files in diff: ask the user what to work on (this is the ONLY case where clarification is allowed)

Classify Artifact Type

Follow the rules in artifact-detection.md:

| Signal | Type | |--------|------| | Source code extensions (.ts, .py, .js, .go, .rs, .cs, .java, etc.) | code | | *-plan*, *-tasks*, *implementation-plan* | plan | | *-architecture*, *-spec* | architecture | | Other .md in docs/ or plans/ | design | | Mixed | default to code |

Initialize State

ROUND = 0
MAX_ROUNDS = 
ARTIFACT_TYPE = 
TARGET_FILES = 
BASE_BRANCH = 

Step 3: Claude PRODUCES Analysis

Claude analyzes target files and produces numbered findings with severity. No implementation yet -- analysis only. Do not modify any files.

Skill Discovery (Code Artifacts)

For code artifacts, search available skills for the best match:

• Search for: coder, code-review, feature-dev
• Priority: project-specific skills first (e.g., unity-coder, python-coder) then general-purpose
• If a matching skill is found, invoke it for analysis guidance
• If no skill found, perform direct structured analysis

Non-Code Artifacts

For plan, architecture, and design artifacts, perform structured analysis against focus areas from ${CLAUDE_PLUGIN_ROOT}/skills/shared/review-domains.md. Read the file and use the focus areas for the detected artifact type.

Output Format

Produce numbered findings, globally ordered by severity:

[1] [critical] [security] src/auth/login.ts:42 -- SQL injection via unsanitized input
    Suggested fix: Use parameterized query instead of string concatenation

[2] [high] [correctness] src/api/handler.ts:87 -- Missing null check on response.data
    Suggested fix: Add guard clause before accessing .data property

[3] [medium] [performance] lib/cache.ts:15 -- Cache has no TTL, grows unbounded
    Suggested fix: Add maxAge option to cache constructor

Every finding must:

• Have a sequential number [N]
• Include severity: critical, high, medium, or minor
• Include category (e.g., security, correctness, performance, test-coverage)
• Reference specific file:line
• Provide a concrete suggested fix

Hold findings in conversation context. Do not write intermediate files.

Step 4: Codex VALIDATES

Send Claude's numbered findings to Codex for per-finding validation. Codex independently evaluates each finding and returns CONFIRM or REJECT with evidence.

Pre-dispatch: fresh setup. Before dispatching, re-invoke /codex:setup to verify the runtime is alive. Read the "Fresh Setup Before Dispatch" section in ${CLAUDE_PLUGIN_ROOT}/skills/shared/prerequisites.md. Do NOT reuse the preflight result from Step 1 — the runtime endpoint may have changed since preflight.

IMPORTANT: Use /codex:rescue --fresh via the Skill tool -- NOT /codex:adversarial-review. Adversarial review produces its own independent findings and does not map back per-finding. Only /codex:rescue with a custom prompt supports per-finding CONFIRM/REJECT. Always pass --fresh to prevent the codex plugin from prompting the user about resuming a previous thread.

Skill-gate rejection is NOT a runtime failure. If the user denies the /codex:rescue Skill invocation at the permission prompt, no job was dispatched — do NOT run the Auto-Retry Protocol from prerequisites.md. Instead:

1. Report to the user that Codex validation is required for this loop to proceed with bilateral consensus
2. Offer Direct CLI Fallback (codex exec) as an alternative that doesn't route through the Skill gate
3. Wait for the user's explicit choice — do not auto-dispatch via CLI, since denial at the Skill gate signals the user wants to decide

User denial ≠ runtime failure. Retrying the Skill tool without user input would be a permission bypass attempt.

Monitor the task using the Hang Detection procedure from Step 1. Verify task health within 60 seconds, watch for starting-stuck at 5 minutes. Remember: after tool calls go quiet, Codex is likely generating its response (10-30 minutes) — do NOT cancel. Use the Monitor tool to stream events from the task rather than looped status polling; only re-check status on Monitor timeout, an unexpected event, or immediately before retrieving results.

Compose the Validation Prompt

Invoke the gpt-5-4-prompting skill patterns when composing the prompt. Structure the prompt with XML-tagged blocks:

`` block:

Validate each of Claude's findings independently. For each finding, determine
whether it is a genuine issue (CONFIRM) or a false positive (REJECT). You must
provide evidence from the actual code or specification for each decision.
Also report any issues you find that Claude missed entirely.

Include in the prompt:

• Claude's numbered findings (the full list from Step 3)
• Focus areas from ${CLAUDE_PLUGIN_ROOT}/skills/shared/review-domains.md for the detected artifact type
• ${CLAUDE_PLUGIN_ROOT}/skills/shared/validation-format.md as ``
• For code artifacts: include target file paths so Codex can read them directly
• For non-code artifacts: include the artifact content inline

Expected Response

Codex returns per validation-format.md:

## Confirmed Findings
- [1] CONFIRM -- evidence from code/spec
- [3] CONFIRM -- evidence from code/spec

## Refined Findings
- [4] REFINE -- agree with issue but severity should be medium, not high: 

## Rejected Findings
- [2] REJECT -- evidence why this is a false positive

## New Findings (Missed by Driver)
- [high] [error-handling] src/api/handler.ts:91 -- Unhandled promise rejection
  Suggested fix: Add try/catch wrapper

## Status
VALIDATED | PARTIALLY_VALIDATED | REJECTED

## Summary
Brief assessment (confirmed X, refined Y, rejected Z, found W new)

Step 4.5: Claude RE-EVALUATES Codex Validation

Claude reviews Codex's CONFIRM/REJECT decisions against the original analysis. This is the bilateral consensus gate.

Decision Matrix

| Codex Says | Claude Agrees? | Action | |------------|---------------|--------| | CONFIRMED | Yes | Proceed -- act on this finding in Step 5 | | CONFIRMED | No | Flag for user -- present disagreement, ask for mediation | | REFINED | Yes | Proceed -- act with Codex's adjusted severity/fix | | REFINED | No | Flag for user -- present disagreement on the refinement | | REJECTED | Yes | Drop -- both agree this is not a real issue | | REJECTED | No | Flag for user -- present disagreement, ask for mediation |

Process

1. For each CONFIRMED finding: Claude reviews whether the confirmation is sound. If Claude still agrees the finding is real, mark as proceed. If Claude now thinks Codex's confirmation was based on a misunderstanding, mark as flag.

1. For each REFINED finding: Claude reviews the adjusted severity/fix. If Claude agrees with the refinement, mark as proceed (using Codex's adjusted severity/fix). If Claude disagrees with the refinement, mark as flag.

1. For each REJECTED finding: Claude reviews whether the rejection is justified. If Claude agrees the finding was a false positive, mark as drop. If Claude still believes the finding is valid despite Codex's rejection, mark as flag.

1. For new findings from Codex: Claude evaluates each. If Claude agrees it is a real issue, mark as proceed. If Claude disagrees, mark as flag.

1. Flagged disagreements: Present ALL flagged items to the user with both models' reasoning. Wait for user mediation before continuing. The user may:

• Confirm the finding (add to proceed list)
• Reject the finding (add to drop list)
• Modify the finding and confirm

1. Only findings marked proceed (including user-mediated ones) advance to Step 5.

Never silently resolve disagreements. The entire point of bilateral consensus is that ambiguous cases get human judgment.

Step 5: Claude ACTS on Validated Findings

Filter to confirmed-and-agreed findings only. Claude implements the fixes.

Implementation Strategy

• Apply fixes in order of severity (critical first)
• For each fix, make the minimum change that addresses the finding
• Use subagents (Agent tool with run_in_background: true) when parallelism adds value -- specifically when fixes are independent and span different modules/files
• When fixes are interdependent or touch the same file, apply sequentially

Rejected Findings

Log dropped findings for the summary but do not act on them:

Dropped (both models agreed not real):
- [2] [high] [correctness] src/api/handler.ts:87 -- reason for drop

Step 6: Codex REVIEWS Changes

After Claude implements fixes, Codex reviews the resulting changes.

Pre-dispatch: fresh setup. Before dispatching, re-invoke /codex:setup to verify the runtime is alive. Same rationale as Step 4 — the runtime endpoint may have changed during Claude's implementation work in Step 5.

For Code Artifacts

Invoke /codex:review --base via the Skill tool, where `` is the commit or ref before Step 5's changes. This uses the codex plugin's native review capability.

For Non-Code Artifacts

Invoke /codex:rescue --fresh via the Skill tool with a review prompt. Compose the prompt using gpt-5-4-prompting patterns:

• ``: Review the changes made to these artifacts. Evaluate whether the fixes correctly address the validated findings without introducing new issues.
• Include the modified artifact content
• Include ${CLAUDE_PLUGIN_ROOT}/skills/shared/verdict-format.md as ``

Skill-gate Rejection in Review Phase

The same rule as Step 4 applies to Step 6: if the user denies /codex:review or /codex:rescue at the permission prompt, no job was dispatched — do NOT run the Auto-Retry Protocol. Instead:

1. Report that Codex review of the applied fixes is required to close the round
2. Offer Direct CLI Fallback (codex exec with the diff and verdict contract inlined) as an a

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DmitriyYukhanov
• Source: DmitriyYukhanov/claude-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.