@gtrabanco/pi-agentic-workflow 0.13.3 → 0.14.0

package/skills/plan-feature/SKILL.md

@@ -1,208 +0,0 @@
----
-name: plan-feature
-user-invocable: true
-version: 5.3.1
-argument-hint: <NN-slug | #N> | --from-issue N | --scaffold <slug> | --next
-author: "Gabriel Trabanco <1969593+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
-✓ Then the Product-review gate ran: no current `spec-review-pass` receipt bound to
-  the recomputed snapshot → STOP with its fixed block and the `/review-spec`
-  hand-off; a candidate/verification receipt, a Plan receipt, or readiness never counts
-✓ 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
-✓ Planned, not reviewed: the ledgers are frozen, `stage: plan` readiness printed
-  `READY-FOR-REVIEW`, and the turn hands off to `/review-plan` — this skill never
-  reviews the plan it just wrote and never hands off to `/execute-phase` for a
-  plan with no current Plan review receipt
-✓ 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 allowlist:
-
-1. Every invocation: read [redirect gate and routing](references/ROUTING.md),
-   apply the status gate, then the Product-review gate, 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.
-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.
-4. Only when `node scripts/unit-route.mjs <NN>` prints `route: replan`: load the
-   [replan contract](<../replan-findings/SKILL.md>); it owns the exemption.
-
-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. **Product-review gate** from the same resource — current `spec-review-pass`
-   receipt bound to the recomputed snapshot, or STOP. No bypass flag.
-3. **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**; that internal stops at the Product-review
-   gate, so `plan-feature-scaffold` runs only once `review-spec` has passed the half:
-   it fills the engineering half, 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.
-4. **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.
-   `plan-feature` verifies and repairs the roadmap entry; `plan-feature-scaffold`
-   is the sole writer of the `defined → planned` write.
-5. **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.
-- **Never plan an unreviewed Product half** — this gate has no bypass flag either.
-  Planning binds the reviewer's receipt; it may never write, widen, or "refresh"
-  one, and a receipt bound to older bytes is stale, not close enough.
-- 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).
-- **Redirects to** `review-spec` when the Product-review gate stops: designed is not
-  reviewed. Its receipt is this skill's input, and `plan-feature-scaffold` binds it
-  as the Plan snapshot's Product parent.
-- `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 two planning ledgers were frozen with the Engineering half
-  ([planning ledgers](<../../pre-execution-review/SKILL.md>)), the
-  `stage: plan` readiness preflight printed `READY-FOR-REVIEW`, and the new
-  `artifactRevisionId` is named in the hand-off. A planned unit is **not** an
-  executable unit: this skill never reviews its own plan.
-- The dependency & blocker check ran, and **the closing `→ Next:` block matches
-  its result** — clean:
-
-  ```
-  → Next: /review-plan <NN> — the plan is written; an independent context must
-    review it before any phase is executed
-    · the review returned PLAN-REVIEW-FAIL → this skill replans the batch, then re-reviews
-    · 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>.
-  ```
-
-  designed but unreviewed/stale (Product-review gate stopped): the fixed
-  `PRODUCT-REVIEW GATE … BLOCKED` block from `ROUTING.md`, closing with
-  `/review-spec <NN>-<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

@@ -1,155 +0,0 @@
-## 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.
-
-**Replan exemption — the router runs first.** Before the status gate, run
-`node scripts/unit-route.mjs <NN>`. A `route: replan` line means the unit
-carries an open finding whose frozen route is the plan owner: skip the STOP and
-load [the replan contract](<../../replan-findings/SKILL.md>) to re-cut the plan
-from the router's bounded read set. Any other route keeps the gate and the
-hand-off its line names; a router that cannot run is `BLOCKED`.
-
-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** (replanning stays forbidden — the
-   feature is fully built), and: `done` means built + PR open with the human merge
-   pending (a lifecycle label, never a gate verdict), so this is **not** "nothing
-   pending". Route to the merge gate instead. Print exactly:
-
-   ```
-   → Next: /audit-pr <PR> — done means built + PR open, merge pending (a lifecycle label, never a gate verdict)
-     · the row's PR is merged → nothing pending, pick the next unit → /plan-feature --next
-     · no PR is open → the row is mislabeled or execution stopped → /execute-phase <NN> (never a replan)
-   ```
-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.
-
-## Product-review gate (after the redirect gate, before Routing)
-
-The redirect gate proves the Product half was **designed**; this proves it was
-**independently reviewed** and unchanged since. Run it before any write on every
-planning route. Issue input has no slug yet: evaluate it on the slug
-`plan-feature-from-issue` produces, just before `plan-feature-scaffold` would run.
-
-1. Read the newest `## Pre-execution review receipt v1 — spec` block in the unit's
-   `progress.md`; none → fail closed.
-2. Recompute the SPEC-stage snapshot from the bytes on disk now — exactly one
-   artifact row (`kind: spec`, `selector: spec-product-v1`) plus the current
-   `artifactRevisionId` — digested with the schema package's canonical entry (no
-   package: record `validated: manual` and compare the stored digest line by line).
-3. Accept only when all hold: contract `agentic-workflow/
-   pre-execution-review-receipt@1`, `stage: spec`, verdict `spec-review-pass`,
-   `snapshotDigest` equals step 2, zero open or unverified material findings,
-   `contextClean: true`, and under `authorExclusion: enforced` reviewer ≠ author.
-4. Refuse, never silently: **missing** · **stale** (digest or `artifactRevisionId`
-   differs — any Product write, context change, or mutate-and-revert) ·
-   **wrong-stage** (a `plan` receipt) · **substitute** (candidate `ReviewReceipt v1`
-   or staged `VerificationReceipt v1`: different contracts, never interchangeable) ·
-   **self-approved** (reused identity under enforced exclusion, or `contextClean:
-   false`) · **author-readiness** (`READY-FOR-REVIEW` licenses a review request, it
-   is not one).
-
-Fail closed — print exactly, then touch nothing else this turn:
-
-```
-PRODUCT-REVIEW GATE — <NN>-<slug> BLOCKED (<missing|stale|wrong-stage|substitute|self-approved|author-readiness>)
-Expected: current spec-review-pass receipt bound to snapshot <digest>
-Actual:   <receipt state>
-
-→ Next: /review-spec <NN>-<slug> — the Product half needs a current independent
-    review before engineering planning can start
-  · a product choice is genuinely open → /design-feature <NN>-<slug> "<question>"
-  · no bypass flag exists for this gate
-```
-
-A stale receipt is never "refreshed" by editing the block — only a new review of a
-new snapshot produces one, and `--force` is not a `plan-feature` flag.
-
-## 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 14-csv-export` (designed, no current spec review) | unreviewed Product half | — | STOP → `/review-spec 14-csv-export` |
-| `plan-feature 131` | issue #131 | `plan-feature-from-issue` (stops at the Product-review gate) | `/review-spec` → re-run `plan-feature 131` |
-| `plan-feature 14-csv-export` (designed + reviewed) | 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` |
-
-## Mode grammar (versioned — read by `scripts/normative-drift.test.mjs`)
-
-The detection order above is prose for the human; this table is the machine form
-of the same routing: `flag` must be a flag this skill's `argument-hint:` accepts
-and `route` must be a skill that exists. A flag or a route no surface declares is
-a defect in this table, never in the hint.
-
-```text
-plan-mode-routes@1
-# owner: plan-feature
-mode | flag | route
-issue-derived | --from-issue | plan-feature-from-issue
-forced-scaffold | --scaffold | plan-feature-scaffold
-next-defined | --next | plan-feature-scaffold
-designed-slug | n/a | plan-feature-scaffold
-```

package/skills/plan-feature-from-issue/SKILL.md

@@ -1,162 +0,0 @@
----
-name: plan-feature-from-issue
-user-invocable: false
-version: 2.0.0
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Internal step of plan-feature: turn a feature-request issue into a scoped,
-  sized, roadmap-mapped SPEC **product half** (capability closure satisfied)
-  with Closes #N traceability.
----
-
-# Plan Feature — From Issue (internal)
-
-Convert a feature-request issue into the project's planning artifacts, keeping a
-clean issue → SPEC → PR(Closes #n) trace. Writes the SPEC's **product half**
-(same two-halves convention `design-feature` uses) and must satisfy capability
-closure before handing off — a thin issue does not get a shortcut around it.
-
-**This skill stops at the Product half.** It designs, then the unit goes to
-`review-spec` for an independent Product review; engineering planning is a
-different authority's turn. Composing `plan-feature-scaffold` in the same breath
-as the design it just wrote is the bypass this separation exists to close — the
-author of a Product half cannot be the one who decides it is ready to build on.
-
-## When to use
-
-- The `plan-feature` router calls this when the input is a GitHub issue (or
-  `--from-issue N`) that describes new product capability.
-
-If the issue is a **bug or tech-debt**, stop and route it: `triage-issue` to
-classify, then `plan-fix` + `execute-phase --fix`. This skill is for
-genuine features only.
-
-## Step 0 — Discover the project (always first)
-
-Per the agent guide's **Workflow conventions** + **documentation map**, then read
-what THIS skill needs: the feature SPEC template, the roadmap, and the issue/PR
-templates (`.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md`) so the
-SPEC mirrors the fields reviewers expect. Then read the issue (forge CLI per the
-project's Workflow conventions — examples use `gh`):
-
-```sh
-gh issue view <N> --json number,title,body,labels,state,comments
-```
-
-## Process
-
-1. **Classify first.** Confirm it is a feature. Not a feature if it describes a
-   defect, regression, duplicated code, perf debt, or carries a "when to
-   fix / trigger" clause → hand to `triage-issue`. State the verdict explicitly.
-2. **Normalize language.** If not in the project's docs language (this repo:
-   **English**), translate before drafting any artifact.
-3. **Map to the roadmap.** Assign the next number + slug. Identify dependencies
-   and conflicts with existing features, coupling/migration risks, and whether
-   it should instead extend an existing feature.
-4. **Close product-half gaps proactively.** Compare the issue against what a
-   complete SPEC **product half** needs (goals, scope in/out, business goals,
-   i18n/SEO/a11y/pricing per the docs map, a UI design reference when the
-   feature has a UI surface), probing the same fixed **vagueness rubric**
-   `design-feature`'s interview uses: affected users/roles · error & edge
-   states · data shape · boundaries & limits · out of scope · success
-   criteria — each slot filled or explicit `n/a: <reason>`. For each genuine
-   gap you can't safely default, ask the user **one question per turn, never
-   batched**, each with a recommended default; never ask what the issue or
-   docs already answer. **Structural hand-off threshold:** if ≥ 3 rubric
-   slots remain unfillable from the issue plus the answers so far, stop and
-   hand the feature to `design-feature` (the thin-issue rule below, now with
-   a fixed trigger) instead of continuing to interview here.
-5. **Satisfy capability closure.** Walk the same fixed checklist
-   `design-feature` uses (per entity: CRUD + state transitions, each with UI +
-   API + test, or explicit `n/a: <reason>`; per capability: entry point + ACL;
-   per role: assigned/revoked/viewed where) into the SPEC's `## Capability
-   closure` and `## Acceptance criteria`. **A thin issue that doesn't carry
-   enough to fill it is not a shortcut around the gate** — hand it to
-   `design-feature` (compose in-turn only at ≥ this skill's tier, per
-   *Guardrails*; otherwise hand off with `run /design-feature <slug>` and stop
-   here) rather than stamping `designed` on a hollow closure.
-6. **Size it.** Estimate `XS / S / M / L` (scale defined in the SPEC template)
-   and record it in the SPEC. XS/S → the SPEC is the only planning artifact
-   (single-pass execution); M/L → full artifact set. If L, propose splitting.
-7. **Produce the SPEC product half.** Fill it and stamp `## Design status:
-   designed` once closure is complete; set the roadmap row (added at `idea`
-   first if it didn't exist) to `defined` in the same edit — the same
-   `idea → defined` transition `design-feature` owns, performed here when this
-   skill is the one that satisfies closure. Then run the `stage: spec` readiness
-   preflight from the internal
-   [`evidence-grounding`](<../evidence-grounding/SKILL.md>) capability, mint the
-   current `artifactRevisionId`, and **stop**: this skill never continues into the
-   engineering half, never promotes the row past `defined`, and never composes
-   `plan-feature-scaffold` in this turn. The `plan-feature` router may scaffold only
-   after `review-spec` returns a current `spec-review-pass` receipt bound to these
-   exact bytes.
-8. **Wire traceability.** Record `#N` in the SPEC; the PR body must include
-   `Closes #N` so the issue closes on merge.
-9. **Hand off — return exactly** (fixed completion report, back to the router):
-
-   ```
-   ISSUE #<N> → SPEC <slug> — size: <XS|S|M|L>
-   Verdict: feature (not bug/debt — else this would have routed to triage-issue)
-   Gaps closed: <n> asked / <n> defaulted (logged)   Closure: designed | handed to design-feature
-   Readiness: READY-FOR-REVIEW | NEEDS-EVIDENCE | NEEDS-DESIGN   Artifact revision: <id>
-   Traceability: Closes #<N> wired
-   → review-spec next (engineering planning is gated on its receipt; do not scaffold here)
-   ```
-
-## Guardrails
-
-- Don't silently expand scope beyond the issue — surface additions as proposals.
-- Don't open the feature branch or write code here.
-- **Don't plan engineering work here.** No Engineering half, no phases, no
-  `defined → planned` promotion, no in-turn `plan-feature-scaffold` composition:
-  the Product half this skill writes must be reviewed by `review-spec` first, and
-  readiness `READY-FOR-REVIEW` is not that review.
-- Keep the `Closes #N` link; an issue-born feature must close it.
-- **Never stamp `## Design status: designed` with a blank Capability closure
-  row** — the same rule `design-feature` follows; a thin issue hands off
-  instead of faking closure.
-- **Composition tier.** Composing `design-feature` in-turn for a thin issue is
-  allowed only when this skill is running at ≥ `design-feature`'s tier
-  (planning-class — strongest model / highest effort); otherwise hand off
-  (`run /design-feature <slug>`) rather than under-power it.
-- Otherwise honor the project's **Workflow conventions** (branch/PR, docs-language).
-
-## Architectural invariants
-
-The [planning preflight](<../planning-preflight/SKILL.md>) owns the normalized
-repository state read and the ONE final architectural classification for the
-whole plan. Consume it here before writing the product half: for each applicable
-invariant rule, cite its ID and repository evidence and classify the issue
-proposal as `preserves`, `violates`, `introduces`, or `changes`. Only
-`preserves` can be stamped `designed`; every other classification stops for an
-explicit architectural decision through the project-declared authority — never
-before the full plan exists, and never inferred from the issue body, SPEC, or
-passing test.
-
-## Relationship to other skills
-
-- `triage-issue` — decides bug vs feature vs defer; call it if unsure.
-- `plan-fix` — the fix-side sibling for bug/debt issues.
-- `design-feature` — receives thin issues this skill cannot safely close
-  capability closure for; both write the SPEC's product half in the same format.
-- `review-spec` — the mandatory next hop for every issue-derived feature: it
-  reviews and receipts the Product half this skill produced.
-- `plan-feature-scaffold` — fills the engineering half later, only once
-  `review-spec` passed. This skill never invokes it.
-- `execute-phase` — executes the phases; its PR carries `Closes #N`.
-
-## Done when
-
-- A filled SPEC product half exists, roadmap-registered at `defined`, with the
-  `stage: spec` readiness block printed and the current `artifactRevisionId`
-  recorded.
-- Capability closure is satisfied (or the issue was handed off to
-  `design-feature` instead of faking it) and `## Design status` is accurate.
-- The roadmap row status is `defined` (added at `idea` first if new) whenever
-  `## Design status: designed` was stamped — never `defined` on a hollow
-  closure, never left at `idea` once `designed` is stamped.
-- Nothing was scaffolded: no Engineering half, no phases, no `planned` write, and
-  the fixed report hands off to `/review-spec`.
-- `#N` is recorded and the PR plan includes `Closes #N`.
-- Scope gaps were resolved with the user, not assumed.

package/skills/plan-feature-scaffold/SKILL.md

@@ -1,112 +0,0 @@
----
-name: plan-feature-scaffold
-user-invocable: false
-version: 2.4.0
-author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
-license: MIT
-description: >
-  Internal step of plan-feature: from an already-designed SPEC (product half
-  `designed`), fill the **engineering half** and generate the planning
-  artifact set scaled to the feature's size (XS/S → SPEC-only with ≥ 2 phases
-  in the SPEC, last = Hardening & PR; M/L → full set with a hardening phase),
-  freeze one compact ACCEPTANCE.md for every size, and register the roadmap
-  entry. Docs only — never code.
----
-
-# Plan Feature — Scaffold (internal)
-
-Turn a designed feature into the project's complete planning artifact set,
-ready for phase-by-phase execution. Fills only the SPEC's **engineering half**
-— the product half (goal, context, scope, capability closure) already exists
-and is marked `designed` before this skill ever runs (`plan-feature`'s
-redirect gate guarantees it). **Docs only — never code.**
-
-## When to use
-
-- The `plan-feature` router calls this once a feature's product half is
-  `designed` — from `design-feature`, `plan-feature-from-issue`, or an
-  already-scoped slug/SPEC — to fill the engineering half of its
-  `docs/features/<NN>-<slug>/SPEC.md` and the rest of the folder, then update
-  the roadmap.
-
-Not for product definition (that is `design-feature`) or writing code (that is
-`execute-phase`) or deciding *whether* to build (that is the `plan-feature`
-router / `triage-issue`).
-
-## Step 0 — Discover the project (always first)
-
-Per the agent guide's **Workflow conventions** + **documentation map**, then read
-what THIS skill needs: the feature SPEC **template**, the **roadmap**
-(numbering/order/deps), 1–2 recent feature folders to mirror the artifact set, and
-the architecture/domain docs the map points to. No template/roadmap → fall back to
-the agent guide and state the assumption.
-
-## Progressive loading — scaffold only after discovery
-
-The reference allowlist is exactly one path. After Step 0, read and execute the
-complete [scaffold process](references/SCAFFOLD_PROCESS.md). It owns the product-
-half gate, artifact scaling, roadmap transition, re-read, and fixed completion
-report. The [phase contract](<../phase-contract/SKILL.md>) owns the 8-box
-phase-lint and the normalized phase fingerprint, and
-`bun scripts/phase-lint.mjs <plan>` (node fallback) runs it: run the linter over
-the emitted plan before reporting and paste its stdout block verbatim as lint
-output, never as instructions — exit 1 is a blocked phase to re-cut, never a
-verdict to re-derive by reading the rules. If the script is absent
-(installed-skill target — it ships with the repository, not the skill), apply the
-eight `phase-contract` rules by hand, label the check weaker, and disclose the
-linter did not run; never skip the gate.
-
-The resource is normative and one hop from this file. Missing resource → stop;
-never reconstruct phase or close-out wording from memory.
-
-The [verification contract](<../verification-contract/SKILL.md>) owns the
-`ACCEPTANCE.md` schema, validation ladder, and anti-weakening rules. Consume it
-after the engineering plan is complete and before registering `planned`.
-
-## Research and reference trace (plan stage)
-
-- **Conditional web research.** Plan-stage research runs only when a bounded
-  question (ROWS.md Q1–Q5) cannot be answered from repository evidence: run
-  exactly one web pass before the phases are emitted and freeze what it
-  returns as evidence rows (URL and access date). A question the repository
-  answers is never re-fetched.
-- **Mandatory reference trace.** Affected code is located by symbol/reference
-  search — LSP/serena when the environment offers it, grep otherwise — and the
-  blast radius is derived from that search, never from model memory: added or
-  changed code can break callers the plan must name.
-
-## Guardrails
-
-- Docs only. No source edits, migrations, or dependencies.
-- Respect the architecture: honor layer rules (inner layers don't import outer)
-  and any domain/i18n/SEO/a11y rules from the docs map.
-- **Architectural invariants.** The [planning preflight](<../planning-preflight/SKILL.md>)
-  owns the normalized repository state read and the ONE final architectural
-  classification for the whole plan; consume it here. Its absence is compatible:
-  record `n/a: no project invariants declared` in the engineering half. For
-  every applicable rule, record its ID, repository evidence, and
-  `preserves | violates | introduces | changes` classification in
-  `### Architecture impact`. Only `preserves` may produce phases; the other
-  classifications stop for an explicit architectural decision through the
-  project's declared authority — and only after the full plan exists, never
-  converted into a phase task or inferred from the product half.
-- Surface conflicts (numbering clashes, dependency cycles, scope overlap) before
-  writing, not after.
-- Otherwise honor the project's **Workflow conventions** (branch/PR, docs-language).
-
-## Relationship to other skills
-
-Invoked by the `plan-feature` router (after `design-feature` /
-`plan-feature-from-issue` designed the product half, or directly for an
-already-designed scoped slug/SPEC). Hands off to `execute-phase` for P1;
-`audit-docs` audits anytime.
-
-## Done when
-
-- `docs/features/<NN>-<slug>/` exists with the SPEC's engineering half +
-  `ACCEPTANCE.md` + every scaled planning artifact filled — the product half untouched from what
-  `design-feature` / `plan-feature-from-issue` wrote.
-- The roadmap lists the feature with correct number, order, dependencies, and
-  **status `planned`** (the `defined → planned` write this skill owns) —
-  **re-read and confirmed after the write**, not assumed from having run it.
-- No code changed; open questions captured in `decisions.md`.