cvg-plan-loop

name	cvg-plan-loop
description	Orchestrate a monitored Codex planning loop with a planner, fresh plan reviewers, focused re-review, callback transport, heartbeat waiting, and strict fresh-reviewer exit gates. Use when the user asks to create or revise a plan through Codex sessions.
argument-hint	[planning goal, requirements path, behavior contract path, or planning prompt]

Codex Plan Loop

Use this skill for plan-only cvg-multi-session orchestration.

Before doing anything, open and read references/cvg-multi-session-protocol.md, then apply the protocol gates from cvg-multi-session:

• real Codex thread gate,
• orchestrator callback transport gate,
• heartbeat handoff gate,
• cvg-plan-review-feedback gate,
• fresh-reviewer exit gate.

Do not implement product code in this workflow.

Phase 0: Orchestrator Setup

Record:

• current orchestrator thread id,
• worktree or repo path,
• current git rev-parse HEAD if available,
• dirty worktree state,
• source prompt and input documents,
• expected plan path or target docs directory when known.

Classify dirty files:

• plan-owned files,
• unrelated user artifacts,
• files the planner must not touch.

Phase 1: Planner Handoff

Create the planner as a real Codex thread with create_thread.

Immediately verify the returned planner thread id with read_thread. If it is not readable, do not continue.

Planner prompt must include:

• role: planner,
• destination orchestrator Codex thread id,
• required planning skill, such as cvg-plan or another user-specified plan skill,
• source prompt and exact user goal,
• repo path and starting state,
• dirty-state warning,
• mandatory context documents,
• task-triggered local instructions or domain skills,
• plan-only boundary,
• output path rules,
• no implementation, no staging, no commit unless explicitly requested,
• callback transport block,
• callback template.

Planner callback template:

I am the planner. My session/thread id is <id or thread id not exposed>. Orchestrator thread id: <orchestrator-id>. This planning round is complete. Plan path: <absolute path>. Key status: <brief>. Please decide the next step.

After verifying the planner thread, create or update a heartbeat and end the active turn. Do not use sleep or repeated read_thread to wait.

Phase 2: Fresh Plan Review

After planner callback is visible in the orchestrator thread, create a new fresh reviewer Codex thread.

Immediately verify the reviewer thread id with read_thread.

Reviewer prompt must include:

• role: fresh plan reviewer,
• destination orchestrator Codex thread id,
• required cvg-plan-review skill, such as cvg-plan-review,
• original planning goal and source prompt,
• plan path,
• repo path and relevant context,
• mandatory context documents and local policies,
• read-only boundary,
• blocker-only reporting rule,
• callback transport block,
• callback template.

Reviewer callback template:

I am the fresh reviewer. My session/thread id is <id or thread id not exposed>. Orchestrator thread id: <orchestrator-id>. This first-pass full review is complete. Verdict: <passed / blocking findings>. Findings: <none or numbered concise list>. Please decide the next step.

Create or update a heartbeat and end the active turn while waiting. Do not manually poll.

Blocking plan findings include:

• missing required surface,
• incomplete behavior contract coverage,
• wrong ownership boundary,
• unclear external or API contract,
• missing migration, rollback, deletion, privacy, or safety lifecycle,
• insufficient test or verification gate,
• plan criterion that cannot be implemented as written,
• unsafe side-effect assumption.

Phase 3: Return Review Feedback to Planner

If the reviewer reports blockers, send the reviewer feedback to the same verified planner thread with send_message_to_thread.

Do not classify findings, choose revision strategy, filter reviewer output, or turn the review into an edit list in the orchestrator.

The feedback prompt must include:

• destination orchestrator Codex thread id,
• reviewer thread id,
• required feedback skill: cvg-plan-review-feedback,
• original planning goal and source prompt,
• current plan path and related contracts,
• exact reviewer blocker findings appended under a Plan Review Feedback Input section,
• instruction to produce the cvg-plan-review-feedback intake summary before editing,
• instruction to revise only valid plan-owned findings,
• instruction to callback instead of editing when a missing behavior decision or reviewer clarification is required,
• instruction to run the gates selected by cvg-plan-review-feedback,
• unchanged scope boundaries,
• callback transport block,
• callback template.

Create or update a heartbeat and end the active turn.

Phase 4: Focused Re-Review

After planner feedback callback is visible in the orchestrator thread and a reviewable plan revision exists, send a focused re-review request to the same verified reviewer thread with send_message_to_thread.

Focused scope:

• verify old blockers were addressed,
• check directly related contradictions introduced by the revision,
• do not redo broad review unless the plan's core design changed.

Create or update a heartbeat and end the active turn.

If the planner reports a contract decision, escalation, or clarification need, route that callback to the appropriate reviewer or user decision before requesting re-review.

If same reviewer still finds blockers, repeat Phase 3.

If same reviewer passes, do not exit. Continue to Phase 5.

Phase 5: Final Fresh Review

Create a new fresh reviewer Codex thread for a complete first review of the revised plan. Verify it with read_thread.

Final exit condition:

• new fresh reviewer,
• complete first review,
• no blocking findings.

Only then can the orchestrator declare the plan loop complete.

Completion Summary

Report:

• plan path,
• planner thread id,
• reviewer thread ids,
• callback transport status,
• blockers and planner cvg-plan-review-feedback results,
• final fresh reviewer verdict,
• heartbeat cleanup,
• known gaps.