| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 18 | 1 | 0% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 1 | 6 | 0 | 14% |
What each file covers
Sections
0 shared · 18 only in A · 1 only in B- − 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
- + CLAUDE.md → AGENTS.md
Commands
0 shared · 2 only in A · 0 only in B- − git add path/to/file
- − git add .
Section tags
1 shared · 6 only in A · 0 only in B- − setup
- − code-style
- − architecture
- − git-pr
- − performance
- − do-not
- agent-behaviour
Line diff
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
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
@@ −1 +1 @@
1−# AGENTS.md
1+# CLAUDE.md → AGENTS.md
22
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>`.
3+Project instructions live in `AGENTS.md`. Read that file.
64
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.
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`.
128
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".>
9+If you are an AI tool reading this file: open `AGENTS.md` in this repo
10+and follow the instructions there.
39111
