standards/portability.md

# 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/
  AGENTS.md  ← CLAUDE.md (relative symlink)   ← agent-facing orientation to this repo
  README.md   how-i-work.md   portability.md   retrofit-playbook.md   subagents-handbook.md
  ROADMAP.md               ← this repo's backlog (future agents, commands, standards)
  INBOX.md                 ← cross-project capture buffer (/capture → here, /triage drains it)
  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, ~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 substance they point at never moves. Every command and subagent is a thin wrapper in `adapters/<tool>/` whose substance lives in `guides/` — no inline exceptions, so any wrapper converts to a new tool by swapping its header.
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 (now) | `## Current state` section in AGENTS.md | (same symlink) | Fully portable; maintained by the close-out ritual |
| Project backlog (later) | `ROADMAP.md` at repo root | — (plain committed file, no symlink) | Fully portable; committed and pushed like any file, read only on demand |
| 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 | 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) | substance in `guides/` at matching scope, same rule as subagents | thin wrapper in `.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).

## What git tracks

Symlinks and `.claude/` raise a recurring question: what belongs in the repo, what stays
local, and how does the global `~/.claude` layer get backed up? One rule resolves all three
— **git tracks knowledge and the wiring that serves it; it ignores machine-local state and
secrets** — but it lands in three places.

**1. Relative symlinks are committed and travel.** Git stores a symlink as its target path.
Because every vendor path in this standard is a *relative* symlink (`CLAUDE.md → AGENTS.md`,
`.claude/rules/x.md → ../../docs/guides/x.md`), it commits and clones correctly on any
machine. This is the concrete payoff of the relative-symlink mandate: an absolute symlink
would commit too, but break on every other clone. Never commit an absolute symlink.

**2. Inside a project repo — commit shared, ignore local.**

Committed (any agent or teammate needs them to work the repo correctly — corollary 1):
`AGENTS.md` and its `CLAUDE.md` symlink; `docs/guides/*.md` and their `.claude/rules/*.md`
symlinks; `ROADMAP.md`; `.claude/settings.json` (shared project settings and hooks —
deterministic behavior is part of the repo); `.claude/agents/*.md`, `.claude/commands/*.md`,
`.claude/skills/` (project-scoped wrappers).

Gitignored (per-user, per-machine, or secret): `.claude/settings.local.json` and any
`*.local.*` (personal permissions/overrides); `.env` and secrets (corollary 5); OS cruft.

Put these in the repo's **own committed `.gitignore`** — don't rely on a global
excludesfile, which a fresh clone or another machine won't have. Canonical block:

```
# Secrets & local env
.env
.env.*
!.env.example

# Claude Code — commit shared config, ignore personal/local
.claude/settings.local.json
.claude/*.local.json

# OS cruft
.DS_Store
```

**3. The global `~/.claude` layer is backed up *through the standards repo*, not on its
own.** `~/.claude` is not a git repo. Its durable, portable parts — `commands`, `agents`,
`CLAUDE.md` — are symlinks *into* this standards repo, so committing and pushing standards
backs them up. Everything else under `~/.claude` (the machine-local `settings.json`,
`projects/` session transcripts and auto-memory, history, todos, caches) is disposable
session state by design (corollary 4) and is neither committed nor backed up. What makes
this safe: promote anything durable out of auto-memory into a committed file (AGENTS.md or a
guide); audit with `/memory`.

So the answer to "are we backing up all of `.claude`?" is **no, by design**: knowledge and
shared wiring are committed per-repo or symlinked into a backed-up repo; machine-local state
and secrets never are.

## 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: ___