| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 0 | 8 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 0 | 3 | 0% |
What each file covers
Sections
0 shared · 0 only in A · 8 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
Commands
neither file has anySection tags
0 shared · 0 only in A · 3 only in B- + build
- + code-style
- + performance
Line diff
machbuilds/atom · scaffold/.cursorrules
@@ −1 @@
1Project instructions live in AGENTS.md. Read that file before starting
2any work.
3
4This .cursorrules exists so Cursor's default rule auto-load works
5without duplicating content.
6
7Open AGENTS.md in the project root and follow the instructions there.
8
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−Project instructions live in AGENTS.md. Read that file before starting
2−any work.
1+# AGENTS.md — atom
32
4−This .cursorrules exists so Cursor's default rule auto-load works
5−without duplicating content.
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−Open AGENTS.md in the project root and follow the instructions there.
7+The name: every project starts from atom. Atom is the seed.
8+
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.
12+
13+## Two modes you operate in here
14+
15+### Mode 1 — Bootstrap a new project
16+
17+When the user says "let's start a new project from atom", or similar:
18+
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?
26+
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
36+
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).
40+
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.
46+
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.
50+
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.
54+
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.
58+
59+8. **Begin the GSD/Spec Kit flow**: `/gsd-new-project` OR
60+ `speckit-specify` → `speckit-plan` → `speckit-tasks`. User's preference.
61+
62+9. **Initial commit + push**, then start Phase 1.
63+
64+### Mode 2 — Maintain atom itself
65+
66+When the user says "add this lesson to atom", "update atom with X", or
67+similar:
68+
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)`).
79+
80+### Mode 3 — Build atom features
81+
82+When the user says "let's build nucleus", "start on Docker", "build the
83+wizard", or similar:
84+
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.
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+
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**
115+
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.
119+
120+## Voice
121+
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.
8125
