@phuc1403/musketeer 0.6.0 → 0.8.0

package/template/.claude/hooks/inject-ubiquitous-language.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// SessionStart hook (dotnet company): auto-load `docs/ubiquitous-language.md` —
+// the bounded context's vocabulary, produced by the knowledge-crunching skill —
+// into every session, so the domain's language and invariants "lead the code".
+//
+// If the doc is missing, ALERT the user (systemMessage) with the command that
+// creates it. Any other error fails open (emits nothing, exit 0) so it can never
+// block a session.
+const fs = require("fs");
+const path = require("path");
+
+const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const REL = "docs/ubiquitous-language.md";
+const file = path.join(root, "docs", "ubiquitous-language.md");
+
+try {
+  let content;
+  try {
+    content = fs.readFileSync(file, "utf-8");
+  } catch {
+    // Not found — surface a visible warning to the user, inject nothing.
+    process.stdout.write(
+      JSON.stringify({
+        systemMessage:
+          `musketeer: no ${REL} — the bounded context's ubiquitous language is missing. ` +
+          "Run the knowledge-crunching skill (/knowledge-crunching) to create it.",
+      })
+    );
+    process.exit(0);
+  }
+
+  const additionalContext =
+    `Ubiquitous language (${REL}) — injected every session. It is the vocabulary and ` +
+    "model rules of this bounded context, kept vendor- and decision-neutral. Treat it as " +
+    "canonical for domain naming, concepts, and invariants: name new code after it, and when a " +
+    `concept is renamed update ${REL} and the code in the same turn. It bounds what the DOMAIN ` +
+    "model sees, not what infrastructure may do (an ACL can legitimately key on more).\n\n" +
+    `===== ${REL} =====\n` +
+    content.trimEnd();
+
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext,
+      },
+    })
+  );
+  process.exit(0);
+} catch {
+  process.exit(0); // fail open
+}

package/template/.claude/hooks/lib/adr/command-scan.cjs

@@ -22,9 +22,17 @@
 // false one blocks an unrelated command for a reason nobody can guess.
 
 // boundary/start, whitespace, any existing KEY=value prefix, then `adr <sub>`.
+//
+// The subcommand must not run straight into a word character or a hyphen. `\b`
+// alone is not enough: it sits happily between the `w` of `new` and the `-` of
+// `adr new-thing`, so that string would count as an `adr new` invocation. A hook
+// that only reads the command could shrug that off, but inject-adr-flags writes
+// the flag directly after the subcommand and would turn it into `adr new -q-thing`.
+// A trailing `;` or `|` still has to count, so this is a negated class rather
+// than a required space.
 function invocationRe(sub) {
   return new RegExp(
-    `(^|[;&|\\n(){}])([ \\t]*)((?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\\S*)[ \\t]+)*)(adr[ \\t]+${sub}\\b)`,
+    `(^|[;&|\\n(){}])([ \\t]*)((?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^']*'|"[^"]*"|\\S*)[ \\t]+)*)(adr[ \\t]+${sub})(?![\\w-])`,
     'g'
   );
 }

package/template/.claude/hooks/sync-adr-toc.cjs

@@ -6,6 +6,11 @@
 // source. That is why there is no need to be clever about which adr subcommand
 // ran, or to protect the file from being rewritten.
 //
+// Also deletes the tool's own `decisions.md`. Every `adr new` regenerates that
+// file unconditionally (not just on `adr generate toc`), which would leave two
+// competing indexes side by side in the same directory. README.md is the richer
+// one — it carries a status column — so it is the one kept.
+//
 // Also runnable directly:  node sync-adr-toc.cjs --write
 //
 // Fails open at exit 0 on any problem — a hook must never block a session.
@@ -16,7 +21,7 @@ const path = require('path');
 const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const ADR_FILE = /^\d+-.*\.md$/;
 
-// adr-tools reads its directory from a committed `.adr-dir` (default `doc/adr`).
+// The tool reads its directory from a committed `.adr-dir` (default `doc/adr`).
 function adrDir() {
   try {
     return fs.readFileSync(path.join(root, '.adr-dir'), 'utf8').trim() || 'doc/adr';
@@ -25,8 +30,8 @@ function adrDir() {
   }
 }
 
-// Was this Bash call an adr command? (`VISUAL=true EDITOR=true adr new …` counts;
-// the internal `adr-new` script name does not, hence the required whitespace.)
+// Was this Bash call an adr command? (`adr new -q …` counts; a hyphenated name
+// such as `adr-new` does not, hence the required whitespace.)
 function isAdrCommand() {
   try {
     const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
@@ -36,8 +41,9 @@ function isAdrCommand() {
   }
 }
 
-// First line, minus the leading "# " and adr-tools' own number prefix — it writes
-// "# 12: Use X over Y" for 0012-….md. Dropping the unpadded 12 keeps the padded
+// First line, minus the leading "# " and the tool's own number prefix — the
+// template renders "# 12: Use X over Y" for 0012-….md. Dropping the unpadded 12
+// keeps the padded
 // stem in the ADR column the only number in the file, so nothing here can be
 // mistaken for the stem `adr new -s` expects.
 function title(body, fallback) {
@@ -45,8 +51,8 @@ function title(body, fallback) {
   return first.replace(/^#\s*(\d+\s*[:.]\s*)?/, '').trim() || fallback;
 }
 
-// First non-empty line of the `## Status` section. adr-tools maintains this:
-// "Accepted", or "Superceded by [4: …](0004-….md)" after `adr new -s`.
+// First non-empty line of the `## Status` section. The tool maintains this:
+// "Accepted", or "Superseded by [4: …](0004-….md)" after `adr new -s`.
 function status(body) {
   const lines = body.split(/\r?\n/);
   const start = lines.findIndex((l) => /^##\s+Status\s*$/i.test(l));
@@ -78,10 +84,39 @@ function render(dir, files) {
   ].join('\n');
 }
 
+// The tool writes its own table of contents to `<adr-dir>/decisions.md` on every
+// `adr new`. README.md supersedes it, so drop it rather than commit two indexes
+// that have to agree with each other.
+//
+// Only ever deletes a file that is recognisably that generated index: the exact
+// heading it writes, followed by nothing but link lines. `decisions.md` is an
+// ordinary name for a hand-written decision log, and deleting one of those on
+// the next `adr new` would destroy work no backup covers.
+const GENERATED_TOC = /^# Table of Contents\r?\n\r?\n(?:- \[[^\]]*\]\([^)]*\)\r?\n?)*$/;
+
+function removeRedundantToc(dir) {
+  const stale = path.join(root, dir, 'decisions.md');
+  try {
+    if (!fs.existsSync(stale)) return;
+    if (!GENERATED_TOC.test(fs.readFileSync(stale, 'utf8'))) {
+      process.stdout.write(
+        `Left ${dir}/decisions.md alone — it is not the generated index. ` +
+          'README.md is the one this hook maintains.\n'
+      );
+      return;
+    }
+    fs.unlinkSync(stale);
+    process.stdout.write(`Removed ${dir}/decisions.md (README.md is the index).\n`);
+  } catch {
+    /* not worth failing the hook over */
+  }
+}
+
 function main() {
   if (!process.argv.includes('--write') && !isAdrCommand()) return;
 
   const dir = adrDir();
+  removeRedundantToc(dir);
   const files = fs
     .readdirSync(path.join(root, dir))
     .filter((f) => ADR_FILE.test(f))

package/template/.claude/skills/adr-writer/SKILL.md

@@ -1,46 +1,48 @@
----
-name: adr-writer
-description: Write and manage Architecture Decision Records (ADRs) following structured methodology with proper numbering, status tracking, governance, and conversational writing style.
----
-
-# ADR Writer
-
-Write Architecture Decision Records — the log of "architecturally significant" decisions affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
-
-**Scope:** Create, update, and supersede ADRs. Does NOT implement the decisions themselves.
-
-## Workflow
-
-1. **Read the context.** `docs/architecture-characteristics.md` — every Decision is justified against these, with trade-offs framed as which are favored vs. sacrificed. If it is missing, read `.claude/skills/architecture-characteristic-writer/SKILL.md` and use its questions to gather the driving characteristics from the user before going on. Then read `docs/adr/README.md` for the decisions already recorded — one ADR's Consequences are often the next one's Context.
-
-2. **Research before suggesting** — REQUIRED whenever a technology, vendor, product, version, or price is in play. Invoke `/research`; never propose options from memory, it goes stale. Confirm each option still exists and is supported today. Report in one pass, source and verdict per option.
-
-3. **Challenge the proposal — be harsh.** REQUIRED whenever the user proposes a specific option. Do not rubber-stamp it:
-   - **State why** — the concrete reasons, not familiarity or preference.
-   - **Score it against each driving and implicit characteristic** — does it *serve*, *ignore*, or *actively harm* it?
-   - **Give a verdict** — suitable / suitable-with-trade-offs / unsuitable. If it conflicts with a driving characteristic, say so plainly and recommend the better fit, even when that is not what was asked for.
-   - Continue only once it survives, or the user overrides knowing the trade-off — record that override as a Consequence.
-
-4. **Create the file.** From the repo root:
-   ```bash
-   adr new -- "Use X for Z"
-   ```
-   - Use the path `adr new` prints — never guess the number or slug.
-   - Superseding — always the full padded stem, never a bare number (`-s 2` matches the first path containing "2", possibly the wrong file). Writes the cross-link into both ADRs' `## Status`:
-     ```bash
-     adr new -s 0002-use-mysql-for-persistence -- "…"
-     ```
-
-5. **Write the ADR.** Replace every `{…}` placeholder — nothing else. `adr new` has already written the number, title, `Accepted` status, and any supersede/link lines; leave all of them alone. Section Guidance below covers what each section needs. An Accepted ADR is immutable — to change it, write a new ADR that supersedes it.
-
-## Writing Style
-
-- **Calibrate against `references/adr-example.md`** — re-read it before drafting; it is the target for terseness. Cut any section markedly longer than its equivalent.
-- **Match `references/adr-template.md` exactly.** Use only the sections it defines. No invented sections or fields; research citations go inline in the Decision.
-
-## Section Guidance
-
-- **Title** — reveal the *decision*, not the topic: "Use X for Z". Bad: "Gmail Polling for Ingestion". Good: "Use Cloud Scheduler Polling for Gmail Ingestion".
-- **Context** — value-neutral, tensions explicit. No alternatives here, and no notes about what is *not* being decided.
-- **Decision** — record the WHY, not the HOW — omit libraries, drivers, and wiring.
-- **Consequences** — both `### Positive` and `### Negative` required. Consider team, infrastructure, cost, and one-way doors.
+---
+name: adr-writer
+description: Write and manage Architecture Decision Records (ADRs) following structured methodology with proper numbering, status tracking, governance, and conversational writing style.
+---
+
+# ADR Writer
+
+Write Architecture Decision Records — the log of "architecturally significant" decisions affecting structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
+
+**Scope:** Create, update, and supersede ADRs. Does NOT implement the decisions themselves.
+
+## Workflow
+
+1. **Read the context.** `docs/architecture-characteristics.md` — every Decision is justified against these, with trade-offs framed as which are favored vs. sacrificed. If it is missing, read `.claude/skills/architecture-characteristic-writer/SKILL.md` and use its questions to gather the driving characteristics from the user before going on. Then read `docs/adr/README.md` for the decisions already recorded — one ADR's Consequences are often the next one's Context.
+
+2. **Research before suggesting** — REQUIRED whenever a technology, vendor, product, version, or price is in play. Invoke `/research`; never propose options from memory, it goes stale. Confirm each option still exists and is supported today. Report in one pass, source and verdict per option.
+
+3. **Challenge the proposal — be harsh.** REQUIRED whenever the user proposes a specific option. Do not rubber-stamp it:
+   - **State why** — the concrete reasons, not familiarity or preference.
+   - **Score it against each driving and implicit characteristic** — does it *serve*, *ignore*, or *actively harm* it?
+   - **Give a verdict** — suitable / suitable-with-trade-offs / unsuitable. If it conflicts with a driving characteristic, say so plainly and recommend the better fit, even when that is not what was asked for.
+   - Continue only once it survives, or the user overrides knowing the trade-off — record that override as a Consequence.
+
+4. **Create the file.** From the repo root:
+   ```bash
+   adr new -q -- "Use X for Z"
+   ```
+   - `-q` is required on every call. Without it an ambiguous `-s` prompts on stdin and hangs the session; with it, that case errors instead.
+   - `adr new` prints nothing. Run `adr list` (last line is the new file) or read `docs/adr/README.md` — never guess the number or slug.
+   - Never use uppercase `STATUS` in a title. It is substituted after the title is inserted, so "Use STATUS codes" silently becomes "Use Accepted codes" and leaves the real Status unset. Lowercase is fine.
+   - Superseding — always the full padded stem, never a bare number. `-s` matches by substring: with `-q` an *ambiguous* match errors, but a single *wrong* match still succeeds silently. Writes the cross-link into both ADRs' `## Status`:
+     ```bash
+     adr new -q -s 0002-use-mysql-for-persistence -- "…"
+     ```
+
+5. **Write the ADR.** Replace every `{…}` placeholder — nothing else. `adr new` has already written the number, title, `Accepted` status, and any supersede/link lines; leave all of them alone. Section Guidance below covers what each section needs. An Accepted ADR is immutable — to change it, write a new ADR that supersedes it.
+
+## Writing Style
+
+- **Calibrate against `references/adr-example.md`** — re-read it before drafting; it is the target for terseness. Cut any section markedly longer than its equivalent.
+- **Match `references/adr-template.md` exactly.** Use only the sections it defines. No invented sections or fields; research citations go inline in the Decision.
+
+## Section Guidance
+
+- **Title** — reveal the *decision*, not the topic: "Use X for Z". Bad: "Gmail Polling for Ingestion". Good: "Use Cloud Scheduler Polling for Gmail Ingestion".
+- **Context** — value-neutral, tensions explicit. No alternatives here, and no notes about what is *not* being decided.
+- **Decision** — record the WHY, not the HOW — omit libraries, drivers, and wiring.
+- **Consequences** — both `### Positive` and `### Negative` required. Consider team, infrastructure, cost, and one-way doors.

package/template/.claude/skills/context-map/SKILL.md

@@ -75,6 +75,6 @@ For deeper validation, open the file in VSCode with the Context Mapper extension
 
 ## Glossary
 
-Same `CONTEXT.md` convention as the EventStorming skills. Challenge BC names against the glossary before writing. If a relationship introduces a novel domain term, add a one-sentence definition in `CONTEXT.md` the same turn.
+Same `ubiquitous-language.md` convention as the EventStorming skills. Challenge BC names against the language doc before writing. If a relationship introduces a novel domain term, add a one-sentence definition in `docs/ubiquitous-language.md` the same turn.
 
 </supporting-info>

package/template/.claude/skills/knowledge-crunching/SKILL.md

@@ -1,130 +1,94 @@
 ---
 name: knowledge-crunching
 description: >-
-  Crunch domain knowledge with the user as domain expert, Eric Evans style: instead of drawing
-  diagrams, express the emerging model as test-driven domain-layer code in the project's own
-  language, verify understanding in a tight per-concept loop before writing anything, and record the
-  shared vocabulary in the bounded context's CONTEXT.md (its ## Language section). Use when the user invokes
-  /knowledge-crunching, describes a domain flow/feature to model, wants to collaboratively discover a
-  domain model, distill a ubiquitous language, reconcile experts' terminology, or build a DDD domain
-  prototype test-first while confirming each concept before coding.
+  Crunch domain knowledge with the user as domain expert into test-driven domain-layer code and a ubiquitous language (DDD). Use when the user invokes /knowledge-crunching, describes a domain flow or feature to model, wants to discover a domain model, distill a ubiquitous language, or reconcile experts' terminology.
 ---
 
 # Knowledge Crunching
 
-You are the developer/architect on a DDD team; the user is the **domain expert** (the client). You
-crunch their knowledge into a model the way Eric Evans did on the PCB project, with one change: **the
-emerging model is test-driven domain-layer code, not diagrams.**
+You are the developer/architect on a DDD team; the user is the **domain expert** (the client). You crunch their knowledge into a model through a tight modeling dialogue, with one commitment: **the emerging model is test-driven domain-layer code, not diagrams.**
 
-**This skill handles:** the collaborative modeling *dialogue* and the domain-layer model it produces
-— types, behavior, unit tests, and the language in `CONTEXT.md` — for a module that already exists,
-whether its domain layer is a bare scaffold or a live model. **Does NOT handle:** persistence,
-repositories, UI, API/transport, deployment, strategic context-mapping, or standing up a new module
-scaffold (a prerequisite, done first). Stay in the domain layer; if the user asks for the rest, note
-it's out of scope and offer to hand off afterward.
+**This skill handles:** the collaborative modeling *dialogue* and the domain-layer model it produces — types, behavior, unit tests, and the language in `docs/ubiquitous-language.md` — for a module that already exists, whether its domain layer is a bare scaffold or a live model. **Does NOT handle:** persistence, repositories, UI, API/transport, deployment, strategic context-mapping, or standing up a new module scaffold (a prerequisite, done first). Stay in the domain layer; if the user asks for the rest, note it's out of scope and offer to hand off afterward.
 
 ## The five stances (hold these the whole session)
 
-1. **Model in code, not diagrams.** Every model fragment is a small type or method — in the bounded
-   context's own language — you can show on screen. The running test, not a picture, is what makes the
-   model concrete to the expert. (Examples in this skill are language-neutral pseudocode; write yours
-   as real, runnable code and tests in the project's language and test framework.)
-2. **Verify before you build.** Never write code for an unconfirmed concept — propose, ask, and
-   **WAIT** for the answer (mechanics in Step 4). Their corrections *are* the model.
-3. **Speak the expert's words.** Use their nouns and verbs verbatim. Reconcile synonyms and
-   contradictions out loud ("ref-des and component instance — same thing?"). Code names == language names.
-4. **Distill, don't transcribe.** Exclude every fact the current problem doesn't need (Evans dropped
-   `Topology` for the probe simulation). Bring a concept back only when a feature actually pulls it in.
-5. **Don't accept the solution as stated.** Experts often describe a mechanical solution ("read a file,
-   sort it, write a report"). Dig past it for the domain concepts that yield the real leap.
+1. **Model in code, not diagrams.** Every model fragment is a small type or method — in the bounded context's own language — you can show on screen. The running test, not a picture, is what makes the model concrete to the expert.
+2. **Verify before you build.** Never write code for an unconfirmed concept — propose, ask, and **WAIT** for the answer.
+3. **Speak the expert's words.** Use their nouns and verbs verbatim. Reconcile synonyms and contradictions out loud ("customer and account holder — same thing?"). Code names == language names.
+4. **Distill, don't transcribe.** Exclude every fact the current problem doesn't need — the model is a distillation, not a transcription. Bring a concept back only when a feature actually pulls it in.
+5. **Don't accept the solution as stated.** A request usually arrives already framed as a mechanism ("export the table, sort it, email a summary"). That framing is not the domain. Dig past it for the concepts underneath — that is where the model is.
 
 ## Workflow
 
-### Step 1 — Open the session and name the flow
+### Step 1 — Read what already exists
+**First read any prior crunching output for that context** — `docs/ubiquitous-language.md` and the domain's code; in DDD, document = code. If the module is a bare scaffold with no language chosen yet, ask the user which language and test framework the context should be modeled in before proposing any code.
 
-**First read any prior crunching output for that context** — the root-level `CONTEXT.md` and read the domain's code; in DDD, document = code. While reading the code, **note the language, idioms, and test framework already in use** — you'll model in those. If the module is a bare scaffold with no language chosen yet, ask the user which language and test framework the context should be modeled in before proposing any code.
+If a model is already there, read it against the language and let each mismatch become a Step 4 loop turn — surface it, verify with the user, then change code and `docs/ubiquitous-language.md` together:
 
-### Step 2 — Find the first model elements (the "glimmer")
-Listen past the user's solution framing for the **domain nouns and verbs that keep recurring** — Name 2–4 candidate
-concepts back to the user and ask which ones are real. Do not scaffold types yet.
+- **Synonym drift** — code says `Learner`, experts now say `Student`. Reconcile and pick one, in both.
+- **Conflated concept** — one type doing two jobs the experts name separately → candidate split.
+- **Leaked invariant** — a rule enforced in a service/controller that an aggregate should own.
+- **Dead concept** — a type no scenario exercises anymore → remove it from the code and drop its entry.
+
+### Step 2 — Find the first model elements
+The opening description is usually a mechanism, not a model (stance 5). Listen past it for the **domain nouns and verbs that keep recurring**, and name 2–4 of them back as candidate concepts.
+
+For each, ask whether it is something the business actually names and treats as a distinct thing — as opposed to a word used in passing, or one you invented. You are testing your own guesses, so expect to be corrected. This is *not* "which word do you prefer?" — choosing between two words for one thing is stance 3, and it only arises once you have two.
+
+> **You:** I'm hearing `Car`, `Inspection`, and something like `Listing` for a car on the lot for sale. Is `Listing` a real thing you'd name, or just "the car is on the lot"?
+>
+> **Expert:** It's real, but we call it a `Unit`, and only once it's passed inspection. A car we haven't inspected isn't a unit.
+
+One answer, and you have a concept, its actual name, and the rule that brings it into existence. Do not scaffold types yet.
 
 ### Step 3 — Focus on ONE scenario
-Narrow to a single concrete scenario to make progress.
-Ask the user to pick or confirm the one scenario you'll model first. Everything else waits.
+Narrow to a single concrete scenario to make progress. Ask the user to pick or confirm the one you'll model first; everything else waits. If their explanation runs ahead of you, say so and pull back here.
 
 ### Step 4 — The per-concept tight loop (the heart of the skill)
 For each concept the chosen scenario pulls in, run this loop — **one concept at a time**:
 
-1. **Propose** one model fragment as minimal code in the project's language (a type, a method, a
-   relationship) + a one-line plain gloss of what it means.
-2. **Ask one sharp verifying question** that would expose a misunderstanding if your guess is wrong —
-   about cardinality, a synonym, behavior ownership, an exclusion, a simplification, or the goal of the
-   computation. (Catalog of question types + the PCB dialogue worked end-to-end:
-   `references/crunching-dialogue.md`.)
+1. **Propose** one model fragment as minimal code in the project's language (a type, a method, a relationship) + a one-line plain gloss of what it means.
+2. **Ask one sharp verifying question** that would expose a misunderstanding if your guess is wrong. Pick the type that fits the fragment you just proposed — a good question is falsifiable, concrete, and answerable in a sentence, never "does this look right?":
+
+   | Type | What it pins down | Template |
+   |---|---|---|
+   | **Cardinality** | how many relate to how many | "Does one X belong to exactly one Y, or many?" |
+   | **Synonym** | two words, one concept | "Are X and Y the same thing?" |
+   | **Ownership of behavior** | which object does the work | "What pushes the signal — X or Y?" |
+   | **Exclusion / relevance** | is this concept needed *now* | "Does X matter for this scenario?" |
+   | **Simplification** | how little can we model | "Is a simplified Z enough instead of full X?" |
+   | **Computation goal** | what the output must be | "What exactly do you need from this?" |
+   | **Definition of a unit** | what one increment is | "What counts as one X?" |
+   | **Lifetime / sameness** | shared vs per-instance data | "Is this the same for every instance, or per instance?" |
+
+   If you can't think of a question, you don't understand the fragment well enough to code it — go smaller. Prefer a question that could get a "no"; one that can only be answered "yes" teaches nothing. After a "no," restate the corrected understanding before moving on.
 3. **WAIT** for the answer. Do not write code, tests, or the next fragment until the user responds.
 4. **Fold in** the correction (rename, re-shape, drop, or add), then record the term (Step 6).
 
 Example of the loop's rhythm (compressed):
 
-> **You:** Here's my first guess — a `Net` carries a signal to every `Pin` attached to it.
-> ```
-> Net — connects many Pins
-> ```
-> Are you saying a `Pin` belongs to exactly one `ComponentInstance` and connects to exactly one `Net`?
+> **You:** Here's my first guess — an `Order` groups the `LineItem`s a customer buys in one go, so `Order` holds many `LineItem`s. Does a `LineItem` belong to exactly one `Order`, or can the same one sit on several?
 >
-> **Expert:** Yes — one pin, one component instance, one net.
+> **Expert:** One line item, one order. Always.
 >
 > **You:** Good — I'll make that a hard invariant. *(folds in, records the term, then moves to the next concept)*
 
-### Step 5 — TDD the confirmed behavior (one test at a time)
-Now make the confirmed fragment real — **domain only, no persistence, no UI**. The cardinal rule is
-**a genuine RED before any production code**:
-
-1. The fragment you sketched in Step 4 is a *drawing in the chat, not a file*. **Do not create the
-   production type yet.**
-2. **RED** — write ONE test for ONE behavior the fragment must exhibit, run the project's test command,
-   and show it **fail**. A compile error because the type/method doesn't exist yet counts as red — that
-   failing run is the point; never skip it by writing the type and its test together.
-3. **GREEN** — write the *minimal* code to pass that one test; run it; show green.
-4. **Repeat one behavior at a time** — test → code, test → code. Never write several tests at once or
-   write the whole type ahead of its tests. Batching tests ("horizontal slicing") yields tests of
-   *imagined*, not actual, behavior.
-5. Test **observable behavior through the public surface**, not getters or data shape. The test should
-   read like the scenario's rule (Evans: "a path of more than 2–3 hops is a long delay; each Net
-   crossing is one hop") and survive an internal refactor.
-6. **Never refactor while red.** Get to green first; tidy only with the bar green.
-
-Let the failing-then-passing test — not a written-out class — be the turning point that makes the model
-concrete to the expert.
+A loop turn is complete only when **all three** agree: the **expert** has answered the verifying question, the **code** reflects that answer, and **`docs/ubiquitous-language.md`** records the term. If any of the three lags, close the gap before proposing the next concept.
 
-### Step 6 — Record the language immediately
-The ubiquitous language lives in **one** place: the bounded context's `CONTEXT.md`, under
-`## Language`. There is no separate glossary file. The moment a term is confirmed, add an entry in the
-repo's format — `**Term**:` then a one-line definition in the expert's words (mention the `TypeName`
-that embodies it), then `_Avoid_:` rejected synonyms — grouped under a `###` subsection. Keep code and
-`CONTEXT.md` identical: rename in code, rename here in the same turn. Distilled-out concepts go under
-`## Deferred`, unresolved ones under `## Flagged ambiguities`.
+### Step 5 — TDD the confirmed behavior (one test at a time)
+Make the confirmed fragment real with the red-green loop in the `tdd` skill (`.claude/skills/tdd/SKILL.md`) — its rules on one-test-at-a-time, minimal green, testing observable behavior through the public surface, and never refactoring while red all apply here unchanged.
 
-Edit the context's existing root-level `CONTEXT.md` directly — it is canonical, and is
-also your seed (Step 1). If the module is new and has no `CONTEXT.md` yet, create one from
-`assets/context.template.md`.
+Two amendments for a crunching session:
 
-### Step 7 — Distill, then loop
-Drop concepts the current scenario doesn't need and say so ("I'll leave `Topology` out for now; we'll
-bring it back when we model routing"). When a new scenario arrives and the model can't express it,
-brainstorm a new concept or refactor an existing one toward deeper insight — that is crunching the
-knowledge further. Return to Step 3 for the next scenario.
+- **Domain layer only.** No persistence, no application handlers, no UI. Ignore that skill's full-vertical-slice default — here the slice stops at the domain, and what comes next is the expert's next concept, not the next layer.
+- **The Step 4 sketch is a drawing in the chat, not a file.** Do not create the production type ahead of its first failing test. A compile error because the type does not exist yet is a legitimate red, and that failing run is the point.
 
-## Pace and etiquette
+### Step 6 — Record the language immediately
+The ubiquitous language lives in **one** place: `docs/ubiquitous-language.md`. There is no separate glossary file. The moment a term is confirmed, add one line — `Term: ` then what it means in the expert's words. Nothing else: no rejected-synonym list, no deferred section, no grouping. The term is already the type's name (stance 3), so don't restate it. Rename in code, rename here in the same turn.
 
-- Move **one concept per turn**. A wall of ten types with no questions is the failure mode — it skips
-  the verification that makes this skill worth running.
-- When the user's explanation makes your "head spin," say so and pull back to one concrete scenario.
-- Keep the prototype runnable at every step; a red build is fine *during* a cycle, never at a pause.
+Write a dictionary entry, not prose. One line. No lead-in, no narrative, no "this is the concept that…". Keep implementation and vendor words out — they name the mechanism, not the concept (stance 5). Keep invariants out — rules live in the code and its tests (Step 5).
 
-## Resources
+If the doc does not exist yet, copy `assets/ubiquitous-language.template.md` from this skill to `docs/ubiquitous-language.md`. If it already exists, edit it — never overwrite it, and never start a second one. It is canonical, and is also your seed (Step 1).
 
-- `references/crunching-dialogue.md` — the verifying-question catalog, the PCB session worked
-  end-to-end (dialogue → code → `CONTEXT.md`), and drift triggers in existing code. Read at Step 4.
-- `assets/context.template.md` — starter `CONTEXT.md` (repo's `## Language` format) for a **new**
-  module that has none yet; if the context already has a `CONTEXT.md`, edit that one instead.
+### Step 7 — Distill, then loop
+Drop concepts the current scenario doesn't need and say so ("I'll leave scheduling out for now; we'll bring it back when a feature needs it"). When a new scenario arrives and the model can't express it, brainstorm a new concept or refactor an existing one toward deeper insight — that is crunching the knowledge further. Return to Step 3 for the next scenario.

package/template/.claude/skills/knowledge-crunching/assets/ubiquitous-language.template.md

@@ -0,0 +1,3 @@
+# Ubiquitous Language
+
+<Term>: <what it means, in the expert's own words>

package/template/.claude/hooks/inject-adr-env.cjs

@@ -1,83 +0,0 @@
-#!/usr/bin/env node
-// PreToolUse guard: inject the env vars every `adr new` call needs, so the
-// agent can write a bare `adr new -- "Title"` and get a correct command.
-//
-//   VISUAL=true EDITOR=true  — without them an ambient EDITOR opens an
-//     interactive editor and hangs the session (adr-new always shells out to
-//     $VISUAL/$EDITOR to "edit" the new file).
-//   ADR_TEMPLATE=...adr-template.md — points adr-new at this skill's template
-//     instead of adr-tools' own bundled default.
-//
-// Uses PreToolUse's `updatedInput` (not just allow/deny) to rewrite the
-// command before it runs. Only fills in vars that are missing — an assignment
-// the agent already wrote (any value, even a deliberately different template)
-// is left alone. Silent no-op if all three are already present.
-//
-// Safety: a title that happens to contain the literal text "adr new" could
-// make the matching regex fire inside a quoted string. Guarded by counting
-// quote characters before each match — an odd count means "inside an open
-// string", and that occurrence is left untouched rather than risk corrupting
-// the title.
-
-const fs = require('fs');
-const {
-  invocationRe,
-  isInsideQuotes,
-  isInsideHeredoc,
-  invokesAdr,
-} = require('./lib/adr/command-scan.cjs');
-
-const DEFAULTS = [
-  ['ADR_TEMPLATE', '.claude/skills/adr-writer/references/adr-template.md'],
-  ['VISUAL', 'true'],
-  ['EDITOR', 'true'],
-];
-
-function existingVars(prefix) {
-  const names = new Set();
-  const re = /([A-Za-z_][A-Za-z0-9_]*)=/g;
-  let m;
-  while ((m = re.exec(prefix))) names.add(m[1]);
-  return names;
-}
-
-function main() {
-  const payload = JSON.parse(fs.readFileSync(0, 'utf8'));
-  const command = payload?.tool_input?.command || '';
-  if (!invokesAdr(command, 'new')) return;
-
-  let changed = false;
-  const updated = command.replace(invocationRe('new'), (whole, boundary, ws, existingPrefix, adrNew, offset) => {
-    // Both guards, for the same reason the deny hooks use them: a heredoc body
-    // is documentation being written, and injecting env vars into it would
-    // rewrite the file's contents rather than the command.
-    // `offset` is the boundary character; step past it to the word `adr`.
-    const at = offset + boundary.length + ws.length + existingPrefix.length;
-    if (isInsideQuotes(command, at) || isInsideHeredoc(command, at)) return whole;
-    const present = existingVars(existingPrefix);
-    const missing = DEFAULTS.filter(([name]) => !present.has(name));
-    if (missing.length === 0) return whole;
-    changed = true;
-    const injected = missing.map(([name, value]) => `${name}=${value}`).join(' ');
-    return `${boundary}${ws}${injected} ${existingPrefix}${adrNew}`;
-  });
-  if (!changed) return;
-
-  process.stdout.write(
-    JSON.stringify({
-      systemMessage: 'Added missing VISUAL/EDITOR/ADR_TEMPLATE env vars before `adr new`.',
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'allow',
-        updatedInput: { command: updated },
-      },
-    })
-  );
-}
-
-try {
-  main();
-} catch {
-  /* fail open: leave the command untouched */
-}
-process.exit(0);

package/template/.claude/hooks/inject-context.cjs

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-// SessionStart hook (dotnet company): auto-load the repo-root `CONTEXT.md` — the
-// bounded-context model produced by the knowledge-crunching skill — into every
-// session, so the domain's ubiquitous language and invariants "lead the code".
-//
-// If the root CONTEXT.md is missing, ALERT the user (systemMessage) so they
-// create one. Any other error fails open (emits nothing, exit 0) so it can never
-// block a session.
-const fs = require("fs");
-const path = require("path");
-
-const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const file = path.join(root, "CONTEXT.md");
-
-try {
-  let content;
-  try {
-    content = fs.readFileSync(file, "utf-8");
-  } catch {
-    // Not found — surface a visible warning to the user, inject nothing.
-    process.stdout.write(
-      JSON.stringify({
-        systemMessage:
-          "musketeer: no CONTEXT.md at the repo root — the bounded-context model is missing. " +
-          "Run the knowledge-crunching skill (/knowledge-crunching) to create one.",
-      })
-    );
-    process.exit(0);
-  }
-
-  const additionalContext =
-    "Bounded-context model (root CONTEXT.md) — injected every session. It is the " +
-    "ubiquitous language and model rules of this bounded context, kept vendor- and " +
-    "decision-neutral. Treat it as canonical for domain naming, concepts, and invariants: " +
-    "name new code after it, and when a concept is renamed update CONTEXT.md and the code in " +
-    "the same turn. It bounds what the DOMAIN model sees, not what infrastructure may do " +
-    "(an ACL can legitimately key on more).\n\n" +
-    "===== CONTEXT.md =====\n" +
-    content.trimEnd();
-
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "SessionStart",
-        additionalContext,
-      },
-    })
-  );
-  process.exit(0);
-} catch {
-  process.exit(0); // fail open
-}