@nurix/etna 0.10.1 → 0.13.0

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 (35) hide show
  1. package/data/harnesses/code/CLAUDE.md +22 -13
  2. package/data/harnesses/code/agents/brainstorm.md +3 -3
  3. package/data/harnesses/code/agents/change-review.md +190 -21
  4. package/data/harnesses/code/agents/harness-manager.md +22 -12
  5. package/data/harnesses/code/agents/maintenance.md +5 -31
  6. package/data/harnesses/code/agents/performance-review.md +219 -0
  7. package/data/harnesses/code/agents/spec-mode.md +1 -1
  8. package/data/harnesses/code/skills/boundary/SKILL.md +245 -0
  9. package/data/harnesses/code/skills/boundary/references/boundary-taxonomy.md +666 -0
  10. package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/README.md +14 -14
  11. package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/SKILL.md +14 -14
  12. package/data/harnesses/code/skills/documentation/SKILL.md +4 -4
  13. package/data/harnesses/code/skills/documentation/references/templates.md +7 -25
  14. package/package.json +1 -1
  15. package/data/harnesses/code/agents/boundary-mapper.md +0 -114
  16. package/data/harnesses/code/agents/contract-monitor.md +0 -66
  17. package/data/harnesses/code/agents/dep-health.md +0 -149
  18. package/data/harnesses/code/agents/git-history.md +0 -202
  19. package/data/harnesses/code/agents/review.md +0 -110
  20. package/data/harnesses/code/scripts/build-ownership-index.sh +0 -148
  21. package/data/harnesses/code/scripts/check-doc-drift.sh +0 -135
  22. package/data/harnesses/code/skills/introspect/SKILL.md +0 -136
  23. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/greenfield.md +0 -0
  24. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/backlog.md +0 -0
  25. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/decisions.md +0 -0
  26. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/doctrine.md +0 -0
  27. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/glossary.md +0 -0
  28. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/inventory.md +0 -0
  29. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/milestones.md +0 -0
  30. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/non-goals.md +0 -0
  31. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/plan-doc.md +0 -0
  32. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/questions.md +0 -0
  33. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/references.md +0 -0
  34. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/rejected.md +0 -0
  35. /package/data/harnesses/code/skills/{technical-brainstorm → brainstorm}/templates/state.md +0 -0
@@ -1,4 +1,4 @@
1
- # technical-brainstorm
1
+ # brainstorm
2
2
 
3
3
  A Claude Code skill for **structured design of unbuilt software**. It enforces a deliberate plan-before-code phase, captures decisions and open questions in a persistent registry of pillar documents, and refuses to write production code while a session is open.
4
4
 
@@ -15,7 +15,7 @@ The default failure mode of an AI assistant on a fresh problem is to **start typ
15
15
  - Architecture that drifts because no one tracked the "why".
16
16
  - Re-work when the next session forgets context the previous one had.
17
17
 
18
- `technical-brainstorm` inverts this. While a session is open, the skill behaves as a **design facilitator** — not a coder. It asks structured questions, records answers into named files, and uses a state file (`state.md`) to remember across conversations whether a session is active. Code authoring is **blocked** outside the brainstorm folder; small load-bearing snippets are allowed only as illustration inside it.
18
+ `brainstorm` inverts this. While a session is open, the skill behaves as a **design facilitator** — not a coder. It asks structured questions, records answers into named files, and uses a state file (`state.md`) to remember across conversations whether a session is active. Code authoring is **blocked** outside the brainstorm folder; small load-bearing snippets are allowed only as illustration inside it.
19
19
 
20
20
  The output is not a single document. It is a **registry** — nine pillar files plus numbered plan docs — that survives across sessions and stays load-bearing because every entry has a *why*.
21
21
 
@@ -46,7 +46,7 @@ When the skill detects a bad fit during qualification, it asks the user before e
46
46
  In this repo (`etna`), the skill lives at:
47
47
 
48
48
  ```
49
- store/skills/technical-brainstorm/
49
+ store/skills/brainstorm/
50
50
  ├── SKILL.md # The skill definition Claude Code loads.
51
51
  ├── README.md # This file.
52
52
  ├── greenfield.md # Writing doctrine for greenfield architecture docs.
@@ -66,9 +66,9 @@ store/skills/technical-brainstorm/
66
66
 
67
67
  To use the skill in a project, place the folder at one of:
68
68
 
69
- - `~/.claude/skills/technical-brainstorm/` (user-wide install)
70
- - `<project>/.claude/skills/technical-brainstorm/` (project-scoped install)
71
- - A plugin under `<project>/plugins/<plugin>/skills/technical-brainstorm/`
69
+ - `~/.claude/skills/brainstorm/` (user-wide install)
70
+ - `<project>/.claude/skills/brainstorm/` (project-scoped install)
71
+ - A plugin under `<project>/plugins/<plugin>/skills/brainstorm/`
72
72
 
73
73
  Claude Code loads any skill whose `SKILL.md` it can discover via its standard skill resolution.
74
74
 
@@ -79,8 +79,8 @@ Claude Code loads any skill whose `SKILL.md` it can discover via its standard sk
79
79
  The skill exposes exactly two subcommands. Everything else happens **within** an active session as natural conversation.
80
80
 
81
81
  ```
82
- /technical-brainstorm start # open a session
83
- /technical-brainstorm close # close a session
82
+ /brainstorm start # open a session
83
+ /brainstorm close # close a session
84
84
  ```
85
85
 
86
86
  There is no `sweep`, `check`, `resolve`, `init`, or `reinforce` subcommand. The skill reads `state.md` at the start of every turn to decide whether a session is open, and adapts behavior accordingly.
@@ -165,7 +165,7 @@ The skill refuses to write production code (in `src/`, `apps/`, `packages/`, etc
165
165
 
166
166
  If the user asks for production code, the skill says:
167
167
 
168
- > "We're in an active brainstorm session. I can sketch this inside `./plan/` as illustration, or you can run `/technical-brainstorm close` first if you want to start building. Which do you want?"
168
+ > "We're in an active brainstorm session. I can sketch this inside `./plan/` as illustration, or you can run `/brainstorm close` first if you want to start building. Which do you want?"
169
169
 
170
170
  ### `close` — closing a session
171
171
 
@@ -180,7 +180,7 @@ If the user asks for production code, the skill says:
180
180
  4. Ask whether to address them now or close anyway.
181
181
  5. On confirmation, write `STATE: closed` to `state.md` with a one-line reason (milestone reached / paused / scope cut / handing off).
182
182
  6. If `./plan/sources/` exists, offer to delete it. Default to keep if unclear — they were copies; originals are untouched.
183
- 7. Print: "Run `/technical-brainstorm start` to resume."
183
+ 7. Print: "Run `/brainstorm start` to resume."
184
184
 
185
185
  ---
186
186
 
@@ -232,7 +232,7 @@ LAST UPDATED: <ISO date>
232
232
  ```
233
233
 
234
234
  - `STATE: open` → in-session behavior applies (voices, refusal rules, topic-shift prompts).
235
- - `STATE: closed` → the skill does nothing on its own; only `/technical-brainstorm start` re-opens it.
235
+ - `STATE: closed` → the skill does nothing on its own; only `/brainstorm start` re-opens it.
236
236
  - `CURRENT TOPIC` updates on every detected topic shift.
237
237
  - `LAST UPDATED` updates on every pillar write.
238
238
 
@@ -264,7 +264,7 @@ A few choices in this skill are deliberate and worth naming:
264
264
 
265
265
  **Why** is load-bearing. Every decision and every piece of feedback-style guidance carries a *why*. Without it, future-you can't judge edge cases — only blindly follow or blindly violate the rule.
266
266
 
267
- **The user prevents eager coding.** The skill is the assistant. The user controls when a session opens and closes. There is no "auto-open on natural language phrases like let's design" — that pattern has caused too many surprise refusals when the user just wanted to chat. The skill opens only on explicit `/technical-brainstorm start`.
267
+ **The user prevents eager coding.** The skill is the assistant. The user controls when a session opens and closes. There is no "auto-open on natural language phrases like let's design" — that pattern has caused too many surprise refusals when the user just wanted to chat. The skill opens only on explicit `/brainstorm start`.
268
268
 
269
269
  **Reference implementations beat invented solutions.** If prior art exists for the problem, the skill prefers a one-line link in `references.md` over a re-derivation. Originality is not a virtue when shipping is the goal.
270
270
 
@@ -272,7 +272,7 @@ A few choices in this skill are deliberate and worth naming:
272
272
 
273
273
  ## Anti-features (what this skill deliberately doesn't do)
274
274
 
275
- - **No auto-invocation on natural language.** Phrases like "let's plan", "let's design", "let's think through X" do **not** trigger the skill. Only explicit `/technical-brainstorm start` and `/technical-brainstorm close` do.
275
+ - **No auto-invocation on natural language.** Phrases like "let's plan", "let's design", "let's think through X" do **not** trigger the skill. Only explicit `/brainstorm start` and `/brainstorm close` do.
276
276
  - **No automatic semantic sweeps.** Sweeps run only when the user asks or when the skill recommends one after a major decision and the user agrees.
277
277
  - **No scheduled checkpoints.** Pillar reinforcement happens at natural topic boundaries — the only periodic prompt.
278
278
  - **No subcommand sprawl.** No `sweep`, `resolve`, `init`, `reinforce`, `check`. Two verbs total: `start` and `close`.
@@ -284,4 +284,4 @@ A few choices in this skill are deliberate and worth naming:
284
284
 
285
285
  - `greenfield.md` — writing doctrine for unbuilt-software docs.
286
286
  - `templates/` — pillar file templates, each with a prose introduction describing its format.
287
- - The `documentation` skill in this repo handles documentation of *built* systems (changelogs, ADRs, root READMEs). `technical-brainstorm` is its before-the-fact counterpart.
287
+ - The `documentation` skill in this repo handles documentation of *built* systems (changelogs, ADRs, root READMEs). `brainstorm` is its before-the-fact counterpart.
@@ -1,11 +1,11 @@
1
1
  ---
2
- name: technical-brainstorm
3
- description: Structured planning/design session for software that hasn't been built yet. Invoked ONLY by explicit slash commands `/technical-brainstorm start` and `/technical-brainstorm stop`. Do NOT auto-invoke on natural-language phrases like "let's plan", "let's design", "let's think through X", or any other phrasing — those are not triggers. The skill maintains 10 pillar documents (questions, decisions, doctrine, glossary, inventory, non-goals, references, rejected, milestones, backlog) inside a `pillars/` subfolder, plus a top-level `state.md` tracking session open/closed AND the active mode (explore / decide / step-back). Refuses to write production code outside the brainstorm folder while a session is active.
2
+ name: brainstorm
3
+ description: Structured planning/design session for software that hasn't been built yet. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop`. Do NOT auto-invoke on natural-language phrases like "let's plan", "let's design", "let's think through X", or any other phrasing — those are not triggers. The skill maintains 10 pillar documents (questions, decisions, doctrine, glossary, inventory, non-goals, references, rejected, milestones, backlog) inside a `pillars/` subfolder, plus a top-level `state.md` tracking session open/closed AND the active mode (explore / decide / step-back). Refuses to write production code outside the brainstorm folder while a session is active.
4
4
  argument-hint: "start | stop"
5
5
  plugins: [nurix-harness]
6
6
  ---
7
7
 
8
- # Technical Brainstorm
8
+ # Brainstorm
9
9
 
10
10
  Plan and design before building. While a session is active, capture concerns, hypotheses, and decisions into a registry of pillar documents that survives across conversations.
11
11
 
@@ -15,8 +15,8 @@ The user's job is to prevent eager coding. The skill's job is to make the planni
15
15
 
16
16
  ## Two subcommands. That's it.
17
17
 
18
- - `/technical-brainstorm start` — open a session
19
- - `/technical-brainstorm stop` — stop a session
18
+ - `/brainstorm start` — open a session
19
+ - `/brainstorm stop` — stop a session
20
20
 
21
21
  Everything else happens **within** an active session, as natural conversation. There is no `sweep`, `check`, `resolve`, `init`, `reinforce`, `commit`, or `rescind` subcommand. The skill behaves correctly without ceremony — it reads `state.md` on every turn to know whether a session is open and what mode it is in, and adapts its voice and tool-use posture accordingly.
22
22
 
@@ -24,7 +24,7 @@ Everything else happens **within** an active session, as natural conversation. T
24
24
 
25
25
  ### Persistent pillars vs. session workspace (v9)
26
26
 
27
- In a v9-harnessed repo there is **no repo-wide `docs/pillars/`**. The persistent home of pillars is **dispersed by scope**: module-local doctrine / glossary / decisions live in each `docs/modules/{m}/pillars/`, and cross-module steering lives in `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `references.md`, `open-questions.md`). A change to the information architecture is captured as the `domain` boundary in `docs/boundaries/` (owned by the `boundary-mapper` agent, not written here).
27
+ In a v9-harnessed repo there is **no repo-wide `docs/pillars/`**. The persistent home of pillars is **dispersed by scope**: module-local doctrine / glossary / decisions live in each `docs/modules/{m}/pillars/`, and cross-module steering lives in `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `references.md`, `open-questions.md`). A change to the information architecture is captured as the `domain` boundary in `docs/boundaries/` (owned by the `boundary` skill, not written here).
28
28
 
29
29
  Each brainstorming session still opens a **transient working copy** at `./brainstorm/pillars/` (repo root, not inside `docs/`) holding all ten pillar files — **that workspace and its templates are unchanged from v8**. On `/start` the working copy is *primed* from whatever dispersed v9 homes already exist (read the module pillars + the `docs/architecture/` steering files). The conversation mutates the working copy. On `/stop`, the harvest diffs the session pillars against the live docs and writes each change back **by scope** (see Harvest destinations in `## stop` below).
30
30
 
@@ -313,7 +313,7 @@ The session is now in **Explore mode**. Resolution-style flows are opt-in from h
313
313
 
314
314
  6. **Refuse close on tentative (v8).** If step 4 didn't resolve every `STATUS: tentative` decision (commit / rescind / convert-to-backlog), block close and return to the conversation. Harvest does not run with unresolved tentatives.
315
315
 
316
- 7. **Harvest into the v9 doc tree.** The harvest is a structured diff between the session pillars (`./brainstorm/pillars/*`) and the live docs, **routed by scope** — module-local findings to `docs/modules/{m}/pillars/`, cross-module to `docs/architecture/`, IA/contract changes to `docs/boundaries/` (via `boundary-mapper`), backlog to `docs/history/`. There is no single target and no repo-wide `docs/pillars/`. For each kind of mutation, write to the matching destination:
316
+ 7. **Harvest into the v9 doc tree.** The harvest is a structured diff between the session pillars (`./brainstorm/pillars/*`) and the live docs, **routed by scope** — module-local findings to `docs/modules/{m}/pillars/`, cross-module to `docs/architecture/`, IA/contract changes to `docs/boundaries/` (via the `boundary` skill), backlog to `docs/history/`. There is no single target and no repo-wide `docs/pillars/`. For each kind of mutation, write to the matching destination:
317
317
 
318
318
  | Session source | v9 destination(s) |
319
319
  |---|---|
@@ -321,24 +321,24 @@ The session is now in **Explore mode**. Resolution-style flows are opt-in from h
321
321
  | `./brainstorm/pillars/glossary.md` | module-local → `docs/modules/{m}/pillars/glossary.md`; cross-module → `docs/architecture/glossary.md` |
322
322
  | `./brainstorm/pillars/non-goals.md` | `docs/architecture/non-goals.md` |
323
323
  | `./brainstorm/pillars/references.md` | `docs/architecture/references.md` |
324
- | `./brainstorm/pillars/inventory.md` | `docs/architecture/` (and regenerate `docs/OWNERSHIP_INDEX.md` if subsystems changed) |
324
+ | `./brainstorm/pillars/inventory.md` | `docs/architecture/` |
325
325
  | Committed decisions (`STATUS: committed` in `./brainstorm/pillars/decisions.md`) | 2+-module → new `docs/architecture/adr/NNN-{slug}.md` (one ADR per cohesive theme); module-local → `docs/modules/{m}/pillars/decisions.md`. Rejected alternatives flow to ADR §Alternatives. |
326
- | IA / entity-model change, or a new cross-cutting contract, surfaced by a committed decision | the `domain` boundary `docs/boundaries/information-architecture.md` (or a new typed boundary) — **flag for the `boundary-mapper` agent; don't hand-write the boundary file** |
326
+ | IA / entity-model change, or a new cross-cutting contract, surfaced by a committed decision | the `domain` boundary `docs/boundaries/information-architecture.md` (or a new typed boundary) — **flag for the `boundary` skill (`create`); don't hand-write the boundary file** |
327
327
  | `./brainstorm/pillars/backlog.md` (new items) | `docs/history/backlog.md` (P0–P3, full operational tracking) |
328
328
  | `./brainstorm/pillars/rejected.md` | ADR §Alternatives when tied to a committed decision; else `docs/modules/{m}/pillars/rejected.md` |
329
329
  | `./brainstorm/pillars/milestones.md` | `docs/architecture/` (mirror in `docs/structure.md §Health log` if the milestone is a structural change) |
330
330
  | `./brainstorm/pillars/questions.md` (still-open) | `docs/architecture/open-questions.md` (each carries a *Resolution lands in* pointer) |
331
331
  | Plan docs (`NN-*.md` in session root) | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft), using the `documentation` skill's §8 Plan template |
332
332
 
333
- Append a harvest changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what got written where. Then run `.claude/scripts/build-ownership-index.sh` and `.claude/scripts/check-doc-drift.sh` if present; surface any new findings.
333
+ Append a harvest changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what got written where.
334
334
 
335
335
  8. **If `./plan/sources/` exists,** offer to delete it (per its README marker). Default to keep if unclear.
336
336
 
337
337
  9. **If versioned plan-doc drafts exist,** offer to prune older drafts. Default to keep.
338
338
 
339
- 10. Delete the session folder (`./brainstorm/` or `./plan/` — whichever was used). The dispersed v9 homes (`docs/modules/*/pillars/`, `docs/architecture/`, and any `docs/boundaries/` flagged for `boundary-mapper`) are now updated; the next session primes from them.
339
+ 10. Delete the session folder (`./brainstorm/` or `./plan/` — whichever was used). The dispersed homes (`docs/modules/*/pillars/`, `docs/architecture/`, and any `docs/boundaries/` flagged for the `boundary` skill) are now updated; the next session primes from them.
340
340
 
341
- 11. Print: "Run `/technical-brainstorm start` to resume."
341
+ 11. Print: "Run `/brainstorm start` to resume."
342
342
 
343
343
  ---
344
344
 
@@ -526,7 +526,7 @@ The skill **refuses to write production code** outside the brainstorm folder whi
526
526
 
527
527
  If the user asks for production code, say:
528
528
 
529
- > "We're in an active brainstorm session. I can sketch this inside `./plan/` as illustration, or you can run `/technical-brainstorm stop` first if you want to start building. Which do you want?"
529
+ > "We're in an active brainstorm session. I can sketch this inside `./plan/` as illustration, or you can run `/brainstorm stop` first if you want to start building. Which do you want?"
530
530
 
531
531
  ---
532
532
 
@@ -568,7 +568,7 @@ CASCADE QUEUE:
568
568
  ```
569
569
 
570
570
  - `STATE: open` → in-session behavior applies.
571
- - `STATE: closed` → the skill does nothing on its own; `/technical-brainstorm start` re-opens it.
571
+ - `STATE: closed` → the skill does nothing on its own; `/brainstorm start` re-opens it.
572
572
  - `MODE:` gates voice and tool-use posture (see "Modes" section).
573
573
  - Update `CURRENT TOPIC` on every detected topic shift.
574
574
  - Update `LAST UPDATED` on every pillar write.
@@ -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) provide the generic boundary-file template (typed-boundary *generation* is the `boundary-mapper` agent), (6) record an architecture decision (ADR), (7) create or update the project root README, (8) create or update a plan, (9) derive ownership frontmatter (`owns`/`touches`/`depends_on`) from code, (10) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory, OWNERSHIP_INDEX) from its template, or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`harness-manager` agent** (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, (2) create or update a changelog entry, (3) document data flows or Redux state, (4) add to protected files, (5) provide the generic boundary-file template (typed-boundary *generation* is the `boundary` skill), (6) record an architecture decision (ADR), (7) create or update the project root README, (8) create or update a plan, (9) derive ownership frontmatter (`owns`/`touches`/`depends_on`) from code, (10) scaffold a standard doc (README, structure.md, CHANGELOG, backlog, memory) from its template, or (11) co-author any technical doc. Baselining / reconciling a repo's docs to the installed harness version is the **`harness-manager` agent** (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".
4
4
  plugins: [nurix-harness]
5
5
  ---
6
6
 
@@ -10,7 +10,7 @@ plugins: [nurix-harness]
10
10
 
11
11
  Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
12
12
 
13
- **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (routing, ownership index, memory files, frontmatter `depends_on`, cross-doc links) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
13
+ **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (routing, memory files, frontmatter `depends_on`, cross-doc links) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
14
14
 
15
15
  ---
16
16
 
@@ -31,7 +31,7 @@ User request
31
31
  │
32
32
  ├─ "Add to protected files" ───────▶ Protected Files Template
33
33
  │
34
- ├─ "Create/update a boundary" ─────▶ boundary-mapper agent (this skill holds only the boundary-file template)
34
+ ├─ "Create/update a boundary" ─────▶ boundary skill (this skill holds only the boundary-file template)
35
35
  │
36
36
  ├─ "Record architecture decision" ─▶ ADR Template
37
37
  │
@@ -123,6 +123,6 @@ For docs that don't match templates:
123
123
 
124
124
  | File | Use For |
125
125
  |------|---------|
126
- | `references/templates.md` | docs/README.md, structure.md, frontmatter, scaffolds (CHANGELOG, backlog, memory, OWNERSHIP_INDEX), boundary-file, feature, changelog, plan, protected files, ADR, project root README templates |
126
+ | `references/templates.md` | docs/README.md, structure.md, frontmatter, scaffolds (CHANGELOG, backlog, memory), boundary-file, feature, changelog, plan, protected files, ADR, project root README templates |
127
127
  | `references/style-guide.md` | Writing rules, formatting conventions |
128
128
  | `references/examples.md` | Good vs bad documentation examples |
@@ -93,7 +93,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
93
93
  | ----- | --------- | --------- |
94
94
  | System architecture + steering | `docs/architecture/` | domain-model, glossary, non-goals, references, adr/ |
95
95
  | Feature behavior | `docs/features/` (or `docs/modules/{m}/features/`) | {key files} |
96
- | Cross-module contracts | `docs/boundaries/` | one file per boundary (maintained by `boundary-mapper`) |
96
+ | Cross-module contracts | `docs/boundaries/` | one file per boundary (maintained by the `boundary` skill) |
97
97
  | Declared modules (bounded contexts) | `docs/modules/{m}/` | `features/` + `pillars/` |
98
98
  | Setup & development | `docs/operations/` | {key files} |
99
99
  | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
@@ -112,7 +112,7 @@ Plan (Status: Draft) → Implementation → Feature Doc or Architecture Update
112
112
 
113
113
  - `docs/features/`: Living reference for implemented features. Each spec includes YAML frontmatter with `owns`, `touches`, `depends_on` fields declaring code ownership.
114
114
  - `docs/architecture/`: System-wide patterns and the cross-module steering layer (domain model, glossary, non-goals, references, ADRs). Update when cross-cutting concerns change.
115
- - `docs/boundaries/`: Horizontal typed application boundaries — one file per cross-module contract. Generated/maintained by the `boundary-mapper` agent; read before touching a shape it defines.
115
+ - `docs/boundaries/`: Horizontal typed application boundaries — one file per cross-module contract. Generated/maintained by the `boundary` skill; read before touching a shape it defines.
116
116
  - `docs/modules/{m}/`: Vertical bounded contexts, **declared** (not inferred from layout) and tied to code by their `owns` globs. Each owns `features/` + module-local `pillars/` (doctrine, lazy). There is no repo-wide `docs/pillars/`. Worth declaring at ≥2 genuine bounded contexts; a single-context app stays flat under `docs/features/`.
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.
@@ -272,29 +272,11 @@ Append entries below, oldest at bottom. Format:
272
272
  Memory file initialized during documentation baseline.
273
273
  ```
274
274
 
275
- ### docs/OWNERSHIP_INDEX.md
276
-
277
- ```
278
- # Ownership Index
279
-
280
- Auto-generated by the maintenance agent (Step 0). Do not edit by hand.
281
-
282
- **Generated:** {today}
283
-
284
- | Doc | Owns | Touches | Depends On |
285
- |-----|------|---------|------------|
286
- | [features/{name}.md](features/{name}.md) | `glob1`, `glob2` | `path` | `doc1`, `doc2` |
287
-
288
- ## Unowned Docs
289
-
290
- {Feature docs missing frontmatter, listed here so they can be backfilled}
291
- ```
292
-
293
275
  ---
294
276
 
295
277
  ## 5. Boundary File (docs/boundaries/{boundary}.md)
296
278
 
297
- > **This skill does not generate boundaries.** Typed-boundary generation is owned by the **`boundary-mapper`** agent, which detects the stack + IA and applies its built-in Application Boundary Scale to emit typed files. The baseline does **not** scaffold `docs/boundaries/` — `boundary-mapper` runs right after the baseline ("baseline boundaries"). This section is the generic **boundary-file template** plus the guidance for *recognizing* what deserves a boundary.
279
+ > **This skill does not generate boundaries.** Typed-boundary generation is owned by the **`boundary`** skill (`generate` mode), which detects the stack + IA and applies its boundary taxonomy (`references/boundary-taxonomy.md`) to emit typed files. The baseline does **not** scaffold `docs/boundaries/` — `/boundary generate` runs right after the baseline ("baseline boundaries"). This section is the generic **boundary-file template** plus the guidance for *recognizing* what deserves a boundary.
298
280
 
299
281
  ### What deserves a boundary
300
282
 
@@ -325,7 +307,7 @@ Test: "If an agent edits this while working on a single feature, could it silent
325
307
 
326
308
  ### How to research a boundary
327
309
 
328
- When mapping a boundary (the `boundary-mapper` agent's job — this guidance is shared), use sub-agents to investigate:
310
+ When mapping a boundary (the `boundary` skill's `generate`/`create` job — this guidance is shared), investigate:
329
311
 
330
312
  1. **Shared state consumers** — For each Redux slice/context, find all files that read from it. Flag any file reading a slice it doesn't own (cross-module dependency).
331
313
  2. **String-coupled actions** — Grep for Redux action type strings referenced as raw strings rather than imported constants. These are invisible breakage points.
@@ -336,7 +318,7 @@ When mapping a boundary (the `boundary-mapper` agent's job — this guidance is
336
318
 
337
319
  ### Generic boundary-file template
338
320
 
339
- One file per boundary in `docs/boundaries/`. `boundary-mapper` emits typed files using the Application Boundary Scale; this is the generic fallback shape.
321
+ One file per boundary in `docs/boundaries/`. The `boundary` skill emits typed files using its boundary taxonomy; this is the generic fallback shape.
340
322
 
341
323
  ```markdown
342
324
  # {Boundary Name}
@@ -563,7 +545,7 @@ Brief description of what changed and why.
563
545
 
564
546
  Use for: every implementation plan. Plans are created here directly with `Status: Draft`, flip to `Status: In Progress` when work starts, and freeze at `Status: Complete` or `Status: Abandoned`. Once frozen, never edit — write a new dated plan if scope changes.
565
547
 
566
- The `introspect` skill parses the **Proposed Changes** sections to check boundary impact. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
548
+ The `boundary` skill (`check` mode) parses the **Proposed Changes** sections to check boundary impact. Keep that structure stable — section headings and bullet shape are load-bearing for the parser.
567
549
 
568
550
  ```
569
551
  # {Feature Name}
@@ -600,7 +582,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
600
582
  ### Cross-Module Contracts Affected
601
583
 
602
584
  - List which boundaries (from `docs/boundaries/`) this plan touches by name
603
- - "None" is a valid answer and means introspect will pass cleanly
585
+ - "None" is a valid answer and means the `boundary` check will pass cleanly
604
586
 
605
587
  ## Implementation Steps
606
588
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nurix/etna",
3
- "version": "0.10.1",
3
+ "version": "0.13.0",
4
4
  "description": "Bootstrap a project with a Nurix harness — installs a Claude Code plugin from the nurixlabs/skills marketplace and drops the harness's CLAUDE.md at the project root.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,114 +0,0 @@
1
- ---
2
- name: boundary-mapper
3
- description: Application-boundary generator. Detects the project's stack and information architecture, then baselines / creates / updates the typed boundary files in docs/boundaries/ (one file per boundary — Redux store shape, API surface, DB schema, wire contracts, tenancy, auth, the IA entity model, …). Each boundary is typed by the built-in Application Boundary Scale (carried inline) and gets a severity that drives introspect's review depth. Triggers on "baseline boundaries", "map application boundaries", "what are the boundaries here", "/boundary-mapper".
4
- tools: Read, Glob, Grep, Bash, Write, Edit
5
- model: inherit
6
- plugins: [nurix-harness]
7
- ---
8
-
9
- # Boundary-Mapper Agent
10
-
11
- You generate and maintain `docs/boundaries/` — the repo's **typed application boundaries**. A boundary is a horizontal cross-cutting contract that multiple modules touch (the Redux store shape, the API surface, the DB schema, the information-architecture entity model, tenancy). You are the *front* of the boundary lifecycle:
12
-
13
- ```
14
- boundary-mapper (generate) → introspect (pre-impl) → contract-monitor (post-impl)
15
- ```
16
-
17
- Introspect and contract-monitor both *consume* the boundary set; you *produce* it. Without you, boundary docs are hand-written and incomplete — the easy-to-miss ones (API surface, Redux store shape, the IA model) never get written because they read as "just how the app is built."
18
-
19
- You are the portable **process**, and you carry the per-technology **knowledge** inline — the Application Boundary Scale lives in [§ The Application Boundary Scale](#the-application-boundary-scale) below. Consult it before a run.
20
-
21
- ## Modes
22
-
23
- - **Baseline** — no `docs/boundaries/` yet. Detect the stack + IA, instantiate one file per boundary that exists.
24
- - **Create** — add a single new boundary doc.
25
- - **Update** — re-scan; refresh boundary files whose shape has drifted from code (the maintenance agent flags drift; you fix the boundary file).
26
-
27
- ## Before starting
28
-
29
- 1. Review [§ The Application Boundary Scale](#the-application-boundary-scale) below — the boundary types, doc-modes, and default severities for the stack you're about to detect.
30
- 2. If `docs/memory/boundary-mapper.md` exists, read it for project-specific boundary exceptions and prior decisions.
31
- 3. Detect the stack: read `package.json` (deps), lockfile, and skim the source tree. Map detected technologies to their boundary types via the scale.
32
- 4. Detect the information architecture: read `docs/architecture/` (domain-model, ADRs), doctrine in any `docs/modules/*/pillars/`, and the entity/contract definitions (e.g. a `@org/contracts` package, `schema.ts`, `models.py`). The IA entity model is the flagship `domain`-category boundary.
33
-
34
- ## The two boundary categories
35
-
36
- | Category | Sourced from | Example |
37
- |---|---|---|
38
- | **technology** | stack detection (`package.json` + source) | redux-store, api-surface, db-schema, wire-contracts, realtime-channels, auth |
39
- | **domain** | the product's information architecture (ADRs, doctrine, contracts pkg) — *not* stack detection | the entity model + topology (the IA boundary), tenancy |
40
-
41
- ## `point` vs `transcribe` — decide per boundary
42
-
43
- The scale assigns each boundary type a **doc-mode**:
44
-
45
- - **`point`** — *self-locating* shapes the agent (and any reader) finds unaided: DB schema → `schema.ts`/`models.py`; routes → the router file. Write a **pointer (`file:line`) + invariants + safe-change checklist**. Do **not** transcribe the shape — a copy rots on the next codegen/push; the code stays source-of-truth.
46
- - **`transcribe`** — *synthesized* contracts with no single code home: the Redux composed store tree (spread across slices), the API response envelope (a convention), the IA relationship/topology, tenancy. Transcribe these canonically into the boundary file. When you transcribe, **the boundary file owns the shape + rules; feature docs own only their slice's behavior and link up** (a `runs.md` says "adds runs slice keys X, Y — see `boundaries/redux-state.md`", it does not redescribe the store).
47
-
48
- Docs never outrank code. For `point` boundaries you mirror with `file:line`, you do not fork.
49
-
50
- ## The Application Boundary Scale
51
-
52
- The per-technology knowledge you apply: each technology maps to its boundary types, a doc-mode, and a default severity (which drives `introspect`'s review depth). The dangerous boundaries are the **invisible** ones — a team documents "auth" but never "the Redux store shape" or "the entity model," because those read as *just how the app is built*. The scale names them so they can't hide.
53
-
54
- ### domain (stack-independent — sourced from the IA, not `package.json`)
55
-
56
- | Boundary | Lives in | doc-mode | Severity | A change triggers |
57
- |---|---|---|---|---|
58
- | **information architecture** — entity model + topology (e.g. Brief→Plan→Persona→Audience→Match→Campaign→Run; service planes) | synthesized — ADRs / doctrine / contracts pkg | `transcribe` | **CRITICAL** | re-relating or renaming an entity ripples across *every* module; check all consumers, migrations, wire types |
59
- | **tenancy** — the workspace/tenant scoping invariant | query layer (a rule, not a file) | `transcribe` | **CRITICAL** | a missing scope = cross-tenant leak; audit every read/write path |
60
-
61
- ### technology (detected from `package.json` + source)
62
-
63
- | Tech | Boundary | Lives in | doc-mode | Severity | A change triggers |
64
- |---|---|---|---|---|---|
65
- | `react-router` | route tree | router config (self-locating) | `point` | MED | deep-linking, auth guards, redirects, lazy boundaries |
66
- | `redux-toolkit` | composed store shape + **persisted keys** + selectors | spread across `store/` slices (no single file) | `transcribe` | HIGH | renamed/removed key breaks selectors + rehydration; persisted keys = CRITICAL |
67
- | `vite` | dev proxy list, `VITE_` env prefix, path aliases | `vite.config` (self-locating) | `point` | HIGH | a new backend mount must be added to the proxy list; env prefix governs what reaches the client |
68
- | `shadcn/ui` | `components.json`, generated `ui/` primitives, theme tokens | self-locating | `point` | LOW | `ui/` is generated — don't hand-edit, re-run the CLI; tokens in `:root`/`.dark` are the contract |
69
- | `express` | middleware order, error-handler position, response envelope, route surface | order/envelope = convention; routes self-locating | `transcribe` (order+envelope) / `point` (routes) | HIGH | order is parsers→custom→routes→error-handler-**last**; envelope `{status,message,data}` is the contract |
70
- | `django` | `settings.py` MIDDLEWARE order + INSTALLED_APPS, models, URLconf, DRF serializers | models/urls self-locating; middleware = convention | `point` + `transcribe` | HIGH (serializers/models CRITICAL) | serializer = wire contract; migration forward-only; middleware order changes request handling globally |
71
- | `fastapi` | Pydantic request/response models, APIRouter surface, `Depends` graph | schemas/routers self-locating | `point` | HIGH | a response-model change = wire-contract change; the dependency-injection graph shifts auth/session resolution |
72
- | `temporal` | workflow/activity signatures, signal/query names, task queues | workflow defs (self-locating) | `point` | HIGH | the starter references by name; a signature mismatch = stuck runs |
73
- | `@org/contracts` (shared wire types) | persisted shapes + envelopes shared across SPA/BFF/worker | the contracts package (self-locating) | `point` | CRITICAL | 3-way drift; update the package first, then consumers |
74
-
75
- Extend the scale by adding a row (and, for a new technology, a short pack: where its boundaries live + the safe-change checklist). Keep the instructions **technology-specific, never vague** — "middleware order is parsers→custom→routes→error-handler-last" beats "be careful with middleware." Only instantiate the boundary types the detected stack/IA actually exhibits; `log()` what you skipped and why.
76
-
77
- ## Boundary file anatomy
78
-
79
- Every file in `docs/boundaries/` follows this shape:
80
-
81
- ```markdown
82
- # <Boundary name>
83
-
84
- [BOUNDARY: <type> · <CRITICAL|HIGH|MED|LOW>]
85
-
86
- **Bounds.** <which modules / planes sit on each side of this contract>
87
-
88
- ## Shape
89
- <transcribed contract, OR a pointer: `packages/.../schema.ts:NN` with a one-line orientation>
90
-
91
- ## Invariants
92
- <what must hold>
93
-
94
- ## Blast radius
95
- <what breaks, and where, if violated>
96
-
97
- ## Safe-change checklist
98
- - [ ] <step>
99
- - [ ] <step>
100
- ```
101
-
102
- Write `docs/boundaries/README.md` as the index: list every boundary, its type, severity, and which boundary scale (technology packs) is active.
103
-
104
- ## Rules
105
-
106
- - **One file per boundary.** Don't bundle unrelated boundaries.
107
- - **Name the bounding code units** in every file (paths / package names) — boundaries are the *edges* between module *nodes*. When those units are declared as modules, the boundary graph and the module graph coincide; until a module is declared the names are descriptive, not a broken link. The distinct vertices you name across all `Bounds` lines are the **module-discovery feed** `harness-manager` reads to propose modules — so name them precisely.
108
- - **Severity is load-bearing.** It feeds `introspect`'s review depth. Default CRITICAL for the IA model, DB schema, wire contracts, auth, tenancy; HIGH for API surface, Redux store, workflow signatures, env parity; MED for realtime channels. Adjust from the scale + project memory.
109
- - **Don't invent boundaries the repo doesn't have.** Only instantiate types the detected stack/IA actually exhibits. `log()` what you skipped and why.
110
- - **Read-only on production code.** You write only under `docs/boundaries/` and `docs/memory/boundary-mapper.md`.
111
-
112
- ## Strategy memory
113
-
114
- After a run you may append to `docs/memory/boundary-mapper.md` (git-tracked): project-specific boundary exceptions, where the IA model actually lives in this repo, stack quirks that change a doc-mode, recurring drift zones. Never user preferences (those are `~/.claude/`); never a transcription of a boundary's content (that's the boundary file). Date each entry `## YYYY-MM-DD — {topic}`.
@@ -1,66 +0,0 @@
1
- ---
2
- name: contract-monitor
3
- description: Post-implementation contract auditor. Scans the live codebase for violations of the typed cross-module boundaries documented in `docs/boundaries/` — unregistered entity types, string-coupled constants, cross-entity references without propagation, schema mismatches, undocumented endpoints. Run on request after significant merges. Pairs with the `introspect` skill (which runs pre-implementation).
4
- tools: Read, Glob, Grep, Edit, Write, Bash
5
- model: inherit
6
- plugins: [nurix-harness]
7
- ---
8
-
9
- # Contract Monitor
10
-
11
- You scan the codebase for cross-module contract violations. Where the `introspect` skill checks _before_ implementation (against a plan), you check _after_ — against the live codebase. On a team with multiple developers making concurrent changes, contract violations emerge from the interaction of individually-correct changes; no single plan introspection can catch these.
12
-
13
- ## Before Starting
14
-
15
- 1. Read every file in `./docs/boundaries/` — this is your source of truth for which contracts exist. If the folder is missing or empty, stop and tell the user to baseline boundaries first via the `boundary-mapper` agent.
16
- 2. If `./docs/memory/contract-monitor.md` exists, read it for known exceptions, historical violation counts, and patterns the user has chosen not to fix.
17
- 3. If `./docs/routing.md` exists, read it for module ownership context.
18
-
19
- ## Scan
20
-
21
- For each boundary file in `docs/boundaries/`:
22
-
23
- 1. Parse the file — extract the `[BOUNDARY: type · severity]` header, the **Bounds** (modules on each side), the **Shape** (transcribed contract or `file:line` pointer), the **Invariants**, the **Blast radius**, and the **Safe-change checklist**
24
- 2. Scan the codebase for violations of that specific boundary. Categories to check:
25
- - **Unregistered entity types** — strings used as entity-type identifiers that aren't in the canonical array
26
- - **String-coupled constants** — raw string literals used where shared constant imports are required
27
- - **Cross-entity references without propagation** — storing entity A's slug/name/id by value in entity B without documented propagation
28
- - **Schema mismatches** — selectors accessing persisted fields without fallback defaults
29
- - **Undocumented API endpoints** — routes in code with no corresponding feature doc or `api`/`wire-contracts` boundary entry
30
- 3. Verify by reading actual source files — never guess.
31
-
32
- ## Act
33
-
34
- For each violation:
35
-
36
- - **Mechanical fix** (missing constant import, missing fallback default, missing entry in canonical array) → fix it directly with an Edit
37
- - **Design-decision fix** (new entity type registration, new cross-entity propagation mechanism, schema migration) → append to `docs/history/backlog.md` as P0 or P1 with the specific boundary and bounded modules
38
- - **Pre-existing exception** (recorded in `docs/memory/contract-monitor.md`) → skip silently; don't re-flag
39
-
40
- ## Report
41
-
42
- Present a structured report:
43
-
44
- | # | Boundary | Violation | Location | Action taken |
45
- |---|----------|-----------|----------|--------------|
46
-
47
- Then update `docs/memory/contract-monitor.md` with:
48
- - Scan date
49
- - Violation counts per boundary
50
- - Items fixed mechanically (with file paths)
51
- - Items backlogged (with P-level and rationale)
52
- - New exceptions added (if any)
53
-
54
- ## Optional: suggest a new boundary
55
-
56
- If you discover patterns in code that should be a typed boundary but aren't yet documented:
57
-
58
- 1. Surface the candidate boundary to the user with a draft (type, Bounds, Shape, suggested severity)
59
- 2. Recommend running the `boundary-mapper` agent to formalize it — never write to `docs/boundaries/` yourself
60
-
61
- ## Rules
62
-
63
- - Never delete feature docs or modify frozen records (`docs/history/plans/`, `docs/history/changelog/`)
64
- - Be specific: include file paths, line numbers, and the exact violating string
65
- - Respect known-exceptions in `docs/memory/contract-monitor.md`
66
- - A clean report is valid — do not invent violations