@nurix/etna 0.18.12 → 0.18.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  {
2
- "fingerprint": "acbb6d687e95",
2
+ "fingerprint": "8475e43caf9f",
3
3
  "harnesses": {
4
4
  "code": {
5
5
  "plugin": "code",
@@ -101,7 +101,16 @@ A boundary is a horizontal cross-cutting contract — entity model, db schema, w
101
101
 
102
102
  Unless explicitly requested:
103
103
 
104
- ❌ **Tests** – Never generate, update, or modify test files. ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies. ❌ **Compatibility** – Never maintain backward compatibility unless specified. ❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks. ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself. ✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools whenever they help (verifying UI, reproducing a flow, seeding or inspecting local data) — no need to ask first. **Main session only:** never drive the browser from a sub-agent or workflow executor — the session-bound Chrome connection destabilizes the sub-agent. A sub-agent that needs browser verification instead returns an explicit CDP checklist (exact URLs, actions, expected outcomes) for the orchestrator to execute in the main session. ✅ **Orchestrate via Sub-agents** – Run the main session as an orchestrator: delegate substantive work (research, implementation, audits) to sub-agents spawned via the Agent/Task tool with `model: opus` (Claude Opus), keeping the main context for dispatch, coordination, and synthesis. Give each sub-agent a self-contained prompt; parallelize independent dispatches. ✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior. ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one. ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
104
+ - ❌ **Tests** – Never generate, update, or modify test files.
105
+ - ❌ **Dependencies** – Never upgrade frameworks, libraries, or dependencies.
106
+ - ❌ **Compatibility** – Never maintain backward compatibility unless specified.
107
+ - ❌ **Branches & Worktrees** – Never self-create git branches or worktrees. Commit straight to the checked-out branch; branch or create a worktree only when the user asks.
108
+ - ❌ **Protected Files** – Before editing, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; also never modify `AGENTS.md` or the `protected-files.md` file itself.
109
+ - ✅ **Browser Automation** – Use Chrome CDP / "Claude in Chrome" tools freely, no need to ask first. **Main session only** – sub-agents destabilize the connection; a sub-agent needing browser verification returns a CDP checklist (URLs, actions, expected outcomes) for the orchestrator to run instead.
110
+ - ✅ **Orchestrate via Sub-agents** – The main session is an orchestrator, not an implementer: always offload substantive work (research, implementation, audits) to sub-agents via the Agent/Task tool, never run it directly. Every dispatch sets `model: opus` (complex/judgment-heavy) or `model: sonnet` (well-scoped/mechanical) — never leave `model` unset. Self-contained prompts; parallelize independent dispatches.
111
+ - ✅ **Documentation** – Keep `docs/` updated when code changes affect documented behavior.
112
+ - ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflow → Plan Mode). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. If scope changes after completion, write a new dated plan that links back to the old one.
113
+ - ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
105
114
 
106
115
  ---
107
116
 
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "harness": "code",
3
3
  "name": "code",
4
- "version": "3.0.1",
4
+ "version": "3.0.2",
5
5
  "files": [
6
6
  ".prettierrc.json",
7
7
  ".prettierignore",
8
8
  ".vscode/settings.json"
9
9
  ],
10
- "digest": "f301f7867e2e"
10
+ "digest": "07791ff5dfef"
11
11
  }
@@ -108,9 +108,15 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
108
108
 
109
109
  ---
110
110
 
111
- ## Harvest
111
+ ## Exit artifacts
112
112
 
113
- The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop` the skill _offers_ the harvest adapter, which distils the pillars' conclusions into the doc tree (ADRs, module pillars, plans, the `boundary` skill reads contracts from source). The `docs/brainstorm/{topic}/` record is **kept** as the provenance — never deleted. See `harvest.md`.
113
+ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final sync, the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
114
+
115
+ - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
116
+ - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
117
+ - **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
118
+
119
+ The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
114
120
 
115
121
  ---
116
122
 
@@ -118,7 +124,7 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
118
124
 
119
125
  1. **No production code outside the session folder.** Illustrative snippets are fine inside it.
120
126
  2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
121
- 3. **`AskUserQuestion` appears in exactly three places:** the intake frame, interview mode, converge picks.
127
+ 3. **`AskUserQuestion` appears in exactly four places:** the intake frame, interview mode, converge picks, the `stop` exit-artifact pick.
122
128
  4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
123
129
  5. **Questions are the only convergence currency** — nothing pending may live only in the transcript.
124
130
  6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
@@ -129,10 +135,10 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
129
135
 
130
136
  ```
131
137
  brainstorm/ # the skill (in .claude/skills/)
132
- ├── SKILL.md # the skill definition Claude Code loads (~1.8k words)
133
- ├── README.md # this file
134
- ├── harvest.md # doc-tree harvest adapter (record kept at docs/brainstorm/{topic}/)
135
- └── templates/ # pillar templates copied into the session record on first use
138
+ ├── SKILL.md # the skill definition Claude Code loads (~1.8k words)
139
+ ├── README.md # this file
140
+ ├── exit-artifacts.md # what /brainstorm stop publishes: source-of-truth / plans / harvest
141
+ └── templates/ # pillar templates + source-of-truth.md, used in the record and at stop
136
142
  ```
137
143
 
138
144
  The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.
@@ -6,7 +6,7 @@ argument-hint: "start | stop"
6
6
 
7
7
  # Brainstorm
8
8
 
9
- Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, harvest — scales with complexity.
9
+ Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, exit artifacts — scales with complexity.
10
10
 
11
11
  ## The loop — every turn, every mode
12
12
 
@@ -50,7 +50,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
50
50
 
51
51
  ### 3. Bootstrap
52
52
 
53
- Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after harvest (it is the provenance the steering pillars distil from — see `harvest.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
53
+ Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
54
54
 
55
55
  ```
56
56
  STATE: open
@@ -121,7 +121,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
121
121
 
122
122
  1. Run a final sync (wait for any in-flight sync first).
123
123
  2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off.
124
- 3. **Harvest** — see `harvest.md`. The harvest distils the pillars' conclusions into the live steering docs by scope (`docs/architecture/`, `docs/architecture/adr/`, `docs/history/backlog.md`); the `docs/brainstorm/{topic}/` record itself is **kept** (committed), never deleted — it is the provenance the harvested headlines trace back to and the seed the next session resumes from.
124
+ 3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
125
125
  4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
126
126
 
127
127
  ## Conduct — holds for the whole session
@@ -129,7 +129,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
129
129
  1. **Speak English; codes live in files.** In conversation, name every pillar item by what it _is_ in plain words. Append the code in parentheses only when traceability needs it (_"…can a user change answer depth? (tracked as Q6)"_). Never lead with a bare `Q3`/`D7`. The user is not looking at the files.
130
130
  2. **No production code outside the session folder.** Illustrative load-bearing snippets are fine inside it (`samples/` or fenced in pillars). If asked for production code: offer a sketch inside the folder, or `/brainstorm stop` first.
131
131
  3. **The writing posture comes from `build.md`'s mode.** Greenfield: every pillar describes the system as it _will be_, present tense, as though the chosen design was always the plan — no migration vocabulary, no phantom history (banned list in `templates/build.md`). Brownfield/hybrid: migration vocabulary is legitimate, and `build.md` is its home; other pillars still describe the _target_ state.
132
- 4. **`AskUserQuestion` appears in exactly three places:** the intake frame batch, interview mode, and converge picks. Everywhere else: prose.
132
+ 4. **`AskUserQuestion` appears in exactly four places:** the intake frame batch, interview mode, converge picks, and the `stop` exit-artifact pick. Everywhere else: prose.
133
133
  5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
134
134
  6. **Questions are the only convergence currency.** Flaws, gaps, contradictions, uncovered aspects — everything unresolved funnels into `questions.md` or it doesn't exist. Nothing pending may live only in the conversation transcript.
135
135
  7. **No auto-invocation.** Only `/brainstorm start` and `/brainstorm stop` enter or leave a session. Read `state.md` at the start of every turn while a session folder exists.
@@ -0,0 +1,62 @@
1
+ # Exit artifacts
2
+
3
+ What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
4
+ either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
5
+ outward into the form the work needs; the record stays as the source they trace back to.
6
+
7
+ At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
8
+ can publish more than one):
9
+
10
+ | Artifact | Use when the outcome is… | Lands in | Voice |
11
+ | --- | --- | --- | --- |
12
+ | **Source of truth** | a standing reference — "what this thing **is**" | the repo's feature/architecture doc home, else a topic `Readme.md` | README — present tense, reader-first (`templates/source-of-truth.md`) |
13
+ | **Plans** | work to execute — "what to **build**, in what order" | one or more `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft) | plan — steps, sequencing, status |
14
+ | **Harvest into living docs** | findings that belong inside an existing doc system | dispersed by scope (table below) | matches each destination |
15
+
16
+ A session commonly emits a **source of truth** for the thing designed _and_ **plans** for building it.
17
+ Picking "source of truth" does **not** also disperse headlines across the doc tree — that is what "harvest"
18
+ does; pick it too if you want both the one-doc reference and the integrated headlines.
19
+
20
+ ## Source of truth
21
+
22
+ One consolidated, README-style document — the canonical reference for the thing designed. Distil every
23
+ pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
24
+ present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
25
+ `non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
26
+ record. Template: `templates/source-of-truth.md`.
27
+
28
+ Place it at the repo's canonical home for that kind of knowledge: a feature/system → `docs/features/{slug}.md`
29
+ (carry the doc system's `owns:` / `module:` / `keywords:` / `status:` frontmatter); cross-cutting →
30
+ `docs/architecture/{slug}.md`; no doc taxonomy → a `Readme.md` at the topic's folder. One document — if a
31
+ section outgrows it, link out rather than sprawl.
32
+
33
+ ## Plans
34
+
35
+ One or more executable plan docs in `docs/history/plans/` (Status: Draft), authored to the `documentation`
36
+ skill's §8 Plan template. Source: the `thesis.md` narrative for scope, `build.md` for migration strategy /
37
+ gotchas / rollout (execution content is plan content, not architecture). Split by deliverable, not by pillar
38
+ — one plan per cohesive unit of work.
39
+
40
+ ## Harvest into living docs
41
+
42
+ A structured diff between the session pillars and the live docs, dispersed by scope. Modules are labels,
43
+ not folders — a finding scoped to one module still lands in `docs/architecture/` and names the module in prose.
44
+
45
+ | Session source | Destination |
46
+ | --- | --- |
47
+ | Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
48
+ | `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
49
+ | Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant ADR |
50
+ | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
51
+ | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
52
+ | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
53
+ | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
54
+
55
+ Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
56
+
57
+ ## After publishing — keep the record
58
+
59
+ **Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
60
+ conclusions, but the record stays committed as their provenance: a traceable source for every published
61
+ headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the
62
+ `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.
@@ -0,0 +1,49 @@
1
+ # [Thing] — source of truth
2
+
3
+ > This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
4
+ > README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
5
+ > status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
6
+ > `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
7
+ > `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
8
+ >
9
+ > **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
10
+ > that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
11
+ > No doc taxonomy → a `Readme.md` at the topic's home.
12
+
13
+ ## What it is
14
+
15
+ [One paragraph, present tense: what the thing is, what it does, who uses it. Distilled from `thesis.md`.]
16
+
17
+ ## How it works
18
+
19
+ [The model — entities, relationships, the main flow — lifted from `domain-model.md` into plain,
20
+ reader-first description. Prose and tables; a diagram only if it earns its tokens.]
21
+
22
+ ## Parts
23
+
24
+ [One row per component / module / piece: name · role · what it owns · what it depends on.]
25
+
26
+ | Part | Role | Owns | Depends on |
27
+ | --- | --- | --- | --- |
28
+ | | | | |
29
+
30
+ ## Why it's shaped this way
31
+
32
+ [The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
33
+ concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
34
+ table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
35
+ don't reproduce them.]
36
+
37
+ ## Constraints & non-goals
38
+
39
+ [Accepted tradeoffs phrased as current fact ("a 5-second lag is accepted for predictable throughput")
40
+ and what is explicitly out of scope.]
41
+
42
+ ## Open questions
43
+
44
+ [One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
45
+
46
+ ---
47
+
48
+ _Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
49
+ and the provenance for everything above._
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "harness": "etna",
3
3
  "name": "etna",
4
- "version": "1.0.1",
4
+ "version": "1.0.2",
5
5
  "files": [
6
6
  ".prettierrc.json",
7
7
  ".prettierignore",
8
8
  ".vscode/settings.json"
9
9
  ],
10
- "digest": "5699e31e9981"
10
+ "digest": "9447b8703853"
11
11
  }
@@ -108,9 +108,15 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
108
108
 
109
109
  ---
110
110
 
111
- ## Harvest
111
+ ## Exit artifacts
112
112
 
113
- The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop` the skill _offers_ the harvest adapter, which distils the pillars' conclusions into the doc tree (ADRs, module pillars, plans, the `boundary` skill reads contracts from source). The `docs/brainstorm/{topic}/` record is **kept** as the provenance — never deleted. See `harvest.md`.
113
+ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final sync, the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
114
+
115
+ - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
116
+ - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
117
+ - **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
118
+
119
+ The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
114
120
 
115
121
  ---
116
122
 
@@ -118,7 +124,7 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
118
124
 
119
125
  1. **No production code outside the session folder.** Illustrative snippets are fine inside it.
120
126
  2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
121
- 3. **`AskUserQuestion` appears in exactly three places:** the intake frame, interview mode, converge picks.
127
+ 3. **`AskUserQuestion` appears in exactly four places:** the intake frame, interview mode, converge picks, the `stop` exit-artifact pick.
122
128
  4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
123
129
  5. **Questions are the only convergence currency** — nothing pending may live only in the transcript.
124
130
  6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
@@ -129,10 +135,10 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
129
135
 
130
136
  ```
131
137
  brainstorm/ # the skill (in .claude/skills/)
132
- ├── SKILL.md # the skill definition Claude Code loads (~1.8k words)
133
- ├── README.md # this file
134
- ├── harvest.md # doc-tree harvest adapter (record kept at docs/brainstorm/{topic}/)
135
- └── templates/ # pillar templates copied into the session record on first use
138
+ ├── SKILL.md # the skill definition Claude Code loads (~1.8k words)
139
+ ├── README.md # this file
140
+ ├── exit-artifacts.md # what /brainstorm stop publishes: source-of-truth / plans / harvest
141
+ └── templates/ # pillar templates + source-of-truth.md, used in the record and at stop
136
142
  ```
137
143
 
138
144
  The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.
@@ -6,7 +6,7 @@ argument-hint: "start | stop"
6
6
 
7
7
  # Brainstorm
8
8
 
9
- Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, harvest — scales with complexity.
9
+ Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, exit artifacts — scales with complexity.
10
10
 
11
11
  ## The loop — every turn, every mode
12
12
 
@@ -50,7 +50,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
50
50
 
51
51
  ### 3. Bootstrap
52
52
 
53
- Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after harvest (it is the provenance the steering pillars distil from — see `harvest.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
53
+ Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
54
54
 
55
55
  ```
56
56
  STATE: open
@@ -121,7 +121,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
121
121
 
122
122
  1. Run a final sync (wait for any in-flight sync first).
123
123
  2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off.
124
- 3. **Harvest** — see `harvest.md`. The harvest distils the pillars' conclusions into the live steering docs by scope (`docs/architecture/`, `docs/architecture/adr/`, `docs/history/backlog.md`); the `docs/brainstorm/{topic}/` record itself is **kept** (committed), never deleted — it is the provenance the harvested headlines trace back to and the seed the next session resumes from.
124
+ 3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
125
125
  4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
126
126
 
127
127
  ## Conduct — holds for the whole session
@@ -129,7 +129,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
129
129
  1. **Speak English; codes live in files.** In conversation, name every pillar item by what it _is_ in plain words. Append the code in parentheses only when traceability needs it (_"…can a user change answer depth? (tracked as Q6)"_). Never lead with a bare `Q3`/`D7`. The user is not looking at the files.
130
130
  2. **No production code outside the session folder.** Illustrative load-bearing snippets are fine inside it (`samples/` or fenced in pillars). If asked for production code: offer a sketch inside the folder, or `/brainstorm stop` first.
131
131
  3. **The writing posture comes from `build.md`'s mode.** Greenfield: every pillar describes the system as it _will be_, present tense, as though the chosen design was always the plan — no migration vocabulary, no phantom history (banned list in `templates/build.md`). Brownfield/hybrid: migration vocabulary is legitimate, and `build.md` is its home; other pillars still describe the _target_ state.
132
- 4. **`AskUserQuestion` appears in exactly three places:** the intake frame batch, interview mode, and converge picks. Everywhere else: prose.
132
+ 4. **`AskUserQuestion` appears in exactly four places:** the intake frame batch, interview mode, converge picks, and the `stop` exit-artifact pick. Everywhere else: prose.
133
133
  5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
134
134
  6. **Questions are the only convergence currency.** Flaws, gaps, contradictions, uncovered aspects — everything unresolved funnels into `questions.md` or it doesn't exist. Nothing pending may live only in the conversation transcript.
135
135
  7. **No auto-invocation.** Only `/brainstorm start` and `/brainstorm stop` enter or leave a session. Read `state.md` at the start of every turn while a session folder exists.
@@ -0,0 +1,62 @@
1
+ # Exit artifacts
2
+
3
+ What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
4
+ either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
5
+ outward into the form the work needs; the record stays as the source they trace back to.
6
+
7
+ At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
8
+ can publish more than one):
9
+
10
+ | Artifact | Use when the outcome is… | Lands in | Voice |
11
+ | --- | --- | --- | --- |
12
+ | **Source of truth** | a standing reference — "what this thing **is**" | the repo's feature/architecture doc home, else a topic `Readme.md` | README — present tense, reader-first (`templates/source-of-truth.md`) |
13
+ | **Plans** | work to execute — "what to **build**, in what order" | one or more `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft) | plan — steps, sequencing, status |
14
+ | **Harvest into living docs** | findings that belong inside an existing doc system | dispersed by scope (table below) | matches each destination |
15
+
16
+ A session commonly emits a **source of truth** for the thing designed _and_ **plans** for building it.
17
+ Picking "source of truth" does **not** also disperse headlines across the doc tree — that is what "harvest"
18
+ does; pick it too if you want both the one-doc reference and the integrated headlines.
19
+
20
+ ## Source of truth
21
+
22
+ One consolidated, README-style document — the canonical reference for the thing designed. Distil every
23
+ pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
24
+ present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
25
+ `non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
26
+ record. Template: `templates/source-of-truth.md`.
27
+
28
+ Place it at the repo's canonical home for that kind of knowledge: a feature/system → `docs/features/{slug}.md`
29
+ (carry the doc system's `owns:` / `module:` / `keywords:` / `status:` frontmatter); cross-cutting →
30
+ `docs/architecture/{slug}.md`; no doc taxonomy → a `Readme.md` at the topic's folder. One document — if a
31
+ section outgrows it, link out rather than sprawl.
32
+
33
+ ## Plans
34
+
35
+ One or more executable plan docs in `docs/history/plans/` (Status: Draft), authored to the `documentation`
36
+ skill's §8 Plan template. Source: the `thesis.md` narrative for scope, `build.md` for migration strategy /
37
+ gotchas / rollout (execution content is plan content, not architecture). Split by deliverable, not by pillar
38
+ — one plan per cohesive unit of work.
39
+
40
+ ## Harvest into living docs
41
+
42
+ A structured diff between the session pillars and the live docs, dispersed by scope. Modules are labels,
43
+ not folders — a finding scoped to one module still lands in `docs/architecture/` and names the module in prose.
44
+
45
+ | Session source | Destination |
46
+ | --- | --- |
47
+ | Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
48
+ | `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
49
+ | Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant ADR |
50
+ | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
51
+ | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
52
+ | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
53
+ | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
54
+
55
+ Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
56
+
57
+ ## After publishing — keep the record
58
+
59
+ **Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
60
+ conclusions, but the record stays committed as their provenance: a traceable source for every published
61
+ headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the
62
+ `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.
@@ -0,0 +1,49 @@
1
+ # [Thing] — source of truth
2
+
3
+ > This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
4
+ > README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
5
+ > status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
6
+ > `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
7
+ > `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
8
+ >
9
+ > **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
10
+ > that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
11
+ > No doc taxonomy → a `Readme.md` at the topic's home.
12
+
13
+ ## What it is
14
+
15
+ [One paragraph, present tense: what the thing is, what it does, who uses it. Distilled from `thesis.md`.]
16
+
17
+ ## How it works
18
+
19
+ [The model — entities, relationships, the main flow — lifted from `domain-model.md` into plain,
20
+ reader-first description. Prose and tables; a diagram only if it earns its tokens.]
21
+
22
+ ## Parts
23
+
24
+ [One row per component / module / piece: name · role · what it owns · what it depends on.]
25
+
26
+ | Part | Role | Owns | Depends on |
27
+ | --- | --- | --- | --- |
28
+ | | | | |
29
+
30
+ ## Why it's shaped this way
31
+
32
+ [The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
33
+ concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
34
+ table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
35
+ don't reproduce them.]
36
+
37
+ ## Constraints & non-goals
38
+
39
+ [Accepted tradeoffs phrased as current fact ("a 5-second lag is accepted for predictable throughput")
40
+ and what is explicitly out of scope.]
41
+
42
+ ## Open questions
43
+
44
+ [One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
45
+
46
+ ---
47
+
48
+ _Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
49
+ and the provenance for everything above._
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "harness": "hr",
3
3
  "name": "hr",
4
- "version": "0.1.4",
4
+ "version": "0.1.5",
5
5
  "files": [
6
6
  ".prettierrc.json",
7
7
  ".prettierignore",
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "harness": "mobile",
3
3
  "name": "mobile",
4
- "version": "1.0.1",
4
+ "version": "1.0.2",
5
5
  "files": [
6
6
  ".prettierrc.json",
7
7
  ".prettierignore",
8
8
  ".vscode/settings.json"
9
9
  ],
10
- "digest": "7420cc394d05"
10
+ "digest": "efe055be77e7"
11
11
  }
@@ -108,9 +108,15 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
108
108
 
109
109
  ---
110
110
 
111
- ## Harvest
111
+ ## Exit artifacts
112
112
 
113
- The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop` the skill _offers_ the harvest adapter, which distils the pillars' conclusions into the doc tree (ADRs, module pillars, plans, the `boundary` skill reads contracts from source). The `docs/brainstorm/{topic}/` record is **kept** as the provenance — never deleted. See `harvest.md`.
113
+ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final sync, the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
114
+
115
+ - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
116
+ - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
117
+ - **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
118
+
119
+ The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
114
120
 
115
121
  ---
116
122
 
@@ -118,7 +124,7 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
118
124
 
119
125
  1. **No production code outside the session folder.** Illustrative snippets are fine inside it.
120
126
  2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
121
- 3. **`AskUserQuestion` appears in exactly three places:** the intake frame, interview mode, converge picks.
127
+ 3. **`AskUserQuestion` appears in exactly four places:** the intake frame, interview mode, converge picks, the `stop` exit-artifact pick.
122
128
  4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
123
129
  5. **Questions are the only convergence currency** — nothing pending may live only in the transcript.
124
130
  6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
@@ -129,10 +135,10 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
129
135
 
130
136
  ```
131
137
  brainstorm/ # the skill (in .claude/skills/)
132
- ├── SKILL.md # the skill definition Claude Code loads (~1.8k words)
133
- ├── README.md # this file
134
- ├── harvest.md # doc-tree harvest adapter (record kept at docs/brainstorm/{topic}/)
135
- └── templates/ # pillar templates copied into the session record on first use
138
+ ├── SKILL.md # the skill definition Claude Code loads (~1.8k words)
139
+ ├── README.md # this file
140
+ ├── exit-artifacts.md # what /brainstorm stop publishes: source-of-truth / plans / harvest
141
+ └── templates/ # pillar templates + source-of-truth.md, used in the record and at stop
136
142
  ```
137
143
 
138
144
  The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.
@@ -6,7 +6,7 @@ argument-hint: "start | stop"
6
6
 
7
7
  # Brainstorm
8
8
 
9
- Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, harvest — scales with complexity.
9
+ Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, exit artifacts — scales with complexity.
10
10
 
11
11
  ## The loop — every turn, every mode
12
12
 
@@ -50,7 +50,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
50
50
 
51
51
  ### 3. Bootstrap
52
52
 
53
- Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after harvest (it is the provenance the steering pillars distil from — see `harvest.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
53
+ Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
54
54
 
55
55
  ```
56
56
  STATE: open
@@ -121,7 +121,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
121
121
 
122
122
  1. Run a final sync (wait for any in-flight sync first).
123
123
  2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off.
124
- 3. **Harvest** — see `harvest.md`. The harvest distils the pillars' conclusions into the live steering docs by scope (`docs/architecture/`, `docs/architecture/adr/`, `docs/history/backlog.md`); the `docs/brainstorm/{topic}/` record itself is **kept** (committed), never deleted — it is the provenance the harvested headlines trace back to and the seed the next session resumes from.
124
+ 3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
125
125
  4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
126
126
 
127
127
  ## Conduct — holds for the whole session
@@ -129,7 +129,7 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
129
129
  1. **Speak English; codes live in files.** In conversation, name every pillar item by what it _is_ in plain words. Append the code in parentheses only when traceability needs it (_"…can a user change answer depth? (tracked as Q6)"_). Never lead with a bare `Q3`/`D7`. The user is not looking at the files.
130
130
  2. **No production code outside the session folder.** Illustrative load-bearing snippets are fine inside it (`samples/` or fenced in pillars). If asked for production code: offer a sketch inside the folder, or `/brainstorm stop` first.
131
131
  3. **The writing posture comes from `build.md`'s mode.** Greenfield: every pillar describes the system as it _will be_, present tense, as though the chosen design was always the plan — no migration vocabulary, no phantom history (banned list in `templates/build.md`). Brownfield/hybrid: migration vocabulary is legitimate, and `build.md` is its home; other pillars still describe the _target_ state.
132
- 4. **`AskUserQuestion` appears in exactly three places:** the intake frame batch, interview mode, and converge picks. Everywhere else: prose.
132
+ 4. **`AskUserQuestion` appears in exactly four places:** the intake frame batch, interview mode, converge picks, and the `stop` exit-artifact pick. Everywhere else: prose.
133
133
  5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
134
134
  6. **Questions are the only convergence currency.** Flaws, gaps, contradictions, uncovered aspects — everything unresolved funnels into `questions.md` or it doesn't exist. Nothing pending may live only in the conversation transcript.
135
135
  7. **No auto-invocation.** Only `/brainstorm start` and `/brainstorm stop` enter or leave a session. Read `state.md` at the start of every turn while a session folder exists.
@@ -0,0 +1,62 @@
1
+ # Exit artifacts
2
+
3
+ What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
4
+ either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
5
+ outward into the form the work needs; the record stays as the source they trace back to.
6
+
7
+ At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
8
+ can publish more than one):
9
+
10
+ | Artifact | Use when the outcome is… | Lands in | Voice |
11
+ | --- | --- | --- | --- |
12
+ | **Source of truth** | a standing reference — "what this thing **is**" | the repo's feature/architecture doc home, else a topic `Readme.md` | README — present tense, reader-first (`templates/source-of-truth.md`) |
13
+ | **Plans** | work to execute — "what to **build**, in what order" | one or more `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft) | plan — steps, sequencing, status |
14
+ | **Harvest into living docs** | findings that belong inside an existing doc system | dispersed by scope (table below) | matches each destination |
15
+
16
+ A session commonly emits a **source of truth** for the thing designed _and_ **plans** for building it.
17
+ Picking "source of truth" does **not** also disperse headlines across the doc tree — that is what "harvest"
18
+ does; pick it too if you want both the one-doc reference and the integrated headlines.
19
+
20
+ ## Source of truth
21
+
22
+ One consolidated, README-style document — the canonical reference for the thing designed. Distil every
23
+ pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
24
+ present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
25
+ `non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
26
+ record. Template: `templates/source-of-truth.md`.
27
+
28
+ Place it at the repo's canonical home for that kind of knowledge: a feature/system → `docs/features/{slug}.md`
29
+ (carry the doc system's `owns:` / `module:` / `keywords:` / `status:` frontmatter); cross-cutting →
30
+ `docs/architecture/{slug}.md`; no doc taxonomy → a `Readme.md` at the topic's folder. One document — if a
31
+ section outgrows it, link out rather than sprawl.
32
+
33
+ ## Plans
34
+
35
+ One or more executable plan docs in `docs/history/plans/` (Status: Draft), authored to the `documentation`
36
+ skill's §8 Plan template. Source: the `thesis.md` narrative for scope, `build.md` for migration strategy /
37
+ gotchas / rollout (execution content is plan content, not architecture). Split by deliverable, not by pillar
38
+ — one plan per cohesive unit of work.
39
+
40
+ ## Harvest into living docs
41
+
42
+ A structured diff between the session pillars and the live docs, dispersed by scope. Modules are labels,
43
+ not folders — a finding scoped to one module still lands in `docs/architecture/` and names the module in prose.
44
+
45
+ | Session source | Destination |
46
+ | --- | --- |
47
+ | Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
48
+ | `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
49
+ | Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant ADR |
50
+ | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
51
+ | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
52
+ | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
53
+ | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
54
+
55
+ Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
56
+
57
+ ## After publishing — keep the record
58
+
59
+ **Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
60
+ conclusions, but the record stays committed as their provenance: a traceable source for every published
61
+ headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the
62
+ `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.
@@ -0,0 +1,49 @@
1
+ # [Thing] — source of truth
2
+
3
+ > This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
4
+ > README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
5
+ > status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
6
+ > `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
7
+ > `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
8
+ >
9
+ > **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
10
+ > that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
11
+ > No doc taxonomy → a `Readme.md` at the topic's home.
12
+
13
+ ## What it is
14
+
15
+ [One paragraph, present tense: what the thing is, what it does, who uses it. Distilled from `thesis.md`.]
16
+
17
+ ## How it works
18
+
19
+ [The model — entities, relationships, the main flow — lifted from `domain-model.md` into plain,
20
+ reader-first description. Prose and tables; a diagram only if it earns its tokens.]
21
+
22
+ ## Parts
23
+
24
+ [One row per component / module / piece: name · role · what it owns · what it depends on.]
25
+
26
+ | Part | Role | Owns | Depends on |
27
+ | --- | --- | --- | --- |
28
+ | | | | |
29
+
30
+ ## Why it's shaped this way
31
+
32
+ [The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
33
+ concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
34
+ table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
35
+ don't reproduce them.]
36
+
37
+ ## Constraints & non-goals
38
+
39
+ [Accepted tradeoffs phrased as current fact ("a 5-second lag is accepted for predictable throughput")
40
+ and what is explicitly out of scope.]
41
+
42
+ ## Open questions
43
+
44
+ [One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
45
+
46
+ ---
47
+
48
+ _Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
49
+ and the provenance for everything above._
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nurix/etna",
3
- "version": "0.18.12",
3
+ "version": "0.18.14",
4
4
  "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,25 +0,0 @@
1
- # Harvest adapter
2
-
3
- Harvest distils a closed session's **conclusions** into the live steering docs. It is **offered at `stop`, never forced** — but the `docs/brainstorm/{topic}/` record is **kept either way**: it is a committed design record, not a scratchpad, so harvest copies its conclusions outward and leaves the record in place as their provenance. (In a code-harnessed repo `docs/architecture/` and its `adr/` already exist, so the routing below always applies.)
4
-
5
- ## Routing
6
-
7
- The harvest is a structured diff between the session pillars and the live docs, routed by scope: doctrine / glossary / non-goals / IA / contract changes → `docs/architecture/`, decisions → `docs/architecture/adr/`, backlog → `docs/history/backlog.md`. Modules are labels, not folders — a finding scoped to one module's context still lands in `docs/architecture/` and names the module in prose; there is no module-local doc home.
8
-
9
- | Session source | Destination |
10
- | --- | --- |
11
- | `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
12
- | `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, note the contract change there — the `boundary` skill will pick it up from source at the next plan check |
13
- | Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md`, authored to the **`documentation` skill ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
14
- | Doctrine / glossary / rejected | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md`, or the relevant ADR |
15
- | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
16
- | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
17
- | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
18
- | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
19
- | `build.md` (brownfield/hybrid: migration strategy, gotchas, rollout) | the plan doc in `docs/history/plans/` — execution content is plan content, not architecture |
20
-
21
- Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what was written where.
22
-
23
- ## After harvest
24
-
25
- **Keep the `docs/brainstorm/{topic}/` record — never delete it.** The dispersed homes now carry the distilled conclusions, but the record stays committed as their provenance: a traceable source for every harvested headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.
@@ -1,25 +0,0 @@
1
- # Harvest adapter
2
-
3
- Harvest distils a closed session's **conclusions** into the live steering docs. It is **offered at `stop`, never forced** — but the `docs/brainstorm/{topic}/` record is **kept either way**: it is a committed design record, not a scratchpad, so harvest copies its conclusions outward and leaves the record in place as their provenance. (In a code-harnessed repo `docs/architecture/` and its `adr/` already exist, so the routing below always applies.)
4
-
5
- ## Routing
6
-
7
- The harvest is a structured diff between the session pillars and the live docs, routed by scope: doctrine / glossary / non-goals / IA / contract changes → `docs/architecture/`, decisions → `docs/architecture/adr/`, backlog → `docs/history/backlog.md`. Modules are labels, not folders — a finding scoped to one module's context still lands in `docs/architecture/` and names the module in prose; there is no module-local doc home.
8
-
9
- | Session source | Destination |
10
- | --- | --- |
11
- | `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
12
- | `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, note the contract change there — the `boundary` skill will pick it up from source at the next plan check |
13
- | Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md`, authored to the **`documentation` skill ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
14
- | Doctrine / glossary / rejected | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md`, or the relevant ADR |
15
- | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
16
- | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
17
- | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
18
- | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
19
- | `build.md` (brownfield/hybrid: migration strategy, gotchas, rollout) | the plan doc in `docs/history/plans/` — execution content is plan content, not architecture |
20
-
21
- Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what was written where.
22
-
23
- ## After harvest
24
-
25
- **Keep the `docs/brainstorm/{topic}/` record — never delete it.** The dispersed homes now carry the distilled conclusions, but the record stays committed as their provenance: a traceable source for every harvested headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.
@@ -1,25 +0,0 @@
1
- # Harvest adapter
2
-
3
- Harvest distils a closed session's **conclusions** into the live steering docs. It is **offered at `stop`, never forced** — but the `docs/brainstorm/{topic}/` record is **kept either way**: it is a committed design record, not a scratchpad, so harvest copies its conclusions outward and leaves the record in place as their provenance. (In a code-harnessed repo `docs/architecture/` and its `adr/` already exist, so the routing below always applies.)
4
-
5
- ## Routing
6
-
7
- The harvest is a structured diff between the session pillars and the live docs, routed by scope: doctrine / glossary / non-goals / IA / contract changes → `docs/architecture/`, decisions → `docs/architecture/adr/`, backlog → `docs/history/backlog.md`. Modules are labels, not folders — a finding scoped to one module's context still lands in `docs/architecture/` and names the module in prose; there is no module-local doc home.
8
-
9
- | Session source | Destination |
10
- | --- | --- |
11
- | `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
12
- | `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, note the contract change there — the `boundary` skill will pick it up from source at the next plan check |
13
- | Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md`, authored to the **`documentation` skill ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
14
- | Doctrine / glossary / rejected | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md`, or the relevant ADR |
15
- | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
16
- | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
17
- | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
18
- | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
19
- | `build.md` (brownfield/hybrid: migration strategy, gotchas, rollout) | the plan doc in `docs/history/plans/` — execution content is plan content, not architecture |
20
-
21
- Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what was written where.
22
-
23
- ## After harvest
24
-
25
- **Keep the `docs/brainstorm/{topic}/` record — never delete it.** The dispersed homes now carry the distilled conclusions, but the record stays committed as their provenance: a traceable source for every harvested headline, the seed the next `/brainstorm start` on this topic resumes from, and a high-surprisal input the `distiller` ingests. Retire a topic's folder by hand only when the design line is truly dead.