@nurix/etna 0.18.10 → 0.18.11

package/data/harnesses/mobile/skills/brainstorm/README.md

@@ -0,0 +1,136 @@
+# brainstorm
+
+A Claude Code skill that is a **thinking partner for designing software** — not a form to fill in. It runs one constant loop (distill → abstract → sync → record) over a conversation, files the thinking into a small set of substance-first pillars, and treats _coherence_ as a measurable target rather than a vibe.
+
+The point of v2 is a single inversion over v1: **the conversation is the work; the artifacts serve it.** v1 had grown into elaborate bookkeeping (a tentative/committed decision state machine, background cascade locks and queues, a 10-pillar eager bootstrap, an unconditional greenfield doctrine) wrapped around thinking that never had to happen. v2 deletes that machinery and keeps the loop.
+
+---
+
+## The loop (the only constant)
+
+Every turn, in every mode:
+
+1. **Distill** — fold what the user said into the pillars, in their framing, this turn.
+2. **Abstract** — name the latent structure they implied but didn't state (an entity relationship, an invariant, a principle). One offer per exchange.
+3. **Sync** — keep the pillars consistent with each other and with the basis (the sync agent, below).
+4. **Record** — writes happen in the turn that produced the information; nothing is hoarded for a session-end dump.
+
+Everything else — pillar count, ceremony, harvest — scales with the idea. The loop does not.
+
+---
+
+## Lifecycle
+
+Two subcommands, nothing else. The skill never auto-invokes on natural language.
+
+```
+/brainstorm start    # open a session (requires a basis)
+/brainstorm stop     # close a session
+```
+
+### The entry gate
+
+A session needs substance before it opens. `start` asks for a **basis**: a reference document, or a one-shot brain dump of the whole idea. If the user drip-feeds small action items (a bug fix, a single button), the skill says it's the wrong tool and **does not open** unless overridden. The basis _is_ the first dump — the skill distills it into the initial thesis and questions, so the first questions come from the user's own material, never from an empty template.
+
+### Intake frame
+
+After distilling the basis, one `AskUserQuestion` batch sets three dials:
+
+- **Complexity** (low / medium / high) — sets the default pillar surface.
+- **Build mode** (greenfield / brownfield / hybrid) — lands in `build.md`; opens or closes the execution sections and sets the writing posture.
+- **Mode** — where the idea lives right now (see below).
+
+Then the skill proposes an **aspect map** — the thinking dimensions for _this_ idea — which the user edits. The map drives the sync's coverage audit.
+
+### Modes (who drives)
+
+| Mode | Driver | When | Behavior |
+| --- | --- | --- | --- |
+| **dump** | user | idea is in their head | No questions mid-stream. Distill live, reflect back shape + contradictions + implications. |
+| **interview** | skill | idea is fuzzy | Question batches of 2–3, one aspect at a time, each answer distilled immediately. |
+| **probe** | skill | idea is drafted | Adversarial pass — flaws, edge cases, conflicts. Each finding becomes a question. |
+| **converge** | shared | closing | Burn down open questions into decisions or explicit parks; ends with a mandatory sync. |
+
+Mode switches on an explicit user word. On a strong signal the skill _offers_ a switch in one line; it never seizes it.
+
+---
+
+## Coherence (the doneness function)
+
+```
+coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
+```
+
+`questions.md` is the **single convergence currency**: flaws, gaps, contradictions, and uncovered aspects all funnel into it, whoever raised them. Convergence is one number going to zero. Zero means _"audited against the four sources and clean,"_ never _"nothing came to mind"_ — which is why the sync agent's audit contract is mandatory.
+
+---
+
+## The sync agent
+
+The background reconciler that replaces v1's cascade apparatus. One sync in flight at a time; at most one queued behind it. It runs after substantive writes, mandatorily on entering converge and at `stop`, and on demand. It audits exactly four sources:
+
+1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build.
+2. **Aspect coverage** — any mapped aspect with no content → a question.
+3. **Basis drift** — does the thesis still agree with the basis? Accidental divergence → a question.
+4. **Tech conflicts** — anything violating `tech.md` without a recorded deviation.
+
+It applies **scribe-calls** (edits that don't change the design) directly and notes them; it files **design-calls** (edits that change the idea) as questions and moves on — never interrupting to ask "apply now or defer?" Its one-line report ("4 edits · 2 new questions · 6 open · untouched: risks") is the only ambient convergence pressure the skill applies.
+
+---
+
+## Pillars (substance first, lazy by default)
+
+Always present: `thesis.md`, `questions.md`, `decisions.md`, `build.md`. Materialized at medium+ complexity: `domain-model.md`, `tech.md`. Lazy (materialize on first real content at any complexity): `doctrine`, `glossary`, `non-goals`, `backlog`, `rejected`, `references`, `milestones`.
+
+| File | Role |
+| --- | --- |
+| `thesis.md` | Running narrative of what we're designing + the aspect map. |
+| `questions.md` | Single convergence currency — every unresolved design call. |
+| `decisions.md` | Resolved calls with **Why** + **How to apply**. Append-only, no state machine. |
+| `build.md` | How the work executes: build mode, migration strategy, gotchas, rollout. |
+| `domain-model.md` | Information architecture — entities, relationships, cardinalities, state ownership. |
+| `tech.md` | Stack choices, seeded from harness rules; deviations recorded with whys. |
+| `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | As their templates describe. |
+
+The complexity dial sets _defaults_, not a cage — any lazy pillar materializes the moment the conversation produces content for it.
+
+---
+
+## Build modes (replacing the greenfield doctrine)
+
+v1 applied a present-tense "greenfield" writing doctrine unconditionally — which was a bug for brownfield work, where migration vocabulary is load-bearing. v2 folds this into `build.md` as a **mode** chosen at intake:
+
+- **greenfield** (default) — present-tense everywhere, no phantom history. Execution sections closed.
+- **brownfield** — migration vocabulary is legitimate in `build.md`; other pillars still describe the target.
+- **hybrid** — new surface on a live system; execution sections apply to the seams only.
+
+`build.md` also captures **gotchas** — execution hazards known now, before plan mode, because surfacing them in plan mode is too late.
+
+---
+
+## Harvest (optional)
+
+By default the session folder _is_ the product — self-contained, resumed by the next `/brainstorm start`. When the repo is v9-harnessed (`docs/architecture/` + `docs/modules/` exist) the skill _offers_ the harvest adapter at `stop`, which routes pillars into the doc tree (ADRs, module pillars, plans, the `boundary` skill). See `harvest.md`. The adapter is never assumed.
+
+---
+
+## Hard rules
+
+1. **No production code outside the session folder.** Illustrative snippets are fine inside it.
+2. **Speak English to the user; codes (`Q3`, `D7`) live in the files.**
+3. **`AskUserQuestion` appears in exactly three places:** the intake frame, interview mode, converge picks.
+4. **Suggested, never seized** — mode shifts, abstractions, probes are offered once.
+5. **Questions are the only convergence currency** — nothing pending may live only in the transcript.
+6. **No auto-invocation** — only `/brainstorm start` and `/brainstorm stop`.
+
+---
+
+## Files
+
+```
+brainstorm/
+├── SKILL.md      # the skill definition Claude Code loads (~1.8k words)
+├── README.md     # this file
+├── harvest.md    # optional v9 doc-tree adapter
+└── templates/    # pillar templates copied into the session folder on first use
+```

package/data/harnesses/mobile/skills/brainstorm/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: brainstorm
+description: Thinking-partner session for designing software. Invoked ONLY by explicit slash commands `/brainstorm start` and `/brainstorm stop` — never auto-invoke on natural-language phrases like "let's plan", "let's design", or "let's think through X". Entry requires a basis (a reference document or a one-shot brain dump); drip-fed action items are rejected as too small. Runs one constant loop (distill → abstract → sync → record) across four modes (dump / interview / probe / converge). Coherence = zero open questions after a fresh pillar sync. Pillar count scales with a complexity dial; refuses production code outside the session folder while open.
+argument-hint: "start | stop"
+---
+
+# Brainstorm
+
+Think with the user, then file — never the reverse. The artifacts exist to serve the conversation; the conversation never exists to populate artifacts. The constant across every scale of idea is **the loop**; everything else — pillar count, ceremony, harvest — scales with complexity.
+
+## The loop — every turn, every mode
+
+1. **Distill.** Fold what the user just said into the pillars, in _their_ framing, during the same turn.
+2. **Abstract.** Name the latent structure they implied but didn't state — entities and relationships ("an account has many leads" → `domain-model.md`), invariants, principles, terms. Offer at most one abstraction per exchange; it's a contribution, not a lecture.
+3. **Sync.** Keep the pillars consistent with each other and with the basis (see **The sync agent**).
+4. **Record.** Writes happen in the turn that produced the information — never accumulated for a session-end dump.
+
+Modes change _who drives_ and _how much gets asked_. The loop never stops.
+
+## Modes
+
+| Mode | Who drives | When | Behavior |
+| --- | --- | --- | --- |
+| **dump** | user | idea is in their head | No questions mid-stream. Distill live. After each chunk, reflect back: the shape, contradictions, implications. Distillation + reconciliation **is** active listening — never sit silent. |
+| **interview** | skill | idea is fuzzy | Question batches of 2–3 via `AskUserQuestion`, scoped to **one aspect at a time**. Distill each answer immediately. Questions derive from the basis and the pillars — never from a template inventory. |
+| **probe** | skill | idea is drafted, needs stress | Challenge it: flaws, edge cases, conflicts with `tech.md` / `doctrine.md` / the domain model. Each finding becomes a question (`Raised by: probe`) — file it and move on; don't demand resolution. |
+| **converge** | shared | closing in | Burn down open questions. `AskUserQuestion` allowed for picks. Each resolution → a decision with **Why** + **How to apply**, or an explicit park (backlog / non-goals). Ends with a mandatory fresh sync. |
+
+**Switching** is an explicit user word ("let me dump", "ask me questions", "poke holes", "let's converge"). On a strong signal — the user starts monologuing mid-interview, or answers every probe with "I haven't thought about it" — **offer** the switch in one line. Never seize it. Announce every shift in plain English: _"Switching to probe — I'll push on the sync-layer design. Say 'park' anytime."_
+
+## `start`
+
+### 1. The entry gate
+
+A session needs substance before it opens. Ask for a **basis**: a reference document (path or URL), or a one-shot brain dump of the whole idea, right now, in prose.
+
+- Basis arrives → copy/save it into `<folder>/basis/` and proceed.
+- The user offers drip-sized input — a bug fix, a single button, small action items — say this skill is the wrong tool, recommend stopping, and **do not open the session** unless the user explicitly overrides.
+- No basis and no dump → no session.
+
+### 2. Read the basis, propose the frame
+
+Distill the basis _first_ — this seeds `thesis.md` and the initial questions. Then one `AskUserQuestion` batch:
+
+- **Complexity** — low / medium / high. The skill proposes from the basis; the user confirms. This sets the default pillar surface (see **Pillars**) and ceremony depth.
+- **Build mode** — "Is this greenfield, or are we changing something that exists?" (greenfield / brownfield / hybrid). The answer lands in `build.md` and opens or closes its execution sections — migration strategy and gotchas are brainstorm-phase concerns; surfacing them in plan mode is too late.
+- **Mode** — "Where is this idea right now — fully in your head (dump it), half-formed (I'll interview), or drafted and needing stress (I'll probe)?"
+
+Then propose the **aspect map**: the thinking dimensions for _this specific idea_ (e.g., for a product: users/jobs, domain model, architecture, tech, risks; for a small tool: behavior, interface, failure modes). Derive it from the basis — there is no fixed list. The user edits it; write it into `thesis.md`. The map is the coverage source for the sync audit.
+
+### 3. Bootstrap
+
+Session folder: `./brainstorm/` by default (or `./plan/`, `./design/`, custom — reuse any folder containing `state.md`; confirm in one line). Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). Write top-level `state.md`:
+
+```
+STATE: open
+MODE: dump | interview | probe | converge
+COMPLEXITY: low | medium | high
+SESSION STARTED: <ISO date>
+CURRENT TOPIC: <one line>
+LAST SYNC: <ISO datetime or never>
+SYNC IN FLIGHT: no
+```
+
+Initial questions come from the basis distillation **only** — contradictions in the dump, gaps the aspect map exposes. Never interview to fill empty templates.
+
+## Pillars — substance first, lazy by default
+
+| Pillar | Holds | Exists |
+| --- | --- | --- |
+| `thesis.md` | What we're designing — running narrative, kept current + the aspect map | always |
+| `questions.md` | The **single convergence currency** — every unresolved design call, whoever raised it | always |
+| `decisions.md` | Resolved calls with **Why** + **How to apply** | always |
+| `build.md` | How the work gets executed: build mode (greenfield default / brownfield / hybrid), migration strategy, gotchas, rollout. Greenfield closes the execution sections; brownfield opens them | always |
+| `domain-model.md` | Entities, relationships, cardinalities, state ownership | medium+ |
+| `tech.md` | Stack choices, seeded from harness rules (e.g. `.claude/rules/general.md`) at bootstrap; deviations recorded with whys | medium+ |
+| `doctrine` / `glossary` / `non-goals` / `backlog` / `rejected` / `references` / `milestones` | as their templates describe | **lazy** — materialize on first real content, any complexity |
+
+The complexity dial sets _defaults_, not a cage: any lazy pillar materializes mid-session the moment the conversation produces content for it, and at **low** complexity the always-four may even live as sections of a single file if the user prefers.
+
+**Question entries** (`questions.md`): self-contained full prose in the user's framing, plus —
+
+- **Raised by.** user | sync | probe
+- **Closes when.** What resolution looks like — a pick, a confirmed fact, an accepted risk. Every question must be closeable.
+- **Options / Lean / Claude's take** — optional; _Claude's take_ remains opt-in (only when the user asks for a recommendation).
+
+**Decision entries** (`decisions.md`): append-only; **Decision**, **Why**, **How to apply**, **Resolves Q-N**. There is no tentative/committed state machine. Reversing a decision = append a new decision that names what it reverses, mark the old entry "Reversed by D-M", and let the next sync handle the ripples.
+
+## The sync agent
+
+The background reconciler that replaces ceremony with consistency. **One sync in flight at a time; queue at most one behind it.**
+
+**When:** after a distillation batch lands substantive pillar writes (at the turn break, not mid-sentence); mandatorily on entering converge and at `stop`; on demand. At **low** complexity, run it inline yourself; at **medium+**, dispatch a background `general-purpose` agent (read/write access to the session folder only).
+
+**Contract — audit exactly four sources:**
+
+1. **Cross-pillar contradiction** — thesis vs domain model vs decisions vs doctrine vs build (a decision that implies migration work with no `build.md` entry is a contradiction).
+2. **Aspect coverage** — any aspect on the map with no content anywhere → emit a question.
+3. **Basis drift** — does the thesis still agree with `basis/`? Divergence is fine if decided; accidental divergence → emit a question.
+4. **Tech conflicts** — anything that violates `tech.md` without a recorded deviation.
+
+**Output:** direct pillar edits for **scribe-calls**, new questions for **design-calls**, and a one-line report.
+
+**The line:** a _scribe-call_ is anything whose resolution doesn't change the design — wording, annotations, obvious bookkeeping. Just do it; list it in the report (the user can veto). A _design-call_ is anything whose resolution changes the idea — file it as a question (`Raised by: sync`) and move on. **Never** interrupt the conversation to ask "apply now or defer?" — file and continue.
+
+**The report is the status line.** Deliver it at the next natural turn break:
+
+> Sync: 4 edits applied · 2 new questions · **6 open** · untouched aspects: risks
+
+There is no separate dashboard, no scheduled checkpoint. This line is the only ambient convergence pressure the skill applies.
+
+## Coherence
+
+```
+coherent ⇔ open_questions == 0 ∧ last sync ran after the last pillar write
+```
+
+Zero means _"audited against the four sources and clean"_ — never _"nothing came to mind."_ Don't declare the idea coherent on any other basis. Distance-to-coherent is always visible in the sync report; the **user** decides when to converge and when to close. The skill never says "let's decide now."
+
+## `stop`
+
+1. Run a final sync (wait for any in-flight sync first).
+2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off.
+3. **Harvest** — see `harvest.md`. Standalone by default: the session folder _is_ the product. If the repo is v9-harnessed (`docs/architecture/` + `docs/modules/` exist), offer the adapter routing; never assume it.
+4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
+
+## Conduct — holds for the whole session
+
+1. **Speak English; codes live in files.** In conversation, name every pillar item by what it _is_ in plain words. Append the code in parentheses only when traceability needs it (_"…can a user change answer depth? (tracked as Q6)"_). Never lead with a bare `Q3`/`D7`. The user is not looking at the files.
+2. **No production code outside the session folder.** Illustrative load-bearing snippets are fine inside it (`samples/` or fenced in pillars). If asked for production code: offer a sketch inside the folder, or `/brainstorm stop` first.
+3. **The writing posture comes from `build.md`'s mode.** Greenfield: every pillar describes the system as it _will be_, present tense, as though the chosen design was always the plan — no migration vocabulary, no phantom history (banned list in `templates/build.md`). Brownfield/hybrid: migration vocabulary is legitimate, and `build.md` is its home; other pillars still describe the _target_ state.
+4. **`AskUserQuestion` appears in exactly three places:** the intake frame batch, interview mode, and converge picks. Everywhere else: prose.
+5. **Suggested, never seized.** Mode shifts, abstractions, probes — one offer each, accept refusal without re-litigating.
+6. **Questions are the only convergence currency.** Flaws, gaps, contradictions, uncovered aspects — everything unresolved funnels into `questions.md` or it doesn't exist. Nothing pending may live only in the conversation transcript.
+7. **No auto-invocation.** Only `/brainstorm start` and `/brainstorm stop` enter or leave a session. Read `state.md` at the start of every turn while a session folder exists.

package/data/harnesses/mobile/skills/brainstorm/harvest.md

@@ -0,0 +1,26 @@
+# Harvest adapter
+
+Harvest is **optional and offered, never assumed**. By default the session folder is the product: a self-contained registry the next `/brainstorm start` resumes from. Run this adapter only when (a) the repo is v9-harnessed — `docs/architecture/` and `docs/modules/` exist — and (b) the user accepts the offer at `stop`.
+
+## Routing
+
+The harvest is a structured diff between the session pillars and the live docs, routed by scope: module-local findings → `docs/modules/{m}/pillars/`, cross-module + IA/contract changes → `docs/architecture/`, backlog → `docs/history/`.
+
+| Session source | Destination |
+| --- | --- |
+| `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
+| `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, note the contract change there — the `boundary` skill will pick it up from source at the next plan check |
+| Decisions spanning 2+ modules | one ADR per cohesive theme → `docs/history/adr/ADR-NNN-{slug}.md` (a historical decision record, not the deployed-design SOT in `docs/architecture/`), authored to the **`documentation` skill §10 ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
+| Module-local decisions / doctrine / glossary / rejected | `docs/modules/{m}/pillars/{decisions,doctrine,glossary,rejected}.md` |
+| Cross-module doctrine / glossary | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md` |
+| `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
+| `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
+| `backlog.md` | `docs/history/backlog.md` (P0–P3) |
+| Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
+| `build.md` (brownfield/hybrid: migration strategy, gotchas, rollout) | the plan doc in `docs/history/plans/` — execution content is plan content, not architecture |
+
+Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-harvest-{slug}.md` listing what was written where.
+
+## After harvest
+
+Offer to delete the session folder (the dispersed homes now carry the content; the next session primes from them by copying relevant docs into `basis/`). Default to **keep** if the user is unsure — a kept folder simply resumes.

package/data/harnesses/mobile/skills/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/mobile/skills/brainstorm/templates/build.md

@@ -0,0 +1,37 @@
+# Build
+
+This pillar holds **how the work gets executed** — decided during brainstorming, not deferred to plan mode. Migration constraints and execution gotchas discovered late invalidate designs; surfacing them here, while the design is still fluid, is the point.
+
+At `start` the skill asks: _"Is this greenfield, or are we changing something that exists?"_ The answer sets **Mode** below and opens or closes the execution sections. The sync agent treats this file as a contradiction source — a decision that implies migration work with no entry here raises a question.
+
+## Mode
+
+`greenfield` _(default)_ | `brownfield` | `hybrid`
+
+- **greenfield** — nothing built yet: no production deploys, no users, no legacy code. The execution sections below are closed — mark them _Not applicable (greenfield)_. **Writing posture:** all pillars describe the system as it _will be_, in present tense, as though the chosen design was always the plan. Banned: "replaces" / "supersedes" / "previously" / "formerly" / "no longer" / "originally proposed" / `~~strikethrough~~` / "(resolved)" markers — the reader has no past, so don't reference one. Past tense lives only in `decisions.md`, `rejected.md`, `references.md`, and git history.
+- **brownfield** — the idea changes a system that already exists. All sections below are live, and migration vocabulary — "replaces", "currently", "migrate from" — is legitimate and load-bearing **in this file**. Other pillars still describe the _target_ state in present tense; the journey from here to there lives here.
+- **hybrid** — a new surface attached to a live system (a new module in a shipping product). The sections below apply to the seams only: integration points, shared state, contract changes. The new surface itself follows greenfield posture.
+
+## Current state
+
+_(brownfield/hybrid)_ What exists today, as relevant to the change. Link code paths or docs rather than restating them.
+
+## Target state
+
+One or two orienting sentences — cross-reference `thesis.md` rather than duplicating it.
+
+## Migration strategy
+
+How we get from current to target: phases, order of operations, coexistence windows, rollback points. Harvest routes this section into the implementation plan.
+
+## Gotchas
+
+Execution hazards known _now_, before plan mode — each one a bullet with why it bites:
+
+- [e.g. data backfill must run before the new index exists, or reads 404 during the window]
+- [e.g. auth cutover can't be phased — sessions are shared, it's all-or-nothing]
+- [e.g. the event consumer is not idempotent; dual-write window will double-process]
+
+## Rollout & risks
+
+Sequencing, feature flags, kill switches, and the failure modes each phase accepts.

package/data/harnesses/mobile/skills/brainstorm/templates/decisions.md

@@ -0,0 +1,29 @@
+# Decisions
+
+This file is the **append-only ledger of resolved decisions**, with the reasoning future-you needs to judge edge cases.
+
+Load-bearing fields:
+
+- **Decision** — what was decided, in one or two sentences.
+- **Why** — the motivation: a constraint, an incident, a deadline, a stakeholder ask. Without the _why_, decisions decay into rules no one understands.
+- **How to apply** — when and where this decision shapes future work. Name the files, layers, or situations where it kicks in.
+
+There is no tentative/committed state machine. A decision is a decision the moment it's written; the next sync handles its ripples. **Reversing** a decision = append a new decision that names what it reverses, add a one-line `Reversed by D-M (YYYY-MM-DD)` note to the old entry, and let the sync raise questions for anything downstream.
+
+This ledger is one of the places where past tense is permitted (with `rejected.md`, `references.md`, `build.md`'s execution sections, and git history).
+
+---
+
+## D1 — [Title]
+
+**Decision.** [What was decided.]
+
+**Why.** [The motivation future-you needs.]
+
+**How to apply.** [Where this rule kicks in — be specific.]
+
+**Resolves.** Q1 (deleted from `questions.md`).
+
+**Alternatives considered.** _(optional — reference `rejected.md` if substantial)_
+
+**Reverses.** _(only when this decision reverses an earlier one — name it and say what changed)_

package/data/harnesses/mobile/skills/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/mobile/skills/brainstorm/templates/domain-model.md

@@ -0,0 +1,25 @@
+# Domain model
+
+This file holds the **information architecture** of the idea: entities, relationships, cardinalities, and who owns what state. This is where facts like "an account has many leads" land the moment they're said — they are neither principles (`doctrine.md`) nor terms (`glossary.md`), and they must not be lost to the transcript.
+
+The loop's _abstract_ step feeds this file: when the user implies structure without naming it, propose the entry here.
+
+## Entities
+
+### [Entity]
+
+[One paragraph: what it is, what state it owns, where it lives (client / server / external system).]
+
+## Relationships
+
+| From | To | Cardinality | Notes |
+| --- | --- | --- | --- |
+| Account | Lead | 1 : N | [e.g. leads cannot transfer between accounts — see D3] |
+
+Cardinality changes are design changes — when one shifts, expect the sync to raise questions against routing, storage, and milestones.
+
+## Invariants
+
+Rules the model must always satisfy, stated as present-tense facts:
+
+- [e.g. Every lead belongs to exactly one account at any point in time.]

package/data/harnesses/mobile/skills/brainstorm/templates/glossary.md

@@ -0,0 +1,20 @@
+# 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/mobile/skills/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/mobile/skills/brainstorm/templates/non-goals.md

@@ -0,0 +1,17 @@
+# 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 the scope described in `thesis.md`: where the thesis says "this is what we're building", non-goals say "this looked plausible but is deliberately out". Distinguish it from `backlog.md` (things we _will_ build, just later) — a non-goal may never be built.
+
+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, fold the item into scope (`thesis.md`, or `backlog.md` if it's planned-but-later) 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/mobile/skills/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.)