@nurix/etna 0.18.14 → 0.18.16

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.
Files changed (96) hide show
  1. package/README.md +11 -16
  2. package/data/harness-index.json +1 -1
  3. package/data/harnesses/code/CLAUDE.md +71 -57
  4. package/data/harnesses/code/agents/{spec-mode.md → lld-mode.md} +12 -12
  5. package/data/harnesses/code/agents/maintenance.md +2 -31
  6. package/data/harnesses/code/harness.json +2 -2
  7. package/data/harnesses/code/hooks/hooks.json +0 -23
  8. package/data/harnesses/code/rules/testing.md +25 -0
  9. package/data/harnesses/code/skills/boundary/SKILL.md +34 -14
  10. package/data/harnesses/code/skills/boundary/references/index.md +16 -0
  11. package/data/harnesses/code/skills/boundary/references/mechanisms.md +99 -0
  12. package/data/harnesses/code/skills/boundary/references/packs/async-messaging.md +81 -0
  13. package/data/harnesses/code/skills/boundary/references/packs/auth.md +93 -0
  14. package/data/harnesses/code/skills/boundary/references/packs/build-config-runtime.md +93 -0
  15. package/data/harnesses/code/skills/boundary/references/packs/cloudflare.md +93 -0
  16. package/data/harnesses/code/skills/boundary/references/packs/frontend.md +93 -0
  17. package/data/harnesses/code/skills/boundary/references/packs/generic-tail.md +55 -0
  18. package/data/harnesses/code/skills/boundary/references/packs/persistence.md +93 -0
  19. package/data/harnesses/code/skills/boundary/references/packs/wire-api.md +87 -0
  20. package/data/harnesses/code/skills/brainstorm/README.md +28 -10
  21. package/data/harnesses/code/skills/brainstorm/SKILL.md +27 -12
  22. package/data/harnesses/code/skills/brainstorm/exit-artifacts.md +2 -2
  23. package/data/harnesses/code/skills/brainstorm/templates/evidence.md +24 -0
  24. package/data/harnesses/code/skills/brainstorm/templates/rejected.md +5 -1
  25. package/data/harnesses/code/skills/documentation/SKILL.md +2 -2
  26. package/data/harnesses/code/skills/documentation/references/templates.md +10 -77
  27. package/data/harnesses/etna/CLAUDE.md +11 -12
  28. package/data/harnesses/etna/agents/{spec-mode.md → lld-mode.md} +12 -12
  29. package/data/harnesses/etna/agents/maintenance.md +2 -31
  30. package/data/harnesses/etna/harness.json +2 -2
  31. package/data/harnesses/etna/hooks/hooks.json +0 -23
  32. package/data/harnesses/etna/rules/testing.md +25 -0
  33. package/data/harnesses/etna/skills/boundary/SKILL.md +34 -14
  34. package/data/harnesses/etna/skills/boundary/references/index.md +16 -0
  35. package/data/harnesses/etna/skills/boundary/references/mechanisms.md +99 -0
  36. package/data/harnesses/etna/skills/boundary/references/packs/async-messaging.md +81 -0
  37. package/data/harnesses/etna/skills/boundary/references/packs/auth.md +93 -0
  38. package/data/harnesses/etna/skills/boundary/references/packs/build-config-runtime.md +93 -0
  39. package/data/harnesses/etna/skills/boundary/references/packs/cloudflare.md +93 -0
  40. package/data/harnesses/etna/skills/boundary/references/packs/frontend.md +93 -0
  41. package/data/harnesses/etna/skills/boundary/references/packs/generic-tail.md +55 -0
  42. package/data/harnesses/etna/skills/boundary/references/packs/persistence.md +93 -0
  43. package/data/harnesses/etna/skills/boundary/references/packs/wire-api.md +87 -0
  44. package/data/harnesses/etna/skills/brainstorm/README.md +28 -10
  45. package/data/harnesses/etna/skills/brainstorm/SKILL.md +27 -12
  46. package/data/harnesses/etna/skills/brainstorm/exit-artifacts.md +2 -2
  47. package/data/harnesses/etna/skills/brainstorm/templates/evidence.md +24 -0
  48. package/data/harnesses/etna/skills/brainstorm/templates/rejected.md +5 -1
  49. package/data/harnesses/etna/skills/documentation/SKILL.md +2 -2
  50. package/data/harnesses/etna/skills/documentation/references/templates.md +10 -77
  51. package/data/harnesses/mobile/CLAUDE.md +78 -55
  52. package/data/harnesses/mobile/agents/{spec-mode.md → lld-mode.md} +12 -12
  53. package/data/harnesses/mobile/agents/maintenance.md +2 -31
  54. package/data/harnesses/mobile/harness.json +2 -2
  55. package/data/harnesses/mobile/hooks/hooks.json +0 -23
  56. package/data/harnesses/mobile/rules/testing.md +25 -0
  57. package/data/harnesses/mobile/skills/boundary/SKILL.md +34 -14
  58. package/data/harnesses/mobile/skills/boundary/references/index.md +16 -0
  59. package/data/harnesses/mobile/skills/boundary/references/mechanisms.md +99 -0
  60. package/data/harnesses/mobile/skills/boundary/references/packs/async-messaging.md +81 -0
  61. package/data/harnesses/mobile/skills/boundary/references/packs/auth.md +93 -0
  62. package/data/harnesses/mobile/skills/boundary/references/packs/build-config-runtime.md +93 -0
  63. package/data/harnesses/mobile/skills/boundary/references/packs/cloudflare.md +93 -0
  64. package/data/harnesses/mobile/skills/boundary/references/packs/frontend.md +93 -0
  65. package/data/harnesses/mobile/skills/boundary/references/packs/generic-tail.md +55 -0
  66. package/data/harnesses/mobile/skills/boundary/references/packs/persistence.md +93 -0
  67. package/data/harnesses/mobile/skills/boundary/references/packs/wire-api.md +87 -0
  68. package/data/harnesses/mobile/skills/brainstorm/README.md +28 -10
  69. package/data/harnesses/mobile/skills/brainstorm/SKILL.md +27 -12
  70. package/data/harnesses/mobile/skills/brainstorm/exit-artifacts.md +2 -2
  71. package/data/harnesses/mobile/skills/brainstorm/templates/evidence.md +24 -0
  72. package/data/harnesses/mobile/skills/brainstorm/templates/rejected.md +5 -1
  73. package/data/harnesses/mobile/skills/documentation/SKILL.md +2 -2
  74. package/data/harnesses/mobile/skills/documentation/references/templates.md +10 -77
  75. package/package.json +1 -1
  76. package/data/harnesses/code/hooks/lib/redact.mjs +0 -35
  77. package/data/harnesses/code/hooks/prompt-recall.mjs +0 -155
  78. package/data/harnesses/code/hooks/session-reflect.mjs +0 -285
  79. package/data/harnesses/code/skills/boundary/references/boundary-taxonomy.md +0 -796
  80. package/data/harnesses/code/skills/distiller/SKILL.md +0 -90
  81. package/data/harnesses/code/skills/distiller/references/docs-mode.md +0 -299
  82. package/data/harnesses/code/skills/distiller/references/method.md +0 -94
  83. package/data/harnesses/etna/hooks/lib/redact.mjs +0 -35
  84. package/data/harnesses/etna/hooks/prompt-recall.mjs +0 -155
  85. package/data/harnesses/etna/hooks/session-reflect.mjs +0 -285
  86. package/data/harnesses/etna/skills/boundary/references/boundary-taxonomy.md +0 -796
  87. package/data/harnesses/etna/skills/distiller/SKILL.md +0 -90
  88. package/data/harnesses/etna/skills/distiller/references/docs-mode.md +0 -299
  89. package/data/harnesses/etna/skills/distiller/references/method.md +0 -94
  90. package/data/harnesses/mobile/hooks/lib/redact.mjs +0 -35
  91. package/data/harnesses/mobile/hooks/prompt-recall.mjs +0 -155
  92. package/data/harnesses/mobile/hooks/session-reflect.mjs +0 -285
  93. package/data/harnesses/mobile/skills/boundary/references/boundary-taxonomy.md +0 -796
  94. package/data/harnesses/mobile/skills/distiller/SKILL.md +0 -90
  95. package/data/harnesses/mobile/skills/distiller/references/docs-mode.md +0 -299
  96. package/data/harnesses/mobile/skills/distiller/references/method.md +0 -94
@@ -1,22 +1,34 @@
1
1
  ---
2
2
  name: brainstorm
3
- description: Thinking-partner session for designing software. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document or a one-shot brain dump); drip-fed action items are rejected as too small. Runs one constant loop (distill → abstract → sync → record) across four modes (dump / interview / probe / converge). Coherence = zero open questions after a fresh pillar sync. Pillar count scales with a complexity dial; refuses production code outside the session folder while open.
3
+ description: Thinking-partner session for designing software. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document or a one-shot brain dump); drip-fed action items are rejected as too small. Runs one constant loop (distill → abstract → sync → record) across four modes (dump / interview / probe / converge), under a memory contract: the session folder is the only memory — both sides of the conversation are captured, distilled, self-contained. Coherence = zero open questions after a fresh pillar sync. Pillar count scales with a complexity dial; refuses production code outside the session folder while open.
4
4
  argument-hint: "start | stop"
5
5
  ---
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, exit artifacts — 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. But the conversation is mortal — context compacts, sessions end — so the session folder is the **only memory**: everything the session produces lives there, distilled, or it doesn't survive (see **The memory contract**). 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
 
13
13
  1. **Distill.** Fold what the user just said into the pillars, in _their_ framing, during the same turn.
14
14
  2. **Abstract.** Name the latent structure they implied but didn't state — entities and relationships ("an account has many leads" → `domain-model.md`), invariants, principles, terms. Offer at most one abstraction per exchange; it's a contribution, not a lecture.
15
15
  3. **Sync.** Keep the pillars consistent with each other and with the basis (see **The sync agent**).
16
- 4. **Record.** Writes happen in the turn that produced the information — never accumulated for a session-end dump.
16
+ 4. **Record.** The user's words land in the pillars in the turn they arrive — never accumulated for a session-end dump. Your own substance — analyses, diagnoses, recommendations with their reasoning, definitions, informed rejections — is on disk **by the next sync dispatch** at the latest; the dispatch-time filing checklist makes that mechanical (the memory contract, rule 1; **The sync agent**).
17
17
 
18
18
  Modes change _who drives_ and _how much gets asked_. The loop never stops.
19
19
 
20
+ ## The memory contract
21
+
22
+ Write as if the transcript is already deleted — it will be. The folder must let a reader with zero context reconstruct the *thinking*, not just index the conclusions.
23
+
24
+ 1. **Both-sides capture.** Facilitator substance is session knowledge: any analysis, causal diagnosis, recommendation-with-reasoning, or definition delivered in chat lands in the folder **by the next sync dispatch** — that is the batch point; there is no other. The dispatch-time filing checklist (see **The sync agent**) is the forcing function. Test: if a chat message is still the only place a piece of knowledge lives when a sync dispatches, the contract was violated.
25
+ 2. **Distilled, never verbatim.** Capture is interpretation, not stenography: name the claim, the reasoning, and the implication. Record the general point and cite examples as examples — never promote one example into the frame. (Integrity copies demanded by rule 4 — printed enumerations, cited excerpts — are not stenography; the ban is on transcript-pasting.)
26
+ 3. **Evidence notes.** Research and analysis produced *during* the session — audits, studies, comparisons — land as dated files in `<folder>/evidence/` (from `templates/evidence.md`): what was examined, the distilled findings, and which question or decision each feeds. `basis/` holds frozen *inputs* only; the two never mix.
27
+ 4. **No naked pointers.** A pillar may not lean on anything undefined in-folder: an enumeration cited by number gets printed once; a term gets a one-line gloss or a glossary entry; an external citation carries an excerpt of its substance. A reader must never need the transcript or an external file to parse a pillar.
28
+ 5. **Eager rejections.** When the user knowingly declines an option you presented, materialize `rejected.md` then and there — the option *and the evidence it was declined against*. A deliberate call must never read later as an unexamined one.
29
+
30
+ **After compaction:** re-enter from the folder alone (`state.md` first). Anything you still "remember" that isn't on disk is a leak — file it immediately.
31
+
20
32
  ## Modes
21
33
 
22
34
  | Mode | Who drives | When | Behavior |
@@ -50,7 +62,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
50
62
 
51
63
  ### 3. Bootstrap
52
64
 
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`:
65
+ 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**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
54
66
 
55
67
  ```
56
68
  STATE: open
@@ -74,7 +86,7 @@ Initial questions come from the basis distillation **only** — contradictions i
74
86
  | `build.md` | How the work gets executed: build mode (greenfield default / brownfield / hybrid), migration strategy, gotchas, rollout. Greenfield closes the execution sections; brownfield opens them | always |
75
87
  | `domain-model.md` | Entities, relationships, cardinalities, state ownership | medium+ |
76
88
  | `tech.md` | Stack choices, seeded from harness rules (e.g. `.claude/rules/general.md`) at bootstrap; deviations recorded with whys | medium+ |
77
- | `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | as their templates describe | **lazy** — materialize on first real content, any complexity |
89
+ | `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | as their templates describe | **lazy** — materialize on first real content, any complexity. `rejected` is the exception: the memory contract makes it **eager** — it materializes the moment an option is knowingly declined |
78
90
 
79
91
  The complexity dial sets _defaults_, not a cage: any lazy pillar materializes mid-session the moment the conversation produces content for it, and at **low** complexity the always-four may even live as sections of a single file if the user prefers.
80
92
 
@@ -90,18 +102,21 @@ The complexity dial sets _defaults_, not a cage: any lazy pillar materializes mi
90
102
 
91
103
  The background reconciler that replaces ceremony with consistency. **One sync in flight at a time; queue at most one behind it.**
92
104
 
93
- **When:** after a distillation batch lands substantive pillar writes (at the turn break, not mid-sentence); mandatorily on entering converge and at `stop`; on demand. At **low** complexity, run it inline yourself; at **medium+**, dispatch a background `general-purpose` agent (read/write access to the session folder only).
105
+ **When:** after a distillation batch lands substantive pillar writes (at the turn break, not mid-sentence); mandatorily on entering converge and at `stop`; on demand. At **low** complexity, run it inline yourself; at **medium+**, dispatch a background `general-purpose` agent **on Opus** (`model: "opus"` — pillar reconciliation is quality-critical, so never a smaller model; and never the main-loop frontier model, whose session budget belongs to the conversation), with read/write access to the session folder only. Exception at any complexity: the `stop` sync's self-containment pass always dispatches the context-free agent — an inline reader with full conversational context cannot cold-read, because it already knows every undefined term.
106
+
107
+ **The filing checklist — before every dispatch.** The sync agent cannot see the conversation, so the orchestrator runs the transcript-side half itself, immediately before dispatching: list your substantive contributions since the last sync — analyses, diagnoses, recommendations with reasoning, definitions, rejections — and file any that aren't on disk (evidence note, decision rationale, glossary line, rejected entry). Only then dispatch. A sync dispatched over unfiled substance audits an incomplete record and stamps it green.
94
108
 
95
- **Contract — audit exactly four sources:**
109
+ **Contract — audit exactly five sources:**
96
110
 
97
111
  1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build (a decision that implies migration work with no `build.md` entry is a contradiction).
98
112
  2. **Aspect coverage** — any aspect on the map with no content anywhere → emit a question.
99
113
  3. **Basis drift** — does the thesis still agree with `basis/`? Divergence is fine if decided; accidental divergence → emit a question.
100
114
  4. **Tech conflicts** — anything that violates `tech.md` without a recorded deviation.
115
+ 5. **Self-containment** — read as the stranger you are: undefined terms, pointer-only references, enumerations cited by number but never printed, evidence a pillar leans on that no file carries, decided-vs-open ambiguity, citations of artifacts that no longer exist. Also the reverse direction: an evidence note nothing consumes gets a scribe-note in the report — never a question; filing an insight must never push the session away from coherent. The sync agent is dispatched context-free — it **is** the cold reader the memory contract writes for.
101
116
 
102
117
  **Output:** direct pillar edits for **scribe-calls**, new questions for **design-calls**, and a one-line report.
103
118
 
104
- **The line:** a _scribe-call_ is anything whose resolution doesn't change the design — wording, annotations, obvious bookkeeping. Just do it; list it in the report (the user can veto). A _design-call_ is anything whose resolution changes the idea — file it as a question (`Raised by: sync`) and move on. **Never** interrupt the conversation to ask "apply now or defer?" — file and continue.
119
+ **The line:** a _scribe-call_ is anything whose resolution doesn't change the design — wording, annotations, obvious bookkeeping, printing a missing enumeration, glossing an undefined term. Just do it; list it in the report (the user can veto). A _design-call_ is anything whose resolution changes the idea — file it as a question (`Raised by: sync`) and move on. **Never** interrupt the conversation to ask "apply now or defer?" — file and continue.
105
120
 
106
121
  **The report is the status line.** Deliver it at the next natural turn break:
107
122
 
@@ -115,12 +130,12 @@ There is no separate dashboard, no scheduled checkpoint. This line is the only a
115
130
  coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
116
131
  ```
117
132
 
118
- Zero means _"audited against the four sources and clean"_ — never _"nothing came to mind."_ Don't declare the idea coherent on any other basis. Distance-to-coherent is always visible in the sync report; the **user** decides when to converge and when to close. The skill never says "let's decide now."
133
+ Zero means _"audited against the five sources and clean"_ — never _"nothing came to mind."_ Don't declare the idea coherent on any other basis. Distance-to-coherent is always visible in the sync report; the **user** decides when to converge and when to close. The skill never says "let's decide now."
119
134
 
120
135
  ## `stop`
121
136
 
122
- 1. Run a final sync (wait for any in-flight sync first).
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.
137
+ 1. Run a final sync (wait for any in-flight sync first). It audits all five sources — self-containment included, so the record is verified standalone-readable exactly when it is about to become the only survivor of the session.
138
+ 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. Flag parked **self-containment** gaps distinctly: parking one means the record ships not fully standalone.
124
139
  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
140
  4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
126
141
 
@@ -131,5 +146,5 @@ Zero means _"audited against the four sources and clean"_ — never _"nothing ca
131
146
  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
147
  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
148
  5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
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.
149
+ 6. **Nothing lives only in the transcript.** Questions are the only convergence currency — flaws, gaps, contradictions, uncovered aspects funnel into `questions.md` or they don't exist. The memory contract extends the same law from pending work to **knowledge**: analyses, reasoning, definitions, and rejections funnel into the folder or they don't exist.
135
150
  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.
@@ -58,5 +58,5 @@ Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}
58
58
 
59
59
  **Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
60
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.
61
+ headline, and the seed the next `/brainstorm start` on this topic resumes from. Retire a topic's folder
62
+ by hand only when the design line is truly dead.
@@ -0,0 +1,24 @@
1
+ # Evidence — [what was examined]
2
+
3
+ This file is a **session-produced analysis** — research, an audit, a study, a comparison — captured under the memory contract: distilled findings, not a log. One file per analysis, dated, in `<session>/evidence/`. (`basis/` is for frozen *inputs* the session started from; evidence is what the session itself produced.)
4
+
5
+ Every evidence note should **feed** something — a question it informs, a decision it grounds, or, for free-floating insight, the thesis aspect it belongs to. The sync agent notes unconsumed evidence in its report as a scribe-note, never a question — filing an insight must never push the session away from coherent.
6
+
7
+ Write for a reader with zero context: define terms, print the numbers, excerpt sources. Distill — name the claim, the reasoning, the implication; never paste transcripts or raw tool output.
8
+
9
+ ---
10
+
11
+ **Date.** YYYY-MM-DD
12
+
13
+ **Examined.** [What was analyzed and how — the sources, the method, one or two lines.]
14
+
15
+ **Feeds.** [Q-N / D-N — or `aspect: <name>` from the thesis map when no specific question or decision consumes it yet.]
16
+
17
+ ## Findings
18
+
19
+ - [Distilled finding 1 — the claim, with the number/citation that carries it.]
20
+ - [Distilled finding 2.]
21
+
22
+ ## Implication
23
+
24
+ [What this means for the design — one short paragraph. If it changes a lean or closes an option, say so and point at the question/decision entry that records it.]
@@ -2,7 +2,9 @@
2
2
 
3
3
  This file captures **paths that were considered and rejected**, with the reason for rejection. Its purpose is to prevent re-litigation: when someone proposes the same alternative six weeks later, this file answers "we already looked at that; here's why we didn't go that way."
4
4
 
5
- Each entry needs three load-bearing parts: **Considered** (what was proposed, in concrete terms), **Rejected because** (the specific reason — "didn't fit" is useless to future-you; name the constraint, the cost, the risk), and **Re-evaluate if** (what would need to change for the rejected path to become viable again). The re-evaluate field stops the rejection from looking permanent when it isn't — most rejections are scope-conditional, not absolute.
5
+ Each entry needs four load-bearing parts: **Considered** (what was proposed, in concrete terms), **Evidence on the table** (what prior art, findings, or arguments were in front of the decider when they declined — this is what separates an informed rejection from an unexamined one), **Rejected because** (the specific reason — "didn't fit" is useless to future-you; name the constraint, the cost, the risk), and **Re-evaluate if** (what would need to change for the rejected path to become viable again). The re-evaluate field stops the rejection from looking permanent when it isn't — most rejections are scope-conditional, not absolute.
6
+
7
+ This file is **eager**, not lazy (the memory contract): it materializes the moment the user knowingly declines a presented option, in the same turn — an informed rejection that lives only in the transcript is a leak.
6
8
 
7
9
  This is one of the four places inside the brainstorm folder where past tense and "we considered X" framing is permitted (the others: `decisions.md`, `references.md`, git history). The whole point of this file is to capture the path-not-taken so future architects don't have to re-discover it.
8
10
 
@@ -14,6 +16,8 @@ If circumstances change and a rejected path becomes attractive again, **do not s
14
16
 
15
17
  **Considered.** [What was proposed.]
16
18
 
19
+ **Evidence on the table.** [The prior art, findings, or arguments in front of the decider at the moment of declining — cite the evidence note or basis file if one carries it.]
20
+
17
21
  **Rejected because.** [The reason. Be specific.]
18
22
 
19
23
  **Re-evaluate if.** [What would change to make this viable.]
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: documentation
3
- description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module, (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc".
3
+ description: Template & generator library for technical docs — the skill agents call to produce a doc from a template. Use to (1) document a feature or module (the feature doc is the feature's LLD — low-level design — written in LLD Mode), (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) record an architecture decision (ADR), (6) create or update the project root README, (7) create or update a plan, (8) derive a feature doc's `owns:` frontmatter (the code-path globs it owns) from code, (9) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (10) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`maintenance` agent (baseline mode)** (which calls this skill for each template) — this skill does not orchestrate baseline. Triggers on "document this", "create docs", "update changelog", "add to protected files", "ADR", "architecture decision", "root README", "plan", "feature doc", "LLD".
4
4
  ---
5
5
 
6
6
  # Technical Documentation Skill
@@ -22,7 +22,7 @@ User request
22
22
  │
23
23
  ├─ "Baseline/reconcile docs" ──────▶ maintenance agent (baseline mode) (it calls this skill per template)
24
24
  │
25
- ├─ "Document feature/module" ──────▶ Module Template
25
+ ├─ "Document feature/module (LLD)" ▶ Module Template
26
26
  │
27
27
  ├─ "Create/update changelog" ──────▶ Changelog Template
28
28
  │
@@ -112,7 +112,7 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
112
112
 
113
113
  ## Folder Rules
114
114
 
115
- - `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index. (An optional `anchors:` block — a qmd drift tripwire, see §3 — is a separate tooling key a doc may additionally carry.)
115
+ - `docs/features/`: Living reference for implemented features. Each feature doc **carries** the `owns:` / `module:` / `keywords:` / `status:` frontmatter — `owns:` declares the code-path globs it owns (the only ownership key), `module:` is an optional bounded-context label, `keywords:` are discovery terms, `status:` is `active`/`draft`/`deprecated`. The SessionStart hook unions every feature's `owns:` globs into the injected ownership index.
116
116
  - `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). A module's cross-cutting prose lives here (or in a browse-folder `Readme.md`). Update when cross-cutting concerns change.
117
117
  - `docs/operations/`: How-to procedures for setup, development, and deployment. Update when workflows change.
118
118
  - `docs/history/plans/`: Historical. Must have `Status:` field. Never modify after completion.
@@ -131,21 +131,10 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
131
131
 
132
132
  ---
133
133
 
134
- ## 3. Code-Path Ownership & Anchors
134
+ ## 3. Code-Path Ownership
135
135
 
136
136
  **Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See **Frontmatter Derivation** in `SKILL.md` for turning code into `owns:` globs.
137
137
 
138
- **Anchors (optional tooling key).** A doc may additionally carry an `anchors:` block — a qmd drift tripwire, orthogonal to ownership:
139
-
140
- ```yaml
141
- ---
142
- anchors:
143
- - "qmd query: feature-name persistence shape"
144
- ---
145
- ```
146
-
147
- `anchors` is an optional list of qmd queries (or `#docid`s) that re-resolve to the code a doc abstracts as it moves. It is a drift tripwire, never a contract — an anchor that returns nothing IS the drift signal, and nothing auto-rewrites from an anchor result. It is read on demand by the maintenance anchor-drift check, never injected, and inert when qmd is absent.
148
-
149
138
  ---
150
139
 
151
140
  ## 4. Scaffold Files (create if missing)
@@ -241,14 +230,6 @@ description: Shared knowledge accumulated across agent sessions. All agents shou
241
230
  - **Spec version:** v{harness-version}
242
231
  <!-- v{harness-version} resolves to the installed harness version — read it from `.claude/harness.json` (`version`) / `docs/structure.md` frontmatter (`harness-version`); never hardcode a literal version here. -->
243
232
 
244
- ## Knowledge Tiers
245
-
246
- Memory is a gradient — volume falls, signal rises, one hop down each tier. Tiers describe themselves here even before they fill:
247
-
248
- - **Inbox** (`docs/memory/inbox/`) — per-actor queue of session lessons, written by the `session-reflect` hook at session end and consumed by the distiller on digestion. Transient by design, rarely read directly.
249
- - **Fact-cards** (`docs/memory/facts/`) — distilled, provenance-linked atomic facts, written by the distiller (`facts` mode) from inbox entries and resurfaced at prompt time by the `prompt-recall` hook.
250
- - **This index** — the curated read tier: the learnings list below, distilled from the colder tiers and hand-appended.
251
-
252
233
  ## Learnings
253
234
 
254
235
  {Agents append learnings here as they discover gotchas, patterns, and architecture notes}
@@ -278,15 +259,13 @@ Append entries below, oldest at bottom. Format:
278
259
  Memory file initialized during documentation baseline.
279
260
  ```
280
261
 
281
- > The per-actor memory **inbox** (`docs/memory/inbox/`) is _not_ a baseline scaffold — the `session-reflect` hook creates it mechanically on the first reflected session. See **§11 Memory inbox entry** for its format.
282
-
283
262
  ---
284
263
 
285
- ## 5. Feature Documentation (docs/features/{feature}.md)
264
+ ## 5. Feature Documentation — the LLD (docs/features/{feature}.md)
286
265
 
287
- Use for: every feature in `docs/features/`. The same file persists from design (Status: Draft) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap.
266
+ Use for: every feature in `docs/features/`. The feature doc is the feature's **LLD (low-level design)**: the same file persists from design (Status: Draft, written in LLD Mode) through implementation to live reference (Status: Active). Sections fill in as the feature matures — no template swap.
288
267
 
289
- The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to spec-mode's return shape. The orchestrator drops spec-mode's findings into those slots without restructuring.
268
+ The four research-derived sections (**Affected Modules**, **Conventions to Follow**, **Current Behavior**, **Ownership Conflicts**) map 1:1 to the `lld-mode` agent's return shape. The orchestrator drops its findings into those slots without restructuring.
290
269
 
291
270
  ```yaml
292
271
  ---
@@ -294,8 +273,6 @@ owns: ["src/feature/**", "src/other/file.ts"] # required — code-path globs t
294
273
  module: billing # optional — single bounded-context label; omit if cross-cutting
295
274
  keywords: [invoice, pdf] # required — discovery terms
296
275
  status: active # required — active | draft | deprecated
297
- anchors: # optional extra — a qmd drift tripwire; see §3
298
- - "qmd query: wire envelope invariants"
299
276
  ---
300
277
  ```
301
278
 
@@ -332,22 +309,22 @@ High-level shape of the solution. ASCII diagram if it helps. Implementation spec
332
309
 
333
310
  ## Affected Modules
334
311
 
335
- (From spec-mode research) Files, routes, components, slices this feature involves. Group by module.
312
+ (From lld-mode research) Files, routes, components, slices this feature involves. Group by module.
336
313
 
337
314
  | Module | Path | Role in this feature |
338
315
  |--------|------|----------------------|
339
316
 
340
317
  ## Conventions to Follow
341
318
 
342
- (From spec-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.
319
+ (From lld-mode research) Naming patterns, structural patterns, doc-fit heuristics confirmed for the area being touched. Cite the source file(s) where the convention is established.
343
320
 
344
321
  ## Current Behavior
345
322
 
346
- (From spec-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.
323
+ (From lld-mode research) How the relevant part of the system works *today*, before this feature lands. Without this baseline the design intent is hard to evaluate.
347
324
 
348
325
  ## Ownership Conflicts
349
326
 
350
- (From spec-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
327
+ (From lld-mode research) Existing feature docs whose `owns:` globs overlap with the projected scope. Resolve before the plan starts — leave nothing unresolved.
351
328
 
352
329
  | Conflicting doc | Overlapping path(s) | Resolution |
353
330
  |-----------------|---------------------|------------|
@@ -426,7 +403,7 @@ Sections fill in across the feature's lifecycle. No template swap — they accum
426
403
  | When | Sections written | Source |
427
404
  | --- | --- | --- |
428
405
  | Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
429
- | Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | spec-mode agent |
406
+ | Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | lld-mode agent |
430
407
  | Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; `owns:` globs confirmed against real code | Main agent (from actual code) |
431
408
 
432
409
  Resolved Open Questions can be summarized into Background; unresolved ones stay visible.
@@ -807,47 +784,3 @@ The full surface lives in [`{path/to/public-index}`]({path/to/public-index}).
807
784
  The baseline audit **does** scaffold the project root README when missing. The risk this template guards against — template-shaped placeholders that look abandoned — is mitigated by the writing rules above: fill every section with concrete details from the repo (real package manager from the lockfile, real scripts, real layout, real status). Skip sections that genuinely don't apply rather than leaving stubs.
808
785
 
809
786
  **Never overwrite an existing root README** during a baseline. If one is present — even sparse or outdated — leave it untouched. Treat updates to a pre-existing root README as a separate, explicit request.
810
-
811
- ---
812
-
813
- ## 11. Memory inbox entry (docs/memory/inbox/{actor}.md)
814
-
815
- Use for: the capture tier of the knowledge gradient — the durable lessons of each session (corrections, root-caused failures, decisions with rationale, discovered constraints), reflected by the `session-reflect` hook at session end. It is the raw input to distillation: `distiller facts` digests entries into fact-cards and **consumes** them, so the file holds exactly what is undigested.
816
-
817
- ### File grain
818
-
819
- One file **per actor**: `docs/memory/inbox/{actor}.md`. `actor` is `git config user.name` lowercased and kebab-slugged; fall back to `$USER`, then `agent`. Two actors write to different files, so the inbox is **append-only without merge conflicts** — no shared file to contend over, no lock, no last-writer-wins.
820
-
821
- ### File header
822
-
823
- Written once, on the first entry:
824
-
825
- ```
826
- # Memory inbox — {actor}
827
- Session lessons awaiting distillation — appended by the session-reflect hook, consumed by `distiller facts`.
828
- ```
829
-
830
- ### Entry shape
831
-
832
- One block per reflected session, at most 6 bullets. Each bullet is one complete, self-contained sentence tagged `[project]` (true of the repo or its tooling) or `[user]` (true of the user) — the tag routes it at distillation: project facts → `docs/memory/facts/`, user facts → user-level memory.
833
-
834
- ```
835
- ## YYYY-MM-DD HH:MM · session <id> · {repo}@{branch}
836
- - [project] <one self-contained sentence, names and identifiers spelled out>
837
- - [user] <one self-contained sentence>
838
- ```
839
-
840
- ### Examples
841
-
842
- ```
843
- ## 2026-06-08 22:26 · session bc06c4fc · etna@dev
844
- - [project] The read_network_requests Chrome CDP tool only captures after its first call — arm it, trigger traffic, then read.
845
- - [user] jane-doe prefers minimal fixes over defensive machinery; fail loudly instead of engineering around a problem.
846
- ```
847
-
848
- ### Rules
849
-
850
- - **Hooks append, the distiller consumes.** A digested entry block is deleted by `distiller facts`; nothing else edits or reorders the file. A human may hand-append a lesson in the same shape — it rides the same queue.
851
- - **Sessions are deduped by id.** The reflect hook skips a session whose id already appears in the file (SessionEnd re-fires on resume).
852
- - **Secrets are redacted on write.** The privacy filter replaces secret shapes with `[redacted:{kind}]` (e.g. `[redacted:api-key]`, `[redacted:bearer]`, `[redacted:pem]`) before any line is appended — never paste a raw token in by hand either.
853
- - **Don't curate here.** Promotion to fact-cards and `docs/memory/main.md` happens at distillation; the inbox stays a transient queue.
@@ -20,20 +20,20 @@ This file defines how AI agents (Claude, GPT, etc.) should work on this project.
20
20
 
21
21
  ## Workflows
22
22
 
23
- For new features or new systems, enter **Spec Mode** before Plan Mode.
23
+ For new features or new systems, enter **LLD Mode** (low-level design) before Plan Mode.
24
24
 
25
- ### Spec Mode → Plan Mode → Completion
25
+ ### LLD Mode → Plan Mode → Completion
26
26
 
27
- 1. **Spec Mode**: Create or update a feature spec in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see `.claude/skills/documentation/references/templates.md` §6. Use the **`spec-mode`** agent (`.claude/agents/spec-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the spec for approval before proceeding.
27
+ 1. **LLD Mode**: Create or update the feature LLD in `docs/features/{feature}.md` using the **Feature Documentation template** (Status: Draft) — see `.claude/skills/documentation/references/templates.md` §6. Use the **`lld-mode`** agent (`.claude/agents/lld-mode.md`) for codebase research; its findings drop directly into the template's research-derived sections (Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts). Interview the user for the design-intent sections (Goal, Goals & Non-Goals, Background, Approach). Present the LLD for approval before proceeding.
28
28
 
29
- 2. **Plan Mode**: Once the spec is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature spec in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill parses them to check boundary impact.
29
+ 2. **Plan Mode**: Once the LLD is approved, create a plan in `docs/history/plans/YYYY-MM-DD-feature-name.md` using the **Plan template** (see `.claude/skills/documentation/references/templates.md` §8). Link back to the feature LLD in the **Spec** field. The template's **Proposed Changes** sections are load-bearing — the `boundary` skill parses them to check boundary impact.
30
30
 
31
31
  3. **Completion**: When a plan is fully implemented:
32
32
  - Mark the plan `Status: Complete` in `docs/history/plans/` and fill the **Completed:** date. The plan is now frozen.
33
- - **Flip the feature spec** to `status: active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm the feature's `owns:` globs against actual code; resolve any unresolved Open Questions by folding them into Background.
33
+ - **Flip the feature LLD** to `status: active` and extend it in place with the implementation sections (Architecture, Key Functions, State, Redux, Files). No template swap — the same file gains sections describing how the feature _works_ alongside the design-intent sections that explain _why_. Confirm the feature's `owns:` globs against actual code; resolve any unresolved Open Questions by folding them into Background.
34
34
  - Use the injected ownership index to find other docs affected by the changes (and update the `owns:` globs of any feature doc whose source you moved or added). Update affected docs — or create new ones if a touched area has no doc yet.
35
35
 
36
- For **Product-level** work (new systems, unclear scope), the spec should also include: problem statement, key hypotheses, and open questions.
36
+ For **Product-level** work (new systems, unclear scope), the LLD should also include: problem statement, key hypotheses, and open questions.
37
37
 
38
38
  `docs/features/` is _what_ we're building (lives on as documentation). `docs/history/plans/` is _how_ we built it (historical record).
39
39
 
@@ -42,9 +42,8 @@ For **Product-level** work (new systems, unclear scope), the spec should also in
42
42
  Before modifying code in an unfamiliar area:
43
43
 
44
44
  1. Consult the **injected ownership index** — the generated `glob → doc · module · keywords · status` map, surfaced into context at session start (the union of every feature doc's `owns:` frontmatter). Match your path or topic (its `keywords:`) to the owning doc and read it before changes. (If no ownership index appears in context, the repo isn't reconciled — run `maintenance` in baseline mode to reconcile it.)
45
- 2. If `qmd` is installed, run `qmd query --format json -c <collection> "<topic>"` for semantic recall over the indexed docs — prefer it when entering an unfamiliar area; absent ⇒ skip.
46
- 3. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
47
- 4. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
45
+ 2. If your change touches a cross-cutting contract area (entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config), run the **`boundary`** skill scoped to your change — it reads both sides of each touched contract in source and reports what would break.
46
+ 3. If a `docs/memory/` file exists for the domain you're working in, read it for domain knowledge and failure modes
48
47
 
49
48
  For the protocol on _writing_ to memory (which file, what belongs there, what doesn't), see **Project Memory** below.
50
49
 
@@ -72,9 +71,9 @@ When implementing a plan, if you discover work that is important but outside the
72
71
 
73
72
  ### Doc Ownership
74
73
 
75
- Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures. A living doc may additionally carry an optional `anchors:` block (a qmd drift tripwire, not ownership).
74
+ Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. Architecture docs describe cross-cutting patterns and don't own specific files; operations docs describe procedures.
76
75
 
77
- The spec-mode agent checks for ownership conflicts during research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the spec before proceeding.
76
+ The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. If conflicts are found, address them in the LLD before proceeding.
78
77
 
79
78
  ---
80
79
 
@@ -82,7 +81,7 @@ The spec-mode agent checks for ownership conflicts during research — feature d
82
81
 
83
82
  A boundary is a horizontal cross-cutting contract — entity model, db schema, wire envelope, auth/authz, event vocabulary, webhooks, env/config — where editing one side silently breaks the other. Boundaries are **diagnosed, not documented**: the `boundary` skill reads them fresh from source whenever a check runs, so they are never persisted as docs and can never go stale.
84
83
 
85
- **Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/boundary-taxonomy.md` is the catalog), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
84
+ **Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source files, identifies the contracts they participate in (its `references/mechanisms.md` defines the failure mechanisms; technology packs under `references/packs/` carry stack specifics), traces the consumers on the other side, and reports severity-ranked violations with suggested plan amendments — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code, run the same diagnostic scoped to the diff.
86
85
 
87
86
  > Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here.
88
87
 
@@ -1,33 +1,33 @@
1
1
  ---
2
- name: spec-mode
3
- description: Specification researcher for Feature and Product workflows. Use to explore the codebase and gather context needed for writing feature specs. Returns research findings — does not write files.
2
+ name: lld-mode
3
+ description: LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files.
4
4
  tools: Read, Glob, Grep, WebSearch, WebFetch
5
5
  model: inherit
6
6
  skills:
7
7
  - documentation
8
8
  ---
9
9
 
10
- # Spec Mode Agent
10
+ # LLD Mode Agent
11
11
 
12
- You are a specification researcher. Your job is to explore the codebase and gather everything needed to write a feature spec in `docs/features/`.
12
+ You are an LLD researcher. Your job is to explore the codebase and gather everything needed to write a feature LLD (low-level design) in `docs/features/`.
13
13
 
14
- You do NOT write the spec — you return structured research that the main agent uses to write it.
14
+ You do NOT write the LLD — you return structured research that the main agent uses to write it.
15
15
 
16
16
  ## Before Starting
17
17
 
18
18
  First, understand the documentation landscape:
19
19
 
20
20
  1. Read `./docs/structure.md` to understand the documentation structure
21
- 2. If `./docs/features/README.md` exists, read it to see existing feature specs and where the new spec fits; otherwise glob the feature docs directly
22
- 3. If `./docs/memory/spec-mode.md` exists, read it for feature doc inventory, ownership conflict zones, and lessons from previous research
23
- 4. Read 1-2 existing specs in `./docs/features/` to calibrate format and depth
21
+ 2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
22
+ 3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
23
+ 4. Read 1-2 existing feature LLDs in `./docs/features/` to calibrate format and depth
24
24
  5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. This is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
25
25
 
26
- This tells you what already exists, what's adjacent, how detailed the spec should be, and what code paths are already owned.
26
+ This tells you what already exists, what's adjacent, how detailed the LLD should be, and what code paths are already owned.
27
27
 
28
28
  ## What You Research
29
29
 
30
- 1. **Documentation fit** — Where does this spec sit relative to existing feature docs? Does it extend an existing spec or need a new one?
30
+ 1. **Documentation fit** — Where does this LLD sit relative to existing feature docs? Does it extend an existing one or need a new doc?
31
31
  2. **Existing patterns** — Find related features, similar implementations, and conventions in the codebase
32
32
  3. **Affected modules** — Identify what files, routes, components, and data flows are relevant
33
33
  4. **Current state** — Understand how the system works today in the area being specified
@@ -38,13 +38,13 @@ This tells you what already exists, what's adjacent, how detailed the spec shoul
38
38
 
39
39
  Structure your findings as:
40
40
 
41
- - **Documentation context**: Existing specs that relate, whether to create new or update existing, suggested filename
41
+ - **Documentation context**: Existing feature LLDs that relate, whether to create new or update existing, suggested filename
42
42
  - **Related patterns**: What similar things exist in the codebase and where
43
43
  - **Affected modules**: Files, routes, components that will be involved
44
44
  - **Current behavior**: How the relevant part of the system works today
45
45
  - **Conventions**: Naming, structure, and patterns to follow based on existing code
46
46
  - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
47
- - **Risks or concerns**: Anything the spec should address or call out
47
+ - **Risks or concerns**: Anything the LLD should address or call out
48
48
 
49
49
  Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.
50
50
 
@@ -108,20 +108,6 @@ For unowned code paths:
108
108
  1. Update `docs/structure.md` Health Log with today's date and summary.
109
109
  2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
110
110
  3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
111
- 4. **Inbox-distillation threshold.** Count undigested inbox entries — `## ` entry blocks across `docs/memory/inbox/*.md` (the inbox is consume-on-digest, so every block present is undigested). If the count is **≥5**, add one line to the report **proposing** a `distiller facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence _is_ the dedupe, so never backlog it.
112
- 5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance ∩ the doc's `owns:` globs strong, entities ∩ declared ownership supporting — qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined or ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence _is_ the dedupe, so never backlog the proposal.
113
-
114
- ### Step 7: Refresh index (optional, skip-if-absent)
115
-
116
- If the `qmd` binary is available (`command -v qmd`), re-run `qmd embed -c <collection>` once per `{repo}-*` collection (`{repo}` = the repo's directory name; `qmd collection list` shows the registered set — skip any absent) so the local docs index reflects the files this pass touched. Scope every run with `-c` — the qmd index is global (`~/.cache/qmd/` holds every repo's collections), so a bare `qmd embed` would re-embed unrelated repos' collections. If `qmd` is absent, skip silently — it's never required.
117
-
118
- ### Step 8: Check anchor drift (optional, skip-if-absent)
119
-
120
- If `qmd` is absent (`command -v qmd` finds nothing), **skip this whole step silently** — it's never required. `anchors:` is a qmd-only tooling key; with no qmd it is inert.
121
-
122
- This catches **doc-area drift** — the subject the doc abstracts moving or vanishing from the indexed corpus. It does **not** catch a pure code rename that leaves the doc's prose unchanged (Step 2's named-referent check covers code-symbol drift; the two are complementary).
123
-
124
- Glob `docs/features/**/*.md`, `docs/architecture/**/*.md`, and `docs/operations/**/*.md` for docs carrying `anchors:` frontmatter. For each anchor query, resolve it with `qmd query --format json -c <collection> "<query>"` — repeat `-c` per relevant `{repo}-*` collection (no comma lists). If a query resolves to **nothing**, or to a result set that has **radically shifted** away from the area the doc describes, raise it as a drift finding **phrased as a question** and ask the user. On **yes**, dispatch the remediation sub-agent (the same yes-branch as Step 5). On **decline or no action**, append it to `docs/history/backlog.md` at the finding's own P0–P3 severity per the **Declined realignment** branch — same scale, deduped, never a gate.
125
111
 
126
112
  ---
127
113
 
@@ -148,7 +134,7 @@ docs/
148
134
  │ ├── changelog/ # Individual entries
149
135
  │ ├── plans/ # Implementation plans (Status field required)
150
136
  │ └── backlog.md # Tracked work items by priority (P0-P3)
151
- ├── memory/ # inbox/ (captured-lessons queue), facts/ (distilled cards), index.md, main.md, {agent}.md
137
+ ├── memory/ # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
152
138
  └── tests/ # Optional, author-maintained — create only if test docs exist
153
139
  ```
154
140
 
@@ -189,26 +175,11 @@ Scaffold missing mandated files **by calling the `documentation` skill for each
189
175
 
190
176
  - `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
191
177
 
192
- Scaffold `docs/memory/facts/` so the distilled tier has a home from day one: the `session-reflect` hook appends session lessons to the per-actor inbox at `docs/memory/inbox/{actor}.md` (not a scaffold — created mechanically on first reflection), and the `distiller` digests that queue down into fact-cards under `docs/memory/facts/`, consuming the entries it digests.
193
-
194
178
  ### Step B4 — Stamp the version
195
179
 
196
180
  Write `harness-version: <installed version>` (the semver from `.claude/harness.json`) into `docs/structure.md` frontmatter. This single field is the repo's baseline-and-version sentinel — there is no second marker (no `epoch`, no `docs/memory/index.md` "is-baselined" check).
197
181
 
198
- ### Step B5 — Register the qmd retrieval lens (optional, skip-if-absent)
199
-
200
- Strictly optional and guarded on the binary — if `command -v qmd` finds nothing, **skip this entire step silently** (no error, no behavior change) and carry one advisory line into the hand-back: _"qmd not installed — semantic retrieval unavailable; the generated ownership index + `keywords:` discovery are active."_ The index is a **local rebuildable lens** — data stays in git; never commit index artifacts, and never use `qmd init` (the default global index keeps the repo clean).
201
-
202
- If the binary exists, register the docs subtrees once the tree is scaffolded. **Do not register one collection rooted at `docs/`** — qmd hard-codes the `**/*.md` pattern and has no exclude flag, so a `docs/`-root collection would sweep the consumable inbox queue at `docs/memory/inbox/` into the index (the inbox's entries are deleted on digestion, leaving dangling index entries). Register **per indexable subtree** (skip absent ones; `{repo}` = the repo's directory name; an existing name/path no-ops — treat as success):
203
-
204
- - `qmd collection add docs/features --name {repo}-features`
205
- - `qmd collection add docs/architecture --name {repo}-architecture`
206
- - `qmd collection add docs/operations --name {repo}-operations`
207
- - `qmd collection add docs/memory/facts --name {repo}-facts` (never `docs/memory` as a whole)
208
-
209
- Then `qmd context add` per registered collection and `qmd embed -c <name>` per collection (always scope with `-c`; a bare `qmd embed` re-embeds every repo's collections). This augments discovery; it never supersedes the `owns:`-glob ownership resolution.
210
-
211
- ### Step B6 — Module proposal
182
+ ### Step B5 — Module proposal
212
183
 
213
184
  Modules are **labels, declared, never inferred from physical layout**. Derive the repo's candidate bounded contexts directly from the code and docs: distinct wire surfaces (who owns routes/handlers), schema/data-access ownership, entry points and process units, plus any contexts `docs/architecture/` already names.
214
185
 
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "harness": "etna",
3
3
  "name": "etna",
4
- "version": "1.0.2",
4
+ "version": "1.1.1",
5
5
  "files": [
6
6
  ".prettierrc.json",
7
7
  ".prettierignore",
8
8
  ".vscode/settings.json"
9
9
  ],
10
- "digest": "9447b8703853"
10
+ "digest": "018554d4192f"
11
11
  }
@@ -11,29 +11,6 @@
11
11
  }
12
12
  ]
13
13
  }
14
- ],
15
- "SessionEnd": [
16
- {
17
- "matcher": "",
18
- "hooks": [
19
- {
20
- "type": "command",
21
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-reflect.mjs\"",
22
- "async": true
23
- }
24
- ]
25
- }
26
- ],
27
- "UserPromptSubmit": [
28
- {
29
- "matcher": "",
30
- "hooks": [
31
- {
32
- "type": "command",
33
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-recall.mjs\""
34
- }
35
- ]
36
- }
37
14
  ]
38
15
  }
39
16
  }