Gabriel Brown
89761a7da3
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.
2.2 KiB
2.2 KiB
CONTEXT.md format
Structure
# {Context name}
{One or two sentences: what this context is and why it exists.}
## Language
**Order**:
{One or two sentences describing the term.}
_Avoid_: Purchase, transaction
**Invoice**:
A request for payment sent to a customer after delivery.
_Avoid_: Bill, payment request
**Customer**:
A person or organization that places orders.
_Avoid_: Client, buyer, account
Rules
- Be opinionated. Where several words exist for one concept, pick the best and list the rest
under
_Avoid_. A glossary that refuses to choose is a thesaurus, and settles nothing. - Keep definitions tight. One or two sentences. Define what the term is, not what it does.
- Only terms specific to this project. General programming concepts (timeouts, error types, utility patterns) do not belong, however heavily the project uses them. Before adding a term, ask whether it is unique to this context or just general vocabulary. Only the former earns a place.
- Group under subheadings once natural clusters emerge. A flat list is fine while the terms belong to one cohesive area.
Single vs multi-context repos
Single context, which is most repos: one CONTEXT.md at the root.
Multiple contexts: a CONTEXT-MAP.md at the root lists them, where they live, and how they
relate:
# Context map
## Contexts
- [Ordering](./src/ordering/CONTEXT.md): receives and tracks customer orders
- [Billing](./src/billing/CONTEXT.md): generates invoices and processes payments
- [Fulfillment](./src/fulfillment/CONTEXT.md): manages warehouse picking and shipping
## Relationships
- **Ordering → Fulfillment**: Ordering emits `OrderPlaced`; Fulfillment consumes it to start picking
- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched`; Billing generates the invoice
- **Ordering ↔ Billing**: shared types for `CustomerId` and `Money`
Infer which structure applies:
CONTEXT-MAP.mdexists → read it to find the contexts- Only a root
CONTEXT.md→ single context - Neither → single context; create the root
CONTEXT.mdlazily when the first term resolves
Where several contexts exist, infer which one the current topic belongs to, and ask if it is unclear.