Add portability protocol and subagents handbook
Document the portability protocol (vendor-neutral knowledge, vendor-named symlinks) and a Claude subagents reference handbook, and link the portability protocol from the retrofit playbook.
This commit is contained in:
Keysat
@@ -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 | `<repo>/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 | `<repo>/docs/guides/<topic>.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 — `<repo>/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/<tool>/` (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 `<repo>/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/<tool>/` 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/<topic>.md` → symlinks → `docs/guides/<topic>.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/<project>/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: ___
|
||||
Reference in New Issue
Block a user