@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/review-security/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: review-security
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal security review pass of the agentic-workflow review pack — composed
+  in-turn by review-change and product-audit; not a menu entry. Checks secrets,
+  input validation, injection, authn/authz, PII exposure, and dependency risk
+  on the changed surface. Findings only; never edits code.
+---
+
+# Review Security (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+✓ No secrets/credentials/tokens in code, config, tests, or fixtures (grep the
+  diff for key-like strings)
+✓ Every external input on the changed paths is validated/sanitized before use
+✓ No injection vectors (SQL/command/path/template) — parameterized/escaped,
+  never concatenated
+✓ AuthN/AuthZ enforced on every new/changed endpoint or entry point (cite
+  where)
+✓ No PII or secrets written to logs/error messages on the changed paths
+✓ Webhooks/callbacks verify signatures before processing
+✓ Rate limiting / abuse controls considered where a new public surface appears
+  (n/a if none)
+✓ New/updated dependencies pinned and free of known-critical advisories (state
+  how you checked)
+✓ Error responses don't leak stack traces or internal paths
+✓ Unsafe deserialization / dynamic evaluation of untrusted data absent
+
+## Return exactly
+
+```
+REVIEW SECURITY — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/review-seo/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: review-seo
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal SEO review pass of the agentic-workflow review pack — composed
+  in-turn by review-change and product-audit; not a menu entry. Checks changed
+  web pages/routes for indexability, metadata, and structured data — applies
+  only to public web surfaces. Findings only; never edits code.
+---
+
+# Review SEO (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+- ✓ Read the project's SEO doc first (e.g. `docs/frontend/SEO.md`) — n/a all
+  items with the reason if the product has no public web surface
+- ✓ Every new/changed public page has a unique title and meta description
+  within the project's declared lengths
+- ✓ Canonical URL correct on new/changed routes (no accidental duplicates)
+- ✓ Indexability intended = indexability actual (robots/noindex/sitemap state
+  matches the page's purpose)
+- ✓ One h1 per page; heading levels don't skip
+- ✓ Structured data valid for the content type the project declares (cite the
+  validator output when run)
+- ✓ Links crawlable (real hrefs, not click handlers) on changed navigation
+- ✓ Images on changed pages have descriptive filenames/alt where the SEO doc
+  requires
+- ✓ No render-blocking regression for primary content (content present without
+  JS where the project declares SSR/SSG)
+
+## Return exactly
+
+```
+REVIEW SEO — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/review-verify/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: review-verify
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal run-it verification review pass of the agentic-workflow review pack —
+  composed in-turn by review-change and product-audit; not a menu entry. Runs
+  the project's gate and the changed behavior for real — commands, exit codes,
+  observed output — instead of assuming; what cannot be executed goes to the
+  manual checklist. Findings only; never edits code.
+---
+
+# Review Verify (internal)
+
+Composed by `review-change` / `product-audit` within their conversation — on any
+agent, follow this file inline as the routed step. **Findings only; never edits,
+never refactors.**
+
+## Scope
+
+The diff or path/glob the caller passes; default the current change vs the
+default branch. State the scope at the top of the returned table.
+
+## Checklist (evaluate EVERY item — none is optional; n/a must be stated)
+
+✓ The project's verification gate ran in THIS review (type-check, tests, build
+  per the project's declared commands) — paste exit status per command
+✓ The change's primary claimed behavior was exercised for real (run the
+  CLI/endpoint/function; paste the actual observed output)
+✓ At least one failure-mode from the SPEC's dev scenarios was reproduced (bad
+  input, missing file, error path) and behaved as specified
+✓ New/changed tests actually fail when the implementation is reverted or
+  broken (mutate or stash to prove they assert something — restore after)
+✓ No test was skipped/disabled to get green (grep for skip/only/todo markers
+  in the diff)
+✓ The build artifact/dev server starts cleanly (no new warnings that indicate
+  breakage)
+✓ Anything that can only be confirmed by a human (visual, device, locale,
+  load) is listed explicitly under "Manual" — never silently dropped
+
+## Return exactly
+
+```
+REVIEW VERIFY — scope: <scope>
+
+| # | Finding | Sev | Evidence | Suggested fix |
+|---|---------|-----|----------|---------------|
+| 1 | <what>  | critical|major|minor | <file:line> | <smallest action> |
+
+Checklist: <n> evaluated, <n> pass, <n> findings, <n> n/a (<which + why>)
+Summary: <1-2 sentences>
+Manual (a human must check): <bullet list, or "none">
+Decision: PASS | FAIL
+```
+
+FAIL if any critical or major finding is open; PASS otherwise. Minor findings
+never block — they route to the caller's triage step.
+
+## Done when
+
+- Every checklist item was evaluated with evidence (file:line or command output)
+  or explicitly marked n/a with the reason.
+- The fixed-format block above is returned — nothing more, nothing less — and
+  no code was changed.

package/skills/ship-roadmap/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ship-roadmap
+user-invocable: true
+version: 4.0.2
+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: `CLAUDE.md`/`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`; `loop-review-fold`; 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

@@ -0,0 +1,90 @@
+## 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.
+   - **PLAN** — compose `plan-feature` in-turn via its scoped path (equal
+     tier). Every unit reaching PLAN is already `planned`-bound (DESIGN ran
+     first for any `idea`/`defined` unit), so `plan-feature`'s own redirect
+     gate always 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.
+   - **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 `loop-review-fold` in-turn (equal tier) once, over
+     the complete PR candidate. 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.
+
+   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)
+   skips straight to PLAN. Every size follows [DESIGN] → 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.

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

@@ -0,0 +1,64 @@
+### 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

@@ -0,0 +1,26 @@
+## 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 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

@@ -0,0 +1,101 @@
+## 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 — 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.