@nurix/etna 0.2.1 → 0.3.2

package/data/harnesses/code/skills/technical-brainstorm/greenfield.md

@@ -0,0 +1,99 @@
+# Greenfield writing doctrine
+
+> **The reader has no past.** They've never seen an earlier version of the system, never heard of the alternative you considered, never knew about the repo you were going to fold in. Write for them.
+
+For projects with nothing built yet — no production deploys, no users, no legacy code — architecture docs describe the system as it **will be**, in present tense. The temptation to narrate the design journey ("we considered X, chose Y, dropped Z") produces documents full of phantoms — references to things the reader has no way to imagine.
+
+These rules apply equally to the first draft and to subsequent edits. After every design decision, the architecture doc should look as though the chosen option was always the plan.
+
+---
+
+## The rule
+
+Describe what the system **is** (or will be — same thing in greenfield). Never describe what it isn't, used to be, replaces, supersedes, or is migrating from.
+
+There is no past tense in a doc for software that doesn't exist yet.
+
+---
+
+## Banned patterns
+
+| Don't write | Why it's wrong | Write instead |
+|---|---|---|
+| "X replaces Y" / "X supersedes Y" | Reader doesn't know Y. | "X is the [role]." |
+| "Previously planned" / "originally proposed" / "we used to" | There is no previous. | Describe the current plan. |
+| "What was dropped" / "What we ruled out" sections | Only useful when readers carry a stale model. | Move reasoning to `decisions.md` if load-bearing; otherwise delete. |
+| `~~strike-through~~` text | Tracks edits for live readers; pollutes fresh docs. | Delete the struck text. Keep the surviving prose. |
+| "ex-Foo", "from ex-Bar" annotations on packages | Repo-fold bookkeeping. | Just name the package. |
+| "Folded into monorepo" / `import-legacy.sh` / migration scripts | Migration mechanic, not architecture. | Describe the monorepo as the steady state. |
+| "v1 vs v2" / "future migration target" | Implies one is becoming the other. | Describe v1. Phase-2 ideas can be a "future scope" subsection without "migration" framing. |
+| "(existing — `~/dev/foo`)" / "no build needed" markers | Differentiates from non-existing; in greenfield everything is to-build. | Just list the service. |
+| "There is no foo_table" / "we don't have a foo service" | Reader didn't expect one. | Don't mention it. |
+| "Per Decision-N resolution" inline citations on every paragraph | Architecture doc isn't a decision log. | Plain prose. One cross-ref per section, only when the *why* is non-obvious. |
+| "Resolved (was: open question)" / "(retired)" markers | Edit-history bookkeeping. | Delete — the resolution **is** the doc now. |
+| "What this kills" / "Trade-off accepted" headings | Decision-capture format leaking into architecture. | Keep these in `decisions.md` only. |
+| "We no longer X" / "X is no longer needed" | Reader had no expectation that X existed. | Don't mention X. |
+| "Renamed from foo to bar" / "(formerly known as …)" | The rename doesn't matter — only the current name does. | Use the current name. |
+
+---
+
+## Smell-words grep
+
+`stop` runs this automatically. Manual invocation:
+
+```sh
+grep -rEni \
+  'replaces|supersedes|superseded|previously|formerly|originally proposed|what was dropped|fully retired|~~|ex-[a-z-]+|folded in|import-legacy|migration target|migrate from|no longer|we used to|resolved per|renamed from|formerly known' \
+  plan/
+```
+
+In a clean greenfield architecture doc, this should return no hits in `01–NN` numbered docs.
+
+Hits **are** acceptable in:
+- `decisions.md` — scoped to a specific decision-capture entry.
+- `rejected.md` — scoped to a rejected alternative.
+- `references.md` — describing external prior art.
+- Commit messages and PR descriptions.
+- `./plan/sources/` — copies of input documents (not authored under these rules).
+
+---
+
+## Where the past DOES belong
+
+- `decisions.md` — alternatives + why the chosen option won, **only** when the reasoning isn't obvious from the architecture itself.
+- `rejected.md` — paths considered and rejected.
+- `references.md` — external prior art.
+- Commit messages, PR descriptions — what changed and why; lives in git, not docs.
+
+These are the only four places. Architecture docs (`01-foo.md`, `02-bar.md`, ...) are present-tense.
+
+---
+
+## What's still allowed (don't over-correct)
+
+- **Forward planning that names a phase** ("ships in M7 so the bus already knows about `lead.created` when CRM sync arrives") — describes a positive future, not a past.
+- **Constraint statements** ("we accept a 5-second tile lag for predictable server load") — current tradeoffs, stated as facts. Live in `decisions.md`, not architecture.
+- **Cross-refs** ("see `04 §4.3`") — pointers, not history.
+- **Negative assertions about external systems** ("the upstream service has no native fan-in") — describing a real third-party limitation is fine.
+- **Future-scope subsections** ("Phase 2 considerations") — labelled clearly, not framed as migrations.
+
+---
+
+## Before merging an architecture doc, ask
+
+1. If a brand-new collaborator read this section cold, would they need to know about the alternative I'm comparing to? If no, delete the comparison.
+2. Does the section read as present-tense description, or as a story of "we went from X to Y"? Rewrite the story form.
+3. Are there strike-throughs? Delete them.
+4. Does an open-questions list still contain resolved items? Move them to `decisions.md` and drop from the list.
+5. Are there inline "(per Decision-X)" citations sprinkled through the prose? Strip — keep at most one cross-ref per section.
+
+---
+
+## Why this matters
+
+A greenfield doc that reads like a migration guide signals two things to a new reader:
+
+1. **There is hidden context I don't have.** Every "previously" / "replaces" makes them wonder what they're missing.
+2. **The author is still in the middle of deciding.** Strike-throughs and "(resolved)" markers feel provisional.
+
+Both undermine the doc's authority. A clean greenfield doc reads as an act of architecture, not an act of revision.

package/data/harnesses/code/skills/technical-brainstorm/templates/backlog.md

@@ -0,0 +1,39 @@
+# Backlog
+
+This file is the **forward-looking list of deferred-but-planned items** — work the team intends to build, but not in the current scope. It complements `non-goals.md` (which holds the scope-creep guards: things we are **not** building) and `rejected.md` (which holds paths we considered and chose against). Use the right pillar:
+
+| Pillar | Semantics |
+|---|---|
+| `backlog.md` (this file) | "We **will** build this, just **later**." Deferred to a known future milestone. Roadmap forward. |
+| `non-goals.md` | "We deliberately are **not** building this." Scope guard. May never be built. |
+| `rejected.md` | "We considered this path and chose another." Past-tense alternative. |
+
+If you can't tell which file an item belongs in, ask: *"Is the plan to build this eventually?"* If yes → backlog. If no but could change → non-goals. If we already weighed it against an alternative → rejected.
+
+Backlog items carry four load-bearing fields. **Target milestone** names the future bucket (`v1.1`, `M2`, `TBD`); **Why deferred** explains the reason it isn't in the current scope (commonly: scope cut, depends on something else, waiting for user feedback, lower priority than current work); **Scope** sketches what the item actually includes — enough that a future planner can pick it up cold; **Re-evaluate when** is the trigger that promotes it from backlog to active work.
+
+When a backlog item is promoted (its milestone comes due), **delete it from this file** and either (a) seed a new round of intake questions in `questions.md` for the new scope, or (b) move the spec into a plan doc if the design is already mostly clear. Don't strikethrough, don't leave a "(promoted)" marker — same hygiene as resolved questions and triggered non-goals.
+
+If a backlog item turns out to be unworkable or unneeded, move it to `rejected.md` (not deleted silently) with the reason.
+
+---
+
+## B1 — [Title]
+
+**Target milestone.** [v1.1 / M2 / TBD]
+
+**Why deferred.** [The reason it isn't in current scope. Be specific: "scope cut to ship M0 by Q3"; "depends on X landing first"; "waiting for user feedback on whether this is actually needed"; "lower priority than the M0 critical path".]
+
+**Scope.** [What this item actually includes when it eventually gets built. Sketch enough that a future planner can pick it up cold. Bullet points are fine.]
+
+**Depends on.** [Optional. Other backlog items, milestones, or upstream features that need to land first. Drop the field if nothing.]
+
+**Re-evaluate when.** [The trigger that promotes this from backlog to active work. Tie to a milestone boundary, a metric, or an external event.]
+
+---
+
+## B2 — [Title]
+
+(same format)
+
+---

package/data/harnesses/code/skills/technical-brainstorm/templates/decisions.md

@@ -0,0 +1,42 @@
+# Decisions
+
+This file is the **append-only ledger of resolved decisions**. Every decision the brainstorm produces lands here, with the reasoning that future-you will need to judge edge cases.
+
+Each entry has these load-bearing fields:
+
+- **Status** — `tentative | committed | rescinded`. New decisions land as `tentative` (no cascade dispatched, question stays open in `questions.md`). User explicitly says "commit" to lock in (cascade fires, question deletes). User explicitly says "rescind" to reverse (cascade reversals if previously committed, question restored if needed).
+- **Decision** — what was decided, in one or two sentences.
+- **Why** — the motivation: a past incident, a constraint, a deadline, a stakeholder ask. Without the *why*, decisions decay into rules no one understands.
+- **How to apply** — when and where this decision should shape future work. Without it, decisions get ignored at the boundaries where they matter most.
+
+This file is **append-only**. If a decision is reversed, mark it `STATUS: rescinded` with the reason — do not delete the entry. The ledger is a record of what was true (or proposed) when it was written. It is one of the four places inside the brainstorm folder where past tense is permitted (the others: `rejected.md`, `references.md`, git history).
+
+When a question in `questions.md` is resolved, the question is **NOT** immediately deleted — it is marked tentatively-answered (referenced by the new decision's `Resolves Q-N` field). The question is deleted only when the decision transitions to `committed`. This gives the user space to reverse a tentative call without restoring text by hand.
+
+---
+
+## D1 — [Title]
+
+**Status.** tentative
+
+**Decision.** [What was decided, in one or two sentences.]
+
+**Why.** [The motivation — past incident, constraint, deadline, stakeholder ask. The reason future-you needs to judge edge cases.]
+
+**How to apply.** [When and where this decision shapes future work. Be specific — name the files, layers, or situations where this rule kicks in.]
+
+**Resolves.** Q1 (deleted from `questions.md` on commit).
+
+**Alternatives considered.** [Optional. Reference `rejected.md` entries if substantial. Skip if obvious.]
+
+**Committed on.** [YYYY-MM-DD — filled when STATUS transitions to committed. Omit until then.]
+
+**Rescinded on.** [YYYY-MM-DD with one-line reason — filled when STATUS transitions to rescinded. Omit until then.]
+
+---
+
+## D2 — [Title]
+
+(same format)
+
+---

package/data/harnesses/code/skills/technical-brainstorm/templates/doctrine.md

@@ -0,0 +1,31 @@
+# Doctrine
+
+This file holds **stable principles that pre-answer future questions**. When a new question arises during a brainstorm, check here first — the doctrine may already settle it without a full debate.
+
+Doctrine entries should be **rare and durable**. They are not preferences ("I like Postgres") and not one-off picks ("we picked Temporal for this project"). They are statements that apply across many decisions: *"we never self-host stateful services in M0–M3 because operating burden outweighs cost savings at our scale."* A doctrine that gets revised every other week isn't doctrine — it's a preference in disguise. Demote it to `decisions.md`.
+
+Add to doctrine only when a principle has either (a) been validated across multiple decisions in this project or others, or (b) is imposed from outside (compliance, vendor lock-in, team size) and won't change without a major shift. Doctrine pre-empts argument; if you're not confident the principle will hold for the next six months, don't write it here.
+
+Each entry carries **Principle** (the one-line statement), **Why** (the reason this is principle, not preference — often a past incident, a hard constraint, or an accepted tradeoff), and **Applies when** (the triggers, so a reader recognizes "ah, this is a doctrine question" rather than re-debating from scratch). An optional **Exceptions** field is allowed but suspicious — if a principle has many exceptions, it's mis-stated.
+
+Examples of real doctrine entries from past projects: *"Temporal IS the trace — no separate APM tool."* — *"No Terraform; deploys are wrangler + GitHub Actions only."* — *"Secrets only via wrangler, never in code or env files."* — *"Buy-not-build for non-core capabilities until paying-customer signal justifies otherwise."*
+
+---
+
+## P1 — [Principle name]
+
+**Principle.** [One-line statement of the rule.]
+
+**Why.** [The reason this is a principle, not a preference. Often a past incident, a hard constraint, or a tradeoff the team has already accepted.]
+
+**Applies when.** [Triggers — situations where this principle should be invoked.]
+
+**Exceptions.** [Optional. Cases where the principle deliberately does not apply. If you find yourself listing many exceptions, the principle is probably mis-stated.]
+
+---
+
+## P2 — [Principle name]
+
+(same format)
+
+---

package/data/harnesses/code/skills/technical-brainstorm/templates/glossary.md

@@ -0,0 +1,19 @@
+# Glossary
+
+This file collects **terms with project-specific meaning** — words whose definition in this project diverges from their general industry sense, or whose meaning is short and opaque enough that re-explaining it across docs wastes time.
+
+The glossary exists to prevent the quietest and most expensive kind of design drift: two collaborators using the same word for different things. By the time you notice — usually mid-implementation — the cost of resolving the ambiguity is much higher than the cost of writing the entry that would have prevented it. So when you catch yourself saying "by X I mean…" for the second time, add the entry.
+
+Do **not** catalog every term. Add to the glossary only when:
+- A term has been used to mean two different things in the same session.
+- A term's meaning here diverges from the standard industry sense (e.g., `subscriber` meaning a webhook destination rather than a pub/sub consumer).
+- A short term names a specific concept that would otherwise need re-defining across docs (e.g., a node category name, an internal product term).
+
+Entries are intentionally terse: one term, one line of meaning. Long explanations belong in plan docs or `decisions.md`.
+
+---
+
+| Term | Meaning |
+|---|---|
+| (example: `studio`) | the canonical task queue for non-publish work — see `04-runtime.md` |
+| (example: `subscriber`) | a webhook destination registered against an event kind, distinct from a `webhook` which is the inbound side |

package/data/harnesses/code/skills/technical-brainstorm/templates/inventory.md

@@ -0,0 +1,44 @@
+# Inventory
+
+This file is the **authoritative list of components in scope** — services, repos, packages, databases, external integrations. It answers the question "what are we actually building?" and stops the team from inventing services that already exist or "folding in" things that should stay separate.
+
+The inventory is grouped by category (application monorepo, edge services, shared packages, managed externals, reference-only prior art). Each entry carries a **status**:
+
+- **build** — in scope, we're constructing this in this project.
+- **external** — managed elsewhere (third-party SaaS, another team's service). We integrate with it but don't own it.
+- **reference** — prior art we read or copy patterns from but do not deploy.
+
+Do **not** mark items as "retired", "deprecated", or "previously planned" — if it's not being built or used, omit it. (See the greenfield doctrine.) The inventory describes the steady state, not the history of how the steady state was arrived at.
+
+When scope changes (a service moves from "build" to "external", a non-goal flips to a build, a planned component gets dropped), update this file immediately and run a semantic sweep across plan docs.
+
+---
+
+## A. Application monorepo
+
+| Name | Status | Notes |
+|---|---|---|
+| (example: `apps/gateway`) | build | (one-line role) |
+| (example: `apps/web`) | build | (one-line role) |
+
+## B. Edge services
+
+| Name | Status | Notes |
+|---|---|---|
+
+## C. Shared packages
+
+| Name | Status | Notes |
+|---|---|---|
+
+## D. Managed externals
+
+| Name | Status | Notes |
+|---|---|---|
+| (example: Temporal Cloud) | external | (one-line — what we use it for) |
+
+## E. Reference / prior art
+
+| Name | Status | Notes |
+|---|---|---|
+| (example: `~/dev/vibe/foo-poc`) | reference | (what pattern we borrow from it) |

package/data/harnesses/code/skills/technical-brainstorm/templates/milestones.md

@@ -0,0 +1,43 @@
+# Milestones
+
+This file holds **sequencing only** — what ships in what order, with the dependencies that justify the order. Scope of each milestone lives in the plan docs; this file is the schedule.
+
+Every milestone names three things: a **Goal** (one line — what this milestone proves or unlocks), **Depends on** (the prior milestones, or "nothing" for M0), and **Open questions** (Q-numbers from `questions.md` that must be resolved before this milestone can start). The open-questions list is what makes a milestone "ready to start" — when the list is empty, the milestone is unblocked.
+
+The **Ships** field captures the concrete artifact: "auth + empty dashboard deployed to staging" is useful; "MVP foundation" is not. Concrete ship definitions make it visible when a milestone has crept.
+
+Order matters and the order is enforced by `Depends on`. If you ever notice that M3 could ship before M2, the sequencing is wrong — fix it here. Milestones do not exist to chunk work into nice-sized bites; they exist to make dependency order explicit so the team can parallelize what's parallelizable and serialize what isn't.
+
+When a milestone ships, do **not** mark it "complete" with a strikethrough or "(shipped)" marker. The plan docs for that milestone should already describe the steady state in present tense; the milestone entry stays here as schedule, not as history. (Git tags and PR history capture "what shipped when" — this file is forward-looking.)
+
+---
+
+## M0 — [Name]
+
+**Goal.** [One-line — what this milestone proves or unlocks.]
+
+**Depends on.** Nothing (this is the start).
+
+**Open questions.** Q1, Q2, Q3 — see `questions.md`.
+
+**Ships.** [Concrete deployed artifact.]
+
+---
+
+## M1 — [Name]
+
+**Goal.** [One-line.]
+
+**Depends on.** M0.
+
+**Open questions.** Q4, Q5 — see `questions.md`.
+
+**Ships.** [Concrete deployed artifact.]
+
+---
+
+## M2 — [Name]
+
+(same format)
+
+---

package/data/harnesses/code/skills/technical-brainstorm/templates/non-goals.md

@@ -0,0 +1,21 @@
+# Non-goals
+
+This file is the **explicit list of things we are not building** in the current scope, with the reason for each. It is the mirror of `inventory.md`: where inventory says "this is in scope", non-goals say "this looked plausible but is deliberately out".
+
+Non-goals carry real weight. Every entry here is a constraint that future decisions should respect — a scope-creep guard. The reason field is load-bearing: without it, a non-goal looks like an arbitrary "no" that future-you will second-guess at the first complication. With the reason, future-you knows whether the non-goal still holds when circumstances change.
+
+Each non-goal should include a **Re-evaluate when** clause where applicable. Non-goals are not permanent vows; they are scope decisions tied to current constraints. When the constraint changes (a customer signs in a new region, a competitor ships the feature, infrastructure costs drop), the non-goal may move into scope. The re-evaluate clause names the trigger so the team doesn't carry a stale non-goal forever.
+
+At milestone boundaries, scan this file. If a non-goal's re-evaluate trigger has fired, move the item to `inventory.md` with status `build` and delete the non-goal entry here — do not strikethrough, do not leave a "(promoted)" marker.
+
+---
+
+- **No multi-region writes in M0.**
+  *Reason:* cost > benefit until 3+ paying customers in distinct regions.
+  *Re-evaluate when:* second paying customer signs in a non-primary region.
+
+- **No mobile app.**
+  *Reason:* product hypothesis is desktop-first; no validated mobile demand.
+  *Re-evaluate when:* >20% of dashboard sessions are mobile UA.
+
+- (add more here)

package/data/harnesses/code/skills/technical-brainstorm/templates/plan-doc.md

@@ -0,0 +1,61 @@
+# NN — [Domain name]
+
+> This is a **plan doc**, not a pillar. It describes one domain of the system (e.g., runtime, storage, ingress) in present tense, as if the chosen design were always the plan. Plan docs do not host their own "open questions" sections — those live in `pillars/questions.md`. Plan docs do not narrate the design journey — that lives in `pillars/decisions.md` and `pillars/rejected.md`. Plan docs describe what the system is.
+>
+> Number plan docs sequentially: `01-foo.md`, `02-bar.md`, ... Each plan doc owns one domain. If a section grows past ~500 lines, split it into two plan docs rather than letting it sprawl.
+>
+> Cross-reference other plan docs with `see 04 §3.2` — pointer, not duplicated content.
+
+---
+
+## On versioning iterations
+
+If this plan doc goes through a substantial rewrite (decision reversal, structural shift, ≥3 sections change together), preserve the evolution by saving a new version as `NN-domain-v0.X.md` rather than overwriting. Examples:
+
+```
+01-architecture-v0.1.md       ← initial draft
+01-architecture-v0.2.md       ← second draft after architecture change
+01-architecture-v0.3.md       ← current draft (the one to read)
+```
+
+Each version stays in the folder. Readers can follow v0.1 → v0.2 → v0.3 in order to see exactly how the design evolved. The current version's top-of-file frontmatter or first line notes its status:
+
+```markdown
+# 01 — Architecture (v0.3)
+
+> **Status:** Current draft. Supersedes v0.1 and v0.2. v0.4 will narrow content.
+```
+
+Skip versioning for small edits (typos, single-section polish, find-and-replace). The versioning pattern is for substantial rewrites that warrant a separate readable artifact.
+
+The `stop` step in the brainstorm offers to prune older versions if you want to simplify the final handoff. Keeping them preserves the design rationale across long sessions; pruning them produces a clean steady-state.
+
+---
+
+## 1. What this is
+
+[One paragraph in present tense describing what this domain is, what it does, and who depends on it. No "we decided" framing, no comparisons to alternatives.]
+
+## 2. Components
+
+[Subsystems, services, or modules inside this domain. Each gets a subsection with: name, role, what it owns, what it depends on. Diagrams are OK if they help.]
+
+## 3. Interfaces
+
+[How other domains interact with this one. APIs, queues, events, file formats. Stable contracts only — speculative ones go in `pillars/questions.md`.]
+
+## 4. Constraints accepted
+
+[Tradeoffs that shape the design. Phrased as current fact: "we accept a 5-second lag for predictable throughput", not "we considered streaming but chose batch".]
+
+## 5. Future scope (optional)
+
+[Cleanly labelled phase-2 ideas. Not framed as migrations. Skip the section if there's nothing here.]
+
+---
+
+## Open questions for this domain
+
+See [`pillars/questions.md`](./pillars/questions.md): Q-N, Q-M, ...
+
+(One line, never more. The plan doc never hosts question bodies.)

package/data/harnesses/code/skills/technical-brainstorm/templates/questions.md

@@ -0,0 +1,84 @@
+# Open Questions
+
+This file is the **live ledger of unresolved concerns and pending decisions**. Every open design question or worry lives here, and only here — plan docs never host their own questions, they link back to this file with the relevant Q-numbers.
+
+Each question is **self-contained**: full text, optional options, optional lean, and where the resolution lands. You should be able to read any question and understand it without opening another doc. Duplicating one paragraph of context is much cheaper than the cognitive cost of context-switching.
+
+**In Explore mode**, questions land here in the user's framing — possibly just a concern stated in prose, without Options or Lean. That is fine. Captured concerns are valid questions even when their shape is fuzzy. Resist the urge to immediately structure them into A/B/C/D choices; that happens when the user invites decide-mode for a specific question.
+
+When a question transitions through a decision flow:
+1. User signals "let's resolve Q-N" → enter decide mode for this Q.
+2. Decision lands in `decisions.md` with `STATUS: tentative`. **The question stays here**, in a tentatively-answered state (cross-reference the D-N).
+3. User says "commit D-N" → the question is **deleted** from this file. No strikethrough, no "(resolved)" marker.
+4. User says "rescind D-N" before commit → the question stays, the decision is marked rescinded.
+
+When you add a new question, fill in fields the user has actually given you. Leave others blank. The dependency graph (`Blocks.` field) is computed only when the user moves into decide mode and needs sequencing.
+
+---
+
+## Conventions
+
+**Group questions by domain** when the list grows past ~10 entries. Use `## Category` headers (e.g. `## Data & Schema`, `## Runtime`, `## Connectors`). Categories are project-specific.
+
+**Question ID** is `QN` where N is the next free integer. IDs are stable for as long as the question is open. On commit-delete, the ID disappears with the question — do not reuse it.
+
+**Question body fields** (per entry):
+
+- **Question.** Full prose, may be multi-paragraph. Repeat context if needed. Use the user's words when capturing in Explore mode.
+- **Options.** *(optional)* Lettered list (A / B / C ...) with one-line description per option. Add only when the user has named alternatives, or when entering decide mode for this question.
+- **Lean.** *(optional)* The user's current preference, one line. Drop the field entirely if no lean exists yet — don't write "none yet". This field reflects the user's lean, not the skill's.
+- **Claude's take.** *(optional, OPT-IN ONLY)* The skill's recommendation. **Default: do not write this field.** Emit only when the user explicitly asks "what would you recommend?" / "what's your take?" / similar on this specific question. Phrase as a clear pick + one-line reason. If the field becomes stale (options change, scope shifts), delete it.
+- **Tentatively answered by.** *(only when a tentative D-N exists)* Cross-reference to `decisions.md`. Marks the question as in-flight rather than fully open.
+- **Resolution lands in.** *(optional)* Target doc + section (e.g. `04-runtime.md §3.2`). Tells the resolver where to absorb the answer.
+- **Blocks.** *(optional)* Milestone (`M0`) or other Q-numbers (`Q5, Q7`) that depend on this. Empty = "nothing yet".
+
+**Extension sections** beyond plain questions are allowed:
+
+- `## Upstream feature requests` — items that aren't questions we own; they're features we need from upstream services. Use IDs like `U-foo-1`.
+- `## Doc completeness follow-ups` — work items that aren't decisions but should not be forgotten. Use IDs like `F1`, `F2`.
+
+Resolved upstream-feature items and completed follow-ups get **deleted**, same rule as questions.
+
+---
+
+## Q1 — [Title]
+
+**Question.** [Full text. Repeat context if needed — a future reader should be able to read this without leaving the doc. In Explore mode, capture in the user's words.]
+
+**Options.** *(optional — only when named by the user or entering decide mode)*
+- A. [Option A — what it means in one line]
+- B. [Option B]
+- C. [Option C]
+
+**Lean.** *(optional, user's lean)*
+
+**Tentatively answered by.** *(only if a tentative D-N exists)*
+
+**Resolution lands in.** *(optional)* `XX-foo.md` §N
+
+**Blocks.** *(optional)* [Milestone (e.g., M0) or other Q-numbers.]
+
+---
+
+## Q2 — [Title]
+
+(same format)
+
+---
+
+## Upstream feature requests *(optional section)*
+
+### U-foo-1 — [Title]
+
+[What we want from the upstream service.]
+
+**Why we want it.** [Reason — usually a current workaround that's costing us something.]
+
+[Current status: filed, tracked, ETA, etc.]
+
+---
+
+## Doc completeness follow-ups *(optional section)*
+
+- **F1** — [Doc name + one-line scope]. [What triggers writing it.] [Which milestone it must precede.]
+- **F2** — [Doc name + one-line scope]. [What triggers writing it.] [Which milestone it must precede.]

package/data/harnesses/code/skills/technical-brainstorm/templates/references.md

@@ -0,0 +1,28 @@
+# References
+
+This file collects **external prior art** — repos, docs, papers, talks — with one-line pointers to what we use each for. Reference implementations beat invented solutions: if someone has already solved the problem you're about to design, the right move is to link it here and use it, not re-derive.
+
+References are not bookmarks. Every entry should answer the question "what specific pattern, idea, or implementation do we lift from this?" A reference without that grounding decays into noise. If you can't write the one-line "what we use it for", you probably don't need the entry.
+
+References to **source materials** copied into `./plan/sources/` during the session also live here — point at the local copy, not the original location. This keeps the brainstorm self-contained.
+
+When a referenced thing changes (renames, moves, deprecation), **update or remove the entry**. A stale reference that no longer points at what the description claims is worse than no reference — it teaches the reader to distrust the file.
+
+---
+
+## Internal repos / paths
+
+- `~/path/to/repo` — [what pattern we borrow]
+- `~/path/to/another` — [what pattern we borrow]
+
+## Source materials (this session)
+
+- `./plan/sources/[file]` — [original location, why it's relevant]
+
+## External docs
+
+- `https://example.com/foo` — [what we use it for]
+
+## Papers / talks
+
+- [Title] — [link or citation] — [the specific idea we're applying]

package/data/harnesses/code/skills/technical-brainstorm/templates/rejected.md

@@ -0,0 +1,29 @@
+# Rejected alternatives
+
+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."
+
+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.
+
+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.
+
+If circumstances change and a rejected path becomes attractive again, **do not silently revive it**. Add a new question to `questions.md` that references the rejection here, and resolve it explicitly. The new decision can override the rejection — but it should override, not pretend the rejection never happened.
+
+---
+
+## R1 — [Rejected option]
+
+**Considered.** [What was proposed.]
+
+**Rejected because.** [The reason. Be specific.]
+
+**Re-evaluate if.** [What would change to make this viable.]
+
+**Came up during.** [Q-number or D-number for context.]
+
+---
+
+## R2 — [Rejected option]
+
+(same format)
+
+---

package/data/harnesses/code/skills/technical-brainstorm/templates/state.md

@@ -0,0 +1,8 @@
+STATE: open
+MODE: explore
+SESSION STARTED: YYYY-MM-DD
+SESSION CLOSED:
+CURRENT TOPIC: (one-line summary — updated on every detected topic shift)
+LAST UPDATED: YYYY-MM-DD
+CASCADE LOCKS: none
+CASCADE QUEUE: none

package/data/harnesses/code/skills/workflow-mapper/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: workflow-mapper
 description: Discover and document all major workflows in a codebase by tracing call chains from user action to database/external system. Produces mermaid sequence diagrams and markdown documentation. Use when the user asks to map workflows, trace flows, document sequences, understand how features work end-to-end, or generate architecture diagrams. Triggers on "map workflows", "trace workflows", "workflow diagram", "sequence diagram", "how does X work end-to-end", "document flows", "codebase workflows", "how does this feature work", "trace the request flow", "show me the call chain", "what happens when a user does X", "end-to-end flow".
+plugins: [nurix-harness]
 ---
 
 # Workflow Mapper Skill

package/data/harnesses/kb-agi/CLAUDE.md

@@ -1,4 +1,19 @@
-# nupilot Knowledge Hub — router
+---
+name: kb-agi
+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.
+version: 0.1.0
+keywords:
+  - harness
+  - knowledge-base
+  - obsidian
+  - vault
+  - self-improving
+  - kb
+  - nurix
+plugin: kb-agi
+---
+
+# nuStack Knowledge Hub — router
 
 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.
 

package/data/harnesses/kb-agi/agents/kb-agi-init.md

@@ -3,6 +3,7 @@ name: kb-agi-init
 description: Initializes a kb-agi vault by scaffolding the meta/ control plane — the contract (guidance.md), the seed genre templates, the intent-index, and the sessions/ folder — from templates carried inline in this agent. Use on a fresh vault, or when the router reports that meta/guidance.md is missing. Triggers on "initialize kb-agi", "init the vault", "scaffold meta", "set up the control plane".
 tools: Read, Glob, Bash, Write
 model: inherit
+plugins: [kb-agi]
 ---
 
 You are the **kb-agi-init** agent. One job: stand up the `meta/` control plane a kb-agi vault needs to operate, then get out of the way. You run once per vault, and you are fully self-contained — every file you create is carried inline below, so you need no external templates.
@@ -150,7 +151,7 @@ Upkeep is run by the kb-agi agents (invoked by name); there is no `meta/goals/`
 ````markdown
 # genre — Sales
 
-The reader is positioning nupilot 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.
+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.
 
 **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…").
 
@@ -212,7 +213,7 @@ This is a living index. It is hand-maintained today and kept fresh by the `kb-re
 ---
 
 ## "I want to understand the product"
-_What nupilot is, what it can do, the claims and their proof._
+_What nuStack is, what it can do, the claims and their proof._
 
 - _populated on migration_
 

package/data/harnesses/kb-agi/agents/kb-catch-stale.md

@@ -3,9 +3,10 @@ name: kb-catch-stale
 description: Finds notes that have drifted out of date — a canonical note superseded by a newer one but never demoted, or a summary whose linked-down sources changed after it. Use to audit freshness. Reports by default; demotes/flags only when explicitly asked.
 tools: Read, Grep, Glob, Bash
 model: inherit
+plugins: [kb-agi]
 ---
 
-You are the **kb-catch-stale** goal-agent for the nupilot knowledge hub. One job: surface notes that have drifted out of date.
+You are the **kb-catch-stale** goal-agent for the nuStack knowledge hub. One job: surface notes that have drifted out of date.
 
 **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.