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
@@ -0,0 +1,68 @@
# 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](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](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](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:
1. The interface: types, entry points, params, plus invariants, ordering, and error modes
2. A usage example showing how callers use it
3. What the implementation hides behind the seam
4. Its dependency strategy and adapters
5. 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.