--- name: plan-expedite description: Chain plan-review-autofix, plan-wrap-autofix, repo-sync, and task-handoff into one autonomous prep step before /build-phase. Required arg --plan . Default continues in-window — emits a /goal + /build-phase command pair (the /goal arms the Stop hook over the agent-completable build span); auto-compaction handles context (no forced /compact). Use --new-window for a fresh-window handoff (durable current.md write via task-handoff --next-task, then /session-wrap --end renders handoff-prompt.md and prints the Pick-up-here block). user-invocable: true --- # Plan Expedite `/plan-expedite --plan ` runs the full plan -> sync -> handoff pipeline as one autonomous step. Default output: TWO continue commands in order — first a `/goal ""` line that arms the Stop hook over the agent-completable span, then the `/build-phase --plan ` command — both to run **in the same window** — no forced `/compact`, because auto-compaction handles context on its own when it fills and the `SessionStart` re-inject hook reloads `current.md` afterward. (A focused `/compact` before the long build is optional — see step 4.) Add `--new-window` to hand off to a fresh window instead: a durable `current.md` write (`task-handoff --next-task`), then `/session-wrap --end` renders the handoff to disk (`.claude/task-state/handoff-prompt.md`) and prints the Pick-up-here block. --- ## Execution model — autonomous, invoke sub-skills via the Skill tool (HEAVY) This skill's whole reason to exist is that the operator does not want to type `/plan-review` → wait → `/plan-wrap` → wait → `/repo-sync` → wait → `/session-wrap`. They invoked `/plan-expedite` to have those four happen as one autonomous run. Therefore: 1. **Execute, do not advise.** When invoked, you MUST invoke each sub-skill via the `Skill` tool in the order specified in the "Sub-skill chain" section. Do NOT respond by emitting the chain as text (e.g. "Next: `/plan-review` → `/plan-wrap` → `/repo-sync` → `/session-wrap` → `/build-phase`"). That listing-the-steps response is the single most common failure mode for this skill — if you find yourself about to type that sentence, stop and call the `Skill` tool instead. 2. **No mid-run confirmations.** Do not ask "Should I run /plan-review now?", "Apply autofixes?", "Proceed to /plan-wrap?", "Ready to sync issues?", or any other (y/n) gate. The operator opted into the chain by invoking `/plan-expedite`. Halt only on the cases the "Halt template" section enumerates — sub-skill non-zero exit, genuine ambiguity surfaced under "Needs your input:" requiring operator judgment, or missing sub-skill. Everything else proceeds. 3. **Minimal between-step narration.** Between sub-skill invocations, one brief sentence is enough ("plan-review returned READY with 3 autofixes applied; invoking plan-wrap"). Do not re-describe what the next sub-skill is going to do — its SKILL.md handles that. 4. **Final output is the continue command(s) (or, with `--new-window`, the Pick-up-here block), verbatim.** On default success, the final output is TWO lines in order — a `/goal ""` line (scoped to the agent-completable automated span, per Step 4 of the chain) followed by the `/build-phase --plan ` command — no summary, paraphrase, or "here's what to do next" preamble. With `--new-window`, the Pick-up-here block that `/session-wrap --end` prints (exact next command + digest + pointer to the rendered `handoff-prompt.md`) IS the final output; emit it as-is. --- ## When to use - After `/plan-init` or `/plan-feature` produces a plan.md, before `/build-phase` runs. - When you want one command instead of remembering plan-review -> plan-wrap -> repo-sync -> session-wrap in order. - Re-running is safe: each sub-skill is idempotent on already-applied state (per autofix-applied markers from Steps 7-8) and `/plan-expedite` skips already-completed sub-skills (per `.plan-expedite-state` resume detection). ## When NOT to use - Mid-build-phase (this skill is a PRE-build prep; /build-phase has its own flow). - For ad-hoc plan edits without intent to ship (use individual skills directly). - If you want to manually review autofix changes before applying (use individual skills with --no-autofix). ## Arguments | Arg | Required | Default | Description | |---|---|---|---| | `--plan` | yes | -- | Path to the plan.md file (e.g., `documentation/foo-plan.md`) | | `--new-window` | no | false | Fresh-window handoff: run `task-handoff --next-task` (durable `current.md` write) FIRST, then `/session-wrap --end` — the handoff is rendered to `.claude/task-state/handoff-prompt.md` and the screen shows the Pick-up-here block (exact next command + <=6-line digest + pointer; no word floor). Use when you want the next step in a fresh window. | ## Flow ### Stale-plan check (per BPA plan section 5 D9) Check `plan.md`'s mtime before invoking any sub-skill. If >30 days old, print a warning but CONTINUE — do not bail: ```text warning: plan.md was last modified days ago (). Autofix may reshape stale plans significantly. Continuing — review the auto-applied fixes before /build-phase if drift is a concern. ``` ### Resume detection Check for `.plan-expedite-state` JSON file in the project root (sibling to plan.md). Schema: ```json { "plan_path": "documentation/foo-plan.md", "plan_mtime": 1779167384.42, "handoff_mode": "in-window", "completed": [ {"skill": "plan-review", "verdict": "READY", "timestamp": "..."}, {"skill": "plan-wrap", "verdict": "READY", "timestamp": "..."} ], "halted_at": null } ``` `handoff_mode` is `"in-window"` (default — `task-handoff --next-task`) or `"new-window"` (`--new-window` flag — `task-handoff --next-task` then `session-wrap --end`). Recorded at run start; used by resume logic to invoke the correct final sub-skill(s) on re-entry. `plan_mtime` is a numeric float — seconds since the Unix epoch, as returned by `os.path.getmtime(plan_path)` or `stat -c %Y`. No timezone, no string parsing. Comparison uses a 1-second tolerance: `abs(current_mtime - state_mtime) <= 1.0`. The tolerance accommodates filesystems with different mtime precision (NTFS records to 100ns, FAT32 rounds to 2s) and avoids spurious "plan changed" detections from format-only round-trips. Logic: - If file does not exist: fresh run, execute all 4 sub-skills sequentially. - If file exists AND `abs(current_mtime - state.plan_mtime) <= 1.0`: skip every sub-skill in `completed[]`. Start from the first uncompleted (or from where `halted_at` left off). - If file exists BUT the mtime difference exceeds 1 second: plan was edited since last run; discard the resume state and start fresh. - **Malformed state file:** if `.plan-expedite-state` exists but is invalid JSON, missing required keys (`plan_path`, `plan_mtime`, `completed`, `halted_at`), or has the wrong shape (e.g., `plan_mtime` not numeric, `completed` not a list), log a warning citing the malformation, rename the bad file to `.plan-expedite-state.malformed-` for forensics, and treat as a fresh run (proceed with all 4 sub-skills). Do NOT halt — an autonomous prep skill should self-heal from corrupted resume state, not require operator intervention to clear it. Update `completed[]` with the sub-skill name and write the file back after each successful sub-skill. On halt, set `halted_at` to the sub-skill name that failed and persist. ### Sub-skill chain Call each sub-skill below via the `Skill` tool, in order. Before the first invocation, `cd` to the project root containing `` (use the Bash tool). Between invocations, one brief progress sentence ("plan-review returned READY; invoking plan-wrap") is enough — do NOT re-emit the chain as prose. **Path-passing contract:** only `/repo-sync` documents a `--plan` CLI flag in its Arguments table; `/plan-review`, `/plan-wrap`, and `/session-wrap` operate on the plan via conversation context (they read the plan path from the invoking turn's prose or from cwd). Pass the path via the `args` parameter of the `Skill` call so the sub-skill picks it up. Read the exit code and final verdict line after each `Skill` call returns. On success, append to `completed[]` in `.plan-expedite-state` and proceed to the next sub-skill. On halt, write the halt template (see below) and stop. 1. **Invoke `plan-review` via the Skill tool** with `args: "--autofix "`. - Success criteria: verdict READY, or "READY (auto-fixed N items)", or NEEDS WORK with only clarifying questions auto-answerable. - Halt criteria: genuine ambiguity surfaced under "Needs your input:" requiring operator judgment, OR sub-skill non-zero exit, OR sub-skill missing. 2. **Invoke `plan-wrap` via the Skill tool** with `args: "--autofix "`. - Success criteria: verdict READY, "READY (auto-fixed N items)", "READY WITH GAPS: M gaps" (plan-wrap-only — 0 Blockers, M≥1 Gaps, /repo-sync may proceed), or NEEDS WORK with only clarifying questions auto-answerable. - Halt criteria: same as plan-review (genuine ambiguity under "Needs your input:" requiring operator judgment, OR sub-skill non-zero exit, OR sub-skill missing). 3. **Invoke `repo-sync` via the Skill tool** with `args: "--plan "` (autonomous default per Step 6 — no `--dry-run`). - Same success / halt criteria. 4. **Invoke the final sub-skill, then emit the continue command** — depends on `--new-window`: **Default (no `--new-window`):** Invoke `task-handoff` via the Skill tool with `args: "--next-task build-phase"` (it writes current.md + MEMORY + push — the durable handoff state). - Then emit the two continue commands verbatim as the `/plan-expedite` final output, BOTH inside ONE fenced code block (goal first, build command second) so the operator copies both in a single action — continue in the SAME window (auto-compaction handles context, no forced `/compact`). No preamble, no summary — the final output IS this one block. The `/goal` arms the Stop hook over the automated span and is user-typed (a skill cannot arm `/goal` itself), so it sits above `/build-phase`: ``` /goal "" /build-phase --plan ``` - **Derive the `` from the plan, scoped to the AGENT-COMPLETABLE slice.** plan-expedite has already read the plan, so enumerate its steps. The agent-completable (automated) steps are the ones the agent builds end-to-end with its own tools: `Type: code` and `Type: conditional`. NOT agent-completable: every `Type: operator` step, every Manual M-step (M1/M2/M3), AND every `Type: wait` step — a `Type: wait` step is an intentional build-phase halt (halt-contract class #4: the orchestrator stops and the operator resumes in a fresh session after the clock-gated wait), so its finish line is not reachable by the agent in-session. Build the condition over ONLY the contiguous automated (`code`/`conditional`) steps up to the FIRST operator / Manual-M / wait boundary — a goal that spans an operator, Manual M-step, or wait step busy-loops forever, because the Stop hook re-fires against a finish line the agent's own tools cannot reach. Form: `" automated steps are all marked Status: DONE in (issues #-# closed), and `` / `` / `` exit 0 — STOP before the operator/wait/Manual steps (M1/M2/M3, issues #-#); those are an operator handoff, not part of this goal"`. Cite the GitHub issue numbers for the automated steps and for the closing/quality-gate conditions wherever the plan makes them derivable; omit a clause only if the plan genuinely lacks it. If the plan is all-automated (no `Type: operator` steps, no `Type: wait` steps, and no Manual M-steps), target ALL steps and drop the STOP-before clause. - Record `handoff_mode: "in-window"` in `.plan-expedite-state`. - **Optional focused reset.** A proactive `/compact` before a long build-phase gives cleaner context than auto-compaction's best-guess summary — but it is the operator's choice, not the default, and is never auto-emitted as the mandated output (there is no way to trigger `/compact` programmatically). If they want it, they type it first: `/compact Focus on build-phase for [plan-name]: step list in plan.md, issue numbers filled, current.md has next action`. **`--new-window` mode:** TWO invocations, in this order — the durable write MUST land before session-wrap runs because `handoff-prompt.md` is a RENDERING of `current.md`: the render can only carry state already on disk. The default transition RECYCLES this window: `/clear` fires the SessionStart re-inject hook (matcher: `compact|resume|clear`), then the operator pastes the pair. The rendered handoff + fresh-window opener remain the closed-window alternative (the hook does not fire on plain startup): 1. **Invoke `task-handoff` via the Skill tool** with `args: "--next-task build-phase"` — the durable `current.md` write (finished prep lands in Completed; WIP, Next Action, and Status repoint at the build; MEMORY.md updated; commit + push). Set the written Next Action to the SAME agent-completable `/goal ""` line (derived per the Default-branch bullet above) followed by the `/build-phase --plan ` command, goal line first, so the rendered handoff carries the armed pair. 2. **Invoke `session-wrap` via the Skill tool** with `args: "--end "` — `--end` explicitly, never bare: end-window is the route `--new-window` wants, and a bare invocation triages and may route `continue`. session-wrap renders the handoff to disk (`.claude/task-state/handoff-prompt.md`, a rendering of the `current.md` just written — one source of truth) and prints the Pick-up-here block per its screen contract: digest + pointer first, then numbered Step blocks — Step 1 `/clear`, an optional `/model ` step when the session's model was explicitly overridden this session, and the FINAL fenced block carrying the `/goal` + `/build-phase` pair verbatim (goal line first). No word floor. session-wrap's route step 1 checkpoint must preserve step 1's Next Action verbatim (its no-regress clause) — the pair survives into the render and into the final Step block. - Emit session-wrap's Pick-up-here block verbatim as the `/plan-expedite` final output. Do not paraphrase, do not summarize, do not add a preamble. VERIFY the `/goal` + `/build-phase` pair is the block's final fenced Step — the last lines on screen are what the operator runs. If the block arrived without the pair (defensive), append a final Step carrying both lines in ONE fenced code block — never as bare indented lines. - Record `handoff_mode: "new-window"` in `.plan-expedite-state`. The `--new-window` flag is the escape hatch for users who want the next step in a fresh window instead of continuing in-window: durable state on disk plus a rendered handoff file, not a wall of copy-paste text. ### Halt template (per BPA plan section 5 D8 — generic, no per-skill enumeration) Write the following template verbatim on any sub-skill non-success exit: ```text /plan-expedite halted at: Reason: Plan state: GitHub state: To resume: fix the cited issue, then re-run /plan-expedite --plan (already-completed sub-skills are skipped via state inference from .plan-expedite-state) ``` Stop without producing the final continue command / Pick-up-here block after printing. The `.plan-expedite-state` records `halted_at: ` for resume. Use the same five-line template regardless of which sub-skill fails (plan-review, plan-wrap, repo-sync, task-handoff, session-wrap); per-sub-skill diagnostic detail belongs in the cited stderr, not in `/plan-expedite`'s template. ## Relationship to other skills | Skill | Role | |---|---| | `/plan-init`, `/plan-feature` | Produce the plan.md `/plan-expedite` operates on | | `/plan-review`, `/plan-wrap` | Autofix sub-skills (Steps 7-8 of BPA plan) | | `/repo-sync` | Issue-sync sub-skill (Step 6) | | `/session-wrap` | End-window handoff sub-skill (`--new-window` only, invoked `--end` AFTER the durable `task-handoff --next-task` write; renders `handoff-prompt.md` + prints the Pick-up-here block) | | `/build-phase` | Continues in-window from the `/goal` + `/build-phase` commands /plan-expedite emits (the `/goal` arms the Stop hook over the automated span; or, with `--new-window`, the fresh window opens from the rendered handoff carrying both) | ## Limitations - Resume state lives in a single `.plan-expedite-state` file in the project root. Multiple concurrent `/plan-expedite` invocations on the same plan have undefined behavior — don't do that. - Concurrent operator edits to `.plan-expedite-state` during a run have undefined behavior. Don't edit the file while `/plan-expedite` is running. - Sub-skill failures halt the chain; resume requires manual operator inspection. By design — autofix's promise is to handle the boring cases, not the surprising ones.