| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 18 | 8 | 0% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 2 | 5 | 1 | 25% |
What each file covers
Sections
0 shared · 18 only in A · 8 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
- + 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
Commands
0 shared · 2 only in A · 0 only in B- − git add path/to/file
- − git add .
Section tags
2 shared · 5 only in A · 1 only in B- − setup
- − architecture
- − git-pr
- − do-not
- − agent-behaviour
- + build
- code-style
- performance
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 · AGENTS.md
@@ +1 @@
1# AGENTS.md — atom
2
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.
6
7The name: every project starts from atom. Atom is the seed.
8
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.
12
13## Two modes you operate in here
14
15### Mode 1 — Bootstrap a new project
16
17When the user says "let's start a new project from atom", or similar:
18
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?
26
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
36
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).
40
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.
46
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.
50
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.
54
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.
58
598. **Begin the GSD/Spec Kit flow**: `/gsd-new-project` OR
60 `speckit-specify` → `speckit-plan` → `speckit-tasks`. User's preference.
61
629. **Initial commit + push**, then start Phase 1.
63
64### Mode 2 — Maintain atom itself
65
66When the user says "add this lesson to atom", "update atom with X", or
67similar:
68
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)`).
79
80### Mode 3 — Build atom features
81
82When the user says "let's build nucleus", "start on Docker", "build the
83wizard", or similar:
84
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.
97
98## What NOT to do here
99
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
@@ −1 +1 @@
1−# AGENTS.md
1+# AGENTS.md — atom
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+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.
66
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.
7+The name: every project starts from atom. Atom is the seed.
128
13−## Project overview
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.
1412
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.>
13+## Two modes you operate in here
1714
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.>
15+### Mode 1 — Bootstrap a new project
2116
22−## <N> non-negotiable principles (constitution v<TODO>)
17+When the user says "let's start a new project from atom", or similar:
2318
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`.>
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?
2626
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>**
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
3236
33−## Tech stack (locked)
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).
3440
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.>
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.
3746
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>
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.
4450
45−<TODO: one-line cost envelope expectation — e.g., "~$0.005/request at scale"
46−or "~$50/month at expected traffic">
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.
4754
48−## Folder conventions
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.
4958
50−<TODO: describe the project's directory structure. Keep it terse — the
51−pattern is what matters, not every file.>
59+8. **Begin the GSD/Spec Kit flow**: `/gsd-new-project` OR
60+ `speckit-specify` → `speckit-plan` → `speckit-tasks`. User's preference.
5261
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−```
62+9. **Initial commit + push**, then start Phase 1.
6363
64−<TODO: one-line note on where pure functions live vs where I/O lives.>
64+### Mode 2 — Maintain atom itself
6565
66−## Agent ownership rules (do not cross boundaries)
66+When the user says "add this lesson to atom", "update atom with X", or
67+similar:
6768
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.>
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)`).
7079
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> |
80+### Mode 3 — Build atom features
7781
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.
82+When the user says "let's build nucleus", "start on Docker", "build the
83+wizard", or similar:
8084
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.
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.
8697
87−## Workflow discipline (Superpowers — non-negotiable)
98+## What NOT to do here
8899
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.
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).
92109
93−## Environment variables
110+## Memory architecture (inherited by every project bootstrapped from atom)
94111
95−`.env` is never committed. `.env.example` is the canonical reference.
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**
96115
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`.>
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.
99119
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> |
120+## Voice
105121
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".>
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.
391125
