@gtrabanco/pi-agentic-workflow 0.13.3 → 0.15.0

package/skills/ship-roadmap/SKILL.md

@@ -1,120 +0,0 @@
----
-name: ship-roadmap
-user-invocable: true
-version: 5.2.3
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-argument-hint: "[--fullauto] | --continue [--fullauto]"
-description: >
-  Found or continue a roadmap autopilot one stage per invocation. Default:
-  human merge. --fullauto is invocation-scoped and uses the transient wrapper
-  only after a fresh audit. Triggers: "ship-roadmap", "ship the roadmap",
-  "autopilot this project".
----
-
-# Ship the roadmap (autopilot)
-
-Found once, then run the driver-fired loop (Claude `/loop`, external driver, or
-manual re-invocation): plan, implement, review, open and optionally merge one PR
-per roadmap unit. After the roadmap, sweep existing issues, ship fix-now work,
-report residue as proposals (never create backlog automatically), and print the
-final report. Use strong tiers for judgment, cheap tiers for typing, and humans
-at expensive-to-undo decisions.
-
-`ship-roadmap` is the conductor of the loop. It emits its native fixed `SHIP:`
-banner and closing `→ Next:` block; the package-owned machine-result profiles
-apply to the worker and sensor skills that a driver invokes inside the loop.
-
-## 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 active --fullauto wrapper; direct merge
-  commands remained blocked and no authorization survived the iteration
-✓ 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 as the ABSOLUTE last output
-```
-
-Any unchecked box means the turn is not done.
-
-## When to use
-
-Use for a locked roadmap with supervision at merge/end points. For one feature,
-one bug, or exploratory work use the manual planning/execution flow instead.
-
-## Step 0 — Discover the project (always first)
-
-Read before acting: `AGENTS.md` Workflow conventions, documentation
-map, `docs/features/ROADMAP.md`, fix index, architecture doc, and `.github/`
-templates. Then establish:
-
-1. **Substrate:** if the guide, map, roadmap and fix index exist, skip founding
-   and confirm their answers; otherwise founding creates missing pieces.
-2. **Skills:** verify `plan-feature`, `execute-phase`, `review-change`, and
-   `audit-pr` are installed and record their directory for worker prompts. If
-   absent, stop with `npx skills add gtrabanco/agentic-workflow`. With
-   `--fullauto`, also require executable `.agentic-workflow/hooks/fullauto-merge.sh`
-   and its platform guard; otherwise route to `init-workspace`, never direct merge.
-3. **Run:** existing `docs/features/SHIP_DECISIONS.md` or an open
-   `docs/ship-founding` PR means resume with `--continue`; bare invocation reports
-   status instead of founding again.
-4. **Shape:** greenfield/existing, branch, and dirty tree; unexplained dirty
-   default branch stops (never clean it silently).
-
-
-## Progressive loading — select the invocation route
-
-The allowlist is exactly the linked paths below. Never invent another reference.
-Every route starts with [guardrails](references/GUARDRAILS.md), then loads only
-its matching row:
-
-**Hard rule for `--continue` at AUDIT:** LOAD exactly, in this order,
-`references/GUARDRAILS.md`, `references/RECOVERY_AND_SELECTION.md`,
-`references/STOP_CONDITIONS.md`, `references/ADVANCE.md`,
-`references/MODEL_ROUTING.md`, and
-`references/AUDIT_AND_MERGE.md`; after the stage, load
-`references/CLOSEOUT_AND_LOG.md`. When the run is not terminal and all named
-primitives exist, every other reference is forbidden for that turn.
-
-| Condition now | LOAD complete route in this order | SKIP now |
-|---|---|---|
-| Found or inspect a run, no `--continue` (default mode or greenfield `--fullauto`) | [guardrails](references/GUARDRAILS.md) → [founding](references/FOUNDING.md) | recovery, stop conditions, advance, model routing, audit/merge, terminal report, portability |
-| Existing-repo founding with `--fullauto` | [guardrails](references/GUARDRAILS.md) → [founding](references/FOUNDING.md) → [audit and merge policy](references/AUDIT_AND_MERGE.md) | recovery, stop conditions, advance, model routing, terminal report, portability |
-| Continue one non-AUDIT iteration | [guardrails](references/GUARDRAILS.md) → [recovery and selection](references/RECOVERY_AND_SELECTION.md) → [stop conditions](references/STOP_CONDITIONS.md) → [advance](references/ADVANCE.md) → [model routing](references/MODEL_ROUTING.md) before stage execution → [closeout and log](references/CLOSEOUT_AND_LOG.md) after it | founding, audit/merge, terminal report, portability |
-| Continue an AUDIT/fullauto iteration | [guardrails](references/GUARDRAILS.md) → [recovery and selection](references/RECOVERY_AND_SELECTION.md) → [stop conditions](references/STOP_CONDITIONS.md) → [advance](references/ADVANCE.md) → [model routing](references/MODEL_ROUTING.md) → [audit and merge policy](references/AUDIT_AND_MERGE.md) before the AUDIT stage → [closeout and log](references/CLOSEOUT_AND_LOG.md) after it | founding, terminal report, portability |
-| Terminal stop/report | the active row above, then [terminal report](references/TERMINAL_REPORT.md) | unrelated rows |
-| A named platform primitive is absent | the active row above, then [portability](references/PORTABILITY.md) | unrelated rows |
-
-Do not load terminal reporting before terminal state or portability when all
-primitives exist. Model routing precedes every stage; audit/merge precedes every
-AUDIT stage, including non-`--fullauto` runs.
-
-Selected resources are one hop from this file. Fixed banners, transitions, floor
-checks and output blocks are normative; an unreadable required resource stops the
-run—never improvise from an older run.
-
-## Portability
-
-The workflow is driver-neutral. Use the exact [portability](references/PORTABILITY.md)
-fallback only when a primitive is unavailable; keep stage order and safety floors.
-
-## Relationship to other skills
-
-| Relation | Skills/policy |
-|---|---|
-| Compose (same/lower tier) | `init-workspace`; JIT `design-feature` + `plan-feature-scaffold`; `plan-feature`; the review→fold manual path (`/review-change` → `/fold-findings` on `REVIEW-FAIL` → re-run `/review-change`); verdict-only `audit-pr`; `audit-docs`. |
-| Cheap workers | `execute-phase` (fresh context/phase), mechanical folds, audit-blocker fixes; use the validated worker model. |
-| Human hand-off | Default merges, `product-audit` (higher effort), and report issue batches via `triage-issue`. |
-| Sibling | `workflow-status` supplies the strict sensor result; worker skills use the package-owned output profiles, while the conductor keeps its native `SHIP:` turn contract. |
-
-Manual feature-by-feature flow remains the default; this skill packages it with
-the human at its edges.
-
-## Done when
-
-- A terminal banner and final report exist with an open PR; roadmap statuses are
-  true; every PR is merged, open/audited, or parked with a reason. `SHIP: COMPLETE`
-  also accounts for the issue sweep and reports residue as proposals.
-- Locked answers, iteration evidence, outcomes and recommendations are traceable
-  in `SHIP_DECISIONS.md`, the run log and report; the report states exact next
-  human actions (merges, triage, proposals, product-audit timing).

package/skills/ship-roadmap/references/ADVANCE.md

@@ -1,117 +0,0 @@
-## Advance exactly one stage
-
-4. **ADVANCE exactly one stage:**
-   - **DESIGN (mid-run `idea`/`defined` unit only)** — compose `design-feature`
-     in-turn (equal tier, opus/high — within the ≥ rule already stated for
-     founding), **deriving the product half strictly from the locked
-     `SHIP_DECISIONS.md` record — no new questions, ever** (the "no further
-     questions after the interview" contract this skill already enforces for
-     every other stage applies here identically). Walk capability closure
-     from what rounds 2–4 already answered for this feature; stamp `## Design
-     status: designed` and promote the roadmap row `idea → defined` on
-     success. Then compose `plan-feature-scaffold` in the same iteration to
-     promote `defined → planned` (both writes are the same JIT pass — a
-     feature never sits mid-promotion between iterations). **Undesignable
-     from the locked record** (the feature as scoped contradicts a locked
-     decision, or needs an answer rounds 2–4 never covered) → do **not**
-     guess and do **not** ask: emit `NEEDS_INPUT`, **park the unit** with the
-     specific gap recorded (mirrors a red-gate park — see Stop conditions),
-     and SELECT continues with the next startable unit this same run (or ends
-     the iteration per the capacity guard if none remain). A parked
-     undesignable unit is picked back up only by a human answering the
-     recorded question and re-running `/design-feature <slug> "<answer>"`
-     directly — the autopilot never re-asks it.
-   - **REVIEW-SPEC** (only between DESIGN and PLAN) — compose `review-spec` in a
-     clean context at the routed tier (opus/high), never in the turn that wrote the
-     product half. `SPEC-REVIEW-PASS` releases the unit into PLAN. A FAIL whose
-     findings are common-root-cause or wording-only returns to the same unit's
-     author for one root-caused repair batch, then a fresh review. `NEEDS-DESIGN`
-     means a product choice is open that this run's locked record cannot answer:
-     **park the unit** with the exact question (`NEEDS_INPUT`, same shape as the
-     undesignable park above) — the autopilot never answers a product question
-     itself, and `SELECT` continues with the next startable unit.
-   - **PLAN** — compose `plan-feature` in-turn via its scoped path (equal
-     tier). Every unit reaching PLAN holds a current `SPEC-REVIEW-PASS` (REVIEW-SPEC
-     ran first, or the unit was already planned before this gate existed and its
-     own Product receipt is current), so `plan-feature`'s PRODUCT-REVIEW gate passes
-     here. The interview path is **forbidden** mid-run:
-     SPEC gaps are resolved silently from the decision record and logged. JIT
-     planning that reveals the feature's premise is wrong (obsolete, absorbed,
-     impossible on this stack) → mark it blocked with the contradiction
-     recorded; never re-ask.
-   - **REVIEW-PLAN** (only between PLAN and EXECUTE) — compose `review-plan` in a
-     clean context at the routed tier over the plan the previous stage just froze.
-     `PLAN-REVIEW-PASS` releases EXECUTE. A FAIL routes by root cause: plan-local
-     (bad phase cut, blank validator, ledger drift) → root-caused re-cut by the
-     planning author and a review; product-rooted or an assumption this record
-     cannot settle → PLAN-REVIEW-FAIL with class: product → design-feature. A second local cycle
-     that changes nothing stops editing and reports `CONVERGENCE-ANOMALY` instead of
-     burning a third budget. **No stage between PLAN and EXECUTE may create a forge
-     issue or defer an obligation to one** — an unmet obligation fails this stage, it
-     is never exported.
-   - **EXECUTE** — run each unfinished **implementation phase** in a **fresh cheap-tier context**: on Claude
-     Code, spawn one subagent per phase with `model: sonnet` (the override is
-     the only mechanism that runs *below* the conductor's turn tier); on an
-     agent without subagents, the equivalent is one headless invocation per
-     phase driven from outside (see `docs/workflow/ORCHESTRATION.md`), or —
-     last resort — executing the phase in THIS turn while noting in the run
-     log that it ran at the conductor's tier. Whatever the mechanism, the
-     phase executor is instructed to read the **installed `execute-phase`
-     SKILL.md first** (at the skills directory
-     located in Step 0 and recorded in the decision record — e.g.
-     `.claude/skills/execute-phase/SKILL.md` in Claude Code) and follow it for
-     exactly one explicit phase: tests-first where it
-     applies, gate green, one commit, per-phase docs. Two autopilot overrides
-     to its recipe: (a) **never ask** — SPEC ambiguity is resolved from the
-     committed decision record with the most conservative reading, and the
-     assumption is surfaced in the phase docs so the conductor logs it;
-     (b) the **P1 planning commit also carries `ROADMAP.md`** (the feature's
-     `in-progress` flip rides it; the **`done` flip rides the PR-stage commit**
-     when the PR opens; any flips left at run end ride the report commit).
-     Stop before the literal final `Hardening & PR` phase: PR owns that explicit
-     phase so close-out has one owner. Never bundle phases into one worker.
-   - **REVIEW** — compose the review→fold path (equal tier) once: `/review-change`, then `/fold-findings` (on `REVIEW-FAIL`), then re-run `/review-change`. It reuses a current exact-SHA receipt or runs `review-change`
-     context-clean, batches compatible fixes through `fold-findings`, and
-     re-reviews only changed HEADs. Default correction budget is two; unchanged
-     evidence stops NO-PROGRESS. L/sensitive features
-     forward `--adversarial 2` (security/auth: `3`) as the unattended floor;
-     other units use one final reviewer. There are no intermediate phase
-     reviews in autopilot: phase gates + frozen acceptance guard execution,
-     and the independent final loop judges one complete candidate. Independent
-     future work remains proposals; no review/fold stage creates issues.
-   - **PR** — run the unit's explicit final `Hardening & PR` phase through one
-     fresh cheap-tier `execute-phase` worker. That canonical close-out flips the
-     feature to `done` (built, not merged), pushes, creates the PR with `Closes
-     #N` where issue-born, prints its URL, links it from the roadmap, commits the
-     link, and pushes. Reconcile an already-open matching PR idempotently; never
-     create a second one. The stage is incomplete until the row carries its PR
-     link and the branch is clean/current.
-   - **AUDIT** — compose `audit-pr` in-turn (equal tier); bind the verdict to
-     the PR's head SHA in the run log, and **print the PR's full URL next to
-     the verdict in the iteration output** (the human merging works from the
-     chat, not from a CI monitor). MERGE-READY → default mode logs and
-     moves on; `--fullauto` treats `audit-pr` as verdict/comment-only, checks
-     the floors, **records the merge intent in the run log first**, then calls
-     `.agentic-workflow/hooks/fullauto-merge.sh` with only the PR number and
-     run id. The wrapper derives and verifies head, base, decision, and audit
-     evidence from the forge. Never invoke `gh pr merge` directly.
-     BLOCKED → in-scope blockers go to a
-     cheap-tier worker next iteration (max 2 audit cycles, then the feature is
-     parked and the loop moves on); the fixer's cycle ends committed AND
-     pushed (step 5), so the re-audit judges the real branch.
-
-   Fix units take the same pair in miniature: **plan-fix → REVIEW-PLAN → EXECUTE
-   (`--fix`)** — a fix has no Product hop to wait on (D6), so its plan review is the
-   only pre-execution gate it can have. The stage sequence is per-feature and size-dependent — always **one stage
-   per iteration**: a feature starting at `idea`/`defined` gets a DESIGN stage
-   first; one already `planned` (including the founding-scaffolded feature 01)
-   goes to its missing review stage, and skips to EXECUTE only when a current
-   `PLAN-REVIEW-PASS` is bound to its bytes. Every size follows
-   **[DESIGN → REVIEW-SPEC] → PLAN → REVIEW-PLAN → EXECUTE**
-   (implementation phases, fresh cheap worker per phase) → PR (explicit
-   `Hardening & PR`) → REVIEW (bounded final loop) → AUDIT. Risk changes final
-   review strength, not phase cadence. The two review stages are the pre-execution
-   pair: they judge documents in a clean context and are **not** the post-code
-   REVIEW loop, which stays exactly as described below. Merge policy is unchanged —
-   the human (or the `--fullauto` wrapper behind its recorded floors) still owns the
-   merge, and neither review stage may merge, close, or file anything.

package/skills/ship-roadmap/references/AUDIT_AND_MERGE.md

@@ -1,64 +0,0 @@
-### Merge policy
-
-**Default — the human merges.** The autopilot opens PRs and never merges. It
-continues with the next feature whose dependencies are all merged (new branches
-always cut from the freshly pulled default branch); when everything remaining
-waits on human merges, it stops with `SHIP: BLOCKED` + the unblock map. After
-merging, re-run the same launch command (`/loop /ship-roadmap --continue`, plus
-`--fullauto` on fullauto runs) — recovery records the merges (the rows are already
-`done` from PR-open), unblocks the dependents, and resumes.
-
-**`--fullauto` — dual-keyed.** Auto-merge requires a fresh SHA-bound
-`audit-pr:merge-ready` comment and `merge: fullauto` in the decision file at
-the PR's current head — stale or caller-supplied local evidence can never
-enable it. The **first
-feature PR of a greenfield run is always human-merged** (calibration: inspect
-one complete artifact — code, tests, docs, review trail — before delegating).
-
-This AUDIT stage is the **sole automated merge authority**. Authorization lasts
-for this invocation and this merge attempt only:
-
-1. `audit-pr` returns a fresh SHA-bound MERGE-READY verdict and never merges.
-2. Record merge intent in `.ship-run.log` before execution.
-3. Invoke exactly:
-
-   ```sh
-   .agentic-workflow/hooks/fullauto-merge.sh \
-     --pr <number> --run-id <run-id>
-   ```
-
-   The wrapper derives the PR head and forge default base itself. A project
-   with no forge-reported checks fails closed.
-4. The wrapper re-checks the current PR head, forge default base, SHA-bound
-   audit comment, decision file fetched from that head, clean/synchronized
-   branch, mergeability, and CI evidence. It
-   creates a namespaced marker under the git common directory only after those
-   checks, installs cleanup with `trap`, and removes the marker on success,
-   failure, signal, or already-merged recovery.
-5. After the forge reports MERGED, the wrapper posts one idempotent comment
-   marked `<!-- agentic-workflow:automerge head=<sha> -->`, containing the run,
-   audited head, and merge commit. That PR comment is the durable automerge log;
-   no repository log grows.
-
-Direct `gh pr merge`, `glab mr merge`, `git merge`, and forge-API merge calls
-remain blocked by the command guard at all times. There is no `.automerge` file
-and no persistent exception for a later manual `audit-pr` or shell session.
-
-Non-negotiable floors, evaluated fresh immediately before every merge —
-**fail-closed: a floor that cannot be evaluated counts as breached**:
-
-1. **Never merge red** — re-verify CI status via the forge CLI at merge time;
-   the audit verdict is evidence, fresh green CI is the precondition. In a
-   no-CI project the accepted evidence is a **fresh local verification-gate run
-   on the PR's exact head SHA**, recorded in the run log — without one of the
-   two, the floor is unevaluable and therefore breached.
-2. **Verdict freshness** — MERGE-READY must reference the PR's current head
-   SHA; any later commit forces a re-audit.
-3. **Sensitive-area pause** — PRs touching the declared sensitive set are
-   never auto-merged; the run continues around them and the report flags them.
-4. **Destructive-operation pause** — data-deleting or schema-destructive
-   diffs pause even when not in the declared set (users forget to declare it).
-5. **Forge refusal is a signal** — never bypass branch protection, never
-   force-push, never merge to anything but the default branch; a refused merge
-   parks the PR and is reported.
-6. **Budget floors still bind** — no cap is exempted by `--fullauto`.

package/skills/ship-roadmap/references/CLOSEOUT_AND_LOG.md

@@ -1,27 +0,0 @@
-## Close out and log the iteration
-
-5. **CLEAN CLOSE-OUT — verify before logging the stage complete.** A stage
-   only counts as advanced when the conductor has RUN and checked, on the
-   unit's branch: `git status --porcelain` → empty (no tracked modification
-   left behind — **docs included**: progress/testing/known-issues/roadmap
-   edits ride the stage's commit, never linger), and — once the unit's PR
-   exists — `git status -sb` after `git fetch` → not ahead of the remote
-   (every commit pushed; the PR and CI must see what was actually done).
-   A subagent that "finished" but left the tree dirty or the branch unpushed
-   did NOT finish: the conductor commits/pushes the remainder itself (same
-   stage, same iteration) or marks the stage partial. This check is
-   unconditional for REVIEW-SPEC/REVIEW-PLAN repairs, EXECUTE, REVIEW fix cycles,
-   PR, and AUDIT fix cycles.
-6. **LOG** one line to `.ship-run.log`; print `→ Next: <unit> (CONTINUE)` (the
-   canonical next-step shape; `CONTINUE` stays the loop's keep-going signal).
-   **Say WHY the turn is ending** — one explicit
-   line before the `→ Next:` block, always one of: "iteration complete — one
-   stage advanced (normal; re-invoke to continue)", "parked <unit>: <exact cap
-   hit — red-gate retries / review ping-pong / audit ping-pong / 3 partials /
-   planning contradiction>", or the terminal banner's reason. A turn ending
-   silently reads as a crash on agents without `/loop` — never leave the stop
-   unexplained.
-
-**Capacity guard:** an iteration that cannot finish its stage in one turn
-(e.g. an oversized review) writes a partial-stage marker and ends cleanly;
-three consecutive partials on the same stage parks the feature as blocked.

package/skills/ship-roadmap/references/FOUNDING.md

@@ -1,101 +0,0 @@
-## 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 (AGENTS.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 — founding IS batch design.** The interview's rounds 2–4
-(features, quality/ops, workflow) already collected every product-definition
-answer a `design-feature` capability closure would ask — founding is design
-for every feature it names, not a shortcut around it. 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 `idea`** (the locked founding decisions are the design record, but
-no per-feature `SPEC.md`/capability-closure artifact exists yet — that gets
-written JIT per feature, see ADVANCE → DESIGN below), depends-on, one-line
-summary with a **provisional XS/S/M/L size in the summary text** (the
-template's five-state legend and column schema stay exactly as they are —
-`plan-feature`/`plan-feature-scaffold` re-size 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 —
-founding scaffolds it immediately (composing `design-feature` +
-`plan-feature-scaffold` in-turn, pre-fed from the interview, no questions) so
-it lands directly at **status `planned`**, never left at `idea` — 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 its native `SHIP:`/`→ Next:` contract, and re-invoke while the turn is non-terminal — 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;
-    parse the native `SHIP:` banner and `→ Next:` block, then re-invoke
-    while the turn is non-terminal (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.

package/skills/ship-roadmap/references/GUARDRAILS.md

@@ -1,56 +0,0 @@
-## Guardrails
-
-- **Never work on the default branch** — the empty-repo initial scaffold commit
-  is the single exception. One PR per unit, never stacked; roadmap status flips
-  ride PR-bound commits only.
-- **Forge bodies are Markdown, not shell — never hand-escape.** Every explicitly
-  authorized issue, PR, or comment the run creates (subagent PRs, triage
-  comments) carries a body of **real Markdown**: backticks / `*` / `_` are
-  formatting, and a `\` before them renders literally (`` \`code\` `` instead
-  of `` `code` ``). Write the body to a file and pass **`--body-file <path>`**
-  to `gh issue create` / `gh pr create` / `gh issue comment` (or the declared
-  forge's equivalent) — never inline `--body "…"` or a quoted heredoc. Verify
-  with `gh … --json body` that no literal `` \` `` survived. (execute-phase
-  subagents already follow this; the conductor must too.)
-- **Never commit red; never merge red.** The gate and the floors are
-  unconditional — no flag, mode, or interview answer disables them.
-- **Never request or retain a direct-merge permission.** Fullauto calls only
-  the repository wrapper with command-scoped variables; a missing wrapper or
-  active guard blocks the run and routes to `init-workspace` upgrade.
-- **No stage ends dirty or unpushed.** The clean close-out check (Mode B
-  step 5) is part of every stage: tracked modifications — docs included — are
-  committed with the stage, and a PR-backed branch is pushed before the
-  iteration logs the stage complete. Merging while anything is uncommitted,
-  unpushed, or unpulled is forbidden: push, wait for CI, re-audit, then merge.
-- **The conductor never writes application code.** All implementation flows
-  through fresh cheap-tier `execute-phase` workers, one phase per context —
-  that keeps the cost model honest and `execute-phase` the single pathway.
-- **Tier discipline.** Compose in-turn only skills at ≤ opus/high;
-  implementation goes below the turn tier via explicit subagent model
-  overrides; `product-audit` is never run by this skill. `ultracode` is a
-  user-owned session setting — recommended, never claimed.
-- **Interview once, then silence.** Mid-run gaps — including a mid-run
-  `idea`/`defined` unit's product-half gaps in the DESIGN stage — are resolved
-  from the decision record and logged; contradictions park the feature with
-  the evidence recorded. Re-interviewing mid-run is forbidden, in DESIGN as in
-  every other stage: an undesignable unit is parked (`NEEDS_INPUT` on that
-  unit, `state: CONTINUE` on the run), never asked about. The recovery from a
-  wrong founding call is a reported stop and a human-restarted run.
-- **Scope discipline.** Defects and ideas discovered mid-run become report
-  proposals — never automatically-created issues or in-run side quests. Only
-  existing user/forge issues enter the issue sweep.
-- **Stack/architecture/forge agnostic; English artifacts** regardless of the
-  interview language; recommendations proportional to the interviewed scale,
-  recorded in the project's own docs so every sub-skill discovers them through
-  its normal Step 0.
-
-**Known limits (stated, not hidden):** subagent overrides pin the model but
-not the effort, so execution subagents inherit the session's effort — cost can
-drift if the session runs high. `/loop`'s stop-on-banner matching should be
-treated as a convenience, not a guarantee — iterations after a terminal banner
-are idempotent no-ops, and the loop can always be stopped manually. Budget caps
-count iterations, not tokens — and the count lives in the machine-local log, so
-it bounds each machine's run, not the run's lifetime across machines. Verdicts
-persist in the run log and feature docs,
-but a crash between PR close-out and review may re-run one receipt check —
-accepted cost, never a correctness risk.

package/skills/ship-roadmap/references/MODEL_ROUTING.md

@@ -1,16 +0,0 @@
-### Model routing
-
-| Stage | Tier | Mechanism |
-|---|---|---|
-| Interview, founding, roadmap creation | opus/high | this skill's frontmatter; composes `init-workspace` (equal tier), answers pre-fed |
-| Recovery, routing, logging | opus/high | in-turn (tiny token volume; a subagent would add cost, not save it) |
-| JIT feature design (mid-run `idea`/`defined` unit) | opus/high | compose `design-feature` + `plan-feature-scaffold` in-turn (equal tier, deriving only from `SHIP_DECISIONS.md` — no new questions) |
-| JIT feature planning | opus/high | compose `plan-feature` in-turn (its internals are opus/high–medium: ≥ holds) |
-| Product review (REVIEW-SPEC) | opus/high | `review-spec` in a **clean context** (fresh subagent or outside headless call) — never the turn that wrote the product half; tier equals or exceeds the author's, so the ≥ rule holds |
-| Plan review (REVIEW-PLAN) | opus/high | `review-plan` in a **clean context**, same rule; it judges the plan the previous stage froze |
-| Phase execution, single-pass, fixes | **cheap worker** | fresh context per phase following `execute-phase`; Claude branch maps this role to `sonnet`, portable drivers use their validated worker tier |
-| Final review/correction loop | opus/high | compose the manual path `/review-change`, then `/fold-findings` (only on `REVIEW-FAIL`), then re-run `/review-change`; it reuses a current exact-SHA receipt or reviews context-clean, and routes unresolved findings to `triage-issue --prioritize-now` |
-| Merge gate | opus/high | compose `audit-pr` in-turn (the highest-stakes automated verdict; must share one turn with the floor checks) |
-| Forge/git mechanics | — | Bash tool calls; no model judgment involved |
-| Final-report evidence gathering | haiku (optional) | fan-out subagents for grep-shaped per-feature log collection when ultracode is on; synthesis stays opus |
-| `product-audit` | opus/max | **never composed, never imitated by a subagent** — its effort (max) exceeds the conductor's (high) and a subagent override cannot carry `effort: max`. Hand-off only: the report prescribes when to run it. |

package/skills/ship-roadmap/references/PORTABILITY.md

@@ -1,34 +0,0 @@
-## Portability (agents other than Claude Code)
-
-The workflow is the contract; Claude Code features are conveniences. This skill
-leans on them harder than any other — here is the manual equivalent of each:
-
-- **No `/loop`** — two equivalent replacements, both vendor-neutral: (a) an
-  **external orchestrator** loops `/ship-roadmap --continue` headless and
-  routes its native fixed `SHIP:` banner plus closing `→ Next:` block (full
-  protocol + driver skeleton in `docs/workflow/ORCHESTRATION.md`); (b) manual
-  re-invocation after each iteration. Iterations are
-  stateless-by-reconstruction, so any driver is exactly equivalent; stop when
-  the first line is a terminal `SHIP:` banner. **Every iteration ending is
-  announced** — "iteration complete (normal; re-invoke to continue)" vs a
-  parked/terminal reason — so a stop is never ambiguous.
-- **No subagents** — execute phases sequentially: for each phase, one **fresh
-  headless invocation (or conversation) on a cheaper model** following the
-  installed `execute-phase` SKILL.md for exactly one phase (same two autopilot
-  overrides) — the external-driver pattern in `docs/workflow/ORCHESTRATION.md`
-  does exactly this. The conductor stages (recover/plan/PR/review/audit) stay
-  on your strongest model.
-- **No slash-command menu** — where this skill says `/<skill>`, open that
-  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
-  literally in the conversation the routing table assigns it (in-turn = this
-  conversation; subagent/hand-off = a fresh one).
-- **No per-skill `model:`/`effort:`** — the `#claude` branch's routing table pins these tiers; here, pick tiers yourself:
-  judgment stages on your **strongest** model, implementation on a cheaper one,
-  and `product-audit` always as its own maximum-effort run.
-- **Provider concurrency limits** — when spawning parallel subagents (or
-  parallel headless invocations), cap concurrency at the provider's documented
-  parallel-request limit per API key, leaving one slot free for the conductor
-  (e.g. a provider allowing 5 concurrent requests → at most 3–4 parallel
-  executors). An agentic loop spends one request per tool round-trip, so
-  parallel executors also eat the per-minute request budget fast; on a 429,
-  reduce parallelism before retrying rather than hammering the limit.

package/skills/ship-roadmap/references/RECOVERY_AND_SELECTION.md

@@ -1,94 +0,0 @@
-### 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/<NN-slug>/` + 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.
-2. **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.
-3. **SELECT one unit.** Priority order, first match wins:
-   1. **Urgency labels first (feature 15, injection-safe).** Read
-      `workflow-status`'s `detail.urgent` (labels-only, presence-only —
-      never derived from issue text; see `skills/triage-issue/SKILL.md`, the
-      sole owner of the `urgent`/`fix-next` vocabulary):
-      - Any open issue labeled **`fix-next`** → its fix jumps to the head of
-        the queue exactly like a blocking fix below (`plan-fix` →
-        `execute-phase --fix`), **no interrupt** of the in-flight unit — it
-        waits for the current stage to finish this iteration, then is
-        SELECTed next.
-      - Any open issue labeled **`urgent`** → run the canonical pause-vs-finish
-        rubric in `docs/workflow/ORCHESTRATION.md` **by reference, never
-        forked here** — feed it the issue content plus `detail.urgent
-        .interruptibility` for the current in-flight unit.
-        `INTERRUPT_NOW` → park the in-flight unit (WIP commit + `progress.md`
-        note, same as any voluntary park) and SELECT the urgent issue's fix as
-        this iteration's unit instead. `FINISH_FIRST` → this iteration
-        proceeds normally (steps below); the urgent fix is queued head-of-line
-        for the **next** iteration, same as `fix-next`.
-      - No `urgent`/`fix-next` issues in `detail.urgent` → fall through to the
-        normal priority order below.
-   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.
-   3. An in-progress feature's next pending stage.
-   4. The next feature at status `idea` **or** `planned` 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). A `defined`-but-not-`planned` row is treated the
-      same as `idea` here — its design exists but its planning artifacts
-      don't, so it still needs a scaffold pass before PLAN.
-      **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.
-      → `idea`/`defined`: DESIGN first (see ADVANCE). `planned`: → REVIEW-SPEC/
-         REVIEW-PLAN if its receipt for that stage is missing or stale, else PLAN/EXECUTE
-      directly.
-   5. **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
-         proposals/trade-offs. Residue without an existing issue remains a
-         deduplicated **proposal** in the report; the run never creates backlog
-         to make inventory look complete. Log existing issue numbers and
-         proposal sources separately.
-      2. **TRIAGE (compose `triage-issue` in-turn, equal tier).** Classify
-         each existing 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 and untracked residue become report proposals,
-         never in-run scope or automatically-created issues).
-      3. **SHIP the fix-now issues** one unit at a time through the normal
-         stages (`plan-fix` → REVIEW-PLAN → EXECUTE (`--fix`) → PR → REVIEW → AUDIT), same
-         budget caps, floors, and merge policy as features.
-   6. Nothing startable → `SHIP: BLOCKED` with the **unblock map** ("merging
-      issue `#<n>` unblocks features `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.