@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/loop-review-fold/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: loop-review-fold
+user-invocable: true
+version: 2.0.0
+argument-hint: <NN> | --fix <issue-number>
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Run the simple review-change/fold-findings loop for an open feature or fix
+  unit. Inspect persisted review evidence first so a previous review resumes
+  with fold-findings instead of reviewing the same candidate again. Unresolved
+  findings go to triage-issue with an immediate-fix instruction; oversized
+  findings become a user-confirmed plan-feature or plan-fix replan with new
+  phases. Triggers: "loop-review-fold", "review and fold this PR", "run the
+  review fold loop".
+---
+
+# Review / Fold Loop
+
+Run one small state loop over the current feature or fix unit:
+
+```text
+review-change ── findings ──▶ fold-findings ── changed HEAD ──▶ review-change
+       ▲                              │
+       └──────── current PASS ◀───────┘
+                                      └─ unresolved ─▶ triage-issue
+```
+
+This skill is a router, not a third review or repair implementation. It reads
+the durable evidence left by `review-change` and `fold-findings`, chooses the
+next action, and stops when a user decision or manual phase execution is
+required. Never merge, create an unrelated issue, or silently discard a
+finding.
+
+## Turn contract
+
+```text
+✓ The feature/fix unit, branch, PR, current HEAD, acceptance, and finding ledger were checked
+✓ The first action was selected from persisted evidence: PASS, review-change, or fold-findings
+✓ review-change ran only when no current review result required fold-findings first
+✓ A successful fold was followed by review-change on the new HEAD
+✓ Every unresolved finding is named and routed to triage-issue --prioritize-now
+✓ An oversized finding routes to plan-feature or plan-fix, new P<n> phases, and manual user execution
+✓ No merge, unrelated issue, acceptance weakening, or silent finding drop occurred
+✓ The fixed result and the closing → Next: block are the final output
+```
+
+Any unchecked box means the turn is not done.
+
+## When to use
+
+Use after `execute-phase` opens the unit PR, or when the user asks to review and
+fold an open feature or fix. The argument identifies the unit:
+
+- `/loop-review-fold <NN>` for a feature unit.
+- `/loop-review-fold --fix <issue-number>` for a fix unit.
+
+Do not use this entrypoint to edit this skill, inspect its implementation as the
+requested deliverable, or invent a target when the unit argument is missing.
+
+## Step 0 — Discover the project (always first)
+
+Read the target project's agent guide and documentation map. Then verify the
+target unit, current branch, open PR, remote HEAD, frozen acceptance artifact,
+the latest `review-change` result/receipt, and the unit's `review-findings.md`.
+Use repository and forge commands required by the project's own conventions.
+Narration, an old chat result, or a clean worktree alone is not evidence.
+
+If the target, PR, acceptance, or ledger cannot be verified, stop with
+`BLOCKED` and name the exact missing input and recovery command. Do not create
+replacement artifacts in this router.
+
+## Process
+
+Apply this first-match table exactly:
+
+| Persisted state on the current HEAD | First action |
+|---|---|
+| Exact current `REVIEW-PASS`, matching acceptance, and no open finding rows | `PASS`; do not run either skill |
+| A review result exists for this HEAD and it leaves any `folded: no` row | `fold-findings` on the complete open queue |
+| No usable current review result and no open queue | `review-change` on the current HEAD |
+
+Then continue as follows:
+
+1. Run the selected skill in its own fresh context and follow that skill's
+   contract literally. This loop does not copy its internal checklist.
+2. If `review-change` returns `REVIEW-PASS`, verify its exact-HEAD receipt and
+   zero open rows, then return `PASS`.
+3. If `review-change` returns findings, run `fold-findings` for every open
+   `fix-now` row. Do not start another review before that queue is processed.
+4. If `fold-findings` changes and pushes the candidate, run `review-change` on
+   that new HEAD. Never review an unchanged HEAD a second time.
+5. If any finding remains unresolved (`DISPUTED`, `BLOCKED`, `REPLAN`, or an
+   open row left after folding), stop the loop and hand every such ID to:
+
+   ```text
+   /triage-issue --prioritize-now <unit-or-fix> F1 F2 ...
+   ```
+
+   Tell `triage-issue` to try to resolve every named finding immediately. It
+   may route a small correction back to the current unit, but it must not hide,
+   downgrade, or postpone a review finding merely to finish the loop.
+6. When the smallest correct correction is too large for the current fold,
+   `triage-issue` must choose a replan route: re-run `/plan-feature <slug>` for
+   a feature or `/plan-fix <issue-number>` for a fix, append explicit new
+   `P<n>` phases to the unit's SPEC, and stop. The loop then asks the user to
+   execute those phases manually with `/execute-phase <unit> P<n>` (or the
+   fix equivalent) before invoking this loop again.
+
+Do not use a hidden retry count. The loop ends at the first `PASS`, blocked
+prerequisite, unresolved finding, or required manual replan. A later user
+invocation starts from the newly persisted state.
+
+## Fixed output contract
+
+Return exactly:
+
+```text
+REVIEW-FOLD LOOP — PASS | TRIAGE-REQUIRED | BLOCKED
+Unit: <unit> · PR: <url> · HEAD: <sha>
+First action: PASS | review-change | fold-findings
+Review: <PASS | FAIL | not-run> · Fold: <changed | unchanged | not-run>
+Unresolved: <F1 + F2 + … | none>
+Evidence: <one concise line explaining the selected action and result>
+
+→ Next: <one concrete command or user action> — <why>
+  · <alternative when applicable>
+```
+
+Use `TRIAGE-REQUIRED` whenever a finding needs `triage-issue`, a replan, or a
+user decision. Replace every placeholder, list each actual finding ID exactly
+once joined with ` + `, and never emit a literal ellipsis.
+
+## Guardrails
+
+Allowed: read target evidence, invoke `review-change`, invoke `fold-findings`,
+and route unresolved findings to `triage-issue`.
+
+Forbidden: implementing a fix in this router, editing review classifications,
+marking findings folded, creating unrelated issues, weakening acceptance or
+checks, merging, or claiming that a user has implemented newly planned phases.
+
+## Relationship to other skills
+
+`execute-phase` hands off here after a unit PR opens. `review-change` owns
+read-only classification and the SHA-bound pass receipt. `fold-findings` owns
+the actual correction and ledger tick. `triage-issue --prioritize-now` owns the
+decision for unresolved findings and routes oversized work to `plan-feature` or
+`plan-fix`; the user then executes the appended phases manually.
+
+## Portability (agents other than Claude Code)
+
+If fresh contexts or subagents are unavailable, invoke each delegated skill in
+a new conversation and re-read the persisted HEAD, receipt, and ledger before
+continuing. If the host has no slash-command menu, open each named `SKILL.md`
+and follow it literally. Never claim a clean review after the same context
+implemented the correction.
+
+## Done when
+
+The current HEAD has a verified `REVIEW-PASS` and no open findings, or every
+remaining finding has a concrete triage/replan hand-off and the user has been
+told to implement the new phases manually.
+
+→ Next: print the matching terminal route from the fixed output contract — never send a non-PASS result to audit-pr
+  · PASS → /audit-pr — consume the current exact-HEAD REVIEW-PASS
+  · TRIAGE-REQUIRED → /triage-issue --prioritize-now <unit> F<k> — resolve every actual unresolved finding, then plan/execute new phases manually
+  · BLOCKED → the exact recovery command — supply the missing target, PR, acceptance, or ledger input before re-running the loop

package/skills/orchestration-envelope/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: orchestration-envelope
+user-invocable: false
+version: 2.0.2
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal machine-result contract for headless agentic-workflow drivers. The
+  executable source is @gtrabanco/agentic-workflow-schema: strict Envelope v2
+  for workflow-status, compact SkillOutcome v1 for driven work, compatibility
+  parsing, and deterministic document snapshots. Not a menu entry.
+---
+
+# Machine result contract (internal)
+
+Interactive skills remain text-first. A headless driver obtains a compact,
+validated result at the boundary; it does not add a repeated JSON section to
+every user-facing skill.
+
+The canonical [Turn contract](references/TURN_CONTRACT.md) remains here for
+the executor and review skills that load it.
+
+The executable source of truth is
+[`@gtrabanco/agentic-workflow-schema`](../../packages/agentic-workflow-schema/):
+types, JSON Schemas, `renderOutputInstruction(skill)`, `parseTurn(input)`, and
+`compileWorkflowSnapshot(input)`. This document states the policy only; do not
+copy a second schema here.
+
+## Output profiles
+
+`WORKFLOW_SKILL_PROFILES` is the authoritative inventory.
+
+- `workflow-status` always returns the strict **Envelope v2** sensor result.
+  Its envelope includes the detailed project view under `detail`.
+- The other driver-invoked skills return **SkillOutcome v1** only when the
+  driver appends `renderOutputInstruction(skill)` to that invocation. It has
+  the small model-owned fields: outcome, next intent/targets, blockers,
+  questions, discoveries, and evidence references.
+- `ship-roadmap` is the conductor, not a worker profile: it keeps its native
+  terminal `SHIP:` banner and is parsed by its own fixed turn contract.
+- Interactive invocations emit their normal human-readable reports; no driver
+  result is required.
+
+Both results are one final fenced `json` block. The package rejects unknown
+keys at the routing boundary. Repository facts are never reconstructed from
+model prose: the driver compiles `WorkflowSnapshot v1` from its selected,
+versioned documents and caller-supplied repository facts.
+
+## Driver protocol
+
+1. Read the profile and append `renderOutputInstruction(skill)` only for a
+   driven invocation.
+2. Pass the final response to `parseTurn({skill, text, context})`. Keep the
+   returned source and diagnostics with the run journal.
+3. On an absent, malformed, or invalid machine result, re-invoke the same
+   session once with: `Emit only the machine result for the turn above.`
+4. Parse the repair reply. A second failure is driver-level `FAILED`; never
+   retry indefinitely and never turn arbitrary prose into workflow facts.
+
+Compatibility is deliberately narrow: it can repair documented legacy v2
+shapes only when the missing value is mechanically knowable. A nonzero issue
+count without issue identities, an unmatched numeric unit id, or unrelated
+prose remains invalid and is surfaced to the driver.
+
+## Contract evolution
+
+- Envelope v2 is strict for new drivers. `detail` is required (usually `null`)
+  and skill-specific extensions live inside it; `design_candidates`, for
+  example, is `detail.design_candidates`, never a root key.
+- `workflow-status` retains Envelope v2 for existing sensor consumers.
+  `parseEnvelope()` remains the legacy-compatible package API; new consumers
+  use `parseEnvelopeV2Strict()` or `parseTurn()`.
+- `SkillOutcome v1` and `WorkflowSnapshot v1` are separate, versioned JSON
+  Schemas. A breaking change to any published contract is a package major.
+
+## Normalized Repository State
+
+Drivers call `discover-repository-state` before planning and retain the frozen
+`docs/workflow/REPOSITORY_STATE.md` reference. `WorkflowSnapshot v1` preserves
+unknowns, provenance, and declared contradictions; a driver routes a
+contradiction to `resolve-repository-state` rather than silently replacing it.

package/skills/orchestration-envelope/references/TURN_CONTRACT.md

@@ -0,0 +1,21 @@
+# Canonical Turn Contract (orchestration-envelope owner)
+
+## Turn contract — verify before ending the turn
+
+```
+✓ 1. Branch verified FIRST (`git branch --show-current` RUN, output pasted; default branch → new branch created before edits). Never work on main/master.
+✓ 2. All pre-edit gates (phase-lint, architectural invariants, dependency) RUN, plus frozen acceptance verified, with commands/exit codes pasted. Any FAIL without an allowed override → STOP.
+✓ 3. `git add`, `git commit -m "<type>(<scope>): <summary>"` EXECUTED; SHA pasted. Commits you did not run do not count.
+✓ 4. Unit finished (single-pass/--fix/final phase)? `git push`, `gh pr create` EXECUTED; PR URL printed in chat (with --body-file, real Markdown, Closes #N). Roadmap/fix-index updated to `done · [#<pr>](<pr-url>)` in follow-up commit. For mid-phase push rules when a PR is already open, see per-consumer supplement (§ Push policy supplement).
+✓ 5. Clean-tree check LAST (`git status --porcelain` RUN, output pasted). No uncommitted changes (code or docs). PR branch not ahead of remote.
+✓ 6. Artifact language: explicit user > project docs > English.
+✓ 7. Descope guard applied to every issue created this turn (dated ## Amendments in SPEC before issue).
+✓ 8. Out-of-scope findings classified per Opportunistic finding policy, recorded in decisions.md; proposals created no issue without explicit user triage.
+✓ 9. Closing `→ Next:` block printed as ABSOLUTE last output.
+✓ 10. Machine result emitted if driver requested (package output profile).
+✓ 11. No reconstruction from memory — missing reference → STOP.
+```
+
+**Single owner:** orchestration-envelope/references/TURN_CONTRACT.md. All skills load this + skill-specific additions only. Duplication forbidden. Missing reference = STOP.
+
+**Push policy supplement:** Box 4 covers the end-of-unit push. Some consumers (e.g. `execute-phase/references/PREFLIGHT.md`) define additional push rules for mid-phase commits when a PR is already open — those per-consumer supplements extend this contract and must be loaded alongside it by the consumer skill.

package/skills/phase-contract/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: phase-contract
+user-invocable: false
+version: 1.0.1
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal contract: the single owner of the eight phase-lint rules, the fixed
+  PASS/BLOCKED result, and the normalized phase fingerprint. Consumed by
+  plan-feature-scaffold, plan-fix, and execute-phase. Not a menu entry.
+---
+
+# Phase Contract (internal)
+
+The one authoritative owner of phase shape for this workflow. Planners lint
+every phase they emit against the eight rules below; `execute-phase` re-checks
+the same rules before any edit. Nothing else may define what a valid phase is.
+
+## When to use
+
+- `plan-feature-scaffold` — lint every phase of a feature plan before emission.
+- `plan-fix` — lint every phase of a fix SPEC before commit.
+- `execute-phase` — phase-lint pre-flight guard before editing a phase.
+- Templates store the contract version + fingerprint + lint result, never the
+  eight rules (they point here).
+
+## The eight phase-lint rules
+
+Every implementation phase must pass all 8 boxes before it is emitted (planner
+skills) or executed (`execute-phase` pre-flight). Fail-closed: any unticked box
+blocks emission/execution until the phase is re-cut or split.
+
+1. **Title names ONE deliverable** — FAIL if it joins nouns with `+`, `,`, `&`,
+   `and`/`y`, or `/`.
+2. **One declared layer** — each phase declares exactly one of the fixed enum
+   `schema/db | domain | api | ui | config/infra | docs | hardening | close-out`;
+   FAIL if any task's target file belongs to another. Tests for the phase's own
+   layer belong to the phase; a test-only phase declares `hardening`.
+3. **≤ 8 tasks** (close-out phase: ≤ 10, only the literal close-out chain).
+4. **One checkbox = one deliverable** — FAIL if a task contains a `→` chain of
+   implementation steps, enumerates > 3 cases/scenarios, or creates > 1 file of
+   distinct concerns.
+5. **Zero decision words** — FAIL on `Decide`, `choose`, `OR` between
+   alternatives, `If … then <change scope>`.
+6. **No conditional scope mutation** — a task may not move work between phases
+   at runtime.
+7. **No external/manual gates inside implementation phases** —
+   human/out-of-repo verifications live in the hardening/close-out phase,
+   marked `manual`.
+8. **Machine-checkable done-when** — every phase ends with one verifiable
+   invariant (a command + expected outcome).
+
+## Result — fixed PASS/BLOCKED output
+
+```text
+Phase-lint: PASS (8/8)
+```
+
+or, on the first failing box:
+
+```text
+Phase-lint: BLOCKED — box <n>: <one-line reason>
+```
+
+A BLOCKED phase is re-cut or split; it is never emitted, committed, or executed
+as-is (no `--force` bypass exists for a non-atomic phase — that decision belongs
+to the user).
+
+## Normalized phase fingerprint
+
+Each phase's fingerprint is a deterministic string over the phase's shape:
+`P<n>:<layer>:<n-tasks>:<title-deliverable>`. It binds the lint result to the
+exact phase version a plan committed to — templates and plans record
+`Phase-lint: PASS (8/8) · fingerprint <fingerprint>` so later re-lints and
+`execute-phase` can confirm nothing in the phase shape drifted since planning.
+
+## Guardrails
+
+- Sole owner of the eight rules — planners and executor point here, never carry
+  their own copy.
+- Never relax a rule to let a phase pass; re-cut the phase instead.
+- Docs only — no code, no branch.

package/skills/plan-feature/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: plan-feature
+user-invocable: true
+version: 3.5.1
+argument-hint: <NN-slug | #N> | --from-issue N | --scaffold <slug> | --next
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Route designed features or issues into engineering planning and roadmap
+  registration; undesigned work stops at design-feature. Supports `--next`,
+  `--from-issue`, and `--scaffold`. Triggers: "plan-feature", "plan a feature",
+  "plan the next roadmap feature", "create SPEC and TASKS".
+---
+
+# Plan Feature (router)
+
+The engineering-planning door for a feature whose product definition already
+exists. Routes to a focused internal step so only the work you need runs (no
+fat single skill). **Docs only — no code, no branch.** Product definition
+(raw-idea interview, capability closure) is `design-feature`'s job, not this
+one — the routed redirect gate enforces that split.
+
+## Turn contract — verify before ending the turn
+
+```
+✓ The redirect gate ran FIRST, before any SPEC edit: undesigned input → STOP,
+  print the fixed `/design-feature <slug>` block, do nothing else this turn
+✓ Designed input only: engineering half filled, artifacts written, and the
+  roadmap entry registered (number, order, deps verified)
+✓ If `plan-feature-scaffold` ran this turn: the roadmap row was re-read
+  AFTER the write and literally reads `planned` — a dropped `defined→planned`
+  write fails this box; do not end the turn until it's fixed
+✓ The dependency & blocker check was RUN and its result decides which closing block is printed
+✓ An unmet dependency? The closing block lists the complete dependency chain, deepest first, joined with ` + `
+✓ 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
+```
+
+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).
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then read
+what THIS skill needs: the **roadmap** (`docs/features/ROADMAP.md`), so routing
+and roadmap registration match the project's real layout.
+
+## Progressive loading — route before planning
+
+The reference allowlist is exactly the two paths below:
+
+1. Every invocation: read [redirect gate and routing](references/ROUTING.md),
+   apply the status gate first, and stop on its exact block when instructed.
+2. Any route that can write planning artifacts: after the redirect gate permits
+   routing, consume the [planning preflight](<../planning-preflight/SKILL.md>) —
+   it owns the normalized repository state read and the ONE final architectural
+   classification — before composing an internal step, including the
+   issue-derived route.
+3. Before composing an internal step: load the [phase contract](<../phase-contract/SKILL.md>)
+   so every SPEC written this turn carries the canonical 8-box phase-lint and
+   the normalized phase fingerprint.
+
+Do not load planning gates after a redirect stop. Both resources are normative,
+one hop from this file, and fail closed when missing.
+
+## Process
+
+1. **Redirect gate** from `ROUTING.md` — always first.
+2. **Route** from the same resource. For issue input, resolve and validate the issue
+   identity only; after the [planning preflight](<../planning-preflight/SKILL.md>)
+   confirms that planning may write, compose the from-issue internal to produce
+   a **filled, sized SPEC product half**; then invoke `plan-feature-scaffold`,
+   which fills the engineering half and scales the artifacts to the SPEC's size
+   (XS/S → SPEC-only; M/L → full set) and registers the roadmap. The
+   already-designed scoped path runs `plan-feature-scaffold` directly. Every
+   path holds **one immutable planning context** — the roadmap snapshot taken
+   before writing (and one issue payload when `--from-issue`) — reused across
+   the internal steps; never re-fetched mid-plan.
+3. **Confirm roadmap.** Verify the feature is registered in
+   `docs/features/ROADMAP.md` with the right number, ordering, and dependencies;
+   if any of the three is missing or wrong, fix the entry now — never leave
+   registration for later.
+4. **Dependency & blocker check (always, before recommending execution).**
+   - Walk the feature's `Depends on:` closure (transitively): every dependency
+     must be `done` **and merged**. Any unmet → the closing block recommends
+     building the deepest unmet dependency first, NOT this feature.
+   - Check the fix index + open issues (forge CLI) for fix-now items touching
+     the same modules this SPEC names. Any hit → the closing block recommends
+     `/plan-fix <n>` before execution ("building on a known defect bakes it in").
+   - Planning itself never blocks on either — the SPEC/artifacts are still
+     written; only the **recommended next step** changes.
+5. **Print the next step** per the check above (see Done when).
+
+## Guardrails
+
+- Docs only — no code, no branch (that is `execute-phase`).
+- **Never plan an undesigned feature** — the redirect gate has no bypass flag,
+  ever. Do not add one, even if asked; point at `/design-feature` instead.
+- Don't re-ask what a flag, the issue, or the docs already settle.
+- Surface conflicts (numbering clashes, dependency cycles, scope overlap) before
+  writing, not after.
+- Otherwise per the project's **Workflow conventions** (docs-language).
+
+## Internal steps (not user-invocable)
+
+- `plan-feature-from-issue` — issue → scoped SPEC product half, `Closes #N`.
+- `plan-feature-scaffold` — SPEC → engineering half + full artifact set +
+  roadmap entry.
+
+These run **within this same conversation** (that's what "composing" means) —
+on any agent, just follow their `SKILL.md` inline as the routed step. The
+raw-idea interview that used to be an internal step of this router is retired
+— see `docs/workflow/MIGRATION.md`; that logic now lives in `design-feature`,
+a user-facing skill in its own right (product definition is its own pipeline
+stage, not an internal routing detail of this one).
+
+## Portability (agents other than Claude Code)
+
+The workflow is the contract; Claude Code features are conveniences. On an
+agent that lacks one, apply the fallback — never skip the step the feature
+enables:
+
+- **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 a fresh conversation: hand-offs assume a clean context. The
+  internal steps above are the exception — they run inline, in this one.
+- **No per-skill `model:`/`effort:`** — on the `#claude` branch the frontmatter pins these tiers; here, pick tiers yourself:
+  planning is judgment work — run it on your **strongest** model. The
+  execution it hands off to may run cheaper.
+
+## Relationship to other skills
+
+- **Redirects to** `design-feature` when the redirect gate stops on an
+  undesigned feature — never composed in-turn (planning-class, ≥-tier hand-off).
+- `triage-issue` routes here to promote an issue to a feature (still subject to
+  the redirect gate if the promoted issue is undesigned).
+- `execute-phase` executes the phases afterward (`audit-docs` audits anytime).
+
+## Done when
+
+- The redirect gate ran, and if it stopped, nothing else in this turn touched
+  the SPEC.
+- Designed input only: a planned feature with its full artifact set exists and
+  is roadmap-registered — **and the roadmap row was re-read after the write and
+  literally reads `planned`** (never assumed from having run the write step).
+- The dependency & blocker check ran, and **the closing `→ Next:` block matches
+  its result** — clean:
+
+  ```
+  → Next: /execute-phase <NN> — execute every remaining phase and open the PR
+    · explicit atomic mode → /execute-phase <NN> P1
+    · adjust scope first → re-run /design-feature <slug>   · audit the planning docs → /audit-docs
+  ```
+
+  already-planned feature (redirect gate stopped, never re-scaffolded):
+
+  ```
+  → Next: /execute-phase <NN> — this feature is already planned; execute every
+    remaining phase, don't re-plan it.
+    · explicit atomic mode → /execute-phase <NN> P1
+  ```
+
+  undesigned feature (redirect gate stopped):
+
+  ```
+  → Next: /design-feature <slug> — this feature has no completed product design yet
+    (capability closure not done). Design it first; then re-run /plan-feature <slug>.
+  ```
+
+  unmet dependency and/or blocking fix-now issue:
+
+  ```
+  Dependency chain (deepest first): <deepest> + <dependency> + <NN> (replace with every actual member; never print `…`)
+  → Next: /plan-feature <deepest-unmet-dep> (or /execute-phase <deepest-unmet-dep>) — build the
+    complete dependency chain first: <deepest> + <dependency> + <NN>
+    · blocking fix-now issue #<n> in the same area → /plan-fix <n> before executing
+    · proceed anyway → /execute-phase <NN> --force (the gate logs the override)
+  ```

package/skills/plan-feature/references/ROUTING.md

@@ -0,0 +1,83 @@
+## Redirect gate (always, before routing)
+
+Before any other step, resolve the target slug/issue. An issue input
+(`--from-issue <N>` or issue URL/number) resolves and validates the issue
+identity only; it does not invoke `plan-feature-from-issue` here. The parent
+must consume the [planning preflight](<../../planning-preflight/SKILL.md>) and
+confirm that planning may write before composing that internal writer. The
+internal step supplies the feature slug for the later roadmap gate. For other
+inputs, read **the roadmap status** (`docs/features/ROADMAP.md` → the five-state machine
+`idea/defined/planned/in-progress/done`) — the **primary** gate signal. The
+SPEC's `## Design status` marker is the SPEC-local record and the
+**legacy-compat fallback** only (see step 6 below), never the primary check:
+
+1. **Roadmap row status `defined`** → proceed to Routing below (the product
+   half is designed; the engineering half still needs scaffolding).
+2. **Roadmap row status `planned`** (SPEC + artifacts already present) →
+   **STOP**. Never invoke `plan-feature-scaffold` — re-scaffolding an
+   already-planned feature is the re-plan-loop bug this gate exists to close.
+   Print exactly:
+
+   ```
+   → Next: /execute-phase <NN> — this feature is already planned; execute every
+     remaining phase, don't re-plan it.
+     · explicit atomic mode → /execute-phase <NN> P1
+   ```
+3. **Roadmap row status `in-progress`** → **STOP**. Print exactly:
+
+   ```
+   → Next: /execute-phase <NN> <next-phase> — this feature is already being
+     implemented; resume the current phase, don't re-plan it.
+   ```
+4. **Roadmap row status `done`** → **STOP**. Print exactly:
+
+   ```
+   → Next: nothing — <NN>-<slug> already shipped (roadmap status `done`).
+   ```
+5. **Roadmap row status `idea`, or no row at all** → **STOP**. Print exactly:
+
+   ```
+   → Next: /design-feature <slug> — this feature has no completed product design yet
+     (capability closure not done). Design it first; then re-run /plan-feature <slug>.
+   ```
+
+   No bypass flag exists for this gate — an undesigned feature is never
+   planned by this skill, under any flag or instruction.
+6. **Legacy compat.** A roadmap row still reading a plain `planned` with no
+   five-state history (predates this repo's roadmap-status-machine feature):
+   fall back to the SPEC marker — `## Design status: designed` and Capability
+   closure filled → treat as `defined`+`planned`, STOP per step 2 above (a
+   legacy `planned` row is still already-planned — hand off to
+   `/execute-phase`, never re-scaffold). Marker missing/`not designed`/closure
+   empty → treat as `idea`, STOP per step 5. See `docs/workflow/MIGRATION.md`.
+7. **A raw idea with no slug at all** (nothing to check) → the same STOP
+   applies: print the block above pointing at `/design-feature "<idea>"`
+   instead of a slug.
+
+## Routing
+
+Once the gate passes, pick the mode — first match wins:
+
+1. **Flag forces it** (skip detection): `--scaffold <slug>`, `--next`.
+2. **Issue input** — `--from-issue <N>`, an issue URL, or a bare numeric argument
+   `<N>` (for example, `131`) selects the issue-derived route; detection itself
+   does not compose `plan-feature-from-issue`. The parent route owns the
+   [planning preflight](<../../planning-preflight/SKILL.md>) consumption and must
+   confirm that planning may write before it composes `plan-feature-from-issue`,
+   then `plan-feature-scaffold`.
+3. **Scoped** — an existing, designed roadmap slug or a filled `SPEC.md` →
+   `plan-feature-scaffold`.
+4. **`--next` / no input** — read the roadmap, take the next `defined` entry
+   (the units that still need engineering planning — a `planned` row is
+   already scaffolded); apply the redirect gate to it, then scaffold.
+5. **Ambiguous** — ask one question, then route.
+
+### Example (routing)
+
+| You run | Detected | Routes to | Then |
+|---|---|---|---|
+| `plan-feature 14-csv-export` (not designed) | undesigned slug | — | STOP → `/design-feature 14-csv-export` |
+| `plan-feature 131` | issue #131 | `plan-feature-from-issue` → `plan-feature-scaffold` | PR carries `Closes #131` |
+| `plan-feature 14-csv-export` (designed, `defined`) | designed slug | `plan-feature-scaffold` | `execute-phase 14 P1` |
+| `plan-feature 14-csv-export` (already `planned`) | already-planned slug | — | STOP → `/execute-phase 14 P1` (no re-scaffold) |
+| `plan-feature --next` | next `defined` roadmap entry | gate, then scaffold | `execute-phase NN P1` |