dotfiles

Cross-platform dev environment powered by Chezmoi + Homebrew. One command to a fully configured machine.

Quick Start · Report Bug · Agent Skills

Features

• Homebrew + apt as source of truth for CLIs (git, gh, kubectl, terraform, ...)
• Per-language version managers: fnm (Node), uv (Python), rustup (Rust)
• Pinned upstream installers for tools that need it: gcloud, aws-cli, Snowflake Cortex
• Zsh with Oh My Zsh + Powerlevel10k and pre-generated completions
• Tmux with Ctrl+a prefix, vim keys, Catppuccin cyberdream theme
• Ghostty terminal with cyberdream theme and MonaspiceNe Nerd Font
• Neovim (HEAD) with LSP for all included languages, tuned for reviewing agent work: a clickable Files/Changes/Tests sidebar, worktree switching, and buffers that reload when an agent edits them. See dot_config/nvim/README.md.
• AI agents (Claude Code, Antigravity, Codex, Copilot, OpenCode) auto-installed via chezmoi
• A portable agent skills catalog in dot_agents/skills/ and subagents in dot_agents/agents/, installable into any tool via agentspec. See Agent Skills for the full list.
• Chezmoi automation scripts that trigger on apply
• Docker cleanup launchd agent running daily at 3 AM

Quick Start

One-liner (installs Homebrew + chezmoi, then runs chezmoi init --apply):

curl -fsSL https://raw.githubusercontent.com/urmzd/dotfiles/main/install.sh | bash

With packs (company, team, or role overlays; --pack repeats), including private ones on a fresh laptop:

curl -fsSL https://raw.githubusercontent.com/urmzd/dotfiles/main/install.sh | bash -s -- \
    --pack git@github.com:acme/dev-setup.git//backend-engineer

The first apply installs git, gh, gpg, and the dotfiles CLI. If a pack cannot be fetched yet (a private repo before this machine has GitHub access), the installer runs dotfiles identity (browser sign-in to gh, an SSH key created and uploaded), loads the key into ssh-agent (on macOS, its passphrase is saved in Keychain), and applies twice more: once to clone the packs, once to install what they contain. SSH and HTTPS pack URLs both work: GitHub's host keys are added to ~/.ssh/known_hosts from its API over HTTPS, and HTTPS clones of github.com use gh's token. Without a terminal it skips this and prints the commands to run.

Or step by step:

# 1. Install Homebrew (macOS) or your distro's package manager (Linux)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. Install chezmoi and apply this repo in one shot
sh -c "$(curl -fsLS https://get.chezmoi.io)" -- init --apply urmzd

chezmoi apply installs Brewfile/apt packages, sets up gcloud/aws/cortex from upstream, and installs the AI CLIs. Open a new terminal afterwards.

The bootstrap does not depend on our releases being healthy. chezmoi comes from get.chezmoi.io, falling back to Homebrew. The dotfiles CLI comes from the newest release that has a binary for your platform (the latest can be mid-build or failed), falling back to building cli/ from the checkout with cargo. If both fail, the apply still finishes: the CLI is optional. Re-running the bootstrap fast-forwards an existing checkout before applying, and every third-party installer is downloaded and checked before it runs, so a network failure warns instead of passing silently.

chezmoi init asks only what it cannot derive: name (prefilled on macOS), machine type (personal or work), one email for commits, Cortex, package preset, which AI coding CLIs to install, and excludes. On a personal machine the GitHub user comes from the repo remote; the GPG key always comes from your keyring. A personal machine is asked for its email and about secrets management; a work machine is asked for its work email, its work GitHub account, and an optional list of packs (git URLs, url//folder, or local folders), and never for personal details. See Setting up a machine's GitHub identity for keys. Re-running chezmoi init reuses every saved answer.

Usage

Day-to-day

chezmoi diff          # Preview pending dotfile changes
chezmoi apply         # Apply dotfile changes to $HOME
chezmoi add <file>    # Start tracking a new file
chezmoi edit <file>   # Edit source, then apply

Maintenance

The dotfiles command is a Rust CLI built from cli/ in this repo. Every release attaches its binaries for macOS and Linux (x86_64 and arm64) with .sha256 checksums; the first apply installs it, and dotfiles update keeps it and the dotfiles current. To install it by hand: curl -fsSL https://raw.githubusercontent.com/urmzd/dotfiles/main/cli/install.sh | sh.

dotfiles package                 # Search + toggle optional packages, then apply
dotfiles package add acli twg    # Select by id; `package remove` deselects (--uninstall to brew uninstall)
dotfiles package list --selected # The catalog with this machine's selection
dotfiles package setup           # Pending sign-in / interactive installers for selected packages
dotfiles package update          # brew upgrade + AI CLIs, then apply (or: brew | ai)
dotfiles theme set tokyonight    # Color theme for Ghostty, Neovim, tmux, and dotfiles output; `dotfiles theme` lists
dotfiles pack add <url//folder>  # Stack a pack (company, role, personal); also: pack list, pack remove
dotfiles identity                # This machine's GitHub identity: gh, SSH + GPG keys, signing check
dotfiles doctor                  # Health check, each finding with the command that fixes it
dotfiles plan                    # Desired vs installed: migrations, files, packages (+ missing, - deselected)
dotfiles apply                   # Make the machine match the plan (-y skips confirm, --prune uninstalls deselected)
dotfiles diff                    # Full diff of pending file changes
dotfiles config                  # Re-run the setup questions (saved answers kept), then apply
dotfiles status                  # Machine, packages, pending setup, tool versions
dotfiles update                  # Update everything: the CLI, pull the dotfiles, then apply
dotfiles self-update             # Update only the CLI
dotfiles edit                    # Open the dotfiles source in $EDITOR
dotfiles clean                   # Prune build artifacts and caches under ~/github

Desired state, like Terraform. The desired packages are the selection plus required pack entries; what is installed is probed fresh every run (Homebrew, npm, uv, the Linux package manager, or a package's check), never remembered, so a failed install cannot be marked done. dotfiles plan shows the difference, dotfiles apply closes it, and dotfiles update runs both after pulling. Selection changes that ship in a release (for example, existing machines gaining Claude Code) run as migrations on the next apply instead of waiting for chezmoi init. Only packages the CLI has seen installed are offered for --prune; software installed by hand is listed, never removed. Ownership lives in ~/.local/state/dotfiles/managed.json.

dotfiles doctor checks chezmoi, the catalog and selection, whether the CLI is the latest release, unapplied changes, Python (3.12+, gcloud pinned), that gh is signed in as this machine's account, that the commit signing key exists, AI CLIs installed twice (the first on PATH wins), and the package plan: selected packages that are missing, deselected ones still installed, pending migrations, and pending sign-ins. --format json prints the findings for scripts.

What's installed

CLI essentials (Homebrew on macOS, apt/dnf/pacman on Linux): git, gh, fzf, ripgrep, jq, yq, just, tmux, direnv, chezmoi, tree-sitter, uv, tealdeer, fnm, deno, go, lua, ...see Brewfile.tmpl.

Version managers (per-language, best-in-class): fnm (Node), uv (Python), rustup (Rust).

Default Python is a uv-managed CPython 3.12 (run_before_install-python.sh.tmpl): python/python3 link to it from ~/.local/share/dotfiles/python/bin, which zsh puts ahead of Homebrew and /usr/bin, and gcloud uses it through CLOUDSDK_PYTHON. Without it, python3 falls back to macOS's 3.9 (which breaks gcloud components) or to whatever python@3.x Homebrew pulled in. Bump PYTHON_VERSION in that script to change it; it re-checks on every apply, so a failed first install heals on the next.

Upstream-pinned installers (security/auth fixes ship faster than distro repos):

• gcloud + aws-cli, run_onchange_after_install-cloud-clis.sh.tmpl
• Snowflake Cortex Code, run_onchange_after_install-cortex.sh.tmpl (gated on install_cortex feature flag)
• gh CLI extensions, run_onchange_after_install-gh-extensions.sh.tmpl (github/gh-stack for stacked PRs)

Optional packages live in catalog.toml, grouped by category:

Category	Packages
cloud	Docker + Colima, Kubernetes (kubectl, helm, k9s), Terraform, RunPod, Temporal
languages	Zig, Scala (scala-cli + coursier), mise
mobile	Android Studio + SDK, CocoaPods
fonts	Nerd Fonts (MonaspiceNe, Iosevka)
notes	Obsidian, Notion, Granola, Mintlify CLI (mint)
editors	Cursor, Visual Studio Code
chat	Slack, Slack CLI (slack), Discord, Zoom
productivity	1Password, Raycast, Linear, Figma
ai	Claude, ChatGPT (desktop apps), Warp Agent CLI (warp, runs in Ghostty), Hugging Face CLI (hf)
media	Spotify
work	Atlassian CLI (acli), Teamwork Graph CLI (twg)
stack	teasr (README screenshots and GIFs), oag (OpenAPI client codegen)
skills	Agent skill packs: scaffolding, review, agent authoring, urmzd ecosystem, Vercel, Gemini, FastAPI, Better Auth, gh-stack

Bundles group packages so you pick a toolchain, not ten ids. Selecting a bundle selects all of its packages; drop any one afterwards in the package list.

Bundle	Packages	Presets
cloud	docker, kubernetes, terraform, runpod	standard, full
dev-skills	skills-scaffold, skills-review, skills-agent-dev	standard, full
framework-skills	skills-vercel, skills-gemini, skills-fastapi, skills-better-auth, skills-gh-stack	full
mobile	android, cocoapods	none
languages	zig, scala, mise	none
ecosystem	teasr, oag, skills-ecosystem	none

Always installed, whatever the selection: the core Brewfile, agentspec, sr, the dotfiles CLI, every subagent, and the core skills (every skill in dot_agents/skills/ that no skill pack lists).

Entries install through Homebrew (formulae and casks), npm -g into fnm's default Node, or uv tool install for Python CLIs. Each machine's selection is the list of ids at packages in its local chezmoi.toml. Change it with dotfiles package: first a bundle list (space to toggle a whole bundle), then the search-as-you-type package list to refine. dotfiles package add cloud takes bundle ids too. Brewfile.tmpl renders the selected entries on macOS; on Linux, run_onchange_after_install-catalog-linux.sh.tmpl installs their apt/dnf/pacman names (entries without any are macOS-only). Packages that need sign-in (acli, twg) finish with dotfiles package setup, never during apply.

On first init, package_preset seeds the selection: minimal = always-installed only (plus Obsidian), standard = + cloud, dev-skills, Nerd Fonts, full = + framework-skills, and custom opens the bundle multi-select. Heavy toolchains (mobile, Temporal, Zig, Scala, mise) and the apps beyond Obsidian are never preset; pick them explicitly. Machines set up before skill packs existed keep every skill pack plus teasr and oag, once, unasked (skills_seeded). pkg_exclude still drops individual core packages by name. To offer a new package, add a [[package]] entry to catalog.toml (and to a [[bundle]] if it belongs to one); no CLI release is needed. Every entry needs a category; for a GUI app use one from the table above and map each cask to its app bundle (apps = { "<cask>" = "<App>.app" }) so an app already in /Applications is skipped instead of failing the install.

The Brewfile installer continues past individual package failures, retries the remainder once, and prints categorized next steps (tap, permission, unknown formula, network, conflict) rather than aborting the whole apply. A cask that conflicts with an app already on disk is reported, not retried.

AI coding CLIs are catalog packages (category agents): Claude Code, Codex, GitHub Copilot CLI, Antigravity (agy), OpenCode, Gemini CLI, Cursor Agent CLI, and Amp. The first chezmoi init asks which to install (multi-select, default Claude Code + Codex); change them any time with dotfiles package. Claude Code, agy, and OpenCode use their own installers, which keep them updated (run_after_install-catalog-scripts.sh.tmpl, retried every apply until present); the rest come from Homebrew (npm on Linux). Codex runs with a workspace-write "Auto" default and writer/reviewer/plan/guardian profiles. dotfiles package update ai upgrades the selected ones.

Adding a new tool

Optional tools (apps, CLIs people pick per machine) go in catalog.toml as a [[package]] entry; dotfiles package add <id> installs one. Company tools go in a pack's catalog.toml instead (Packs). The steps below are for tools every machine gets:

1. Homebrew: add to Brewfile.tmpl. Linux: add to the apt/dnf/pacman list in run_once_before_install-packages-v2.sh.tmpl.
2. For tools needing version pinning: write a run_onchange_after_install-<name>.sh.tmpl mirroring the cortex / cloud-clis pattern.
3. Run chezmoi apply. Completions regenerate automatically, but check which of the three shapes the tool needs first:
   • Ships its own _<tool> into Homebrew's share/zsh/site-functions. Nothing to do, and run_onchange_after_z-generate-completions.sh.tmpl deliberately skips generating a rival copy, since Homebrew's tracks the installed formula version.
   • Has a <tool> completion zsh subcommand but no site-functions. Add a generate_completion line. Output goes to ~/.zsh/completions/ and is autoloaded lazily, so it costs nothing at shell startup.
   • Is bash-style (complete -C / complete -F, as with aws and npm) or otherwise needs compdef. It has to be appended to ~/.zsh/completions-post.zsh instead, which ~/.zshrc sources after compinit. A file placed in fpath without a leading #compdef line is never bound to any command and silently completes nothing.

Adding a new dotfile

1. Create or edit the file in your home directory
2. Run chezmoi add <file> to start tracking it
3. Use dot_ prefix naming, private_ for sensitive files, .tmpl for templates
4. Platform-specific blocks use {{ if eq .chezmoi.os "darwin" }}...{{ end }}

Configuration

Themes

One theme colors Ghostty, Neovim (colorscheme and lualine), tmux (catppuccin flavour and colors), and the dotfiles' own output. Built-ins live in themes/ (cyberdream, the default; tokyonight; catppuccin-mocha), and any pack can ship a theme.toml. dotfiles theme lists them and marks the one in effect; dotfiles theme set <name> switches and applies (auto follows the last pack theme). The machine's choice is theme in your local chezmoi.toml. themes/README.md has the format and where each app picks it up.

Packs

Company, team, and personal setup lives in optional packs: folders of plain files, usually in a company git repo shareable with teammates whether or not they use these dotfiles. A machine stacks any number of them, in order, in packs (dotfiles pack add|remove|list; a work machine's chezmoi init also asks):

Entry	Folder the hooks read	Fetching
git@github.com:acme/dev-setup.git//backend-engineer	that folder of the repo	repo cloned once to ~/.config/packs/dev-setup, fast-forwarded at most daily
https://github.com/acme/team.git	the whole repo	cloned to ~/.config/packs/team
~/my-overrides or /path	that folder, in place	none

<url>//<folder> is Terraform's module syntax: one company repo can hold base/, engineer/, backend-engineer/, and so on, and each person stacks the folders for their role. Fetching (run_after_sync-packs.sh.tmpl) never fails the apply: an unreachable or private repo (common on a new laptop before dotfiles identity adds its SSH key), a missing folder, or a non-git folder in the way only prints a warning with the next step. The bootstrap's --pack flag and its access setup cover a fresh laptop end to end (see Quick Start). Only the list is stored, in your local chezmoi.toml; nothing from a pack is tracked here. Configs from before the list keep their single work_pack as a one-pack list. To start one, copy pack-template/; its README has the steps.

Every file is optional, and each hook is a no-op when its file is missing:

File	Loaded by	With several packs
env.zsh	~/.zshenv (all shells, including agent tool calls)	sourced in order; later packs win
gitconfig	[include] in ~/.gitconfig (company URL rewrites, extra settings)	one include per pack, in order
ssh_config	Include at the top of ~/.ssh/config	one Include per pack, in order
Brewfile	appended to the Brewfile at install time; excludes and failure reporting apply, and a cask whose app is already in /Applications is skipped	all appended
catalog.toml	merged into the package catalog: entries show in dotfiles package tagged with their pack, and required = true ones always install. Checked before use (valid TOML, required fields); a bad file is ignored with a warning and dotfiles doctor names the problem	an id already taken (dotfiles catalog or an earlier pack) is skipped and reported
AGENTS.md	appended to the global Claude Code, Codex, and OpenCode instructions on the next chezmoi apply	one block per pack
theme.toml	the theme for Ghostty, Neovim, tmux, and dotfiles output	the last pack with a theme applies when the machine sets none

A work machine also defaults git to the work email, skips personal apps (Obsidian) and secrets tooling, and leaves Codex on the default service tier.

One identity per machine. A work machine only pulls this repo (it is public, so no GitHub account is needed for that); edits happen on a personal machine. A work machine is asked for its work email and the work GitHub account it pushes as, signs with work_signing_key, and carries no personal email, key, or account. With no work key, work commits go unsigned rather than borrowing a personal one. chezmoi init finds each GPG key by its email, and the key stays in your local chezmoi.toml, never in the shared work pack.

Setting up a machine's GitHub identity

One command, run on the machine itself, safe to re-run:

dotfiles identity            # add --dry-run to see what it would do first
dotfiles identity --account urmzd-fwai   # change which GitHub account this machine pushes as

It reads the account and email from your chezmoi config (the work account and work email on a work laptop), then:

Step	What happens	Skipped when
gh	signs in as that account in the browser (or switches to it), adds the write:gpg_key, admin:public_key, user:email scopes	already signed in with those scopes
SSH	creates ~/.ssh/github (what ~/.ssh/config uses for github.com) and uploads it	the key exists and GitHub has it
GPG	creates an ed25519 signing key for the email and uploads it	a usable key exists and GitHub has it
Email	warns if the email is not verified on the account (commits would show as unverified)	verified
Save	writes the key to work_signing_key / gpg_signing_key and re-applies ~/.gitconfig	already saved
Check	makes a signed throwaway commit and requires "Good signature"

Passphrases are asked by ssh-keygen and by pinentry-mac's dialog (managed on macOS, so signing also works from editors and agent sessions; tick "Save in Keychain"). chezmoi init also finds an existing key by its email, so creating one by hand works too: gpg --quick-gen-key "Name <email>" ed25519 sign 2y, then gpg --armor --export <email> | gh gpg-key add -.

Chezmoi automation

These scripts run automatically on chezmoi apply. The bootstrap and every dotfiles command apply with --keep-going: a failing step no longer skips the steps after it, failures are listed at the end, and a failed one-time script is retried on the next apply. Run plain chezmoi apply as chezmoi apply --keep-going for the same behavior.

Script	Type	Trigger
install-packages-v2	run_once (before)	First apply (installs Homebrew + bootstrap Linux packages)
brewfile-install	run_onchange (after)	Brewfile, catalog.toml, the packages selection, pkg_exclude, or a pack Brewfile changes
install-cloud-clis	run_onchange (after)	Script changes (re-pin gcloud/aws version)
install-cortex	run_onchange (after)	Script changes (gated on install_cortex flag)
install-gh-extensions	run (after)	Every apply; silent once installed. Waits for gh sign-in (dotfiles identity) instead of failing
install-catalog-linux	run_onchange (after)	Linux only: the packages selection or catalog.toml changes
generate-completions	run_onchange (after)	zshrc, Brewfile, or cloud-clis script changes
setup-node	run (after)	Every apply; silent unless it installs Node LTS (fnm) or runs a one-time npm migration
install-catalog-scripts	run (after)	Every apply; installs selected installer-based packages (Claude Code, agy, OpenCode) that are missing
install-python	run (before)	every apply, silent once linked; installs the default Python with uv
install-skills	run_onchange (after)	Selected skill packs change (bootstraps agentspec, adds each pack's agentspec sources)
sync-agent-resources	run (after)	Every apply (keeps local skills and agents managed by agentspec; removes skills of deselected packs)
install-stack	run_once (after)	First apply only (installs sr and the dotfiles CLI)
configure-terminal	run_once (after)	First apply only
unload-docker-cleanup	run_once (after)	First apply only (macOS: unloads the retired com.docker.cleanup launchd agent)

Every script prints through .chezmoitemplates/ui.sh: one ==> header per script, quiet when nothing changed, and a next step under every warning or failure.

CI and releases

Workflow	Runs on	What it does
ci.yml	pull requests, and before every release	.github/scripts/check.sh renders the full source state for a personal and a work machine on macOS and Linux, then runs the shell gate (lint-shell.sh): every script parses under the shell that runs it, with macOS's bash 3.2 as the floor, no bash-4-only constructs, and every modify_ merge script produces valid, key-preserving output under 3.2; cli/ gets rustfmt, clippy, and tests
release.yml	push to main	After CI passes, sr tags the release, bumps cli/Cargo.toml, and updates CHANGELOG.md from conventional commits; a build matrix then attaches dotfiles-<target> binaries and .sha256 files to the release

Run the same checks locally before pushing: .github/scripts/check.sh, plus cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test in cli/. Release secrets are managed in urmzd/infra.

AI tools

AI coding agents are installed by chezmoi apply (sentinel-gated, no shell-startup cost). Check versions with:

dotfiles status

Per-tool AI config is tracked and deployed by chezmoi:

Tool	Source	Default posture
Claude Code	dot_claude/	Settings, custom statusline, project-scoped skills
Codex	dot_codex/	Workspace-write "Auto" base (auto-run safe ops, guardian auto-reviewer vets escalations) + writer/reviewer/plan/guardian profile overlays and /agent subagents
Antigravity CLI (agy)	dot_gemini/	Legacy Gemini CLI settings kept as agy first-run migration seed; agy config lives in ~/.gemini/antigravity-cli/ (authored in-app via /config and /permissions)
GitHub Copilot	dot_copilot/	settings.json with model, xhigh effort, theme
OpenCode	dot_config/opencode/	Shared instructions; agentspec renders agents into ~/.config/opencode/agents/ with inherited models and provider-specific overrides

Codex runs OpenAI's documented "Auto" preset by default: sandbox_mode = "workspace-write" + approval_policy = "on-request", with the guardian auto-reviewer (approvals_reviewer = "auto_review") classifying every escalation before it reaches you. Drop to codex --profile reviewer or --profile plan for read-only work; the guardian profile supervises orchestrate-agents fleets.

Agent Skills

Skills and subagents in this repo are cross-project: once installed via agentspec, they are available to any tool (claude-code, codex, gemini, copilot) from any project. The source-of-truth lives in dot_agents/skills/ and dot_agents/agents/, following the Agent Skills Specification.

Related standards: AGENTS.md and llms.txt

Managing skills

chezmoi apply installs the core skills and every subagent on every machine. The rest come in skill packs, catalog packages (category skills) picked with dotfiles package or the dev-skills and framework-skills bundles (see Usage). A pack's skills list holds dotfiles skill names (deployed to ~/.agents/skills/ only while the pack is selected) and agentspec sources. The install-skills script uses agentspec to link them into every installed agent.

Pack	Skills
(core, always)	ship, pr, review-diff, merge-ready, diagnose-ci, diagnose-runtime, fix-and-retry, use-worktrees, write-code, test-code, clean-docs, sync-docs, scaffold-docs, audit-security, manage-secrets, sync-release, dotfiles, manage-machine, manage-theme, triage-dotfiles-env, orchestrate-agents
skills-scaffold	scaffold-project, scaffold-go/node/python/rust/terraform, repo-init, check-project, community-health, setup-ci, setup-devenv, choose-stack, build-cli, write-readme, create-llms-txt, configure-ai, update-repo-meta
skills-review	assess-quality, review-design, release-audit, repo-status, asd-ste100
skills-agent-dev	agent-design-doctrine, create-oss-skill, extend-oss-skills-to-claude, run-eval-harness
skills-ecosystem	write-code-portfolio, style-brand, sync-ecosystem, sync-ecosystem-to-chezmoi, setup-devenv-with-chezmoi, align-readmes
skills-vercel	vercel-labs/skills, vercel/ai-elements, vercel/streamdown, vercel/ai (ai-sdk)
skills-gemini	google-gemini/gemini-skills
skills-fastapi	fastapi/fastapi (fastapi)
skills-better-auth	better-auth/skills (better-auth-best-practices)
skills-gh-stack	github/gh-stack (gh-stack)

Deselecting a pack removes its dotfiles skills on the next apply. Skills from an agentspec source stay until removed: agentspec manage remove <name>.

To manage skills and agents manually:

agentspec manage list                          # List managed resources with tool linkage
agentspec manage add <source>                  # Add from local path, GitHub (owner/repo), or name
agentspec manage link <name> <tool>            # Link resource to a tool (claude-code, codex, etc.)
agentspec manage remove <name>                 # Remove a managed resource
agentspec manage create [name]                 # Scaffold a new resource
agentspec manage validate [path]               # Validate SKILL.md or agent definition
agentspec status                               # Show managed vs unmanaged inventory
agentspec sync --fast                          # Discover, adopt, link, and verify all resources

All skills

Quality & design (framework -> principles -> operational)

Skill	Purpose
assess-quality	Foundational quality framework. The "why" layer above review-design and write-code
review-design	Pragmatic Programmer principles (DRY, orthogonality, design by contract)
review-diff	Review staged, unstaged, and untracked changes using the assess-quality and review-design rubric
write-code	Operational picks: error handling, testing strategy, commit conventions, interface design
write-code-portfolio	Personal portfolio specifics (Nix Flakes, chezmoi machine polymorphism, Powerlevel10k, Neovim)
test-code	Testing philosophy and per-language conventions
build-cli	Design and audit CLI tools end-to-end (output modes, TTY, JSON piping, install.sh, portfolio self-update / --format requirements)
check-project	Validate project structure against scaffold conventions
choose-stack	Canonical tech stack reference by purpose

Scaffolding & setup

scaffold-project is the canonical source for standard files; each scaffold-<lang> adds only language-specific deltas.

Skill	Purpose
scaffold-project	Project structure and standard files (canonical)
scaffold-go	Go-specific deltas (toolchain, CI matrix, release publisher)
scaffold-node	Node/TypeScript deltas
scaffold-python	Python deltas
scaffold-rust	Rust deltas
scaffold-terraform	Terraform infra deltas
setup-ci	CI/CD pipeline conventions
setup-devenv	Per-language version manager + direnv pattern (portable)
setup-devenv-with-chezmoi	Chezmoi-specific helpers for pinned installers and tracked .envrc
dotfiles	Chezmoi naming, templating, and agentspec resource management conventions
sync-release	End-to-end release pipeline (sr.yaml, CI, multi-platform builds)
repo-init	Full repo bootstrap (create, license, scaffold, push)
community-health	GitHub Community Standards (CODE_OF_CONDUCT, SECURITY, ISSUE_TEMPLATE) with $COMMUNITY_HEALTH_CONTACT

Workflow automation

Skill	Purpose
ship	Generate a conventional commit, then optionally push and watch CI until pass/fail
pr	Create PRs with auto-generated summary from commits
merge-ready	Drive an existing PR or MR to a mergeable state without merging it
diagnose-ci	Find failing remote CI pipelines, pull logs, identify root cause (local sibling: diagnose-runtime)
diagnose-runtime	Triage local runtime errors, hangs, slowness, and hardware/serial issues (the local counterpart to diagnose-ci)
manage-theme	Switch, create, or debug the machine theme (Ghostty, Neovim, tmux, dotfiles output) via dotfiles theme and theme files
manage-machine	Operate a dotfiles machine through the dotfiles CLI: install or remove catalog tools, dotfiles doctor fixes, updates, and company tools in a pack catalog
triage-dotfiles-env	Playbook of known dotfiles-stack failure modes (pipx shims, gpg signing, nix shellHook, P10k, nvim Lua APIs) with mandatory verification
fix-and-retry	Diagnose CI failure, apply fix, commit, push, re-run
repo-status	Scan a folder of git repos and report recent activity, branch divergence, and uncommitted state (renamed from status)
release-audit	Audit releases, tags, and assets for health
sync-ecosystem	Audit one repository against ecosystem conventions and emit a drift report
sync-ecosystem-to-chezmoi	Apply a sync-ecosystem drift report back into the chezmoi source tree
update-repo-meta	Update GitHub repo topics, description, homepage
manage-secrets	1Password-based secret workflow (vault layout, 1p:// references, op run)
orchestrate-agents	Survey-first orchestration of agent CLIs (Claude, Codex, Antigravity) over tmux: adopt and extend existing sessions, spawn only what is missing
use-worktrees	Create, enter, and clean up git worktrees under the standard .worktrees/<name> layout

AI & documentation

create-oss-skill owns the base spec; extend-oss-skills-to-claude is a sequel covering only the Claude-specific deltas.

Skill	Purpose
agent-design-doctrine	House doctrine for LLM agent systems: safety in the harness, tools return results, minimal loop code, deterministic evals, POC scope discipline
clean-docs	Slash-invocable documentation cleanup: no em dashes, current facts, readable formatting, user-focused guidance
configure-ai	AI tooling configuration, AGENTS.md, skills standard
create-llms-txt	Generate llms.txt files
create-oss-skill	Create portable agent skills (canonical spec)
extend-oss-skills-to-claude	Claude-specific skill deltas (invocation control, subagent execution, model overrides)
audit-security	Security auditing and threat detection
run-eval-harness	Run a project's eval suite end to end: launch, monitor, parse the report, diff against the previous run (forks to a sonnet subagent)
style-brand	Frame and document a project's visual identity. Ships Cyberdream + MonaspiceNe + teasr as a template, not a mandate
sync-docs	Audit and synchronize project documentation (canonical doc-drift skill)
scaffold-docs	Root-file allowlist, docs/ layout (architecture, adrs, rfcs, guides, reference, runbooks, plans) and templates
write-readme	README structure and section order

Subagents

Delegation targets in dot_agents/agents/ that adopt a specific reasoning mode. Installable into any tool via agentspec manage link <name> <tool>.

Agent	Purpose
architect	Interface-first systems design with verbose, principle-driven reasoning
curator	Prescriptive perfectionist for consistency, polish, and visual hierarchy
debugger	Terse, empirical root-cause analysis
guardian	Supervises orchestrated agent fleets driven by the orchestrate-agents skill (also installed as a Codex profile)
ideator	Expansive, generative creative exploration
strategist	Imperative orchestration across multiple systems and repos
technical-documentation-architect	Structured technical documentation and architecture docs
writer	Concise, outcome-focused technical documentation

License

Apache-2.0