Control Session Orchestrator

Control Session Orchestrator

Use the current session as the control plane for project work that is too broad, risky, or stateful for one conversation. The control session owns intent, decomposition, routing, status, verification, and consolidation. Worker sessions own scoped execution. Worker subagents are local implementation/research/audit helpers inside each worker session.

Mental model

User
  -> Control session (strategy, dispatch, tracking, integration)
       -> Worker project session A (persistent branch/workstream)
            -> Subagents for research, implementation, review, tests
       -> Worker project session B (persistent branch/workstream)
            -> Subagents for local fan-out
       -> Verifier/reviewer session (optional independent gate)

This is similar to dynamic workflows, but the orchestration is human-readable and session-native instead of a runtime script. Use it when persistence, branches, PRs, human steering, or cross-session continuity matter more than fully automated fan-out.

A code runtime gets reliability for free (validated results, barriers, budgets, dedup, resume). A prompt-driven control plane only gets it if you make state machine-checkable. Two contracts do that without a runtime: a required worker result block and a durable control-state manifest (see Machine-checkable contracts). Everything else in this skill keys off those two artifacts — without them, "is this worker done and passing?" is a guess, not a field read.

Supported control apps

This skill is app-agnostic. First discover which orchestration tools are available in the current session, then adapt the same control workflow to that surface.

Do not assume the GitHub Copilot or Codex tool names. Use the tools exposed in the current environment, and say which control surface is active before dispatching workers.

When to use

Use this skill for:

• Codebase-wide audits, migrations, or parity checks
• Parallel investigation across modules, services, features, or PRs
• Work that benefits from independent implementer and verifier sessions
• Large features where design, implementation, testing, and review should be split
• Project-control prompts like "coordinate agents", "spin up sessions", "run a workflow",

"make workers handle this", "monitor the other sessions", or "act as control"

• Situations where worker sessions may themselves use subagents for local research, coding, or review

Do not use it for a simple one-file fix, a quick answer, or a task where a single local subagent is enough. Orchestration has overhead; spend it only when coordination reduces risk or increases throughput.

Machine-checkable contracts

These are the session-native analog of a runtime's typed results and durable run state. They stay human-readable, but they are required, not advisory — the control session parses them instead of re-reading prose.

Worker result block

Every worker MUST end its report with a fenced `json block tagged control-result. The control session reads this block (never the surrounding prose) to update state, dedup, and decide routing.

```json control-result { "worker_id": "auth-api", "wave_id": "w1", "unit_key": "service/auth", "scope": "src/auth/** — refresh-token rotation", "status": "complete", "files_changed": ["src/auth/rotate.ts"], "verification": { "command": "pnpm test auth", "result": "pass", "evidence": "42 passed" }, "subagents_used": "2 — one research, one test author", "risks": ["rotation interacts with logout; covered by test"], "next_step": "ready for review session", "report_ref": "thread/PR/path to the full report" }

The block must be **strict JSON** (no comments/trailing commas) so it parses. `status` is one of
`complete | blocked | needs-decision | failed`; `verification.result` is one of `pass | fail | not-run`.

### Control-state manifest

One durable artifact that **is** the source of truth for the mission — a pinned control thread, a
tracking-issue body, a canvas node, or a committed `control/state.json`. Re-read and update it every
turn; keep the conversation for decisions, not state. One row per **unit** (unit-keyed, so the same
unit is never dispatched twice — this is the dedup ledger).

{ "mission": "MCP tool parity audit", "non_goals": ["no behavior changes"], "success_criteria": ["every tool present in server, HTTP, SDK, docs or flagged"], "budget": { "max_concurrent_workers": 5, "max_total_workers": 25, "spawned": 0, "in_flight": 0 }, "convergence": { "rule": "single-pass", "k_empty": 2, "empty_streak": 0, "target": null, "current": 0 }, "workers": [ { "unit_key": "surface/http", "worker_id": "http-audit", "session_ref": "thread-or-session id/link", "scope": "HTTP API surface", "branch_or_pr": "—", "status": "pending", "wave_id": "w1", "last_update": "ISO-8601", "evidence_ref": "report_ref from the result block", "verification": "not-run", "blocker": null } ], "decisions": [], "open_followups": [] }

Rules:

- **Worker status** (what a worker self-reports in its result block): `complete | blocked |
  needs-decision | failed`.
- **Manifest unit status** (the superset the control session maintains): `pending | dispatched |
  needs-decision | blocked | stalled | complete | failed | dropped`. Worker-reported values are a
  subset of these, so setting a unit's status from a worker block (Step 5) is always valid.
- **Terminal** states — a unit is closed — are `complete | failed | dropped`. Everything else is
  non-terminal and must be resolved, or explicitly converted to `dropped` with a reason, before the
  mission closes (Step 8).
- `budget.in_flight` is the number of rows currently `dispatched`. Increment `spawned` and `in_flight`
  on dispatch; decrement `in_flight` when a unit leaves `dispatched`; recompute it from the rows on
  rehydrate.
- `convergence.rule` is one of `single-pass | loop-until-dry | loop-until-budget |
  accumulate-to-target`. `k_empty`/`empty_streak` are used only by `loop-until-dry`; `target`/`current`
  only by `accumulate-to-target` (`target` = the count or coverage goal, `current` = progress so far).
- dropped/failed units MUST carry a reason in `open_followups`.

This manifest is what a fresh control session rehydrates from (Step 0).

## Control workflow

### 0. Rehydrate (resume an in-flight mission)

On session start, look for an existing control-state manifest for this mission. If one exists:

- Load it; treat it as the source of truth.
- Re-attach to workers by `session_ref` and reconcile each worker's *real* status (read the thread/PR)
  before any new dispatch.
- Recompute `budget.in_flight` from the rows still marked `dispatched`.
- Do NOT re-dispatch a unit whose status is `dispatched` or `complete` — route a follow-up instead.

If no manifest exists, this is a new mission — create one during Step 1.

### 1. Frame the mission

Before spawning anything, capture (and write into the manifest):

- Objective and non-goals
- Repositories, branches, PRs, or issues in scope
- File or subsystem boundaries for each workstream
- Success criteria and verification gates
- Merge/integration expectations
- Any "do not touch" constraints

Also set explicit limits up front (manifest `budget` and `convergence`):

- `max_concurrent_workers` (default ~4–6) — never more in flight at once
- `max_total_workers` — a lifetime backstop for the whole mission (e.g. 25)
- optional token / cost / time ceiling
- the convergence rule: `single-pass` for bounded missions; `loop-until-dry`, `loop-until-budget`,
  or `accumulate-to-target` for open-ended audits/migrations/parity sweeps

If any boundary is ambiguous and could cause conflicting edits, ask before dispatch.

### 2. Detect the control surface

Before dispatch, identify the available app tools:

- Codex app: thread/session tools such as list, create/read, send-message, rename, pin/archive, plus
  optional local subagent tools.
- GitHub Copilot app: session or workspace tools exposed by the app connector, plus any available
  GitHub issue/PR/branch controls.
- Generic agent app: any combination of session, task, subagent, branch, issue, PR, or automation
  tools.

If no persistent-session tools are available, downgrade to a local multi-agent plan and explain the
limitation. Do not invent a backend.

### 3. Choose the topology

Pick the smallest useful topology:

- **One worker**: isolated implementation or bug fix that should live in its own project session
- **Parallel workers**: independent modules, packages, endpoints, tests, or docs
- **Research then implementation**: exploratory sessions report findings before coding starts
- **Implementer + verifier**: one session changes code, another reviews or verifies independently
- **Control-only**: no workers yet; just inspect state, list sessions, or plan the dispatch

Prefer separate sessions when workers may edit overlapping history, need different branches, or need
long-running context. Prefer local subagents inside one session when the task is exploratory and does
not need persistent branch state.

### 4. Dispatch workers with complete prompts

Respect the budget: **never dispatch while `in_flight >= max_concurrent_workers`** — queue the unit
(`status: pending`) and log it. On reaching `max_total_workers` or a token/cost ceiling, STOP
dispatching and surface a *Decision needed* rather than spawning more. Dispatch is an **atomic
manifest update**: set the unit's row to `status: dispatched` (with `session_ref`, `worker_id`,
`wave_id`, `last_update`) and increment `spawned` and `in_flight` together; if the dispatch fails to
start, leave the row `pending` and advance neither counter. Decrement `in_flight` when a unit leaves
`dispatched` (it reaches a terminal state, or returns to `needs-decision`/`blocked`/`stalled`) so
queued units can start. This keeps `in_flight` equal to the count of `dispatched` rows that Step 0
recomputes.

Each worker prompt should be self-contained. Include:

- The mission and exact scope (and its `unit_key`)
- Files, subsystems, issue/PR links, and branch expectations
- What the worker may and may not change
- Verification commands or acceptance criteria
- Whether it may create commits, PRs, or only report back
- The required result block

Worker prompt template:

You are worker <name> for <project>.

Mission: <specific outcome> unit_key / wave_id: <key> / <wave> Scope: <files/subsystems/issue/PR> Do not touch: <boundaries> Approach: <expected plan or constraints> Verification: <commands/checks/evidence>

You MAY use your own subagents for local research, implementation, and review, but you remain accountable for this scope and the final report. Do NOT create or steer further persistent project sessions — if the work needs another full workstream, say so in next_step.

End your report with a fenced ```json control-result block (see the contract). Populate every field; record subagents you used in subagents_used. The control session reads only that block.

When using Codex app controls, prefer to rename and pin important worker/control threads so the
session graph stays legible. When using GitHub Copilot app controls, use the corresponding session or
workspace labels if exposed.

### 5. Track state centrally

The control-state manifest is the single source of truth — update it every turn, not the
conversation. From each worker's result block, set the unit's `status`, `evidence_ref` (= the block's
`report_ref`), `verification` (= the block's `verification.result`), and — when `status` is `blocked`
or `needs-decision` — `blocker` (the block's blocking reason; otherwise `null`). The control session
records the remaining fields itself: stamp `last_update` from its own clock, and set `branch_or_pr`
from the worker's session/PR metadata when known (workers don't self-report it in the block). Keep the
control session's context focused on summaries and decisions, not full transcripts; the full report
lives at `report_ref`.

Track at least, per unit: `unit_key`, `worker_id`, `session_ref`, scope, status, branch/PR, last
update, blocker, and verification state — matching the row schema above. Canvas nodes or a SQL/todo
table are good backends for the manifest when the app exposes them.

### 6. Route follow-ups (result-gate)

When a worker reports, first run the **result-gate**:

- Parse the `control-result` block. If a required field is missing or malformed, or the status is
  inconsistent with evidence (e.g. `status: complete` with `verification.result != pass`), do NOT
  accept it — send exactly one standardized re-prompt asking only for the corrected block. Cap at 2
  retries, then escalate to the user.
- Accept completed work only when the block validates AND meets the success criteria.

Then route:

- Send targeted follow-ups for missing verification, scope drift, or blockers.
- Avoid duplicating a worker's investigation unless its result is incomplete or suspect (check the
  unit ledger first).
- If two or more workers conflict, pause integration and resolve ownership before more edits happen.

### 7. Iterate waves to convergence

For multi-wave missions, after routing a wave's follow-ups, apply the declared `convergence.rule`
before consolidating:

- **single-pass** — one wave; skip to consolidate.
- **loop-until-dry** — keep opening units until `k_empty` consecutive waves produce zero *new*
  (deduped) units; maintain `empty_streak` in the manifest.
- **loop-until-budget** — stop when a budget cap is hit.
- **accumulate-to-target** — stop when the target count/coverage is reached.

"New" and "dry" are measured against the manifest's set of `unit_key`s, not memory. Never stop
silently — write why iteration ended (`open_followups` / `decisions`).

### 8. Verify and consolidate

Before declaring the mission done:

- Run or delegate the agreed verification gate.
- Review diffs or ask an independent reviewer session for high-signal findings.
- Ensure worker outputs are integrated in the right branch/session.

**Wave-join / completeness gate:** the mission is complete only when **every** manifest worker row is
in a **terminal** state — `complete`, `failed`, or `dropped`. Non-terminal rows (`pending`,
`dispatched`, `needs-decision`, `blocked`, `stalled`) must first be resolved; a unit that cannot be —
e.g. a worker that never reported by its checkpoint, marked `stalled` — must be explicitly converted
to `dropped` with a reason. Only then may the mission be declared *"complete with N dropped: <ids +
reasons>"*. Never close with a non-terminal row, and never drop silently. Enumerate every dispatched
unit in the final summary.

**Pull cadence (no push signal):** a session-native control plane has no "worker done" event to wake
it. After dispatching a wave, define the next checkpoint trigger — a follow-up turn, a status-table
poll, or a user ping — and never leave a wave un-joined.

For PR-bound work, keep the control session responsible for final PR readiness and review routing.

## Safety rules

- Do not spawn workers for trivial tasks.
- Do not let multiple workers edit the same files unless explicitly coordinated.
- Do not assume a named app connector exists; discover it and fall back honestly.
- Do not silently create branches, commits, pushes, or PRs; follow the user's consent and repo rules.
- Do not ask workers to share secrets or sensitive data across sessions.
- Worker subagents are leaf helpers — they MUST NOT create or steer further persistent sessions. The
  hierarchy is exactly two levels (control -> worker -> subagents); a worker that needs another full
  workstream reports that need to control.
- Enforce the concurrency and total-fan-out caps; never exceed them silently. Dropped, skipped, or
  failed units MUST be recorded with a reason (no silent truncation).
- If using an in-place checkout, be extra careful: other user-owned changes may already exist.
- If the plan changes materially, update the user and the workers before continuing.

## Recommended reporting format

Use a compact control-plane update (rows derived from the manifest):

Status: <on track | blocked | needs decision | complete> Budget: in-flight <X/Y> · spawned <A/B> · wave <N> (empty-streak <E>)

Decision needed: <only if blocked>

Keep user-facing updates concise. The control session should make coordination legible, not flood the
user with every worker's transcript.