cvg-multi-session git:20260712.c5052edA

Immutable. This exact content is served forever at /api/v1/blob/63cf9559ff0376b8.

---
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.

(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.

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.

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
`<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.

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

## 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 the fresh-reviewer exit condition was met.