@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.
- package/data/harness-index.json +1 -1
- package/data/harnesses/code/CLAUDE.md +10 -1
- package/data/harnesses/code/harness.json +2 -2
- package/data/harnesses/code/skills/brainstorm/README.md +13 -7
- package/data/harnesses/code/skills/brainstorm/SKILL.md +4 -4
- package/data/harnesses/code/skills/brainstorm/exit-artifacts.md +62 -0
- package/data/harnesses/code/skills/brainstorm/templates/source-of-truth.md +49 -0
- package/data/harnesses/etna/harness.json +2 -2
- package/data/harnesses/etna/skills/brainstorm/README.md +13 -7
- package/data/harnesses/etna/skills/brainstorm/SKILL.md +4 -4
- package/data/harnesses/etna/skills/brainstorm/exit-artifacts.md +62 -0
- package/data/harnesses/etna/skills/brainstorm/templates/source-of-truth.md +49 -0
- package/data/harnesses/hr/harness.json +1 -1
- package/data/harnesses/mobile/harness.json +2 -2
- package/data/harnesses/mobile/skills/brainstorm/README.md +13 -7
- package/data/harnesses/mobile/skills/brainstorm/SKILL.md +4 -4
- package/data/harnesses/mobile/skills/brainstorm/exit-artifacts.md +62 -0
- package/data/harnesses/mobile/skills/brainstorm/templates/source-of-truth.md +49 -0
- package/package.json +1 -1
- package/data/harnesses/code/skills/brainstorm/harvest.md +0 -25
- package/data/harnesses/etna/skills/brainstorm/harvest.md +0 -25
- package/data/harnesses/mobile/skills/brainstorm/harvest.md +0 -25
package/data/harness-index.json
CHANGED
|
@@ -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.
|
|
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
|
|
|
@@ -108,9 +108,15 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
|
|
|
108
108
|
|
|
109
109
|
---
|
|
110
110
|
|
|
111
|
-
##
|
|
111
|
+
## Exit artifacts
|
|
112
112
|
|
|
113
|
-
The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop
|
|
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
|
|
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
|
|
133
|
-
├── README.md
|
|
134
|
-
├──
|
|
135
|
-
└── templates/
|
|
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,
|
|
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
|
|
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. **
|
|
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
|
|
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._
|
|
@@ -108,9 +108,15 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
|
|
|
108
108
|
|
|
109
109
|
---
|
|
110
110
|
|
|
111
|
-
##
|
|
111
|
+
## Exit artifacts
|
|
112
112
|
|
|
113
|
-
The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop
|
|
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
|
|
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
|
|
133
|
-
├── README.md
|
|
134
|
-
├──
|
|
135
|
-
└── templates/
|
|
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,
|
|
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
|
|
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. **
|
|
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
|
|
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._
|
|
@@ -108,9 +108,15 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
|
|
|
108
108
|
|
|
109
109
|
---
|
|
110
110
|
|
|
111
|
-
##
|
|
111
|
+
## Exit artifacts
|
|
112
112
|
|
|
113
|
-
The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop
|
|
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
|
|
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
|
|
133
|
-
├── README.md
|
|
134
|
-
├──
|
|
135
|
-
└── templates/
|
|
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,
|
|
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
|
|
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. **
|
|
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
|
|
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.
|
|
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.
|