Skip to content
oolothPublic

About

My macOS development environment, including the agent skills and workflows I use for software engineering.

Topics

Resources

Contributing

Stars

24 stars

Watchers

1 watching

Forks

Repository files navigation

My dotfiles 🦸

A highly opinionated development environment for macOS, including shell, editor and tool configuration plus the agent skills and engineering workflows I use every day.

Disclaimer: I update these configurations often as my preferences change. I recommend you treat this repo as inspiration and fork and customize it if you'd like stability.

🤖 Agent-assisted development

I've been experimenting with coding agents as a way to make good engineering practices explicit and repeatable, rather than just using them to generate code. Most of what's here exists because an agent failed in a specific way and the fix had to be something that runs, not something I remember. The same rules keep surfacing in different places: prove-it-works, the global instructions and write-pr-description each refuse to count a passing test suite as evidence that a change works.

The skills and standards live in tools/agents/config/, symlinked into both ~/.claude/ and ~/.agents/ so they belong to no single harness and any agent that reads the shared location gets the same files. Claude Code's own global instructions, settings and subagent definitions live in tools/claude/config/, symlinked into ~/.claude/.

Standards

The standards library is 31 files the rest of this reads. Each standard is phrased as a claim about the code rather than an instruction to the agent: "Errors are handled at the level with enough context to act," not "Handle errors at the right level." That single rule is what lets one file serve three jobs unchanged, since a writing skill reads it as "produce this," a review skill as "check for this," and a scan as "find violations of this." Each is graded Must, Should or Consider, and only Must holds unconditionally.

uphold-standards is how they get loaded, and it's short on purpose. An instruction that governs an act has to load at that act, not at the start of a session, because memory of a rule decays and work built on the paraphrase looks compliant while breaking it. So the trigger is phrased as recurring: a session making four changes loads the standards four times.

Deciding

discuss explores a problem and decides what to do without changing anything. Every claim is either verified, with the check named, or tagged as an assumption. Where my description of the system and the code disagree, that becomes an open question rather than being quietly resolved in either direction.

design works out the type progression, assertion plan and test plan before anything is implemented. A constraint that can be asserted at runtime is asserted and tested, never one instead of the other: a test covers the inputs its author imagined, an assertion covers the inputs production supplies.

next recommends one to three things to work on next in any repo and stops. It ranks by cost of delay, not by how long the work would take, and it learns each repo's trackers and conventions from that repo's own docs rather than from a copy of the skill kept per repo. scan-ideas applies the same rule to the whole backlog and lists what has gone stale.

Reviewing

review-code runs thirteen specialised reviewers in parallel, plus one that checks rule consistency when instruction files change, one that checks, when the base branch has moved since the fork, whether the PR still relies on what changed and where its edits land, one that checks whether merging another open PR that shares its files would undo its edits, one that checks that every assertion removed from the tests is still made or dropped for a stated reason, one that checks every claim the change's prose makes, one that runs a PR's own verification steps and the checks its author would run, base against head, and one that checks that removed prose took nothing a reader needs. Then it assumes they're wrong. Every claim about library behaviour, API guarantees or numbers is checked against the installed code before it reaches me, and a claim that fails is struck rather than softened. Findings are labelled introduced or pre-existing by reading the base ref, not by impression.

review-converge reviews and fixes in rounds until nothing auto-fixable is left, escalating only the decisions that need an author, and never committing. It spawns one fix agent per round rather than one per file, because a fix and the test guarding it are coupled, and splitting by file produces a serial chain of handoffs that looks like parallelism and isn't.

review-pr-comments-converge does the same for reviewer feedback, and doesn't take the reviewer's word for it either: each comment is checked against the current code and marked valid, stale or mistaken before anything acts on it. What gets fixed automatically and what gets escalated turns on one question, does applying this require the author to make a choice.

prove-it-works proves or disproves a claim about the running system, given one sentence naming the claim or a PR, commit or URL. It sets the bar for proof and leaves the method to the model: every observation's raw output is saved and every quote points to its file, so a reader who wasn't there can check each verdict. The test suite doesn't count as any part of the proof, and neither does server state for a claim about what an app shows: that comes from the app itself, as a terminal's text or a screenshot of one window that never includes another app's.

merge-and-verify takes an approved PR through merge to proof of its effect. It starts when I ask to merge a PR, or runs only the verifying when I say I merged one. It reads the deploy chain from the repo's docs, counts the change as serving only when the live artifact's commit contains the merge, and checks every five minutes or so in a fresh turn until the watch reaches one of its named endings. When the proof proves the whole claim, it posts the proof on the ticket, closes the ticket once every PR for it has a proven verdict, and lists the backlog changes what shipped calls for, posting only the ones I approve. When the proof disproves or can't observe part of the claim, it posts nothing and shows me the draft.

monitor-prs checks every fifteen minutes or so, or every five while one of my pull requests has checks running or is undecided, for the pull requests where it's my move, and says why, using the same rules hub's daemon does. Each check reads one snapshot from GitHub and decides from that alone, so two checks of the same state agree. A truncated or failed fetch is reported as such rather than as nothing waiting. It never writes to GitHub. In Rex, each of my pull requests with new feedback gets a worktree and a tab running review-pr-comments-converge, so its draft replies and fixes are waiting when I look.

wrap-up-codebase finds everything in the repo that a change made untrue or that would mislead the next agent, and sorts each finding into a fix, a question for me or a dismissal. A cold reader given only the repo path orients itself from the entry points and reports whatever confused it or looked stale. It runs once before a draft PR opens, so its fixes merge with the code, and, on a default branch or on any branch of a repo like this one that commits straight to main, once per session before asking for the last commit signal. wrap-up-backlog does the same for the tracker's open tickets, and merge-and-verify runs it once its proven report is posted. Neither changes anything itself: whoever runs it acts on the list.

wrap-up ends a session with both passes, asking the cold reader what it would do next and passing it only if it picks the right thing for the right reason, plus a ledger in which every action the session raised gets exactly one status (done, deferred, dropped or open) with evidence for it, so a request made in passing can't quietly disappear. It fixes only what I approve.

Writing

write-pr-description writes the verification checklist a reviewer actually needs, which means never citing the test suite or CI, and cutting any step that can't run on a laptop before merging. The bar is what a skeptic would demand you prove without running tests or deploying.

create-pr is the one way a PR gets opened. It commits and pushes the branch, opens a draft PR with the description write-pr-description writes, and links the new PR on its Jira, Linear or Monday ticket.

write-ticket-description covers issues and epics, and records how tickets relate (parent, prerequisite) with the tracker's own links rather than in the body, so a body never goes stale when tickets are renumbered or closed.

write-progress-update drafts a short Slack update on what a work project finished and what comes next, gathered from Jira, GitHub and Slack since the last update. It shows the candidate items with their sources first, flags anything from a DM or private channel, and saves the result as a Slack draft that it never sends.

They're opinionated and evolving because they're mostly an attempt to encode how I already like to work.

What's Included

docs/          # decisions, invariants, open questions, repo-specific standards
features/      # workflows that span tools: setup, install, update, check, test, run
tools/         # one self-contained folder per tool, each owning its own
               # install, config, symlinks and update logic
├── agents/    # config shared by every coding agent: the standards library and skills
├── claude/    # Claude Code harness: CLAUDE.md, settings, subagents, routines
└── ...        # bash, git, neovim, tmux, zsh and the rest

Prerequisites

  1. Connect to the internet
  2. Sign into iCloud in System Preferences (required for App Store installations via mas)
  3. Install Xcode Command Line Tools:
    xcode-select --install
  4. Update macOS:
    sudo softwareupdate --install --all --restart

Installation

curl -s https://raw.githubusercontent.com/ooloth/dotfiles/main/features/setup/setup.zsh | zsh

This will:

  1. Clone this repository to ~/Repos/ooloth/dotfiles, or pull it if it is already there
  2. Run the zsh scripts in features/install/zsh/, which create SSH keys, install Homebrew, switch to Homebrew's zsh, and install rust, uv, Node, global npm packages and the tmux and neovim dependencies
  3. Link the configs with features/install/zsh/deprecated/symlinks.zsh
  4. Configure macOS system preferences

It does not install the packages the tools' Brewfiles list. Run u afterwards: it installs them and links the configs with each tool's link.bash.

Keep the repo at ~/Repos/ooloth/dotfiles, including in a fork. Every link in $HOME leads there, and the link step refuses to run from a checkout anywhere else.

Values this public repo must not name, such as internal hostnames and cloud project IDs, live in private.env at the repo root, which git ignores. Copy private.env.example there and fill in the keys this machine reads. Each tool names its key when it runs without one.

Checking

dcheck        # verify symlinks, tools, the agent shell and feature aliases

dcheck is a read-only health check. It reports OK, MISSING, or WRONG TARGET for every managed symlink and confirms that critical tools are installed. It also starts an interactive zsh with and without CLAUDECODE set, and confirms that the agent shell has no aliases and no function named like a command, while your own shell keeps its aliases. Last, it confirms each feature's aliases run that feature's own scripts. Exits nonzero if anything is wrong. u runs it after a full update.

Updating

u             # update everything, then run dcheck
u "homebrew"  # update one tool
symlinks      # update symlinks

The u function runs all updates. Before updating anything, it checks each tool's prerequisites, such as the network or a running Docker daemon, and stops within a few seconds if one is missing, saying which tool needs it and how to fix it.

Contributing

I'm not accepting pull requests, but please feel free to...

  • Open issues to discuss bugs, questions or suggestions
  • Fork and customize this project however you like
  • Demonstrate improvement opportunities using your fork

Inspiration

About

My macOS development environment, including the agent skills and workflows I use for software engineering.

Topics

Resources

Contributing

Stars

24 stars

Watchers

1 watching

Forks

Contributors

Languages