Canonical GitHub issue planning route — issue intake, strengthened resource intelligence, repo-tracked plan artifact, adversarial review, GitHub progress posting, future-issue capture, explicit approval gate before execution, machine-dispatch readiness checks, and execution-ready delegation packaging for Claude agent teams.
version
1.3.1
author
Hermes Agent
category
coordination
triggers
["When user says \"gh work planning\"","When planning Telegram/Hermes machine dispatch readiness; see references/telegram-hermes-machine-dispatch-readiness.md","When planning a GitHub issue before implementation","When an issue must move into plan-review before code changes"]
This is the canonical planning route for GitHub issue work.
Use it whenever work starts from a GitHub issue and must follow:
Issue -> Plan -> User Approval -> Implement.
Route summary
The output of this route is one artifact: an approved plan that downstream execution can follow without guessing.
GitHub posting rule
As work progresses, post meaningful GitHub updates at each major step.
Do not wait until the end to communicate progress.
Minimum posting cadence during planning:
after Step 1: intake / classification note
after Step 2: resource-intelligence findings note
after Step 3: draft-plan ready note if useful internally, or proceed directly into review
after Step 4: review result summary
after Step 5: final plan comment + status label update
Posts should be concise, factual, and cumulative rather than noisy.
If multiple sub-actions happen quickly, combine them into one structured update.
Future-issue capture rule
During planning, if you discover adjacent work that should not be silently absorbed into the current issue, capture it as a future GitHub issue.
Post-batch future-issue extraction routine
After a planning-only batch or overnight plan-review wave, do not leave deferred scope buried inside plan files or review artifacts.
Use this routine:
Read the batch results report and the newly created/refreshed plan files.
Search specifically for explicit deferred-scope markers such as:
Open:
follow-up issue
future issue
out of scope
can be added incrementally
Filter to items that are genuinely separate from the current bounded issue, not just implementation notes.
Search GitHub for duplicates before creating anything.
Create concrete follow-up issues immediately for the strongest deferred items, with bodies that explain:
why the work was intentionally kept out of the current issue
which issue/plan surfaced it
what dependency or sequencing relationship exists
Record the created issue numbers in the session handoff / results summary so the next execution wave does not silently absorb the deferred work.
This is especially useful after overnight Claude planning runs, where multiple plans may each leave one or two explicit "Open" decisions. Converting the strongest ones into real GitHub issues preserves scope discipline and gives tomorrow's execution wave a cleaner boundary.
Claude agent-team prompt packaging rule
When the work is large enough to benefit from multiple agents or multiple terminals, use Claude to package the work into self-contained prompts for agent team(s).
Use this especially when:
the plan naturally splits into non-overlapping workstreams
agent teams need explicit file ownership and zero git contention
overnight or unattended execution is desired
a licensed or external machine must execute work without Hermes context
Prompt packages should be:
self-contained
explicit about scope boundaries
explicit about allowed write paths and forbidden paths
explicit about tests, validation, and GitHub posting expectations
explicit about commit/close or comment-only behavior
Preferred supporting skills for this packaging:
overnight-parallel-agent-prompts
licensed-machine-prompt-orchestration
Agent-team decision gate
Before splitting work across Claude agent teams, explicitly decide yes/no on delegation.
Delegate only when all are true:
work naturally splits into non-overlapping streams
each stream can be given explicit file ownership
dependencies between streams are known and minimal
the orchestrator can keep GitHub status and final integration coherent
Do not delegate when:
streams would touch the same files or branches concurrently
ownership boundaries cannot be made explicit
the work is small enough that orchestration overhead dominates
a critical unknown should be resolved first in the main planning thread
If delegation is chosen, the plan must include a workstream split contract, delegated prompt pack, GitHub authority split, and execution-ready handoff per stream.
Zero git contention rule
Zero git contention is a hard rule.
no two delegated teams may write the same file
no two delegated teams may own the same branch or worktree
shared-file integration stays with the orchestrator unless one stream is explicitly designated as the sole owner
if clean ownership cannot be enforced, do not split the work that way
Prefer additive boundaries, isolated worktrees, and orchestrator-controlled final merges.
GitHub authority split
Default authority split:
orchestrator owns issue intake, planning comments, labels, approval-state transitions, future-issue creation, final synthesis, and closeout decisions
delegated teams own execution evidence inside their assigned stream packet and may draft suggested GitHub text only if requested
Delegated teams should not independently change issue-wide status labels, redefine scope, or close the parent issue unless the orchestrator explicitly grants that authority.
Decision checkpoint rule
At the end of each major planning step, explicitly choose one:
continue current issue
create future issue
stop for user decision
stop for blocker
Do not carry ambiguity across steps.
Create a future issue when the discovered work is:
materially out of scope
a follow-up optimization rather than required for current acceptance
blocked by missing data/decisions
a separate bug/risk/remediation item
useful institutional knowledge that should be tracked rather than buried in comments
When creating a future issue:
give it a precise title
include context, impact, and why it was split out
link back to the current issue
reference the new issue number in the current issue comment and in the plan's Risks/Open Questions or Follow-ups section
The 5 steps
STEP 1: Issue Intake — read, classify, announce
STEP 2: Resource Intelligence — search all knowledge sources, map artifact locations, identify gaps and follow-ups
STEP 3: Draft the Plan — pseudocode, file map, tests, acceptance criteria, follow-up issues
STEP 4: Adversarial Review — Claude + Codex + Gemini review the plan
STEP 5: Hard Stop — post to GitHub, label, wait for user approval
STEP 1 — Issue intake
Read the full issue body: scope, acceptance criteria, references, labels.
Classify complexity:
T1: trivial change, abbreviated plan still required
T2: standard multi-file work with tests
T3: complex or architectural change
Announce that planning is underway before any implementation starts.
Post a short GitHub comment that planning has started, with complexity and any immediate scope notes.
Blocker protocol
If planning is blocked, post a GitHub update immediately with:
blocker summary
impact on scope, plan quality, or approval readiness
missing dependency/decision/input
whether a future issue should be created
If the blocker is substantial and not resolvable inside the current planning cycle, create a future issue or dependency-tracking issue instead of burying it in notes.
Tool-budget / interruption checkpoint rule
If planning is interrupted by context/tool-call limits, provider timeout, or a forced stop before Step 5, leave a restartable checkpoint instead of a vague status note.
The checkpoint must state:
current task-list status by step (intake, draft, review, post, or equivalent)
exact issue URL/number and live status/labels last observed
evidence already gathered, with paths/commands/issue comments inspected
artifacts confirmed absent or present, especially docs/plans/*issue-NNN* and scripts/review/results/*NNN*
dirty-worktree caveat if unrelated existing changes were present before the planning work
the next 3-7 concrete files/commands to inspect when resuming
the gate state: whether implementation is still blocked and why
Do not imply the plan is approval-ready unless the canonical plan exists and review artifacts are complete. A checkpoint is a handoff, not a substitute for Step 3/4/5.
STEP 2 — Resource intelligence
Read-only only. No code written.
Search in this order, and strengthen the search until uncertainty is acceptably low.
Do not stop at the first plausible match.
Proof-first rule
Every major claim from resource intelligence should be backed by explicit proof, such as:
exact file path
issue or PR number
commit hash
doc path
standards/source reference
command/query result
Do not rely on vague impressions like "seems to exist" or "probably handled elsewhere."
live-state diagnosis on the current machine or host
repo-owned code/config remediation
Do not assume a repo patch is the right answer just because the symptom appears in repo logs.
Migration-aware architecture planning
For architecture plans that span data, execution, and report layers, treat current paths as evidence, not authority. If the user or evidence indicates data was moved piecemeal, current layout is a migration state until inventoried.
Planning behavior:
keep the broad architecture issue as an umbrella / cross-layer lifecycle contract when it already exists
split data, execution, and report concerns into child issues with separate approval surfaces
require inventory/taxonomy evidence before final approval of data-boundary decisions
allow execution/report issues to proceed only through explicit interface contracts while data residency is unresolved
do not create duplicate umbrellas; post the sequencing recommendation to the existing parent issue
Use references/migration-aware-layer-architecture-planning.md for data inventory classes, provisional contract fields, fail-closed handling, and GitHub comment shape.
Scheduled-report route-state rule
For weekly cadence reports, OSS watchlists, roadmap boards, or any generated artifact that routes findings to GitHub issues, plan route-state safety as part of the normal generation path — not only as an after-the-fact validator.
Planning must inspect and name every routing source:
committed route-map data files
hardcoded fallback/default route constants in generator scripts
helper functions that apply route-map values to rendered rows
A plan is weak if it only adds a validator that detects closed issue targets while normal offline generation can still render those closed targets. Require TDD that proves rendered output falls back to an open roadmap/umbrella anchor, or another explicitly verified open child issue, when a mapped child issue has closed.
Session-specific detail and test-shape checklist: references/route-state-validation-for-weekly-cadence.md.
Required planning behavior for these issues:
Capture a reviewable live-state classification artifact first (for example: installed vs not-installed, firing vs not-firing, failing before startup vs failing after startup).
State which branch is operational-only and which branch is repo-fixable.
If the live cause is operational drift (for example missing crontab installation), do not pretend a repo-code patch solves it. Record the classification explicitly and either stop at operator guidance or create a follow-up ops issue.
Only draft implementation files/tests for the repo-owned failure branch that has actually been evidenced.
Keep acceptance criteria aligned to the chosen branch; avoid mixing "diagnose the live host" and "ship a code fix" as if both must always happen in one issue.
a) Repo code
Check whether the feature/fix already exists partially or fully.
Record exact files, modules, functions, tests, configs, scripts, and docs found.
Search both direct names and adjacent synonyms/older terminology.
b) Existing issue/PR history
Check related GitHub issues, issue comments, linked PRs, and commit references.
Look for prior attempts, rejected approaches, known constraints, and already-landed partial work.
c) Standards / registries
Check any standards registries or reference ledgers relevant to the issue.
Record gap vs done status when standards are cited.
Identify whether the issue is actually blocked by a missing standard/source artifact.
d) Primary knowledge base / wiki
Search the repo knowledge base or wiki index before broader guessing.
Record pages/entities consulted and any contradictions vs current repo reality.
e) Local docs and document index
Read docs/ and any indexed local references relevant to the issue.
Check for prior plans, architecture notes, design decisions, validation reports, and policy docs.
f) Session recall
Use session search if similar work may have been done before.
Extract prior decisions, pitfalls, and previous issue numbers when applicable.
g) External or upstream source check when needed
If the issue depends on an external API, package, standard, vendor tool, or upstream repo behavior, verify that dependency instead of guessing.
Capture version-specific or source-specific constraints.
h) Artifact location planning
Decide where every artifact will live before drafting:
plan file
tests
implementation files
review artifacts
docs/wiki updates
planning index updates
future follow-up issue references
Canonical plan artifact location:
docs/plans/YYYY-MM-DD-issue-NNN-<slug>.md
Do not use .hermes/plans/ for the canonical GitHub issue plan.
i) Operational-vs-repo fault isolation for cron/scheduler issues
For issues about cron jobs, scheduled tasks, wrappers, health monitors, or other automation that depends on live machine state, do not assume the fix is in repo code.
Before drafting an implementation-heavy plan:
capture at least one reviewable live-state probe artifact when possible (for example: crontab -l, generated scheduler dry-run output, current log directory contents, current health JSON/log snapshot)
save the probe in a durable repo-visible artifact such as docs/reports/YYYY-MM-DD-issue-NNN-<slug>-probe.md when the result materially changes the decision tree
explicitly separate these branches:
not installed / not scheduled
installed but not firing yet / operational drift
installed and failing after launch
repo-owned command/config defect
if live evidence eliminates one branch, update the draft plan immediately rather than carrying stale hypothetical branches forward
if the live cause appears operational rather than repo-owned, the plan must say whether the correct outcome is:
diagnosis + operator guidance only
diagnosis + follow-up issue
bounded repo patch plus separate operational remediation
Important rule:
do not present a repo-code patch as the solution if the strongest evidence says the issue is host-state or installation drift
for mixed issues, make the stop condition explicit: exactly when do we stop at diagnosis, and exactly when do repo changes become in-scope?
Required Step 2 output schema
Before leaving Step 2, produce a structured intelligence summary with these sections:
Existing assets
code
tests
docs
configs/scripts
Related prior work
issues
PRs
commits
prior sessions
Constraints
standards
upstream/API/tooling
policy constraints
Gaps
Risks / unknowns
Scope split
in scope now
future issue candidates
Artifact map
Also capture negative findings when useful, for example:
no existing test found for X
no prior issue found for Y
no standards/source artifact found for Z
Resource intelligence strengthening checks
Before leaving Step 2, explicitly ask:
Did I inspect code, tests, docs, issue history, and prior session context?
Did I search for alternate names, legacy names, and neighboring modules?
Did I identify what already exists, what is missing, and what is uncertain?
Did I identify out-of-scope findings that deserve future issues?
Have repeated searches converged on the same likely implementation surface?
Implementation-surface confidence
Assign one confidence rating at the end of Step 2:
High: clear implementation surface, tests, and artifact locations are known
Medium: likely implementation surface is known, but some uncertainty remains
Low: implementation surface is unclear, conflicting, or blocked
Low-confidence hard stop
If confidence is Low:
do not draft a detailed plan as if certainty exists
continue intelligence work, or
stop and post a blocker update / request decision
GitHub update template for Step 2
Post a concise GitHub update using this structure:
Existing: ...
Missing: ...
Risks/unknowns: ...
Likely implementation surface: ...
Future issues likely: yes/no
Confidence: High/Medium/Low
STEP 3 — Draft the plan
Decision checkpoint after Step 2:
continue drafting
create future issue(s)
package work as Claude prompts for agent team(s)
stop for blocker/user decision
If agent-team delegation is being considered, decide it here before writing execution handoff materials.
Step 3 recommendations now applied
Draft the plan by consuming the Step 2 output schema directly.
Do not rewrite the plan from memory or from a vague summary.
Each major section of the plan should trace back to Step 2 findings and explicit proof.
Use the repo issue-plan template if present and fill every section.
Minimum sections:
Resource Intelligence Summary
Traceability to Step 2 Findings
Artifact Map
Deliverable
Scope Boundaries
Pseudocode
Files to Change
TDD Test List
Acceptance Criteria
Risks and Open Questions
Follow-up Issues
Review Readiness Notes
Complexity
Plan requirements:
pseudocode for each meaningful new function/module
exact likely file paths
explicit tests before implementation
acceptance criteria that are verifiable
explicit separation between current-scope work and future issues
each major plan claim should trace back to Step 2 findings or explicit evidence
explicit scope boundaries: what is included now vs intentionally deferred
follow-up issues should be listed with status: created now / candidate only / blocked
Workstream split contract
When Step 3 chooses delegated execution, add one workstream contract per stream.
Each contract must contain:
Stream name
Objective
Owning issue or sub-issue
Allowed paths
Forbidden paths
Dependency on other stream(s) or none
Deliverable
Keep contracts short and operational.
If any field is vague, the split is not ready.
Delegated prompt pack structure
When producing Claude agent-team materials, create a prompt pack with:
master-plan.md — orchestrator view of the full plan, stream map, dependency order, GitHub authority split, and integration notes
stream-<id>.md per stream — self-contained execution prompt bound to that stream's contract
execution-readme.md — operator instructions for launching teams, branch/worktree mapping, validation order, and return protocol
The prompt pack should live near the canonical plan or in a clearly referenced execution-support directory, and the plan must record the exact paths.
Keep the naming and structure stable so execution sees one prompt pack vocabulary: master-plan.md, stream-<id>.md, and execution-readme.md.
Execution-ready handoff contract per stream
Every delegated stream prompt must be execution-ready, not advisory.
Include:
stream objective and success condition
exact issue context and acceptance criteria slice
allowed paths and forbidden paths
dependency status and what inputs are assumed ready
exact tests/validation commands or required checks
expected deliverable artifact(s)
GitHub authority limits
return format for completion, blockers, and future-issue recommendations
Acceptance-criteria quality rule
Acceptance criteria should be:
measurable
testable
specific to the issue
tied to proof expected during execution
Avoid vague criteria like "works correctly" or "looks good."
Scope discipline rule
Do not silently expand the plan to absorb adjacent work.
Only include adjacent work when it is required for correctness, safety, or to satisfy the stated acceptance criteria.
All other adjacent work must become future issues or explicit follow-ups.
Review-readiness rule
Before sending the plan for adversarial review, confirm:
the plan is internally consistent
the proposed files and tests match the implementation surface discovered in Step 2
every acceptance criterion has a plausible verification path
future issues are clearly separated from current deliverables
blockers and assumptions are visible, not hidden
If future issues were discovered, either create them now or mark them as issue candidates with exact proposed titles and rationale.
Strategy / architecture issue packaging rule
For planning-only strategy, architecture, or governance issues, reviewers are highly sensitive to both underscoping and packaging drift.
Operational rules learned from live review waves:
Do not use a vague single "report" artifact when the issue explicitly calls for multiple durable outputs (for example: standing contract, reusable battery/spec, gap analysis, follow-up issue drafts, consumer inventory). Name each required artifact explicitly in Artifact Map, Files to Change, and Acceptance Criteria.
Avoid adding auxiliary file edits that are not clearly required by the issue (for example updating unrelated dependency maps or indexes). Reviewers treat these as scope creep.
If an issue requires conditional follow-up issues, the plan must include a concrete artifact for them (draft pack, issue stubs, or explicit creation step). Saying "recommend follow-ups in the report" is usually judged insufficient.
If a plan claims something is reusable/standing, place it in a durable standards/config surface rather than only in a date-stamped report.
For repo-boundary or migration decisions, include a first-class consumer/backlink/path inventory artifact before recommending movement. Reviewers will reject high-level recommendations that are not grounded in concrete dependency evidence.
For checker/CI/enforcement artifacts, do not bundle rollout prematurely if exception rules or scope boundaries are still unresolved. Separate "define contract" from "enforce contract" unless the issue explicitly requires both.
If repeated review rounds still return MAJOR after tightening, keep the issue in draft/review-only state and post a GitHub status comment summarizing the remaining blockers rather than prematurely moving it to status:plan-review.
Review-state hygiene learned from live reruns:
If a newer rerun wave exists but one or more provider artifacts are empty, UNAVAILABLE, or wrapper-failed, do not describe older artifacts as simply the "latest" state. Distinguish clearly between:
freshest wave status (including provider failures)
last valid artifact per provider, if different
whether the review gate is still unsatisfied because the newest wave did not produce the required valid artifacts
Re-check .planning/plan-approved/<issue>.md before claiming approval evidence is absent. If a marker exists with weak/non-auditable provenance (for example Approval source: current Hermes chat instruction), treat it as governance drift / likely self-approval evidence, remove it for open draft issues, and note the cleanup explicitly in the plan summary or GitHub status comment.
For CI-hardening plans that change workflow gates, include both:
isolated red/green commands for the narrow source/test fixes, and
at least one workflow-shaped local command that matches the CI gate closely enough to expose the likely next blocker (for example coverage thresholds / markers), so the plan does not overclaim "CI parity" from isolated tests alone.
Planning pre-review checklist
Before adversarial review, confirm all are true:
deliverable is clear in one sentence
likely files to change are listed explicitly
tests are named before implementation
acceptance criteria are measurable
acceptance criteria have plausible verification paths
blockers/unknowns are stated plainly
follow-up work is separated from current scope
no adjacent work has been silently absorbed without justification
Step 2 findings are reflected accurately in the plan
future issue handling is explicit: created, candidate, or none
delegated streams, if any, have non-overlapping ownership and execution-ready handoff packets
GitHub update template for Step 3
Post a concise GitHub update using this structure:
Planned deliverable: ...
Likely files/tests: ...
Scope boundaries: ...
Future issues: created / candidate / none
Review readiness: yes/no
STEP 4 — Adversarial plan review
Run three independent plan reviews in parallel before the user sees the plan.
This is a formal quality gate, not a casual opinion check.
Review package completeness check
Before dispatching reviewers, ensure the review package includes:
issue body
Step 2 structured intelligence summary
draft plan
acceptance criteria
follow-up issues or candidates
blockers, assumptions, and scope boundaries
If the package is incomplete, fix the package before review instead of sending a weak review prompt.
Practical packaging rule for local draft plans
When the plan is still only in local/uncommitted repo state, do not rely on the reviewer being able to fetch it from GitHub or rediscover it from the filesystem.
Use this order of preference:
Provide the full revised plan text inline / via stdin bundle in the review prompt
If needed, include the minimal supporting excerpts inline too
Only rely on path-based retrieval when the artifact is definitely readable from the review environment
Why:
non-interactive provider runs can fail to read local drafts because of sandbox, trust, or repo-state limitations
a reviewer may return a misleading MAJOR caused by retrieval failure rather than by the plan itself
path-only prompts are best for stable readable files, not for fresh local draft artifacts
Operational rule:
if a review artifact is being refreshed, write the new review to a temp file first and only replace the canonical artifact after the run succeeds; this avoids accidentally truncating a previously good artifact with a failed rerun
if a reviewer returns MAJOR primarily because retrieval adequacy was insufficient, treat that as a packaging failure first; fix the package, rerun review, and only then treat remaining findings as substantive plan criticism
Blind-first rule
Each reviewer should critique independently before seeing any other reviewer conclusions.
Do not let reviewers anchor on each other.
Standard reviewer prompt contract
Every reviewer should evaluate the same dimensions:
correctness
completeness
feasibility
TDD adequacy
scope discipline
risk handling
future-issue separation
verification readiness
Required reviewer output schema
Each reviewer should return:
Verdict: APPROVE | MINOR | MAJOR
Strengths
Gaps
Risks
Missing tests
Scope creep concerns
Weakest assumption and what breaks if it is false
Most likely implementation failure mode
Most likely test gap
Future issues suggested
Review confidence
Verdict normalization
Use these meanings consistently:
APPROVE: no blocking issue remains
MINOR: safe to proceed after minor or optional corrections
MAJOR: the plan cannot proceed without revision
Mandatory synthesis step
After all reviews return, produce one authoritative synthesis containing:
consensus findings
disagreements
accepted changes
rejected suggestions with rationale
residual risk level: Low | Medium | High
user-attention-required decisions, if any
execution handoff notes
ready_for_approval: yes/no
Disagreement handling
If reviewers disagree materially:
do not average the disagreement away
resolve it using Step 2 evidence, Step 3 traceability, and explicit reasoning
revise and re-review if the disagreement affects correctness, scope, tests, or feasibility
Diagnosis-vs-remediation branch rule
When an issue can resolve in more than one fundamentally different way — especially:
operational/environment diagnosis only
repo-owned code/config remediation
make that branch decision explicit in the plan.
Required pattern:
identify the live-state classification artifact you will use to choose the branch
state the stop condition for the diagnosis-only path
state the stop condition for the repo-remediation path
avoid mixing both as if implementation is guaranteed
if a diagnosis-only outcome is plausible, say explicitly that the issue may end with operator guidance and no repo code changes
Good examples:
installed vs not-installed cron entry
host drift vs repo defect
external service outage vs local integration bug
This prevents approval-ready plans from smuggling in speculative code changes before the branch is actually chosen.
Review-iteration stop rule
When a plan keeps returning fresh MAJOR findings across multiple re-review passes, do not iterate indefinitely.
After 2-3 substantive tightening passes, explicitly choose one:
continue because the remaining blocker is shrinking and clearly actionable
park the issue in draft with a concise blocker summary
switch to planning a sibling/follow-up issue that may unblock faster
split the issue into a narrower parent/child decomposition when the blockers are really decomposition problems rather than wording problems
Operational guidance:
treat repeated MAJOR findings with shrinking but persistent scope as a signal of diminishing returns
post a GitHub update summarizing the remaining blocker instead of silently grinding through more revisions
do not move the issue to status:plan-review just because the plan is "close"
if you switch away, record why and what exact blocker remains
if reviewers keep objecting that one issue mixes too many concerns, stop rewriting the same monolith and decompose it into child issues by artifact/responsibility type
Practical decomposition heuristic for architecture/governance issues:
split canonical contract / policy work from inventory / evidence gathering work
split fixture corpus / examples / baselines from runner / schema / interface design
split normalization of existing entry surfaces from new contract language
split follow-up issue creation / dedup automation from the main policy issue if reviewers treat it as a separate risky subsystem
keep the original broad issue as a parent/umbrella after the split; do not keep trying to force the parent through approval as one approval unit once review has shown the scopes are separable
Typical signs the split is overdue:
repeated MAJOR findings say the issue is "too broad", "too large for T2", or "mixes contract definition with normalization/automation"
reviewers accept the high-level direction but block on one or two attached subsystems (for example runner semantics, issue creation policy, or entrypoint normalization)
each rewrite fixes wording but not the structural objection
Decomposition trigger after repeated MAJOR reviews
Use this pattern when the review waves keep converging on the same structural complaint, for example:
"scope too broad for one T2/T3 plan"
"this includes multiple risky subsystems"
"runner/schema/policy/inventory should be separate issues"
"parent umbrella should stay steering-only"
Required response:
stop trying to force the whole scope through one approval gate
identify the independent workstreams causing the blocking findings
create child issues for those workstreams immediately
keep the original issue as a parent/umbrella unless the whole issue should be replaced
comment on the parent issue with:
why the decomposition happened
the child issue links
recommended execution / approval order
narrow the parent issue's role to steering, sequencing, or final synthesis if appropriate
Practical rule:
if repeated MAJOR findings are mostly about decomposition, boundaries, or "too much in one issue," do not spend another full revision cycle polishing prose inside the monolith. Split it.
once split, seek approval on the narrowest child issue first, especially the one that establishes the canonical contract or evidence base for the others.
Monolith-to-child-issue decomposition pattern
Use this when repeated adversarial review converges on the same meta-problem: the issue is too broad, mixes multiple subsystems, or keeps failing because approval is being sought for one large plan instead of several narrower ones.
Trigger signals:
2+ review rounds still return MAJOR
multiple providers independently call out scope bloat, packaging sprawl, or unresolved architectural decomposition
one issue is trying to define policy + fixtures + runner semantics + inventory + automation behavior all at once
revisions improve wording but do not eliminate the same structural blocker
Required response:
Stop trying to force the original issue through approval as one monolith.
Identify the natural child workstreams and write them as separate GitHub issues with bounded deliverables.
Recast the original issue as a parent/umbrella that links the child issues and owns only steering/synthesis.
Comment on the parent issue explaining why decomposition was necessary and in what order the child issues should be reviewed.
Prefer approving the narrowest contract/evidence issues first, then the dependent execution/policy issues.
Practical rule:
If the repeated blocker is decomposition itself, further prose-only tightening of the same parent plan is usually wasteful. Split the work instead of polishing the monolith.
Monolithic-parent decomposition trigger
If cross-provider review repeatedly says the issue is too broad, mixes multiple subsystems, or bundles governance + inventory + automation + execution-policy concerns into one approval gate, stop rewriting the same parent plan.
Instead:
keep the parent issue as umbrella/steering only
split the blocked scope into 3-5 narrower child issues, each with one clear approval surface
create the child issues immediately so the decomposition is concrete, not just suggested
comment on the parent with the decomposition, rationale, and recommended review/approval order
move planning/review effort to the narrowest child issue first
Typical split axes:
contract/policy
evidence inventory / reconnaissance
fixture corpus / test assets
runner/schema/interface design
follow-up issue creation / governance automation
Use this when the blocker is structural decomposition, not missing wording. Repeatedly polishing a monolithic umbrella usually wastes review cycles and still returns MAJOR.
Monolith-plan split trigger (learned from repeated #2399-style review failures)
If fresh Codex/Gemini/Claude reviews keep converging on findings like:
"issue is too large for a single T2 governance/planning issue"
"too many artifacts / documentation sprawl"
"runner contract / automation / issue-creation logic is scope creep"
"ecosystem claim is broader than the actual evidence base"
"this should be split into smaller child issues or rescope to workspace-hub-only"
then stop trying to polish the monolith.
Do this instead:
classify the blocker as decomposition failure, not wording failure
rewrite the parent as a narrower umbrella / steering issue
create concrete child issues for the major concern clusters
if ecosystem-wide evidence is too thin, rescope the parent to the smaller proven domain (for example workspace-hub-only) and move broader claims into follow-up inventory issues
only resume plan-review on the narrower parent/children after the split is reflected in the issue structure
Heuristic:
if the latest review wave is still MAJOR after multiple rewrites and the blocker list keeps naming scope, packaging, automation, or missing ecosystem evidence rather than a few specific missing sections, the correct fix is almost always to split/rescope, not to keep editing the same plan.
No silent downgrade rule
If any reviewer returns MAJOR, do not silently downgrade that to MINOR without explicit written rationale tied to evidence.
Material-change re-review rule
If the plan changes materially after review, run Step 4 again.
Material changes include:
changed deliverable
changed file map
changed tests
changed acceptance criteria
changed scope boundary
changed external dependency assumption
Review artifact schema
When storing review artifacts, capture:
reviewer
timestamp
prompt version
verdict
structured findings
synthesis linkage
Decision gate
any MAJOR -> revise plan and re-run review
all APPROVE/MINOR and ready_for_approval=yes -> proceed to Step 5
GitHub update template for Step 4
Post a concise synthesis-first GitHub update using this structure:
Review status: complete / revision required
Verdict summary: ...
Accepted changes: ...
Major unresolved items: ...
Residual risk: Low/Medium/High
Future issues: created / candidate / none
Ready for approval gate: yes/no
Do not dump raw full reviewer text into the issue unless necessary.
Link or reference full review artifacts separately when needed.
STEP 5 — Hard stop and approval gate
This is the explicit stop line between planning and execution.
No implementation begins from this route until approval handling is complete.
Exact GitHub action order
Before waiting:
Save the plan file to docs/plans/...
Update the planning index if the repo uses one
Ensure any follow-up issues discovered during planning are either created or explicitly marked as candidates
Post the final plan comment to the GitHub issue
Post or include the Step 4 synthesis summary if not already present in the final plan comment
Add status:plan-review
Remove any stale status labels that conflict with plan-review state
Stop and wait for explicit user approval
Final GitHub plan comment should include
final deliverable summary
scope boundaries
likely files/tests
review synthesis summary
residual risk level
future issue links or candidates
ready_for_approval status
explicit request for approval / revision / rejection
Approval response normalization
Interpret user responses using this mapping:
APPROVE / GO / YES -> approve
REVISE / CHANGE / UPDATE -> revise
REJECT / NO-GO / STOP -> reject
BLOCKED / HOLD -> pause
If the response is ambiguous, do not start execution. Clarify first.
Label discipline
Expected planning labels:
status:plan-review
status:plan-approved
Approval handling:
on approve: remove status:plan-review, add status:plan-approved
on revise: keep or re-apply status:plan-review
on reject: remove planning-ready labels that imply approval
on pause/hold: leave the issue clearly not approved for execution
Revise flow
If the user requests revision:
post a GitHub acknowledgement of requested changes
update the plan
re-run Step 4 if the revision is material
re-post the updated final plan
keep the issue in status:plan-review
wait again for explicit approval
Reject flow
If the user rejects the plan:
post a GitHub acknowledgement of rejection
summarize the likely reason and unresolved decision if known
remove approval-implying labels
do not start execution
either stop or open an alternative-plan discussion / future issue
Pause / hold flow
If the user pauses or holds the plan:
post a GitHub note that execution is not authorized yet
preserve the current plan artifact
keep labels consistent with not-approved state
do not start execution until explicit approval arrives later
Batch-readiness rule
A plan is batch-ready only when:
the final plan artifact is saved
Step 4 synthesis is complete
follow-up issues are captured appropriately
status:plan-approved is present
no unresolved blocker or approval ambiguity remains
No issue in status:plan-review is eligible for execution.
Audit-report to overnight queue pattern
Use this pattern when a repo capability/readiness audit produces several GitHub follow-up issues that need to become overnight-ready work items.
Operational rules:
Treat the audit reports as Step 2 resource-intelligence evidence, but still re-read the issue bodies, canonical repo docs, manifests/configs, and related source files needed to draft each plan.
Batch related issues only when they share evidence but have separable implementation surfaces; each issue still needs its own canonical docs/plans/YYYY-MM-DD-issue-NNN-<slug>.md artifact and GitHub final plan comment.
Freeze source-of-truth decisions in the plan before review when multiple registries disagree (for example manifest vs source tree vs catalog vs CLI registry vs scheduler config). Reviewers should see the chosen authority for each artifact class, not an open-ended reconciliation exercise.
For capability/data/scheduler readiness issues, explicitly separate documentation/index reconciliation from runtime refresh execution. Do not authorize unbounded downloads, full refreshes, or long-running scheduler jobs unless the approved plan says so and prerequisite runtime readiness is proven.
When one issue owns a shared surface that another issue touches only by reference, state that ownership boundary in both plans so overnight workers do not race on the same file or semantic decision.
Use adversarial review to convert vague cleanup themes into frozen decisions, testable acceptance criteria, and bounded no-download smoke checks before moving issues to status:plan-review.
status:plan-review means the issue is ready for human approval, not overnight execution. Only move into long-running/overnight implementation batches after explicit user approval and status:plan-approved.
Approval-candidate audit rule
When asked whether there are issue plans to approve, do not rely on status:plan-review labels alone.
Audit all of these before saying a plan is approval-ready:
live GitHub issue state and labels (gh issue list/view)
canonical plan file under docs/plans/
the plan header/status line and Adversarial Review Summary
durable review artifacts under scripts/review/results/
whether any reviewer verdict is MAJOR, FAIL, UNAVAILABLE, or still pending
whether the plan itself says a fresh re-review is required
Operational pattern:
gh issue list --repo OWNER/REPO --state open --label 'status:plan-review' --json number,title,url,labels,updatedAt
find docs/plans -maxdepth 1 -type f -name '*issue-NNN-*' -o -name '*NNN*.md'
find scripts/review/results -maxdepth 1 -type f -name '*plan-NNN-*.md'
Classification:
approval candidate now: plan exists, review artifacts exist, latest valid verdicts are only APPROVE/MINOR, and the plan does not require another review pass.
approval-prep priority: high-value issue, but missing review artifacts, stale plan status, or a fresh re-review is required.
not approval-ready: any current or latest-valid MAJOR, FAIL, unresolved blocker, missing required provider evidence, or pending review slot.
If none are approval-ready, answer that directly and list the best approval-prep targets rather than presenting stale status:plan-review issues as ready.
Kanban-to-execution W0 reconciliation gate
When a generated Kanban board, roadmap, or five-hour swarm recommendation packet proposes execution windows, run a W0 live-state reconciliation before launching workers.
Do not treat generated board lanes as launch authority by themselves. Re-check live GitHub state, approval markers on origin/main, referenced worker branches/worktrees, and commits mentioned in issue comments. Classify each candidate as:
closeout candidate: already landed but still open/working
blocked/no-op candidate: prior worker found a dependency blocker and no active branch remains
board drift only: issue is closed or labels changed after board generation
executable candidate: still open, approved, not blocked, and not already landed
blocked/no-op candidate -> blocker conversion or plan revision, not relaunch
board drift only -> refresh board/exclude from active routing
executable candidate -> only then package a 5-hour execution prompt
Session-specific command pattern and report shape: see references/w0-kanban-live-state-reconciliation.md.
Post-approval implementation-state audit
When the user asks for the current blocker/status of an already-approved issue, do not stop at plan artifacts and labels.
Audit all of these before summarizing status:
live GitHub issue labels/state
local plan row in docs/plans/README.md
open PRs referencing the issue (gh pr list/view)
whether the planned implementation files actually exist on main
CI / check status on the implementation PR
Operational rules:
status:plan-approved does not mean the work is implemented or merge-ready.
If the issue comment claims implementation shipped but the planned files are missing on main, classify the state as implemented off-main / pending PR resolution, not complete.
If the local README row still says plan-review but the live issue is status:plan-approved and work moved into a PR, update the README row to reflect the newer live state.
If the implementation exists only on a branch/PR and checks are failing, the blocker is PR/CI failure, not plan revision.
For honest status reporting, explicitly separate:
plan state
implementation branch/PR state
merged-to-main state
This prevents stale local planning metadata from masking the real current blocker on approved issues.
Execution handoff package
When approval is granted, the handoff into execution should be explicit and include:
approved plan path
final deliverable summary
scope boundaries
acceptance criteria
residual risk level and residual risks to watch
future issue links
execution handoff notes from Step 4 synthesis
Claude-packaged prompt files for agent team(s), when execution is delegated or parallelized
When execution is delegated, the handoff must also include:
prompt pack paths: master-plan.md, stream prompt files, and execution-readme.md
one execution-ready handoff contract per stream
branch/worktree ownership per stream
dependency order and orchestrator integration checkpoint(s)
GitHub authority split for orchestrator vs delegated teams
explicit confirmation that zero git contention is enforced
If execution will be performed by agent teams, package the work into self-contained Claude-readable prompts before handoff.
Each prompt should define:
owned issue(s)
owned paths and forbidden paths
exact validation steps
GitHub posting expectations
future-issue capture expectations
The orchestrator remains accountable for the parent issue state even when execution is delegated.
GitHub update template for Step 5
Use a concise approval-gate update structure:
Plan status: awaiting approval / approved / revision requested / rejected / on hold
Plan artifact: ...
Residual risk: Low/Medium/High
Future issues: ...
Execution authorized: yes/no
Next action: await approval / revise / stop
Valid approval outcomes:
approve -> set status:plan-approved, then execution may begin
revise -> update plan and re-run review as needed
reject -> stop and discuss alternative approach
pause -> hold with no execution authorization
Required gate
No implementation starts until the issue is explicitly approved and labeled status:plan-approved.
Pre-labeled approved issue recovery rule
Sometimes an issue already carries status:plan-approved before the canonical repo planning artifacts exist.
Do not treat the label alone as sufficient proof that the planning route was completed.
When you encounter an already-approved issue with no repo-tracked plan artifact:
draft the canonical plan file under docs/plans/YYYY-MM-DD-issue-NNN-<slug>.md
update docs/plans/README.md with the plan index row
post a GitHub comment linking the new plan artifact and summarizing scope/resource-intel anchors
do not start implementation yet just because the old approval label is present
next run adversarial plan review and reconcile the issue state with the actual plan artifacts before coding
Approval-state drift checklist learned from live use:
verify all three surfaces before treating an issue as execution-ready:
live GitHub status:* label(s)
canonical local plan file under docs/plans/
local approval marker .planning/plan-approved/NNN.md
if GitHub says status:plan-approved but either the canonical plan file or local approval marker is missing, classify the state as governance drift, not true approval
repair the local artifacts first, then reconcile labels/comments; do not let the live label short-circuit the planning gate
when the user asks for manual review/approval links, provide the exact review surfaces explicitly:
GitHub issue URL
canonical plan URL/path
exact CLI label-flip command
required local approval-marker path
if the issue body points at a stale implementation path, call out the real repo path in the plan before review so approval is anchored to the actual file surface
This recovery pattern is especially important for harness/operations issues that were approved conversationally before the repo plan discipline was enforced, and for cases where GitHub label state drifted ahead of the repo-tracked approval evidence.
GitHub labels
Expected labels:
status:plan-review
status:plan-approved
Create them if missing before relying on this route.
Preferred companion skills
github-issues for issue view/comment/label/create actions
plan only for non-GitHub or purely local planning
Pitfalls
Skipping adversarial review because the issue looks simple
Posting only once at the end instead of at major planning steps
Weak resource intelligence based on one search path only
Folding follow-up work silently into the current issue instead of creating future issues
Posting a plan before review passes
Writing the plan in .hermes/plans/ instead of docs/plans/
Forgetting to update the planning index when the repo uses one
Starting implementation on status:plan-review
Treating piecemeal-migrated data locations as canonical architecture without an inventory/taxonomy dependency
Letting execution/report child issues hardcode provisional data paths instead of using source/residency contracts while data classification is unresolved
Legacy compatibility
Older guidance may reference issue-planning-mode.
Treat that as a deprecated alias/reference for this route, not the primary route name.
