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:
+58
-1
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user