/feature-new

name: feature-new
description: >
  Scaffold a feature narrative in an existing project layer with Design,
  Plan, Verify, and Conclusion sections. Use when: "create a new feature",
  "start work on feature", "scaffold feature doc", "/feature-new", or
  "begin feature narrative". Inspects and preserves the target project's
  feature ID, registry, filename, and coordination conventions; does not
  create a missing layer (use /layer-new).
user-invocable: true
model: sonnet

/feature-new -- scaffold a feature narrative

Creates a feature document in an existing layer. The document follows the ULTRAPACK-style narrative template (Design / Plan / Verify / Conclusion) extended with explicit cross-references to layer invariants and global principles.

When to use

• Beginning design work on a new feature, **before** writing code
• Migrating an in-flight feature from "scattered context" into the

formal narrative

• Creating a feature placeholder when planning future work that

another session will pick up

When NOT to use

• One-line bug fixes that do not need a design phase (just commit)
• Documentation-only changes (those go in handoffs or PR

descriptions)

• Refactors with no behavioral change (commit message is sufficient)

Arguments

/feature-new <layer> <slug> [--title "..."] [--branch <name>] [--id <project-id>]

• `<layer>` -- existing layer name. Must be a directory under

`docs/layers/`. If missing, suggest `/layer-new <layer>` first.

• `<slug>` -- kebab-case feature identifier without a project ID

prefix. Examples: `api-key-rotation`, `audit-log`, `dual-encryption`.

• `--title` -- human-readable feature title. If omitted, derive from

slug by title-casing.

• `--branch` -- git branch name. If omitted, default to

`feature/<slug>`.

• `--id` -- override the auto-allocated project-native ID. Use only when

migrating a pre-existing feature with a known ID. Refuse if the ID already exists in this layer.

Direction (what to do, in order)

Step 1 -- Verify environment

1. Determine repo root via `git rev-parse --show-toplevel`. 2. Confirm `docs/layers/<layer>/` exists. If not, refuse with a suggestion to run `/layer-new <layer>` first. 3. Confirm `docs/layers/<layer>/features/_FEATURE-TEMPLATE.md` exists. If not, copy from `<claude-code-skills-checkout>/templates/kb-skeleton/docs/layers/_LAYER-TEMPLATE/features/_FEATURE-TEMPLATE.md`.

Step 2 -- Discover and reserve the project-native ID

Do this before changing the feature document, layer README, or registry. A feature registry is project-owned state; this skill does not impose its old `F-NNN` example on it.

1. Inspect existing feature documents, the layer README, `feature_list.json` (if present), a co-located schema or validator, and `AGENTS.md`/project docs for the actual ID format, namespace, filename convention, fields, initial status, allocator, and coordination rule. For example, this repository's long-run template uses lowercase `feat-NNN` IDs with `description`, `dependencies`, and string `evidence`; that is not interchangeable with the old `F-NNN` example. 2. If `--id` was provided, validate it against the discovered convention and check every project-owned feature source that the convention names. If it is already used, refuse without changing anything. 3. Otherwise use the project's allocator when one exists. If the convention is visible only in current records, derive a candidate from those records and recheck all of them immediately before reservation. Do not infer a global namespace, digit width, prefix, or sort order from this skill. 4. Follow an existing project coordination mechanism when one exists and you are authorized to use it. Otherwise reserve the **logical ID**, not a slug-bearing pathname, with `scripts/reserve_feature_id.py`. It atomically creates `refs/feature-new/reservations/<project-id>` in the repository and binds that ID to the layer, slug, and final document path. This is a Git allocator record, not a second feature registry: the same request returns `resumed`; a different layer/slug/path returns `conflict` and must not edit the registry or another claimant's document. 5. On `conflict`, re-inventory the project convention and choose the next project-native candidate. Continue safe reconciliation while the requested scaffold remains actionable; do not guess that a durable reservation has a stale owner, overwrite it, or impose an arbitrary retry limit. 6. If no project ID/path convention exists at all, bootstrap only this skill's documented default: lowercase `feat-NNN`, globally allocated through the Git-ref helper, with `docs/layers/<layer>/features/feat-NNN-<slug>.md` as the document path. Do not create `feature_list.json`; once a registry exists it becomes authoritative over this fallback. 7. After reservation, re-read the README and registry before companion updates. If their convention changed, preserve the valid document and stop before a stale README/registry write; report the exact conflict and reserved path for the owner to reconcile.

When the project has no registry schema or helper, do not stop merely because it differs from this skill's example. Adapt by copying one current entry's field set and ID style, changing only values whose meaning is established by the project. If no representative entry or documented meaning exists, create the requested narrative only and leave the unknown registry untouched rather than append an invented record.

Step 3 -- Validate slug

• Lowercase kebab-case (`[a-z][a-z0-9-]*`).
• Length <= 50 characters.
• Does not repeat the discovered ID prefix.
• The resulting project-native feature filename does not already exist.

Step 4 -- Copy and fill the template

Source: `docs/layers/<layer>/features/_FEATURE-TEMPLATE.md`

Destination: the project-native feature filename discovered in Step 2.

In the new file, replace placeho