AGENTS.md

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