@naswerks/engineering-loop 0.1.0 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,8 @@
 {
   "name": "engineering-loop",
-  "owner": { "name": "naswerks" },
+  "owner": {
+    "name": "naswerks"
+  },
   "metadata": {
     "description": "The engineering loop as a Claude Code plugin: docs-* (knowledge), spec-* (execution), init."
   },
@@ -8,8 +10,12 @@
     {
       "name": "naswerks",
       "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
-      "version": "0.1.0",
-      "source": "./"
+      "version": "0.2.0",
+      "source": {
+        "source": "npm",
+        "package": "@naswerks/engineering-loop",
+        "version": "0.2.0"
+      }
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The engineering loop: a knowledge loop (docs-*) and an execution loop (spec-*) for repositories driven by hosted agent sessions, plus init to make a repository ready for both.",
   "author": { "name": "naswerks" },
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,35 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-20
+
+### Changed
+
+- The reading floor every seat reads is four documents plus the `_meta` trio: `patterns/code-organization.md`
+  (was `vertical-slice-anatomy.md` — it describes the layout a repository actually has and presumes no
+  pattern), `backend-patterns.md`, `frontend-patterns.md`, `testing.md`. `codegen.md` leaves the floor.
+- The standard set a role reads on top of the floor is seven documents, each drafted by `init` only when the
+  repository shows the concern and each carrying a `doc-index.md` row either way: `codegen`,
+  `state-management`, `ui-style-guide`, `design-tokens` (the token authority, split out of the style guide),
+  `long-running-workflows` (split out of `background-work`), `realtime-events`, `background-work`.
+  `spec-child` names them by path and says an absent one has a row saying `not detected`.
+- `docs/_meta/doc-index.md` § Role reading lists is the repository's reserved space: `Doc | what it gives
+  the seat | backend | frontend | mixed`. `spec-parent` copies a role's rows into every seed's `EXTRA DOCS`
+  line, so a team's own documents reach a seat as paths in its prompt rather than as an index to consult.
+- `spec-pipeline` sizes every spec for one session before context compacts, with no target count;
+  `engineering-loop.md` says the same in place of a session range.
+- `init doctor` fails a standard document that is absent without its `not detected` row, and any
+  Role-reading-lists row whose path does not exist.
+
+### Added
+
+- Templates `code-organization.md`, `design-tokens.md`, `long-running-workflows.md`.
+
+### Removed
+
+- The snapshot-stub pattern for the standard names: a repository names its documents with the standard
+  names directly; no pointer documents.
+
 ## [0.1.0] - 2026-09-20
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The engineering loop as a Claude Code plugin: a knowledge loop (docs-*), an execution loop (spec-*), and init for a fresh repository. The package root is the plugin root.",
   "license": "MIT",
   "type": "module",

package/references/docs-workflow.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.1.0 -->
+<!-- naswerks-loop: version=0.2.0 -->
 # Docs Workflow
 
 > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.

package/references/engineering-loop.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.1.0 -->
+<!-- naswerks-loop: version=0.2.0 -->
 # The Engineering Loop — flow, seats, skills, and the ceremony
 
 > The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`
@@ -170,7 +170,8 @@ diff.
    seat's own commit, so left alone it hands the NEXT seat a dirty tree. Goto 1.
 
 **Hard rules:** no commit/push without the relayed call; explicit staging, never `git add -A`, verified
-with `verify-staged`; codegen only through the command `patterns/codegen.md` names; component files as
+with `verify-staged`; codegen only through the command `patterns/codegen.md` names (when the repo has
+one); component files as
 `patterns/frontend-patterns.md` states; additive-only, never amend pushed commits; parallel sessions only
 when specs share no files — commits sequence regardless; seats run the pipeline's declared default model
 (allowlist-exact, set at creation), and an investigation-heavy seat may warrant a reasoning-heavier one.

package/skills/init/SKILL.md

@@ -37,10 +37,16 @@ docs/
   _meta/doc-index.md              the menu, written LAST — every doc that exists + three repo slots:
                                   ## Role reading lists · ## Apps and their build commands · ## The evidence tools
   research/ working/ archive/ guides/ patterns/ infrastructure/ features/     each with a README.md
-  patterns/vertical-slice-anatomy.md  patterns/backend-patterns.md  patterns/frontend-patterns.md
-  patterns/testing.md  patterns/codegen.md                          the floor — always drafted
-  patterns/state-management.md  patterns/ui-style-guide.md
-  infrastructure/realtime-events.md  infrastructure/background-work.md   only when the scan finds the concern
+  patterns/code-organization.md  patterns/backend-patterns.md
+  patterns/frontend-patterns.md  patterns/testing.md               the floor — always drafted; a repo
+                                                                   with no server side or no client side
+                                                                   gets an honest "not detected" doc
+  patterns/codegen.md  patterns/state-management.md  patterns/ui-style-guide.md
+  patterns/design-tokens.md  patterns/long-running-workflows.md
+  infrastructure/realtime-events.md  infrastructure/background-work.md
+                                                                   the standard set — drafted ONLY when
+                                                                   the scan finds the concern; every one
+                                                                   gets a doc-index row either way
 CLAUDE.md                          the Start-here stanza appended (created with only the stanza if absent)
 AGENTS.md                          the same stanza, only when the file already exists
 .claude/settings.json              the plugin pin merged in (never clobbers existing keys)
@@ -49,6 +55,19 @@ AGENTS.md                          the same stanza, only when the file already e
 Eight folders, and the set is closed. Anything else already under `docs/` is left alone and reported as
 "outside the loop's shape — not touched" — never an error, never a queue entry.
 
+**The standard set is shaped by what an engineering team usually has, and a team that lacks one of them
+is told so, not handed a placeholder.** A concern the scan finds no evidence for is NOT drafted; its
+`doc-index.md` § Role reading lists row says `not detected — no {library/mechanism} found`, and the
+report lists it under "not in this codebase". A seat that later meets the absent path reads that row and
+moves on. The floor four are the exception: every repository can answer "where the code lives", "how
+the server side is built", "how the client side is built" and "how tests run" — even when the answer to
+one of them is "no client side here" — so those are always written.
+
+**The reserved space.** § Role reading lists in `doc-index.md` is the repository's own table: one row
+per doc a role should read, standard or not. The coordinator copies a role's rows into every seat's
+`EXTRA DOCS` line, so a team's own docs reach a seat as paths in its prompt. `init` seeds the standard
+rows; the team adds its own, and can add a role column if its seats have kinds the loop does not ship.
+
 **Every template lives at the pack root under `templates/`** (`templates/docs/patterns/*.md`,
 `templates/docs/infrastructure/*.md`, `templates/docs/_meta/doc-index.md`, `templates/docs/readme-*.md`,
 `templates/claude-md-stanza.md`, `templates/settings-pin.json`). Under Claude Code the pack root is
@@ -91,9 +110,13 @@ not. `init` never overwrites, never reorders, never deletes.
    the only file init writes into a folder that already exists.
 2. `docs/_meta/docs-workflow.md` and `docs/_meta/engineering-loop.md` — byte copies of the pack's
    `references/*` (their first line is the version stamp; copy it with the file).
-3. The five floor drafts from `templates/docs/patterns/*.md`, filled as below.
-4. The conditional drafts — `state-management`, `ui-style-guide`, `realtime-events`, `background-work` —
-   only where pass 3 found the concern.
+3. The four floor drafts (`code-organization`, `backend-patterns`, `frontend-patterns`, `testing`) from
+   `templates/docs/patterns/*.md`, filled as below.
+4. The standard-set drafts — `codegen`, `state-management`, `ui-style-guide`, `design-tokens`,
+   `long-running-workflows`, `realtime-events`, `background-work` — only where pass 3 found the concern.
+   Evidence per concern: a `generated/` folder or codegen config; a state library; a UI library; a tokens
+   file or token layer; a saga / workflow / state-machine mechanism; a realtime library on either side; a
+   queue, worker or scheduler.
 5. `docs/_meta/doc-index.md` from its template, LAST, listing every doc that now exists under the four
    living folders (drafted or repo-owned), the three repo slots filled from the scan.
 6. The Start-here stanza (`templates/claude-md-stanza.md`) appended to `CLAUDE.md` (created if absent)
@@ -138,8 +161,9 @@ FAIL, so a CI job or a control plane can call it.
 | each of the eight folders | missing | README missing | present |
 | `_meta/docs-workflow.md`, `_meta/engineering-loop.md` | missing, or no stamp on line 1 | stamp behind the pack's version | stamp equals it |
 | `_meta/doc-index.md` and its three slot sections | missing | a slot carries only the absent-line | filled |
-| the five floor docs | missing | `status=draft`, or an `<!-- init: -->` left in | `status=current` |
-| the four conditional docs | — | `status=draft` when present | present and current, or absent |
+| the four floor docs | missing | `status=draft`, or an `<!-- init: -->` left in | `status=current` |
+| the seven standard docs | absent AND no doc-index row saying `not detected` | `status=draft` when present; absent with its row | present and current, or absent with its row |
+| every path a § Role reading lists row names | the row's path does not exist | — | resolves |
 | `CLAUDE.md` / `AGENTS.md` stanza · `.claude/settings.json` pin | — | missing | present |
 | `verify-staged` | — | not on PATH (the row carries the fallback) | resolvable |
 | every `docs/research/*/00-ignition-brief.md` | the five problems the control plane's parser emits (no `## The kick`; the kick has no blockquote; no `## The sequence`; the sequence holds no table; a row names no kind from `coordinator build fixit review retro witness docs-process`), or a spec a row names is missing from disk | — | clean |
@@ -157,7 +181,8 @@ state: the owner promotes each draft to `status=current` as they confirm it, sec
 
 - `init` is the front door of the pack; `docs-status` is the pulse after it. Run `docs-status` once the
   drafts are promoted to see the queue the way a session will.
-- The floor is always drafted, even in a repository with no frontend or no codegen — the reading floor
-  must RESOLVE for every seat kind, and "No frontend detected — fill this in" is an honest doc.
+- The floor four are always drafted, even in a repository with no frontend — the reading floor must
+  RESOLVE for every seat kind, and "No frontend detected — fill this in" is an honest doc. The standard
+  seven are drafted only on evidence; their absence is recorded, never papered over.
 - Counterpart skills: `spec-seat` (reads the floor), `spec-child` (reads the role rows), `spec-pipeline`
   (writes the brief `doctor` checks), `docs-write` / `docs-process` (the queue `doctor` reads).

package/skills/init/scripts/doctor.mjs

@@ -56,13 +56,20 @@ for (const name of ['docs-workflow.md', 'engineering-loop.md']) {
 }
 
 // ── 4. the reading floor and the conditional docs ───────────────────────────────────────────────
-const FLOOR = ['patterns/vertical-slice-anatomy.md', 'patterns/backend-patterns.md', 'patterns/frontend-patterns.md', 'patterns/testing.md', 'patterns/codegen.md'];
-const CONDITIONAL = ['patterns/state-management.md', 'patterns/ui-style-guide.md', 'infrastructure/realtime-events.md', 'infrastructure/background-work.md'];
+const FLOOR = ['patterns/code-organization.md', 'patterns/backend-patterns.md', 'patterns/frontend-patterns.md', 'patterns/testing.md'];
+const STANDARD = ['patterns/codegen.md', 'patterns/state-management.md', 'patterns/ui-style-guide.md', 'patterns/design-tokens.md', 'patterns/long-running-workflows.md', 'infrastructure/realtime-events.md', 'infrastructure/background-work.md'];
+const roleRows = (() => { const t = read(join(repo, 'docs', '_meta', 'doc-index.md')); return t === null ? null : sectionOf(t, '## Role reading lists'); })();
 for (const d of FLOOR) docRow(d, true);
-for (const d of CONDITIONAL) docRow(d, false);
+for (const d of STANDARD) docRow(d, false);
 function docRow(relPath, required) {
   const text = read(join(repo, 'docs', relPath));
-  if (text === null) { row(required ? 'FAIL' : 'ok', `docs/${relPath}`, required ? 'missing' : 'absent (drafted only when the scan finds the concern)'); return; }
+  if (text === null) {
+    if (required) { row('FAIL', `docs/${relPath}`, 'missing'); return; }
+    const rowText = roleRows === null ? null : roleRows.split('\n').find((l) => l.includes(relPath));
+    if (rowText && /not detected/i.test(rowText)) row('ok', `docs/${relPath}`, 'absent, and doc-index says why (not detected)');
+    else row('FAIL', `docs/${relPath}`, 'absent with no doc-index row saying it was not detected — a seat meeting this path has no answer');
+    return;
+  }
   const meta = /<!-- meta:[^>]*status=([a-z]+)/.exec(text);
   if (!meta) row('DEGRADE', `docs/${relPath}`, 'no <!-- meta --> line');
   else if (meta[1] === 'draft') row('DEGRADE', `docs/${relPath}`, 'status=draft — scanned, not decided');
@@ -70,6 +77,17 @@ function docRow(relPath, required) {
   if (/<!-- init:/.test(text)) row('DEGRADE', `docs/${relPath}`, 'an <!-- init: --> instruction was left in the file');
 }
 
+// ── 4b. every path a Role reading lists row names resolves ─────────────────────────────────────
+if (roleRows !== null) {
+  for (const line of roleRows.split('\n').filter((l) => l.trim().startsWith('|') && !/^\|\s*-/.test(l.trim()) && !/^\|\s*Doc\s*\|/i.test(l.trim()))) {
+    for (const m of line.matchAll(/`((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)`|\]\((?:\.\.\/)?((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)\)/g)) {
+      const p = m[1] || m[2];
+      if (/not detected/i.test(line)) continue;
+      row(existsSync(join(repo, 'docs', p)) ? 'ok' : 'FAIL', `doc-index row: docs/${p}`, existsSync(join(repo, 'docs', p)) ? '' : 'the row names a path that does not exist');
+    }
+  }
+}
+
 // ── 5. CLAUDE.md / AGENTS.md stanza, settings pin ───────────────────────────────────────────────
 for (const name of ['CLAUDE.md', 'AGENTS.md']) {
   const text = read(join(repo, name));

package/skills/spec-child/SKILL.md

@@ -34,16 +34,24 @@ apply** (`spec-seat`, Step 0). This list is for a build seat working from a spec
 
 ## Role — the adds, on top of spec-seat's Step 0 floor
 
+The loop's standard docs, by path. **Read every one that exists for your role.** One that is absent was
+not detected by `init` — `docs/_meta/doc-index.md` § Role reading lists carries a row saying so — and is
+not a missing-file finding. `patterns/codegen.md` is read by any seat that touches a generated folder.
+
 | Role | Adds |
 |---|---|
-| **frontend** | `patterns/state-management.md` · `patterns/ui-style-guide.md` · `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure UI" work) · plus your role's rows in `docs/_meta/doc-index.md` § Role reading lists |
-| **backend** | `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure API" work) · `infrastructure/background-work.md` as the task warrants · plus your role's rows in `docs/_meta/doc-index.md` § Role reading lists |
-| **mixed** | **NOT every set by default** — read the adds for the surfaces your spec ACTUALLY touches, decided at recon once you have read the spec. **This is the default role and it covers every surface with no role of its own** — a surface the repo names only in `docs/_meta/doc-index.md` § Role reading lists (a sidecar, a CLI, a worker) reads the row there; docs work needs nothing beyond the Step 0 floor |
+| **frontend** | `patterns/state-management.md` · `patterns/ui-style-guide.md` · `patterns/design-tokens.md` · `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure UI" work) · `patterns/codegen.md` when the client consumes generated types |
+| **backend** | `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure API" work) · `infrastructure/background-work.md` · `patterns/long-running-workflows.md` as the task warrants · `patterns/codegen.md` when the server side emits generated code |
+| **mixed** | **NOT every set by default** — read the adds for the surfaces your spec ACTUALLY touches, decided at recon once you have read the spec. **This is the default role and it covers every surface with no role of its own** — a CLI, a sidecar, a worker project; docs work needs nothing beyond the Step 0 floor |
+
+**This repository's own docs reach you as paths too, not as an index to consult:** the coordinator copies
+your role's rows from `docs/_meta/doc-index.md` § Role reading lists into your prompt's `EXTRA DOCS` line.
+Read those the same way. If your prompt carries no `EXTRA DOCS` line, read that section yourself once and
+say in your PLAN TLDR which rows you took.
 
 A role is *which docs does this build session read* — nothing else. Jobs are SEAT KINDS, not roles:
 `docs-process` is a session type of its own, and a spec that touches a surface with no role of its own is
-`mixed` with that surface's row. A doc-index row that says "no X detected" is an honest answer from `init`:
-that concern is not in this repo yet, and there is nothing to read for it.
+`mixed` with that surface's rows.
 
 ## Recon — the build seat's first act
 

package/skills/spec-parent/SKILL.md

@@ -32,13 +32,14 @@ hand-testing what shipped. Everything else that a human does hand-cranked, you d
 
 ## Read first
 
-**Step 0 — the same floor every seat reads, all eight.** You verify every seat's work, so you start
-from the context they build in. A coordinator that has not read `testing.md` cannot judge a receipt; one
-that has not read `codegen.md` cannot spot a hand-written generated file.
+**Step 0 — the same floor every seat reads, all seven, plus every standard doc this repository has.**
+You verify every seat's work, so you start from the context they build in. A coordinator that has not
+read `testing.md` cannot judge a receipt; one that has not read `codegen.md` (when the repo has one)
+cannot spot a hand-written generated file.
 
 `_meta/doc-index.md` · `_meta/docs-workflow.md` · `_meta/engineering-loop.md` ·
-`patterns/vertical-slice-anatomy.md` · `patterns/backend-patterns.md` · `patterns/frontend-patterns.md` ·
-`patterns/testing.md` · `patterns/codegen.md`
+`patterns/code-organization.md` · `patterns/backend-patterns.md` · `patterns/frontend-patterns.md` ·
+`patterns/testing.md` — then every doc `doc-index.md` § Role reading lists carries a path for.
 
 **Step 1 — the effort**, in order:
 
@@ -113,9 +114,12 @@ read the board and answer on first receipt rather than spending a round-trip.
    defect even when it works: there are then two sources for one contract and only one of them gets
    corrected.
 
-   **Pick the docs:** the role floor is settled (`spec-seat`'s Step 0 + `spec-child`'s role table) and
-   **extras are YOUR call per task** — scan `docs/_meta/doc-index.md` for the quick decision. When in
-   doubt, seed the doc: a seat reading one extra doc is cheaper than a seat guessing.
+   **Pick the docs:** the floor and the loop's standard docs are settled (`spec-seat`'s Step 0 +
+   `spec-child`'s role table). **This repository's own docs are yours to seed, by path, every time:** copy
+   the seat's role rows from `docs/_meta/doc-index.md` § Role reading lists into the prompt's `EXTRA DOCS`
+   line — a seat follows a path in its prompt and does not reliably follow an index. Then add the extras
+   the task itself warrants. When in doubt, seed the doc: a seat reading one extra doc is cheaper than a
+   seat guessing.
 
    **The seed-retirement rule:** each new seed restates ONLY what OVERRIDES a default (every seat
    re-acquires the defaults from the skill + umbrella from scratch) and DROPS what merely confirms them.
@@ -368,7 +372,7 @@ so read them as run-time obligations, not close-out ones:
   branch-deletion backstop. The fence fires on the commands a careful seat runs to PROVE its work.
 - Seats never edit `project-status.md` or memory files; never run `docs-write` unprompted; respect the
   umbrella's out-of-scope list; codegen only through the command `patterns/codegen.md` § Running codegen
-  names; component files laid out as `patterns/frontend-patterns.md` § Component files states. Run the
+  names (when the repo has one); component files laid out as `patterns/frontend-patterns.md` § Component files states. Run the
   suite lanes SERIALLY.
 - Cross-slice changes (touching a shipped spec's files) need your explicit approval and get recorded as
   a departure. Additive-only; never amend pushed commits.
@@ -440,7 +444,8 @@ Pipeline context: {umbrella path} (settled decisions — don't relitigate) + {pr
 (READ-ONLY, coordinator-owned — prior rows, deferred findings, and process incidents are your contract).
 
 EXTRA DOCS for this task (beyond your role's floor — read them):
-{the coordinator's picks from doc-index.md}
+{this repository's rows for the role, copied from doc-index.md § Role reading lists, by path}
+{the coordinator's task-specific picks}
 
 PRIOR SPECS ARE SHIPPED at {hash} — build against their ACTUAL shapes:
 {bullet the real endpoints, contracts, helpers-to-reuse, caveats, and coordinator-adopted requirements

package/skills/spec-review/SKILL.md

@@ -102,9 +102,12 @@ other; an identity or authorization plane that is trustworthy per-slice and forg
 ordinary correctness: null and error paths, concurrency, data loss, exception swallowing.
 
 **Lens 2 — the patterns, and the language.** Read the diff against `patterns/backend-patterns.md`,
-`patterns/frontend-patterns.md`, `patterns/vertical-slice-anatomy.md`, `patterns/testing.md`,
-`patterns/codegen.md` — and against ordinary good practice in the language, which no pattern doc covers
-exhaustively.
+`patterns/frontend-patterns.md`, `patterns/code-organization.md`, `patterns/testing.md`, and every
+standard doc the repository has (`patterns/codegen.md`, `patterns/state-management.md`,
+`patterns/ui-style-guide.md`, `patterns/design-tokens.md`, `infrastructure/realtime-events.md`,
+`infrastructure/background-work.md`, `patterns/long-running-workflows.md` — those that exist) plus the
+rows in `docs/_meta/doc-index.md` § Role reading lists — and against ordinary good practice in the
+language, which no pattern doc covers exhaustively.
 
 **A pattern break is not automatically a defect.** There are legitimate reasons to depart. Your job is
 that **every departure is IDENTIFIED and its reason stated** — an intentional break with a recorded reason

package/skills/spec-seat/SKILL.md

@@ -61,20 +61,24 @@ Then recon the tree: `git rev-parse HEAD`, `git status --porcelain`, `git branch
 
 | Doc | What it gives you |
 |---|---|
-| `patterns/vertical-slice-anatomy.md` | where a feature's files go, every stack the repo has |
+| `patterns/code-organization.md` | where the code lives and where a new piece goes, every stack the repo has |
 | `patterns/backend-patterns.md` | how the server side is built here |
 | `patterns/frontend-patterns.md` | how the client side is built here |
 | `patterns/testing.md` | how to write and RUN the suites — including the run protocol |
-| `patterns/codegen.md` | what is generated and how; never hand-write a generated folder |
 
 **That is the default set, required regardless of role** —
 `docs/_meta/doc-index.md` · `docs/_meta/docs-workflow.md` · `docs/_meta/engineering-loop.md` ·
-`patterns/vertical-slice-anatomy.md` · `patterns/backend-patterns.md` · `patterns/frontend-patterns.md` ·
-`patterns/testing.md` · `patterns/codegen.md`
+`patterns/code-organization.md` · `patterns/backend-patterns.md` · `patterns/frontend-patterns.md` ·
+`patterns/testing.md`
 <!-- A control plane may read this line + list as its preset hint (it looks for "default set" and "role" on
      one line, then collects the backticked paths until a blank line). Keep the phrase and the list
      contiguous, or the hint silently empties. -->
 
+**On top of the floor, your job skill names the loop's standard docs for your role by path, and your
+prompt's `EXTRA DOCS` line names this repository's own.** Read every one that exists. A standard doc that
+is absent was not detected by `init` — `docs/_meta/doc-index.md` § Role reading lists carries a row
+saying so — and is not a missing-file finding.
+
 A doc marked `status=draft` in its meta line was scanned by `init`, not decided by the repo's owners —
 read it as the starting point it is, and treat a rule it states without a cited source as a question for
 your PLAN TLDR, not a law.
@@ -365,8 +369,8 @@ doorbell with no follow-through**; if you receive one bare, retry anyway and say
   echo text — the deny layer matches text, not parsed verbs.
 - Prefer native read/glob/grep tools for reads; a shell read flows with its row like any other
   non-boundary call.
-- **Codegen only through the command `patterns/codegen.md` § Running codegen names** — never hand-write a
-  generated folder.
+- **Codegen only through the command `patterns/codegen.md` § Running codegen names** (when the repo has
+  one) — never hand-write a generated folder.
 - **Never improvise a qualifying path in.** If a push parks and the remedy you can think of is touching a
   `docs/working/` file or the tracker to satisfy a predicate, that is fabricating a receipt. Raise a
   `## MID-BUILD QUESTION` and price the options; do not execute it and do not invent a way around it.

package/templates/docs/_meta/doc-index.md

@@ -21,12 +21,11 @@
 
 | Doc | When to read |
 |-----|-------------|
-| [vertical-slice-anatomy](../patterns/vertical-slice-anatomy.md) | **Where a feature's files go**, per stack, and the new-feature checklist |
+| [code-organization](../patterns/code-organization.md) | **Where the code lives and where a new piece goes** — the folder shape as it is, per stack, and the add-a-feature checklist |
 | [backend-patterns](../patterns/backend-patterns.md) | **How the server side is built here** — data layer, API layer, write paths, registration |
 | [frontend-patterns](../patterns/frontend-patterns.md) | **How the client side is built here** — architecture rules, component kinds and files, state, styling |
 | [testing](../patterns/testing.md) | **How to write and RUN the suites** — the lanes and their exact commands, the run protocol, what to test where, the controls discipline |
-| [codegen](../patterns/codegen.md) | **What is generated and by which command** — never hand-write a generated file |
-<!-- init: add rows for state-management and ui-style-guide when they were drafted. -->
+<!-- init: add rows for codegen, state-management, ui-style-guide, design-tokens and long-running-workflows when they were drafted; the hook for each ends "(draft — scanned, not decided)". -->
 
 ## Infrastructure — what runs UNDER THE HOOD
 
@@ -49,15 +48,22 @@
 
 ## Role reading lists
 
-The adds a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). `spec-child`
-names the generic docs; this section is where THIS repository adds its own rows per role.
-
-| Role | Adds |
-|---|---|
-| **backend** | <!-- init: `infrastructure/realtime-events.md` when drafted, else "no realtime library detected"; `infrastructure/background-work.md` when drafted, else "no queue or worker detected" --> |
-| **frontend** | <!-- init: `patterns/state-management.md` when drafted, else "no state library detected"; `patterns/ui-style-guide.md` when drafted, else "no UI library detected"; `infrastructure/realtime-events.md` as above --> |
-| **mixed** | reads the rows above for the surfaces the spec touches; <!-- init: one row per surface the scan found that has no role of its own (a CLI, a sidecar, a worker project): "`{path to its doc, or the folder}` — {what it is}" --> |
-<!-- repo rows go here: a surface this repository has that the generic docs do not cover -->
+The docs a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). The `spec-child`
+skill names the loop's standard docs by path; this table is the repository's reserved space — one row per
+doc, saying which roles read it. The coordinator copies a role's rows into every seat's seed as
+`EXTRA DOCS`, so a seat sees paths, not this index. Add a row for any doc of your own a role should read;
+add a role column if your seats have kinds the loop does not ship.
+
+| Doc | What it gives the seat | backend | frontend | mixed |
+|---|---|---|---|---|
+<!-- init: one row per standard doc the scan found evidence for and drafted (codegen, state-management,
+     ui-style-guide, design-tokens, realtime-events, background-work, long-running-workflows), with the
+     roles that read it marked `x` (realtime-events: backend + frontend; state-management, ui-style-guide,
+     design-tokens: frontend; background-work, long-running-workflows: backend; codegen: any seat that
+     touches a generated folder). One row per standard doc NOT drafted, in the form
+     "| `patterns/state-management.md` | not detected — no state library found | | | |" so a seat that
+     meets the absent path knows why. `mixed` reads the rows for the surfaces its spec touches. -->
+<!-- repo rows go here: a doc this repository has that the loop's standard set does not name -->
 
 ## Apps and their build commands
 

package/templates/docs/infrastructure/background-work.md

@@ -32,11 +32,13 @@
 
 ## Long-running workflows
 
-<!-- init: scan — a saga / orchestration / state-machine base class, a job with stages.
-     fill — the shape (stages, per-item progress, exactly-once stage transitions and what guarantees them,
-     progress reporting to the client), one REAL workflow as the example, then `### Rules`.
-     absent — "No multi-stage workflow detected — fill this in when one appears: how stages chain, how a
-     stage transition happens exactly once, how progress is reported." -->
+Snapshot — multi-stage work (stages, per-item progress, exactly-once transitions) is the authority of
+[long-running-workflows](../patterns/long-running-workflows.md) when the repo has one; this page is the
+transport it runs on.
+
+<!-- init: fill — one sentence naming the workflow mechanism (from long-running-workflows.md when drafted).
+     absent — "No multi-stage workflow detected — every background job here is single-stage; fill this in
+     when one appears." -->
 
 ## Gotchas
 
@@ -50,4 +52,4 @@
 |------|---------|
 
 ## Lineage
-- **Related** — [backend-patterns](../patterns/backend-patterns.md) · [realtime-events](realtime-events.md)
+- **Related** — [backend-patterns](../patterns/backend-patterns.md) · [realtime-events](realtime-events.md) · [long-running-workflows](../patterns/long-running-workflows.md)

package/templates/docs/patterns/backend-patterns.md

@@ -93,4 +93,4 @@
      absent — "| (none detected) | fill this in: the base entity, the data context, the composition root |" -->
 
 ## Lineage
-- **Related** — [vertical-slice-anatomy](vertical-slice-anatomy.md) · [testing](testing.md) · [codegen](codegen.md)
+- **Related** — [code-organization](code-organization.md) · [testing](testing.md) · [codegen](codegen.md)

package/templates/docs/patterns/{vertical-slice-anatomy.md → code-organization.md}

@@ -1,20 +1,24 @@
-# Vertical Slice Anatomy
+# Code Organization
 
-> Where to place each piece when building a feature in this repository. Last verified {today}.
+> Where the code lives and where a new piece goes — the folder shape this repository actually uses, per
+> stack, and the checklist for adding a feature to it. Last verified {today}.
 <!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---
 
-## Feature structure
+## The shape
 
 <!-- init: scan — the folder layout two deep for every stack (Features/, src/app/, apps/*, packages/*,
-     cmd/, internal/, lib/), and ONE existing feature per stack.
-     fill — one ASCII tree per stack showing a REAL feature as it exists, side by side when there are
-     two, with a comment per folder saying what goes there; then one sentence per stack on what lives
-     OUTSIDE a feature (shared infrastructure, cross-cutting stores).
-     absent — "No feature layout detected — fill this in: where a feature's files go, per stack, as a
-     tree copied from a real one." -->
+     cmd/, internal/, lib/, a layered src/{Domain,Application,Infrastructure}), and ONE existing feature or
+     module per stack.
+     fill — name the organization as it IS (vertical slices, layers, packages in a monorepo, a flat
+     module tree — whatever the folders say), then one ASCII tree per stack showing a REAL feature/module
+     as it exists, side by side when there are two, with a comment per folder saying what goes there; then
+     one sentence per stack on what lives OUTSIDE a feature (shared infrastructure, cross-cutting code).
+     Do not describe a pattern the folders do not show.
+     absent — "No code layout detected — fill this in: where a feature's or module's files go, per
+     stack, as a tree copied from a real one." -->
 
 ```
 {stack A}                                 {stack B, if any}
@@ -25,22 +29,22 @@
 ## The kinds of file, and their roles
 
 <!-- init: scan — the kinds the trees above show (endpoint / model / query / service; page / component /
-     store; command / handler).
+     store; command / handler; a module's public surface).
      fill — a table `Kind | Role | Where | Owns` with one row per kind.
      absent — "No kinds detected — fill this in: each kind of file a feature holds, and what it owns." -->
 
 | Kind | Role | Where | Owns |
 |------|------|-------|------|
 
-## Checklist: new feature
+## Checklist: adding a feature
 
 <!-- init: scan — the trees above, the registration points (composition root, router, module list), the
      test conventions in patterns/testing.md § What to test where.
      fill — an ordered `- [ ]` checklist per stack: create X in {path} (one line on what it must extend
      or implement), register it in {file}, add the route/handler in {file}, add the tests the testing doc
      names for each kind, run the build. Each item is a real path.
-     absent — "- [ ] No feature layout detected — fill this in: the ordered steps that add a feature,
-     each naming its file." -->
+     absent — "- [ ] No layout detected — fill this in: the ordered steps that add a feature, each naming
+     its file." -->
 
 ### {stack A}
 
@@ -53,7 +57,7 @@
 ## Gotchas
 
 <!-- init: scan — CONTRIBUTING.md, CLAUDE.md, AGENTS.md, lint rules that fire on layout (import
-     boundaries, dependency-cruiser, ArchUnit-style rules).
+     boundaries, dependency-cruiser, ArchUnit-style rules, banned-symbol lists).
      fill — one `### Gotcha:` per written-down layout rule, citing its source file.
      absent — "No layout gotchas written down yet — fill this in the first time one bites." -->
 

package/templates/docs/patterns/design-tokens.md

@@ -0,0 +1,62 @@
+# Design Tokens
+
+> The token authority: which colour, spacing and typography tokens exist, what each means, and how
+> component CSS consumes them. Component usage (which class for which job) lives in
+> [ui-style-guide](ui-style-guide.md). Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — a tokens/theme file (a CSS file defining --* custom properties, a tailwind/daisyui
+     theme block, a design-system package), the global stylesheet, how themes are switched.
+     fill — two to four sentences: the token system, the library that emits it, how a theme is selected.
+     absent — this doc is only drafted when a tokens file or a UI library with a token layer is found. -->
+
+## Token reference
+
+<!-- init: fill — one table per family (`Token | CSS variable | Purpose | When to use`): brand, base /
+     surface, status; each row read from the tokens file, never invented.
+     absent — "No token definitions found — fill this in." -->
+
+### Brand
+
+| Token | CSS variable | Purpose | When to use |
+|-------|-------------|---------|-------------|
+
+### Base / surface
+
+| Token | CSS variable | Purpose | When to use |
+|-------|-------------|---------|-------------|
+
+### Status
+
+| Token | CSS variable | Purpose | When to use |
+|-------|-------------|---------|-------------|
+
+## Consuming tokens in component CSS
+
+<!-- init: scan — how existing component styles reference tokens (var(--…), a theme() helper, a mixin).
+     fill — the ONE rule in this repo's form ("use `var(--…)` directly; express opacity with `color-mix`;
+     never a literal colour"), a fenced example copied from a real stylesheet, and the dead forms to grep for
+     if the library moved majors.
+     absent — "No token consumption found in component styles — fill this in." -->
+
+## Rules
+
+<!-- init: scan — a style lint, a stylesheet rule spec, a CONTRIBUTING note.
+     fill — bold-lead imperative bullets, each citing its source when written down; the loop supplies one:
+     "**A stylesheet never names a colour** — every value is a token or a mix over one, so a skin or a dark
+     mode needs no per-component work."
+     absent — the one loop-supplied bullet, then "- No further token rules found written down — fill this
+     in." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+
+## Lineage
+- **Related** — [ui-style-guide](ui-style-guide.md) · [frontend-patterns](frontend-patterns.md)

package/templates/docs/patterns/frontend-patterns.md

@@ -89,4 +89,4 @@
      absent — "| (none detected) | fill this in: the app config, the routes, the shared components |" -->
 
 ## Lineage
-- **Related** — [vertical-slice-anatomy](vertical-slice-anatomy.md) · [testing](testing.md) · [codegen](codegen.md) · [backend-patterns](backend-patterns.md)
+- **Related** — [code-organization](code-organization.md) · [testing](testing.md) · [codegen](codegen.md) · [backend-patterns](backend-patterns.md)

package/templates/docs/patterns/long-running-workflows.md

@@ -0,0 +1,63 @@
+# Long-Running Workflows
+
+> How multi-stage work is orchestrated in this repository: the stages, per-item progress, exactly-once
+> transitions, and how progress reaches the client. The transport it runs on is
+> [background-work](../infrastructure/background-work.md). Last verified {today}.
+<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- naswerks-loop: draft; scanned={files} -->
+
+---
+
+## Overview
+
+<!-- init: scan — a saga / orchestration / workflow / state-machine base class or library (a saga
+     framework, a durable-functions style runtime, a job with named stages), the entities that record
+     stage state.
+     fill — two to four sentences: what a workflow is here, what guarantees it makes, and which features
+     use it.
+     absent — this doc is only drafted when a multi-stage workflow mechanism is found. -->
+
+## The shape
+
+<!-- init: fill — an ASCII diagram of one REAL workflow (trigger, stages, the transition that starts the
+     next stage, completion), then the base classes / tables that hold it.
+     absent — "No workflow found to diagram — fill this in with the first one." -->
+
+```
+{trigger} -> stage 1 -> stage 2 -> ... -> complete
+```
+
+## Exactly-once transitions
+
+<!-- init: scan — the code that decides a stage is done (a TryComplete, a row lock, a compare-and-set, an
+     idempotency key).
+     fill — what guarantees a stage transition happens once, with the real symbol named; what happens on a
+     retry; who owns the transition.
+     absent — "No transition guard found — fill this in: how a stage completes exactly once under
+     concurrency." -->
+
+## Per-item progress and failure
+
+<!-- init: fill — how an item starts, completes and fails inside a stage; what a stuck item looks like and
+     who reaps it; how progress is reported (an event, a poke, a row).
+     absent — "No per-item tracking found — fill this in." -->
+
+## Creating a new workflow — checklist
+
+<!-- init: fill — an ordered `- [ ]` list: the base class to extend, the stage events or handlers to add,
+     the registration, the tests the testing doc names (the concurrency test especially).
+     absent — "- [ ] No workflow mechanism detected — fill this in when one appears." -->
+
+## Rules
+
+<!-- init: scan — comments on the base class, CONTRIBUTING notes.
+     fill — bold-lead imperative bullets citing their source.
+     absent — "- No workflow rules found written down — fill this in." -->
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+
+## Lineage
+- **Related** — [background-work](../infrastructure/background-work.md) · [backend-patterns](backend-patterns.md) · [testing](testing.md)

package/templates/docs/patterns/state-management.md

@@ -70,4 +70,4 @@
 |------|---------|
 
 ## Lineage
-- **Related** — [frontend-patterns](frontend-patterns.md) · [vertical-slice-anatomy](vertical-slice-anatomy.md)
+- **Related** — [frontend-patterns](frontend-patterns.md) · [code-organization](code-organization.md)

package/templates/docs/patterns/testing.md

@@ -100,4 +100,4 @@ A test that cannot go red is a green light with a test's name on it. For every p
      absent — "| (none detected) | fill this in: the runner config, the shared fixtures, the CI workflow |" -->
 
 ## Lineage
-- **Related** — [backend-patterns](backend-patterns.md) · [frontend-patterns](frontend-patterns.md) · [vertical-slice-anatomy](vertical-slice-anatomy.md)
+- **Related** — [backend-patterns](backend-patterns.md) · [frontend-patterns](frontend-patterns.md) · [code-organization](code-organization.md)

package/templates/docs/patterns/ui-style-guide.md

@@ -1,7 +1,7 @@
 # UI Style Guide
 
 > Which class or component to reach for, for which job, and the composition rules that keep screens
-> consistent — plus the design tokens and how to consume them. Last verified {today}.
+> consistent. The tokens themselves are the authority of [design-tokens](design-tokens.md). Last verified {today}.
 <!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
@@ -52,12 +52,13 @@ Every data-driven page handles four states: **loading**, **error**, **empty**, *
 
 ## Tokens
 
-<!-- init: scan — a tokens/theme file, a global stylesheet, the UI library's token variables.
-     fill — a table `Token | CSS variable | Purpose | When to use` for brand, base and status tokens,
-     then the ONE consumption rule for component CSS (use `var(--…)` tokens, never a literal colour; how to
-     express opacity), and the dead forms to grep for if the library moved majors.
-     absent — "No design tokens detected — fill this in: the colour and spacing tokens and how component
-     CSS consumes them." -->
+Snapshot — the token authority is [design-tokens](design-tokens.md): which tokens exist, what each
+means, and the one rule for consuming them in component CSS. This page names the class for the job; that
+page names the value behind the class.
+
+<!-- init: fill — one sentence naming the token family this UI library exposes (from design-tokens.md when
+     drafted). absent — "No design tokens detected — the classes above are the whole vocabulary; fill this in
+     if a token layer appears." -->
 
 ## Forms
 
@@ -73,4 +74,4 @@ Every data-driven page handles four states: **loading**, **error**, **empty**, *
 |---------|-------|
 
 ## Lineage
-- **Related** — [frontend-patterns](frontend-patterns.md)
+- **Related** — [frontend-patterns](frontend-patterns.md) · [design-tokens](design-tokens.md)

package/templates/docs/readme-patterns.md

@@ -2,8 +2,8 @@
 
 Conventions to FOLLOW when writing code. Prescriptive: truth is by decision, so a mismatch between a
 pattern doc and the code is usually a code problem to flag, not a doc to rewrite. Every seat reads the
-floor (`vertical-slice-anatomy`, `backend-patterns`, `frontend-patterns`, `testing`, `codegen`)
-before it writes a line; a doc marked `status=draft` was scanned by `init`, not decided — promote it as
+floor (`code-organization`, `backend-patterns`, `frontend-patterns`, `testing`) before it writes a
+line, and its role's docs on top of it; a doc marked `status=draft` was scanned by `init`, not decided — promote it as
 you confirm each section.
 
 A README in this folder is never a queue entry.