with one click
issue-planning-mode
Mandatory planning workflow for ALL GitHub issues — plan, review, approve, then implement.
Menu
Mandatory planning workflow for ALL GitHub issues — plan, review, approve, then implement.
Adversarially review the last 24h of multi-agent work by combining git history, GitHub issue state, generated analysis artifacts, governance tests, and duplicate-checked follow-up issue creation.
Analyze session quality trends — identify high-churn patterns, report waste, flag sessions exceeding 500 tool calls
Build self-contained interactive web applications as single HTML files. Use for creating demos, prototypes, interactive tools, and standalone web experiences that work without external servers.
Quick provider/model switching for Hermes CLI — aliases, fallbacks, task routing matrix, and utilization audit pattern.
Quick provider/model switching for Hermes CLI — aliases, fallbacks, task routing matrix, and utilization audit pattern.
Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming
| name | issue-planning-mode |
| description | Mandatory planning workflow for ALL GitHub issues — plan, review, approve, then implement. |
| version | 3.1.0 |
| author | Workspace Hub |
| category | coordination |
| tags | ["planning","github","enforcement","workflow","onboarding"] |
| related_skills | ["engineering-issue-workflow"] |
ALL agents (Claude, 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
Issue → Resource Intel → Draft Plan → Adversarial Review → Post to GH
→ Label status:plan-review → USER APPROVES → Label status:plan-approved
→ Implement (TDD) → Cross-review → Completeness gate (#2798) → Close
Completeness gate before close (#2798): compute a test-/evidence-based completeness score (
scripts/workflow/completeness_score.py), persist it (kanban--metadata+ issue-bodycompleteness {json}stamp), renderdocs/reports/<date>-<issue>-completeness.html, and require the owner-onlystatus:completeness-verifiedlabel (≥ class threshold) beforegh issue close. The server-side gate (.github/workflows/completeness-gate.yml) reopens issues closed without it. See the rule.claude/rules/completeness-before-close.md.
Canonical execution method: non-trivial work must be classified up front as single-lane, parallel-readonly, or parallel-worktree per docs/standards/PARALLEL_FIRST_EXECUTION.md. Resource intelligence, plan review, and validation may run in parallel; implementation still requires user approval and TDD before any write-capable lane starts.
single-lane, parallel-readonly, or parallel-worktree. For planning, default to parallel-readonly evidence gathering when the issue is broad enough to benefit; the main orchestrator still owns the canonical plan.Mandatory before drafting when the issue alleges any of: a failing test, a broken import, a missing method, an incorrect numeric output, a regression, or a "this used to work" claim. Capture the output verbatim and cite it in the plan's Reproduction Evidence section.
# Test failures: run the specific failing case, not the suite
uv run pytest <repo>/tests/path/to/test_module.py::TestClass::test_case -xvs 2>&1 | tail -40
# Import / module breakage: try the import directly
cd <repo> && uv run python -c "from <module.path> import <name>; print(<name>)"
# Missing method / attribute: instantiate and call
cd <repo> && uv run python -c "from <module> import Cls; Cls().<method>()"
# Numeric / output regression: run the calc and compare against issue's claimed value
cd <repo> && uv run python -m <module>.<entrypoint> <args>
Rationale (empirical RED data, 2026-05-06 session): of 6 plans drafted from issue-body + grep alone, 4 (67%) diverged from reality. Concrete drift cases:
digitalmodel#559 — issue described > → >= as a one-character fix. The fixture was genuinely not diagonally dominant for rotational rows 3/4; >= only shifts the failure site, doesn't eliminate it.worldenergydata#278 — issue alleged 4 broken __init__.py files in modules/*. Reality: 3 of 4 were healthy; the actual breakage was an absolute-path symlink in a different file the issue never named.worldenergydata#270 — already fixed in a commit weeks before the plan was drafted; reproduction would have caught this in 30 seconds.Required output in the plan: under Resource Intelligence Summary > Evidence, a Reproduction proofs sub-block citing the exact command, timestamp, and tail of output. The reproduction is the load-bearing artifact — without it, the plan is a guess about what the issue body claims, not a fix for what is actually broken.
Skip-allowed only when: issue is documentation-only, governance-only (e.g., index updates, README typos), or otherwise has no runtime claim to verify. Mark Reproduction proofs: N/A — <reason> so reviewers know the skip was intentional, not forgotten.
Reviewers must reject any plan whose Resource Intelligence Summary describes a runtime failure but has no reproduction citation. This is a MAJOR finding by default.
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.
Required header fields (per .claude/rules/wiki-sibling-routing.md Layer 3, #2778):
Client: — required for any plan touching wiki content (llm-wiki or llm-wiki-<client> repos). Use N/A for plans that don't touch wiki content (most operational, infra, or pure-workspace-hub work).Project: — optional. Populate when the plan scopes to a single project under a client (e.g., Project: sirocco for B1528 SIROCCO work under client acma). Consumed by check-wiki-sibling-frontmatter.py Rule E to validate project: frontmatter on staged content.Lane: — required. Set the plan-time AI provider lane (lane:codex for heavy compute — engineering calcs, long-running analysis, large data crunching, bulk sweeps; lane:claude for orchestration, review, planning, light edits) per the "Compute lane assignment" rule in .claude/memory/agents.md, and verify the issue carries exactly one matching lane: label (#3029). If planning changed the scope class, relabel the issue. Note: a human/dispatch-set ai: label outranks lane in routing — if one is present and now wrong, reconcile it explicitly.When Client: is a real client slug (not N/A), verify it matches a short_name in config/client-wikis.yml. When Project: is set, verify it's enumerated in that client's projects: list (or the list is absent/empty — warn-only forward-compat).
For engineering-calculation or parametric chart plans, also run the checks in references/engineering-parametric-chart-plan-review.md: freeze local vs reported coordinate frames before formulas, explicitly classify off-grid UI defaults versus engineering sweep rows, ensure representative chart traces do not hide requested sweep coverage, and require tests for frame transforms/sign conventions.
When review finds unresolved domain decisions, use references/domain-decision-blocked-plan-review.md to keep the plan blocked-draft/needs-decision, post a concise decision checklist, and avoid prematurely applying approval-ready labels.
For repo/data location contract plans, also run the checks in references/repo-location-contract-planning.md: keep repo checkout placement separate from raw/bulk/private/public data placement, prefer adjacent sibling checkouts under /mnt/local-analysis/<repo> with workspace-hub as the control plane, enumerate the live checkout set empirically, and represent any moves as future reviewable transactions rather than performing them during planning.
For per-machine repo placement plans, also apply references/per-machine-repo-placement-outcome-contract.md: the first machine issue in a sequence must leave a reusable pattern for consistent tier-1 repo folder structure, primary/reference checkout decisions, and repo harness/file ecosystem handling through one repo-tracked authority rather than creating machine-specific duplicate conventions.
For plans being revised after a source/provenance ambiguity is resolved, especially when licensed or private off-repo material is involved, apply references/source-provenance-plan-revision.md: patch the canonical plan narrowly, state the source/license boundary, add fail-closed citation/leakage tests, run focused re-review, and stop at user approval rather than self-approving.
Update the index table in docs/plans/README.md with a new row.
When a user asks for a feature/issue that spans multiple architectural layers (for example data at rest, execution/compute, and report/publication surfaces), prefer a parent issue plus dispatchable child issues/plans instead of one overloaded plan.
Required shape:
Session-specific examples and checklists: references/layered-architecture-issue-planning.md.
For GitHub issue portfolios that must flow from data layer → execution layer → result/output layer, use references/data-execution-results-kanban.md: inventory issues by architectural lane, create a repo-tracked Kanban/report artifact, delegate read-only planning/review waves by provider strengths, verify delegate claims in the orchestrator checkout, and stop at an explicit approval checkpoint before implementation.
For sequential issue-tree planning where downstream plans depend on revised upstream architecture/boundary plans, use references/focused-reqa-before-downstream-planning.md: run focused re-QA against the exact revised local upstream artifacts before drafting downstream issues, post concise GitHub comments for MAJOR results with --body-file, keep labels conservative, and block downstream drafting until upstream MAJOR findings are patched or explicitly waived.
Execution discipline for delegated agents:
docs/plans/README.md index rowdraft 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.Route the plan to 2+ AI providers for review. Each gives: APPROVE | MINOR | MAJOR. If any MAJOR: revise and re-review.
When MAJOR findings identify unresolved user/domain decisions rather than pure plan-writing defects, do not force the plan into status:plan-review or present it as approval-ready. Patch the plan/header/index to a conservative blocked-draft or needs-decision state, add a short GitHub checkpoint comment listing the exact decisions required, and keep implementation stopped. Only after the user supplies the decisions should you revise the plan, rerun adversarial review, and then surface it for approval.
For batch review closeout where a preserved task list says to move labels but fresh reviews return MAJOR, follow references/batch-major-review-closeout.md: post blocking summaries, keep labels conservative, update todos to reflect that status:plan-review is intentionally withheld, and patch only issue-scoped README rows to avoid collateral drift.
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:
## 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.
git rev-parse HEAD
git ls-remote origin refs/heads/main | awk '{print $1}'
lane: label consistent with the plan's Lane: header field (#3029)gh issue edit NNN --remove-label "status:needs-plan" --add-label "status:plan-review"
Adjust the removed lower-status label if the issue uses a different earlier gate label.Operational pitfall: do not update docs/plans/README.md to plan-review and stop there. The live GitHub label must also be reconciled, but only after pushed artifact evidence exists.
The user (never the implementing agent) approves the plan:
gh issue edit NNN --remove-label "status:plan-review" --add-label "status:plan-approved".planning/plan-approved/NNN.mdThe 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.
When plan status signals disagree across artifacts, use this precedence:
status:* label is authoritative for live issue state.planning/plan-approved/NNN.md marker is authoritative local evidence that approval happeneddocs/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 realityPractical rules:
status:plan-review and status:plan-approved appear, treat status:plan-approved as authoritative and clean up the stale lower-status label when possible.status:plan-approved), do not downgrade it just to match a stale local plan file or README row.When issue state drifts across artifacts, use this precedence order for operational decisions:
status:plan-approved label on the GitHub issue.planning/plan-approved/NNN.md local approval markerstatus:plan-review label on the GitHub issuedocs/plans/README.mdRules:
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.plan-review.Important operational rule learned in live use:
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.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:* labels, treat the latest/most-advanced state as authoritative. In practice: status:plan-approved outranks status:plan-review.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..planning/plan-approved/<issue>.md as the canonical local proof that approval happened.When the user asks which plans are still pending cross-provider review, audit all five signals before answering:
docs/plans/README.md plan row/statusdocs/plans/ file search for issue-<NNN>-*.md (catches orphaned/unindexed local plans)gh issue view/list.planning/plan-approved/<issue>.mdscripts/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.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.*-subagent.md, *-hermes.md, or *-final.md do not by themselves prove Codex/Gemini review happened.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.status:plan-review but no canonical docs/plans/ artifact exists yet)docs/plans/README.md and/or the local plan header still claim plan-review / adversarial-reviewed)docs/plans/README.md from plan-review/adversarial-reviewed to completedcompleteddocs/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.docs/plans/ and add the docs/plans/README.md row with local status draft.status:plan-review without a canonical plan artifact.status:plan-review label while the plan is still only a local draft.plan-review and restore/apply the live status:plan-review label.claude -p review prompt is often more reliable than embedding the full plan text inline. If a long inline Claude 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.## 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 updateclaude -p review prompt is often more reliable than embedding the full plan text inline. If a long inline Claude 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.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.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:
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.
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:
status:plan-approved, remove status:plan-approved and add status:plan-review..planning/plan-approved/<issue>.md but the live issue is now back in status:plan-review, remove the stale marker.docs/plans/README.md to match the rolled-back live state (plan-review rather than plan-approved).Practical rules:
status:plan-review.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 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:
MAJOR and link the new review artifacts.status:plan-approved to status:plan-review..planning/plan-approved/NNN.md, remove it so local state no longer implies approval.docs/plans/README.md row from plan-approved to plan-review.Operational rule:
status:plan-approved just because it was previously approved if the newest adversarial review says it is not approval-ready.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.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:
status:* labels.planning/plan-approved/<issue>.md local markerdocs/plans/README.md row statusscripts/review/results/Remediation rules:
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.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.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.docs/plans/README.md to the effective live state once labels/markers are corrected.Practical sequencing:
docs/plans/README.mdThis keeps the plan queue operationally trustworthy after large review waves instead of letting stale plan-approved signals linger.
If a plan already carries status:plan-approved but fresh Codex/Gemini review returns MAJOR or otherwise says "not ready for user approval":
status:* labels.planning/plan-approved/<issue>.md markerdocs/plans/README.md row statusscripts/review/results/ artifactsstatus:plan-approved and move it back to status:plan-review.status:plan-approved without a marker, remove the stale approval label and post a cleanup note; do not silently leave misleading approval state behind.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:
Only after status:plan-approved label AND .planning/plan-approved/NNN.md marker exist:
single-lane for tight/shared work, parallel-worktree for approved disjoint write surfaces, or parallel-readonly for verification-only lanes.parallel-worktree, orchestrator verifies worker outputs directly and serializes commit/push/closeout.status:plan-review — do NOT implementstatus:plan-approvedIssues with cat:engineering* or cat:data-pipeline labels require the full
engineering-issue-workflow skill (adds cross-review after implementation).
.claude/hooks/plan-approval-gate.sh blocks writes without approval markerscripts/enforcement/require-plan-approval.sh --strict blocks commits without approval.planning/, docs/plans/, docs/governance/, docs/reports/, docs/standards/,
and the four top-level agent adapter markdown files
SKIP_PLAN_APPROVAL_GATE=1 # for Claude Code hook
FORCE_PLAN_GATE=1 git commit # for pre-commit hook
All bypasses are logged.
docs/plans/README.mddocs/plans/_template-issue-plan.mddocs/standards/HARD-STOP-POLICY.md.claude/skills/coordination/engineering-issue-workflow/SKILL.md