My/Dotfiles/Process/Adding a New Global Dependency/Idea
Refining the Process of Adding Dependencies to my Dotfiles with Agent Skills
Current vision
The goal
- As part of my effort to be guided by documented principles, for each thing configured in My/Dotfiles, I want myself to have documented what each tool or configuration option, why it's necessary, and some analysis of that dependency's security and consistency with My/Principles.
- I want a process that surface the parts that are not. This applies to tools already installed as much as to new ones. Adding something new should be rigorous but low-friction; it is never blocked.
Two loops
- Inner loop — the dotfiles OpenSpec. Concrete if / when / then requirements for how chezmoi, mise, LazyVim, and the rest are configured. It can be regenerated from its specs.
- Outer loop — a garden-side system of Agent/Skills whose specification is my My/Principles, My/Prefs, and articulated ideas, and whose target is the dotfiles. It is the why and whether; the inner loop is the how.
- The two meet at eventual consistency, one tool at a time. A tool can be installed and only partly gardened; the outer loop surfaces that gap and closes it over time — lazily for what is already installed, with more scrutiny for new additions.
- The skills make the rigorous path the low-friction one, so the aim is not to slow adoption but to make the disciplined route the easy route. An undocumented, unvetted install is what should meet friction. The corollary fits the model: demos are easy, production earns quality control — a cheap idea versus a vetted adoption.
Two entities, not three tiers
- Logseq/Entity/Dotfiles/Dep/Idea — an idea: a job to be done for the toolchain, keyed to the job rather than a tool, for example Terminal/Multiplexer/Idea. Cheap to record, no status property, progress shown by the notes present. It works forward — jot an idea, later adopt a tool — and backward — write the idea behind an already-installed tool.
- Logseq/Entity/Dotfiles/Dep — the tool that fills an idea, usually also a Logseq/Entity/Software/Project, carrying its own adoption status (candidate, adopted, retired).
- An installed tool's status is an asserted fact; an idea's progress is a claim it should not assert, only show. My/Principle/Make Illegal States Unrepresentable: an idea is not a half-built dependency, so the two are separate pages and a dependency is always a real tool.
Stage implied by deliverables
- An idea has no stored stage. Its progress is the furthest deliverable present on it:
- a survey of the alternatives
- a security read of the candidates — see 2026-06-27 Sat for the impetus, and tools like deptrust
- a decision naming the tool chosen, or recording that none was and why
- This mirrors OpenSpec, where progress is the artifacts rather than a status field. Each deliverable is a page or section that fits a schema, in the spirit of Logseq/Entity/Definition and Structured Output.
Handoff to the dotfiles
Given a new technology
- The entry move is a guided OpenSpec explore, widened to research both the dotfiles and the garden. AI imports the technology as a Logseq/Entity/Software/Project, reviews my principles and preferences, checks that it does not duplicate a tool already doing the same job, and interviews me critically — pushing back to keep me consistent with what I have written down. The first question is whether to add the dependency at all.
Try-before-commit window (Homebrew case)
- Homebrew is the one dotfiles backend where installing and declaring are separate actions:
brew install x works whether or not x is in the Brewfile. That gap is the low-friction "try it out" move this Idea already asks for — install something to try it, live with it a few days, then decide. - The corresponding rule is My/Principle/Declarative over Imperative applied to Homebrew:
chezmoi/Brewfile is meant to be the complete record of everything brew manages, not a hand-picked subset. A brew install absent from the Brewfile is fine while under evaluation, not fine as a permanent state. - The garden-side ritual: once a week or so, compare what's actually brew-installed (formulae marked
--installed-on-request, plus casks) against the Brewfile, and uninstall anything not explicitly committed. This applies the outer loop's weekly check to Homebrew specifically — same "surface the gap, close it" pattern as the rest of this Idea, on a regular schedule instead of lazily. - This is the other half of My/Dotfiles/openspec/specs/brewfile-style (only what mise can't do belongs in the Brewfile): what does belong there must actually be there.
- See 2026-07-17 Fri.
Deprecated
- The flag-based
dotfiles-dep-stage:: enum (1 Incubating through 5 Selected, plus Adopted, Declined, Retired) as the funnel tracker. Replaced by deliverable-implied progress: a stored stage can claim work that was never done. - The earlier Need-versus-Dep framing, where a Need held the record. Replaced by Logseq/Entity/Dotfiles/Dep/Idea, keyed to the job.
- The want / need / desire tier. Dropped as a distinction not acted on differently, per My/Principle/Simplify/Not every distinction is worth recording; necessity is at most a note on an idea.
Open questions
- the minimal deliverable set to start with
- each deliverable as a freeform section or subpage versus its own entity type — starting freeform, promoted only if it earns the distinction
- whether presence gates on the existence or the completion of a deliverable
- how to tolerate an idea that skips a step — a trivial one may need no survey
- whether the garden should link back to the dotfiles location; today the link runs one way, dotfiles to garden