Agent Config

Unified configuration for AI coding agents. One central location for slash commands and instructions that all agents share via symlinks.

Supported Agents

Agent	Commands	Instructions
Pi (pi-coding-agent)	`~/.pi/agent/prompts/`	`~/.pi/agent/AGENTS.md`
Claude Code	`~/.claude/commands/`	`~/.claude/CLAUDE.md`
Codex (OpenAI)	`~/.codex/prompts/`	`~/.codex/AGENTS.md`
Gemini (Google)	TOML format (manual)	`~/.gemini/GEMINI.md`
Droid (Factory)	`~/.factory/commands/`	`~/.factory/droids/`
OpenCode	`~/.config/opencode/commands/`	Project-level only

Installation

Full machine setup (new machine)

git clone https://github.com/carmandale/agent-config.git ~/.agent-config
cd ~/.agent-config
./scripts/setup.sh

setup.sh orchestrates everything: Homebrew packages, shell config baselines, secrets directory, symlinks, Claude hooks build, and agent config bootstrap. Safe to run multiple times.

Quick update (existing machine)

cd ~/.agent-config
git pull
./install.sh                    # Symlinks only
./scripts/bootstrap.sh apply    # Agent configs only
./scripts/bootstrap.sh check    # Verify everything

What setup.sh does

Homebrew — installs packages from Brewfile (required + recommended)
Shell config — applies ~/.zshenv (PATH, secrets) and ~/.zshrc (interactive baseline), creates ~/.secrets/ for API keys
Symlinks — runs install.sh (commands, instructions, skills to all agents)
Claude hooks — deploys hook source from configs/claude/hooks/, installs deps, builds TypeScript → .mjs (settings.json depends on ~28 hook files)
Agent configs — runs bootstrap.sh apply (codex, claude, pi baselines)
Verification — runs bootstrap.sh check to confirm everything resolves

Structure

~/.agent-config/
├── commands/                 # Shared slash commands (46+)
├── configs/
│   ├── claude/               # Claude Code settings.json + hooks source
│   ├── codex/                # Codex config.toml, config.json, rules, policy
│   ├── pi/                   # Pi agents, mcporter, extensions
│   └── shell/                # zshenv, zshrc, secrets-template.env
├── docs/                     # Additional documentation (gj-tool, cupertino, etc.)
├── instructions/
│   └── AGENTS.md             # Unified global instructions
├── scripts/
│   ├── setup.sh              # Full machine setup orchestrator
│   ├── bootstrap.sh          # Agent config check/apply/status
│   ├── vendor-sync.sh        # Sync vendored skill repos
│   └── verify-hooks.sh       # Verify hook file integrity
├── skills/                   # Unified skills (300+)
├── specs/                    # Planning artifacts (shaping, plans)
├── tests/                    # Test scripts
├── thoughts/                 # Shared thoughts and handoffs
├── tools-bin/                # CLI utilities (agent-config-parity)
├── Brewfile                  # Homebrew packages (required + recommended)
├── install.sh                # Creates symlinks
├── install-all.sh            # Full install: symlinks + compound-engineering
└── README.md

How It Works

The install.sh script creates symlinks from each agent's config location to this central repository:

~/.pi/agent/prompts      → ~/.agent-config/commands
~/.claude/commands       → ~/.agent-config/commands
~/.codex/prompts         → ~/.agent-config/commands
~/.config/opencode/commands → ~/.agent-config/commands

~/.pi/agent/AGENTS.md    → ~/.agent-config/instructions/AGENTS.md
~/.claude/CLAUDE.md      → ~/.agent-config/instructions/AGENTS.md
~/.codex/AGENTS.md       → ~/.agent-config/instructions/AGENTS.md
~/.gemini/GEMINI.md      → ~/.agent-config/instructions/AGENTS.md

~/.claude/skills         → ~/.agent-config/skills
~/.agents/skills         → ~/.agent-config/skills  (Codex + Gemini)
~/.config/agent-skills   → ~/.agent-config/skills
~/.pi/agent/skills       → ~/.agent-config/skills

Dual Instructions Support

All agents support both user-level and project-level instructions:

Level	Pi	Claude Code	Purpose
User (Global)	`~/.pi/agent/AGENTS.md`	`~/.claude/CLAUDE.md`	Your universal standards
Project (Repo)	`./AGENTS.md`	`./CLAUDE.md`	Project-specific rules

Load order: Global → Parent directories → Current directory

This means you can have:

Global AGENTS.md: Core standards, never-do rules, preferred workflows
Repo AGENTS.md: Project architecture, specific conventions, tooling

Session Workflow

The core workflow for tracked, traceable work sessions:

/focus <bead-id>           # Start: load context, mark in-progress
    ↓
  ... do work ...
    ↓
/checkpoint                # Optional: mid-session save
    ↓
  ... more work ...
    ↓
/handoff                   # End: summarize, commit, requires bead

Key Rules

/handoff requires a bead - hard stop if no active bead (traceability)
/handoff writes .handoff/YYYY-MM-DD-HHMM-{bead-id}.md - tracked & committed
/checkpoint writes .checkpoint/YYYY-MM-DD-HHMM.md - tracked & committed
/focus marks bead in-progress and loads relevant context

Key Commands

Session Management

Command	Description
`/focus <bead>`	Start session - load context, mark bead in-progress
`/handoff`	End session - requires bead, writes `.handoff/`, commits
`/checkpoint`	Mid-session save - writes `.checkpoint/`, commits
`/standup`	Quick status update
`/retro`	Session retrospective

Development Workflows

Command	Description
`/commit`	Smart commit with conventional format
`/debug`	Structured debugging workflow
`/sweep`	Code cleanup pass
`/fix-all`	Fix all lint/type errors
`/iterate`	Iterative refinement loop

Planning & Triage

Command	Description
`/triage`	Issue triage and prioritization
`/estimate`	Time estimation for tasks
`/repo-dive`	Deep dive into unfamiliar repo

Team & Parallel Work

Command	Description
`/parallel`	Spawn parallel workstreams
`/swarm`	Coordinate multiple agents
`/swarm-status`	Check swarm progress
`/swarm-collect`	Gather swarm results

Customization

Adding Commands

Create a new .md file in ~/.agent-config/commands/:

---
description: Your command description (shown in autocomplete)
---

Your prompt instructions here...

Use $1, $2, etc. for positional arguments.
Use $@ for all arguments joined.

Modifying Global Instructions

Edit ~/.agent-config/instructions/AGENTS.md - changes apply to all agents immediately.

Project-Specific Instructions

Create AGENTS.md (or CLAUDE.md) in your project root:

# Project Instructions

## Architecture
- This is a visionOS app using SwiftUI and RealityKit
- Follow MVVM pattern

## Conventions
- Use `gj` tool for all builds (never raw xcodebuild)
- Run `gj test P0` before committing

## Never Do
- Don't add UIKit patterns to visionOS code
- Don't modify the Shared Types package without approval

Updating

cd ~/.agent-config
git pull
./install.sh  # Re-run if symlinks are broken

Parity and Version Sync (Laptop <-> Mac Mini)

Use tools-bin/agent-config-parity to make parity explicit and reproducible.

Step 1: Align repo version on both machines

cd ~/.agent-config
git fetch origin
git checkout main
git pull --ff-only
git rev-parse HEAD

The git rev-parse HEAD value must match on laptop and Mac mini.

Step 2: Run installers from the same checkout

cd ~/.agent-config
./install.sh
./install-all.sh

Step 3: Capture snapshots

Laptop:

~/.agent-config/tools-bin/agent-config-parity snapshot --output /tmp/laptop.snapshot

Mac mini:

~/.agent-config/tools-bin/agent-config-parity snapshot --output /tmp/mini.snapshot

Step 4: Compare snapshots

~/.agent-config/tools-bin/agent-config-parity compare /tmp/laptop.snapshot /tmp/mini.snapshot

No diff means parity for tracked repo/symlink/tool keys.

If there is diff output, classify each key before making changes:

managed.* drift is usually actionable and should be fixed.
external.* drift is often machine-local and should be reviewed, not blindly copied.
system.* drift is expected when macOS versions differ between machines.

Step 5: Human-readable audit

~/.agent-config/tools-bin/agent-config-parity report

Focus on:

repo.sha
managed.*.status and managed.*.actual
tool.*.version

Troubleshooting

Commands not showing up

# Verify symlinks exist and point correctly
ls -la ~/.pi/agent/prompts
ls -la ~/.claude/commands
ls -la ~/.codex/prompts

Broken symlinks after moving directories

cd ~/.agent-config
./install.sh

Agent not reading instructions

Pi: Restart the agent session
Claude Code: Instructions load per-session
Codex: Restart codex
Gemini: Restart gemini
Droid: Custom droids load from ~/.factory/droids/

What Is Outside `.agent-config`

Managed by bootstrap (baselines tracked in configs/):

~/.claude/settings.json, ~/.claude/hooks/ (TypeScript source + build), ~/.codex/config.*, ~/.pi/agent/agents/, extensions, mcporter
~/.zshenv, ~/.zshrc (shell baselines)

Machine-specific (intentionally not tracked):

~/.zshrc.local — per-machine aliases, conda, pnpm, app paths
~/.secrets/agent-keys.env — API keys (template tracked, values not)
Agent CLI installations (claude, codex, gemini, pi, openclaw)
Toolchain versions (git, node, bun, bd, rg)
Auth state and credentials (keychain entries, logged-in sessions)

Run ~/.agent-config/tools-bin/agent-config-parity report to see these surfaces explicitly.

License

MIT

Skills (Unified)

Skills are unified across all agents, organized by function:

~/.agent-config/skills/
├── tools/          # Wraps external CLI/API/service (76)
├── review/         # Analyzes/reviews code or content (21)
├── workflows/      # Orchestrates multi-step dev processes (54)
├── meta/           # Agent behavior rules, patterns (42)
├── domain/         # Technology-specific knowledge (62)
│   ├── swift/      # Apple/Swift platform
│   ├── compound/   # Vendored compound plugin set
│   ├── ralph/      # Ralph orchestrator
│   ├── shaping/    # Shaping methodology (submodules)
│   └── ...         # agentica, design, gitnexus, math, notion, other
└── <name> -> <category>/<name>  # Discovery symlinks

Symlinks

All agents point to the same unified location:

~/.claude/skills        → ~/.agent-config/skills
~/.agents/skills        → ~/.agent-config/skills  (Codex + Gemini)
~/.config/agent-skills  → ~/.agent-config/skills
~/.pi/agent/skills      → ~/.agent-config/skills

Adding Skills

Add new skills to the appropriate category using the decision rule:

Wraps external CLI/API/service? -> tools/
Analyzes/reviews code or content? -> review/
Orchestrates multi-step dev process? -> workflows/
Specific to a named technology domain? -> domain/<sub>/
Agent behavior rule or pattern? -> meta/

mkdir ~/.agent-config/skills/tools/my-tool
# Create SKILL.md with description and instructions
ln -s tools/my-tool skills/my-tool  # Discovery symlink

Skill Format

Each skill needs a SKILL.md file:

---
name: my-skill
description: Brief description of what the skill does
---

# Skill Name

Detailed instructions for the skill...

Full Install (All Agents)

For a complete setup that includes both symlinks AND compound-engineering plugin:

cd ~/.agent-config
./install-all.sh

This runs:

install.sh - Creates symlinks for commands, instructions, skills
bunx @every-env/compound-plugin install compound-engineering --to opencode --also droid

What Each System Provides

Component	agent-config (symlinks)	compound-plugin (converter)
Commands	✓ Shared via symlink	—
Instructions	✓ AGENTS.md symlinked	—
Skills	✓ Shared via symlink	—
Agent definitions	—	✓ Per-format agents
MCP config	—	✓ mcporter.json, etc.

Name	skill-upgrader
Description	Upgrade any skill to v5 Hybrid format using decision theory + modal logic

skill-upgrader

SKILL.md