@nurix/etna 0.3.1 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/etna.js +17 -3
- package/data/harnesses/code/CLAUDE.md +69 -124
- package/data/harnesses/code/agents/boundary-mapper.md +31 -8
- package/data/harnesses/code/agents/brainstorm.md +22 -86
- package/data/harnesses/code/agents/change-review.md +12 -12
- package/data/harnesses/code/agents/contract-monitor.md +14 -14
- package/data/harnesses/code/agents/maintenance.md +4 -4
- package/data/harnesses/code/scripts/build-ownership-index.sh +11 -2
- package/data/harnesses/code/scripts/check-doc-drift.sh +10 -1
- package/data/harnesses/code/skills/documentation/SKILL.md +20 -17
- package/data/harnesses/code/skills/documentation/references/templates.md +36 -48
- package/data/harnesses/code/skills/introspect/SKILL.md +23 -23
- package/data/harnesses/code/skills/technical-brainstorm/SKILL.md +47 -21
- package/data/harnesses/kb-agi/CLAUDE.md +2 -2
- package/data/harnesses/kb-agi/agents/kb-agi-init.md +2 -2
- package/data/harnesses/kb-agi/agents/kb-catch-stale.md +1 -1
- package/data/harnesses/kb-agi/agents/kb-find-gaps.md +2 -2
- package/data/harnesses/kb-agi/agents/kb-fix-links.md +1 -1
- package/data/harnesses/kb-agi/agents/kb-refresh-frontdoor.md +1 -1
- package/data/harnesses/kb-agi/agents/kb-refresh-summaries.md +1 -1
- package/data/harnesses/kb-agi/agents/kb-sync-metadata.md +1 -1
- package/package.json +1 -1
- package/data/harnesses/code/skills/boundaries/SKILL.md +0 -86
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: introspect
|
|
3
|
-
description: Pre-implementation impact analyzer. Reads a plan in docs/history/plans/ and checks every Proposed Change against docs/
|
|
3
|
+
description: Pre-implementation impact analyzer. Reads a plan in docs/history/plans/ and checks every Proposed Change against the typed boundaries in docs/boundaries/ to surface cascading risks before coding starts. Produces a severity-ranked violation report with suggested plan additions. Read-only. Triggers on "introspect", "check this plan", "impact analysis", "/introspect", "what could break", "boundary check before I start".
|
|
4
4
|
plugins: [nurix-harness]
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Introspect Skill
|
|
8
8
|
|
|
9
|
-
Pre-implementation impact analysis. Reads a plan, intersects every proposed change with documented
|
|
9
|
+
Pre-implementation impact analysis. Reads a plan, intersects every proposed change with the documented boundaries in `docs/boundaries/`, and surfaces cascading risk _before_ implementation. The complement to `contract-monitor`, which scans the live codebase _after_ changes land.
|
|
10
10
|
|
|
11
11
|
The skill is read-only. It does not edit the plan, modify code, or write to memory. Output is a report the user reviews and acts on.
|
|
12
12
|
|
|
@@ -18,11 +18,11 @@ Trigger this skill when:
|
|
|
18
18
|
|
|
19
19
|
- The user types `/introspect`, "introspect", "check this plan", "impact analysis", "what could break"
|
|
20
20
|
- A plan exists in `docs/history/plans/` and the user is about to start implementation
|
|
21
|
-
- A plan was recently revised and the user wants to re-check
|
|
21
|
+
- A plan was recently revised and the user wants to re-check boundary impact
|
|
22
22
|
|
|
23
23
|
Do not run it when:
|
|
24
24
|
|
|
25
|
-
- No `docs/
|
|
25
|
+
- No `docs/boundaries/` exists, or it's empty — tell the user to baseline the typed boundaries first via the `boundary-mapper` agent (`baseline boundaries`)
|
|
26
26
|
- No plan exists — tell the user to write a plan first (documentation skill, `create plan`)
|
|
27
27
|
- The user wants post-implementation auditing — that's the `contract-monitor` agent
|
|
28
28
|
|
|
@@ -31,7 +31,7 @@ Do not run it when:
|
|
|
31
31
|
## Inputs
|
|
32
32
|
|
|
33
33
|
- **Plan path**: user-provided. If unspecified, use the most recent file in `docs/history/plans/` (sorted by filename date).
|
|
34
|
-
- **
|
|
34
|
+
- **Boundaries**: every file in `docs/boundaries/` is mandatory input. Stop if the folder is missing or empty (suggest `boundary-mapper`).
|
|
35
35
|
- **Source files**: read on demand to verify intersections — never guess from plan text alone.
|
|
36
36
|
|
|
37
37
|
---
|
|
@@ -43,7 +43,7 @@ Do not run it when:
|
|
|
43
43
|
1. Resolve the plan path. If the user named a feature, glob `docs/history/plans/*{feature}*.md` and pick the newest.
|
|
44
44
|
2. Read the plan in full.
|
|
45
45
|
3. Confirm it has a `Status:` field. If `Complete` or `Abandoned`, ask the user whether they want to introspect a frozen plan anyway — it's usually a mistake.
|
|
46
|
-
4. Read `docs/
|
|
46
|
+
4. Read every file in `docs/boundaries/`. For each boundary, parse the `[BOUNDARY: type · severity]` header plus: **Bounds** (the modules on each side of the contract), **Shape** (the transcribed contract, or a `file:line` pointer to self-locating code), **Invariants** (what must hold), **Blast radius** (what breaks if violated), and the **Safe-change checklist**. The severity (CRITICAL / HIGH / MED / LOW) sets the review depth for any change that touches that boundary.
|
|
47
47
|
|
|
48
48
|
### Phase 2: Parse Proposed Changes
|
|
49
49
|
|
|
@@ -51,25 +51,25 @@ The plan template's **Proposed Changes** subsections are load-bearing — intros
|
|
|
51
51
|
|
|
52
52
|
| Subsection | What introspect uses it for |
|
|
53
53
|
|------------|------------------------------|
|
|
54
|
-
| **New Files** | New paths to check against ownership and
|
|
55
|
-
| **Modified Files** | Existing paths to check against
|
|
56
|
-
| **New Entities / State** | Entity strings, state slices, schema additions — checked against
|
|
57
|
-
| **API Changes** | New or modified routes, contracts, request/response shapes — checked against
|
|
58
|
-
| **Cross-Module Contracts Affected** | The plan author's own admission of
|
|
54
|
+
| **New Files** | New paths to check against ownership and the modules each boundary **Bounds** |
|
|
55
|
+
| **Modified Files** | Existing paths to check against boundaries that **Bound** them |
|
|
56
|
+
| **New Entities / State** | Entity strings, state slices, schema additions — checked against the `domain` and `db-schema` boundaries |
|
|
57
|
+
| **API Changes** | New or modified routes, contracts, request/response shapes — checked against the `api` / `wire-contracts` boundaries |
|
|
58
|
+
| **Cross-Module Contracts Affected** | The plan author's own admission of boundaries touched — start here, then verify |
|
|
59
59
|
|
|
60
60
|
If a subsection is missing or empty, note it in the report (the plan may be incomplete) but continue with what's there.
|
|
61
61
|
|
|
62
62
|
### Phase 3: Analyze
|
|
63
63
|
|
|
64
|
-
For each
|
|
64
|
+
For each boundary × proposed change pair, check intersection:
|
|
65
65
|
|
|
66
|
-
1. **
|
|
67
|
-
2. **
|
|
68
|
-
3. **
|
|
66
|
+
1. **Bounds overlap** — does the change touch any module the boundary **Bounds**, or any file its **Shape** pointer (`file:line`) locates?
|
|
67
|
+
2. **Invariant overlap** — does the change introduce code shapes the boundary's **Invariants** prohibit (raw string literal where a shared constant is required, new entity type not in the canonical array, persisted field without selector fallback)?
|
|
68
|
+
3. **Shape overlap** — does the change modify the canonical **Shape** of a boundary (the `ENTITY_TYPES` array, the shared constants file, the persistence schema, the API envelope)?
|
|
69
69
|
|
|
70
70
|
Whenever an intersection is plausible from plan text, **read the actual source files** to verify. Never guess from plan text alone.
|
|
71
71
|
|
|
72
|
-
Assign severity:
|
|
72
|
+
Assign severity. Anchor it to the **boundary's own severity** (it sets the floor), then adjust by the concrete risk this change carries — a change against a CRITICAL/HIGH boundary starts at that floor; downgrade only with a stated reason. The boundary's **Blast radius** is the evidence for the rating:
|
|
73
73
|
|
|
74
74
|
- **Critical** — silent data loss, corrupted persistence, broken cross-entity references
|
|
75
75
|
- **High** — stale state, broken lookups, schema selectors without fallbacks
|
|
@@ -84,13 +84,13 @@ Produce a markdown report:
|
|
|
84
84
|
# Introspect — {plan filename}
|
|
85
85
|
|
|
86
86
|
Plan: {path}
|
|
87
|
-
|
|
87
|
+
Boundaries: {N} files evaluated
|
|
88
88
|
Intersections found: {N} ({critical}/{high}/{medium}/{low})
|
|
89
89
|
|
|
90
90
|
## Violations
|
|
91
91
|
|
|
92
|
-
| # |
|
|
93
|
-
|
|
92
|
+
| # | Boundary | Risk | Severity | Plan step |
|
|
93
|
+
|---|----------|------|----------|-----------|
|
|
94
94
|
|
|
95
95
|
## Suggested Plan Additions
|
|
96
96
|
|
|
@@ -106,7 +106,7 @@ For each violation, a specific recommendation:
|
|
|
106
106
|
|
|
107
107
|
## New Cross-Module Contracts Detected
|
|
108
108
|
|
|
109
|
-
{If the plan introduces a contract not yet in
|
|
109
|
+
{If the plan introduces a cross-cutting contract not yet in `docs/boundaries/`, describe the proposed boundary (type, Bounds, Shape, suggested severity) and recommend running the `boundary-mapper` agent to formalize it — never write a boundary file directly.}
|
|
110
110
|
```
|
|
111
111
|
|
|
112
112
|
The severity-ranked table is the load-bearing output. Suggestions are advisory — the user decides which to fold back into the plan.
|
|
@@ -116,17 +116,17 @@ The severity-ranked table is the load-bearing output. Suggestions are advisory
|
|
|
116
116
|
After producing the report:
|
|
117
117
|
|
|
118
118
|
- If the user accepts a suggested plan addition, they edit the plan themselves (or invoke the documentation skill to do it). Introspect never edits plans.
|
|
119
|
-
- If new contracts are detected, suggest
|
|
119
|
+
- If new contracts are detected, suggest running the `boundary-mapper` agent to formalize them as a typed boundary — do not write to `docs/boundaries/` from this skill.
|
|
120
120
|
|
|
121
121
|
---
|
|
122
122
|
|
|
123
123
|
## Rules
|
|
124
124
|
|
|
125
|
-
- **Read-only**. Never edit the plan, source code,
|
|
125
|
+
- **Read-only**. Never edit the plan, source code, boundaries, or memory.
|
|
126
126
|
- **Verify against source**. Never report a violation purely from plan text — read the files the plan claims it will touch.
|
|
127
127
|
- **Plan structure is load-bearing**. If a plan was not written using the documentation skill's plan template, the Proposed Changes subsections may be missing. Note this clearly rather than fabricating intersections.
|
|
128
128
|
- **A clean report is valid**. Plans with no intersections produce an empty violations table — say so, don't pad.
|
|
129
|
-
- **Be specific**. Cite file paths, plan-step numbers,
|
|
129
|
+
- **Be specific**. Cite file paths, plan-step numbers, boundary names, and the exact code shape that breaks the contract.
|
|
130
130
|
- **Don't replicate contract-monitor**. Introspect checks intent (plan text). Contract-monitor checks reality (code). If the user wants to scan live code, route them to contract-monitor.
|
|
131
131
|
|
|
132
132
|
---
|
|
@@ -11,6 +11,8 @@ Plan and design before building. While a session is active, capture concerns, hy
|
|
|
11
11
|
|
|
12
12
|
The user's job is to prevent eager coding. The skill's job is to make the planning conversation feel like a conversation — not an interview, not a decision-extraction funnel.
|
|
13
13
|
|
|
14
|
+
**This skill is self-contained.** It runs a complete brainstorming session on its own through the two subcommands below — the `brainstorm` agent is an optional *thin orchestrator* that recognizes when to enter Brainstorming Mode and otherwise defers entirely here. Everything a session needs lives in this file and its `templates/` + `greenfield.md` siblings: the three modes, the tentative→committed lifecycle, the realignment cascade, the scope-routed harvest, the 10 pillar templates, the greenfield rules, and strategy memory. Nothing here depends on the agent.
|
|
15
|
+
|
|
14
16
|
## Two subcommands. That's it.
|
|
15
17
|
|
|
16
18
|
- `/technical-brainstorm start` — open a session
|
|
@@ -20,11 +22,13 @@ Everything else happens **within** an active session, as natural conversation. T
|
|
|
20
22
|
|
|
21
23
|
## Folder layout
|
|
22
24
|
|
|
23
|
-
### Persistent pillars vs. session workspace (
|
|
25
|
+
### Persistent pillars vs. session workspace (v9)
|
|
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).
|
|
24
28
|
|
|
25
|
-
|
|
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).
|
|
26
30
|
|
|
27
|
-
If
|
|
31
|
+
If none of those v9 homes exist yet (a freshly-baselined repo, or first-time use), the skill still runs the session from this skill's `templates/` folder; the harvest **creates** each destination file on `/stop`, so nothing needs to pre-exist.
|
|
28
32
|
|
|
29
33
|
### Session folder
|
|
30
34
|
|
|
@@ -309,29 +313,30 @@ The session is now in **Explore mode**. Resolution-style flows are opt-in from h
|
|
|
309
313
|
|
|
310
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.
|
|
311
315
|
|
|
312
|
-
7. **Harvest into
|
|
313
|
-
|
|
314
|
-
| Session source |
|
|
315
|
-
|
|
316
|
-
| `./brainstorm/pillars/doctrine.md` (additions / amendments) | `docs/pillars/doctrine.md
|
|
317
|
-
| `./brainstorm/pillars/glossary.md` | `docs/pillars/glossary.md
|
|
318
|
-
| `./brainstorm/pillars/non-goals.md` | `docs/
|
|
319
|
-
| `./brainstorm/pillars/references.md` | `docs/
|
|
320
|
-
| `./brainstorm/pillars/inventory.md` | `docs/
|
|
321
|
-
| Committed decisions (`STATUS: committed` in `./brainstorm/pillars/decisions.md`) |
|
|
322
|
-
|
|
|
323
|
-
| `./brainstorm/pillars/
|
|
324
|
-
| `./brainstorm/pillars/
|
|
325
|
-
| `./brainstorm/pillars/
|
|
326
|
-
|
|
|
327
|
-
|
|
328
|
-
|
|
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:
|
|
317
|
+
|
|
318
|
+
| Session source | v9 destination(s) |
|
|
319
|
+
|---|---|
|
|
320
|
+
| `./brainstorm/pillars/doctrine.md` (additions / amendments) | module-local → `docs/modules/{m}/pillars/doctrine.md`; cross-module → `docs/architecture/domain-model.md` |
|
|
321
|
+
| `./brainstorm/pillars/glossary.md` | module-local → `docs/modules/{m}/pillars/glossary.md`; cross-module → `docs/architecture/glossary.md` |
|
|
322
|
+
| `./brainstorm/pillars/non-goals.md` | `docs/architecture/non-goals.md` |
|
|
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) |
|
|
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** |
|
|
327
|
+
| `./brainstorm/pillars/backlog.md` (new items) | `docs/history/backlog.md` (P0–P3, full operational tracking) |
|
|
328
|
+
| `./brainstorm/pillars/rejected.md` | ADR §Alternatives when tied to a committed decision; else `docs/modules/{m}/pillars/rejected.md` |
|
|
329
|
+
| `./brainstorm/pillars/milestones.md` | `docs/architecture/` (mirror in `docs/structure.md §Health log` if the milestone is a structural change) |
|
|
330
|
+
| `./brainstorm/pillars/questions.md` (still-open) | `docs/architecture/open-questions.md` (each carries a *Resolution lands in* pointer) |
|
|
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
|
+
|
|
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.
|
|
329
334
|
|
|
330
335
|
8. **If `./plan/sources/` exists,** offer to delete it (per its README marker). Default to keep if unclear.
|
|
331
336
|
|
|
332
337
|
9. **If versioned plan-doc drafts exist,** offer to prune older drafts. Default to keep.
|
|
333
338
|
|
|
334
|
-
10. Delete the session folder (`./brainstorm/` or `./plan/` — whichever was used). The
|
|
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.
|
|
335
340
|
|
|
336
341
|
11. Print: "Run `/technical-brainstorm start` to resume."
|
|
337
342
|
|
|
@@ -593,6 +598,27 @@ Plus **plan docs** at the top level — `01-foo.md`, `02-bar.md`, ... — domain
|
|
|
593
598
|
|
|
594
599
|
---
|
|
595
600
|
|
|
601
|
+
## Strategy memory
|
|
602
|
+
|
|
603
|
+
After a session you may append to `docs/memory/brainstorm.md` (git-tracked) to make future brainstorming on this project more effective. This is the brainstorming process's own memory — it applies whether the session was driven standalone or via the `brainstorm` agent.
|
|
604
|
+
|
|
605
|
+
**Record (project-strategy facts):**
|
|
606
|
+
|
|
607
|
+
- **Doctrine drift zones** — topics where the user repeatedly proposes things that brush an existing principle (e.g. "drift concentrates around the `audience` vocabulary — surface the read-only-agent principle early here").
|
|
608
|
+
- **Productive framings** — interview shapes that converged a question quickly (e.g. "for IA questions, walking the entity from a user's mental model clarifies faster than starting from schema").
|
|
609
|
+
- **Pillar-challenge patterns** — phrasings that reliably signal a challenge vs. a clarification.
|
|
610
|
+
- **Harvest pitfalls** — where the scope-routed harvest needed manual intervention (e.g. a genuinely cross-module doctrine update must land in `docs/architecture/domain-model.md`, not a single module's pillar).
|
|
611
|
+
|
|
612
|
+
**Never record:** user preferences / communication style (those are `~/.claude/`); per-decision content (that's the ADR or pillar file); anything tied to a single conversation or transient state.
|
|
613
|
+
|
|
614
|
+
Format each entry oldest-at-bottom, and read the file first so you update in place rather than duplicating:
|
|
615
|
+
|
|
616
|
+
```
|
|
617
|
+
## YYYY-MM-DD — {topic}
|
|
618
|
+
|
|
619
|
+
{1–3 lines of strategy fact, with pillar references where relevant}
|
|
620
|
+
```
|
|
621
|
+
|
|
596
622
|
## Greenfield doctrine
|
|
597
623
|
|
|
598
624
|
Loaded separately at `<skill-dir>/greenfield.md`. Read it before any sweep, gap detection, or stop — that's where the smell-words grep and the banned-patterns table live.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: kb-agi
|
|
3
3
|
description: Self-improving knowledge-base harness — a CLAUDE.md router (interview → ask/contribute) over a flat Obsidian note-vault, with single-intent upkeep agents that keep the vault trustworthy and grow it from its own query logs.
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.3.5
|
|
5
5
|
keywords:
|
|
6
6
|
- harness
|
|
7
7
|
- knowledge-base
|
|
@@ -13,7 +13,7 @@ keywords:
|
|
|
13
13
|
plugin: kb-agi
|
|
14
14
|
---
|
|
15
15
|
|
|
16
|
-
#
|
|
16
|
+
# nuStack Knowledge Hub — router
|
|
17
17
|
|
|
18
18
|
This repo is a flat Obsidian vault that you read on the user's behalf. It's the bridge from the front (positioning, claims) to the back (product and service specs); detailed execution lives downstream in the service repos.
|
|
19
19
|
|
|
@@ -151,7 +151,7 @@ Upkeep is run by the kb-agi agents (invoked by name); there is no `meta/goals/`
|
|
|
151
151
|
````markdown
|
|
152
152
|
# genre — Sales
|
|
153
153
|
|
|
154
|
-
The reader is positioning
|
|
154
|
+
The reader is positioning nuStack to someone else: a prospect, a partner, a teammate who needs the pitch. They want the claim and the proof behind it, not the implementation.
|
|
155
155
|
|
|
156
156
|
**Default depth.** Start crisp. Lead with the answer in one or two sentences — what we can do, what makes it different — then offer the supporting detail rather than front-loading it. Go deeper only when the question reaches for it ("how exactly…", "what's underneath…").
|
|
157
157
|
|
|
@@ -213,7 +213,7 @@ This is a living index. It is hand-maintained today and kept fresh by the `kb-re
|
|
|
213
213
|
---
|
|
214
214
|
|
|
215
215
|
## "I want to understand the product"
|
|
216
|
-
_What
|
|
216
|
+
_What nuStack is, what it can do, the claims and their proof._
|
|
217
217
|
|
|
218
218
|
- _populated on migration_
|
|
219
219
|
|
|
@@ -6,7 +6,7 @@ model: inherit
|
|
|
6
6
|
plugins: [kb-agi]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are the **kb-catch-stale** goal-agent for the
|
|
9
|
+
You are the **kb-catch-stale** goal-agent for the nuStack knowledge hub. One job: surface notes that have drifted out of date.
|
|
10
10
|
|
|
11
11
|
**Read first:** `meta/guidance.md` (the note model, `maturity` + `canonical` hints) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
|
|
12
12
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: kb-find-gaps
|
|
3
|
-
description: Audits the
|
|
3
|
+
description: Audits the nuStack vault for missing notes — diffs each folder's metadata.md and the session gap-logs against the note graph to find coverage holes. Use when asked to find gaps, check coverage, or "what's missing". Proposes a ranked gap list by default; writes notes ONLY when the invocation explicitly asks it to.
|
|
4
4
|
tools: Read, Grep, Glob, Bash
|
|
5
5
|
model: inherit
|
|
6
6
|
plugins: [kb-agi]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are the **kb-find-gaps** goal-agent for the
|
|
9
|
+
You are the **kb-find-gaps** goal-agent for the nuStack knowledge hub. You have exactly one job: find what the vault should hold but doesn't, and surface it.
|
|
10
10
|
|
|
11
11
|
## First, read the contract
|
|
12
12
|
|
|
@@ -6,7 +6,7 @@ model: inherit
|
|
|
6
6
|
plugins: [kb-agi]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are the **kb-fix-links** goal-agent for the
|
|
9
|
+
You are the **kb-fix-links** goal-agent for the nuStack knowledge hub. One job: keep the note graph sound — no dead links, no orphans.
|
|
10
10
|
|
|
11
11
|
**Read first:** `meta/guidance.md` (the note model) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
|
|
12
12
|
|
|
@@ -6,7 +6,7 @@ model: inherit
|
|
|
6
6
|
plugins: [kb-agi]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are the **kb-refresh-frontdoor** goal-agent for the
|
|
9
|
+
You are the **kb-refresh-frontdoor** goal-agent for the nuStack knowledge hub. One job: keep the entry points pointing at the right notes.
|
|
10
10
|
|
|
11
11
|
**Read first:** `meta/guidance.md` (the note model, `canonical` hint) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
|
|
12
12
|
|
|
@@ -6,7 +6,7 @@ model: inherit
|
|
|
6
6
|
plugins: [kb-agi]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are the **kb-refresh-summaries** goal-agent for the
|
|
9
|
+
You are the **kb-refresh-summaries** goal-agent for the nuStack knowledge hub. One job: keep summary notes current with the raw material beneath them.
|
|
10
10
|
|
|
11
11
|
**Read first:** `meta/guidance.md` (the note model, the `maturity` ladder) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
|
|
12
12
|
|
|
@@ -6,7 +6,7 @@ model: inherit
|
|
|
6
6
|
plugins: [kb-agi]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
You are the **kb-sync-metadata** goal-agent for the
|
|
9
|
+
You are the **kb-sync-metadata** goal-agent for the nuStack knowledge hub. One job: keep folder `metadata.md` files honest.
|
|
10
10
|
|
|
11
11
|
**Read first:** `meta/guidance.md` (the note model + the fixed `metadata.md` shape) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
|
|
12
12
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nurix/etna",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.6",
|
|
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,86 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: boundaries
|
|
3
|
-
description: The technology-aware Application Boundary Scale — the knowledge the boundary-mapper agent applies when generating docs/boundaries/. Maps each technology to its application boundaries (what ripples when touched), a doc-mode (point vs transcribe), and a default severity that drives introspect's review depth. Seeded for react-router, redux-toolkit, vite, shadcn/ui, express, django, fastapi, plus the stack-independent `domain` category (the information-architecture entity model). Use when baselining or extending a repo's boundary set, or when deciding whether a change touches a protected boundary.
|
|
4
|
-
plugins: [nurix-harness]
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Boundaries — the Application Boundary Scale
|
|
8
|
-
|
|
9
|
-
A **boundary** is a horizontal cross-cutting contract that multiple modules touch. Touching it ripples outward, so it must be documented and protected. This skill is the *knowledge*; the `boundary-mapper` agent is the *process* that applies it to a repo, writing one file per boundary into `docs/boundaries/`.
|
|
10
|
-
|
|
11
|
-
This skill exists because the dangerous boundaries are the invisible ones. A team writes a guardrail for "auth" but never for "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.
|
|
12
|
-
|
|
13
|
-
## Two categories
|
|
14
|
-
|
|
15
|
-
| Category | Determined by | How `boundary-mapper` finds it |
|
|
16
|
-
|---|---|---|
|
|
17
|
-
| **technology** | the stack | detect from `package.json` + source tree |
|
|
18
|
-
| **domain** | the product's information architecture, independent of stack | read ADRs, doctrine, the entity/contracts definitions — **not** stack detection |
|
|
19
|
-
|
|
20
|
-
The **domain** boundary (the IA entity model) is usually the *highest-severity boundary in the whole repo* and is the cleanest bridge from Brainstorming Mode (which shapes the IA) to the boundary set (which `introspect`/`contract-monitor` enforce).
|
|
21
|
-
|
|
22
|
-
## doc-mode: `point` vs `transcribe`
|
|
23
|
-
|
|
24
|
-
- **`point`** — *self-locating* shapes a reader finds unaided (DB schema → `schema.ts`/`models.py`; routes → the router file). The boundary file is **pointer (`file:line`) + invariants + checklist**. Never transcribe — the code is source-of-truth and a copy rots on the next push/codegen.
|
|
25
|
-
- **`transcribe`** — *synthesized* contracts with no single code home (the composed Redux store tree, the API response envelope, the IA relationship/topology, tenancy). Transcribe canonically; the boundary file then owns the shape and feature docs link up.
|
|
26
|
-
|
|
27
|
-
## The scale
|
|
28
|
-
|
|
29
|
-
Each entry: boundary type(s) · where it lives · doc-mode · default severity · what a change triggers.
|
|
30
|
-
|
|
31
|
-
### domain (stack-independent)
|
|
32
|
-
|
|
33
|
-
| Boundary | Lives in | doc-mode | Severity | A change triggers |
|
|
34
|
-
|---|---|---|---|---|
|
|
35
|
-
| **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 |
|
|
36
|
-
| **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 |
|
|
37
|
-
|
|
38
|
-
### technology
|
|
39
|
-
|
|
40
|
-
| Tech | Boundary | Lives in | doc-mode | Severity | A change triggers |
|
|
41
|
-
|---|---|---|---|---|---|
|
|
42
|
-
| `react-router` | route tree | router config (self-locating) | `point` | MED | deep-linking, auth guards, redirects, lazy boundaries |
|
|
43
|
-
| `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 |
|
|
44
|
-
| `vite` | dev proxy list, `VITE_` env prefix, path aliases | `vite.config` (self-locating) | HIGH | `point` | a new backend mount must be added to the proxy list; env prefix governs what reaches the client |
|
|
45
|
-
| `shadcn/ui` | `components.json`, generated `ui/` primitives, theme tokens | self-locating | LOW | `point` | `ui/` is generated — don't hand-edit, re-run the CLI; tokens in `:root`/`.dark` are the contract |
|
|
46
|
-
| `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 |
|
|
47
|
-
| `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 |
|
|
48
|
-
| `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 |
|
|
49
|
-
| `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 |
|
|
50
|
-
| `@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 |
|
|
51
|
-
|
|
52
|
-
Extend the scale by adding a row (and, for a new technology, a short pack describing where its boundaries live and the safe-change checklist). The instructions must be **technology-specific, never vague** — "middleware order is parsers→custom→routes→error-handler-last" beats "be careful with middleware."
|
|
53
|
-
|
|
54
|
-
## Boundary file template
|
|
55
|
-
|
|
56
|
-
`boundary-mapper` writes one file per boundary using this shape:
|
|
57
|
-
|
|
58
|
-
```markdown
|
|
59
|
-
# <Boundary name>
|
|
60
|
-
|
|
61
|
-
[BOUNDARY: <type> · <CRITICAL|HIGH|MED|LOW>]
|
|
62
|
-
|
|
63
|
-
**Bounds.** <which modules / planes sit on each side>
|
|
64
|
-
|
|
65
|
-
## Shape
|
|
66
|
-
<transcribed contract, OR a `file:line` pointer with one-line orientation>
|
|
67
|
-
|
|
68
|
-
## Invariants
|
|
69
|
-
<what must hold>
|
|
70
|
-
|
|
71
|
-
## Blast radius
|
|
72
|
-
<what breaks, and where, if violated>
|
|
73
|
-
|
|
74
|
-
## Safe-change checklist
|
|
75
|
-
- [ ] <step>
|
|
76
|
-
- [ ] <step>
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
`docs/boundaries/README.md` indexes every boundary (name · type · severity) and records which technology packs are active.
|
|
80
|
-
|
|
81
|
-
## How the pieces connect
|
|
82
|
-
|
|
83
|
-
- `boundary-mapper` (agent) detects the stack + IA and applies this scale to write `docs/boundaries/`.
|
|
84
|
-
- `introspect` (skill) reads `docs/boundaries/` before implementation; the boundary **severity** sets its review depth.
|
|
85
|
-
- `contract-monitor` (agent) scans the live codebase against `docs/boundaries/` after changes land, per boundary type.
|
|
86
|
-
- The **maintenance** agent flags when a boundary file drifts from code; `boundary-mapper` update-mode fixes it.
|