Personal macOS development environment. Everything is symlinked into place; editing a file here edits it live.
Preview · Installation · What's inside · Skills · License
One repo that owns the whole machine: shell, terminal, editor, multiplexer, and the AI-agent layer on top of them. install.sh bootstraps a new Mac — Homebrew, packages, fonts, symlinks, nvm — and restoring any config later is just re-running it. The dark yugen theme is applied per-tool and kept in sync manually.
The part that evolved the most is agents/: a set of skills shared across Claude Code, Cursor, and opencode that turns fuzzy ideas into shipped PRs through a documented pipeline — brainstorm, decide, plan, implement.
Editor — Neovim with lazy.nvim
Dashboard
File finder
Diagnostics
git clone https://github.com/vmarcosp/dotfiles ~/projects/dotfiles
cd ~/projects/dotfiles && ./install.shThe script is idempotent. It installs Homebrew (formulae and casks), Nerd Fonts, oh-my-zsh, and nvm, then symlinks every config to its system location. Run it again anytime to restore links or pick up new packages.
| Directory | What it is | Linked to |
|---|---|---|
env/ |
.zshrc (oh-my-zsh, nvm, aliases) and .gitconfig |
~/.zshrc, ~/.gitconfig |
nvim/ |
Neovim config, lazy.nvim | ~/.config/nvim |
kitty/ |
Kitty terminal + yugen theme |
~/.config/kitty/ |
tmux/ |
Minimal tmux config | ~/.tmux.conf |
better-tmux/ |
TypeScript/React tmux status bar | ~/.config/better-tmux |
bin/ |
Utility scripts (notification, worktree) |
~/bin/ |
agents/ |
AI skills and rules, shared across tools | ~/.agents, ~/.claude/*, ~/.cursor/skills |
claude/ |
Global Claude Code settings | ~/.claude/settings.json |
opencode/ |
Opencode config, plugins, themes | ~/.opencode/plugins |
cursor/ |
Cursor hooks and MCP servers | — |
wallpapers/ |
Desktop wallpapers | — |
install.sh is the source of truth for the full symlink map.
Skills live in agents/skills/ and are symlinked into every agent I use (Claude Code, Cursor, opencode), so one edit updates them everywhere. They split on one axis — who can invoke them. User-invoked skills only fire when I type them; they orchestrate a process. Model-invoked skills the agent reaches for on its own when the task fits.
The core skills form a pipeline from fuzzy idea to shipped PR. Each one produces a document the next one consumes, so context survives across sessions and agents:
fuzzy idea
│
┌─────▼──────┐
│ /brainstorm │ explore, stress, converge
└─────┬──────┘
┌─────────────┼─────────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ /prd │───▶│ /tdd │ │ /adr │
│ the │ │ the │◀───│ binding│
│ WHAT │ │ HOW │ │ record │
└────┬───┘ └────┬───┘ └────┬───┘
└──────┬──────┘─────────────┘
▼
fits in a single change?
│ no │ yes
┌─────▼─────┐ │
│ /phasing │ │
│ roadmap, │ │
│ N phases │ │
└─────┬─────┘ │
│ per phase │
┌─────▼─────┐ │
│ /spec │◀────────────┘
└─────┬─────┘
▼
┌───────────┐
│/implement │ 1 step = 1 verify = 1 commit → PR
└─────┬─────┘
▼
carry-over ──▶ /phasing (sync) absorbs and replans
- brainstorm — A long-form session for a fuzzy idea, not a document generator. Grounds every claim in sources read during the session, steelmans before criticizing, measures instead of estimating, and converges into trade-offs with named prices. Exit hands off to
/prd,/tdd, or/adr. - prd — Writes the product requirements: who it's for, what they can do, what "done" looks like per scenario. Behavior only — mechanism is banned from the document. Feeds on a brainstorm artifact, a TDD, or a plain description.
- tdd — Writes the technical design: how a system fits together, As-Is or To-Be, with mermaid diagrams. States the design and links the decisions that justify it instead of re-arguing them. (The name collides with test-driven development on purpose — it never fires on its own.)
- adr — Records one decision already made — context, decision, consequences. ADRs are binding downstream:
/specand/implementtreat them as contracts, never suggestions. - phasing — Cuts settled scope into phases, each sized to be exactly one
/spec. Builds a dependency graph, computes the critical path, and renders parallel work streams. Each phase's/implementleaves a carry-over fragment; a sync run absorbs them and replans. - spec — Turns one change into an implementation plan: recon grounded in files actually read, an approach that complies with every ADR, and ordered steps where each ends on a runnable Verify. Decisions that outlive the change get promoted to ADRs instead of dying in the plan.
- implement — Executes the plan: one step at a time, verify, commit, next. Nothing counts as done because it looks done — only because its Verify ran and passed. Delivers the PR, and when the plan is a roadmap phase, writes the carry-over and flips the phase status.
Standalone skills, no pipeline attached.
User-invoked
- worktree — Creates or removes a git worktree from a branch name, copying
.envfiles and installing dependencies automatically. - review — Reviews a delivered change against its contracts — the
/specplan, the roadmap phase's boundary, binding ADRs, and test authenticity — and returns a verdict with blocking and advisory findings.
Model-invoked
- notification — Fires a native macOS notification when an autonomous flow needs me — a pending question, a human gate, a failure. Clicking it focuses the terminal.
- context7-mcp — Routes library and framework questions through Context7 for current docs instead of stale training data.
3rdparty / installed
Skills I installed from elsewhere; not mine.
- writing-great-skills — Matt Pocock's reference for writing and editing skills well.
- todoist-cli — Doist's skill for managing Todoist through the
tdCLI. - richview — VTEX's skill for generating rich, self-contained HTML artifacts from prompts and referenced files.
agents/rules/ holds always-on guidance every agent loads — when to reach for Context7, when to fire a notification. Repo-scoped rules and skills for this repository live in .agents/.
MIT