Ship Roadmap

Ship the roadmap (autopilot)

Run the entire agentic workflow unattended between human decision points: one interactive founding turn that asks everything, then a driver-fired build loop (Claude Code's /loop, an external orchestrator, or manual re-invocation — see the launch contract) that plans, implements, reviews, opens and (optionally) merges one PR per feature until the roadmap is done — then keeps going: an issue sweep inventories open issues and the run's own documented residue (known-issues, trade-offs, postponed findings), triages it all, and ships what's fix-now — ending in a final report that recommends issues, newly discovered features, and the product-audit cadence.

This is the expensive skill: a full run burns planning, implementation and review tokens for every roadmap feature. It exists to spend them well — strong tiers only where judgment lives, cheap tiers where code gets typed, humans only where a wrong call is expensive to undo.

> Ultracode tip: for large roadmaps, the user can enable the ultracode > session setting (/effort ultracode) before starting the loop — the conductor > then fans out independent sub-work (review axes, report evidence gathering) > more aggressively. It is a session toggle only the user can set; this skill > cannot declare or enable it (effort: accepts only low/medium/high/xhigh/max).

Turn contract — verify before ending the turn

✓ Exactly ONE stage advanced (or a terminal banner printed) and ONE line appended to the run log
✓ Nothing was merged outside the --fullauto floors; nothing asked mid-run
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed, then the machine envelope (fenced ```json — see ## Machine envelope) as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

• You have a roadmap — or at least a product idea and a feature list in your

head — and want the whole application built with supervision only at merge points and at the end.

• Not for one feature (plan-feature → execute-phase), one bug

(plan-fix), or exploratory work. The autopilot ships a locked scope; it is the wrong tool when the scope is still being discovered.

Step 0 — Discover the project (always first)

Read before acting: the agent guide (CLAUDE.md/AGENTS.md) and its Workflow conventions (forge CLI, verification gate, docs language), the documentation map, docs/features/ROADMAP.md, the fix index, the architecture doc, and .github/ templates. Then establish run context:

1. Substrate present? CLAUDE.md with Workflow conventions + doc map +

roadmap + fix index → founding is skipped and interview rounds 3–4 collapse to confirmations of what the docs already state. Missing pieces → founding will create them.

1. Workflow skills installed? Verify plan-feature, execute-phase,

review-change, and audit-pr are actually available in this environment (e.g. listed by the skills CLI or present under the skills directory), and record the discovered skills-directory path in the decision record — subagent prompts reference it. Missing → stop and instruct: npx skills add gtrabanco/agentic-workflow. Without these files the loop silently degrades.

1. Run in progress? docs/features/SHIP_DECISIONS.md exists — on any

branch — or a docs/ship-founding PR is open → a run exists: --continue resumes it; a bare /ship-roadmap prints run status and the resume command instead of re-interviewing (never a second founding).

1. Repo shape: empty greenfield vs existing history; current branch; dirty

tree (an unexplained dirty default branch is a stop condition, never something to clean up silently).

Process

Mode A — Found & launch (interactive): /ship-roadmap [--fullauto]

1. The interview — all questions up front, then silence. Small batched rounds; recommended defaults on every question; skip what discovery already answered. After Round 6 locks, no further questions for the entire run — every later decision is made silently and logged with a one-line rationale.

| Round | Covers | |---|---| | 1 — Product | What it is, for whom; scale ceiling (solo / team / thousands of customers); lifespan & ambition (throwaway, internal, long-lived production). Calibrates every ceremony decision downstream. | | 2 — Features | The feature list (or "elicit" → draft one from the goal); must-have vs can-wait; ordering constraints; explicit out-of-scope. | | 3 — Stack & architecture | Stack decided? else recommend from features/constraints. Architecture chosen? else recommend the lightest structure proportional to Round 1 — a solo tool gets a flat modular layout, a thousands-of-customers system gets enforced boundaries; never default to DDD, hexagonal, or any named pattern. Platform/runtime constraints, library vetoes. | | 4 — Quality & ops | Test depth (smoke / workflow default / strict); whether a11y, SEO, i18n, perf budgets apply (proposed from platform type); deploy target + scaffold CI?; secrets posture; confirm the proposed verification gate commands — they become the gate every phase must pass. | | 5 — Workflow & autonomy | Docs language (default English); forge + CLI (verify with a real authenticated call now, e.g. gh auth status — not mid-loop); git workflow (default branches: one active unit, sequential, no worktrees — worktrees only if the user declares it and their tooling manages them; recorded in the Workflow conventions and honored by every stage); merge policy (default human-merge vs --fullauto); the sensitive-area list (defaults: auth, payments, destructive migrations/data deletion, secrets, CI config — seeded with every integration named in rounds 2–4, e.g. the payment processor or auth provider the user mentioned); budget caps (default: max iterations = 4× roadmap feature count; 2 retries per red gate; 2 review-fix and 2 audit-fix cycles; optional "pause after N shipped features" checkpoint and milestone stop lines); model-routing confirmation; recommend enabling ultracode for the loop. | | 6 — Confirm & launch | The drafted roadmap (numbers, order, deps, sizes) and the full decision record, presented for one last edit. Then: founding artifacts written, exact /loop command printed. |

2. Founding (only what's missing). Compose init-workspace's process in-turn (both opus/high — within the ≥ rule), pre-fed with the interview answers so it asks nothing. Branch discipline:

• Empty repo: the scaffold (CLAUDE.md, docs/, .github/, completed

ROADMAP.md, decision record) is the repo's initial commit on the default branch — there is no history to protect and no base for a PR yet.

• Existing repo: founding goes on a docs/ship-founding branch as a PR.

Default mode: stop after the interview — print the PR and require it merged before the loop starts (building features against an unmerged substrate would stack PRs). --fullauto: gate the founding PR with audit-pr like every other PR, then merge it.

3. The roadmap. Adopt existing entries (never renumber), fill gaps the interview surfaced, append elicited features. If absent, write the complete table: NN in dependency-respecting order, slug, status: planned, depends-on, one-line summary with a provisional XS/S/M/L size in the summary text (the template's 3-status legend and column schema stay exactly as they are — plan-feature re-sizes authoritatively at planning time; a size change is logged silently). Greenfield: feature 01 is always the project skeleton (stack init, gate wiring, CI if requested), sized S — and every other feature's depends-on closure must include 01 (directly or transitively), so SELECT can never start a feature on a default branch that lacks the skeleton.

4. The run state — two artifacts, deliberately split:

• docs/features/SHIP_DECISIONS.md — committed (rides the founding

commit/PR): run mode, safety floors, sensitive-area list, budget caps, stop lines, model routing, docs language, and a digest of every locked interview answer. It is the durable, auditable policy: a crash, another machine, or a fresh clone recovers the full run policy without re-interviewing.

• docs/features/.ship-run.log — untracked (founding appends it to

.gitignore): the append-only iteration log — one line per iteration (date | NN-slug | stage | outcome | evidence: SHA / PR# / verdict), silent decisions with rationale, partial-stage markers, verdict↔SHA bindings. Machine-local mechanics; committing it would conflict across every open PR.

5. Print the launch contract — detect which driver this environment has and print the matching command. Three equivalent drivers (the loop is the contract; who re-invokes it is an implementation detail):

| Driver | When | Launch | |---|---|---| | /loop (Claude Code) | The agent has a self-re-invoking loop primitive | /loop /ship-roadmap --continue | | External orchestrator | Any agent invocable headless (a shell loop, CI, your own program) | loop: invoke /ship-roadmap --continue, parse the machine envelope, re-invoke while state: "CONTINUE" — see docs/workflow/ORCHESTRATION.md | | Manual | Neither of the above | re-run /ship-roadmap --continue yourself after each iteration; each ends with the exact next command |

Default launch contract text (adapt the first line to the detected driver):

Founded. Start the autopilot with:

  /loop /ship-roadmap --continue        (Claude Code)
  — or loop `/ship-roadmap --continue` from your orchestrator/by hand;
    every iteration ends with a machine envelope: re-invoke while
    state is CONTINUE (see docs/workflow/ORCHESTRATION.md)

Stop when an iteration's first line is SHIP: COMPLETE, SHIP: BLOCKED, or
SHIP: STOPPED (envelope state OK, BLOCKED, or FAILED). Iterations are
idempotent and resume cleanly; stopping at any time is safe.

For a fullauto run the command is /ship-roadmap --continue --fullauto (under whichever driver) — the flag must ride every iteration, because auto-merge is dual-keyed: the flag on the running command and merge: fullauto in the committed decision record (see Merge policy). One key without the other runs in default mode.

Each firing is a fresh /ship-roadmap --continue turn (on Claude Code's #claude branch, at this skill's pinned tier; elsewhere, at whatever tier the driver chose — judgment iterations deserve your strongest model). Iterations after a terminal banner are cheap no-ops that re-print the same banner — so a missed stop costs tokens, never correctness.

Mode B — One loop iteration: /ship-roadmap --continue [--fullauto]

Every iteration is stateless-by-reconstruction — no memory is assumed between turns:

1. RECOVER. Read SHIP_DECISIONS.md (missing → `SHIP: STOPPED — no run

policy; run /ship-roadmap first) and .ship-run.log (missing on this machine → recreate empty; policy lives in the committed record). **Verify the substrate landed:** SHIP_DECISIONS.md must exist on the default branch — an open docs/ship-founding PR means the substrate isn't merged yet → SHIP: BLOCKED with "merge the founding PR" as the unblock map. Read ROADMAP.md; query the forge for open/merged PRs on feat/, fix/, docs/ship-founding and docs/ship-report heads; check git state. Reconcile: a feature flips to done when its **PR opens** (built, not merged — see the PR stage), so a done row with an open PR is awaiting a human merge (default mode), not finished shipping. A **merged** PR needs no status change (already done) — it means *shipped*, and **unblocks its dependents** + counts toward SHIP: COMPLETE. The done-flip rides the PR-bound commit, never a lone commit on the default branch. A dirty feature branch from a crashed phase is handed to the next phase subagent to finish or restart (counts against the red-gate retry cap). Uncommitted changes on the default branch confined to docs/features//` + ROADMAP.md that match an in-flight roadmap row are the loop's own planning output — resume that feature; the dirty-default stop fires only for changes matching no roadmap unit.

1. STOP-CHECK. Evaluate the stop conditions (below). Terminal → write or

refresh the final report, open the report PR, print the SHIP: banner + status table, end the turn.

1. SELECT one unit. Priority order, first match wins:
2. Blocking fixes first. A fix-index entry classified fix-now whose

subject blocks the next startable feature (same module, a dependency's defect, or a red gate cause) → its fix is the selected unit (plan-fix → execute-phase --fix through the normal stages). Fixes that block nothing wait for the report's triage batch.

1. An in-progress feature's next pending stage.
2. The next planned feature whose depends-on rows are all merged

(forge state, not merely done — a done dep with an open PR isn't on the default branch yet, so a dependent cut from it would lack its code). Verify the closure transitively: a dep row marked merged whose own dependencies aren't merged means the roadmap's statuses are inconsistent → SHIP: STOPPED (substrate invariant broken), never build on top of it. → PLAN.

1. Issue sweep — features exhausted, run NOT over. Every roadmap feature

is done and merged but the sweep hasn't completed → the run continues with issues; finishing the features is not finishing the run:

1. INVENTORY (once per run, its own iteration). Enumerate (a) every

open forge issue and fix-index entry; (b) every documented residue the run itself generated — each feature's known-issues.md, the trade-offs in decisions.md, and every review report's postponed/intentional-tradeoff findings. For residue items that are real defects/gaps but have no tracked issue yet, file the issue now (forge CLI; body cites the doc + trigger). The issue body is Markdown — write it to a file and pass --body-file, never an inline --body "…"/heredoc that leaves \-escaped backticks (see Guardrails). Log the full inventory (issue #s + sources) to the run log.

1. TRIAGE (compose triage-issue in-turn, equal tier). Classify

each inventoried issue against the CURRENT codebase. fix-now → it becomes a selectable unit; postpone / wontfix / promote-to-feature → the dated verdict is recorded on the issue and carried into the report (promotions become report feature-proposals, never in-run scope).

1. SHIP the fix-now issues one unit at a time through the normal

stages (plan-fix → EXECUTE (--fix) → REVIEW → PR → AUDIT), same budget caps, floors, and merge policy as features.

1. Nothing startable → SHIP: BLOCKED with the unblock map ("merging

#12 unblocks 05 and 07") and the resume command.

execute-phase's own dependency gate stays active inside every subagent — it's the belt to this braces. The autopilot never passes --force: a gate stop inside a subagent parks the feature with the unmet chain recorded; forcing through unmet dependencies is a human-only decision, made outside the loop.

1. ADVANCE exactly one stage:

• PLAN — compose plan-feature in-turn via its scoped path (equal

tier). The interview path is forbidden mid-run: SPEC gaps

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gtrabanco
• Source: gtrabanco/agentic-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.