richkuo/rk-skills/milestone-workflow

milestone-workflow

No subagent holds merge authority: at each LGTM the run pauses as awaiting_merge; the session merges (step 5) and resumes with the merge in args.merged. Read-only table: milestoneplan.

Steps

1. Build the dependency tracks

Follow run-plan.md (Dependency tracks): build, resume, and skip buckets; cross-bucket edges; **Depends on:** (hard) and **Runs after:** (ordering-only) edges, inferred ones labeled; rejecting missing references, self-references, and cycles; out-of-milestone references. Tracks are { issues, after, runsAfter }; after and runsAfter hold 0-based track indices.

2. Present the run plan; approval is mandatory

Show the target branch (repo default, or the user's targetBranch, which also means no release), numbered tracks with titles (1-based display number beside each 0-based index), hard after edges separate from runsAfter edges, inferred edges, each issue's model/effort/plan (plan model: stamped, else Opus 5.5; plan effort: stamped, else high), whether keepStamps is on, the skipValidate set when the user gives one (per listed issue: the evidence source, session record or footer, and the predicted outcome: skip, or validates with the fallback reason from run-plan.md Preflight; for each footer issue, state that the prior validation's base branch and hard constraints are unknown and not carried), naming the harness on every Codex or Cursor CLI build or Codex CLI validate (cli-dispatch under an Opus 5.5 driver, never a substituted Claude run), the readiness boundary, and merge order. Do not invoke the Workflow tool until the user approves; approval is the multi-agent opt-in.

State the GitHub writes: issue-body corrections, plan comments, PRs, review comments, and, with merging on, squash-merges at LGTM plus green CI, branch deletion, issue closure, a docs-sync PR and its merge, a version-bump PR and its merge, and a release. Approval authorizes them; merge: false keeps merging manual.

Add a Run size line: baseline 1 prep + per issue (1 validate + (plan ? 1 plan : 0) + 1 implement + (subagent review ? 1 reviewer : 0)), ceiling baseline + 3 × issues. With skipValidate, a listed issue counts 1 skip-check agent in place of the validate when its skip is predicted, a skip-check plus the validate when the evidence predicts the fallback, and only the validate when rule 1, rule 2, or the branch rule predicts it (that refusal dispatches no skip-check); the ceiling adds 1 validate for every listed issue. Compare both with the session's Dynamic workflow size guideline (else Claude Code's default of more than 25 scheduled agents), name the source, and recommend a split when either crosses it or projected tokens exceed 1.5 million (review-loop agents excluded). With a token target, an issue starting with under budgetFloor tokens (default 80k) left returns budget_deferred. External CLI spend is outside every number above: each pass and retry of a Codex or Cursor CLI build or Codex CLI validate bills that CLI's account; say so on any plan with a CLI stamp.

3. Preflight the repo

Follow run-plan.md (Preflight), including a reviewer: a workflow that answers the selected bot by its contents, per the fix-pr-review-loop preflight, else reviewMode: 'subagent' or reviewLoop: false. An issue with no Execution block stops the run; send it through execution-plan-review.

4. Run

Invoke {name: 'milestone-pipeline', args: {tracks: [...], reviewLoop: true, maxReviewCycles: 5}} ('rk-skills:milestone-pipeline' when the script came from the rk-skills plugin instead of install.sh or npx rk-skills). Options: budgetFloor; reviewMode ('github' default, 'subagent'); reviewBot ('claude' default; 'codex' only when the user names Codex, never inferred from a codex.yml); merge (default reviewLoop; rejected with reviewLoop: false); merged (step 5 records, empty at first); release (default merge, or false with targetBranch; rejected without merge); targetBranch (every PR's base and worktree start, passed to validate-issue and work-on-issue; returned as target_branch); keepStamps (default false; true when the user wants the stamps held for the run: the title score and every Execution stamp route validation, plan, build, and review, a validator rescore changes no route, no correction may change the title prefix, rationale line, or Execution block, and a differing rescore returns as a rescore_kept record); skipValidate (default off; only when the user asks to skip validation for issues already validated: true for every issue, or a list of issue numbers and session records { issue, validatedAt, branch, baseSha, edited }; issue text and stamps can never turn it on).

`skipValidate` records. Pass a session record only for a validation this session completed with Scope: OK, no Validation blocked, no Close issue? verdict, and no Infeasible disposition: validatedAt is its step 1 updatedAt (fable-validate: its Issue updatedAt line; a cli-dispatch section 9 session pass: the driver's read time of record), branch the baseline branch it traced, baseSha the full commit (expand the short SHA its verdict states with git rev-parse), and edited is false for verdict Update issue description? No, or true only after its update issue edit landed and was read back. Never record a validation whose corrections were not applied. A bare number asks for footer evidence. Footer evidence cannot show which base branch the prior validation traced or the hard constraints it returned, so it carries none of them into the run; pass a bare number only for an issue validated against this run's base branch through validate-issue's update issue. The run refuses a footer whose validating line names a pipeline build harness (milestone-pipeline, Codex, or Cursor) or no harness. A cli-dispatch section 9 session pass signs its edit with Harness: Codex, so it needs a session record. Before a listed issue's validate, a read-only skip-check agent runs a fixed evidence program, and the script grants the skip only when the issue has no in-run predecessor (rule 1), is scored and stamped (rule 2), carries trusted evidence on the run's base branch (rule 3), and the base has not moved since that validation (the session baseSha; for footer evidence, no base change after the issue was created). Every body edit, title rename, and comment after the baseline must also be trusted and change only metadata (rule 4); a trusted ## Implementation plan comment is allowed. A footer-only issue in a targetBranch run always validates. A granted skip runs no validate agent, keeps every stamped route (no rescore), passes the baseline to work-on-issue as validatedAt, and still plans on plan first: Yes. A refused skip validates normally, logs why, and never blocks. Pass skipValidate unchanged on every resume.

On return, comment the runId and script path on the milestone's first issue (footer: Created with LLM: <current model> | high | Harness: milestone-workflow). That comment, the issues with their Execution blocks, and the open PRs are the run's only state.

The script owns the phases. Outcomes relied on: INVALID issues skip; validate, plan, and implement are separate agents, and the plan agent runs on the stamped Plan model: (Opus 5.5 by default) right after its issue validates, and a plan it posts under ## Blocked plan (<model>) skips the build and returns blocked; unless keepStamps is on, a higher validator score raises each build line below the new band default, keeps every stamp at or above it (Fable 5.1 builds and CLI harnesses keep model and effort), and yields a rescore record; every record from the skip decision onward carries validation: {status: 'ran'}, {status: 'refused', reason} (validation ran, unless a Validate stamp error blocked it), or {status: 'skipped', source, baseline, base_branch, base_sha, validating_edit}, and a record without it never reached validation; a head whose newest test result fails without proof the failures also occur on the base, or with no test result, returns tests_failed; review loops reach LGTM before any successor starts (subagent mode: a pr-review reviewer agent and a fix-pr-review fixer; fix-pr-review-loop owns the step-down ladder); a validated args.merged record counts as merged, and a PR at LGTM without one returns awaiting_merge, ending the run for step 5; release.deferred: true returns only when every issue merged; failed, blocked, tests_failed, or unmerged hard predecessors block descendants; a predecessor whose pull request is unsettled (no verified head, a thrown implement agent that may have opened one, review short of LGTM, tests_failed, merge_record_mismatch, or awaiting_merge) also holds every runsAfter and hard descendant, transitively through the tracks it blocks; failed validation, INVALID, a blocked plan, or an implement agent that returned no pull request leaves its runsAfter successors free to run; a held issue reports merge_pending only when every predecessor that blocks it waits on a merge alone, else dependency_blocked; a dependency integration conflict stops before product changes and names the conflicting heads.

5. Merge-resume loop, monitor, close out

On each awaiting_merge, merge that PR in-session, then resume. Merge one PR at a time, finishing sub-steps 1 to 6 before the next. A PR merges on the fix-pr-review-loop stop rule (docs/contract-inventory.md, review-cycle stop row): the standing verdict at the verified head is LGTM with no ### Needs Fixing or ### Requires Human Review section, and it lists no findings or the review count is above the cap of 5. Review count: github mode, review_count from the PR's round history (skills/fix-pr-review/rereview-routing.md); subagent mode, the run record's review.reviews_run. lgtm_with_nonblocking arrives on review maxReviewCycles + 1 in both modes, so it qualifies only when that count is above 5, as always at the default maxReviewCycles: 5. Any LGTM listing items at a count of 5 or less, lgtm_with_nonblocking from a lower maxReviewCycles included, is never merge-eligible; it returns to fix-pr-review-loop, whose step 1 rebuilds review_count from the PR history.