| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 18 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 1 | 0 | 6 | 14% |
What each file covers
Sections
0 shared · 1 only in A · 18 only in B- − CLAUDE.md → AGENTS.md
- + AGENTS.md
- + Project overview
- + <N> non-negotiable principles (constitution v<TODO>)
- + Tech stack (locked)
- + Folder conventions
- + Agent ownership rules (do not cross boundaries)
- + Workflow discipline (Superpowers — non-negotiable)
- + Environment variables
- + Git rules
- + Memory architecture
- + Tooling
- + nucleus — the user's memory of every session
- + learnings — the user's playbook of patterns to carry forward
- + Setup nudge
- + model-race — parallel AI model comparison via Git worktrees
- + Other CLIs
- + Source-of-truth references
- + Project status
Commands
0 shared · 0 only in A · 2 only in B- + git add path/to/file
- + git add .
Section tags
1 shared · 0 only in A · 6 only in B- + setup
- + code-style
- + architecture
- + git-pr
- + performance
- + do-not
- agent-behaviour
Line diff
machbuilds/atom · scaffold/CLAUDE.md
@@ −1 @@
1# CLAUDE.md → AGENTS.md
2
3Project instructions live in `AGENTS.md`. Read that file.
4
5This forwarder exists so Claude Code's default `CLAUDE.md` auto-load
6works without duplicating content. The `.claude/skills/` directory in
7this repo holds Claude-specific augmentations on top of `AGENTS.md`.
8
9If you are an AI tool reading this file: open `AGENTS.md` in this repo
10and follow the instructions there.
11
machbuilds/atom · scaffold/AGENTS.md
@@ +1 @@
1# AGENTS.md
2
3Project instructions for any AI tool working in this repository. Source
4of truth: `.specify/memory/constitution.md` (v<TODO: version>) +
5`<TODO: link to plan.md, spec.md, or other primary planning doc>`.
6
7This is the canonical instructions file. Tool-specific files (`CLAUDE.md`,
8`GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`) are
9forwarders that point here. atom's richest experience assumes Claude
10Code; other tools (Codex CLI, Gemini CLI, Cursor, Copilot) read this
11file and call the project's CLIs (e.g. `nucleus`) directly.
12
13## Project overview
14
15<TODO: 1-paragraph description — what this is, what problem it solves,
16who the user is. Be concrete. Reference real numbers if they exist.>
17
18<TODO: 1-paragraph on the product's "primary surface" — what's the canonical
19user moment? Mobile screenshot? Desktop dashboard? CLI output? API
20response? This decides many downstream design and engineering tradeoffs.>
21
22## <N> non-negotiable principles (constitution v<TODO>)
23
24<TODO: list 3-5 principles, each one-line action-oriented, each followed
25by a short rationale. See atom's `docs/HOW_TO_WRITE_CONSTITUTION.md`.>
26
271. **<Principle 1>** — <one-line rationale>
282. **<Principle 2>** — <one-line rationale>
293. **<Principle 3>** — <one-line rationale>
304. **<Principle 4 — optional>**
315. **<Principle 5 — optional>**
32
33## Tech stack (locked)
34
35<TODO: pin runtime, framework, key libraries. Pin to caret-minor, not
36exact patch. See atom's `docs/LESSONS_LEARNED.md` on dependency pinning.>
37
38- **Runtime**: <e.g., Node.js 20, Python 3.12>
39- **Framework**: <e.g., Next.js ^14.2.x, FastAPI ~=0.110>
40- **Database**: <e.g., PostgreSQL via `pg` ^8.x>
41- **Cache**: <e.g., Redis via `ioredis` ^5.x>
42- **Hosting**: <target — see atom's `docs/HOW_TO_PICK_DEPLOY_TARGET.md`>
43- **Key libraries**: <list with pins>
44
45<TODO: one-line cost envelope expectation — e.g., "~$0.005/request at scale"
46or "~$50/month at expected traffic">
47
48## Folder conventions
49
50<TODO: describe the project's directory structure. Keep it terse — the
51pattern is what matters, not every file.>
52
53```
54src/
55├── <main entry>
56├── <api/server logic>
57├── <components — if frontend>
58├── <lib — pure functions>
59├── <types>
60├── <constants>
61└── <tests>
62```
63
64<TODO: one-line note on where pure functions live vs where I/O lives.>
65
66## Agent ownership rules (do not cross boundaries)
67
68<TODO: customise this matrix for the project. If solo with no agent split,
69write "solo build — no agent split" and skip the table.>
70
71| Agent | Harness | Owns |
72|---|---|---|
73| **Backend** | <e.g., Claude Code> | <paths> |
74| **Design** | <e.g., Codex> | <paths> |
75| **Test** | <e.g., Gemini CLI> | <paths> |
76| **Deploy** | <e.g., Claude Code> | <paths> |
77
78If a task forces you across a boundary, **stop** and flag it as a routing
79error. Never silently edit another agent's files.
80
81Skill files in `.claude/skills/{role}-agent/SKILL.md` define each
82agent's full workflow, conventions, and constitutional enforcement
83points. These are Claude-specific augmentations on top of the
84instructions in this file. AI tools without skill auto-loading still
85get the relevant guidance by reading this file.
86
87## Workflow discipline (Superpowers — non-negotiable)
88
89Every task: **clarify → design → plan → TDD → build → verify**. Skipping
90a step = mandatory restart. Writing code before a failing test exists =
91mandatory restart.
92
93## Environment variables
94
95`.env` is never committed. `.env.example` is the canonical reference.
96
97<TODO: list env vars in this format. Mark each Required or Optional per
98the two-tier pattern in atom's `docs/PATTERNS.md`.>
99
100| Variable | Required? | Notes |
101|---|---|---|
102| `<VAR_1>` | Required | <what it's for> |
103| `<VAR_2>` | Required | <what it's for> |
104| `<VAR_3>` | Optional | <what it's for; what degrades if missing> |
105
106`NEXT_PUBLIC_*` (or framework equivalent) vars are inlined into the
107client bundle at build time. Never put a secret behind that prefix.
108
109<TODO: note what the healthcheck endpoint does. Required env missing
110should be 503; optional env missing should be 200 with `degraded` status.>
111
112## Git rules
113
114- **Never** `--no-verify`, `--force` to `main`, or `--no-gpg-sign`.
115- **Never** amend a published commit. Create a new commit instead.
116- **Always** force-push with `--force-with-lease`, never `--force`.
117- Stage specific files (`git add path/to/file`), not `git add .` or `-A`
118 — keeps `.env` and credentials out of accidental commits.
119- Commit messages: lowercase imperative, scoped where useful
120 (`backend: …`, `design: …`, `deploy: …`).
121- Co-author trailer required when AI-assisted:
122 `Co-Authored-By: <agent name> <noreply@<vendor>.com>`.
123
124## Memory architecture
125
126Load order at task start:
127**this AGENTS.md → nucleus search (relevant) → mem0 query → Multica skill → `.claude/memory.md`** (Claude only)
128
129- **AGENTS.md** (this file) — static, hand-maintained, hard cap ~250 lines.
130 Tool-specific forwarders (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`,
131 `.github/copilot-instructions.md`) all redirect here.
132- **nucleus** — cross-project learning store. Run `nucleus search "<keyword>"`
133 at session start when the work touches a known concern (auth, caching,
134 deploys, migrations). See "Tooling > nucleus" below for full usage.
135- **mem0** — episodic; agents log key decisions after task completion.
136 All memory operations use `user_id: "<TODO: project-slug>"`.
137- **Multica skills** — procedural, per-agent. In Claude Code, lives at
138 `.claude/skills/`. Other tools read the equivalent guidance from this
139 file directly.
140- **`.claude/memory.md`** — auto-generated session notes; Claude-only;
141 do not edit.
142
143After every commit, log a mem0 entry with the SHA, what changed, and the
144non-obvious WHY (the constraint, the surprise, the past incident).
145
146## Tooling
147
148The project's CLIs and conventions for AI tools.
149
150### nucleus — the user's memory of every session
151
152`nucleus` is the user's cross-project memory: raw, project-tagged
153captures from every coding session. Lives at `~/.atom/nucleus/` on
154the user's machine. 100% theirs.
155
156Common subcommands: `nucleus search`, `nucleus add`, `nucleus slug`,
157`nucleus promote`, `nucleus sync`. Run `nucleus --help` for the full
158CLI.
159
160**When to search nucleus:**
161
162At session start, before coding on a known concern (auth, caching,
163deploys, migrations, performance, etc.):
164
165```
166nucleus search "<keyword>" --json --limit 5
167```
168
169If past pitfalls or patterns apply, mention them to the user before
170proceeding. Empty results: proceed normally; do not pad responses with
171"nucleus had nothing to say."
172
173Before non-obvious decisions, search for prior context:
174
175- Adding a new dependency: `nucleus search --type pitfall --tags deps`
176- Adding a cache layer: `nucleus search "cache"`
177- Writing a migration: `nucleus search --type pitfall --tags migration`
178
179**When to add to nucleus:**
180
181The capture mode is in `~/.atom/nucleus/config.json`. Capture is not
182automated — there is no daemon, no hook, no cron. In `claude-managed`
183mode you (the AI) actively call `nucleus add` during the session; in
184`manual` mode you surface candidates and let the user run it.
185
186Active triggers for capture (don't wait for a session boundary —
187capture in-flow when one of these fires):
188
189- **After fixing a non-obvious bug.** What was the surprise? Capture.
190- **After a design decision with rationale.** Why this approach over
191 the alternative? Capture.
192- **After discovering a generalizable pattern.** A snippet, a flag, a
193 workflow that worked. Capture.
194- **At `/clear` or end-of-task signals.** Sweep recent work and
195 capture anything you missed.
196
197The bar is **low**. If you're unsure whether to capture, capture.
198Promotion (later, by the user) is where refinement happens; nucleus
199is the journal.
200
201Per capture-mode flavor:
202
203| Mode | AI behavior |
204|---|---|
205| `claude-managed` (default) | You call `nucleus add` directly when a trigger fires. |
206| `manual` | You surface a one-line candidate ("Worth capturing? — `<one-line>`") but the user runs the command. |
207| `auto-timer` | Reserved. Behave the same as `claude-managed` until the daemon ships. |
208
209Capture command:
210
211```
212nucleus add "<insight>" \
213 --type architecture|pitfall|pattern|workflow|decision|bug-fix|performance|security \
214 --confidence low|medium|high \
215 --source human|claude|cross-model|observation \
216 --tags tag1 tag2 \
217 --files path/to/file
218```
219
220**When to surface promotion candidates:**
221
222After **3+ captures in a single session**, OR when the user signals
223end-of-task ("ship it", "we're done", `/clear`, commit-ready), pause
224and surface promotion candidates in a single message:
225
226> "I've captured N entries this session. Worth promoting any to your
227> playbook? Top candidates: …"
228
229Pick 1–2 entries with the strongest generalization potential. An
230entry passes the test if it would help a project unrelated to this
231one, doesn't reference project-specific names or vendor quirks, and
232describes a pattern rather than an incident.
233
234**Do not call `nucleus promote` directly** — it opens `$EDITOR`
235interactively, which doesn't work in agent flows. Print the command
236for the user instead: `nucleus promote <ULID>`.
237
238**What not to do:**
239
240- Do not call `nucleus add` after every Bash command. Capture is for
241 durable lessons, not noise.
242- Do not write hedged or vague insights. "Be careful with auth" is
243 not a learning. "Cache the in-flight refresh promise" is.
244- Do not invoke `nucleus sync` automatically. Sync is on the user's
245 clock (on `/clear`, end of day, or explicit request).
246- Do not run `nucleus promote` yourself. Print the command and let
247 the user decide.
248
249### learnings — the user's playbook of patterns to carry forward
250
251`learnings` is the user's curated playbook: generalized patterns
252they've decided are worth carrying into every future project. Lives
253at `~/.atom/learnings/` on the user's machine. **Auto-copied into
254every new project they bootstrap from atom**, filtered by the new
255project's stack tags.
256
257100% theirs. Same privacy model as nucleus. Optional sync to their
258own private GitHub repo (separate from the nucleus sync repo).
259
260Common subcommands: `learnings list`, `learnings show <key>`,
261`learnings sync`, `learnings init`. Run `learnings --help` for the
262full CLI.
263
264**Promotion is the bridge from nucleus → learnings:**
265
266When a nucleus entry has settled and applies beyond the current
267project, graduate it:
268
269```
270nucleus promote <id>
271```
272
273This generates a draft at `~/.atom/learnings/<type>/<key>.md`,
274opens `$EDITOR` for the user to refine, and they keep it forever.
275
276**The generalization test (the only filter that matters at promotion):**
277
278Would this teach something that applies beyond the current project?
279If the lesson references a project-specific endpoint, table, vendor
280quirk, or proprietary detail, **don't promote**. The lesson stays in
281nucleus, where it's still searchable.
282
283Pass: "Cache the refresh promise across concurrent calls."
284Fail: "Update the `/api/v1/users/me` route to return 304." (project-specific)
285
286**Suggesting promotion (Claude-specific):**
287
288After several captures from a session, before `/clear` or end of
289work, scan for promotion candidates and surface them: *"This one
290looks broadly useful. Promote to your playbook? — `nucleus promote
291<id>`."* Don't auto-promote without the user's explicit yes.
292
293**What not to do:**
294
295- Do not run `nucleus promote` automatically. The user decides what
296 enters their playbook.
297- Do not push project-specific content into learnings, even if the
298 user asks. Suggest leaving it in nucleus and refining the prose.
299- Do not invoke `learnings sync` automatically. Same as nucleus —
300 sync is on the user's clock.
301
302### Setup nudge
303
304If the user has not yet run `nucleus init` AND `learnings init`
305(check for `~/.atom/nucleus/config.json` and
306`~/.atom/learnings/config.json`), mention this once at the start
307of the first session in a new project:
308
309> "I notice you haven't initialized nucleus and learnings yet. Run
310> `nucleus init && learnings init` once on this machine — both are
311> optional but unlock the cross-project memory and playbook
312> propagation."
313
314Don't nag. Mention once, drop it.
315
316### model-race — parallel AI model comparison via Git worktrees
317
318This project may have model-race available (opt-in via the wizard;
319check for `model-race.config.json` in the repo root). Run
320`model-race --help` for the CLI.
321
322**What it is.** A development-time workflow for running the same
323feature spec through multiple AI models in parallel via Git worktrees.
324Compare the implementations, merge the winner.
325
326**When to suggest it (AI-facing rule):**
327
328Only when the user is about to make a non-obvious decision with multiple
329reasonable approaches AND the stakes justify the comparison cost. Cases:
330
331- Tricky algorithm or data structure choice.
332- Non-obvious API design where shape decisions compound later.
333- Performance-critical hot paths.
334- Refactors where the right pattern is unclear.
335
336NOT for: CRUD endpoints, boilerplate, glue code, bug fixes, or
337anything where the answer is obvious.
338
339**Lifecycle:**
340
341```
342model-race start <feature> --spec spec.md # create worktrees
343model-race status # see state
344model-race launch <model> # open AI CLI in worktree
345 # (run for each model in
346 # separate terminal)
347model-race score # automated scorecard
348model-race judge # opt-in LLM evaluation
349model-race merge <winner> # cherry-pick + cleanup
350```
351
352**Spec quality matters.** A race is only as good as its spec. Before
353`model-race start`, help the user write a spec with:
354
355- One-paragraph statement.
356- Testable acceptance criteria.
357- Constraints (perf budgets, API contracts, file boundaries).
358- No solution details (don't pre-decide the approach).
359
360A weak spec produces three confused implementations and no clear winner.
361
362**What not to do:**
363
364- Don't suggest model-race for routine work. The 3-5x time cost is only
365 justified when the decision is hard.
366- Don't run `model-race judge` automatically. It costs an LLM call and
367 the user should decide when to invoke it.
368- Don't run `model-race abort` without confirmation. It destroys
369 in-progress work in worktrees.
370
371### Other CLIs
372
373<TODO: list other project-specific CLIs as they're added — e.g.,
374`gsd-new-project`, custom build/deploy scripts. Each entry: when to
375invoke, what flags matter, what NOT to do automatically.>
376
377## Source-of-truth references
378
379<TODO: link to project-specific planning docs once they exist:>
380
381- `.specify/memory/constitution.md` — principles + locked tech stack
382- `<spec.md, plan.md, etc.>` — feature specs and implementation plans
383- `<contracts/, schemas/>` — API contracts and data shapes
384- `<README.md, docs/>` — how to develop locally
385- `.claude/skills/{role}-agent/SKILL.md` — per-agent procedural memory
386
387## Project status
388
389<TODO: one-line on current phase. E.g., "Phase 1 (planning), no production
390code yet" or "Phase 2 (active development), beta target X".>
391
@@ −1 +1 @@
1−# CLAUDE.md → AGENTS.md
1+# AGENTS.md
22
3−Project instructions live in `AGENTS.md`. Read that file.
3+Project instructions for any AI tool working in this repository. Source
4+of truth: `.specify/memory/constitution.md` (v<TODO: version>) +
5+`<TODO: link to plan.md, spec.md, or other primary planning doc>`.
46
5−This forwarder exists so Claude Code's default `CLAUDE.md` auto-load
6−works without duplicating content. The `.claude/skills/` directory in
7−this repo holds Claude-specific augmentations on top of `AGENTS.md`.
7+This is the canonical instructions file. Tool-specific files (`CLAUDE.md`,
8+`GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`) are
9+forwarders that point here. atom's richest experience assumes Claude
10+Code; other tools (Codex CLI, Gemini CLI, Cursor, Copilot) read this
11+file and call the project's CLIs (e.g. `nucleus`) directly.
812
9−If you are an AI tool reading this file: open `AGENTS.md` in this repo
10−and follow the instructions there.
13+## Project overview
14+
15+<TODO: 1-paragraph description — what this is, what problem it solves,
16+who the user is. Be concrete. Reference real numbers if they exist.>
17+
18+<TODO: 1-paragraph on the product's "primary surface" — what's the canonical
19+user moment? Mobile screenshot? Desktop dashboard? CLI output? API
20+response? This decides many downstream design and engineering tradeoffs.>
21+
22+## <N> non-negotiable principles (constitution v<TODO>)
23+
24+<TODO: list 3-5 principles, each one-line action-oriented, each followed
25+by a short rationale. See atom's `docs/HOW_TO_WRITE_CONSTITUTION.md`.>
26+
27+1. **<Principle 1>** — <one-line rationale>
28+2. **<Principle 2>** — <one-line rationale>
29+3. **<Principle 3>** — <one-line rationale>
30+4. **<Principle 4 — optional>**
31+5. **<Principle 5 — optional>**
32+
33+## Tech stack (locked)
34+
35+<TODO: pin runtime, framework, key libraries. Pin to caret-minor, not
36+exact patch. See atom's `docs/LESSONS_LEARNED.md` on dependency pinning.>
37+
38+- **Runtime**: <e.g., Node.js 20, Python 3.12>
39+- **Framework**: <e.g., Next.js ^14.2.x, FastAPI ~=0.110>
40+- **Database**: <e.g., PostgreSQL via `pg` ^8.x>
41+- **Cache**: <e.g., Redis via `ioredis` ^5.x>
42+- **Hosting**: <target — see atom's `docs/HOW_TO_PICK_DEPLOY_TARGET.md`>
43+- **Key libraries**: <list with pins>
44+
45+<TODO: one-line cost envelope expectation — e.g., "~$0.005/request at scale"
46+or "~$50/month at expected traffic">
47+
48+## Folder conventions
49+
50+<TODO: describe the project's directory structure. Keep it terse — the
51+pattern is what matters, not every file.>
52+
53+```
54+src/
55+├── <main entry>
56+├── <api/server logic>
57+├── <components — if frontend>
58+├── <lib — pure functions>
59+├── <types>
60+├── <constants>
61+└── <tests>
62+```
63+
64+<TODO: one-line note on where pure functions live vs where I/O lives.>
65+
66+## Agent ownership rules (do not cross boundaries)
67+
68+<TODO: customise this matrix for the project. If solo with no agent split,
69+write "solo build — no agent split" and skip the table.>
70+
71+| Agent | Harness | Owns |
72+|---|---|---|
73+| **Backend** | <e.g., Claude Code> | <paths> |
74+| **Design** | <e.g., Codex> | <paths> |
75+| **Test** | <e.g., Gemini CLI> | <paths> |
76+| **Deploy** | <e.g., Claude Code> | <paths> |
77+
78+If a task forces you across a boundary, **stop** and flag it as a routing
79+error. Never silently edit another agent's files.
80+
81+Skill files in `.claude/skills/{role}-agent/SKILL.md` define each
82+agent's full workflow, conventions, and constitutional enforcement
83+points. These are Claude-specific augmentations on top of the
84+instructions in this file. AI tools without skill auto-loading still
85+get the relevant guidance by reading this file.
86+
87+## Workflow discipline (Superpowers — non-negotiable)
88+
89+Every task: **clarify → design → plan → TDD → build → verify**. Skipping
90+a step = mandatory restart. Writing code before a failing test exists =
91+mandatory restart.
92+
93+## Environment variables
94+
95+`.env` is never committed. `.env.example` is the canonical reference.
96+
97+<TODO: list env vars in this format. Mark each Required or Optional per
98+the two-tier pattern in atom's `docs/PATTERNS.md`.>
99+
100+| Variable | Required? | Notes |
101+|---|---|---|
102+| `<VAR_1>` | Required | <what it's for> |
103+| `<VAR_2>` | Required | <what it's for> |
104+| `<VAR_3>` | Optional | <what it's for; what degrades if missing> |
105+
106+`NEXT_PUBLIC_*` (or framework equivalent) vars are inlined into the
107+client bundle at build time. Never put a secret behind that prefix.
108+
109+<TODO: note what the healthcheck endpoint does. Required env missing
110+should be 503; optional env missing should be 200 with `degraded` status.>
111+
112+## Git rules
113+
114+- **Never** `--no-verify`, `--force` to `main`, or `--no-gpg-sign`.
115+- **Never** amend a published commit. Create a new commit instead.
116+- **Always** force-push with `--force-with-lease`, never `--force`.
117+- Stage specific files (`git add path/to/file`), not `git add .` or `-A`
118+ — keeps `.env` and credentials out of accidental commits.
119+- Commit messages: lowercase imperative, scoped where useful
120+ (`backend: …`, `design: …`, `deploy: …`).
121+- Co-author trailer required when AI-assisted:
122+ `Co-Authored-By: <agent name> <noreply@<vendor>.com>`.
123+
124+## Memory architecture
125+
126+Load order at task start:
127+**this AGENTS.md → nucleus search (relevant) → mem0 query → Multica skill → `.claude/memory.md`** (Claude only)
128+
129+- **AGENTS.md** (this file) — static, hand-maintained, hard cap ~250 lines.
130+ Tool-specific forwarders (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`,
131+ `.github/copilot-instructions.md`) all redirect here.
132+- **nucleus** — cross-project learning store. Run `nucleus search "<keyword>"`
133+ at session start when the work touches a known concern (auth, caching,
134+ deploys, migrations). See "Tooling > nucleus" below for full usage.
135+- **mem0** — episodic; agents log key decisions after task completion.
136+ All memory operations use `user_id: "<TODO: project-slug>"`.
137+- **Multica skills** — procedural, per-agent. In Claude Code, lives at
138+ `.claude/skills/`. Other tools read the equivalent guidance from this
139+ file directly.
140+- **`.claude/memory.md`** — auto-generated session notes; Claude-only;
141+ do not edit.
142+
143+After every commit, log a mem0 entry with the SHA, what changed, and the
144+non-obvious WHY (the constraint, the surprise, the past incident).
145+
146+## Tooling
147+
148+The project's CLIs and conventions for AI tools.
149+
150+### nucleus — the user's memory of every session
151+
152+`nucleus` is the user's cross-project memory: raw, project-tagged
153+captures from every coding session. Lives at `~/.atom/nucleus/` on
154+the user's machine. 100% theirs.
155+
156+Common subcommands: `nucleus search`, `nucleus add`, `nucleus slug`,
157+`nucleus promote`, `nucleus sync`. Run `nucleus --help` for the full
158+CLI.
159+
160+**When to search nucleus:**
161+
162+At session start, before coding on a known concern (auth, caching,
163+deploys, migrations, performance, etc.):
164+
165+```
166+nucleus search "<keyword>" --json --limit 5
167+```
168+
169+If past pitfalls or patterns apply, mention them to the user before
170+proceeding. Empty results: proceed normally; do not pad responses with
171+"nucleus had nothing to say."
172+
173+Before non-obvious decisions, search for prior context:
174+
175+- Adding a new dependency: `nucleus search --type pitfall --tags deps`
176+- Adding a cache layer: `nucleus search "cache"`
177+- Writing a migration: `nucleus search --type pitfall --tags migration`
178+
179+**When to add to nucleus:**
180+
181+The capture mode is in `~/.atom/nucleus/config.json`. Capture is not
182+automated — there is no daemon, no hook, no cron. In `claude-managed`
183+mode you (the AI) actively call `nucleus add` during the session; in
184+`manual` mode you surface candidates and let the user run it.
185+
186+Active triggers for capture (don't wait for a session boundary —
187+capture in-flow when one of these fires):
188+
189+- **After fixing a non-obvious bug.** What was the surprise? Capture.
190+- **After a design decision with rationale.** Why this approach over
191+ the alternative? Capture.
192+- **After discovering a generalizable pattern.** A snippet, a flag, a
193+ workflow that worked. Capture.
194+- **At `/clear` or end-of-task signals.** Sweep recent work and
195+ capture anything you missed.
196+
197+The bar is **low**. If you're unsure whether to capture, capture.
198+Promotion (later, by the user) is where refinement happens; nucleus
199+is the journal.
200+
201+Per capture-mode flavor:
202+
203+| Mode | AI behavior |
204+|---|---|
205+| `claude-managed` (default) | You call `nucleus add` directly when a trigger fires. |
206+| `manual` | You surface a one-line candidate ("Worth capturing? — `<one-line>`") but the user runs the command. |
207+| `auto-timer` | Reserved. Behave the same as `claude-managed` until the daemon ships. |
208+
209+Capture command:
210+
211+```
212+nucleus add "<insight>" \
213+ --type architecture|pitfall|pattern|workflow|decision|bug-fix|performance|security \
214+ --confidence low|medium|high \
215+ --source human|claude|cross-model|observation \
216+ --tags tag1 tag2 \
217+ --files path/to/file
218+```
219+
220+**When to surface promotion candidates:**
221+
222+After **3+ captures in a single session**, OR when the user signals
223+end-of-task ("ship it", "we're done", `/clear`, commit-ready), pause
224+and surface promotion candidates in a single message:
225+
226+> "I've captured N entries this session. Worth promoting any to your
227+> playbook? Top candidates: …"
228+
229+Pick 1–2 entries with the strongest generalization potential. An
230+entry passes the test if it would help a project unrelated to this
231+one, doesn't reference project-specific names or vendor quirks, and
232+describes a pattern rather than an incident.
233+
234+**Do not call `nucleus promote` directly** — it opens `$EDITOR`
235+interactively, which doesn't work in agent flows. Print the command
236+for the user instead: `nucleus promote <ULID>`.
237+
238+**What not to do:**
239+
240+- Do not call `nucleus add` after every Bash command. Capture is for
241+ durable lessons, not noise.
242+- Do not write hedged or vague insights. "Be careful with auth" is
243+ not a learning. "Cache the in-flight refresh promise" is.
244+- Do not invoke `nucleus sync` automatically. Sync is on the user's
245+ clock (on `/clear`, end of day, or explicit request).
246+- Do not run `nucleus promote` yourself. Print the command and let
247+ the user decide.
248+
249+### learnings — the user's playbook of patterns to carry forward
250+
251+`learnings` is the user's curated playbook: generalized patterns
252+they've decided are worth carrying into every future project. Lives
253+at `~/.atom/learnings/` on the user's machine. **Auto-copied into
254+every new project they bootstrap from atom**, filtered by the new
255+project's stack tags.
256+
257+100% theirs. Same privacy model as nucleus. Optional sync to their
258+own private GitHub repo (separate from the nucleus sync repo).
259+
260+Common subcommands: `learnings list`, `learnings show <key>`,
261+`learnings sync`, `learnings init`. Run `learnings --help` for the
262+full CLI.
263+
264+**Promotion is the bridge from nucleus → learnings:**
265+
266+When a nucleus entry has settled and applies beyond the current
267+project, graduate it:
268+
269+```
270+nucleus promote <id>
271+```
272+
273+This generates a draft at `~/.atom/learnings/<type>/<key>.md`,
274+opens `$EDITOR` for the user to refine, and they keep it forever.
275+
276+**The generalization test (the only filter that matters at promotion):**
277+
278+Would this teach something that applies beyond the current project?
279+If the lesson references a project-specific endpoint, table, vendor
280+quirk, or proprietary detail, **don't promote**. The lesson stays in
281+nucleus, where it's still searchable.
282+
283+Pass: "Cache the refresh promise across concurrent calls."
284+Fail: "Update the `/api/v1/users/me` route to return 304." (project-specific)
285+
286+**Suggesting promotion (Claude-specific):**
287+
288+After several captures from a session, before `/clear` or end of
289+work, scan for promotion candidates and surface them: *"This one
290+looks broadly useful. Promote to your playbook? — `nucleus promote
291+<id>`."* Don't auto-promote without the user's explicit yes.
292+
293+**What not to do:**
294+
295+- Do not run `nucleus promote` automatically. The user decides what
296+ enters their playbook.
297+- Do not push project-specific content into learnings, even if the
298+ user asks. Suggest leaving it in nucleus and refining the prose.
299+- Do not invoke `learnings sync` automatically. Same as nucleus —
300+ sync is on the user's clock.
301+
302+### Setup nudge
303+
304+If the user has not yet run `nucleus init` AND `learnings init`
305+(check for `~/.atom/nucleus/config.json` and
306+`~/.atom/learnings/config.json`), mention this once at the start
307+of the first session in a new project:
308+
309+> "I notice you haven't initialized nucleus and learnings yet. Run
310+> `nucleus init && learnings init` once on this machine — both are
311+> optional but unlock the cross-project memory and playbook
312+> propagation."
313+
314+Don't nag. Mention once, drop it.
315+
316+### model-race — parallel AI model comparison via Git worktrees
317+
318+This project may have model-race available (opt-in via the wizard;
319+check for `model-race.config.json` in the repo root). Run
320+`model-race --help` for the CLI.
321+
322+**What it is.** A development-time workflow for running the same
323+feature spec through multiple AI models in parallel via Git worktrees.
324+Compare the implementations, merge the winner.
325+
326+**When to suggest it (AI-facing rule):**
327+
328+Only when the user is about to make a non-obvious decision with multiple
329+reasonable approaches AND the stakes justify the comparison cost. Cases:
330+
331+- Tricky algorithm or data structure choice.
332+- Non-obvious API design where shape decisions compound later.
333+- Performance-critical hot paths.
334+- Refactors where the right pattern is unclear.
335+
336+NOT for: CRUD endpoints, boilerplate, glue code, bug fixes, or
337+anything where the answer is obvious.
338+
339+**Lifecycle:**
340+
341+```
342+model-race start <feature> --spec spec.md # create worktrees
343+model-race status # see state
344+model-race launch <model> # open AI CLI in worktree
345+ # (run for each model in
346+ # separate terminal)
347+model-race score # automated scorecard
348+model-race judge # opt-in LLM evaluation
349+model-race merge <winner> # cherry-pick + cleanup
350+```
351+
352+**Spec quality matters.** A race is only as good as its spec. Before
353+`model-race start`, help the user write a spec with:
354+
355+- One-paragraph statement.
356+- Testable acceptance criteria.
357+- Constraints (perf budgets, API contracts, file boundaries).
358+- No solution details (don't pre-decide the approach).
359+
360+A weak spec produces three confused implementations and no clear winner.
361+
362+**What not to do:**
363+
364+- Don't suggest model-race for routine work. The 3-5x time cost is only
365+ justified when the decision is hard.
366+- Don't run `model-race judge` automatically. It costs an LLM call and
367+ the user should decide when to invoke it.
368+- Don't run `model-race abort` without confirmation. It destroys
369+ in-progress work in worktrees.
370+
371+### Other CLIs
372+
373+<TODO: list other project-specific CLIs as they're added — e.g.,
374+`gsd-new-project`, custom build/deploy scripts. Each entry: when to
375+invoke, what flags matter, what NOT to do automatically.>
376+
377+## Source-of-truth references
378+
379+<TODO: link to project-specific planning docs once they exist:>
380+
381+- `.specify/memory/constitution.md` — principles + locked tech stack
382+- `<spec.md, plan.md, etc.>` — feature specs and implementation plans
383+- `<contracts/, schemas/>` — API contracts and data shapes
384+- `<README.md, docs/>` — how to develop locally
385+- `.claude/skills/{role}-agent/SKILL.md` — per-agent procedural memory
386+
387+## Project status
388+
389+<TODO: one-line on current phase. E.g., "Phase 1 (planning), no production
390+code yet" or "Phase 2 (active development), beta target X".>
11391
