Add capture/triage inbox loop; dogfood AGENTS.md/ROADMAP; document git-tracking standard

Introduce the cross-project capture->triage->roadmap loop: /capture appends an
idea or bug to INBOX.md from any repo (new-project ideas included), /triage drains
a project's items into its AGENTS.md or ROADMAP.md. Give the standards repo its own
AGENTS.md (+ CLAUDE.md symlink) and ROADMAP.md so it follows its own standard, and
add a 'What git tracks' section to portability.md plus the canonical .gitignore
block answering what is committed vs gitignored around .claude and symlinks.
This commit is contained in:
Keysat
2026-06-14 10:36:36 -05:00
parent b9dd7288c4
commit 9e5c42c25f
11 changed files with 483 additions and 2 deletions
+58 -1
View File
@@ -6,7 +6,10 @@
```
~/Projects/standards/
how-i-work.md portability.md retrofit-playbook.md subagents-handbook.md
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/
@@ -43,6 +46,60 @@ Corollaries:
**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.