--- name: cvg-multi-session description: Orchestrate real specialist sessions as one monitored multi-agent workflow. Use when the user asks to coordinate or supervise multiple agent sessions, planning or implementation loops, or worker/reviewer handoffs, on Codex threads or Claude Code background agents. argument-hint: "[goal, plan path, worktree, or workflow description]" --- # Multi-Session Workflow Use this skill when the current session should act as an **orchestrator** over other real specialist sessions. The workflow is repo-independent. Specialist prompts should carry only the coordination data the specialist cannot infer from the selected role skill and source artifact. Do not paste broad repo rules, likely-file lists, old phase state, or role-skill procedures unless they are task-specific authority. ## Non-Negotiable Protocol Gates Apply these gates before any planner, worker, reviewer, QA runner, or quality reviewer is launched. ### Gate 0: Transport Binding Tool contracts and existing user authorization govern task creation, delegation and external actions; a skill invocation does not grant additional permissions. Bind the specialist operations to the current platform before applying any other gate: | Operation | Codex | Claude Code | |---|---|---| | Spawn specialist | `create_thread` | `Agent` tool with `run_in_background: true` | | Continue specialist | `send_message_to_thread` on the same thread id | `SendMessage` to the agent id | | Verify identity | `read_thread` on the returned thread id | agent id in the `Agent` tool result | | Inspect output | `wait_threads` and `read_thread` | `TaskOutput` or the completion notification | | Wait | one bounded `wait_threads` call, then heartbeat handoff if still active | end the turn; the harness re-invokes the orchestrator on `` | The authoritative specialist identity is always the id returned by the platform tool — never an id the specialist writes in prose. Do not accept placeholder specialist identity in callback templates. On Claude Code, background specialists can spawn their own subagents (auxiliary reviewers, researchers), and a completed specialist is resumed from its persisted transcript when continued with `SendMessage`. Both loop requirements are natively supported; do not flatten a specialist's internal delegation into the orchestrator. If the transport tools are not available after searching for them, report a tool-layer blocker. Do not fall back to inline simulation of a specialist. ### Gate 1: Real Specialist Session Specialists must run as real, individually addressable platform sessions: Codex threads or Claude Code background agents. - Spawn a new specialist with the spawn operation unless the user explicitly named an existing specialist session. - Continue an existing specialist with the continue operation. - Verify every specialist id immediately after creation or selection with the Gate 0 verify operation. - Do not use local shell jobs, detached processes, or inline role-play in the orchestrator turn as substitutes for a real specialist session. - Do not treat a process id, shell job id, or model-generated id as a specialist id. - If the id returned by the spawn operation cannot be verified, stop the workflow and retry with the platform specialist tools or report a tool-layer blocker. - If the platform specialist tools are not loaded, search for them first. If they still cannot be loaded, report a tool-layer blocker. (Claude Code) The specialist tools to search for are `Agent`, `SendMessage`, and `TaskOutput`. The `Agent` tool result already carries the authoritative agent id; no separate read or identity note is needed. ### Gate 2: Orchestrator Callback Transport Every specialist prompt must include: - the callback destination, - exact callback template, - instruction to include `Audit artifact: ` when the specialist creates or receives an audit artifact. On Claude Code, the specialist's final message is the callback: the harness delivers it to the orchestrator as the completion notification, so the specialist must format that final message per the callback template. If the specialist creates or receives an audit artifact, the callback must include `Audit artifact: `. The specialist must use the verified id supplied by the orchestrator in its callback body. The orchestrator treats the phase as pending until the callback is visible. ### Gate 3: Waiting Handoff Waiting is handled by the platform, not by manual polling. Handoff sequence: 1. Send the specialist work with the spawn or continue operation. 2. Verify the specialist id per Gate 1. 3. Tell the user the specialist id. 4. End the active turn and let the platform deliver the callback. (Claude Code) The harness re-invokes the orchestrator with a `` when the specialist completes; no heartbeat exists or is needed. Do not emulate waiting with `sleep`, repeated reads, shell loops, timers, or repeated status checks in the same assistant turn — on either platform. This gate forbids in-turn waiting, not background watchers: a background watcher command that exits when its condition holds (the hybrid loops' codex-completion watcher) is the platform's single-completion shape and ends the turn properly — arming one is not a violation of this gate. A wake-up turn (heartbeat on Codex, task notification on Claude Code) may do one status check. If the specialist is still active, report one short status and stop. Do not sleep and check again. Continue immediately only when an explicit callback is already present or the specialist is already shown as completed. ### Gate 4: Role-Specific Review Feedback Reviewer feedback returns to the same planner or worker session that produced the reviewed artifact, via the continue operation. The orchestrator adjudicates scope and severity against the original user outcome, authorized changes and concrete evidence before routing repairs. Preserve each original finding and the reason for accepting, rejecting or reclassifying it in the existing loop ledger. Prefer removing a failure's cause when that preserves required behavior; do not turn suggestions into new scope. The worker/planner chooses the implementation within its role. Never report the orchestrator's judgment as an independent reviewer's signature. Plan-review blockers return to the planner with the `cvg-plan-review-feedback` skill. The prompt must contain the exact reviewer blocker findings under a `Plan Review Feedback Input` section. Code-review blockers return to the worker with the `cvg-code-review-feedback` skill. The prompt must contain the exact reviewer blocker findings under a `Code Review Feedback Input` section. Role boundaries still apply: workers repair implementation-owned findings; planners revise plans/contracts. Pause dependent work for material unresolved behavior decisions, while independent authorized work continues. Source-backed technical omissions can be resolved by the planner/orchestrator. Ask the user only for a missing product choice, expanded scope/authorization or new risk acceptance; reuse existing authorization for the same target and operation. The orchestrator continues only after the actor callback reports a role-valid result: implementation repair from a worker, plan or contract revision from a planner, or a blocker that needs planner, reviewer, user, or escalation handling. ### Gate 5: Independent Review and Bounded Exit Start with one independent complete review. If it passes, proceed to required acceptance checks. If blockers remain, adjudicate them, route a repair batch to the same actor, and have the same reviewer verify the findings, repair diff and newly affected risks. A focused pass can satisfy the review exit condition. Start another full independent review only for a material design/contract change, a substantially expanded risk surface, new evidence, or an explicit user requirement. A mechanical plan correction does not restart full review. Honor user-selected hybrid/dual signatures; inline checks cannot impersonate them. A fresh reviewer is a newly spawned specialist without prior review context. Focused re-review continues the original reviewer. Optional auxiliary checks are risk-selected by the role skill; missing required independent coverage must be reported as an incomplete review, not repaired with new product code. Exit when the original outcome and applicable constraints are met, required review and acceptance evidence are complete, and no blocking findings remain. A "ready with fixes" verdict carries non-blocking P2 notes to the completion summary; it does not require another round or permission to end the loop. **Round cap.** One round is one substantive repair batch plus its re-review, including repeated repairs by the same reviewer. The default cap is 3 unless the user set another limit. The initial review and status checks are not repair rounds. Log each round before dispatching its repair; changing reviewer, model, role or plan artifact does not reset the count. At the cap, complete the pending re-review, then exit if clean or report unfinished work with the exact remaining blockers, evidence and smallest next step. Further repair rounds require an explicit cap increase recorded in the ledger; reaching the cap is not success. **Loop ledger.** In-context round counting drifts over long loops, so the cap and the ratchet are enforced from a file, not from memory. When the loop starts, create `/tmp/convergo//ledger.md` — the slug is `-` (timestamp alone when there is no repo), so every loop gets a fresh directory. Never append to or read another loop's ledger: a stale ledger's non-blocking adjudications would suppress a new loop's legitimate blockers. Append one line per event: `round opened | reviewer | blockers` when feedback is sent, `round closed | ` when the focused re-review returns, `cap raised to | user` on authorization, and `adjudication | | | by ` for every validity or severity adjudication. The cap check and the adjudication ratchet read the ledger; the completion summary quotes it. **Adjudication ratchet.** A finding already adjudicated invalid, out of scope or non-blocking cannot re-block without new evidence. Match the underlying failure and requirement, not merely a line number or reworded title. This applies to all reviewers, including `Review mode: final-fresh-exit`; a new reviewer alone is not new evidence. The orchestrator supplies the relevant prior adjudication when a duplicate arises. A changed call path, failing test or proof that the old evidence was wrong can reopen it. Record the evidence and decision; never suppress a real defect merely to satisfy the cap. Audit artifact identity fields are self-reported by the reviewer. Treat them as an audit trail, not proof of dispatch. A missing required artifact, a callback that contradicts it, or missing verified identity for a reviewer required to sign independently leaves the exit gate unmet. An optional auxiliary recorded as inline or skipped may have a null identity; that record does not substitute for a required independent signature and does not itself block exit. ## Specialist Prompt Checklist Every specialist prompt must include: - role and scope, - original user outcome, explicit non-goals, authorized changes and applicable product/safety constraints, stated briefly or linked from the source artifact, - callback destination per Gate 2, - worktree or repo path, - base/head refs when relevant, - dirty-state warning and unrelated files when present, - one source artifact or exact user input: plan path, requirements path, review callback, or implementation goal, - required role skill, - task-specific external side-effect boundary, especially whether push, deploy, remote smoke checks, secrets, or external environment/data changes are allowed, - audit artifact callback line when the specialist creates or receives one, - exact callback transport block, - exact callback template. Do not include: - execution rules already owned by the required role skill, - duplicated authority lists when the plan or source artifact links them, - likely files or exhaustive surface checklists copied from the orchestrator, - old heartbeat payloads or previous phase instructions, - reviewer concerns unless this is a role-specific feedback prompt. Callback transport block (Claude Code): ```text You are a background specialist agent. Your final message is your callback to the orchestrator: format it exactly per the callback template below. Do not end your turn before the work is complete or blocked: an early stop without a formatted callback orphans the loop until someone nudges you. If you create or receive an audit artifact, include this line in the callback: Audit artifact: ``` ## Completion Summary When the workflow completes, summarize: - base and final refs or final plan path, - specialist ids verified per Gate 1, - callback transport status, - audit artifact paths received from specialists, - review loop results, - role-specific feedback results, - verification gates, - remaining known gaps, - whether independent review and required acceptance were completed.