Your Agent Config Is Infrastructure

• File lives in a git-tracked notes vault, not in any tool's own config directory.
• Symlink it into place: ln -s ~/notes/agents/CLAUDE.md ~/.claude/CLAUDE.md — every tool points at the same target.
• Claude Code reads CLAUDE.md; Codex CLI and a growing list of others read the emerging AGENTS.md convention — symlink both filenames to the same source if a tool needs the other name.
• Two tiers: a global file for what holds in every repo, plus each repo's own AGENTS.md for what doesn't.

A generic global file looks like this, but it should be personalized to match your conventions and proclivities:

Copied
Universal guidance for any agent (Claude, Codex, others) in any repo. This file
lives in my knowledge base and is symlinked into every tool's config directory,
so there is only one canonical copy, editable from wherever I happen to be.
Repo-specific rules live in that repo's own AGENTS.md.

## General guidelines

- Prefer quality, simplicity, and long-term maintainability over development
  speed. Simplicity is the final achievement, not the starting compromise.
- Smallest possible diff. Read the referenced files before claiming anything.
- Fix bugs by reproducing them first, then fix the actual cause, not the
  symptom.
- Never manually edit generated files (changelogs, lockfiles, exports).

## My knowledge base

Persistent knowledge — decisions, projects, preferences, research — lives in
my notes, not in this file. When a task needs context I don't already have,
that's where to look. Rule of thumb: tooling that's topic-agnostic belongs in
a skill; otherwise it belongs in the notes.

## Work efficiently

Context gets re-billed on every turn, so keep it lean:
- Read a file once per session.
- Delegate exploration and grep sweeps to subagents; keep the main thread
  for judgment calls.
- Hand off long-running work to a fresh session rather than letting one
  thread run indefinitely.

## Subagents and models

You are an orchestrator. Delegate liberally. Send to a subagent: exploration
touching more than a couple of files, log or grep sweeps, parallel independent
workstreams, second opinions on hard calls, diff-heavy implementation.
- Default model for most reasoning and code.
- Escalate to a stronger model for ambiguous design or security calls, and
  for a real second opinion — have it argue against the first conclusion,
  not just confirm it.
- A second CLI agent is wired in as an independent read on anything a
  single model might rubber-stamp.

## Task tracking

Track non-trivial work in a task tracker, not ad hoc TODO comments.

## Git

- Pull before starting, commit after each logical unit.
- Private repos I own: push freely and often.
- Anyone else's repo, or unclear ownership: commit locally, don't push
  without asking.

Skills are topic-agnostic bundles of context; for most skills, your agents should use them without you in the loop.

• Default new skills to explicit invocation (a slash command). Promote to autonomous triggering only after watching it fire correctly by hand a few times. Most skills should be autonomous.
• The trigger description does the routing — write it as concrete task shapes and phrasing ("user says X", "file matches Y"), not a summary of what the skill does. That's the only thing the routing model sees before deciding to invoke it.
• Build these three first, in this order: reconnaissance (grep the codebase and prior notes before proposing anything, so the agent argues from what's actually there), spec-writing (turn a rough ask into a scoped, written plan before any code changes), and voice (below) — each one replaces a habit you'd otherwise have to re-explain every session.
• Working example of the voice skill: tone rules, banned words, sentence patterns, set to autonomous triggering — it fires on any public-facing draft without being asked, so voice stays consistent across a blog post, a reply, or a bio instead of being re-pasted into each prompt.

A template for authoring one:

Copied---
name: skill-name-in-kebab-case
description: State what this does and when to trigger it. The description is the only thing the routing model sees before deciding to invoke you — front-load concrete trigger conditions (specific phrases, file types, task shapes), not a vague summary.
---

# /skill-name

## Purpose
One paragraph: what this skill produces and why it exists as a skill rather
than being handled inline.

## When to use
- Concrete trigger: the user says X
- Concrete trigger: the task touches a file matching Y
- Concrete trigger: the task shape looks like Z

## When NOT to use
- The adjacent case this skill should NOT claim — say so explicitly, since
  this is what keeps two similar skills from fighting over the same trigger

## Process
1. What to gather or ask before acting
2. The core transformation or generation
3. Verification — how you know the output is right before handing it back

## Output format
What the final artifact looks like (file, structured data, direct response)
and where it goes.

## Example invocations
A short before/after: rough input to what the skill should produce.

Every agent is actually an orchestrator of its subagents.

• Default: exploratory, parallelizable, or independent-read work goes to a subagent, not the main thread.
• Concretely — grep/log sweeps, multi-file research, independent workstreams, second opinions on a hard call: all delegated, never run inline.
• Subagent returns a summary; raw output (file contents, search hits, logs) never enters the main thread.
• Any subagent that writes files gets its own git worktree — parallel subagents edit in isolation, so two of them running at once never collide on the same file.
• Subagents can spawn their own subagents, several layers deep — the top-level thread only ever sees the final report, never obligated to see the intermediate work.
• Main thread's actual job: decide what runs in parallel, what blocks on what, what the results mean once they're back.

Coordinating several subagents on a task with real interdependencies — this piece finishes before that one starts, these three run in parallel, this output needs a synthesis pass before anything downstream can use it — is still a manual call. It gets harder as the subagent count grows, and it's tempting to treat that as a sign you need a third-party scheduler.

Don't reach for one yet. Claude Code's own agent dispatch — launching subagents directly, deciding by hand what runs in parallel and where the synthesis points are — already covers most tasks. Access the agents interface via claude agents from the CLI, or the regular sidebar from Claude Desktop. By adopting the root CLAUDE.md above, your agents will already use subagents liberally and to great effect.

A custom orchestration layer solves a problem most setups haven't hit yet; building one before you've felt the ceiling is premature infrastructure, the same mistake as installing five plugins on day one.

Beads covers the one piece of this that's actually tedious; it offers a git-backed, agent-queryable dependency task graph. bd ready lists what's unblocked, agents claim and close their own work, and the record survives past the session that created it.

For actual scheduling — automatic parallelization, synthesis passes, retries — Gas City (with a friendly introduction) is what I use, on a separate VM, but the overhead is too substantial to recommend universally. Standing up a scheduler is a heavier lift than the ad hoc coordination it replaces, and it isn't worth that lift until hand-coordinating subagents is the actual bottleneck, not just mildly annoying. These days dynamic workflows are sufficient alternatives for most users.

Models accessible via CLI are accessible to other models, which they should use just as much as subagents.

• Codex CLI runs in the same terminal, alongside Claude Code
• Two uses: ask it to independently re-check a call the first model already made, or hand it a separate piece of the same task to run in parallel
• Rule of thumb: second opinion on anything you'd regret getting wrong (security, architecture, a close judgment call); workhorse when you just need more hands
• Current state, not a fixed ranking: Anthropic and OpenAI lead on this kind of agentic work right now, local models win only on cost or privacy — swap the tool as that changes, the second-opinion habit is what's durable

A snippet to add to your own global file:

Copied## Second opinions

A second CLI agent (Codex) runs alongside the primary one. Two uses:
- Ask it to independently re-check a call already made — a security
  read, an architecture decision, anything worth being wrong about.
- Hand it a separate piece of the same task to run in parallel when
  the bottleneck is just needing more hands.
Default to using it, not just reaching for it after something already
went wrong.

Where do you put everything you and your agent both need to regularly access?

• Plain markdown, git-tracked, opened in Obsidian — no export step, no separate database.
• Not the only surface: Notion runs alongside it for anything that needs to work well from a phone — the vault stays the canonical, git-tracked source; Notion is a mobile-friendly complement, not necessarily a replacement. I use both; start with one.
• Structure: Projects/<Category>/<Project>/ per active thing, each with a Brief.md — what it is, current state, open decisions — written so a cold read needs no context reconstruction
• Cross-cutting material (the config file, shared conventions, skill definitions) lives in one top-level System/ area, not scattered per-project
• Agents read the relevant brief before acting and write updates back after — same discipline as reading a codebase's docs before touching it

A slice of my personal graph. Scale doesn't guarantee complexity—the structure underneath is still just Projects, People, Meetings, System.

• Rafter runs security scanning — dependency, secret, and code security checks — as a gate agents run before calling security-relevant work (auth, credentials, input handling, SQL/shell) done. It's the same instinct as the second model: don't let one pass be the only check. Plus, I created and maintain it.
• Context7 pulls current, version-specific library documentation into context instead of relying on training data that's often stale on fast-moving APIs — same instinct again, aimed at library docs specifically.
• Playwright MCP gives Claude a real browser — navigate, click, read a rendered page, take a screenshot — for anything a one-shot fetch can't reach: JS-heavy pages, actually testing a UI you just built.
• Account-level connectors — Gmail, Google Calendar, Google Drive — extend reach past the vault and the codebase into your actual accounts. The staleness question below doesn't apply here; the real risk is an agent taking a real action on your behalf, not trusting stale data. Grant read access freely, write access slowly — sending an email or deleting a file is a different mistake than citing an old API. Prompt injection is also a risk. Consider yourself warned.

Beyond particular plugins, keep in mind:

• Every other plugin — a memory layer, a project-management bridge, any tool that claims to remember things for the agent — earns its place only if it answers two questions: can it go stale and still get trusted over the actual codebase? And: will this cost more tokens than it saves?
• Real failure mode: an agent works off a memory plugin's record of a branch from months back, unaware someone reverted the real config since — trusting the plugin's account over a git log. The fix isn't a better memory plugin. It's a rule: the codebase is the only thing an agent is allowed to treat as ground truth, and anything else gets verified against it, not substituted for it.
• Installing several plugins at once to fix a setup that feels slow makes it slower and less predictable, not faster — add one, run it for a week, decide if the next one earns its place. Every plugin above got added this way, months apart, not together.

• When a correction reveals a mistake, fixing the instance is half the job. The other half: extract the general, reusable lesson and write it into whichever skill should have caught it — so the same mistake doesn't get made again next session by an agent with no memory of this one.
• The generalization has to be sharper than the instance: "cut this one word from this one sentence" only fixes that sentence. "Ask what a qualifier adds that its absence wouldn't, and cut it if nothing" fixes every sentence shaped like it, from here on.
• The caveat: this compounds mistakes as readily as it compounds fixes. One sharp correction, generalized too far, becomes a standing rule applied somewhere it doesn't belong. A skill nobody prunes accumulates caveats faster than anyone rereads them, until the file itself is the problem it was meant to prevent. Review what gets written back in — not just whether the instance got fixed.

• Swap the notes app: the config file only needs a stable file path, no dependency on the skill format
• Swap the second CLI agent: whichever tool is strongest next year drops in, nothing else changes
• Swap in Gas City, or drop it: skills and the config file don't need to know it's there either way
• Drop either plugin and nothing else breaks — each is an independent check, not load-bearing for any other piece
• The feedback loop needs only a skill file to write into — it runs the same whether the vault behind it is a full second brain or one folder of notes

That's most of what you need. The rest is the specific rules and preferences that only sound right in your own voice — no writeup hands you those.

Don't adopt all of it at once. Start with the config file: one canonical CLAUDE.md, symlinked, versioned. Add a skill when a habit gets tedious enough to formalize, not before. Add a plugin when its absence actually costs you something, not because a list made it sound necessary. None of these pieces needs the others in place first, so there's no wrong order to start in — just a wrong instinct to install everything in one sitting.

Build it to help you, not to look complete. Iterate.