Session Orchestrate

session-orchestrate — product-plan completion across bounded tasks

Self-validate after edits. Run ./scripts/validate.sh from this skill directory after any change.

This skill reads the repository's product-plan owner, assesses implementation against live evidence, maintains a source-fingerprinted program map in the repo's .session/ workspace, executes one goal, and creates at most one same-project successor per handoff. It preserves exact unfinished work through save-session and resume-session. Running $session-orchestrate authorizes orchestration now; it does not make old checkpoint or session-history details true.

Operating contract

Main flow

Resolve the caller's current Git product root, then run python3 ~/.codex/skills/session-orchestrate/scripts/entry.py --compact --root "$(git rev-parse --show-toplevel)" once. When an authorized successor prompt supplies a nonce, add --claim-nonce <nonce>; this mechanically claims, canonicalizes, binds, and materializes the exact objective without shell extraction. Follow route_receipt until one of its listed invalidators changes. Run its reference_command once only when present, and its goal_detail_argv only when the selected goal's actions or routes are needed. A claimed handoff needs neither read—use its goal_file, call create_goal with that exact objective, settle with set-goal, execute first_command, then immediately record its returned hash with consume-command. Re-entry never replays a consumed command.

The helper refuses the global skills repository, creates or validates only the current product's .session/, delegates checkpoint eligibility to resume-session, checks plan and chain consistency, and returns a cheap owner/status inventory. Use deterministic owner reads first. If delegation is still plausible, let codex-routing-policy choose the lane, subagent-playbook choose the agent type, and codex-efficient-delegation decide whether the bounded treatment repays its overhead; a successor is continuity transfer, not subagent delegation. Rebuild only when workspace.program_action says so, and rebuild derived projections in place—never delete .session to recover staleness.

If a claimed handoff's owner sources changed, revalidate-claimed-handoff keeps its exact goal and restricts review to the changed owner slice; do not reopen broad planning or history.

Use scripts/chain_state.py for every state transition, scripts/validate_goal.py before create_goal, and scripts/checkpoint.py for exact-goal closeout.

Hard rules

1. One substantive goal. Split independent deliverables, but keep one accepted milestone's implementation, actual-target verification, and repository-required promotion/handoff stages in one project-lifecycle. Reconcile already-proven work inline without consuming a hop.
2. Reuse deterministic receipts. Refresh only after a receipt invalidator changes. Record proof by scope plus product and optional proof-environment fingerprints; a newer generation supersedes only that scope. A selector must match the admitted goal; a dynamic queue retains only its exact unfinished target.
3. Preserve exact transactions. Keep one canonical objective until completion or handoff, consume each admitted command once, and honor hop/nonce bounds. A same-goal successor requires a paused source Codex goal plus a genuine context, compaction, or operator-requested task boundary; a next-goal successor requires a completed source goal plus accepted evidence. Role switches, fixes, retests, and proof continuation stay in the same task or use the delegation owners. Reclaiming the same nonce is idempotent and never re-exposes a consumed command. "At most one successor" means zero only when no eligible goal remains, a phase/authority/max-hop stop applies, spawn_allowed is false, task creation is unavailable, or the operator opts out.
4. Pause authority, stop phases. Use await-authority for spend, deployment, sends, destructive work, secrets, or authentication. Resume the same goal only after explicit authority; never infer a new product phase.
5. Keep owners separate. Product owners define completion; TRACKING.json derives progress, CURRENT.md owns tactical resume, and ORCHESTRATION.json owns mechanics. A stale map regenerates only TRACKING.json and PLAN.md; preserve checkpoints, chain history, admitted/claimed goals, nonces, blockers, and successor ids. History and file presence are hints, not proof.
6. Freeze before final proof. Persist repository-owned lifecycle routes and repair/create a local skill only for proven repeated multi-step friction. Before expensive rendered or independent acceptance, freeze the acceptance contract, semantic proof-owner evidence, product fingerprint, and fingerprint-keyed artifact root with chain_state.py freeze-proof. Batch all findings from one review wave before editing. A later source mutation requires targeted repair, a new freeze, and only affected proof reruns; final acceptance uses record-proof --final-acceptance.
7. Bound discovery and evidence. A justified explorer may inspect at most three sessions. Keep inline proof within the receipt budget using paths, stable ids or hashes, and concise results—never raw logs, base64, or image batches.
8. Avoid false blockers. Status questions, authentication handoffs, repair prompts, and a bounded proof-campaign pause are not terminal blocker repeats. Persist an exact proof blocker and resume the same goal without a hop or successor. Skip broad session-introspection when a repository owner already provides the exact issue and next command.

Cross-references

• references/workflow.md — source precedence, operator DNA, program mapping, goal selection, negative scenarios, handoff, and closeout
• references/program-schema.md — canonical .session files, program JSON input, sync, status, and goal-update commands
• scripts/session_workspace.py — workspace bootstrap, legacy migration, source fingerprints, generated plan, and evidence tracking
• scripts/project_inventory.py — cheap owner/plan/status inventory by default; bounded history, commit, and skill hints only in explicit explore mode
• scripts/entry.py — checkpoint, chain, and project-inventory entry resolver
• scripts/chain_state.py — nonce-protected chain transaction state
• scripts/validate_goal.py — session-goal shape and size gate
• scripts/checkpoint.py — exact-goal save-session wrapper
• sibling skills: save-session, resume-session, session-introspection