/control-session-orchestrator

name: control-session-orchestrator
description: >
  Control-plane workflow for coordinating multi-agent, multi-session project work from a single
  Codex, GitHub Copilot, or agent-app control session. Use this skill whenever the user asks to
  orchestrate agents, create or steer worker sessions, run a workflow-like effort, fan out
  audits/research/migrations, coordinate parallel implementation streams, monitor other project
  sessions, or compare this control-session pattern to Claude Code dynamic workflows. This skill is
  especially relevant when the current session can spawn persistent project sessions and those
  sessions can spawn their own subagents, creating a two-level orchestration hierarchy.

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

| Capability | Codex app | GitHub Copilot app | Fallback | |---|---|---|---| | Find worker sessions | List/search project threads | List/search app sessions | Ask user for target session links/IDs | | Create persistent workstreams | Create or reuse Codex threads/worktrees when available | Create or reuse Copilot app sessions/workspaces when available | Use local subagents only | | Steer an existing workstream | Send a follow-up prompt to the thread | Send a follow-up prompt to the session | Ask user to paste the prompt into the worker | | Local fan-out | Spawn subagents from this session or ask workers to spawn their own | Use Copilot's available agent/session tools | Keep work local | | Tracking | Thread titles, pins, branches, PRs, canvas nodes, compact status tables | Session names, branches, PRs, issues, canvas nodes, compact status tables | Markdown status table |

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.

{
  "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"],
  "succ