AGENTS.md

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