---
name: orchestrate-supergoals
description: Execute a complete phased project plan by coordinating one work unit at a time through a dedicated Supergoal task, verifying each result, repairing technical failures, advancing automatically, and pausing only for genuine owner decisions. Use for explicit full-program autonomous execution requests. Do not use for plan review, one phase, or ordinary Supergoal tasks.
---

# Orchestrate Supergoals

The task is:

`$ARGUMENTS`

Coordinate a complete project plan from intake to final audit. The controller owns the program
sequence; one dedicated executor owns the product edits through ordinary `$supergoal` runs.

## Authorization

Classify the request before creating a Goal, executor task, runtime state, or project change:

- `AUTHORIZED_EXPLICIT`: `$orchestrate-supergoals <plan>` or an equivalent explicit full-program
  execution request.
- `AUTHORIZED_UNAMBIGUOUS`: the user clearly asks to execute every phase autonomously from start
  to finish, including automatic repair and owner gates.
- `NOT_AUTHORIZED`: review, explanation, plan editing, one phase, ordinary Supergoal work, or any
  explicitly read-only request.

For `NOT_AUTHORIZED`, remain read-only and do not create a run. Do not infer execution from a
mention of this skill, Supergoal, or a phased plan.

## V1 boundary

V1 supports Codex Desktop only. Before dispatching work, inspect the actual available capabilities:

- native Goal support for the controller and executor;
- one exact executor task that can be created or bound;
- programmatic send, wait, and read operations for that task;
- shared access to the target project and Supergoal evidence.

Use the available task-coordination tools by capability, not by assumed tool name. If only task
creation is unavailable but the user supplied an exact executor task ID, use bound-executor mode.
If send, wait, read, native Goals, or evidence access is unavailable, record
`stop_reason: UNSUPPORTED_SURFACE` in the bootstrap run and stop before creating an executor,
running Supergoal, or changing the product. Never ask the user to relay every prompt manually.

## Durable run

For an authorized request, create the bootstrap state before capability preflight with the bundled
helper:

```text
python3 <skill-dir>/scripts/state.py init --project-root <project> --run-id <id> \
  --plan-path <plan> --objective "<objective>"
```

Git projects use `<git-common-dir>/codex/orchestrate-supergoals/runs/<run-id>/state.json`; non-Git
projects use `<project>/.codex/runtime/orchestrate-supergoals/runs/<run-id>/state.json`. Keep this
state outside the working tree. The controller is its only writer. Supergoal keeps its own
artifacts.

The state has one of these readable statuses:

`PREPARING`, `RUNNING`, `VERIFYING`, `REPAIRING`, `WAITING_OWNER`, `PAUSED`, `BLOCKED`, `STOPPED`,
`COMPLETE`.

Use `stop_reason` for `NO_GO` and `UNSUPPORTED_SURFACE`. Update state atomically and reject stale
revisions. One active source-editing orchestration run is allowed per target project; resume a
matching run and report unrelated conflicts instead of interfering with them.

## Controller Goal and executor

Create one program-level native Goal whose objective contains:

```text
Supergoal run root: <canonical run root>
Program objective: <final outcome>
Continue through all technical work, verification, repair, owner gates, and final audit.
```

Create or bind exactly one persistent executor task for the whole program. Save its exact task ID
in state. Do not create a new executor for every phase. The executor must use normal Supergoal
behavior; do not change or embed a second implementation of Supergoal.

## Contracting

Read project instructions, the supplied plan, relevant code/tests, and existing project practice.
The source plan must identify a final objective, phases or major results, the meaning of each, and
known constraints. Complete missing technical detail yourself:

- order and dependencies;
- acceptance checks and commands;
- regression and security boundaries;
- required evidence;
- program-level definition of done.

You may split or resequence technical work, but never silently change product meaning or remove
requested scope. If read-only inspection cannot determine one product outcome, prepare a concrete
owner question with alternatives and consequences before executing that part.

## Work-unit loop

For each ordered work unit:

1. Persist the work-unit ID and a new attempt ID before dispatch.
2. Send the executor one bounded `$supergoal` request containing the objective, allowed scope,
   forbidden scope, acceptance checks, program run ID, work-unit ID, and attempt ID.
3. Wait for that executor task; do not ask the owner to relay messages.
4. Correlate the result with its native Goal and one Supergoal run root.
5. Independently verify the evidence. A prose success claim is not enough.
6. Advance only after acceptance. On a technical defect, repair the same unit with a new attempt.
7. Stop at a genuine owner gate only after its decision packet is complete.

Load [references/workflow.md](references/workflow.md) for the dispatch, progress, owner, and
resume details. Load [references/verification.md](references/verification.md) when correlating
artifacts or deciding whether a work unit is accepted.

## Repair and owner gates

Technical uncertainty is repaired automatically while a safe bounded path remains. Preserve failed
evidence, diagnose the cause, confirm whether Supergoal already recovered, send a focused repair
objective, and rerun the affected checks. Never weaken requirements or tests to clear a failure.

Ask the owner only for unresolved product meaning, authority, missing credentials, irreversible,
public, or paid actions, or genuine human judgment. Before entering `WAITING_OWNER`, prepare the
artifact or verified URL, what passed, a checklist, available verdicts, a recommendation, and the
exact next action after each verdict. Use `GO`, `PARTIAL <issue>`, or `NO-GO <reason>`; `NO-GO`
ends the run as `STOPPED` with `stop_reason: NO_GO`.

## Resume and completion

After compaction, application restart, stale controller lease, or uncertain dispatch, reconcile
state with the executor task, its Goal, and Supergoal artifacts before doing anything else:

- active existing attempt → wait;
- terminal existing attempt → verify it;
- proven failed or absent attempt → repair or dispatch a new attempt;
- unknown dispatch → reconcile, never blindly retry.

Do not redispatch merely because the controller lost context. Keep progress updates informational.

After all units pass, run a program-level audit against the original plan, constraints, evidence,
integration/regression checks, security boundaries, and documentation. Then record closeout and set
the run `COMPLETE`. Do not claim completion before this audit.

Use Recallant for project memory and closeout when available; it is not a replacement for the
active state file. Do not save secrets or raw private artifacts.