control-session-orchestrator

What this skill does

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

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

```json
{
  "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