grant/standards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tighten portability protocol: no inline-substance exceptions

Browse Source 
Align portability.md with the handoff refactor — every command and
subagent is now a thin wrapper whose substance lives in guides/, with
no self-contained inline exceptions.
This commit is contained in:
Keysat
2026-06-12 13:08:13 -05:00
parent 98755f8507
commit ba7bb3479a
1 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
portability.md
+5 -5
View File
@@ -6,7 +6,7 @@
``` ```
~/Projects/standards/ ~/Projects/standards/
how-i-work.md portability.md retrofit-playbook.md subagents-handbook.md how-i-work.md portability.md retrofit-playbook.md
guides/ ← neutral substance (vendor-agnostic): checklists, role knowledge guides/ ← neutral substance (vendor-agnostic): checklists, role knowledge
adapters/ adapters/
claude/ claude/
@@ -14,7 +14,7 @@
agents/ ← ~/.claude/agents symlinks here (global subagents) 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. Companions: `how-i-work.md` (the always-loaded user layer, under 50 lines) and `retrofit-playbook.md` (the one-time conversion manual). This document is reference material — never symlink it into anything always-loaded.
## The principle ## The principle
@@ -24,7 +24,7 @@ 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. 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. 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. 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. 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. 5. **No secrets in any of these files.** Secrets live in gitignored .env files; documents reference env-var names only.
@@ -37,8 +37,8 @@ Corollaries:
| 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 | | 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 | | 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 | | 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 | | 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) | 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 | | 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). **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).