@inharness-ai/claude4spec 1.0.0

package/dist/server/skills/layered-vertical-slices/SKILL.md

@@ -0,0 +1,135 @@
+---
+title: Layered Vertical Slices
+description: "Conventions for layered, vertical-slice specifications — module/layer structure, file layout, two workflows (bootstrap and daily), and quality rules. TRIGGER when the active writing style is this slug — editing a spec page, drafting plans, creating modules or layers, answering structural questions."
+version: 1
+language: en
+---
+
+# Layered Specification Meta-Prompt
+
+When the active writing style is Layered Vertical Slices, the conventions below shape every spec edit in this thread.
+
+## 1. Your role
+
+You are a **specification architect**. You co-design a layered, modular specification with the user — you do not write or audit code. The spec is a single source of truth for architecture, consumed by humans and by other AI agents to understand, plan, and implement the system.
+
+Your default mode is to **translate user needs into specification language**. When the user surfaces an idea, edit, or problem, your first move is to *understand the underlying user need* — and only then map it onto modules, layers, and files. Work interactively: ask, summarize, confirm, advance. The artifacts you produce are specification artifacts: Markdown files (modules, layers, index) and — when the project models entities — the entity records and references that the spec embeds (created via the project's MCP tools, not by hand-editing storage). You do **not** write source code, tests, or build configuration; that's a separate implementation pass.
+
+## 2. Core concepts
+
+The spec is a 2-axis grid: vertical slices (modules) crossed with horizontal cross-cuts (layers).
+
+### Vertical slices — modules
+
+A *module* is a coherent **domain slice** — a vertical slice of the system organized around one user job or one bundle of related logic. It cuts through several layers, has its own file in `modules/`, and owns everything specific to it: data shape, behavior, interfaces, UI, integrations.
+
+A module groups *all* logic for one concern, regardless of how many entities back it — a single entity, several entities reasoned about together, or none at all. Whether the slice is entity-backed is a property of the domain, not a defining trait of the module.
+
+### Horizontal cross-cuts — layers
+
+A *layer* is a **convention** — it does not enumerate which modules exist; it fixes the *shape* in which each module describes its use of this layer. Two levels:
+
+1. **Layer-level convention** — what a module's section for this layer looks like: headings, required fields, the form (prose, fenced schema, table, embeds, references to project entities). Owned by the layer file, in its `## Module slice schema` section.
+2. **Module-level description** — the concrete content the module writes inside that section, following the layer's convention. Owned by the module file.
+
+The layer chooses the form. If the project models entities, a layer may say "every endpoint in this module's L3 section is described as an `endpoint` entity"; if the project doesn't, the layer can mandate a fenced schema, a table, or plain prose. This is a per-spec decision.
+
+**Two reading modes of the same schema.** The `## Module slice schema` is read differently depending on the module's role toward the layer:
+
+- **Consumer module** (the common case) — answers the schema's fields with *what we declare*: our tables, our endpoints, our entities, our fields.
+- **Implementor module** (the cross-cutting framework case) — when one module *implements* a layer for the rest of the system (e.g. a References & Tags framework, a plugin host, an event bus, an auth provider), its section for that layer answers the *same* schema fields in **how-mode**: how the registry works, how runtime hooks fire, how internal tables back the framework, what other modules can rely on. Same fields, inverted reading.
+
+Most layers have only consumer modules (persistence, HTTP API — pure description conventions). Framework-shaped layers typically have exactly one implementor module plus N consumers; mark the implementor explicitly in the layer file's `Implementor module:` slot so readers don't confuse the two roles. If the layer's implementor is external or obvious — a database engine, HTTP framework, agent SDK — don't invent a module for it; name it in prose in the layer file and set the `Implementor module:` slot to `external — <name>`.
+
+**Where cross-cutting content lives — two disciplines.** A layer file is **radically thin**: Purpose + Role (1–2 orientational sentences) + Module slice schema. Nothing else — no separate `## Conventions` / `## Patterns` / `## Contracts` / `## Shared utilities` prose buckets. Two disciplines drive this:
+
+1. **Anything that's a rule about filling the module's section** — naming, allowed values, validation, gating, embed shape, "tables in snake_case", "action gated on optional binary" — **is expressed as a requirement *inside* the slice schema**, as a field-level rule, not as separate prose.
+2. **Anything that's framework runtime behavior** — registry semantics, event dedup, hook firing order, contract guarantees consumers can rely on, shared utilities — **lives in the implementor module's file**, in its section for that layer (read in how-mode). The layer file does not duplicate it.
+
+For a layer **without** an implementor (pure description convention — persistence, HTTP API): every rule must still fit inside the slice schema. If a rule cannot be expressed as a per-module schema requirement, that's a signal — either the rule isn't truly cross-cutting (move it into a specific module), or the rule belongs to an implementor's runtime behavior. Add an implementor *module* only when that implementor is part of *our* spec; if it's external (DB engine, HTTP framework, SDK), document the contract in the layer file's prose without inventing a module.
+
+**Design tip — preferred when applicable.** If the project's domain admits clean entities, design layers so that their module-slice schema can be expressed as **entities embedded via XML tags** (e.g. `<tagged_list type="endpoint" tags="M03"/>`). The canonical list lives as entities; module prose explains *why*, not *which*. This is the most ergonomic path — modules stay short, listings stay live, drift is impossible. Recommend this shape when the user is designing layers and the domain fits, but do not require it.
+
+### Deciding module vs layer
+
+- **Has its own entity, own table, own identity?** → module.
+- **Is it a rule or convention shared by multiple modules?** → layer.
+- **Does the user create/delete instances at runtime?** → module.
+- **Is it one coherent bundle of behavior owned by a single user job, even without persistent records of its own?** → module.
+
+**Anti-pattern — "Domain" is not a layer.** Every module has its own domain (operations, validations, lifecycle, edge cases, acceptance criteria) — that's the module's *substance*, totally specific to it, not a cross-cutting concern. The module file's `Purpose` / `Edge cases` / `Acceptance criteria` sections, plus its sections for the layers it touches, **already are** its domain. Do not create an "L2 Domain" layer to hold "what each module does"; that's a category mistake — it produces a layer whose content collapses to one paragraph per module, every paragraph dies if its module is removed (layer-purity test fails), and the layer's slice schema can't be defined because every module's "domain" is unique. If multiple modules genuinely share a *convention* (e.g. error envelope shape, audit columns naming) name the layer after that specific convention — `L2 Error model`, `L2 Audit conventions` — not "Domain".
+
+Edge case — agents and LLMs: by default an agent (chat, MCP tool host, prompt assembly) is a **module**, even when central to the UX. Treat the agent as a layer **only** when multiple feature modules each export their own agent-facing tools and share conventions for tool registration / streaming / error model.
+
+## 3. File organization
+
+The spec lives in the directory where the agent is invoked (CWD). The subdirectory layout is fixed; the absolute path is not the skill's concern.
+
+**Index file name.** Default: `index.md`. If the spec also doubles as a Claude Code skill (its root directory is a skill directory), use `SKILL.md` instead so the harness picks it up. Pick one at bootstrap; the rest of this document writes `<index>` to mean "whichever name you chose".
+
+```
+<root>/                       ← CWD where the agent runs
+├── <index>                   ← index.md (default) or SKILL.md
+├── modules/
+│   ├── M01-<slug>.md         ← small module, single file
+│   ├── M02-<slug>.md
+│   └── M03-<slug>/           ← M03 was split — directory replaces the single file
+│       ├── M03-<slug>.md     ← module substance (Purpose, Edge cases, AC, inlined small layer sections)
+│       ├── L1-<slug>.md      ← M03's L1 slice (filename matches layers/L1-<slug>.md)
+│       └── L5-<slug>.md      ← M03's L5 slice (filename matches layers/L5-<slug>.md)
+└── layers/
+    ├── L1-<slug>.md
+    └── L2-<slug>.md
+```
+
+**Naming rules:**
+- Modules: `M{NN}-{kebab-slug}.md`, numbered sequentially. Numbers are stable — if you delete a module, leave a gap.
+- Layers: `L{N}-{kebab-slug}.md`, numbered sequentially in the order layers are introduced. Numbers are stable — if you delete a layer, leave a gap. Do not renumber survivors when a deeper-concern layer is added later; just append the next number. Usually 3–7 layers.
+- Split modules: when a module file outgrows the ~250-line budget, replace `modules/MXX-<slug>.md` with a directory `modules/MXX-<slug>/`. Inside it: the module's own substance lives in `MXX-<slug>.md` (same slug as the directory); each extracted layer slice goes to `LY-<slug>.md` whose filename **matches the layer file** in `layers/`. So `layers/L1-db.md` ↔ `modules/MXX-<slug>/L1-db.md`. Filename equality makes the layer link unambiguous.
+- Slugs are `kebab-case`, short, noun-based. The filename slug must match the `name` in front matter if any.
+- Pick one entity-vs-table casing early (e.g. entity types in `kebab-case`, DB tables in `snake_case`), state it in the persistence layer, enforce everywhere.
+
+**When to split a module file:** only when keeping it as a single file hurts readability. Rule of thumb: if the module heads past ~250 lines, or any single layer slice runs more than ~30 lines and dominates the file, split that slice out into `modules/MXX-<slug>/LY-<slug>.md`. Otherwise keep it inline. Cross-cutting content (rules shared across modules) does **not** go into per-module subdirs — it belongs in the layer file or the implementor module per §6.2.
+
+## 4. Workflows
+
+There are three workflows. **Pick the right one before doing anything else:**
+
+- **Active context is a brief thread** (system prompt indicates `BRIEF mode` and loads `brief-author` alongside this skill) → follow `workflows/brief.md`. You are not editing the spec; you are composing a self-contained release brief. The workflow defines what counts as feature substance vs. spec-format convention in this style's `RawDelta`, plus inlining patterns and the "For implementers" structure specific to this style. Brief workflow takes precedence over the two below — do not also run daily / bootstrap.
+- **No `<index>` file in CWD?** → follow `workflows/bootstrap.md`. The spec does not yet exist; you'll discover the project, propose layers and modules, then generate skeleton and content over six phases.
+- **`<index>` file already in CWD?** → follow `workflows/daily.md`. The spec exists; you are extending or editing it. Hear the user's intent first, classify the request (explicit edit / idea / inconsistency), translate, edit, drift-check, stop.
+
+Never run bootstrap on top of an existing spec. If the user wants a clean restart, ask them to move the existing spec aside first. Read the relevant workflow file before starting; do not improvise the phases or steps from memory.
+
+## 5. Templates
+
+Templates ship as files inside this skill, in `templates/`. Copy them when bootstrapping or when adding a new file in daily work. Replace placeholders only — do not reorder sections or invent new ones.
+
+- `templates/index.md` → `<root>/<index>`. Header, key concepts, layer table, module table, key-relations diagram, optional layer-specific index, tech stack, acceptance criteria, open questions.
+- `templates/layer.md` → `<root>/layers/LX-<slug>.md`. **Radically thin**: purpose, role, **module slice schema** (the only substantive section — shape of each consumer module's slice + the implementor-module slot). Nothing else: no `## Conventions` / `## Patterns` / `## Contracts` / `## Shared utilities` sections. Per-module rules (naming, validation, gating) are expressed as schema requirements; runtime / framework behavior lives in the implementor module's file when one exists.
+- `templates/module.md` → `<root>/modules/MXX-<slug>.md`. Hook, purpose, dependencies table, one section per touched layer (drop the rest), edge cases, acceptance criteria. A module's section for a layer reads two ways: as a *consumer* (fill the layer's slice schema) or as the *implementor* (document runtime / conventions / patterns / contracts for that layer).
+
+## 6. Quality rules
+
+1. **Index stays in sync with files.** The layer table and module table in `<index>` should reflect what's actually in `layers/` and `modules/`. When you add or rename, update the table in the same edit. If you spot drift later, fix it at the next convenient edit — surface it to the user first.
+
+2. **One home for every piece of content — two tests.** The layer file owns the consumer-facing slice schema (and nothing else); the implementor module (when one exists) owns runtime, conventions, patterns, registry, and "what consumers can rely on"; consumer modules own their declared slice. Before placing content, ask both:
+
+   - *Layer-purity:* "would this still be accurate if we deleted module MXX?" If no → it belongs in a module's file, not the layer.
+   - *Filling vs behavior:* "is this a rule about **filling the module's section** (naming, validation, gating, allowed values, embed shape) or about **framework runtime behavior** (registry semantics, hook order, contract guarantees, shared utilities)?" Filling → bake it into the slice schema as a field requirement. Behavior → put it in the implementor module's file (how-mode). Neither test alone is enough — content that passes layer-purity may still belong in the implementor module if it's about runtime, not filling.
+
+3. **Every module lists every layer it touches.** In the module file, there's a section per touched layer with at minimum a 2-line note. Each section follows the schema declared in that layer's `## Module slice schema`.
+
+4. **Ask, don't assume.** When the user's answer is ambiguous, stop and ask one short clarification. Do not invent column names, endpoint paths, or business rules. **Special case — user-need rationale:** if the *why* behind a module or change is unclear, that is a hard stop. Name your gap and ask before authoring. Do not infer the user-need from technical context alone.
+
+5. **Bounded scope per file.** If a module file heads past ~250 lines, propose splitting one or more layer slices out into a per-module subdirectory: convert `modules/MXX-<slug>.md` into `modules/MXX-<slug>/`, with the module's own substance in `MXX-<slug>.md` and each extracted layer slice in `LY-<slug>.md` (filename matches the corresponding `layers/LY-<slug>.md`).
+
+6. **No code, no tests, no build config.** You are writing specification. If the user asks for code, stay in-role: "This prompt is scoped to the spec — I can describe behavior; a separate implementation pass writes the code."
+
+7. **Version-safe numbering.** Module *and layer* numbers are stable. If a module or layer is deleted mid-design, leave the number retired rather than renumbering survivors. Layers are appended in introduction order — do not reshuffle when a deeper-concern layer is added later. Mark in `<index>`: `M04 — (retired)` or `L3 — (retired)`.
+
+8. **Acceptance criteria are observable.** Each criterion in a module's "Acceptance criteria" checklist must be something a reader could verify by using the system, not a vague goal.
+
+9. **No historical breadcrumbs in spec prose.** When you move content between files, **just move it**. Do not leave behind prose like *"(moved to M20)"*, *"see M07 for new location"*, or empty stub files that only redirect. Anchors (`<!-- anchor: xxxxxxxx -->`) are stable identifiers; the page/entity versioning subsystem owns move history.
+
+   *Distinguish from referential cross-links, which stay:* sentences like *"M04 plugs into L6"* or *"see M03 for the endpoint contract"* describe architecture, not history — keep them. Only forbid prose whose sole purpose is to tell a reader *"this used to live somewhere else."* Tabular state markers like `M04 — (retired)` are fine.

package/dist/server/skills/layered-vertical-slices/templates/index.md

@@ -0,0 +1,97 @@
+<!--
+Template for the index file of a layered-vertical-slices spec.
+Copy this file, rename it (default `index.md`, or `SKILL.md` if the spec is also a Claude Code skill), and replace placeholders.
+See SKILL.md §5 and §6 for guidance.
+-->
+
+# Specification: <Project Name>
+
+<2–4 sentences describing what the project is and who uses it.>
+
+> **Spec target:** <Research prototype | MVP | Feature-complete | Production-hardened>.
+> <1 sentence on what this scope includes and what it explicitly defers to a later spec.>
+
+## Core principle
+
+<One sentence that captures the architectural soul of the system. E.g.:
+"Markdown is the source of truth for content; SQLite is the source of truth for entities; XML tags are the bridge.">
+
+## High-level architecture
+
+<Optional: an ASCII diagram or a brief prose description of the main components and data flow. Skip if the system is simple.>
+
+## Key concepts
+
+<3–5 foundational truths the system is designed around — stated from the project's worldview, not as a tour of how this spec organizes them. Each concept names *what is true about the system as designed* (a principle, an invariant, a stance the project takes); it is not a description of how the concept is later realized across modules, layers, files, or anchors.
+
+Write so a reader can grasp the concept before opening any module or layer file. Do not cross-reference MXX / LY / filenames / anchors here — those belong in the modules table, layer table, and key-relations diagram below. If a concept can only be explained by pointing at where it lives in the spec, it isn't a key concept yet; it's spec mechanics — drop it or rephrase it as the underlying principle.>
+
+### <Concept 1>
+<1 paragraph: state the principle/invariant, then a concrete intuition for what it means in practice — without naming spec internals (no MXX, no LY, no file paths).>
+
+### <Concept 2>
+<1 paragraph.>
+
+## Jobs this spec serves
+
+*Optional — recommended for Feature-complete and Production-hardened targets; usually skipped for Research prototype and MVP. Distilled from Phase 1 topic 1 ("Users & jobs"). Modules are checked against this table — every module should serve at least one job; jobs without modules are gaps.*
+
+| Job | Primary user | Modules involved | Success looks like |
+| --- | --- | --- | --- |
+| J1 | … | M01, M03 | … |
+| J2 | … | M02 | … |
+
+## Layers
+
+Conventions shared across modules live in `layers/`:
+
+| Layer | File | Purpose |
+| --- | --- | --- |
+| **L1 — <name>** | `layers/L1-<slug>.md` | <1 line> |
+| **L2 — <name>** | `layers/L2-<slug>.md` | <1 line> |
+| … | … | … |
+
+## Modules
+
+Each module is a vertical slice through the layers. Modules skip layers they don't touch.
+
+| # | Module | Complexity | Layers | Scope | File |
+| --- | --- | --- | --- | --- | --- |
+| M01 | **<name>** | simple | L1, L2 | <1 line> | `modules/M01-<slug>.md` |
+| M02 | **<name>** | medium | L1, L2, L4, L5 | <1 line> | `modules/M02-<slug>.md` |
+| … | … | … | … | … | … |
+
+### Key relations
+
+<ASCII or prose diagram showing module → layer registrations, module ↔ module relations, and what-feeds-what. Example lines:
+
+M03 Endpoint     -- registers in --> L6 References  (rendering, tags)
+M03 Endpoint     <-- relation -->   M04 DTO         (request/response)
+M05 Agent        -- consumes --> M03, M04 MCP tools
+M01 Project      -- infrastructure --> all modules
+>
+
+## [Optional] <Layer-specific index>
+<Only if at least one module has been split into a per-module subdirectory. Cross-list extracted slices for one layer across modules — e.g. "DB schemas" listing every `modules/*/L1-<slug>.md`, "Agent tools" listing every `modules/*/L4-<slug>.md`.>
+
+| File | Module / Layer | Description |
+| --- | --- | --- |
+| `modules/M01-<slug>/L1-<slug>.md` | M01 / L1 | … |
+
+## Tech stack
+
+| Concern | Choice |
+| --- | --- |
+| Language | … |
+| Persistence | … |
+| … | … |
+
+## Acceptance criteria
+
+- [ ] <high-level outcome 1>
+- [ ] <high-level outcome 2>
+- [ ] …
+
+## Open questions
+
+1. <question — mark resolved with ~~strikethrough~~ + short note when answered>

package/dist/server/skills/layered-vertical-slices/templates/layer.md

@@ -0,0 +1,42 @@
+<!--
+Template for a layer file (`layers/LX-<slug>.md`) in a layered-vertical-slices spec.
+Copy this file, rename it, and replace placeholders.
+
+A layer file is **radically thin**: Purpose + Role + Module slice schema. Nothing else.
+For the rules driving that — what belongs in the slice schema vs. the implementor module,
+how to handle external/no implementor — see SKILL.md §2 (concepts), §5 (templates), §6 (quality rules).
+-->
+
+# LX — <Layer Name>
+
+> <1–2 sentence purpose statement.>
+
+## Role in the system
+
+<1–2 sentences, purely orientational: where this layer sits, what it enables, what it explicitly is NOT responsible for. Do not turn this into a conventions dump.>
+
+## Module slice schema
+
+<This is the only substantive section of a layer file. Define here the *shape* a consumer module's section for this layer takes — and bake every per-module rule (naming, validation, allowed values, gating, embed shape, required fields) into the schema as a requirement.>
+
+**Each module that touches this layer fills its `## <Layer name> (LX)` section with:**
+
+```
+<Concrete schema. Pick a form that fits your project — pick one or mix:
+ - prose with required headings,
+ - a fenced block (Zod / TypeScript type / SQL / table-of-fields),
+ - an embed of project entities,
+ - a table the module fills,
+ - or any combination.
+
+ Encode rules as schema requirements, not separate prose. Examples:
+ - "tables in snake_case" → field `Table name (snake_case)`
+ - "action gated by optional binary" → field `Gate (binary present? required field; absent? omit)`
+ - "validation: positive int" → field `Retries: positive int (default 3)`>
+```
+
+*Recommended shape when the project models entities:* declare the slice as an entity type and embed the live list via `<tagged_list type="<entity-type>" tags="MNN"/>`. Module prose then explains *why*; the canonical list stays in entities, drift becomes impossible. Skip this shape if the project has no entity machinery or the slice doesn't warrant it.
+
+> **Implementor module:** `MNN — <name>` *(or "external — <name>" when the implementor lives outside our spec, e.g. PostgreSQL, Express; or "none — pure description convention")*
+
+*If an implementor module is named*: it owns the **runtime, framework conventions, registry, hooks, and the "what consumers can rely on" half of the contract** for this layer — document them in its file's section for this layer (how-mode), not here.

package/dist/server/skills/layered-vertical-slices/templates/module.md

@@ -0,0 +1,52 @@
+<!--
+Template for a module file (`modules/MXX-<slug>.md`) in a layered-vertical-slices spec.
+Copy this file, rename it, and replace placeholders. See SKILL.md §5 and §6 for guidance.
+-->
+
+# MXX — <Module Name>
+
+> <1-sentence hook — what is this module, in the voice of the spec.>
+
+## Purpose
+
+<First sentence: name the user job this module enables — who does what, to what end. Avoid tautology ("M03 manages endpoints"); name the value ("Endpoint authors can describe HTTP contracts once and have them stay consistent across docs, code, and the running system"). If you cannot write this sentence without circularity, the module is premature — defer it to `<index>`'s "Open questions" until the user job is clear.>
+
+<2–4 more sentences: how this module realizes that job — entity shape, scope boundary, what it explicitly does NOT do.>
+
+## Dependencies
+
+| Module / Layer | Relation |
+| --- | --- |
+| L<X> | <what this module takes from the layer> |
+| M<YY> | <what this module relates to in another module> |
+
+## <Layer 1 name> (L1)
+
+<Only include sections for layers this module touches.>
+
+**If this module is a *consumer* of the layer** (the common case): fill the section using the layer's `## Module slice schema` — declare *what* this module contributes (tables, endpoints, entities, fields).
+
+**If this module is the *implementor* of the layer** (named in the layer file's `Implementor module:` slot): use this section to document *how* the layer is backed — runtime, registry, hooks, cross-cutting conventions (naming, error handling, structure), patterns consumers copy, the "what consumers can rely on" half of the contract, and any shared utilities. Everything that does not depend on a specific consumer module living lives here.
+
+<Content for how this module realizes L1. Example for a consumer:
+- Tables / file layout / schema link (e.g. "See `modules/M03-endpoint/L1-db.md` for full schema")
+- Key columns / fields
+- Constraints and indexes>
+
+## <Layer 2 name> (L2)
+
+<E.g. operations, lifecycle, validation rules, edge cases during operations.>
+
+## <Layer N name> (LN)
+
+…
+
+## Edge cases
+
+- <edge case 1: situation → expected behavior>
+- <edge case 2>
+
+## Acceptance criteria
+
+- [ ] <criterion 1>
+- [ ] <criterion 2>

package/dist/server/skills/layered-vertical-slices/workflows/bootstrap.md

@@ -0,0 +1,116 @@
+# Bootstrap workflow (greenfield spec)
+
+Use this when **no `<index>` file exists in the CWD** — the spec does not yet exist. If an index file is already present, use `workflows/daily.md` instead. Never run bootstrap on top of an existing spec; if the user wants a clean restart, ask them to move the existing spec aside first.
+
+Announce the phase at the start of each one ("**Phase 2: Layer proposal**") so the user can see progress. Do not skip phases. Do not write files before Phase 4.
+
+## Phase 1 — Project discovery
+
+Ask the following topics as **one-at-a-time** questions. Summarize the user's answer in 1–2 sentences before moving to the next. Skip a topic if clearly not applicable.
+
+Topic #1 (Users & jobs) is the foundation — the rest of the discovery flows from it. *Do not skip or compress it.* If the user pushes you toward stack or persistence first, redirect: "I'd like to hear who uses this and what jobs they're doing first — those choices should serve users, not the other way around."
+
+1. **Users & jobs.** Who uses this system, and what 2–4 jobs are they hiring it to do? For each job: what triggers it (the user's situation right before they reach for the system), and what would "done well" look like from their perspective? If there are multiple distinct user roles, list jobs per role. *Stay until the answer is concrete — vague answers like "manage data" or "configure things" produce specs that are about themselves. Push for verbs and outcomes.*
+2. **What is the system?** In 2–3 sentences, what does it do? (You already heard *who* and *what jobs* in topic 1; this question now answers itself in terms of the jobs above.)
+3. **Spec target.** What is the maturity target of *this* spec (not the eventual product)? Options:
+   - **Research prototype** — exploring feasibility; spec captures intent + open questions, minimal rigor, broken edges OK.
+   - **MVP** — smallest useful cut; only core modules, only core layers, deferrals explicit.
+   - **Feature-complete** — all planned functionality; full module set; edge cases and acceptance criteria rigorous.
+   - **Production-hardened** — feature-complete plus cross-cutting concerns: observability, auth, feature flags, i18n, versioning, migrations.
+
+   The answer **gates subsequent phases**:
+   - *Research / MVP* → skip or soft-ask topic #9 below (observability, feature flags, i18n rarely apply); aim for 3–5 modules in Phase 3; shorter acceptance criteria lists.
+   - *Feature-complete* → ask all topics; aim for 5–10 modules.
+   - *Production-hardened* → ask all topics with extra probing on observability, auth, and migrations; expect a dedicated cross-cutting layer for each; 8–15 modules is plausible.
+
+   Also note that a project can have multiple specs over its lifetime (MVP spec → feature-complete spec → hardening spec). If the user signals a future spec, add it as an item in `<index>`'s "Open questions" or a "Future scope" section.
+4. **Primary nouns.** What entities (things the user creates, reads, updates, deletes at runtime) live in the system? *Cross-check against topic 1 — every primary noun should map to at least one job; nouns without a job are usually scope creep.*
+5. **Stack & runtime.** Language, framework, deployment target (desktop app, web, CLI, library, service).
+6. **Persistence.** Database, files on disk, in-memory only, external API — and is there a preferred technology?
+7. **Interface surfaces.** How do users (and other agents) interact? UI, HTTP API, CLI, MCP tools, library exports — possibly several.
+8. **Agent/LLM involvement.** Is there an LLM agent in the loop? If yes, what does it do (read state, mutate state, converse, stream)?
+9. **Cross-cutting concerns.** Auth, i18n, versioning, events/hooks, observability, feature flags, background jobs. *(Skip or compress for Research / MVP targets.)*
+10. **Scope boundary.** What is explicitly *out of scope* for this spec? (Prevents scope creep later.) Encourage the user to name concrete things that are tempting but deferred — easier to enforce later.
+
+At the end of Phase 1, restate what you heard as a **project brief**. The brief opens with a *Users & jobs heard:* paragraph — 3–5 bullets capturing whom the spec serves and the jobs they're hiring it to do (distilled from topic 1). The spec target follows on its own line (e.g. *"Target: MVP"*), then the rest of the brief (system, primary nouns, stack, etc.) in 5–10 more lines. Subsequent phases — layer proposal, module identification, module fill-in — will be checked against the *Users & jobs heard* bullets: every layer should serve at least one job (transitively, through its modules), and every module should serve at least one job directly. Ask the user to correct the brief. Do not proceed until they confirm.
+
+## Phase 2 — Layer proposal
+
+Based on the brief, propose a concrete set of layers specific to this project. Example shapes:
+- A CLI + library: `L1 Persistence`, `L2 CLI`, `L3 Library API`.
+- A web service with an agent in the loop: `L1 DB`, `L2 HTTP API`, `L3 UI`, `L4 Cross-entity Framework`. *(The agent — chat, MCP tool host, prompt/context handling — is typically a **module** in this shape, e.g. `M05 Chat & Agent`, not a layer. Make agent a layer only if multiple feature modules each ship their own agent-facing tools and share conventions for tool registration / streaming / error model.)*
+- An agent platform where every feature exposes agent tools: `L1 DB`, `L2 Agent Toolset Conventions`, `L3 HTTP API`, `L4 UI`.
+- A static content generator: `L1 Sources`, `L2 Transform`, `L3 Output`.
+
+**Do not propose `L2 Domain` (or `L Domain`, `Business Logic`, etc.).** Every module's domain — its operations, validations, lifecycle, edge cases — is the module's substance, not a layer (see SKILL.md §2 anti-pattern). If multiple modules share a specific cross-cutting *convention* (error envelope shape, audit columns, validation framework), name the layer after that convention precisely (`L2 Error model`, `L2 Audit conventions`) rather than the catch-all "Domain".
+
+Present as a table:
+
+| # | Layer | Purpose (1 line) |
+|---|-------|------------------|
+| L1 | … | … |
+
+Then ask:
+> Confirm this layer set, or suggest additions / renames / removals. Layers should be few enough to keep in your head (3–7) and generic enough that any module can declare which ones it touches.
+
+Iterate until the user confirms.
+
+## Phase 3 — Module identification
+
+From the entities + features, propose modules. For each, list which layers it touches. Present as a table:
+
+| # | Module | Complexity | Layers | Scope (1 line) | File |
+|---|--------|-----------|--------|----------------|------|
+| M01 | … | simple/medium/complex | L1, L2, L5 | … | `modules/M01-….md` |
+
+Guidance:
+- Each **entity type** from Phase 1 is a candidate module — sometimes one entity per module, sometimes several related entities (versioning, history, lookup tables) cluster into one domain slice. Decide per cluster, guided by user job rather than table count.
+- Non-entity features can also be modules (config, agent, sync) — see SKILL.md §2 "Vertical slices — modules".
+- Bootstrap/project-config is usually the first module (`M01`).
+- Modules can skip layers they don't touch (e.g. a pure-UI module might not touch L1).
+- Aim for 3–10 modules. If you're heading toward 15+, suggest merging related ones or deferring scope.
+
+Ask the user to confirm, reorder, add, or remove. Iterate until confirmed.
+
+## Phase 4 — Skeleton generation
+
+Now, and only now, write files. Create in this order:
+1. `<index>` (copy from `templates/index.md`) with the concepts, the confirmed layer table, the confirmed module table, and a *relations placeholder* section.
+2. One empty `layers/LX-<slug>.md` per layer (copy from `templates/layer.md`). Fill in *only* the title and purpose line; leave other sections as section headers with a one-line TODO.
+3. One empty `modules/MXX-<slug>.md` per module (copy from `templates/module.md`). Keep the per-layer section headers only for layers the module actually touches; delete the rest.
+4. Do **not** create per-module subdirectories up front. They are introduced lazily in Phase 5 only when a specific module's file outgrows the budget — at that point `modules/MXX-<slug>.md` is converted into `modules/MXX-<slug>/` with the slice extracted to `LY-<slug>.md` inside.
+
+After writing, list the created files back to the user and ask: *"Skeleton is in place. Ready to fill modules in order M01 → MNN, or a different order?"*
+
+## Phase 5 — Module-by-module fill-in
+
+For each module (in the chosen order), fill its file in two parts:
+
+1. **Module's own substance** (its domain — *not* a layer): `Purpose`, `Edge cases`, `Acceptance criteria`. Ask the user about the module's operations, validations, lifecycle, and edge cases here. This is the module file's heart and does not belong to any layer section.
+2. **Per-layer sections** — for each layer the module touches, ask a layer-scoped question and write the section following that layer's `## Module slice schema`. For example, for a module that touches L1 (persistence) and L3 (HTTP API):
+   - *"M03 persistence (L1): what columns does the entity have? Any unique constraints? Any relations?"* → write the L1 section per the layer's schema (or, if it dominates the module file, split M03 into `modules/M03-<slug>/` and move the slice to `modules/M03-<slug>/L1-<slug>.md`).
+   - *"M03 HTTP API (L3): what endpoints expose this entity?"* → write the L3 section per the layer's schema.
+
+Do not ask "what does this module do at the domain level" as a separate per-layer question — that's already covered by the module's `Purpose` and `Edge cases`. If the user starts describing operations and validations, capture them in the module's own substance, not in a "domain layer" section.
+
+After finishing a module, summarize what you captured and ask the user to confirm before moving to the next.
+
+## Phase 6 — Layer fill-in
+
+After all modules are written, fill each `layers/LX-<slug>.md`. Layer files are **radically thin** — only three things:
+
+- The layer's role in the system (1–2 orientational sentences).
+- **Module slice schema** — the only substantive section. The form in which each consumer module declares its slice (headings, fields, fenced schema, embeds, references to project entities). **Bake every per-module rule into the schema as a field-level requirement** — naming ("table name in snake_case"), validation ("retries: positive int"), gating ("required if optional binary present, omitted otherwise"), allowed values, embed shape. No separate `## Conventions` / `## Patterns` / `## Contracts` sections. When the project models entities and the layer's slice is enumerable, prefer entities embedded via XML tags (e.g. `<tagged_list type="<entity-type>" tags="MNN"/>`) — modules stay short, listings stay live, drift becomes impossible.
+- **Implementor module slot** — name the module that implements this layer, or write `external — <name>` when the implementor lives outside our spec (DB engine, HTTP framework, SDK), or `none — pure description convention`. See SKILL.md §2 for when each applies.
+
+If a per-module rule won't fit inside the schema, that's a signal — see SKILL.md §2 ("Where cross-cutting content lives") for how to resolve it. Reflect on the layer instead of adding a prose bucket to the layer file.
+
+**Implementor modules — second pass.** For every layer that names an *internal* implementor module, go to that module's file and expand its section for the layer to cover everything implementation-side: cross-cutting conventions (naming, error handling, structure), patterns consumers copy, contracts ("what consumers can rely on" / "what consumers must provide"), runtime registry, hooks, and shared utilities. The layer file does not duplicate any of this. Skip layers whose implementor is `external — <name>` or `none` — there is no in-spec module to expand.
+
+Apply the layer-purity rule (see SKILL.md §6) as you go: every line in a layer file must stay true if any single module is removed. If a sentence only makes sense because of M03, it belongs in M03, not here.
+
+After all layers are written, update `<index>`:
+- Fill in the *Key relations / dependencies* diagram (which modules depend on which, which modules register into which framework layers).
+- Add a final top-of-file paragraph summarizing the system.
+
+Announce completion and offer: *"Spec skeleton and contents are complete. Want me to (a) do a coverage review, (b) generate a one-page summary for onboarding, or (c) stop here?"*

package/dist/server/skills/layered-vertical-slices/workflows/brief.md

@@ -0,0 +1,154 @@
+# Brief workflow (release brief generation)
+
+Use this when **the active context is a brief thread** and you have just been called via `Skill("layered-vertical-slices")`.
+
+The brief artifact is consumed by **two audiences** — a human in the claude4spec UI, and a coding agent in another terminal that has only the raw bytes of the file. The second audience is load-bearing: everything below serves it.
+
+## A. Spec-format vs feature substance
+
+This is the most consequential filter in this workflow. In `layered-vertical-slices` the spec contains **two kinds of content** that look superficially similar in a `RawDelta`:
+
+1. **Feature substance** — what the *system* does, has, constrains. Lives mostly in `modules/MXX-*.md` per-layer sections, in entity records (DTO, Endpoint, Database Table, UI View), and in the `## Modules` row of `<index>` when a new module appears.
+2. **Spec-format conventions** — rules about *how to write the spec itself*. Lives in `layers/LX-*.md` files (`## Module slice schema` defines the *shape* a consumer module's section takes; `Implementor module:` slot names which module backs this layer; `## Role in the system` is orientational prose).
+
+A coding agent in another terminal cannot act on (2). Telling them "L3 API uses `<tagged_list type="endpoint" tags="MXX"/>` to embed live endpoint lists" is a rule for the *spec author*, not for the implementer. If a brief inlines such content as if it were a requirement, the implementer wastes effort matching the spec's authoring grammar instead of building the system.
+
+**Recognition table:**
+
+| `RawDelta` entry | Classification | Action in brief |
+| --- | --- | --- |
+| Diff inside `layers/LX-*.md` § `## Module slice schema` | spec-format | **Drop.** Exception: if the schema change implies new runtime behavior (e.g. a new required field that any module must now declare → the system must validate it somewhere), describe the *runtime consequence*, not the schema text. |
+| Diff inside `layers/LX-*.md` § `Implementor module:` slot | spec-format | **Drop.** This only renames who-implements-what in the spec; the system is unchanged. |
+| Diff inside `layers/LX-*.md` § `## Role in the system` | spec-format | **Drop.** Orientational prose for spec readers. |
+| New `layers/LX-*.md` file (whole file added) | mostly spec-format | Mention briefly that "the spec gained a new layer LX — \<name\> — which structures how modules describe \<topic\>" and stop. Do not transcribe the schema. The implementer cares only when modules start using this layer. |
+| Diff inside `modules/MXX-*.md` § per-layer (e.g. `## Database (L1)`, `## API (L3)`) | substantive | **Translate** to a system-level statement; inline the entities/fields/endpoints. |
+| Diff inside `modules/MXX-*.md` § `Purpose` / `Edge cases` / `Acceptance criteria` | substantive | **Translate** to system behavior. |
+| New `modules/MXX-*.md` file | substantive | Open with the module's purpose in one sentence, then walk its per-layer sections. |
+| Entity changes (DTO/Endpoint/Database Table/UI View — create/update/delete) | substantive | **Inline with full content.** See §B. |
+| Anchor injection (`<!-- anchor: xxxxxxxx -->`), heading rename, section reorder, typo fix, prose smoothing, comment edit | editorial | **Drop.** Editorial mechanics belong in version history, not in the brief. |
+| Diff in `<index>` § `## Modules` table (new row) | substantive | New module appeared — name it, give purpose. |
+| Diff in `<index>` § `## Layers` table (new row) | mostly spec-format | Same as "new layer file" — one-line mention. |
+| Diff in `<index>` § `## Open questions` | usually drop | Open questions are workshop notes, not commitments. Include only if the user explicitly asks for "spec status" framing. |
+| Diff in `<index>` § `## Tech stack` | substantive | A real change to runtime/dependencies — translate to "the system now runs on \<X\>". |
+| Diff in `<index>` § `## Acceptance criteria` (project-level) | substantive | Translate to observable behavior. |
+
+**Heuristic in one question:** *"Could a coding agent in another repo, with only this brief, do something concrete in response to this?"* If no — drop it.
+
+If after filtering nothing substantive remains in a release, say so explicitly: *"This release contains only editorial cleanup of the specification — no system behaviour changes."* Do not pad.
+
+## B. Inlining patterns (binding — the self-contained invariant)
+
+The reader has only this file. Every "see X" is a failure. Use plain prose to name things, then inline the substance.
+
+**DTO change** — write the field table:
+
+```
+The `User` DTO gained an `emailVerifiedAt` field:
+
+| field             | type                  | required |
+|-------------------|-----------------------|----------|
+| emailVerifiedAt   | string \| null (ISO)  | no       |
+
+Existing rows are backfilled to `null`; the field becomes required-on-write only after the rollout in v0.4.
+```
+
+**Endpoint change** — write method, path, request/response DTOs, status codes, tags:
+
+```
+New endpoint `POST /api/auth/verify-email`. Request: `{ token: string }`. Responses: 204 (success), 400 `INVALID_TOKEN`, 410 `TOKEN_EXPIRED`. Tagged `auth`.
+```
+
+**Database table / migration** — show the SQL fragment verbatim:
+
+````
+New column on `user`:
+
+```sql
+ALTER TABLE user ADD COLUMN email_verified_at TEXT;
+```
+````
+
+**UI View change** — name the route, the data it loads, key interactions:
+
+```
+New view at `/auth/verify` (component `VerifyEmailPage`): reads `?token=…` from the URL, calls `POST /api/auth/verify-email`, redirects to `/login` on success.
+```
+
+**Behavior change documented on a spec page** — translate the page edit into a system-level statement, then quote the substantive content (not the page mechanics):
+
+```
+The signup flow now requires email verification before login is allowed:
+
+> After signup the user receives a token by email and must call `POST /api/auth/verify-email`
+> with `{ token }`. Until that call succeeds, attempts to log in return 403 with code
+> `EMAIL_NOT_VERIFIED`.
+
+The previous magic-link fallback is removed; password + optional TOTP is the only login path.
+```
+
+NOT: *"The page `pages/auth/flow.md` lost a 12-line subsection and gained a 'Verify email' heading between `## Login` and `## Logout`."* — that describes the spec edit, not the system.
+
+## C. Forbidden grammar
+
+Never use these in a brief — they are claude4spec **UI grammar**, only resolvable inside the running app:
+
+- `<single_element type="…" slug="…"/>`
+- `<inline_mention type="…" slug="…">…</inline_mention>`
+- `<element_list type="…">…</element_list>`
+- `<tagged_list type="…" tags="…"/>`
+- `<tagged_list_mixed types="…" tags="…"/>`
+- `@page.md` mentions
+- Any reference like *"see release diff"* or *"per the spec"* without inlining the content
+
+In a terminal that does not have claude4spec running, these resolve to literal XML/markdown noise that confuses rather than helps. Whenever the source spec uses one of them, **resolve it inline**: read the entity content (DTO fields, endpoint shape, table columns) and paste the substance into the brief.
+
+## D. "For implementers" section
+
+This is the section a coding agent reads to act. It must be:
+
+- A bulleted or numbered list of **concrete edit targets** — file paths, function names, SQL/migration snippets, env var names.
+- Self-contained: the agent should be able to start editing immediately without opening any other file.
+- Ordered roughly by dependency (migrations before code that uses them, types before consumers, etc.).
+- Anchored to **modules and layers** when useful — e.g. "this lives in M03's L1 (database) section" — but the path/snippet is what the agent acts on, not the module reference.
+
+Example:
+
+```
+## For implementers
+
+1. Migration: add `migrations/0042_email_verified_at.sql` with `ALTER TABLE user ADD COLUMN email_verified_at TEXT;`. (Belongs to M07 / L1.)
+2. Update the `User` type in `shared/types.ts` — add `emailVerifiedAt: string | null`.
+3. New endpoint handler `server/routes/auth/verify-email.ts` — schema `z.object({ token: z.string() })`, returns 204 on success, 400/410 on failure (codes `INVALID_TOKEN`, `TOKEN_EXPIRED`). (M07 / L3.)
+4. Update the signup flow in `server/routes/auth/signup.ts:46` to call `sendVerificationEmail(user.id)` after user insert.
+5. UI: render a "Verify your email" banner in `client/components/AppShell.tsx` when `user.emailVerifiedAt === null`. (M07 / L5.)
+```
+
+NOT a "for implementers" section: bullet points like "implement email verification" or "add migration" — those are restatements, not edit targets.
+
+## E. Branch A / Branch B specifics for this style
+
+`brief-author` defines the two operating branches (A: initial generation, B: editorial). Apply this style's filters inside them.
+
+### Branch A — initial generation (this writing style)
+
+After `get_brief` and `get_release_diff(...)`:
+
+1. **Filter** every `RawDelta` entry through §A's recognition table. Drop spec-format and editorial entries up front; keep only feature substance.
+2. **Mine** the kept entries: pull entity shapes (DTO fields, endpoint method+path+DTOs, table columns, view URL/params) from `RawDelta.entities[].raw` and `.changes`. For module-section diffs, extract the substantive added lines.
+3. **Compose** the narrative:
+   - Open with a 2–4 sentence summary describing the *intent* of the release — the user-job the changes enable. The reader should learn *why* the release happened in the first paragraph.
+   - Group changes by user-visible theme (new capabilities, breaking changes, internal refactors), not by entity type or by spec page. Module/layer references stay as anchors *within* themes, not as the primary axis.
+   - For each theme: state what the system now does in plain prose, **inline the change content** per §B, avoid forbidden grammar per §C.
+   - Close with `## For implementers` per §D.
+4. **Initial brief detection** — if `frontmatter.from_release === null`, the release diff is synthetic (every entry is `op: 'create'`). Drop "what changed" framing entirely; describe what the system *is* at this point. Open with `# Initial brief: <to_release>` (already pre-filled by the system).
+
+### Branch B — editorial (this writing style)
+
+When the brief already has body content and the user asks for a change:
+
+- **"Make it shorter"** → tighten prose, never drop inlined entity shapes / file paths / signatures. The second audience needs facts intact.
+- **"Add X"** → use `insert_after_section({ anchor: '<8char>', content })`; pull the anchor from the body's `<!-- anchor: ... -->` comments. Prefer `anchor` over `heading`.
+- **"Fix the inlined endpoint shape"** → re-read `release-tools.get_release_diff(...)` for that entity; never paraphrase from memory.
+- **"Reframe for a different audience"** (e.g. "rewrite for a junior") → keep §B/§C/§D rules; only the prose register changes.
+
+If the user request would force you to break §C (forbidden grammar) — e.g. "just paste the `<tagged_list>` from the spec" — explain why that fails the second audience and offer the inlined alternative.