cvg-multi-session

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

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	SendMessage to the agent id
Verify identity	read_thread on the returned thread id	agent id in the Agent tool result
Inspect output	read_thread	TaskOutput or the completion notification
Wait	heartbeat automation	end the turn; the harness re-invokes the orchestrator on <task-notification>

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.

(Codex) The specialist tools to search for are create_thread, send_message_to_thread, and read_thread. For a newly created specialist, send a short identity note after read_thread succeeds: Your verified thread id is <specialist-thread-id>. Use this exact id in callbacks.

(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: <absolute path> when the specialist creates or receives an audit artifact.

• (Codex) fallback instruction if callback transport is unavailable.

On Codex, the callback destination is the orchestrator thread id, and the specialist must send its callback to the orchestrator thread with send_message_to_thread; a final answer left only in the specialist thread is not sufficient.

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: <absolute path>.

The specialist must use the verified id supplied by the orchestrator in its callback body.

(Codex) If send_message_to_thread is unavailable inside the specialist thread, the specialist must say callback transport failed in its final answer and include the exact callback text for manual relay.

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.

(Codex) Between steps 2 and 3, send the verified thread id to newly created specialists, then create or update a heartbeat automation for the current orchestrator thread; include the heartbeat id when telling the user.

(Claude Code) The harness re-invokes the orchestrator with a <task-notification> 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.

(Codex) If heartbeat automation tools are not loaded, search for automation_update first. If no heartbeat tool is available, tell the user the fallback is unavailable and end the turn after one verified handoff; do not replace the missing heartbeat with manual polling.

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 must not classify findings, choose the repair route, filter reviewer output, or turn the review into a patch list.

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 may repair implementation-owned findings only. Workers must stop and callback for plan gaps, contract gaps, systemic design gaps, reviewer clarification, or escalation. Only planners may produce plan or contract revisions.

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: Fresh Reviewer Exit

Same-reviewer pass is never the final exit condition.

The exit sequence is:

1. Fresh reviewer performs a complete first review.
2. If blockers exist, return feedback to the same planner or worker and require the role-specific feedback skill.
3. Same reviewer performs a focused re-review after the actor produces a reviewable update.
4. If same reviewer passes, start a new fresh reviewer for another complete first review.
5. Exit only when the new fresh reviewer reports no blocking findings.

A fresh reviewer is a newly spawned specialist with no prior review context. Same-reviewer re-review continues the original reviewer session so it retains its first-pass context.

For code-review final exits, the final fresh reviewer prompt must include Review mode: final-fresh-exit. Its audit artifact must show every selected auxiliary reviewer dispatched with a non-null agent_id; inline auxiliary coverage cannot satisfy the final fresh-reviewer exit condition.

A "ready with fixes" verdict (plan criteria met, only non-blocking P2 findings remain) satisfies the exit condition; carry the remaining P2 list into the completion summary instead of looping on it.

Round cap. One round is one full cycle of steps 1-4. The cap is 3 rounds unless the user set a different cap in the invocation. When the cap is reached without a clean fresh review, stop the loop and escalate to the user with all open findings, their adjudications, and the one-line instruction to authorize more rounds; an authorization raises the cap explicitly and is recorded in the ledger. Do not keep looping past the cap.

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/<loop-slug>/ledger.md — the slug is <UTC-timestamp>-<base-short-sha> (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 <N> opened | reviewer <id> | <K> blockers when feedback is sent, round <N> closed | <verdict> when the focused re-review returns, cap raised to <N> | user on authorization, and adjudication | <finding key> | <verdict> | by <role> 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 adjudicated invalid or out of scope by the role-specific feedback skill in an earlier round (same file, line, and issue) cannot re-block a later round unless new evidence appears. The orchestrator relays the prior adjudication back to the reviewer; the reviewer decides whether new evidence overrides it.

The ratchet also covers reviewer classifications: a finding an earlier review classified as non-blocking in a verdict that passed cannot be re-raised as blocking by a later reviewer without new evidence. The orchestrator relays the prior classification from the ledger alongside the new finding — a ledger lookup, not orchestrator classification.

A reviewer whose task carries Review mode: final-fresh-exit is exempt from this classification arm: an exit gate blocks on its own judgment. When it re-raises a finding a prior review classified non-blocking, it must cite the prior classification from the ledger in its verdict, and the orchestrator surfaces the unresolved conflict to the user at loop end or escalation. In single-engine loops every Phase 5 fresh reviewer carries final-fresh-exit, so there the classification arm binds only first reviews and focused re-reviews. That narrowing is intended, not an oversight: thrash protection belongs to the early rounds, exit gates keep full judgment, and the round cap bounds the cost of a re-raise. The adjudication arm above is never exempted: overturning an evidence-based adjudication requires new evidence — and showing the original evidence wrong is itself new evidence.

Audit artifact identity fields are self-reported by the reviewer. Treat them as an audit trail, not proof of dispatch. If the artifact is missing, identity fields are null, or the callback contradicts the artifact, treat the exit gate as unmet.

Specialist Prompt Checklist

Every specialist prompt must include:

• role and scope,
• 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 (Codex):

Destination orchestrator Codex thread id: <orchestrator-thread-id>

When complete or blocked, send the callback to that thread with send_message_to_thread.
If you create or receive an audit artifact, include this line in the callback:
Audit artifact: <absolute path>
If send_message_to_thread is unavailable, write "callback transport failed" and include the exact callback text in your final answer.

Callback transport block (Claude Code):

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: <absolute path>

Heartbeat Prompt Checklist (Codex only)

Heartbeat prompts should say:

• which specialist thread to check,
• what callback shape to detect,
• whether the actor completed the role-specific feedback intake,
• if still active, report one short status and continue waiting,
• do not busy-wait,
• delete or update the heartbeat when the phase is complete or stale.

When updating a heartbeat for a new phase, replace the old instructions. Do not wrap or nest previous heartbeat payloads inside the new heartbeat prompt.

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,

• heartbeat cleanup (Codex),

• whether the fresh-reviewer exit condition was met.