# Checkpoint Orchestrator

> Autonomously drive a multi-checkpoint coding plan through implementation, review, revision, and approval using one persistent worker subagent and durable .agent state. Use when the user wants Codex to run a planner/reviewer-to-implementer loop without manually prompting each handoff.

- Skill: `souravmohapatra/checkpoint-orchestrator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add souravmohapatra/checkpoint-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/souravmohapatra/checkpoint-orchestrator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: souravmohapatra (https://skillmd.com/u/souravmohapatra)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/souravmohapatra/checkpoint-orchestrator

---


# Checkpoint Orchestrator

Act as the planner, reviewer, and sole orchestrator. Delegate code changes to one built-in `worker`; do not add a separate reviewer unless the user asks for one.

## Durable state

Use `$workflow-guide` before orchestration. Resume `.agent` when present. If it is absent, follow the workflow-guide consent rule before creating it.

Keep these ownership boundaries:

- Parent owns `.agent/PLAN.md`, `.agent/REVIEW.md`, `.agent/LOOP.json`, and `.agent/WORKER.json`.
- Worker owns application changes, focused verification, `.agent/PROGRESS.md`, and `.agent/HANDOFF.md`.
- As the only exception, a finishing worker may change `LOOP.json.phase` from `implementing` or `revising` to `ready_for_review`. It must preserve every other field.
- Never let two agents edit application code concurrently.

`LOOP.json` is a durable snapshot, not a rigid workflow engine. Valid statuses are `active`, `complete`, and `blocked`. Useful phases are `planning`, `implementing`, `ready_for_review`, `reviewing`, `revising`, `complete`, and `blocked`. Default `max_review_rounds` to 3 when unset.

Keep status truthful. Working phases normally use status `active`; terminal phase `complete` uses status `complete`; terminal phase `blocked` uses status `blocked`. The parent may introduce or change phases, checkpoints, or plan structure when that better serves the objective. Record consequential deviations and their rationale in `.agent/DECISIONS.md` or `.agent/ANALYSIS.md` so another thread can recover them.

`WORKER.json` is the workspace-local worker configuration:

```json
{
  "model": "gpt-5.6-luna",
  "reasoning_effort": "medium"
}
```

If `WORKER.json` is absent, ask the user which worker model and reasoning effort to use. Do not infer defaults or spawn a worker first. Save their answer there for later checkpoints and sessions. If Codex rejects a configured value, ask for a replacement rather than silently falling back.

## Resume intelligently

Reconcile durable notes with the actual workspace before acting. Treat them as evidence, not unquestionable instructions.

- Follow an explicit user-requested checkpoint or phase unless it is unsafe or impossible; persist the resulting state.
- Use the persisted phase when it still fits the evidence. Correct or replace it when a different next action is more effective.
- When state is absent or unclear, normally review first if implementation evidence exists; otherwise start by planning. This is a recovery default, not a restriction on better judgment.
- The parent may replan, combine or split checkpoints, repeat review, investigate before choosing a phase, or take another justified route. Keep `.agent` synchronized with the route chosen.

Implementation evidence means a relevant diff, a checkpoint-ready entry in `PROGRESS.md` or `HANDOFF.md`, or recorded verification for the active checkpoint. Merely having repository files is not implementation evidence.

## Orchestrate

Choose and record the next useful checkpoint. Give checkpoints explicit acceptance evidence when practical.

When implementation or revision is the right next action, spawn one built-in `worker` using `WORKER.json`. Give it only the active checkpoint, its acceptance evidence, and unresolved finding IDs. The worker instructions are strict: `PLAN.md` and `REVIEW.md` are parent-owned; it must run focused verification, update `PROGRESS.md` and `HANDOFF.md`, and make only its permitted `ready_for_review` state transition before returning the completion envelope.

Wait for the worker's completion event. Do not poll files, run sleep loops, or end the parent turn while it is active.

Review actual changes and verification evidence before approving implementation. Do not accept the worker's summary as proof. Record actionable findings with stable IDs in `REVIEW.md`; reuse the same worker when available or spawn a replacement after resume. Respect `max_review_rounds` as a user-visible guardrail unless the user changes it.

The parent decides when evidence justifies advancing, replanning, blocking, or finishing. Mark the objective complete only after appropriate whole-objective verification.

Keep agent messages terse and point to `.agent` files instead of repeating their contents. The worker's expected completion envelope is:

```text
CHECKPOINT_READY <checkpoint-id>
verification: <pass|fail>
progress: .agent/PROGRESS.md
```

Set the loop to `blocked` and return to the user when new authority is required, the same blocker recurs, or `max_review_rounds` is exhausted. Record the exact restart action in `HANDOFF.md`.