| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 8 | 0 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 0 | 3 | 0 | 0% |
What each file covers
Sections
0 shared · 8 only in A · 0 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 · 3 only in A · 0 only in B- − build
- − code-style
- − performance
Line diff
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
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
@@ −1 +1 @@
1−# AGENTS.md — atom
1+Project instructions live in AGENTS.md. Read that file before starting
2+any work.
23
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.
4+This .cursorrules exists so Cursor's default rule auto-load works
5+without duplicating content.
66
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.
7+Open AGENTS.md in the project root and follow the instructions there.
1258
