dotfiles

Personal configuration files and AI agent skills, managed via symlinks into $HOME.

Contents

Shell and editor

Path	Destination	Description
.bashrc	~/.bashrc	Shell config
.cows/custom-cows/	~/.cows/custom-cows/	Custom cowsay art added to the random startup pool
.tmux.conf	~/.tmux.conf	tmux config
.vimrc	~/.vimrc	Vim config

Copilot

Path	Destination	Description
.copilot/agents/	~/.copilot/agents/	Agent mode definitions: Architect, Builder, Reviewer, Tester
.copilot/hooks/hooks.json	~/.copilot/hooks/hooks.json	VS Code Copilot hooks config: fires superpowers SessionStart hook
.copilot/hooks/superpowers-session-start.sh	~/.copilot/hooks/superpowers-session-start.sh	Wrapper that invokes obra/superpowers session-start
.copilot/instructions/agents.instructions.md	~/.copilot/instructions/	Coding behavior guidelines (simplicity, surgical changes, TDD)
.copilot/instructions/team-workflow-multi-agent.instructions.md	~/.copilot/instructions/	Multi-agent workflow rules

Claude

Path	Destination	Description
.claude/CLAUDE.md	~/.claude/CLAUDE.md	Behavioral guidelines to reduce common LLM coding mistakes

AI agent skills (tool-agnostic)

Path	Destination	Description
.agents/handoff-templates/	~/.agents/handoff-templates/	Handoff artifacts: briefs, build logs, review requests, checkpoints
.obra.superpowers/skills/	~/.agents/skills/, ~/.claude/skills/	Superpowers skills (looped from submodule into both agent runtimes)
.agents/skills/rmslop	~/.agents/skills/rmslop, ~/.claude/skills/rmslop	Strip AI-generated slop and humanize writing
.agents/skills/grill-me	~/.agents/skills/grill-me, ~/.claude/skills/grill-me	Stress-test a plan or design through one-question-at-a-time grilling
.agents/skills/research	~/.agents/skills/research, ~/.claude/skills/research	Research and information gathering with anti-hallucination rules
.agents/skills/writing-reviewer-packets	~/.agents/skills/writing-reviewer-packets, ~/.claude/skills/writing-reviewer-packets	Create concise reviewer packets for large PRs with mandatory rendered Mermaid QA

Submodules

Path	Description
.obra.superpowers/	obra/superpowers — skills installed into ~/.agents/skills, hooks used by Copilot SessionStart
.obra.superpowers	~/.obra.superpowers

Setup

Installation

git clone <this-repo>
cd dotfiles
./setup.sh

The script will:

1. Pull the latest .obra.superpowers submodule
2. Symlink each config file/directory into $HOME
3. Prompt to overwrite anything that already exists (skips silently if already correctly linked)

Options

./setup.sh          # symlink mode (default)
./setup.sh -y       # assume yes to all prompts
./setup.sh --agents-only  # install only ~/.agents and ~/.copilot content
./setup.sh -y --agents-only  # non-interactive agent-only install
./setup.sh --copy   # copy instead of symlink (resolves symlinked dirs)
./setup.sh --help   # show this help message

Agent workflow

This repo uses a role-based workflow so complex work stays predictable, reviewable, and reversible. The main idea is simple: one role plans, one role builds, one role validates behavior, one role reviews quality, and only then does Architect run the commit gate.

This also ties into Superpowers: Superpowers provides reusable skills that extend what agents can do during planning, debugging, verification, and handoff execution without bypassing the same gated workflow.

This dotfiles setup intentionally does not install Superpowers SessionStart hooks. That means the skills are available on disk, but the upstream automatic bootstrap behavior is not enabled here.

Why this workflow exists

• Prevent scope creep during implementation.
• Separate building from validation so the same person is not evaluating their own work.
• Leave a paper trail in scratch/ so anyone can reconstruct what happened.
• Keep commit decisions explicit and gated by evidence.

Role responsibilities

1. Architect: Defines scope, writes the current step brief, routes work, and owns the commit gate.
2. Builder: Implements exactly the briefed step and records what changed.
3. Tester: Verifies behavior and test coverage, then reports clear/no-clear.
4. Reviewer: Performs final review after testing clears and flags regressions, risks, and missing cases.

Execution order (strict)

1. Architect writes scratch/ARCHITECT-BRIEF.md.
2. Builder executes the brief and updates scratch/REVIEW-REQUEST.md.
3. Tester validates and writes scratch/TEST-REPORT.md with explicit clearance.
4. Reviewer evaluates and writes scratch/REVIEW-FEEDBACK.md.
5. Architect summarizes outcomes, requests approval, and commits only after approval.

Core artifacts and what they mean

• scratch/ARCHITECT-BRIEF.md: Exact scope, constraints, and build order for one step.
• scratch/BUILD-LOG.md: Timeline of work, decisions, and gate status.
• scratch/TEST-REPORT.md: Validation evidence and the pass/fail gate decision.
• scratch/REVIEW-FEEDBACK.md: Review findings and required fixes.
• scratch/SESSION-CHECKPOINT.md: Resume snapshot for the next session.

Skills model in this repo

• Skills are installed under ~/.agents/skills and ~/.claude/skills.
• Superpowers skills are mirrored from .obra.superpowers/skills.
• First-party skills live in .agents/skills.
• Superpowers skills are used to strengthen planning and execution quality (for example, brainstorming, writing-plans, systematic-debugging, and verification-before-completion).
• Copilot keeps agents and instructions under ~/.copilot/.
• Upstream Superpowers auto-trigger behavior requires loading using-superpowers at session start; this repo currently omits that hook-based bootstrap by choice.

Agent sandbox

The primary isolated environment is the Saildrone agent sandbox — a Lima VM managed by the sdsbx CLI. Repos live on the host in ~/ai-workspace and are mounted at ~/workspace inside the VM.

To install dotfiles inside the sandbox:

sdsbx shell
cd ~/workspace
git clone <this-repo> dotfiles && cd dotfiles
./setup.sh -y --agents-only

Use --agents-only in sandboxes that allow the workspace mount broadly but deny specific repo-backed shell dotfiles like .bashrc. That keeps Copilot agents, instructions, and skills installed without pointing ~/.bashrc back into the workspace.

If you're working in a different isolated environment (Docker, etc.) where only the project directory is available, copy the config into the project instead:

~/Repos/dotfiles/setup.sh -y --copy && cp -r ~/.agents .agents && cp -r ~/.copilot .copilot

Add .copilot/ and .agents/ to your project's .gitignore or .git/info/exclude unless you want them committed.

Adding a new config file

1. Add the file or directory to this repo
2. Add an install_item call in the # --- Items to install --- section of setup.sh (unless it is under .agents/skills, which is installed by directory loop)
3. Update the contents table in this README