feature-new

# /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 F-NNN]
```

- `<layer>` -- existing layer name. Must be a directory under
  `docs/layers/`. If missing, suggest `/layer-new <layer>` first.
- `<slug>` -- kebab-case feature identifier without the `F-NNN-`
  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 F-NNN. 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 -- Allocate F-NNN

If `--id` was provided:

- Validate format (`F-\d{3,}`).
- Check that
  `docs/layers/<layer>/features/feat-<NNN>-*.md` does not already
  exist. Refuse if it does.

If `--id` was NOT provided:

- Scan all existing feature files across **all** layers (not just
  this one) for the highest F-NNN already used.
- Allocate the next number, zero-padded to 3 digits (F-001, F-042,
  F-099, F-100, ...).
- Cross-check that the ID is not in use anywhere -- F-NNN is a
  **project-wide** namespace, not per-layer.

### Step 3 -- Validate slug

- Lowercase kebab-case (`[a-z][a-z0-9-]*`).
- Length <= 50 characters.
- Does not start with `f-` or `feat-` (avoid double-prefix).
- The resulting file `feat-<NNN>-<slug>.md` does not already exist.

### Step 4 -- Copy and fill the template

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

Destination: `docs/layers/<layer>/features/feat-<NNN>-<slug>.md`

In the new file, replace placeholders:

| Placeholder | Replacement |
|-------------|-------------|
| `F-NNN: <feature title>` | `F-<NNN>: <title>` |
| `**Layer:** [<layer-name>](../README.md)` | `**Layer:** [<layer>](../README.md)` |
| `**Status:** design` | leave as `design` |
| `**Branch:** feature/<slug>` | use `--branch` value or default |
| `**Started:** YYYY-MM-DD` | today's date |
| `**Owner:** <name>` | infer from git config user.name, or leave placeholder |

Leave Design / Plan / Verify / Conclusion section bodies as template
placeholders -- the user fills these.

### Step 5 -- Update layer README

In `docs/layers/<layer>/README.md`, find the `## Features in this
layer` table. Insert a new row at the bottom (sorted by F-NNN
ascending):

```
| F-<NNN> | <title> | design | YYYY-MM-DD | [feat-<NNN>-<slug>.md](features/feat-<NNN>-<slug>.md) |
```

If the table has only the placeholder rows from the template, replace
them entirely with the real entry.

### Step 6 -- Update feature_list.json (if present)

If `<repo>/feature_list.json` exists at repo root, parse it and
**append** a new feature entry:

```json
{
  "id": "F-<NNN>",
  "name": "<title>",
  "layer": "<layer>",
  "doc": "docs/layers/<layer>/features/feat-<NNN>-<slug>.md",
  "branch": "feature/<slug>",
  "status": "not-started",
  "dependencies": [],
  "evidence": []
}
```

Important encoding rule (per
`~/.claude/rules/api-utf8-posting.md`): write the JSON file with
`json.dump(data, f, ensure_ascii=False, indent=2)` to preserve any
Cyrillic in titles.

Do NOT change existing entries.

If `feature_list.json` does not exist, do not auto-create it -- emit
a hint instead.

### Step 7 -- Confirm and suggest next step

Print a summary:

```
Created: docs/layers/<layer>/features/feat-<NNN>-<slug>.md
Updated: docs/layers/<layer>/README.md (added F-<NNN> to features table)
Updated: feature_list.json (added F-<NNN>, status: not-started)

Suggested next steps:
1. Fill the Design section in feat-<NNN>-<slug>.md
   - Approach (one paragraph)
   - Invariants (IV-1, IV-2, ...)
   - Rejected alternatives
2. When Design is reviewed, change Status: design -> planning and fill Plan
3. Create the git branch: git checkout -b feature/<slug>
```

## Blueprints (files this skill writes from)

- `templates/kb-skeleton/docs/layers/_LAYER-TEMPLATE/features/_FEATURE-TEMPLATE.md` -- the source template

## Status lifecycle

Two parallel state systems exist; you maintain both manually after this
skill creates them. They serve different purposes:

### Doc Status (narrative phase, in feature.md frontmatter)

Tracks where in the ULTRAPACK Design / Plan / Verify / Conclusion
journey the feature is.

```
design --> planning --> executing --> reviewing --> done
                                  \
                                   --> blocked --> executing
```

Six states: `design`, `planning`, `executing`, `reviewing`, `done`,
`blocked`. Transitions are manual edits. Once `done`, the feature doc
is read-only history; further changes go into a superseding feature.

### feature_list.json status (machine state, for tooling)

Tracks the machine-readable state