Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
docs(skills): enforce STE-80 writing and add the /explain skill
naveenkash6568ff6e78bd
diff --git a/.ai/specs/AGENTS.md b/.ai/specs/AGENTS.mdindex 42d6f611f3..27897b3386 100644--- a/.ai/specs/AGENTS.md+++ b/.ai/specs/AGENTS.md@@ -27,7 +27,7 @@ Check `.ai/specs/` before modifying any module. Create or update specs when the3. Spec written in .ai/specs/{YYYY-MM-DD}-{title}.md with resolutions baked in(questions surfaced while writing go back to step 2 before the spec is final)4. Implementation proceeds phase-by-phase-5. Completed spec moves to .ai/specs/implemented/+5. Completed spec moves to .ai/specs/implemented/ (with its /explain .html, if any)6. PR links back to spec via "Tracking spec:" line```@@ -53,6 +53,12 @@ Examples:| Small bug fix or typo | Skip spec || One-file refactor, no behavior change | Skip spec |+## HTML explainers++A spec may have a sibling `{same-name}.html` made by `/explain`. The `.md` is+the source of truth. After you edit a spec, find the stale pages with the+loop in `/explain` → "Keeping pages fresh", and regenerate each one.+## Spec TemplateUse `.ai/specs/template.md` as a starting point for new specs.diff --git a/.ai/specs/template.md b/.ai/specs/template.mdindex b083939ae4..e6885ae343 100644--- a/.ai/specs/template.md+++ b/.ai/specs/template.md@@ -8,6 +8,18 @@One paragraph summary of what this spec proposes.+## Overview diagram++One Mermaid diagram that explains the whole change. Choose its type with the+table in `/spec-writing` Step 6. Replace this sample.++```mermaid+flowchart LR+ A["Current step"] --> B["Changed step"]:::hot --> C["New step"]:::new+ classDef hot stroke-width:3px+ classDef new stroke-dasharray:4 3+```+## Problem StatementWhat's wrong or what's missing. Include concrete examples if possible.diff --git a/.claude/rules/writing-ste.md b/.claude/rules/writing-ste.mdnew file mode 100644index 0000000000..2c1cda3134--- /dev/null+++ b/.claude/rules/writing-ste.md@@ -0,0 +1,146 @@+---+paths:+ - ".ai/specs/**"+ - ".ai/plans/**"+ - ".ai/research/**"+ - ".ai/runs/**"+---++# Writing style for specs, plans and explainers — "STE-80"++Prose in `.ai/specs/`, `.ai/plans/`, `.ai/research/`, `.ai/runs/`, every+`/explain` page, and the hand-off message that presents any of them follows+**STE-80**: about 80% of the way to ASD-STE100 Simplified Technical+English, the controlled language that aerospace maintenance manuals use. The+full standard is too strict for design work. STE-80 keeps the rules that make+text easy to read and drops the rules that would distort Carbon's vocabulary.++Why: a reader must understand a spec or a plan fast and in one pass. Long+sentences, passive voice and noun stacks hide who does what. A weak executor+model also follows short, literal instructions much better than an essay.++Scope: prose only. Code, SQL, identifiers, commands and quoted error text stay+exact.++## The rules (keep these)++| # | Rule | Limit |+|---|------|-------|+| 1 | Procedural sentence (an instruction) | max **20 words** |+| 2 | Descriptive sentence (a fact, a reason) | max **25 words**; a rationale may go to 30 |+| 3 | One instruction per sentence | split "do X and then do Y" into two steps |+| 4 | Instructions use the imperative | "Run the migration.", not "The migration should be run." |+| 5 | Active voice | name the actor: "The trigger sets `status`", not "`status` is set" |+| 6 | Paragraph | max **6 sentences**, one topic |+| 7 | Sequence of actions | numbered vertical list, one action per item |+| 8 | Condition before action | "If the job is Paused, skip it." |+| 9 | Warning before the step it guards | put the 🛑 / caution line first, then the step |+| 10 | One word, one meaning | pick a term and keep it; never alternate synonyms for variety |+| 11 | Simple word over complex word | use, start, end, help, show, about — not utilize, commence, terminate, facilitate, demonstrate, approximately |+| 12 | No noun clusters longer than 3 words | "the date the supplier confirms the order", not "supplier order confirmation date value" |+| 13 | Keep articles | write "the", "a"; telegraphic text ("Update row, return id") is allowed only inside numbered Steps lists and task `<summary>` lines |+| 14 | Simple tenses | present for facts, imperative for instructions, future only for planned behavior |+| 15 | No vague quantities | a number, a column name, or a named state — never "some", "various", "etc.", "as appropriate" |++## The 20% we drop (Carbon exceptions)++- **Domain terms are approved words.** Use the canonical term from+ `docs/content/src/glossary/terms.ts` (Make to Order, Pull from Inventory,+ Backflush, Lineside, Supersession) even when STE's dictionary has no entry for it. Do not+ replace a domain term with a "simpler" word — that creates rule 10 violations.+- **Identifiers in code font are approved words.** `jobMaterial`,+ `settleConsumeFirstLines`, `companyId` count as one word each.+- **`-ing` forms and phrasal verbs are allowed** when the alternative reads+ worse ("set up", "picking list"). STE forbids them; STE-80 does not.+- **Tables are preferred over prose** for any comparison, decision or mapping.+ A table cell does not need to be a full sentence.++## Before → after++| Before | After (STE-80) |+|--------|----------------|+| "It should be noted that in the event that the predecessor has insufficient stock to cover a whole assembly, the line will be redirected to the successor." | "If the predecessor's stock covers no whole assembly, the line moves to the successor." |+| "Utilize the existing service function to facilitate retrieval of the data." | "Use `getJobMaterialItemIds` to read the item ids." |+| "Validation and persistence of the supplier quote line price break quantity value occurs in the action." | "The route action validates the quantity of each price break. Then it saves the row." |+| "Various edge cases etc. should be handled appropriately." | "Handle 3 cases: quantity 0, a deleted item, and a cancelled job." |++## Enforcement — every time, no exceptions++STE-80 is a gate, not a guideline. It applies to every file you write or+change under `.ai/research/`, `.ai/specs/`, `.ai/plans/` and `.ai/runs/`, and to+the message that hands any of them to the human. It applies in every mode:+supervised, autonomous `/feature`, `/conductor`, and headless runs.++**STE-80 is the author's job, never the human's.** The human reviews the+decisions in a document. The human never checks its style. So:++- Write in STE-80 from the first sentence. Never draft in ordinary English+ with a plan to convert it later.+- Finish the review pass below yourself, before the human sees the file.+- Never ask the human to check STE-80, and never hand off a file "for an+ STE-80 review". If you cannot make a passage pass, rewrite it until it does.+- Never report a file as done while one self-check box is still unticked.++### Write-time habits++Use these as you write each sentence, not afterwards:++1. Start with the actor: "The route action saves the row", "SAP prints the certificate".+2. One fact or one instruction per sentence. Put a full stop where you would write "and".+3. Put the condition first: "If X, do Y."+4. Turn every sequence into a numbered list as you write it.+5. Use the term you used before. Do not switch to a synonym.+6. Write a number or a name, never "some", "various" or "etc.".++### The review pass++Do the **STE-80 review pass** on each such file before you hand it off or+mark a phase done. Do it again after every later edit to the file.++1. Read the whole file, one paragraph at a time. Skip code blocks, SQL,+ tables, headings and the Sources list.+2. For each sentence that runs past about two lines, count its words. A word+ in code font counts as one word.+3. Split each instruction over 20 words and each descriptive sentence over 25+ words. A rationale may go to 30.+4. Find each "is / are / was / were / be / been + past participle". If it hides+ who acts, rewrite it with the actor as the subject.+5. Split each paragraph that has more than 6 sentences.+6. Search the file for "etc.", "various", "some", "as appropriate", "TBD",+ "utilize", "facilitate", "approximately". Replace each one with a number,+ a name or a simpler word.+7. List the key terms of the document. Make sure each concept has one name only.+8. Do the self-check list at the end of this file. Tick every box before you+ continue.++**Subagent output is raw material, not finished prose.** A subagent does not+follow this rule unless you tell it to, and it writes its report for you, not+for the reader. So:++1. In every subagent prompt that returns prose for a document, add: "Write your+ report in STE-80 (`.claude/rules/writing-ste.md`)."+2. When the result arrives, never paste it into the document as it is. Rewrite+ each part in STE-80 and in the document's own terms.+3. After you merge a subagent's result into a document, do the STE-80 review+ pass on that document again, before any other step.+4. If a subagent edits a document directly, do the review pass on that+ document yourself when the subagent reports back. Do not trust the+ subagent's own claim that the prose is clean.+5. Check the facts too. A rewrite can turn a careful claim into a false+ general one ("ProShop and E2 print it" → "all products print it").++Red flags — each one means you are about to skip the gate:++- "The subagent's summary is already clear, I'll paste it."+- "It's only the research file; the spec is what people read."+- "Autonomous mode, no reviewer, I'll check at the end."+- "The subagent says it followed STE-80, so I can skip the review pass."+- "It's a small edit, no need for another review pass."++## Self-check before you finish a document++- [ ] No instruction sentence over 20 words, no descriptive sentence over 25 (30 for a rationale)+- [ ] No passive sentence that hides the actor+- [ ] Every multi-step action is a numbered list+- [ ] Each concept has exactly one name in the whole document+- [ ] No "etc.", "various", "as appropriate", "TBD"diff --git a/.claude/skills/README.md b/.claude/skills/README.mdindex c30cadcc5a..50ac6e5a9f 100644--- a/.claude/skills/README.md+++ b/.claude/skills/README.md@@ -69,6 +69,7 @@ in root-cause, BLOCKED in fix) always surface to the human.| `translate` | Fill missing i18n .po translations via cheap Haiku subagents | `packages/locale/locales/*/*.po` || `test-driven-development` | Red→green→refactor discipline (vitest) | tests-first code || `writing-skills` | House guide for authoring skills | skills |+| `explain` | HTML explainer (STE-80 prose + one diagram) for a spec, plan or research file | `{source}.html` beside the `.md` || `pr-explainer` | Self-contained HTML review aid for a PR | `.pr-review/*.html` || `pr-splitter` | Split a large PR into reviewable stacked PRs | branches + split notes || `carbon-design` | Carbon's design language: principles, page archetypes, components, states, copy, anti-patterns + mandatory design review for any ERP/MES UI | design brief + reviewed UI |@@ -83,6 +84,11 @@ in root-cause, BLOCKED in fix) always surface to the human.- Typecheck is always scoped: `pnpm exec turbo run typecheck --filter=<pkg>`.Whole-repo typecheck OOMs — no skill may prescribe it.- `pnpm run generate:types` after any migration, before typechecking.+- Every file a skill writes under `.ai/research/`, `.ai/specs/`, `.ai/plans/` or+ `.ai/runs/`, and its hand-off message, is written in STE-80 from the first+ draft and passes the STE-80 review pass. The human never checks the style. The skill rewrites subagent results in STE-80+ before they go into a file, and repeats the review pass after every merge+ (`.claude/rules/writing-ste.md` → Enforcement).- Commits only through `/check-and-commit` (explicit file staging, conventionalmessages); push only when the branch tracks a remote or the user asked.- Ephemeral output (screenshots, debug logs) goes to gitignored `.ai/scratch/`,diff --git a/.claude/skills/explain/SKILL.md b/.claude/skills/explain/SKILL.mdnew file mode 100644index 0000000000..45a283e161--- /dev/null+++ b/.claude/skills/explain/SKILL.md@@ -0,0 +1,275 @@+---+name: explain+description: Render a spec, plan, or research file from .ai/ as a self-contained HTML explainer saved beside it (same name, .html) — plain STE-80 prose, one SVG diagram of the whole change, before/after tabs, collapsible decisions and tasks — so a human understands it in minutes instead of reading the markdown. Use when asked to "explain this spec/plan", "make it readable", "visualize the plan", "make an HTML page for this", or after /spec-writing or /plan when someone must review the result. Do not use to design or change the content — the .md stays the source of truth (use /spec-writing or /plan) — and do not use for a pull request (use /pr-explainer).+---++# explain — turn a spec or plan into a page a human can understand fast++Input: one markdown file in `.ai/specs/`, `.ai/plans/` or `.ai/research/`.+Output: `{same path}.html` beside it — one self-contained file, committed with+its source. The page explains the source. It never adds to it or replaces it:+`/plan` and `/execute` keep reading the `.md`.++The idea (from Andrej Karpathy): as agents write more of the work, humans spend+more time understanding it. Three layers help, in order: controlled plain+writing (STE-80), a diagram, and an interactive page. This skill produces all+three in one file.++**Announce at start:** "Using the explain skill — building the HTML explainer+for {source path}."++## Step 1: Resolve the source++| Request | Source |+|---------|--------|+| A path is given | that file |+| "the spec" / "this spec", no path | last-modified dated spec: `ls -t .ai/specs/2*.md \| head -1` |+| "the plan", no path | last-modified dated plan: `ls -t .ai/plans/2*.md \| head -1` |+| Two or more files match the user's words | ask which one — do not guess |++Pick the template:++| Source is under | Template |+|-----------------|----------|+| `.ai/plans/` | `.claude/skills/explain/assets/plan.html` |+| `.ai/specs/` or `.ai/research/` | `.claude/skills/explain/assets/spec.html` |++If the source is a spec with unchecked Open Questions (`- [ ]`), continue, but+show them in a `.callout.warn` at the top of "Decisions". The page must not+look final when the spec is not.++## Step 2: Read the source, then the code it names++1. Read the whole source file.+2. Read `.claude/rules/writing-ste.md`. Every sentence you write follows it.+3. Open each file, table or function that will appear anywhere on the page+ (diagram, tasks, decisions, terms). Confirm it exists: `ls {path}` or+ `grep -rn "{name}" {dir}`.++🛑 Every fact on the page comes from the source or from code you opened. Do not+add a fact to "complete the picture".++When the source and the code differ, use this table:++| The difference | Action |+|----------------|--------|+| The source describes the code BEFORE its change ("Cause", "Today", "Current behavior") | expected — explain it as the old behavior |+| A path or line number in the source no longer exists (the code moved) | show the file name without the line number; list it under "source drift" in the Step 7 report |+| The source's status does not match the code (says implemented but the code differs, or says draft but the code already has it) | do not choose one; explain the source, list it under "source drift" |+| The source contradicts itself (a design section vs an acceptance criterion) | render both as written, add a `.callout.warn` naming the two sections, list it under "source drift" |+| You cannot tell what the source means | STOP and ask the user |++Never correct the source on the page. The user fixes the source; then the page+is regenerated.++## Step 3: Choose the one picture++One diagram must explain the whole change. Choose it from this table — the+first row that matches wins:++| The source is mostly about… | Draw |+|-----------------------------|------|+| the source has a Mermaid overview diagram | the same picture in SVG: the same nodes, edges and changed (`hot` / `new`) marks — the spec author chose it |+| a plan (any plan) | task graph: one column per dependency layer (the plan template has it) |+| several independent fixes or changes (a bundle) | fix grid: one row per fix — fix name as `<text>` at x = 40, before box (`risk`) at x = 240, after box (`hot`) at x = 440, optional `small` note at x = 640; more than 6 fixes → a table instead of a figure |+| a status or lifecycle | state diagram: one box per status, one edge per transition, label each edge with its trigger |+| work that moves between people, modules or services | swimlanes: one lane per actor, boxes in time order left to right |+| a changed calculation or behavior | before → after: two rows of boxes, the same steps, the changed box `hot` |+| new or changed tables | entity boxes: table name + key columns, edges for foreign keys (the "Data model" figure) |+| none of the above | a left-to-right flow of the main steps |++Draw it with the SVG primitives already in the template (`.box`, `.box.hot`,+`.box.new`, `.box.risk`, `.lane`, `.edge`, `.edge.hot`, the `#arrow` markers).+Layout rules:++- `viewBox` width is 800. Make the height fit the content. Only the task+ graph may be wider (see the comment in `plan.html`).+- Box 160×56 (task graph: 160×48). Columns at x = 40, 240, 440, 640 — at most+ 4 boxes in a row, 40px apart. Rows 90px apart (task graph: 70px).+- A label inside a 160px box is at most 18 characters. Put a longer detail in+ a second `<text class="small">` line or in the caption.+- At most 8 boxes in one figure. Two exceptions: the task graph (one box per+ task) and the fix grid (two boxes per fix, at most 6 fixes).+- Never put a color in the SVG. Use only the classes, so dark mode works.+- Give each `<svg>` an `aria-label` that says what it shows in one sentence.+- One main figure in "The picture". You may add ONE more figure only in the+ "Data model" section (spec) or below the task graph (plan, for example the+ shape of a new API). No third figure.++## Step 4: Copy the template and stamp the source++```bash+SRC=.ai/specs/2026-10-04-example.md # the source from Step 1+OUT="${SRC%.md}.html"+cp .claude/skills/explain/assets/spec.html "$OUT" # plan.html for a plan+git hash-object "$SRC"+# Expected: a 40-character hex hash+```++Put `$SRC` in the `explain-source` meta, the kicker and the footer. Put the hash+in the `explain-source-hash` meta. Step 6 and "Keeping pages fresh" compare+that hash with the source to find a stale page.++## Step 5: Fill every section++Work top to bottom. Each `<!-- FILL: … -->` comment says what goes there.+Delete the comment after you fill its section. Delete a whole `<section>` when+the comment says it may be deleted and the source has nothing for it.++Writing rules (from `.claude/rules/writing-ste.md`):++- Rewrite, do not paste. A paragraph copied from the markdown is a failure.+- Instructions ≤ 20 words. Facts ≤ 25 words. One idea per sentence.+- Active voice: name the actor ("The route action saves the row").+- Use the term the source uses, the same one every time.+- Domain terms and code identifiers are allowed — put identifiers in `<code>`.++Specs do not all use the template headings. Map each source section by its+role. The names in brackets are the common alternatives.++Spec template mapping:++| Page section | From the source |+|--------------|-----------------|+| Kicker status | the source's Status line, verbatim ("Awaiting approval", "draft") |+| TL;DR (3 sentences) | TLDR [Summary] + Problem Statement [Problem, Background] |+| Scope | Goals / Non-goals [In scope / Out of scope]; delete when absent |+| The picture | Step 3 |+| The problem + Example | Problem Statement; the example uses synthetic numbers and names (Jane Doe, PART-001) |+| How it works | Proposed Solution [Design, Approach], as numbered actions |+| Before and after | the same scenario run through the old and the new behavior; for a bundle, one numbered item per fix in each tab |+| Decisions | the Design Decisions table + resolved Open Questions; `human` tag for `**Answer:**`, `assumed` tag for `**Autonomous:**`, no tag when no question traces to the row |+| Data model | Data Model Changes [Schema, Migrations]; delete when the source changes no schema |+| Done when | Acceptance Criteria [Done when, Success criteria] |+| Terms | every domain term a newcomer needs; copy the definition from `docs/content/src/glossary/terms.ts` when the term is there |++Plan template mapping:++| Page section | From the source |+|--------------|-----------------|+| Kicker branch / spec | the `**Branch:**` and `**Spec:**` lines; no line → delete the branch segment, write "none" for the spec |+| Progress bar | count `- [x]` and `- [ ]` in the Progress list (else in the Steps checklist) |+| Task graph | each task's `Depends on:` line; no such lines → list order, 4 per row, caption says so |+| Tasks | one `<details class="task">` per task (or per Steps item); add `done` when its box is checked; delete the Files / Verify / Stop-if parts the source does not give |+| Decisions | a Decisions / Notes section, if any; delete when absent |+| Risks and stop points | every "STOP" / "If … turns out false" line |+| Out of scope | every task's "Out of scope" line, without duplicates |++Interactive parts — use only these three:++1. **Tabs** (`[data-tabs]`) for before/after. The script is in the template.+2. **`<details>`** for depth a first-time reader can skip.+3. **A worked example calculator** — only when the source defines a formula+ (a quantity, a price, a rounding rule). Add `<input type="number">` fields+ prefilled with the source's example values and a few lines in the existing+ `<script>` that recompute the result. No libraries.++## Step 6: Check the page yourself++Do every check below on `$OUT`. Do not hand any of them to the human. If a+check fails, fix the page and do that check again.++**1. Nothing left from the template.** Search the page:++```bash+grep -n "FILL" "$OUT"+grep -nE '<(p|li|td|dd)( [^>]*)?>[[:space:]]*</(p|li|td|dd)>' "$OUT"+# Expected: no output from either command+```++Then search for the sample text of the template you copied. Each line below must+return nothing: "Sentence one.", "Step A", "Step B", "Feature name",+"Imperative title", "newThing", "newTable", "path/to/file.ts", "<dt>Term</dt>",+"Definition in one STE-80 sentence.", "YYYY-MM-DD-slug", "0 of 0 tasks".++**2. The page is one self-contained file.**++```bash+grep -nE '<(script|link|img|iframe)[^>]*(src|href)="(https?:)?//' "$OUT"+# Expected: no output+```++**3. Every SVG works in dark mode and has a label.**++1. Read each `<svg>`. It uses only the template classes (`.box`, `.edge`, …).+2. Make sure no `fill=`, `stroke=` or `style=` attribute holds a `#`, `rgb` or `hsl` color.+3. Make sure each `<svg>` tag has a non-empty `aria-label`.+4. Make sure no label is wider than its box and no edge crosses a box it does not connect to.++**4. The HTML is well-formed.** Read the page from top to bottom once. Every+`<section>`, `<details>`, `<div>`, `<ul>`, `<table>` and `<svg>` you opened+has its closing tag, in the right order. Pay most attention to the sections you+deleted or duplicated.++**5. The page matches its source.**++```bash+git hash-object "$SRC"+grep -o 'name="explain-source-hash" content="[^"]*"' "$OUT"+# Expected: the same 40-character hash in both lines+```++**6. The prose is STE-80.** Do the STE-80 review pass+(`.claude/rules/writing-ste.md` → Enforcement) on all page text. Skip code,+the SVG and quoted template text. Check these 3 limits:++1. Instruction sentences (plan tasks, verify steps): 20 words at most.+2. Fact sentences: 25 words at most. A spec's "How it works" steps are facts.+3. A rationale may go to 30 words.++**7. Every fact is real.** For each fact on the page, point to the line in the+source or the code you opened in Step 2. Delete a fact you cannot point to.++Then give the user the path and this command to open the page:++```bash+open .ai/specs/2026-10-04-example.html+```++## Step 7: Report++One short message: the page path, the diagram you chose and why (one line),+and the "source drift" list from Step 2 (or "no source drift"). Commit only when the user asks, through+`/check-and-commit`, with the `.html` and its source in the same commit.++## Done when++- [ ] `{source}.html` exists beside the source+- [ ] Every check in Step 6 passes, done by you, not the human+- [ ] The page has exactly one main diagram chosen by the Step 3 table+- [ ] No fact on the page is missing from the source or the code++## Keeping pages fresh++The page records the hash of its source. When the source changes, the page is+stale. To find every stale page, compare each page's recorded hash with its+source:++```bash+for page in $(grep -rl 'name="explain-source"' .ai --include='*.html'); do+ src=$(grep -o 'name="explain-source" content="[^"]*"' "$page" | sed 's/.*content="//; s/"$//')+ rec=$(grep -o 'name="explain-source-hash" content="[^"]*"' "$page" | sed 's/.*content="//; s/"$//')+ [ -f "$src" ] && [ "$(git hash-object "$src")" = "$rec" ] || echo "STALE $page"+done+# Expected: no output. Each STALE line names a page to regenerate.+```++For each stale page, run this skill again on its source. When a spec moves to+`.ai/specs/implemented/`, move its `.html` too and update the source path in+the meta, the kicker and the footer.++## Failure → action++| Symptom | Action |+|---------|--------|+| The source has neither a problem/design section (spec) nor a task or step list (plan) | STOP — tell the user which file you found and ask which one they meant |+| The main diagram needs more than 8 boxes (not a task graph) | draw the top level only, and put the detail in `<details>` sections |+| One Step 6 check fails twice after your fix | STOP — report the check and the section of the page it refers to |++## Red flags — stop and re-read this skill++- "I'll add a detail the spec forgot" — the page only explains; fix the source with /spec-writing.+- "This paragraph is fine as it is, I'll paste it" — rewrite it in STE-80.+- "A CDN chart library would be faster" — the page must work offline, as one file.+- "Three diagrams show it better" — one main picture, plus at most one in the allowed places (Step 3).+- "The code differs, so I'll describe the code" — explain the source and report the drift.diff --git a/.claude/skills/explain/assets/plan.html b/.claude/skills/explain/assets/plan.htmlnew file mode 100644index 0000000000..1cf98e7bb0--- /dev/null+++ b/.claude/skills/explain/assets/plan.html@@ -0,0 +1,218 @@+<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8" />+<meta name="viewport" content="width=device-width, initial-scale=1" />+<!-- FILL: source path and `git hash-object <source>` — the staleness check reads these two -->+<meta name="explain-source" content=".ai/plans/YYYY-MM-DD-slug.md" />+<meta name="explain-source-hash" content="0000000000000000000000000000000000000000" />+<!-- FILL: the feature name + "plan" -->+<title>Feature name plan</title>+<style>+ :root {+ --bg: #fbfbf9; --panel: #ffffff; --ink: #262323; --faint: #6b6764;+ --hairline: #e3e2de; --accent: #1e84b0; --accent-soft: #dff5ff;+ --warn: #a3520f; --warn-soft: #fff1e0; --ok: #2c7a14; --ok-soft: #e4f8da;+ --code-bg: #efefeb;+ }+ @media (prefers-color-scheme: dark) {+ :root {+ --bg: #141416; --panel: #1c1c1f; --ink: #ececea; --faint: #a3a19c;+ --hairline: #2e2e33; --accent: #5cc2ee; --accent-soft: #10303f;+ --warn: #f0a35e; --warn-soft: #3a2614; --ok: #8fd672; --ok-soft: #1b3112;+ --code-bg: #26262a;+ }+ }+ * { box-sizing: border-box; }+ body { margin: 0; background: var(--bg); color: var(--ink);+ font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }+ main { max-width: 880px; margin: 0 auto; padding: 48px 16px 96px; }+ h1 { font-size: 30px; line-height: 1.2; margin: 8px 0 12px; }+ h2 { font-size: 20px; margin: 56px 0 12px; padding-top: 24px; border-top: 1px solid var(--hairline); }+ h3 { font-size: 16px; margin: 24px 0 8px; }+ p, li { max-width: 72ch; }+ a { color: var(--accent); }+ code { font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;+ background: var(--code-bg); border-radius: 4px; padding: 1px 5px; }+ .kicker { color: var(--faint); font-size: 13px; letter-spacing: .06em; text-transform: uppercase; }+ .tldr { font-size: 18px; border-left: 3px solid var(--accent); padding: 4px 0 4px 16px; margin: 0; }+ .callout { border-radius: 10px; padding: 12px 16px; margin: 16px 0; border: 1px solid var(--hairline); }+ .callout.example { background: var(--accent-soft); }+ .callout.warn { background: var(--warn-soft); }+ .callout .label { display: block; font-size: 11px; font-weight: 700; letter-spacing: .08em;+ text-transform: uppercase; color: var(--faint); margin-bottom: 4px; }+ ol.steps { padding-left: 0; list-style: none; counter-reset: s; }+ ol.steps li { counter-increment: s; position: relative; padding: 8px 0 8px 44px; }+ ol.steps li::before { content: counter(s); position: absolute; left: 0; top: 8px; width: 28px; height: 28px;+ border-radius: 50%; background: var(--accent-soft); color: var(--accent);+ font-weight: 700; font-size: 14px; display: grid; place-items: center; }+ figure { margin: 20px 0; background: var(--panel); border: 1px solid var(--hairline);+ border-radius: 12px; padding: 16px; overflow-x: auto; }+ figcaption { color: var(--faint); font-size: 14px; margin-top: 8px; }+ /* SVG diagram primitives — use these classes, never inline colors */+ svg.diagram { display: block; width: 100%; height: auto; min-width: 560px; }+ svg .box { fill: var(--panel); stroke: var(--hairline); stroke-width: 1.5; }+ svg .box.hot { stroke: var(--accent); stroke-width: 2.5; fill: var(--accent-soft); }+ svg .box.new { stroke: var(--ok); stroke-width: 2; fill: var(--ok-soft); }+ svg .box.risk { stroke: var(--warn); stroke-width: 2; fill: var(--warn-soft); }+ svg .lane { fill: none; stroke: var(--hairline); stroke-dasharray: 4 4; }+ svg .edge { fill: none; stroke: var(--faint); stroke-width: 1.5; }+ svg .edge.hot { stroke: var(--accent); stroke-width: 2.5; }+ svg text { fill: var(--ink); font: 14px ui-sans-serif, system-ui, sans-serif; }+ svg text.small { fill: var(--faint); font-size: 12px; }+ svg text.mono { font-family: ui-monospace, Menlo, monospace; font-size: 13px; }+ svg marker path { fill: var(--faint); }+ svg marker.hot path { fill: var(--accent); }+ /* Tabs (before / after) */+ .tabs { border: 1px solid var(--hairline); border-radius: 12px; background: var(--panel); margin: 16px 0; }+ .tabs [role=tablist] { display: flex; gap: 4px; padding: 8px; border-bottom: 1px solid var(--hairline); }+ .tabs button { font: inherit; font-size: 14px; border: 0; background: none; color: var(--faint);+ padding: 6px 12px; border-radius: 8px; cursor: pointer; }+ .tabs button[aria-selected=true] { background: var(--accent-soft); color: var(--accent); font-weight: 600; }+ .tabs [role=tabpanel] { padding: 12px 16px; }+ .tabs [role=tabpanel][hidden] { display: none; }+ /* Decisions */+ details { border: 1px solid var(--hairline); border-radius: 10px; background: var(--panel); margin: 8px 0; }+ details > summary { cursor: pointer; padding: 10px 14px; list-style: none; }+ details > summary::-webkit-details-marker { display: none; }+ details > summary::before { content: "▸"; color: var(--faint); margin-right: 8px; display: inline-block; transition: transform .15s; }+ details[open] > summary::before { transform: rotate(90deg); }+ details > div { padding: 0 14px 12px 34px; }+ .choice { font-weight: 600; }+ .rejected { color: var(--faint); }+ .tag { display: inline-block; font-size: 11px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase;+ border-radius: 999px; padding: 1px 8px; margin-left: 6px; vertical-align: 2px; }+ .tag.human { background: var(--ok-soft); color: var(--ok); }+ .tag.assumed { background: var(--warn-soft); color: var(--warn); }+ table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }+ th, td { text-align: left; border-bottom: 1px solid var(--hairline); padding: 8px 10px; vertical-align: top; }+ th { color: var(--faint); font-weight: 600; }+ .table-wrap { overflow-x: auto; }+ ul.checks { list-style: none; padding-left: 0; }+ ul.checks li { padding: 6px 0 6px 28px; position: relative; }+ ul.checks li::before { content: "☐"; position: absolute; left: 0; color: var(--accent); }+ dl.terms dt { font-weight: 600; margin-top: 12px; }+ dl.terms dd { margin: 2px 0 0 0; color: var(--faint); max-width: 72ch; }+ footer { margin-top: 64px; color: var(--faint); font-size: 13px; border-top: 1px solid var(--hairline); padding-top: 16px; }+ /* Plan-only */+ .progress { height: 8px; background: var(--hairline); border-radius: 999px; overflow: hidden; margin: 12px 0 4px; }+ .progress > span { display: block; height: 100%; background: var(--ok); }+ .task .meta { color: var(--faint); font-size: 14px; }+ .task.done > summary { color: var(--faint); text-decoration: line-through; }+ .task pre { font: 13px/1.6 ui-monospace, Menlo, monospace; background: var(--code-bg); border-radius: 8px; padding: 10px 12px; overflow-x: auto; }+</style>+</head>+<body>+<main>++ <header>+ <!-- FILL: Plan · the plan's **Branch:** value (delete the segment if it has none) · date · source path -->+ <p class="kicker">Plan · BRANCH-OR-none · 2026-01-01 · <code>.ai/plans/YYYY-MM-DD-slug.md</code></p>+ <!-- FILL: the feature name -->+ <h1>Feature name — implementation plan</h1>+ <!-- FILL: goal — 2 STE-80 sentences: what exists when the plan is done, and how we prove it -->+ <p class="tldr">Sentence one. Sentence two.</p>+ <!-- FILL: done / total from the plan's Progress checklist (else its Steps checklist); width = done/total as a percent.+ Spec: the plan's **Spec:** path, or the word "none". -->+ <div class="progress"><span style="width: 0%"></span></div>+ <p class="kicker">0 of 0 tasks done · spec: <code>SPEC-PATH-OR-none</code></p>+ </header>++ <section>+ <h2>Task graph</h2>+ <!-- FILL: one column per dependency layer (layer 0 = tasks with no dependencies).+ Column x positions: 40, 240, 440, 640, then +200 per extra column (widen the viewBox+ by 200 each time; the figure scrolls). Box 160×48, rows 70px apart.+ No "Depends on:" lines in the plan → draw the tasks in list order, 4 per row, no+ "Layer" labels, and say in the caption that the arrows show list order only.+ Edges go from a task to the tasks that depend on it.+ class "new" = done, "hot" = next task to run, "risk" = task with a STOP condition. -->+ <figure>+ <svg class="diagram" viewBox="0 0 800 200" role="img" aria-label="FILL: task dependency graph">+ <defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" /></marker>+ </defs>+ <text class="small" x="40" y="24">Layer 0</text>+ <text class="small" x="240" y="24">Layer 1</text>+ <rect class="box new" x="40" y="40" width="160" height="48" rx="8" />+ <text x="120" y="69" text-anchor="middle">1 · Migration</text>+ <path class="edge" d="M200,64 L238,64" marker-end="url(#arrow)" />+ <rect class="box hot" x="240" y="40" width="160" height="48" rx="8" />+ <text x="320" y="69" text-anchor="middle">2 · Types</text>+ </svg>+ <!-- FILL: one sentence on which tasks can run in parallel -->+ <figcaption>Tasks in the same column can run in parallel.</figcaption>+ </figure>+ </section>++ <section>+ <h2>Tasks</h2>+ <!-- FILL: one <details class="task"> per plan task, in order. Add class "done" when its+ Progress box is checked. Summary = number + imperative title. Body = what it does+ (1–2 STE-80 sentences), files, verify command + expected output, STOP condition.+ Delete each sub-part (Files / Verify / Stop if) the source does not give — never+ fill one in from the code. -->+ <details class="task">+ <summary><b>1.</b> Imperative title</summary>+ <div>+ <p class="meta">Depends on: none</p>+ <p></p>+ <p class="meta">Files</p>+ <ul><li><code>path/to/file.ts</code> — what changes</li></ul>+ <p class="meta">Verify</p>+ <pre>command+# Expected: output</pre>+ <div class="callout warn"><span class="label">Stop if</span><p>The assumption that, if false, ends the task.</p></div>+ </div>+ </details>+ </section>++ <section>+ <h2>Decisions</h2>+ <!-- FILL: the plan's decisions, if it lists any (a Decisions / Notes section). Same shape+ as the spec page: summary = question + choice, body = why. Delete if there are none. -->+ <details>+ <summary>Question? <span class="choice">Choice.</span></summary>+ <div><p>Why: </p></div>+ </details>+ </section>++ <section>+ <h2>Risks and stop points</h2>+ <!-- FILL: every STOP / escape-hatch line in the plan, as a table. Delete if there are none. -->+ <div class="table-wrap">+ <table>+ <tr><th>Task</th><th>Stop if</th><th>Then</th></tr>+ <tr><td></td><td></td><td></td></tr>+ </table>+ </div>+ </section>++ <section>+ <h2>Out of scope</h2>+ <!-- FILL: the union of every task's "Out of scope" line, deduplicated. Delete if there are none. -->+ <ul><li></li></ul>+ </section>++ <footer>+ <!-- FILL: source path -->+ Generated by <code>/explain</code> from <code>.ai/plans/YYYY-MM-DD-slug.md</code>.+ If this page and the source disagree, the source is correct.+ </footer>++</main>+<script>+ // Tabs: no dependencies. Works for every [data-tabs] block on the page.+ document.querySelectorAll("[data-tabs]").forEach(function (root) {+ var tabs = root.querySelectorAll("[role=tab]");+ var panels = root.querySelectorAll("[role=tabpanel]");+ tabs.forEach(function (tab, i) {+ tab.addEventListener("click", function () {+ tabs.forEach(function (t, j) { t.setAttribute("aria-selected", String(i === j)); });+ panels.forEach(function (p, j) { p.hidden = i !== j; });+ });+ });+ });+</script>+</body>+</html>diff --git a/.claude/skills/explain/assets/spec.html b/.claude/skills/explain/assets/spec.htmlnew file mode 100644index 0000000000..b9fb76ab83--- /dev/null+++ b/.claude/skills/explain/assets/spec.html@@ -0,0 +1,260 @@+<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8" />+<meta name="viewport" content="width=device-width, initial-scale=1" />+<!-- FILL: source path and `git hash-object <source>` — the staleness check reads these two -->+<meta name="explain-source" content=".ai/specs/YYYY-MM-DD-slug.md" />+<meta name="explain-source-hash" content="0000000000000000000000000000000000000000" />+<!-- FILL: the feature name, 2–5 words -->+<title>Feature name</title>+<style>+ :root {+ --bg: #fbfbf9; --panel: #ffffff; --ink: #262323; --faint: #6b6764;+ --hairline: #e3e2de; --accent: #1e84b0; --accent-soft: #dff5ff;+ --warn: #a3520f; --warn-soft: #fff1e0; --ok: #2c7a14; --ok-soft: #e4f8da;+ --code-bg: #efefeb;+ }+ @media (prefers-color-scheme: dark) {+ :root {+ --bg: #141416; --panel: #1c1c1f; --ink: #ececea; --faint: #a3a19c;+ --hairline: #2e2e33; --accent: #5cc2ee; --accent-soft: #10303f;+ --warn: #f0a35e; --warn-soft: #3a2614; --ok: #8fd672; --ok-soft: #1b3112;+ --code-bg: #26262a;+ }+ }+ * { box-sizing: border-box; }+ body { margin: 0; background: var(--bg); color: var(--ink);+ font: 16px/1.65 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }+ main { max-width: 880px; margin: 0 auto; padding: 48px 16px 96px; }+ h1 { font-size: 30px; line-height: 1.2; margin: 8px 0 12px; }+ h2 { font-size: 20px; margin: 56px 0 12px; padding-top: 24px; border-top: 1px solid var(--hairline); }+ h3 { font-size: 16px; margin: 24px 0 8px; }+ p, li { max-width: 72ch; }+ a { color: var(--accent); }+ code { font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;+ background: var(--code-bg); border-radius: 4px; padding: 1px 5px; }+ .kicker { color: var(--faint); font-size: 13px; letter-spacing: .06em; text-transform: uppercase; }+ .tldr { font-size: 18px; border-left: 3px solid var(--accent); padding: 4px 0 4px 16px; margin: 0; }+ .callout { border-radius: 10px; padding: 12px 16px; margin: 16px 0; border: 1px solid var(--hairline); }+ .callout.example { background: var(--accent-soft); }+ .callout.warn { background: var(--warn-soft); }+ .callout .label { display: block; font-size: 11px; font-weight: 700; letter-spacing: .08em;+ text-transform: uppercase; color: var(--faint); margin-bottom: 4px; }+ ol.steps { padding-left: 0; list-style: none; counter-reset: s; }+ ol.steps li { counter-increment: s; position: relative; padding: 8px 0 8px 44px; }+ ol.steps li::before { content: counter(s); position: absolute; left: 0; top: 8px; width: 28px; height: 28px;+ border-radius: 50%; background: var(--accent-soft); color: var(--accent);+ font-weight: 700; font-size: 14px; display: grid; place-items: center; }+ figure { margin: 20px 0; background: var(--panel); border: 1px solid var(--hairline);+ border-radius: 12px; padding: 16px; overflow-x: auto; }+ figcaption { color: var(--faint); font-size: 14px; margin-top: 8px; }+ /* SVG diagram primitives — use these classes, never inline colors */+ svg.diagram { display: block; width: 100%; height: auto; min-width: 560px; }+ svg .box { fill: var(--panel); stroke: var(--hairline); stroke-width: 1.5; }+ svg .box.hot { stroke: var(--accent); stroke-width: 2.5; fill: var(--accent-soft); }+ svg .box.new { stroke: var(--ok); stroke-width: 2; fill: var(--ok-soft); }+ svg .box.risk { stroke: var(--warn); stroke-width: 2; fill: var(--warn-soft); }+ svg .lane { fill: none; stroke: var(--hairline); stroke-dasharray: 4 4; }+ svg .edge { fill: none; stroke: var(--faint); stroke-width: 1.5; }+ svg .edge.hot { stroke: var(--accent); stroke-width: 2.5; }+ svg text { fill: var(--ink); font: 14px ui-sans-serif, system-ui, sans-serif; }+ svg text.small { fill: var(--faint); font-size: 12px; }+ svg text.mono { font-family: ui-monospace, Menlo, monospace; font-size: 13px; }+ svg marker path { fill: var(--faint); }+ svg marker.hot path { fill: var(--accent); }+ /* Tabs (before / after) */+ .tabs { border: 1px solid var(--hairline); border-radius: 12px; background: var(--panel); margin: 16px 0; }+ .tabs [role=tablist] { display: flex; gap: 4px; padding: 8px; border-bottom: 1px solid var(--hairline); }+ .tabs button { font: inherit; font-size: 14px; border: 0; background: none; color: var(--faint);+ padding: 6px 12px; border-radius: 8px; cursor: pointer; }+ .tabs button[aria-selected=true] { background: var(--accent-soft); color: var(--accent); font-weight: 600; }+ .tabs [role=tabpanel] { padding: 12px 16px; }+ .tabs [role=tabpanel][hidden] { display: none; }+ /* Decisions */+ details { border: 1px solid var(--hairline); border-radius: 10px; background: var(--panel); margin: 8px 0; }+ details > summary { cursor: pointer; padding: 10px 14px; list-style: none; }+ details > summary::-webkit-details-marker { display: none; }+ details > summary::before { content: "▸"; color: var(--faint); margin-right: 8px; display: inline-block; transition: transform .15s; }+ details[open] > summary::before { transform: rotate(90deg); }+ details > div { padding: 0 14px 12px 34px; }+ .choice { font-weight: 600; }+ .rejected { color: var(--faint); }+ .tag { display: inline-block; font-size: 11px; font-weight: 700; letter-spacing: .06em; text-transform: uppercase;+ border-radius: 999px; padding: 1px 8px; margin-left: 6px; vertical-align: 2px; }+ .tag.human { background: var(--ok-soft); color: var(--ok); }+ .tag.assumed { background: var(--warn-soft); color: var(--warn); }+ table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }+ th, td { text-align: left; border-bottom: 1px solid var(--hairline); padding: 8px 10px; vertical-align: top; }+ th { color: var(--faint); font-weight: 600; }+ .table-wrap { overflow-x: auto; }+ ul.checks { list-style: none; padding-left: 0; }+ ul.checks li { padding: 6px 0 6px 28px; position: relative; }+ ul.checks li::before { content: "☐"; position: absolute; left: 0; color: var(--accent); }+ dl.terms dt { font-weight: 600; margin-top: 12px; }+ dl.terms dd { margin: 2px 0 0 0; color: var(--faint); max-width: 72ch; }+ footer { margin-top: 64px; color: var(--faint); font-size: 13px; border-top: 1px solid var(--hairline); padding-top: 16px; }+</style>+</head>+<body>+<main>++ <header>+ <!-- FILL: artifact kind · the source's own Status value, verbatim · date · source path -->+ <p class="kicker">Spec · draft · 2026-01-01 · <code>.ai/specs/YYYY-MM-DD-slug.md</code></p>+ <!-- FILL: the feature name -->+ <h1>Feature name</h1>+ <!-- FILL: TL;DR — exactly 3 STE-80 sentences: the problem, the change, the result for the user -->+ <p class="tldr">Sentence one. Sentence two. Sentence three.</p>+ </header>++ <section>+ <h2>The picture</h2>+ <!-- FILL: the ONE diagram that explains the whole change (see SKILL.md Step 3 for which kind).+ Copy the primitives below; move/duplicate them; delete what you don't use.+ Coordinates: viewBox is 800 wide; boxes are 160×56; columns at x = 40, 240, 440, 640 (4 per row, 40px gaps).+ Mark the changed parts with class "hot" (changed), "new" (added) or "risk". -->+ <figure>+ <svg class="diagram" viewBox="0 0 800 220" role="img" aria-label="FILL: one-sentence description of the diagram">+ <defs>+ <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" /></marker>+ <marker id="arrow-hot" class="hot" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" /></marker>+ </defs>+ <!-- lane (optional: one per actor/module) -->+ <rect class="lane" x="10" y="10" width="780" height="200" rx="10" />+ <text class="small" x="24" y="32">Lane / actor name</text>+ <!-- box -->+ <rect class="box" x="40" y="80" width="160" height="56" rx="8" />+ <text x="120" y="113" text-anchor="middle">Step A</text>+ <!-- edge -->+ <path class="edge" d="M200,108 L238,108" marker-end="url(#arrow)" />+ <!-- changed box + hot edge -->+ <rect class="box hot" x="240" y="80" width="160" height="56" rx="8" />+ <text x="320" y="105" text-anchor="middle">Step B</text>+ <text class="small" x="320" y="124" text-anchor="middle">what changed</text>+ <path class="edge hot" d="M400,108 L438,108" marker-end="url(#arrow-hot)" />+ <!-- new box -->+ <rect class="box new" x="440" y="80" width="160" height="56" rx="8" />+ <text class="mono" x="520" y="113" text-anchor="middle">newThing</text>+ </svg>+ <!-- FILL: one STE-80 sentence that tells the reader where to look first. Write your own;+ the sample caption below is a placeholder; replace it. -->+ <figcaption>Read left to right. The blue box is the part that changes.</figcaption>+ </figure>+ </section>++ <section>+ <h2>Scope</h2>+ <!-- FILL: from the source's Goals / Non-goals (or In scope / Out of scope). Delete this+ section if the source has neither. -->+ <div class="table-wrap">+ <table>+ <tr><th>In scope</th><th>Out of scope</th></tr>+ <tr><td></td><td></td></tr>+ </table>+ </div>+ </section>++ <section>+ <h2>The problem</h2>+ <!-- FILL: 2–4 STE-80 sentences: what happens today and why it is wrong -->+ <p></p>+ <div class="callout example">+ <span class="label">Example</span>+ <!-- FILL: one concrete case with real-looking (synthetic) numbers and names -->+ <p></p>+ </div>+ </section>++ <section>+ <h2>How it works</h2>+ <!-- FILL: the new behavior as a numbered sequence, one action per item, ≤20 words each -->+ <ol class="steps">+ <li></li>+ </ol>+ </section>++ <section>+ <h2>Before and after</h2>+ <!-- FILL: the same scenario before and after. Delete this section if the spec adds+ something new and nothing existed before. -->+ <div class="tabs" data-tabs>+ <div role="tablist">+ <button role="tab" aria-selected="true">Before</button>+ <button role="tab" aria-selected="false">After</button>+ </div>+ <div role="tabpanel"><p></p></div>+ <div role="tabpanel" hidden><p></p></div>+ </div>+ </section>++ <section>+ <h2>Decisions</h2>+ <!-- FILL: one <details> per row of the spec's Design Decisions table, most important first.+ summary = the question, then the choice. Body = why (≤30 words) + rejected options.+ Tag: "human" if an Open Question with **Answer:** settled it, "assumed" if **Autonomous:**+ settled it, NO tag if no question traces to it. Delete the "Rejected:" line when the+ source names no rejected option. -->+ <details>+ <summary>Question? <span class="choice">Choice.</span><span class="tag human">human</span></summary>+ <div>+ <p>Why: </p>+ <p class="rejected">Rejected: option — reason.</p>+ </div>+ </details>+ </section>++ <section>+ <h2>Data model</h2>+ <!-- FILL: one box per table (header = table name, then key columns), edges = foreign keys.+ Reuse the SVG primitives above. Delete this section if the spec changes no schema. -->+ <figure>+ <svg class="diagram" viewBox="0 0 800 160" role="img" aria-label="FILL: tables and their relations">+ <rect class="box new" x="40" y="20" width="220" height="120" rx="8" />+ <text class="mono" x="56" y="46">newTable</text>+ <text class="small mono" x="56" y="72">id, companyId (PK)</text>+ <text class="small mono" x="56" y="94">parentId → parent</text>+ </svg>+ </figure>+ </section>++ <section>+ <h2>Done when</h2>+ <!-- FILL: the spec's acceptance criteria, one per line, each testable -->+ <ul class="checks">+ <li></li>+ </ul>+ </section>++ <section>+ <h2>Terms</h2>+ <!-- FILL: every domain term or identifier a newcomer would not know. When the term is in+ docs/content/src/glossary/terms.ts, shorten its definition to one STE-80 sentence.+ Otherwise define it only with words the source itself uses. -->+ <dl class="terms">+ <dt>Term</dt><dd>Definition in one STE-80 sentence.</dd>+ </dl>+ </section>++ <footer>+ <!-- FILL: source path -->+ Generated by <code>/explain</code> from <code>.ai/specs/YYYY-MM-DD-slug.md</code>.+ If this page and the source disagree, the source is correct.+ </footer>++</main>+<script>+ // Tabs: no dependencies. Works for every [data-tabs] block on the page.+ document.querySelectorAll("[data-tabs]").forEach(function (root) {+ var tabs = root.querySelectorAll("[role=tab]");+ var panels = root.querySelectorAll("[role=tabpanel]");+ tabs.forEach(function (tab, i) {+ tab.addEventListener("click", function () {+ tabs.forEach(function (t, j) { t.setAttribute("aria-selected", String(i === j)); });+ panels.forEach(function (p, j) { p.hidden = i !== j; });+ });+ });+ });+</script>+</body>+</html>diff --git a/.claude/skills/feature/SKILL.md b/.claude/skills/feature/SKILL.mdindex 75e9efb21e..4202e78cd9 100644--- a/.claude/skills/feature/SKILL.md+++ b/.claude/skills/feature/SKILL.md@@ -130,6 +130,18 @@ Start at the first selected phase whose artifact is missing or stale:(and its changelog), re-gate (or re-record in autonomous mode), then resume.- Skipping a phase is a logged decision, not a silent omission — it goes in therun record with a reason.+- Everything this pipeline writes is in STE-80 from the first draft: research,+ spec, plan, the run record, and every phase hand-off message to the human.+ STE-80 is the author's job. Never ask the human to check the style.+- STE-80 is a gate at every phase transition, in both autonomous modes. Before+ you announce the next phase, do the STE-80 review pass+ (`.claude/rules/writing-ste.md` → Enforcement) on every research, spec or+ plan file the phase wrote or changed. Log "STE-80 pass done" for each file+ in the run record's Phase log.+- Subagent results are raw material. Rewrite them in STE-80 before they go into+ an artifact. After a subagent edits an artifact, do the review pass on it+ yourself. Never accept the subagent's own "clean" claim+ (`.claude/rules/writing-ste.md` → Enforcement).## Alternative: the conductordiff --git a/.claude/skills/grill/SKILL.md b/.claude/skills/grill/SKILL.mdindex 97ee1f7c52..b8dee437d1 100644--- a/.claude/skills/grill/SKILL.md+++ b/.claude/skills/grill/SKILL.md@@ -85,6 +85,9 @@ apply regardless of target:chat- [ ] Durable conventions reflected in `.claude/rules/`; glossary offers madewhere the three-part test passed+- [ ] Every resolution written to a spec or plan is in STE-80, and the+ STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) is+ done on that file## Anti-patternsdiff --git a/.claude/skills/improve/SKILL.md b/.claude/skills/improve/SKILL.mdindex 15b220ef7f..28806926b0 100644--- a/.claude/skills/improve/SKILL.md+++ b/.claude/skills/improve/SKILL.md@@ -123,6 +123,8 @@ Write each plan **for the weakest plausible executor**:Finish by writing `.ai/plans/improve/README.md` with the recommended execution order, dependencies, and a status column.+Every plan and the README follow STE-80 (`.claude/rules/writing-ste.md`). Do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) on each file before you present them.+## Invocation variants- Bare invocation → full workflow above.diff --git a/.claude/skills/plan/SKILL.md b/.claude/skills/plan/SKILL.mdindex a29248bc48..d519fce0f1 100644--- a/.claude/skills/plan/SKILL.md+++ b/.claude/skills/plan/SKILL.md@@ -70,6 +70,11 @@ Every task uses exactly this shape:Hard rules for task content:+- **Write every sentence in STE-80 from the first draft.** Use the write-time habits in `.claude/rules/writing-ste.md`. Never ask the human to check the style.+- **Prose follows STE-80** (`.claude/rules/writing-ste.md`): one instruction+ per step, imperative, at most 20 words. Step 5 makes the STE-80 review pass a gate.+ Rewrite any subagent report in STE-80 before it goes into a task.+- **Migrations**: create with `pnpm db:migrate:new <name>` (never hand-pick atimestamp; never `000000` as HHMMSS). SQL must use `id('prefix')` defaults,`companyId` + composite PK `("id", "companyId")`, audit columns@@ -122,6 +127,12 @@ file. Do not create a separate todo file.## Step 5: Self-check, then present+Do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) first.+Do it again after every later edit to the plan. If you corrected the spec+while planning, do the pass on the spec too.++- [ ] The STE-80 review pass is done for the plan (and for the spec if you+ edited it), and every self-check box in the rule is ticked- [ ] Every task has exact paths, exact commands, expected output- [ ] Every migration task follows the hard rules above and is followed by a`generate:types` step@@ -130,5 +141,6 @@ file. Do not create a separate todo file.- [ ] Every acceptance criterion in the spec is covered by at least one task,and the final task is browser verification via `/test` for user-facing work-Present the plan path and a one-paragraph summary. Wait for approval, then hand-off to `/execute`.+Present the plan path and a one-paragraph summary. Offer the reviewer view in+one line: "Want an HTML explainer of this plan? (`/explain`)" — run it only on+a yes. Wait for approval, then hand off to `/execute`.diff --git a/.claude/skills/research/SKILL.md b/.claude/skills/research/SKILL.mdindex 58da12bec8..c04a02fbe8 100644--- a/.claude/skills/research/SKILL.md+++ b/.claude/skills/research/SKILL.md@@ -54,10 +54,19 @@ Rules:- Be specific: `SAP S/4HANA inventory valuation methods`, not `SAP inventory`.- Fan searches out to subagents (one competitor or one question per subagent) tokeep the main context clean. Each subagent returns findings + source URLs only.+- End every subagent prompt with: "Write your report in STE-80+ (`.claude/rules/writing-ste.md`): short sentences, active voice, no 'etc.'."+ This makes the rewrite in Step 4 smaller. It does not replace that rewrite.- Focus on data models, workflows, and terminology — not screenshots or UI copy.## Step 4: Write the findings file+> 🛑 Write every sentence in STE-80 from the first draft (`.claude/rules/writing-ste.md` → Write-time habits). Never ask the human to check the style.+>+> Subagent reports are raw material. Never paste one into the findings file+> as it is. Rewrite each finding in STE-80 (`.claude/rules/writing-ste.md`)+> before it goes in. Use one term per concept across all competitors.+Save to `.ai/research/{feature-slug}.md` (kebab-case slug). Use exactly thisstructure:@@ -91,6 +100,19 @@ One paragraph: what was researched, key findings.- {URL}```+## Step 5: Do the STE-80 review pass++Do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement) on+`.ai/research/{feature-slug}.md`. Do it after the last subagent result is+merged, and again after any later edit.++1. Follow the 8 steps of the review pass in that rule, in order.+2. Check every merged finding against its subagent report. A rewrite must not+ turn a claim about one product into a claim about all products.+3. Tick every box of the rule's self-check list.++If a box still fails after 3 rewrite passes, STOP and report the failing lines.+## Done when- [ ] Every matching domain row was researched, SAP included@@ -98,6 +120,7 @@ One paragraph: what was researched, key findings.unanswered — carry it into the spec's Open Questions)- [ ] The findings file exists at `.ai/research/{slug}.md` with all sections filled- [ ] Every claim has a source URL in the Sources section+- [ ] The STE-80 review pass is done after the last edit, and every self-check box is ticked## Next stepdiff --git a/.claude/skills/spec-writing/SKILL.md b/.claude/skills/spec-writing/SKILL.mdindex d3c30ec161..33c45aa83a 100644--- a/.claude/skills/spec-writing/SKILL.md+++ b/.claude/skills/spec-writing/SKILL.md@@ -137,6 +137,15 @@ Only now. Copy `.ai/specs/template.md` to `.ai/specs/{YYYY-MM-DD}-{slug}.md`(today's date, kebab-case slug) and fill every section, with the Step-5resolutions baked into the design. Rules:+- Write every sentence in STE-80 from the first draft (`.claude/rules/writing-ste.md` → Write-time habits). Never ask the human to check the style.+- Prose follows STE-80 (`.claude/rules/writing-ste.md`): short sentences,+ active voice, one term per concept. Tables over paragraphs for decisions.+ Step 8 does the STE-80 review pass; the spec is not final until it passes.+- Never paste research text or a subagent report into the spec as it is.+ Rewrite it in STE-80 first.+- The **Overview diagram** section holds exactly one Mermaid diagram that+ explains the whole change (rules below). A Data Model section with new+ tables may add a second one, an `erDiagram`. No other diagrams.- SQL sketches use `id('prefix')`, `companyId`, composite PK, audit columns —never `gen_random_uuid()`.- Acceptance criteria must be testable: "user creates a PO with 3 lines and sees@@ -146,6 +155,39 @@ resolutions baked into the design. Rules:- The Open Questions section records the resolved Q&A (all boxes checked, eachwith its inline answer) — it is the audit trail of Step 5, not a to-do list.+### The overview diagram++Choose the type with this table. The first row that matches wins.++| The spec is mostly about… | Mermaid type |+|---------------------------|--------------|+| several independent fixes (a bundle) | `flowchart LR`, one `subgraph` per fix: old node → new node |+| a status or lifecycle | `stateDiagram-v2`, one edge per transition, labelled with its trigger |+| work that moves between people, modules or services | `sequenceDiagram`, one participant per actor |+| a changed calculation or behavior | `flowchart LR`, two `subgraph`s named Before and After, the same steps in each |+| new or changed tables only | `erDiagram` (precedent: `.ai/specs/implemented/2026-07-30-workflows-foundation.md`) |+| none of the above | `flowchart LR` of the main steps |++Syntax rules — nothing in this repo validates Mermaid, and a broken diagram+only shows as an error in a preview. Keep to these:++1. Put every node label in double quotes: `A["Pull from Inventory (old)"]`.+ Parentheses, colons, slashes and `#` break unquoted labels.+2. Node ids are plain letters and digits (`A`, `B2`, `oldPick`). No spaces,+ no hyphens.+3. Never write the word `end` as a node id or a bare label — it closes a+ `subgraph`. Quote it: `E["end"]`.+4. At most 12 nodes. A label is at most 30 characters.+5. Mark what changes, do not color it: `:::hot` for a changed node, `:::new`+ for an added node, with the two `classDef` lines from the template. Use no+ other colors, so the diagram reads in light and dark themes.+6. Put code identifiers in labels as plain text; backticks do not render.+7. Every node and edge comes from the spec text or from code you opened. The+ diagram adds no fact.++Self-check before you continue: count the opening and closing lines of each+`subgraph` (they must match), and confirm every edge names nodes that exist.+## Step 7: New questions discovered while writingWriting the spec sometimes surfaces questions Step 4 missed. When that happens:@@ -159,8 +201,21 @@ Writing the spec sometimes surfaces questions Step 4 missed. When that happens:## Step 8: FinalizeAfter every question is resolved: add a changelog entry, set status per-`.ai/specs/AGENTS.md`. The spec is now ready for `/plan` (or `/feature`, which-calls it).+`.ai/specs/AGENTS.md`.++Then do the STE-80 review pass (`.claude/rules/writing-ste.md` → Enforcement).+Do it again after every later edit, including edits from `/grill`, `/plan`+corrections and subagent results.++1. Follow the 8 steps of the review pass in that rule, in order.+2. Tick every box of the rule's self-check list.++If a box still fails after 3 rewrite passes, STOP and report the failing lines.++The spec is now ready for `/plan` (or `/feature`, which calls it).++Then offer the reviewer view in one line: "Want an HTML explainer of this+spec? (`/explain`)". Run `/explain` only on a yes.## Done when@@ -170,8 +225,12 @@ calls it).design reflecting the resolutions (no section contradicts an answer)- [ ] Research file exists and is linked from the spec- [ ] Every applicable heuristic (1–7) has a row in Design Decisions — no TBDs+- [ ] The Overview diagram section has one Mermaid diagram, chosen from the+ Step 6 table, that follows the syntax rules — not the template sample- [ ] Any questions surfaced during writing (Step 7) were also resolved beforethe spec was called final+- [ ] The STE-80 review pass is done after the last edit, and every+ self-check box is ticked## Anti-patternsdiff --git a/AGENTS.md b/AGENTS.mdindex 5b1c5ba757..6fde1c8971 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -146,7 +146,8 @@ IMPORTANT: Before any research or coding, match the task to this table. A single| Creating/refreshing an AGENTS.md | `.claude/skills/create-agents-md/SKILL.md` || **Design Specs** | || Check existing specs before building | `.ai/specs/` + `.ai/specs/implemented/` |-| Writing a new spec | `.claude/skills/spec-writing/SKILL.md` |+| Writing a new spec | `.claude/skills/spec-writing/SKILL.md` + `.claude/rules/writing-ste.md` |+| Explain a spec/plan as an HTML page (diagram + plain prose) | `.claude/skills/explain/SKILL.md` || **Workflows** | || Skills index — pipelines + all skills | `.claude/skills/README.md` || Competitor research for a feature | `.claude/skills/research/SKILL.md` |