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.
3.0 KiB
Design It Twice
Explore several interfaces for one module in parallel, because the first idea is unlikely to be the best. Uses the vocabulary in SKILL.md: module, interface, seam, adapter, leverage.
Gate: is this worth the ceremony?
This pattern spends several agents on one decision. It earns that only where the solution space is genuinely wide and the choice is expensive to reverse:
- Run it when the module is load-bearing, several plausibly-good interfaces exist, and callers will be written against whichever one wins.
- Skip it when one obvious interface fits, the module is small, or the decision is cheap to change later. Design it once, in this context window, and move on.
A single agent that finishes the job in one pass should just finish it. Reach for the fan-out for breadth, not for routine work.
Process
1. Frame the problem space
Before spawning anything, write a user-facing explanation of the problem space:
- The constraints any new interface must satisfy
- The dependencies it relies on, and their category from DEEPENING.md
- A rough code sketch to make the constraints concrete. This grounds the discussion; it is not a proposal.
Show it, then proceed immediately. The reading happens while the agents work.
2. Spawn the designers
Spawn three or more agents in parallel, each producing a radically different interface. Give each a separate technical brief (file paths, coupling details, dependency category, what sits behind the seam) and a different design constraint:
| Agent | Constraint |
|---|---|
| 1 | Minimise the interface: one to three entry points, maximum leverage per entry point |
| 2 | Maximise flexibility: support many use cases and extension |
| 3 | Optimise for the most common caller: make the default case trivial |
| 4 (where relevant) | Design around ports and adapters for cross-seam dependencies |
These agents design, they do not write. Each returns a proposal; none edits a file, so there is no file ownership to divide and no chance of a collision. Say so in each brief.
Include both the SKILL.md vocabulary and the project's CONTEXT.md vocabulary in every
brief, so the proposals name things consistently and can actually be compared.
Each agent returns:
- The interface: types, entry points, params, plus invariants, ordering, and error modes
- A usage example showing how callers use it
- What the implementation hides behind the seam
- Its dependency strategy and adapters
- Trade-offs: where leverage is high, where it is thin
3. Present and compare
Present the designs one at a time so each can be absorbed, then compare them in prose along depth (leverage at the interface), locality (where change concentrates), and seam placement.
Finish with your own recommendation: which design is strongest and why. Where elements from different designs combine well, propose the hybrid. Be opinionated. The point of the fan-out is a strong read, not a menu.