diff --git a/portability.md b/portability.md new file mode 100644 index 0000000..90f0b1c --- /dev/null +++ b/portability.md @@ -0,0 +1,85 @@ +# Portability Protocol + +**Purpose:** keep every layer of my agent setup hot-swappable across model providers. Any compliant tool dropped into one of my repos should be productive immediately; adopting a new tool should cost minutes; returning to a previous tool should cost nothing. + +**Lives at:** `~/Projects/standards/portability.md`. The standards repo is laid out as: + +``` +~/Projects/standards/ + how-i-work.md portability.md retrofit-playbook.md subagents-handbook.md + guides/ ← neutral substance (vendor-agnostic): checklists, role knowledge + adapters/ + claude/ + commands/ ← ~/.claude/commands symlinks here (global commands, e.g. /handoff) + agents/ ← ~/.claude/agents symlinks here (global subagents) +``` + +Companions: `how-i-work.md` (the always-loaded user layer, under 50 lines), `retrofit-playbook.md` (the one-time conversion manual), and `subagents-handbook.md` (designing and running delegated agents). This document is reference material — never symlink it into anything always-loaded. + +## The principle + +**Knowledge lives in vendor-neutral files; vendor-named paths are thin adapters — symlinks or pointers — into them.** + +Corollaries: + +1. **Repos are self-contained.** Everything required to work on a project correctly lives in the repo. Global and user-level files add preferences, never requirements. +2. **Swap at session boundaries.** The close-out ritual (update Current state → commit → push) is the handoff protocol between providers, not just between sessions. +3. **Convert machinery, never knowledge.** At adoption time, an agent regenerates wrappers (subagents, commands, rule loaders). The markdown they point at never moves. In every wrapper, vendor syntax stays confined to the header; the body is plain prose any agent could follow — so even when substance lives inline (a self-contained command like /handoff), conversion is a one-prompt header swap. +4. **Session state is disposable by design.** Conversations and per-tool caches (e.g. Claude's auto memory) are conveniences. Anything important gets promoted into the files below. +5. **No secrets in any of these files.** Secrets live in gitignored .env files; documents reference env-var names only. + +## The layers + +| Layer | Neutral source of truth | Claude adapter | Portability status | +|---|---|---|---| +| Project knowledge | `/AGENTS.md` | symlink `CLAUDE.md` → `AGENTS.md` | Open standard — Cursor, Copilot, Codex, Gemini CLI, opencode read it | +| Project status | `## Current state` section in AGENTS.md | (same symlink) | Fully portable; maintained by the close-out ritual | +| Scoped guides | `/docs/guides/.md` with `paths:` frontmatter, plus one index line each in AGENTS.md | symlinks from `.claude/rules/` (auto lazy-load) | Content fully portable; lazy-loading is per-tool. Other tools find guides via the index lines | +| User preferences | `~/Projects/standards/how-i-work.md` | symlink `~/.claude/CLAUDE.md` → it | No cross-tool standard above repo level; each tool's global file symlinks here at adoption | +| Skills (procedures) | folders of `SKILL.md` + plain bash/python scripts | `.claude/skills/` | Format is open markdown; a cross-tool home (`.agents/skills/`) is emerging. Worst case: a pointer line in AGENTS.md | +| Subagents (delegation) | guides folder at matching scope — `/docs/guides/` for project agents, `standards/guides/` for global — or inline as plain prose if self-contained | thin wrapper in `.claude/agents/` (project) or `standards/adapters/claude/agents/` (global, symlinked as `~/.claude/agents`) | No standard exists. Wrappers regenerated per tool at adoption | +| Commands (saved prompt shortcuts) | same scope rule as subagents; self-contained procedures (like /handoff) may keep substance inline as plain prose | `.claude/commands/` (project) or `standards/adapters/claude/commands/` (global, symlinked as `~/.claude/commands`) | No standard. Same treatment as subagents | + +**Scope rule:** every artifact lives at the scope it describes — project-specific in that repo; universal in the standards repo. There, neutral substance goes in `guides/` and vendor machinery is quarantined under `adapters//` (so a second provider's wrappers never intermix with Claude's or with the shared guides). + +## Swap protocol (between already-adopted tools) + +1. Finish the task and run the close-out ritual; exit the session. +2. Open the other tool in the same repo. +3. It reads AGENTS.md (plus its own global file) and Current state, and continues. + +Nothing else. If step 3 stumbles, the missing fact belongs in AGENTS.md — add it and commit. + +## Adoption checklist (first time using a new provider) + +Run by the new agent itself: *"Read ~/Projects/standards/portability.md and onboard yourself as a new provider."* + +1. Install and authenticate the tool — the only human-heavy step. +2. Symlink (or copy) its global instruction file to `standards/how-i-work.md`. +3. Confirm it reads `/AGENTS.md`. If it expects a different filename, symlink that name to AGENTS.md. +4. If it supports path-scoped or lazy loading, wire its mechanism to `docs/guides/`; otherwise the AGENTS.md index lines suffice. +5. If it supports skills or procedures, point it at the skills folders; otherwise add a pointer line in its global file. +6. Regenerate the thin wrappers it supports (subagents, commands) from the guides they reference, placing global ones in `adapters//` and symlinking the tool's config home to them. +7. **Record what was done in a new provider section at the bottom of this document.** + +## Provider adapters + +### Claude Code (current) + +- `CLAUDE.md` → symlink → `AGENTS.md` at the root of every repo +- `.claude/rules/.md` → symlinks → `docs/guides/.md` (auto lazy-load via `paths:` frontmatter) +- `~/.claude/CLAUDE.md` → symlink → `standards/how-i-work.md` +- `.claude/agents/` — thin subagent wrappers pointing at docs/guides (project-specific agents only) +- `.claude/commands/` — thin command templates, regenerable (project-specific commands only) +- Global commands and agents: `~/.claude/commands` → symlink → `standards/adapters/claude/commands/`; `~/.claude/agents` → symlink → `standards/adapters/claude/agents/` (versioned and backed up with the standards repo) +- `.claude/skills/` — skills home for now; migrate to `.agents/skills/` if that convention solidifies +- Auto memory: local cache only (`~/.claude/projects//memory/`), outside git, not portable. Promote keepers into AGENTS.md or guides. Audit with `/memory`. + +### Next provider — template + +- Global file location: ___ → symlink → `standards/how-i-work.md` +- Reads AGENTS.md natively? ___ (if not: symlink its expected filename → AGENTS.md) +- Scoped/lazy loading mechanism: ___ (wired to docs/guides, or relying on index lines) +- Skills support: ___ +- Delegation/subagent equivalent: ___ (wrappers regenerated on: ___) +- Notes and quirks: ___ diff --git a/retrofit-playbook.md b/retrofit-playbook.md index ae195d5..55759ec 100644 --- a/retrofit-playbook.md +++ b/retrofit-playbook.md @@ -164,7 +164,7 @@ continues the most recent conversation in that folder. Nothing lost. - `/memory` shows every CLAUDE.md and rules file loaded right now, and lets you browse what auto memory has saved. Auto memory lives in `~/.claude`, outside the repo — Gitea never backs it up — so promote anything important into CLAUDE.md. - When **Current state** stops fitting in ~15 lines, it's accumulating history. Prune it; history lives in the git log. - **AGENTS.md is the real file; CLAUDE.md is a symlink to it.** AGENTS.md is the cross-vendor standard (Cursor, Copilot, Codex, Gemini CLI, and the open-source harnesses read it); Claude Code reads only CLAUDE.md, so the symlink serves it the same file under its preferred name. Either name edits the same file — every "update CLAUDE.md" in this runbook lands in AGENTS.md. If you ever switch providers or run self-hosted agents, the repo is already in their native format. -- **The portability principle, generalized:** knowledge lives in vendor-neutral files; vendor-named paths are symlinks into it. Root: AGENTS.md ← CLAUDE.md. Scoped guidance: docs/guides/*.md ← .claude/rules/*.md, indexed by one line each in AGENTS.md. To try a different provider, swap at a session boundary: run the close-out ritual, open the other tool, and it reads AGENTS.md + Current state and continues. The repo is brain-agnostic; sessions are visits. +- **The portability principle, generalized:** knowledge lives in vendor-neutral files; vendor-named paths are symlinks into it. Root: AGENTS.md ← CLAUDE.md. Scoped guidance: docs/guides/*.md ← .claude/rules/*.md, indexed by one line each in AGENTS.md. To try a different provider, swap at a session boundary: run the close-out ritual, open the other tool, and it reads AGENTS.md + Current state and continues. The repo is brain-agnostic; sessions are visits. Full protocol: portability.md in the standards repo. --- diff --git a/subagents-handbook.md b/subagents-handbook.md new file mode 100644 index 0000000..bdb2a3f --- /dev/null +++ b/subagents-handbook.md @@ -0,0 +1,329 @@ +# Subagents Handbook + +**Purpose:** reference for designing, using, and creating Claude Code subagents. +**Lives at:** `~/Projects/standards/subagents-handbook.md`, sibling of `portability.md` +and `retrofit-playbook.md`. The working parts follow the portability protocol: neutral +substance in `guides/.md` (one operating guide per agent, plus +`guides/full-eval.md` for the orchestrator); thin Claude wrappers in +`adapters/claude/agents/` and `adapters/claude/commands/`, reached via the standard +directory symlinks from `~/.claude/agents` and `~/.claude/commands`. + +Verified against the official docs (June 2026): https://code.claude.com/docs/en/sub-agents + +--- + +## 1. What a subagent is + +A subagent is a helper Claude that runs in its **own context window**, does a chunk of +work, and hands back **only its final report**. Your file hierarchy controls what enters +context at session start; subagents control what stays out of context while work happens. + +The trigger is always the same shape: *the task involves lots of reading or noisy output, +but I only need the conclusion.* + +### Mechanics (the facts that matter) + +- **Format.** A Markdown file with YAML frontmatter. Frontmatter = config; body = the + subagent's entire system prompt. Only `name` and `description` are required. Useful + optional fields: `tools` (allowlist), `disallowedTools`, `model` (`haiku`/`sonnet`/ + `opus`/`inherit`), `effort` (`low`/`medium`/`high`/`xhigh`/`max` — reasoning depth, + default high), `maxTurns`, `memory`, `background`. +- **Wrapper/guide split (this setup).** Per the portability protocol, each definition + here is a *thin wrapper*: vendor syntax confined to the frontmatter, and a body that + does exactly three things — direct the agent to read its operating guide at + `~/Projects/standards/guides/.md` before acting, give a fail-safe ("can't read + the guide → stop and say so, don't improvise"), and state a one-line safety floor + (read-only, etc.) that holds even guideless. The guide carries all substance — + mission, procedure, hard rules, report contract — as plain prose any agent could + follow; adopting another provider is a header swap. +- **Locations & precedence.** `.claude/agents/` (project) beats `~/.claude/agents/` + (user, all projects). Both are scanned recursively, so symlinked subfolders work. +- **Loading.** Subagent files (the wrappers) are read **at session start**. Add or edit + a wrapper on disk → restart the session. (Agents made via `/agents` load immediately.) + Guides are different: the agent reads its guide **at run time**, so guide edits take + effect on the very next run, no restart. +- **What the subagent sees.** Its own body, the delegation prompt the main agent writes, + your full CLAUDE.md/AGENTS.md hierarchy, and a git-status snapshot. It does **not** see + your conversation. The delegation prompt is the *only* channel in — paths, symptoms, + and scope must be stated there. +- **What comes back.** The subagent's final message, verbatim. Everything else it read + or did dies with its context window. +- **Built-ins.** `Explore` (Haiku, read-only — fast codebase search), `Plan`, and + `general-purpose` already exist. Don't rebuild them. +- **No nesting.** Subagents cannot spawn subagents. Fan-out happens from the main + thread (see §6, the orchestrator). +- **Foreground vs background.** Foreground blocks and passes permission prompts to you. + Background runs concurrently but **auto-denies** anything that would prompt — so + agents needing Bash approval (exerciser, auditor) should run foreground the first time. +- **Invocation.** Auto-delegation via the `description` field; by name in prose + ("use the reviewer subagent"); or guaranteed via `@agent-`. +- **Cost.** Every subagent is a fresh model run reading files from scratch. Heavy + fan-outs can burn several times the tokens of a single thread. Spend it where the + context savings or fresh eyes are worth it. + +--- + +## 2. The catalog + +Four properties a separate context window gives you. Every useful agent exploits at +least one. + +| Property | What it buys you | Agents | +|---|---|---| +| **Compression** | Huge input → small conclusion | explorer, test-runner, researcher, docs-reader | +| **Independence** | Fresh eyes, unanchored by your session | reviewer, fresh-debugger, spec-checker, security-auditor | +| **Containment** | Messy trial-and-error stays out of your session | exerciser, reproducer, migrator | +| **Parallelism** | N investigations at once | any of the above, fanned out | + +### Roster + +| Agent | Property | One-liner | Status | +|---|---|---|---| +| explorer | compression | Map a codebase/subsystem, report how it works | **built-in** (`Explore`) | +| evaluator | independence | Whole-repo assessment: 6 lenses + intent match + alternatives | ✅ in kit | +| reviewer | independence | Fresh-eyes review of a diff before commit | ✅ in kit | +| security-auditor | independence | Hostile persona: vulns, secrets, dependency CVEs | ✅ in kit | +| spec-checker | independence | Compliance vs Start9 community registry requirements | ✅ in kit (`start9-spec-checker`) | +| exerciser | containment | Black-box QA: run it, feed it normal + hostile inputs | ✅ in kit | +| researcher | compression | Multi-source web research → cited brief | ✅ in kit | +| test-runner | compression | Run the suite, return only failures + causes | build when a repo has a real suite | +| docs-reader | compression | Read a library's docs, return just the calls you need | build on 3rd manual-trawling task | +| fresh-debugger | independence | Gets symptoms only (never your theories), hunts the bug | build next time you're stuck >1hr | +| reproducer | containment | Bug report in → minimal repro steps out | build when triaging user reports | +| migrator | containment | Mechanical change across many files → "done, N anomalies" | build at first big rename/upgrade | + +*CVE, since it'll keep coming up:* **Common Vulnerabilities and Exposures** — the public +catalog of known security flaws, each with an ID like `CVE-2026-12345`. "Dependency +CVEs" = known holes in the third-party libraries your software pulls in. Scanners +(`npm audit`, `cargo audit`, `pip-audit`, `osv-scanner`) check your lockfiles against +the catalog. The security-auditor runs them. + +--- + +## 3. Rules of use + +1. **Delegate reading; keep understanding.** The cardinal rule. A subagent returns + conclusions — its *reasoning* dies with its context. Never delegate work you'll + iterate on (implementation, design) because you'd be editing half-blind. Test: *if + the next step needs the understanding, do it in the main window.* +2. **Demand verifiable outputs.** Trustworthy reports cite things you can spot-check + without re-reading the inputs: `file:line`, repro commands, failing test names, URLs. + If an agent's output can't be made verifiable, it's a bad subagent task. +3. **The description field is the API.** Auto-delegation reads only `description`. Write + it as trigger conditions for the delegating model, not marketing for you. "Use + proactively when…" and "MUST BE USED after…" genuinely change behavior. +4. **Least-privilege tools.** Evaluative agents get read-only (`Read, Grep, Glob`, + maybe `Bash` for git/scanners). Only agents whose *job* is writing get `Write`/`Edit`. + This keeps reports honest (an agent that can "just fix it" stops reporting) and makes + background runs safe. +5. **One job per agent.** When a definition grows "and also…", split it. A muddled + mission produces a muddled report. +6. **Cap the report.** Every definition states a line budget. The main context is the + scarce resource the whole system exists to protect; an agent that returns 500 lines + defeats itself. +7. **Mandate a Surprises section.** Cheap insurance against tunnel vision — the best + findings are often outside the asked question. "None" is an acceptable answer; + omitting the section is not. +8. **Two dials per agent: model × effort.** `model` is who you hire — haiku for + mechanical work, sonnet default, opus where judgment is the product. `effort` is + how long they're allowed to think before answering — it scales reasoning depth, not + capability ceiling. Both live in the wrapper frontmatter; frontmatter effort + overrides the session level while that agent runs. Match the dial to where the cost + actually lives: evaluator and security-auditor are **opus/high** because the report + *is* the reasoning; reviewer, researcher, exerciser, and spec-checker are + **sonnet/medium** because their cost is dominated by frequency, tool-call turns, or + procedure-following — not thinking depth. The deep insight: a well-proceduralized + guide is *pre-computed reasoning*, so every hour spent tightening a guide lowers + the model+effort that task needs forever. `low` is for truly mechanical agents + (migrator, test-runner) once their guides are trusted; `xhigh` is the upgrade if an + opus agent's reports feel shallow on hard targets. Global overrides, strongest + first: `CLAUDE_CODE_EFFORT_LEVEL` and `CLAUDE_CODE_SUBAGENT_MODEL` env vars → + wrapper frontmatter → session setting — handy for "run everything cheap today." +9. **Fresh eyes need fresh inputs.** When delegating to reviewer/debugger types, give + symptoms and scope — *never your theories*. Anchoring them throws away the one thing + the separate context bought you. +10. **Parallelize the independent, serialize the dependent.** "Audit security, exercise + the app, and check spec compliance *in parallel*" is one sentence to the main agent. + But chained work (find issues → fix them) must flow back through the main thread. +11. **Iterate the guide, not the chat.** A disappointing report means the guide is + wrong. Fix `guides/.md` (it's version-controlled) and rerun — guides load at + run time, so no restart. Touch the wrapper only for tools/model/description + changes, and restart the session when you do. Correcting the agent + conversationally fixes nothing for next time. +12. **Know when *not* to delegate.** Quick targeted changes; tasks needing your taste + mid-stream; reads under ~5 files (overhead exceeds benefit); anything where latency + matters more than context hygiene. + +--- + +## 4. Shaping the report + +The summary is the interface — "report back" gets you mush. Every *guide* in this kit +embeds a variant of the universal contract below; the agent reads its guide at startup, +so the contract reaches it without bloating the wrapper. The universal form here is +your template for designing new guides. + +### Universal report contract + +``` +## Verdict — the answer, 1–3 sentences, no throat-clearing +## Findings — each: [severity] one-line title → evidence → so-what +## Coverage — what was examined and what wasn't (makes silence meaningful) +## Surprises — anything unexpected, on-mission or not ("none" allowed) +## Next actions — ranked, concrete, imperative mood +## Confidence — high/medium/low + the one thing that would raise it +``` + +### Severity scale (shared by all evaluative agents) + +- **P0** exploitable, data loss, or crashes in normal use — fix before anything else +- **P1** wrong behavior or weak security on realistic paths — fix before release +- **P2** works, but fragile / hard to maintain / poor practice +- **P3** cosmetic, style, minor docs +- **P4** informational / matter of taste + +### Evidence by agent type + +Per-agent evidence requirements: code findings cite `file:line`; bugs include exact +repro commands plus expected-vs-actual; research claims carry a URL and are labeled +**Fact** (sourced) or **Inference** (the agent's own conclusion); compliance findings +cite the requirement's doc URL. A finding without its evidence type gets deleted, not +softened. + +### Length budgets + +Reviewer ≤ 70 lines · exerciser & spec-checker ≤ 80 · researcher & security-auditor +≤ 100 · evaluator ≤ 120. Tighten freely; loosen only with cause. + +--- + +## 5. Creating a new agent + +Three routes, in order of preference: + +**Route 1 — copy a neighbor.** The fastest path to a *good* agent is copying the +closest existing pair: its guide in `guides/` and its wrapper in +`adapters/claude/agents/`. The contract and structure carry over; only the mission +changes. Scope rule applies: project-specific agents put the guide in +`/docs/guides/` and the wrapper in `/.claude/agents/` instead. + +**Route 2 — `/agents` → "Generate with Claude".** Interactive, guided, loads without a +session restart. Good for quick experiments; once it earns permanence, split it — +substance to a guide, vendor header to a thin wrapper — at the right scope. + +**Route 3 — the meta-prompt.** Paste this into any Claude session, filled in: + +``` +Create a Claude Code subagent definition file (YAML frontmatter + system-prompt body). + +Role: [one sentence — what it does] +Trigger: [when the main agent should delegate; exact phrases that should fire it] +Inputs: [what the delegation prompt will contain — paths, scope, symptoms] +Tools: [least-privilege list; justify any Write/Edit/Bash] +Must never: [hard limits — e.g. never edits source, never returns raw logs] +Report: [sections, severity scale, evidence type, line cap] +Model: [haiku|sonnet|opus|inherit — and why] + +Produce TWO files per my portability protocol: +1. The GUIDE — vendor-neutral, second person, self-contained: mission, procedure, + hard rules, then the report template verbatim. End with: "If blocked, report + exactly what blocked you — never guess or fabricate findings." + → guides/.md (standards repo if global; /docs/guides/ if project). +2. The WRAPPER — vendor syntax confined to the header: YAML frontmatter with name, + a description written FOR THE DELEGATING MODEL (explicit trigger conditions, + "use proactively when…" phrasing where wanted), least-privilege tools, model. + Body only: role one-liner, directive to read the guide first, stop-and-say-so + fail-safe if the guide is unreadable, one-line safety floor. + → adapters/claude/agents/.md (global) or /.claude/agents/ (project). +Then show one example invocation and the first 10 lines of an ideal report. +``` + +**Checklist** (every guide+wrapper pair, before it ships): +Guide — self-contained · embedded report template with line cap · Surprises section · +blocked-means-say-so clause. Wrapper — trigger-rich description · least-privilege +`tools` · explicit `model` · guide pointer with fail-safe · safety floor. Then: save +both at the right scope, restart the session (new wrapper), run once on a real task, +tighten the guide where it disappointed. + +--- + +## 6. The orchestrator question + +You cannot build an orchestrator *as a subagent* — subagents can't spawn subagents. +Three real options: + +1. **Slash command (this kit's choice): `/full-eval`.** A command file is just a stored + prompt for the *main thread* — and the main thread *can* fan out. `/full-eval` makes + it launch evaluator + security-auditor + exerciser (+ start9-spec-checker when + relevant) in parallel, then synthesize one deduplicated, prioritized report. Zero new + machinery, works in any session. +2. **`claude --agent ` (advanced).** A session launched this way takes the agent's + system prompt as its main thread — and a main-thread agent *can* spawn subagents, + even restricted to a roster via `tools: Agent(evaluator, security-auditor, ...)`. + Build this only if `/full-eval` starts feeling too manual. +3. **Agent teams (experimental).** Multiple communicating sessions. Ignore until a task + genuinely exceeds one session's context even with subagents. + +Synthesis is the orchestrator's real job, and it stays in the main thread on purpose: +cross-referencing ("the crash the exerciser found is the injection the auditor +flagged") is exactly the understanding you don't delegate. + +--- + +## 7. Workflows + +### A. The retrospective (the dozen existing repos) + +Per repo, in order: + +1. **Retrofit first** (per `retrofit-playbook.md`): AGENTS.md with Current state, the + CLAUDE.md symlink. Subagents load this file — the evaluator literally reads it to + judge the build against your stated intent. Eval before retrofit = grading against + a blank rubric. +2. **`/full-eval`** in a fresh session. Walk away; read one synthesized report. +3. **Triage** into the repo's AGENTS.md Current state: P0/P1 become the work queue, + P2 becomes a "known debt" list, P3+ gets deleted or done in bulk. +4. **Fix in the main session** (understanding work — yours), running **reviewer** on + each meaningful diff before commit. +5. **Close out** per the ritual; move to the next repo. Don't batch — one repo's + full cycle beats six repos' half-cycles. + +### B. Steady state (everything built from now on) + +- **While building:** built-in Explore for "how does X work" questions; researcher + before adopting any dependency; fresh-debugger discipline when stuck >1hr (symptoms + only, no theories). +- **Every meaningful diff:** reviewer, before commit. This is the habit that compounds. +- **Before any release:** exerciser + security-auditor in parallel. +- **Before registry submission:** start9-spec-checker. +- **Quarterly-ish:** `/full-eval` on actively maintained repos; drift accumulates + silently. + +--- + +## 8. Install & maintenance + +One-time install — the portability protocol's standard symlinks (if `~/.claude/agents` +or `~/.claude/commands` already exist as real directories, move their contents into the +adapters folders first): + +```bash +ln -s ~/Projects/standards/adapters/claude/agents ~/.claude/agents +ln -s ~/Projects/standards/adapters/claude/commands ~/.claude/commands +``` + +Then restart any open Claude Code session (wrappers load at session start). First run: +`cd` into a repo, `claude`, then `/full-eval` — or invoke singles anytime +(`@agent-reviewer look at my uncommitted changes`). + +- **Two-file edit model.** Substance → `guides/.md`, live on the agent's next + run, no restart. Machinery (tools, model, description) → the wrapper, restart + required. When in doubt, you're editing the guide. +- Edits land via the normal close-out ritual → commit → push → backed up on the Start9 + with the rest of the standards repo. The directory symlinks mean `git pull` updates + every machine-wide agent; there is no reinstall step. +- Sessions that can't see `~/Projects` (cloud, containers) simply have no global + agents; a wrapper that loads without its guide stops and says so rather than + improvising — that's the fail-safe working as designed. +- Prune ruthlessly. An agent unused for months is context-rot in the `/agents` list; + delete the pair — git remembers.