| name | add-package |
| description | Add a package to this macOS dotfiles repo. Use when the user asks to
install, add, or migrate a CLI package or GUI app, for example "add jq",
"ripgrep を入れて", "lazygit 入れたい", "brew install foo を repo 管理に",
"kubectl 追加して". Homebrew owns binaries here; update Brewfile, validate
with brew bundle, apply with brew bundle, and verify the executable.
|
add-package
Add packages through Homebrew. This repo's package management is the top-level
Brewfile.
Decision Flow
-
Identify the package name and whether it is a formula, cask, or non-brew
package.
-
Check Homebrew availability:
brew search <name>
brew info <name>
-
Edit Brewfile:
- CLI tools:
brew "<formula>"
- GUI apps:
cask "<cask>"
- Keep existing grouping and simple alphabetical order where practical.
- Keep package changes in
Brewfile.
- If a repo config, validation command, or agent rule requires the binary,
keep the Homebrew-owned package explicit even when it is already installed
transitively or outside the Brewfile.
-
Validate before applying:
brew bundle check --file Brewfile
- Apply:
brew bundle --file Brewfile
- Verify:
command -v <binary>
<binary> --version
For casks, verify with brew list --cask <name> or by checking the app
exists in /Applications.
Non-Homebrew Packages
Use non-brew installation only when Homebrew is unavailable or inappropriate,
for example npm-only ACP adapters. In that case:
- Install with the native package manager, e.g.
npm install -g <package>.
- Verify the exposed command with
command -v.
- State that it is not tracked by
Brewfile unless a Homebrew formula/cask
exists.
Validation
For package-only changes:
brew bundle check --file Brewfile
brew bundle --file Brewfile
If the package affects shell integration, also validate Fish:
fish -n fish/config.fish
for f in fish/functions/*.fish; do fish -n "$f" || exit 1; done
Don't
- Do not create unrelated package management files.
- Do not run
brew uninstall unless the user explicitly asks.
- Do not use
brew cleanup or uninstall unrelated local packages merely to
make the machine match the Brewfile; report that drift separately.
- Do not add a package twice under different names.
- Do not edit generated target files under
~/.config; edit repo sources.
- Do not reformat unrelated parts of
Brewfile.
