feature-workflow

What this skill does

# Feature Workflow

A machine for building features so the **marginal cost of feature N+1 slopes
down**: each feature composes more from what exists and builds less. It does
this by gating code behind a plan, composing from a reusable substrate (the
"shelf"), and growing that shelf on evidence.

This skill orchestrates; it **calls** the `boundary-discipline` skill (a sibling
skill — static placement of trust/effect/consistency/containment boundaries) at
the build and promote steps. Keep the two separate: this one decides *what to
build and what to reuse*; boundary-discipline decides *where each piece lives*.

## The failure modes this defends against

A capable model doesn't fail feature work from inability — it fails from
**momentum** (diving to code, trusting recall over checking the shelf) and
**drift** (re-deciding inconsistently across a long session). Those produce the
two ways feature cost slopes *up*: **duplication** (rebuilt what existed) and
**entanglement** (reused by coupling instead of composition). The gate beats
momentum; the externalized plan beats drift; the shelf-check kills duplication;
the seam-check kills entanglement.

## When to engage

- Building/extending a feature → **engage, gate first.**
- Pure audit / "is this robust" with no new feature → use `boundary-discipline`
  AUDIT directly; this skill is not needed.
- A genuine one-liner (typo, copy change, config bump) → no gate; just do it.
  (If unsure whether it's a one-liner, it isn't — gate it.)

## STEP 0 — Change-kind gate (the router; do this FIRST, always)

The loop is one spine; the **kind of change** determines the planning shape and
the test obligation, because each kind has a different dominant failure mode.
Classify by the **epistemic status of the existing behavior**, then route:

| Kind | Existing behavior | Dominant failure | Route to |
|---|---|---|---|
| **feature** | none — behavior is new | duplication / entanglement | this skill, STAGE 0 below |
| **refactor** | is the spec; preserve exactly | silent regression | `refactor-workflow` skill |
| **fix** | wrong in a bounded way | recurrence / neighbor break | `fix-workflow` skill |
| **spike** | approach itself unknown | committing to the wrong approach | `spike-workflow` skill |

The unifying law: **every kind contains an `unknown` that must be PARSED into a
trusted artifact — a test — before the change proceeds.** The test is the trust
boundary of the change loop; skipping it is proceeding on unparsed input, the
most serious violation in the model. Red-green *is* parse-then-proceed.

The sibling skills delegate back to the shared gate-runners here:
`change_new.py --kind <k>` scaffolds the kind's CHANGE manifest, `change_check.py
--kind <k>` gates it (fails closed on an undeclared obligation), and `verify.py`
enforces the obligation at ship. Only the planning shape and the parse artifact
differ per kind; the spine — gate → parse the unknown → build under the net →
verify the obligation → record/ratchet — is identical. The rest of this file is
the **feature** instance of that spine.

### Earned autonomy (capability-ledger)
Before the plan gate, consult `capability-ledger`'s `cap_check.py --class <c>` for
the problem class. The ledger tracks DEMONSTRATED, benchmark-proven competence and
returns what it licenses. If the class is **practiced** or **proven**, the PLAN
gate may auto-pass (proceed without plan confirmation) — but the verify gate and
human result-review still stand. If **proven**, the class may be delegated to a
sub-agent under the recorded playbook. This is how accumulated learning expands
blast radius: license is READ here, never written here (the loop cannot
self-license), it is earned only by measured near-floor outcomes, and it is
revoked instantly on a miss. A novice class always gets full gates.

**Earned autonomy never reaches the spec parse-point.** A practiced/proven class
may auto-pass the PLAN gate — autonomy over planning *shape* (boundary
decomposition, shelf-check), which the class has demonstrably done before. It is
never autonomy over *intent*: no measured competence at a problem class derives
what *this* feature is meant to do. The STAGE 0.5 spec interview runs at every
maturity; license only shrinks the delta (through inherited invariants), never the
human's confirmation of it. See `capability-ledger/references/licensing.md`.

## STAGE 0 — The gate (do this BEFORE writing any code)

This is the most important step and the one momentum will try to skip.

1. Scaffold the plan: `python scripts/plan_new.py --title "<feature name>"`
   (creates `PLAN.md` from `assets/PLAN.template.md`).
2. Fill sections 0–6. These are *judgment*, not paperwork — read
   `references/loop.md` (the six planning questions and why each exists) and
   `references/shelf.md` (the substrate model and the shelf-check). If a
   `boundary.config.json` exists, `plan_new` will have pre-filled section 3 with
   the real shelf inventory (via `shelf_index.py`) so the REUSE/EXTEND/BUILD
   classification is grounded in what actually exists rather than recalled. You
   still make the classification — the inventory only supplies the candidates.
3. Run the gate: `python scripts/plan_check.py PLAN.md`. It must **exit 0**
   before any implementation. A non-zero exit lists exactly which sections are
   unfilled — fill them, don't bypass them.

The plan is the workflow's trust boundary: establish ground truth once, then the
build phase gets to *assume* it. Code written before the gate passes is the
process equivalent of skipping the parse at ingress.

## STAGE 0.5 — Skeleton (interfaces before bodies)

The cheapest place to catch a conceptual error is the interface stage — concrete
enough to be wrong in checkable ways, abstract enough that fixing it is free
because no implementation exists yet. So before fleshing anything, write the
**skeleton**: the types, the boundary signatures, the port interfaces, and the
wiring, with bodies stubbed (`throw new Error("todo")` / `// ...`).

Two checks, both cheap:
- **It must typecheck.** A skeleton that compiles is proof the interfaces
  actually compose — a mechanical result prose can't give you. This is "make
  illegal states unrepresentable" verified at the type level before any logic.
- **Review the shape.** Run `python scripts/skeleton.py --feature <dir>` to derive
  the review view. It has four sections, each a boundary's face: **interfaces**
  (signatures, with trust/effect/sum-type tags as candidates), **schema** (the
  field shapes of the trust-boundary schemas — where "illegal states
  unrepresentable" is actually decided), **rules & invariants** (the spec), and
  **wiring** (how the units depend on each other). Judge it against the boundary
  model (boundary-discipline): is each boundary's signature its right kind (trust
  = `unknown → domain`; effects *injected* as ports, not returned)? Does the
  schema shape constrain illegal states (a sum type, not two optionals)? Does
  anything couple where it should compose?

This stage is also the **spec parse-point** — the one place the agent's guess
about *what you want* gets confirmed against ground truth (you), at the cheapest
ingress, before any bodies exist. So the rules section is the human-in-the-loop
surface. Invariants live **co-located** on the boundary they govern (a zod
`.refine` where the rule is schema-expressible; an `// @invariant: <rule>`
annotation where it's a claim not yet enforced), and the view classifies them:
- **established** — enforced in code already; confirmed; inherited by this feature
  with no re-work.
- **proposed** — an `@invariant` claim with no enforcement yet; the delta you
  adjudicate. Confirm it (it becomes an enforced refinement, co-located) or
  correct it (the cheapest possible place to catch a wrong rule).
- **blank** — a decision/trust boundary with no invariant is flagged; a blank is
  itself a review signal ("is there really no rule here?").

Each feature inherits the established invaria