Issue Planning Mode

Issue Planning Mode — Mandatory for ALL Issues

ALL agents (Codex, Codex, Gemini, Hermes) MUST follow this workflow for every GitHub issue. Load this skill before drafting or executing any plan.

Full onboarding guide with step-by-step details: docs/plans/README.md

Workflow Overview

Issue → Resource Intel → Draft Plan → Adversarial Review → Post to GH
  → Label status:plan-review → USER APPROVES → Label status:plan-approved
  → Implement (TDD) → Close

Steps

Step 1: Intake and Resource Intelligence

1. Read the full issue body — scope, acceptance criteria, references
2. Classify complexity: T1 (trivial), T2 (standard), T3 (complex)
3. Search existing code, standards, documents, and prior plans before writing

Step 2: Draft Plan

Copy template and fill all sections:

docs/plans/_template-issue-plan.md  -->  docs/plans/YYYY-MM-DD-issue-NNN-slug.md

Required sections: Resource Intelligence Summary, Artifact Map, Deliverable, Pseudocode (T2/T3), Files to Change, TDD Test List, Acceptance Criteria, Risks.

Update the index table in docs/plans/README.md with a new row.

Execution discipline for delegated agents:

• If using Codex/Codex/Gemini in parallel worktrees, explicitly anchor the repo/worktree path in the prompt/context and verify the plan file was written in the intended checkout. Do not assume the child agent stayed in the requested worktree.
• After drafting, verify all expected artifacts exist where intended:
  • the plan file path
  • the docs/plans/README.md index row
  • no accidental extra rows/issues were inserted
• Keep status conservative as draft unless formal review artifacts actually exist under scripts/review/results/. GitHub comments alone are useful evidence, but they do not replace the repo’s review-artifact convention.

Step 3: Adversarial Review

Route the plan to 2+ AI providers for review. Each gives: APPROVE | MINOR | MAJOR. If any MAJOR: revise and re-review.

Post artifacts to scripts/review/results/YYYY-MM-DD-plan-NNN-<agent>.md.

Reviewer-stance contract (mandatory framing for every review prompt): Every prompt sent to a reviewer MUST force an adversarial stance. "Adversarial" here means actively hunting for defects, not charitable reading. Required clauses in the prompt:

1. State explicitly: "You are an adversarial reviewer. Assume the plan has defects until proven otherwise."
2. Forbid praise and restatement: "Do not praise. Do not restate the plan. Focus only on what is wrong, missing, or risky."
3. Bias toward non-approval: "Return APPROVE only after affirmatively verifying each correctness-critical claim. When in doubt, return MINOR or MAJOR."
4. Require evidence: "Each finding must cite a specific file path, plan section, or quoted claim."
5. Treat cited sources as assertions to verify, not facts to trust.
6. Empty reviews are failures — if nothing is found, explicitly list what was checked.
7. Prefer attested evidence over plan text (#2405). If the review prompt carries a ## Attested Evidence block produced by scripts/review/attest-plan-claims.sh, treat plan-asserted facts (issue states, file existence, commit SHAs) as claims to verify against the attestation, not as facts. Do not report "unverified claims" findings for facts already covered by the attestation block — they are verified by construction at the recorded commit SHA. If the plan contradicts the attestation, the contradiction is a finding; the attestation is authoritative. Cross-review dispatchers (submit-to-codex.sh, submit-to-gemini.sh) inject this block automatically for plan files under docs/plans/.

A review that returns APPROVE without at least one verified check-list item is suspect and should be rerun with a stronger prompt.

Rationale: user feedback 2026-04-17 on #2323 — "Make all the reviews adversarial in nature. Helps maximize productivity." Rubber-stamp reviews produce downstream rework that is more expensive than a cold review would be.

Step 4: Post and Label

1. Post the plan as a GitHub issue comment
2. Apply label: gh issue edit NNN --add-label "status:plan-review"
3. STOP — do NOT implement. Wait for user approval.

Step 6: User Approval

The user (never the implementing agent) approves the plan:

• gh issue edit NNN --remove-label "status:plan-review" --add-label "status:plan-approved"
• Creates marker: .planning/plan-approved/NNN.md

Step 5: User Approval

The user (not the implementing agent) approves:

gh issue edit NNN --remove-label "status:plan-review" --add-label "status:plan-approved"
mkdir -p .planning/plan-approved
echo "Approved by: <user>" > .planning/plan-approved/NNN.md

Self-approval by the implementing agent is blocked by the plan-approval gate.

Status authority and surfacing rule

When plan status signals disagree across artifacts, use this precedence:

1. Latest/most-advanced GitHub status:* label is authoritative for live issue state
2. .planning/plan-approved/NNN.md marker is authoritative local evidence that approval happened
3. docs/plans/README.md is a convenience index and may lag; update it when you notice drift, but do not let it override GitHub + approval-marker reality

Practical rules:

• If both status:plan-review and status:plan-approved appear, treat status:plan-approved as authoritative and clean up the stale lower-status label when possible.
• Do not surface a plan to the user for approval until adversarial plan review is complete and the plan is actually approval-ready.
• If a GitHub issue is already at a more advanced latest status (for example status:plan-approved), do not downgrade it just to match a stale local plan file or README row.

Status precedence and stale-state handling

When issue state drifts across artifacts, use this precedence order for operational decisions:

1. status:plan-approved label on the GitHub issue
2. .planning/plan-approved/NNN.md local approval marker
3. status:plan-review label on the GitHub issue
4. local plan status in docs/plans/README.md

Rules:

• Treat the latest / most-advanced status as authoritative. Example: if both status:plan-review and status:plan-approved are present, treat the issue as plan-approved until labels are cleaned up.
• docs/plans/README.md can lag reality; do not rely on it alone for approval state.
• A plan should be surfaced to the user for approval only after adversarial review is complete and the plan content is actually approval-ready. Do not surface draft plans just because a stale label suggests plan-review.
• If you find label drift or README drift, clean it up or annotate it immediately so the queue stays trustworthy.

Important operational rule learned in live use:

• If multiple status:* labels are present on the same GitHub issue, treat the latest / most-advanced status as authoritative (for example, status:plan-approved outranks status:plan-review). Clean up stale lower-status labels when possible, but do not block execution-state interpretation on label drift alone.
• Only surface a plan to the user for approval after adversarial plan review is complete. Draft plans with pending review findings should not be presented as approval-ready just because a local plan file exists.
• docs/plans/README.md can drift from GitHub labels and .planning/plan-approved/*.md; when auditing readiness, reconcile all three and use the latest effective state rather than trusting the README row blindly.

Status precedence and surfacing rules

• If a GitHub issue has multiple status:* labels, treat the latest/most-advanced state as authoritative. In practice: status:plan-approved outranks status:plan-review.
• When local plan indexes (for example docs/plans/README.md) disagree with newer approval markers or newer GitHub status labels, reconcile to the newer/more-advanced state before deciding whether user approval is still needed.
• Use .planning/plan-approved/<issue>.md as the canonical local proof that approval happened.
• Do not surface a plan to the user for approval until adversarial plan review is complete and the plan is actually approval-ready. Draft plans with pending/failed review should be revised first, then surfaced.

Pending cross-review audit routine

When the user asks which plans are still pending cross-provider review, audit all five signals before answering:

1. docs/plans/README.md plan row/status
2. direct docs/plans/ file search for issue-<NNN>-*.md (catches orphaned/unindexed local plans)
3. live GitHub issue labels/state via gh issue view/list
4. local approval marker .planning/plan-approved/<issue>.md
5. review artifacts under scripts/review/results/

Operational rules:

• status:plan-review label alone is not sufficient to say a plan is truly pending; verify whether the issue already advanced to status:plan-approved or already has a local approval marker.
• status:plan-approved without .planning/plan-approved/<issue>.md is approval-state drift; flag it as governance cleanup, not a clean approval-ready item.
• README rows can be stale in either direction. Treat them as discovery/index hints, not final authority.
• Also ignore/example-filter template rows or placeholder examples in docs/plans/README.md (for example the sample 1234 entry in the "Entry Format" section). Do not treat README sample rows as real pending work; always verify against a live GitHub issue and an actual plan file before classifying an item.
• For cross-provider plan review, explicitly check whether provider-specific artifacts exist for Codex and Gemini (or documented substitutes when a provider was unavailable). Files like *-subagent.md, *-hermes.md, or *-final.md do not by themselves prove Codex/Gemini review happened.
• Also verify that a canonical local plan file actually exists under docs/plans/. An open issue in status:plan-review with no plan file and no review artifacts is not a true pending cross-provider review item; it is earlier-stage governance drift / missing-plan work.
• Separate the queue into:
  • true pending review items (open, not approved, plan file exists, cross-review incomplete)
  • needs-revision items (review artifact set exists, but latest provider findings still return MAJOR / not approval-ready)
  • missing-plan items (live status:plan-review but no canonical docs/plans/ artifact exists yet)
  • state-drift items (labels/README/markers disagree)
  • closed-stale-index items (issue already CLOSED or otherwise completed, but docs/plans/README.md and/or the local plan header still claim plan-review / adversarial-reviewed)
• Closed-stale-index remediation rule:
  1. verify the live GitHub issue is actually CLOSED (or otherwise definitively completed)
  2. verify any implementation/closeout evidence in issue comments or landed commits if needed
  3. update docs/plans/README.md from plan-review/adversarial-reviewed to completed
  4. update the local plan header status to completed
  5. do not treat partial historical review artifacts as pending cross-provider work once the issue itself is already complete
• In practice, audit in this order for each candidate issue: GitHub labels/state → local plan file under docs/plans/ → local approval marker → review artifacts by provider. This prevents wasting time chasing “missing provider reviews” for items that are actually missing the plan itself.
• Missing-plan remediation sequence (important):
  1. Draft the canonical local plan under docs/plans/ and add the docs/plans/README.md row with local status draft.
  2. Post a short governance comment on the issue explaining that the item was mislabeled as status:plan-review without a canonical plan artifact.
  3. If the issue truly had no local plan and no provider review artifacts yet, remove the stale live status:plan-review label while the plan is still only a local draft.
  4. Run the real adversarial review wave (Codex/Codex/Gemini as available).
  5. Only after provider artifacts exist, update the plan + README to plan-review and restore/apply the live status:plan-review label.
• This keeps live issue state aligned with actual plan maturity and avoids pretending a draft-only item is already in cross-provider review.
• When only the Codex review artifact is missing, a concise file-path-based Codex -p review prompt is often more reliable than embedding the full plan text inline. If a long inline Codex review prompt hangs or hits a turn cap, retry immediately with a shorter prompt that names the plan file path and explicitly requests the required review headings.
• For plan-review items that are being iteratively tightened after MAJOR findings, keep the ## Adversarial Review Summary current after each wave: record the latest provider verdicts, explicitly say whether the plan is still not approval-ready, and summarize what changed in the latest patch wave. Do not leave the summary stuck at PENDING once real artifacts exist.
  2. add/update the docs/plans/README.md row with local status draft
  3. post a short governance comment explaining the issue was in missing-plan drift
  4. if you need labels to reflect reality strictly, remove stale status:plan-review until real provider review artifacts exist
  5. run the provider review wave
  6. once review artifacts exist, update local status to plan-review, restore/add the live status:plan-review label, and post the review-state update
• When only the Codex review artifact is missing, a concise file-path-based Codex -p review prompt is often more reliable than embedding the full plan text inline. If a long inline Codex review prompt hangs or hits a turn cap, retry immediately with a shorter prompt that names the plan file path and explicitly requests the required review headings.
• For new or recovered plan drafts, keep the local plan file status conservative as draft until actual provider artifacts exist. After the first real review wave lands, update the plan file/README row to plan-review and summarize the live blocker state in ## Adversarial Review Summary rather than leaving placeholder PENDING language.
• If you launch a long-running background Codex review and then recover with a shorter fallback prompt, do not assume the first run is dead forever. Poll or inspect the original background process/log later. If it eventually completes with a fuller or sharper review, refresh the canonical repo artifact with the stronger findings and post a short GitHub follow-up comment noting that the completed long-form review supersedes or sharpens the earlier summary.
• Practical artifact rule: the repo artifact under scripts/review/results/ should represent the best available current-review content, not merely the first usable fallback. Late-arriving stronger findings should replace the weaker stopgap artifact rather than being ignored in terminal/process logs.

This prevents falsely telling the user there are no pending plan reviews just because the live status:plan-review label set is empty, and it avoids misclassifying missing-plan issues as pending provider-review work. Additional triage rule learned in live queue audits:

• For feature/intake sweeps, do not describe an issue as "pending other-provider cross-review" unless a local plan artifact already exists and at least one real provider review artifact exists. If the issue only has the live status:plan-review label but lacks both the local plan file and scripts/review/results/ artifacts, classify it as earlier-stage governance drift / missing-plan work, not as a pending cross-review item.

This prevents falsely telling the user there are no pending plan reviews just because the live status:plan-review label set is empty, and also prevents overstating unlived/missing-plan items as if they were already in the provider review stage.

Governance cleanup after fresh MAJOR re-review

If a plan had previously advanced to status:plan-approved or gained a local approval marker, and a later fresh adversarial re-review returns blocking MAJOR findings, treat that as state rollback required, not just a note in comments.

Cleanup sequence:

1. Post the new review summary/comment linking the fresh review artifacts.
2. If the GitHub issue is still open and labeled status:plan-approved, remove status:plan-approved and add status:plan-review.
3. If the issue has a stale local approval marker .planning/plan-approved/<issue>.md but the live issue is now back in status:plan-review, remove the stale marker.
4. Update docs/plans/README.md to match the rolled-back live state (plan-review rather than plan-approved).
5. Leave a governance-cleanup comment on the issue explaining that the rollback is due to fresh blocking review evidence, not arbitrary relabeling.

Practical rules:

• For open issues, stale approval markers should be removed once the issue is rolled back to status:plan-review.
• For closed issues, stale status:plan-approved labels are misleading and should be removed, but marker cleanup can be treated as historical hygiene rather than an operational blocker.
• If a provider is unavailable (for example Gemini 429 capacity exhaustion), do not stall indefinitely; record the provider failure explicitly and continue with available review evidence while keeping the issue in a non-approved state until blocking findings are resolved.
• Fresh MAJOR review evidence outranks older optimistic comments, stale README rows, and stale marker files.

Fresh-review rollback rule (critical drift cleanup)

If a plan receives fresh external review artifacts (for example Codex/Gemini) with MAJOR / not approval-ready after the issue had already drifted to status:plan-approved, treat that as a governance-state regression that must be cleaned up immediately.

Required cleanup sequence:

1. Post a short GitHub comment summarizing that fresh review evidence returned MAJOR and link the new review artifacts.
2. Move the issue label back from status:plan-approved to status:plan-review.
3. If a local approval marker exists at .planning/plan-approved/NNN.md, remove it so local state no longer implies approval.
4. Update the corresponding docs/plans/README.md row from plan-approved to plan-review.
5. Re-verify all three signals after cleanup:
   • GitHub labels
   • local approval marker presence/absence
   • README row status

Operational rule:

• Fresh blocking review evidence outranks stale prior approval signals. Do not leave an issue in status:plan-approved just because it was previously approved if the newest adversarial review says it is not approval-ready.
• Closed issues with stale status:plan-approved but no matching local approval evidence should at minimum have the misleading label removed, even if you do not reopen the issue.

Step 6: Implement (TDD)

When fresh external plan reviews land (especially Codex + Gemini) and they materially disagree with the current issue state, reconcile the workflow state immediately instead of leaving the queue misleading.

Required checks after a review wave:

1. live GitHub status:* labels
2. .planning/plan-approved/<issue>.md local marker
3. docs/plans/README.md row status
4. latest provider verdicts in scripts/review/results/

Remediation rules:

• If any fresh provider review returns MAJOR, do not leave the issue surfaced as effectively approval-ready. For open issues, roll the issue back to status:plan-review unless there is newer authoritative user approval after the reviewed plan revision.
• If an open issue is status:plan-review but still has a local .planning/plan-approved/<issue>.md marker from an older state, remove the stale marker so local state no longer implies approval.
• If an open issue is status:plan-approved but has no local approval marker, remove or downgrade the stale approval label unless there is other authoritative approval evidence you can point to.
• Sync docs/plans/README.md to the effective live state once labels/markers are corrected.
• Post a short GitHub comment when you perform governance cleanup so future readers know why approval-state signals changed.

Practical sequencing:

1. finish/post review artifacts
2. classify issues into approval-ready vs needs-revision
3. fix GitHub labels/comments
4. fix local marker drift
5. update docs/plans/README.md
6. verify the final open queue

This keeps the plan queue operationally trustworthy after large review waves instead of letting stale plan-approved signals linger.

Governance cleanup when fresh review evidence contradicts current status

If a plan already carries status:plan-approved but fresh Codex/Gemini review returns MAJOR or otherwise says "not ready for user approval":

1. Treat the fresh review evidence as a governance problem, not as permission to continue.
2. Reconcile all four surfaces:
   • GitHub status:* labels
   • .planning/plan-approved/<issue>.md marker
   • docs/plans/README.md row status
   • scripts/review/results/ artifacts
3. If the issue is still open and there is no local approval marker, remove stale status:plan-approved and move it back to status:plan-review.
4. If the issue is closed but still carries stale status:plan-approved without a marker, remove the stale approval label and post a cleanup note; do not silently leave misleading approval state behind.
5. Post a short GitHub comment explaining the cleanup and linking the blocking review artifacts.
6. Update docs/plans/README.md if it still claims adversarial-reviewed or plan-approved in a way that no longer matches the effective live state.

Practical rule:

• After fresh external review, the queue should distinguish between:
  • pending review
  • needs revision after MAJOR review
  • state drift cleaned / still needs rewrite

Step 6: Implement (TDD)

Only after status:plan-approved label AND .planning/plan-approved/NNN.md marker exist:

1. Tests FIRST — write tests, confirm they fail
2. Implement minimum code to pass tests
3. Run full test suite — confirm no regressions
4. Self-review against approved plan

Step 7: Close

• Commit with conventional message referencing the issue
• Push, post summary comment, close issue

Batch / Overnight Sessions

• Draft plans and label status:plan-review — do NOT implement
• Only implement issues already labeled status:plan-approved

Engineering-Critical Issues

Issues with cat:engineering* or cat:data-pipeline labels require the full engineering-issue-workflow skill (adds cross-review after implementation).

Enforcement

• PreToolUse hook: .Codex/hooks/plan-approval-gate.sh blocks writes without approval marker
• Pre-commit hook: scripts/enforcement/require-plan-approval.sh --strict blocks commits without approval
• Self-approval check: gate verifies approval was not created in the same session

Safe paths (no approval needed)

.planning/, docs/plans/, docs/governance/, docs/reports/, docs/standards/, and the four top-level agent adapter markdown files

Emergency bypass

SKIP_PLAN_APPROVAL_GATE=1  # for Codex hook
FORCE_PLAN_GATE=1 git commit  # for pre-commit hook

All bypasses are logged.

References

• Full guide: docs/plans/README.md
• Template: docs/plans/_template-issue-plan.md
• Hard-stop policy: docs/standards/HARD-STOP-POLICY.md
• Engineering workflow: .Codex/skills/coordination/engineering-issue-workflow/SKILL.md