Comparison

A · AGENTS.md · machbuilds/atom B · AGENTS.md · machbuilds/atom

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	8	18	0%
Commands	0	0	2	0%
Section tags	2	1	5	25%

What each file covers

Sections

0 shared · 8 only in A · 18 only in B

− AGENTS.md — atom
− Two modes you operate in here
− Mode 1 — Bootstrap a new project
− Mode 2 — Maintain atom itself
− Mode 3 — Build atom features
− What NOT to do here
− Memory architecture (inherited by every project bootstrapped from atom)
− Voice
+ 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

2 shared · 1 only in A · 5 only in B

− build
+ setup
+ architecture
+ git-pr
+ do-not
+ agent-behaviour
code-style
performance

Line diff

+362 added−96 removed29 unchanged7.4% identical

machbuilds/atom · AGENTS.md

@@ −1 @@

1# AGENTS.md — atom

3This is **atom**, a project-starter template. It is not an application. When

4you read this file, you are being asked to help bootstrap a NEW project from

5this template, OR to maintain the template itself by adding new learnings.

7The name: every project starts from atom. Atom is the seed.

9This file is the source of truth for AI tooling instructions. Tool-specific

10files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`,

11`.github/copilot-instructions.md`) are forwarders that point here.

13## Two modes you operate in here

15### Mode 1 — Bootstrap a new project

17When the user says "let's start a new project from atom", or similar:

191. **Ask for project context first**:

20 - Project name and one-line description (what + why)

21 - Primary stack/runtime (Next.js? Python? Swift? Other?)

22 - Deploy target (Railway? Vercel? Fly? AWS? Custom? Don't know yet?)

23 - Cost envelope expectations (per-request or monthly)

24 - Solo build or multi-agent (Backend / Design / Test / Deploy split)?

25 - Public-facing or internal-only?

272. **Read the docs in this order** (you must, even if you've read them before

28 on a different machine — they may have evolved):

29 - `docs/VOICE.md` — how to write

30 - `docs/WORKFLOW.md` — how the toolchain composes

31 - `docs/PATTERNS.md` — reusable patterns to consider

32 - `docs/LESSONS_LEARNED.md` — pain points to avoid

33 - `docs/HOW_TO_WRITE_CONSTITUTION.md` — for the new project's constitution

34 - `docs/HOW_TO_PICK_DEPLOY_TARGET.md` — only if user said "don't know yet"

35 - `docs/HOW_TO_DESIGN.md` — only if the project has a UI

373. **Copy `scaffold/` into the new project repo**. The `.github/`, `.claude/`,

38 `.gitignore`, `package.json`, `AGENTS.md` all go to the new repo's root.

39 Docker files do NOT live in `scaffold/` (Docker is fully optional).

414. **Ask the user which Docker tier** (None / Dockerfile / + compose /

42 + devcontainer) and copy the matching subset from `extras/docker/`.

43 See `extras/docker/README.md` for the tier-to-file mapping. If the

44 stack matches one in `extras/<category>/<preset>/` and that preset

45 ships a `Dockerfile`, prefer the stack-specific one over the generic.

475. **Walk the user through filling `scaffold/AGENTS.md` placeholders**

48 (search for `<TODO>` markers): project name, principles, tech stack lock,

49 agent ownership, env vars, references.

516. **Write the constitution**: follow `docs/HOW_TO_WRITE_CONSTITUTION.md`

52 methodology to draft it, THEN run the `speckit-constitution` skill once

53 as a verification pass to catch anything the methodology missed.

557. **Run tooling install** per `INSTALL.md`: Multica auth, mem0 MCP, GBrain

56 init, Gstack/GSD skill availability, Spec Kit, Task Master, Grill-me,

57 Chrome DevTools MCP.

598. **Begin the GSD/Spec Kit flow**: `/gsd-new-project` OR

60 `speckit-specify` → `speckit-plan` → `speckit-tasks`. User's preference.

629. **Initial commit + push**, then start Phase 1.

64### Mode 2 — Maintain atom itself

66When the user says "add this lesson to atom", "update atom with X", or

67similar:

691. **Read `CONTRIBUTING.md`** for the rules.

702. **Apply the generalisation test**: would this help a project unrelated

71 to where it came from?

723. **If yes**: propose the structured entry, ask user to confirm wording,

73 append to the right file (`PATTERNS.md`, `LESSONS_LEARNED.md`, or new

74 `extras/<category>/<preset>/`).

754. **If no**: suggest scrubbing the project-specific bits or dropping.

765. **If unsure**: drop it in `docs/INBOX.md` raw, refine later.

776. **Always commit changes to atom** with a message that names the

78 source project (e.g., `lessons: pin deps to minor (from wallet-persona)`).

80### Mode 3 — Build atom features

82When the user says "let's build nucleus", "start on Docker", "build the

83wizard", or similar:

851. **Read the relevant plan** in `docs/planning/<feature>.md`. Each plan

86 captures locked decisions, rationale, schemas, and risks. Plans are

87 the source of truth for build work.

882. **Build order (locked)**: nucleus → learnings → docker → model-race.

89 `atom-setup` builds incrementally as features land.

903. **Do not re-litigate decisions in the plan without a written reason.**

91 The decisions came from a thorough planning session. If you find a

92 reason to deviate, surface it before changing course.

934. After each feature ships, update its plan doc with `Status: built`

94 and link the implementation files.

955. Cross-feature references: `nucleus` powers `learnings`; `atom-setup`

96 wires both into the wizard. Build order respects this.

98## What NOT to do here

100- **Don't develop application features inside atom.** This repo seeds new

101 projects. It is not itself a project.

102- **Don't copy project-specific lessons** (specific API quirks, specific

103 domain logic) into `LESSONS_LEARNED.md`. Only generalisable patterns.

104 Project-specific stays in the source project.

105- **Don't add stack-specific files outside `extras/<category>/<preset>/`.**

106 When updating `scaffold/`, keep it framework-agnostic.

107- **Don't grow `docs/INBOX.md` indefinitely.** Promote or delete entries

108 on a regular cadence (end of project, end of quarter).

109

110## Memory architecture (inherited by every project bootstrapped from atom)

111

112Load order at task start in any bootstrapped project:

113**project's AGENTS.md → mem0 query → GBrain search → Multica skill →

114.claude/memory.md**

115

116Set mem0 `user_id` per-project (e.g., `user_id: "<project-slug>"`). Log

117to mem0 after every commit with the SHA, what changed, and the

118non-obvious why.

119

120## Voice

121

122Read `docs/VOICE.md`. In short: builder-to-builder, direct, concrete, tied

123to user outcomes. No corporate hedging. No AI vocabulary. Same voice for

124the template and every project bootstrapped from it.

125

machbuilds/atom · scaffold/AGENTS.md

@@ +1 @@

1# AGENTS.md

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>`.

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.

13## Project overview

15<TODO: 1-paragraph description — what this is, what problem it solves,

16who the user is. Be concrete. Reference real numbers if they exist.>

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.>

22## <N> non-negotiable principles (constitution v<TODO>)

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`.>

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>**

33## Tech stack (locked)

35<TODO: pin runtime, framework, key libraries. Pin to caret-minor, not

36exact patch. See atom's `docs/LESSONS_LEARNED.md` on dependency pinning.>

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>

45<TODO: one-line cost envelope expectation — e.g., "~$0.005/request at scale"

46or "~$50/month at expected traffic">

48## Folder conventions

50<TODO: describe the project's directory structure. Keep it terse — the

51pattern is what matters, not every file.>

53```

54src/

55├── <main entry>

56├── <api/server logic>

57├── <components — if frontend>

58├── <lib — pure functions>

59├── <types>

60├── <constants>

61└── <tests>

62```

64<TODO: one-line note on where pure functions live vs where I/O lives.>

66## Agent ownership rules (do not cross boundaries)

68<TODO: customise this matrix for the project. If solo with no agent split,

69write "solo build — no agent split" and skip the table.>

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> |

78If a task forces you across a boundary, **stop** and flag it as a routing

79error. Never silently edit another agent's files.

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.

87## Workflow discipline (Superpowers — non-negotiable)

89Every task: **clarify → design → plan → TDD → build → verify**. Skipping

90a step = mandatory restart. Writing code before a failing test exists =

91mandatory restart.

93## Environment variables

95`.env` is never committed. `.env.example` is the canonical reference.

97<TODO: list env vars in this format. Mark each Required or Optional per

98the two-tier pattern in atom's `docs/PATTERNS.md`.>

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>" \

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−# AGENTS.md — atom

1+# AGENTS.md

3−This is **atom**, a project-starter template. It is not an application. When

4−you read this file, you are being asked to help bootstrap a NEW project from

5−this template, OR to maintain the template itself by adding new learnings.

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>`.

7−The name: every project starts from atom. Atom is the seed.

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−This file is the source of truth for AI tooling instructions. Tool-specific

10−files (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`,

11−`.github/copilot-instructions.md`) are forwarders that point here.

13+## Project overview

1214

13−## Two modes you operate in here

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.>

1417

15−### Mode 1 — Bootstrap a new project

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.>

1621

17−When the user says "let's start a new project from atom", or similar:

22+## <N> non-negotiable principles (constitution v<TODO>)

1823

19−1. **Ask for project context first**:

20− - Project name and one-line description (what + why)

21− - Primary stack/runtime (Next.js? Python? Swift? Other?)

22− - Deploy target (Railway? Vercel? Fly? AWS? Custom? Don't know yet?)

23− - Cost envelope expectations (per-request or monthly)

24− - Solo build or multi-agent (Backend / Design / Test / Deploy split)?

25− - Public-facing or internal-only?

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`.>

2626

27−2. **Read the docs in this order** (you must, even if you've read them before

28− on a different machine — they may have evolved):

29− - `docs/VOICE.md` — how to write

30− - `docs/WORKFLOW.md` — how the toolchain composes

31− - `docs/PATTERNS.md` — reusable patterns to consider

32− - `docs/LESSONS_LEARNED.md` — pain points to avoid

33− - `docs/HOW_TO_WRITE_CONSTITUTION.md` — for the new project's constitution

34− - `docs/HOW_TO_PICK_DEPLOY_TARGET.md` — only if user said "don't know yet"

35− - `docs/HOW_TO_DESIGN.md` — only if the project has a UI

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>**

3632

37−3. **Copy `scaffold/` into the new project repo**. The `.github/`, `.claude/`,

38− `.gitignore`, `package.json`, `AGENTS.md` all go to the new repo's root.

39− Docker files do NOT live in `scaffold/` (Docker is fully optional).

33+## Tech stack (locked)

4034

41−4. **Ask the user which Docker tier** (None / Dockerfile / + compose /

42− + devcontainer) and copy the matching subset from `extras/docker/`.

43− See `extras/docker/README.md` for the tier-to-file mapping. If the

44− stack matches one in `extras/<category>/<preset>/` and that preset

45− ships a `Dockerfile`, prefer the stack-specific one over the generic.

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.>

4637

47−5. **Walk the user through filling `scaffold/AGENTS.md` placeholders**

48− (search for `<TODO>` markers): project name, principles, tech stack lock,

49− agent ownership, env vars, references.

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>

5044

51−6. **Write the constitution**: follow `docs/HOW_TO_WRITE_CONSTITUTION.md`

52− methodology to draft it, THEN run the `speckit-constitution` skill once

53− as a verification pass to catch anything the methodology missed.

45+<TODO: one-line cost envelope expectation — e.g., "~$0.005/request at scale"

46+or "~$50/month at expected traffic">

5447

55−7. **Run tooling install** per `INSTALL.md`: Multica auth, mem0 MCP, GBrain

56− init, Gstack/GSD skill availability, Spec Kit, Task Master, Grill-me,

57− Chrome DevTools MCP.

48+## Folder conventions

5849

59−8. **Begin the GSD/Spec Kit flow**: `/gsd-new-project` OR

60− `speckit-specify` → `speckit-plan` → `speckit-tasks`. User's preference.

50+<TODO: describe the project's directory structure. Keep it terse — the

51+pattern is what matters, not every file.>

6152

62−9. **Initial commit + push**, then start Phase 1.

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+```

6363

64−### Mode 2 — Maintain atom itself

64+<TODO: one-line note on where pure functions live vs where I/O lives.>

6565

66−When the user says "add this lesson to atom", "update atom with X", or

67−similar:

66+## Agent ownership rules (do not cross boundaries)

6867

69−1. **Read `CONTRIBUTING.md`** for the rules.

70−2. **Apply the generalisation test**: would this help a project unrelated

71− to where it came from?

72−3. **If yes**: propose the structured entry, ask user to confirm wording,

73− append to the right file (`PATTERNS.md`, `LESSONS_LEARNED.md`, or new

74− `extras/<category>/<preset>/`).

75−4. **If no**: suggest scrubbing the project-specific bits or dropping.

76−5. **If unsure**: drop it in `docs/INBOX.md` raw, refine later.

77−6. **Always commit changes to atom** with a message that names the

78− source project (e.g., `lessons: pin deps to minor (from wallet-persona)`).

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.>

7970

80−### Mode 3 — Build atom features

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> |

8177

82−When the user says "let's build nucleus", "start on Docker", "build the

83−wizard", or similar:

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.

8480

85−1. **Read the relevant plan** in `docs/planning/<feature>.md`. Each plan

86− captures locked decisions, rationale, schemas, and risks. Plans are

87− the source of truth for build work.

88−2. **Build order (locked)**: nucleus → learnings → docker → model-race.

89− `atom-setup` builds incrementally as features land.

90−3. **Do not re-litigate decisions in the plan without a written reason.**

91− The decisions came from a thorough planning session. If you find a

92− reason to deviate, surface it before changing course.

93−4. After each feature ships, update its plan doc with `Status: built`

94− and link the implementation files.

95−5. Cross-feature references: `nucleus` powers `learnings`; `atom-setup`

96− wires both into the wizard. Build order respects this.

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.

9786

98−## What NOT to do here

87+## Workflow discipline (Superpowers — non-negotiable)

9988

100−- **Don't develop application features inside atom.** This repo seeds new

101− projects. It is not itself a project.

102−- **Don't copy project-specific lessons** (specific API quirks, specific

103− domain logic) into `LESSONS_LEARNED.md`. Only generalisable patterns.

104− Project-specific stays in the source project.

105−- **Don't add stack-specific files outside `extras/<category>/<preset>/`.**

106− When updating `scaffold/`, keep it framework-agnostic.

107−- **Don't grow `docs/INBOX.md` indefinitely.** Promote or delete entries

108− on a regular cadence (end of project, end of quarter).

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.

10992

110−## Memory architecture (inherited by every project bootstrapped from atom)

93+## Environment variables

11194

112−Load order at task start in any bootstrapped project:

113−**project's AGENTS.md → mem0 query → GBrain search → Multica skill →

114−.claude/memory.md**

95+`.env` is never committed. `.env.example` is the canonical reference.

11596

116−Set mem0 `user_id` per-project (e.g., `user_id: "<project-slug>"`). Log

117−to mem0 after every commit with the SHA, what changed, and the

118−non-obvious why.

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`.>

11999

120−## Voice

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> |

121105

122−Read `docs/VOICE.md`. In short: builder-to-builder, direct, concrete, tied

123−to user outcomes. No corporate hedging. No AI vocabulary. Same voice for

124−the template and every project bootstrapped from it.

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>" \

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".>

125391