Project Version Upgrade - Plan, Approve, Execute (Deliberate)
You drive a breaking version event - framework, runtime, or load-bearing package - from detection to a verified upgrade: enumerate what actually breaks, sequence it foundation-first, get the user's approval on the plan, then execute it stage by stage with a gate after every stage. Judgment runs in-session; the reads and the edits are delegated to the cheap seats. This skill carries NO model pin and asks for no model switch: the plan is reasoned on the session's model (a skill-level pin lasts only for the turn it activates in; measured: Sonnet at xhigh planned a .NET 8 to 10 upgrade as well as Opus did, at the same cost).
The event kind - framework vs package - is not the user's call to make up front: DETECT reads the manifests and classifies it. The workflow is identical either way; only the breaking-change surface differs. A routine minor/patch bump with no breaking changes needs none of this - say so and exit.
Read references/upgrade-playbooks.md before PLAN - the stack-keyed sequencing rules and the runtime-break catalog are this skill's contract, not suggestions. The printed plan's first line is the receipt: playbooks: read - <the stack section(s) applied>.
When to use
- The deliberate version-upgrade flow for any BREAKING version event - a framework or runtime major, an EOL, a load-bearing package's breaking major: plan in-session (the published breaking-change surface crossed against located usage - applicable changes only), present the staged plan at an approval gate, then drive the execution stage by stage with a green gate after every stage.
- Triggers also on 'plan the framework upgrade'. Routine non-breaking bumps need no skill: just bump.
- Not for a feature that merely needs a newer package (the feature's own flow), or a red CI pipeline (issue-diagnoser-ci, or its single-chat CI-triage twin).
Approval gate - and auto-run
The staged plan is presented and NOTHING is edited until the user approves - an upgrade is consequential. Two answers end the run early: 'just the plan' (exit after PLAN, hand over the plan) and 'stop'.
Under auto-run the gate is answered, not skipped - and only when the user turned auto-run on, the hook's contract in context. Never infer it from urgency, from a clean plan, or from past runs; the old --auto, 'auto mode' or auto-mode wording starts nothing, and the gate stands. The hook takes the gate's (Recommended) option, so an open user-level call still ends the run at 'Just the plan'. The hard stops in step 5 stay rails: under auto-run their ask goes out with no (Recommended) mark, so it waits for the user. (Side effect worth knowing: an unattended run never pauses, so the model the session is on at run start carries the whole run; an attended run can switch at the approval pause and drop to a cheaper model for execution.)
Modes. Mode flags right after the command - --mode-auto-run-on, --mode-auto-run-off, --mode-output-scorer-on, --mode-output-scorer-off - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), -on holds for this run only: each stop takes its (Recommended) option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; --mode-output-scorer-on grades this run's output like a typed stack. A typed 'no stops' or 'run it without asking me' is no waiver in this flow: say in one line that --mode-auto-run-on right after the command turns auto-run on, and never hand-write an AUTO line.
The run
1. DETECT
Green baseline first - build + tests green, zero pending EF migrations, before a single version moves; a red or drifted baseline is a blocking precondition, report it and stop, never plan around it. Then read the manifests (global.json, *.csproj / Directory.Packages.props, package.json / angular.json), pin current -> target versions and the trigger (major, EOL, security advisory), and classify the event and the stacks it touches. No breaking surface -> routine bump, exit.
2. GATHER - delegated
- the documentation tools (load-bearing - the vendor's own page through
WebFetchwhere the tool order ranks nothing else): the target's published breaking-change surface - the migration guide, deprecations-and-removals, the version delta - never from recall. When it is unreachable, the surface is the vendor's migration guide the user pastes or fetches, and a breaking change no doc backs is markedunverifiedin the plan, never asserted. Branch by stack per the playbooks: what a migration tool auto-applies (ng updateschematics on Angular; on .NET whatever the current porting docs name - the Upgrade Assistant is deprecated) versus hand edits. - architecture-analyzer (sonnet/medium) per affected area, dispatched exactly as the roster spells it (
alfred-code:<seat>where the core plugin carries it): where the codebase actually uses the changed/deprecated APIs - located usage digests, reads kept off this context. Mine the build's own signals first (the[Obsolete]/analyzer warnings,ng update/ng lintdeprecation notices) - they are the framework's pre-computed removal map.
3. PLAN - in-session
Cross the surface against located usage: a breaking change nothing uses is not a task. Split engine-applied vs hand edits. Sequence foundation-first per the playbooks (SDK pin -> TFM -> framework packages in lockstep -> code edits on .NET; one major at a time with ng update + the peer matrix on Angular). Each stage carries: its edits, its verification command, its rollback point. Genuinely user-level calls (accept a new major's baseline, drop a deprecated dependency) go to the gate as questions, never guessed. Hard cap: 2 planning passes.
4. APPROVAL GATE
Where a scorer: stacked line is in context, the FIRST action before releasing the staged plan - before it is printed - is the mode-output-scorer Skill call with output upgrade-plan.
PRINT the staged plan in the chat first - the playbooks: line, then every stage with its edits, its verification command and its rollback point - in the same turn as the gate: an approval over a plan the chat never showed approves nothing. Load habits-execution-strategy (the Skill tool); its Execution: line is the mode reason, and stages that share files read serial. Then put the gate through AskUserQuestion as ONE call - free text stays available via Other, and the PLAN step's user-level calls join the same call as their own questions (plain-text options where the harness lacks the tool). With no user-level call open:
The staged plan above: <n> stages, each with its verification and rollback point. Execute it stage by stage <through the seats | in this session>: <the Execution: line's reason>.
- 'Approve - execute through the seats (Recommended)' - each stage goes to the implementer seat and gates green before the next
- 'Approve - execute in this session' - the stages run in order here, no seat; each still gates green
- 'Just the plan' - exit here and hand over the plan
- 'Stop - changes needed' - I ask what to change next, in plain text
The mark moves to 'in this session' when the verdict reads serial; the run never drops the seats on its own call. With a user-level call still open, executing would guess its answer, so the plan is the recommendation:
The staged plan above is ready, but <n> user-level call(s) are open. Take the plan and settle them first.
- 'Just the plan (Recommended)' - exit here with the plan; the open calls are yours to settle
- 'Approve - execute the stages' - run the stages on the answers given in this same call, in the mode the verdict names
- 'Stop - changes needed' - I ask what to change next, in plain text
5. EXECUTE - stage by stage
Before the first implementer dispatch, write the approval gate file <data root>/state/approvals/<plan id>/APPROVAL (<plan id> is this run's own, task-version-upgrade - the plan lives in the chat, not a file) - first line APPROVED <plan id> - "<the user's words, verbatim>" from the gate's approving answer (under auto-run the hook's AUTO stamp already stands - leave it) - the dispatch hook blocks an unstamped implementer; delete the file when the run completes. A question the idle timeout closed is no answer: its result opens 'No response after' and says the user may be away from keyboard, even when it carries an option already selected - write no APPROVED or AUTO line from it; re-ask, or stop and say what waits. Write the stamp at the ABSOLUTE path <project root>/<data root>/state/approvals/<plan id>/APPROVAL with the Write tool, and give every implementer brief the line plan: <plan id> - the dispatch hook passes a brief only on its own plan's stamp. A relative write follows whatever cwd the shell drifted to and the dispatch then bounces. The stamp belongs to the session that dispatches - written when its own decision lands, deleted at its own close; an earlier session's leftover stamp is not consent. If BOTH the Write tool and an absolute-path Bash write are refused by the harness's classifier, stop and ask rather than retrying blind or dispatching around the gate:
Both write routes refused the approval stamp: <the refusal>.
- 'Retry the stamp (Recommended)' - allow the write at the prompt
- 'Run this stage inline' - no dispatch, no stamp
Per stage, in the plan's order, in the mode the gate's answer chose: through the seats, dispatch the domain implementer (sonnet/medium) with the stage as a scoped brief (trivial manifest bumps: edit inline); in this session, make the stage's edits here (no approval stamp needed - nothing dispatches); run the stage's verification (build + tests); a red routes to the matching resolver (sonnet/high) for that stack - the seat covering build errors, or the one covering test failures, matched from your installed agents; with none matching, resolve the red inline and say so; gate green before the next stage. Hard stops, auto-run included: a resolver returning BLOCKED_CONTRACT_CHANGE, a stage that stays red after its resolver pass, or reality contradicting the plan - stop and put it through ONE AskUserQuestion, never push through or skip a stage gate:
Stage <N> hit a hard stop: <the resolver's BLOCKED_CONTRACT_CHANGE | the red that stayed | what contradicts the plan>.
- 'Re-plan from this stage (Recommended)' - the plan is redrawn from here, the landed stages stay
- 'Roll back to the last stage's rollback point' - this stage's changes are undone
- 'Stop here' - nothing more runs; the landed stages stay
Under auto-run put the same three options with NO (Recommended) mark, the question opening 'no option is recommended: a hard stop waits for you under auto-run' - the hook answers only a marked ask, so this one waits.
6. VERIFY + REPORT
Full suite green at the end; on a large upgrade, optionally the domain verifier (sonnet/xhigh) over the assembled result. Report: current -> target, stages landed and what each changed, runtime-break checks done, anything deferred or user-declined, the rollback points, and the commit line. If the run stopped early: which stage, why, and the state it left. Shaped like:
.NET 8 -> 10: 4 stages landed, full suite green (412 passed)
1 SDK pin + global.json (rollback a1b2c3d) 2 TFM + framework packages in lockstep
3 obsolete-API swaps (SYSLIB warnings) 4 hand edits - TimeProvider swap, 3 call sites
runtime-break checks: serializer defaults reviewed, zero [Obsolete] warnings left
deferred: FluentAssertions major (user-declined)
commit: held - the diff is uncommitted
Then the commit decision, ONE AskUserQuestion once the report prints (an early stop asks it too when a stage landed):
<N> upgrade stage(s) landed, uncommitted (<suite green | stopped at stage <k>>). Commit them on this machine?
- 'Commit now (Recommended)' - runs `habits-commit-checkpoint` in full, then commits
- 'Hold - review the diff first' - nothing is committed; the diff stays as it is
Don't game it
Enumerate the real breaking changes from the framework's own docs, not recall - recall catches the compile break and ships the runtime break. Keep the plan to located usage. Never wave a deprecation off as 'probably fine' - unclear impact is marked to verify. Never weaken a test, suppress a warning, or skip a stage gate to make a stage look green - that is a new break, not progress.