Layer New

/layer-new -- scaffold a project layer

Creates docs/layers/<layer-name>/ with the full template structure defined by principle 28.

When to use

• Starting to track a new bounded concern in a long-running project
• Refactoring sprawling cross-cutting code into a documented layer
• Onboarding a new team member who needs the layer map

When NOT to use

• One-off scripts or pet projects with <5 features (overhead not justified)
• Layer name describes a directory (src is not a layer)
• The "layer" is actually one feature in disguise -- use /feature-new inside an existing layer instead

Arguments

/layer-new <layer-name> [--purpose "..."] [--principles P-NN,P-MM]

• <layer-name> -- kebab-case, single word preferred. Examples: security, data, image-processing, observability.
• --purpose -- one-sentence purpose. If omitted, prompt the user.
• --principles -- comma-separated Tier 1 principle IDs that govern this layer (e.g. P-02,P-21). If omitted, leave placeholder in README.

Direction (what to do, in order)

Step 1 -- Verify environment

Check the current working directory:

1. Is it a git repository? Run git rev-parse --show-toplevel. If not, ask the user whether to initialize one (offer git init + private GitHub repo per global rule).
2. Does docs/ exist? If not, create it.
3. Does docs/layers/README.md exist? If not, copy from <claude-code-skills-checkout>/templates/kb-skeleton/docs/layers/README.md.
4. Check if docs/layers/<layer-name>/ already exists. If yes, stop with a message -- do not overwrite. Suggest /feature-new <layer> <slug> instead.

Step 2 -- Validate layer name

• Must be lowercase kebab-case ([a-z][a-z0-9-]*).
• Must not start with _ (reserved for templates).
• Must not be a generic file-system name (src, tests, docs, build).
• If invalid, refuse with a clear message and a suggested fix.

Step 3 -- Copy the template

Source: <claude-code-skills-checkout>/templates/kb-skeleton/docs/layers/_LAYER-TEMPLATE/

Destination: <repo>/docs/layers/<layer-name>/

Copy the entire directory tree. Preserve subdirectory structure (kb/ and features/). Result:

docs/layers/<layer-name>/
├── README.md
├── history.md
├── kb/
│   ├── invariants.md
│   ├── decisions.md
│   ├── gotchas.md
│   └── patterns.md
└── features/
    └── _FEATURE-TEMPLATE.md

Step 4 -- Fill placeholders

In every file under the new layer, replace:

• <layer-name> -> the actual layer name
• <Layer name> -> Title Case of the layer name (e.g. "Security", "Image Processing")

In README.md specifically:

• **Purpose:** <one sentence...> -> the --purpose argument value, or prompt the user
• ## Governing principles list -> populate from --principles arg, or leave the placeholder bullets in place for the user to fill

In history.md:

• Insert a "Layer created" entry at the top with today's date (YYYY-MM-DD) and the originating reason. Prompt the user for the reason if not provided.

Step 5 -- Register the layer

Update docs/layers/README.md:

• Add a row to the ## Layer index table: | <layer-name> | <purpose> | active |
• If a cross-layer Mermaid graph exists, add a node for the new layer with no edges (user will add edges as dependencies form).

Step 6 -- Wire to project state

If the project has feature_list.json at repo root, leave it alone -- features get added by /feature-new. Do not edit feature_list.json from this skill.

If the project has AGENTS.md, suggest (but do not auto-edit) adding the new layer to the "Source-of-truth docs" table if multiple layers exist.