Keep the personal half of the desktop in one place, and ask before installing it

Agent instructions, skills, SSH host aliases and expansion triggers are worth
having identical on every machine one person owns, and belong in none of the
shared configuration. They live in user/ now, with a manifest saying where each
piece goes and a link-user stage that puts it there.

That stage does nothing unless the machine said yes. Somebody who clones Panama
to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was;
the question names the destinations and defaults to no. Anything displaced goes
to config/old rather than being deleted.

~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one
file, which is the drift this exists to prevent.

Also adds the vitals toggles for the battery and Claude usage readouts, which
had preferences and no way to reach them.
This commit is contained in:
Gabriel Brown
2026-08-22 08:54:43 -04:00
parent 8b96d907a1
commit 89761a7da3
156 changed files with 16439 additions and 6 deletions
+106
View File
@@ -0,0 +1,106 @@
---
name: domain-modeling
description: Use when a term is fuzzy, overloaded, or contradicts how the code behaves; when writing or editing a CONTEXT.md glossary; or when a hard-to-reverse decision needs recording as an ADR.
---
# Domain Modeling
Actively build and sharpen a project's domain model as you design: challenge terms, stress-test them
with scenarios, and write the glossary and the decisions down the moment they crystallise.
This is the *active* discipline. Merely **reading** `CONTEXT.md` for vocabulary is a one-line habit
any skill can do and is not this skill. Reach for this one when you are **changing** the model, not
consuming it.
## File structure
Most repos have a single context:
```
/
├── CONTEXT.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
```
A `CONTEXT-MAP.md` at the root means the repo has several contexts, and the map points to where each
one lives:
```
/
├── CONTEXT-MAP.md
├── docs/adr/ ← system-wide decisions
└── src/
├── ordering/
│ ├── CONTEXT.md
│ └── docs/adr/ ← context-specific decisions
└── billing/
├── CONTEXT.md
└── docs/adr/
```
Create files lazily, only once there is something to write. No `CONTEXT.md` yet? Create it when the
first term is resolved. No `docs/adr/`? Create it when the first ADR is needed.
## During the session
### Challenge against the glossary
When a term conflicts with the language already in `CONTEXT.md`, call it out immediately.
> "Your glossary defines *cancellation* as X, but you seem to mean Y here. Which is it?"
### Sharpen fuzzy language
When a term is vague or overloaded, propose a precise canonical one.
> "You're saying *account*: do you mean the Customer or the User? Those are different things."
### Discuss concrete scenarios
When domain relationships are on the table, stress-test them with specific scenarios. Invent the
edge cases that force the boundaries between concepts to become precise.
### Cross-reference with the code
When a claim is made about how something works, check whether the code agrees, and surface any
contradiction.
> "The code cancels whole Orders, but you just said partial cancellation is possible. Which is right?"
The schema is the highest-signal place to check, because it is where the domain nouns are declared
rather than merely used. In a Convex project that is `convex/schema.ts`; elsewhere it is whatever
file defines the tables or types. A term that appears in conversation but nowhere in the schema is
either missing from the model or is not really a domain term.
### Update CONTEXT.md inline
When a term resolves, write it to `CONTEXT.md` right then. Do not batch them: capture each as it
happens, because the precision is what fades between now and the end of the session. Use the format
in [CONTEXT-FORMAT.md](CONTEXT-FORMAT.md).
`CONTEXT.md` is a glossary and nothing else. Keep implementation details, specs, and scratch notes
out of it.
### Offer ADRs sparingly
Offer an ADR only when all three are true:
1. **Hard to reverse**: the cost of changing your mind later is meaningful.
2. **Surprising without context**: a future reader will wonder "why on earth did they do it this
way?"
3. **The result of a real trade-off**: genuine alternatives existed and one was picked for specific
reasons.
Missing any one of the three, skip it. Use the format in [ADR-FORMAT.md](ADR-FORMAT.md).
## Done when
- Every term resolved this session is in `CONTEXT.md`, in the house format, with its rejected
synonyms under `_Avoid_`.
- No implementation detail has leaked into `CONTEXT.md`.
- Every contradiction found between a stated claim and the code was surfaced, not silently resolved.
- An ADR exists for each decision meeting all three tests, and for none that miss one.