cvg-multi-session git:20260913.efcb5b0A

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

---
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` 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 `<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 Codex, search for `list_projects`, `create_thread`,
`send_message_to_thread`, `wait_threads`, and `read_thread`. Use the native
Desktop task lifecycle for both creation and continuation; do not start a
standalone `codex app-server` process or any other second writer.

For repository work, resolve the saved project with `list_projects`. Use a
native project worktree for a git repository and a local project only when the
user explicitly requested the saved checkout. Use `projectless` only for work
without a repository. Omit model and reasoning overrides unless the user
explicitly selected them.

`create_thread` may return either a ready `threadId` or a temporary
`clientThreadId` while worktree setup finishes. Never pass a `clientThreadId`
to thread tools. Give each specialist a unique title and use `list_threads` to
resolve the ready task before verification.

Full Access is a prerequisite for a Codex implementation loop. If a native
specialist unexpectedly requests approval or reports a restricted effective
profile, stop with a permission blocker. Do not switch transports or replace
the specialist task. The release smoke test validates native project-worktree
creation and same-task continuation against the current Codex runtime.

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) After `read_thread` verifies a newly created task, send a short identity
note with `send_message_to_thread`:
`Your verified thread id is <specialist-thread-id>. Use this exact id in callbacks.`
The task id returned by Desktop is authoritative; the setup client id, worktree
path, process id, and any model-generated id are not specialist identities.

### 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 task id. The specialist
must send its callback to that task with `send_message_to_thread`. It must also
make the same callback its final answer so `wait_threads` and `read_thread` can
recover it if cross-task delivery is unavailable or delayed.

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 task,
the specialist must say `callback transport failed` before the exact callback
text in its final answer. The orchestrator may recover that final text with
`wait_threads` or `read_thread` but records the transport failure.

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) After a spawn or continuation, use one bounded `wait_threads` call. If
the task completes, validate the callback immediately. If it remains active at
the timeout, create or update one heartbeat automation for the current
orchestrator task, include its id when telling the user, and end the turn. A
heartbeat turn performs one compact `wait_threads` snapshot or one
`read_thread` check, then either advances the loop or ends again. Do not poll in
a shell, start a background App Server, or create a replacement task.

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):

```text
Destination orchestrator Codex task id: <orchestrator-thread-id>

When complete or blocked, send the exact callback text below to that task with send_message_to_thread, then use the same callback as your final answer.
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" before the exact callback text in your final answer.
```

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