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
+56
View File
@@ -0,0 +1,56 @@
# Capture — append an idea or bug to the cross-project inbox
The user has a thought about some project — a feature, an idea, a bug they just hit — and
wants it logged *now*, without acting on it and without stopping to decide where it
belongs. Your whole job is to record it durably and get out of the way. Capture is
deliberately dumb and uniform: no routing, no triage, no discussion of the merits. Routing
happens later, via `/triage`, inside the relevant project.
The inbox is a single file: `~/Projects/standards/INBOX.md`. You append to it regardless of
which repo the user invoked you from.
## Procedure
1. **Parse the note** from the user's input (`$ARGUMENTS`). Extract or infer four fields —
keep it fast, ask only when a field is genuinely missing and can't be inferred:
- **project** — the target repo. If the user named one, use it. If not, infer from the
current working directory's folder name. If you truly can't tell, use `?` (triage will
sort it) rather than interrogating the user. If the idea is for a **brand-new repo that
doesn't exist yet** ("new project/app/idea for…"), use `new` — or `new:working-name` if
they gave a name — and set type `project`. These wait for the new-repo bootstrap flow
and are never triaged into an existing repo.
- **type** — one of `bug | feature | idea | skill | agent | project | chore` (`project`
= a potential new repo, used with a `new`/`new:name` project tag). Infer from wording
("found a bug" → bug, "we should add" → feature, "what if" → idea). Default `idea`.
- **priority** — `P0``P3`. Use a priority only if the user signals one ("urgent",
"P1", "minor"). Default `P2`.
- **note** — the user's text, lightly cleaned up to stand on its own later. Preserve
their meaning; don't editorialize or expand.
2. **Append one line** to the `## Items` section of `~/Projects/standards/INBOX.md`, in the
exact format the file documents:
`- [ ] (project) [type][Pn] note — optional context, YYYY-MM-DD`
Use today's date. Don't reformat or reorder existing lines.
3. **Make it durable.** Commit and push *only the inbox line* so the note survives and is
visible from any session or machine — this is the point of the tool, so do it without
asking:
- `git -C ~/Projects/standards add INBOX.md`
- `git -C ~/Projects/standards commit -m "Capture: <short summary>" -- INBOX.md`
(the `-- INBOX.md` pathspec commits only the inbox, even if other changes happen to be
staged in the standards repo — never sweep unrelated work into a capture commit).
- `git -C ~/Projects/standards push` (only if a remote is configured; if the push fails,
report it but don't treat the capture as lost — it's committed locally).
Do not touch or commit anything in the repo the user invoked you from.
4. **Confirm in one line** — echo back the exact line you wrote and where, e.g.
`Logged to inbox: (relay) [bug][P1] … — triage it next time you're in relay with /triage.`
Nothing more; the user is mid-thought on something else.
## Rules
- One invocation = one item, unless the user clearly lists several; then append one line
each.
- Never act on the captured item, open files in the target repo, or start discussing the
fix. Capture only.
- No secrets in the note — if the user's text contains a key/token/password, replace it
with a placeholder and say you did.
- If you cannot write to `~/Projects/standards/INBOX.md` (missing, unwritable), stop and
report precisely that — do not silently drop the note or stash it somewhere else.
+70
View File
@@ -0,0 +1,70 @@
# Triage — drain this project's inbox items into the right place
You are running inside one project repo. Your job is to take the items in the cross-project
inbox that belong to *this* repo and route each one to where it actually lives — then clear
it from the inbox. This is the deliberate, with-context counterpart to `/capture`: capture
is dumb and uniform, triage is where the judgment happens. Routing decisions are the user's
call — propose, don't impose.
The inbox is `~/Projects/standards/INBOX.md`. This repo is identified by its current working
directory's folder name (and `AGENTS.md`/`README.md` if you need to confirm the name).
## Procedure
1. **Gather.** Read `~/Projects/standards/INBOX.md`. Select the unchecked items whose
`(project)` tag matches this repo's folder name. Also surface any `(?)` items and ask the
user whether each belongs to this repo — don't assume. **Never select `(new)` or
`(new:…)` items** — those are proposed new repos, not work for this one; if any exist,
note them in your report as awaiting the new-repo bootstrap, but leave them in the inbox.
If there are no matching items, say so and stop.
2. **Orient.** Read this repo's `AGENTS.md` (especially `## Current state`) and `ROADMAP.md`
(if present) so your routing proposals fit what's already there and you can spot
duplicates of items already tracked.
3. **Propose a routing for each item.** Present them as a short list, each with a proposed
destination and a one-line reason. The destinations:
- **`## Current state` in AGENTS.md** — near-term, act-on-it-now items (high priority,
active work, a bug to fix this session).
- **`ROADMAP.md`** — longer-term backlog (features, ideas, deferred work). Create
`ROADMAP.md` if it doesn't exist and there's anything to put there.
- **A `docs/guides/<topic>.md`** (or this repo's equivalent guide location) — if the
item is durable subsystem guidance rather than a task.
- **Escalate to the standards repo** — if the item is really a cross-repo idea (a new
command/agent/standard), it belongs in the standards `ROADMAP.md` or stays in the
inbox tagged `(standards)`, not in this project. Flag these; don't force them into the
project.
- **Discard** — already done, duplicate, or no longer wanted. Say why.
Let the captured priority (`Pn`) inform the destination but use judgment — a `P1` bug
goes to Current state, a `P3` idea to ROADMAP.
4. **Get approval.** Wait for the user to confirm or adjust the routing. Do not edit any
file before they approve — these are their durable project files.
5. **Apply.** Make the approved edits to this repo's files (keep `## Current state` lean —
present tense, ~15 lines max per the close-out convention; if it overflows, push older
items to ROADMAP). Then remove the triaged items from `~/Projects/standards/INBOX.md` — delete the
lines outright (the git history is the record); leave untriaged and other-repo items
untouched.
6. **Commit.** Two repos changed — present the proposed commit message(s) for both and
**wait for the user to confirm before committing or pushing anything** (the same gate as
step 4): this project's AGENTS.md/ROADMAP changes, and the standards repo's INBOX.md
(`git -C ~/Projects/standards …`). Follow `how-i-work.md` for messages and the
no-AI-attribution rule.
7. **Report** what landed where, what was discarded, and any items escalated to the
standards repo that the user still needs to handle there.
## The portable inbox-check line
So pending items surface automatically at the *start* of a session (not only when the user
remembers to run `/triage`), every project repo's `AGENTS.md` should carry this line — it's
vendor-neutral, so any harness that reads AGENTS.md honors it:
> **Inbox check:** At session start, if `~/Projects/standards/INBOX.md` exists, scan it for
> items tagged `(this-repo)` and surface them before proposing next steps; triage with
> `/triage`.
If this repo's AGENTS.md lacks that line, offer to add it as part of the triage.
## Rules
- Never invent items or routings. If an item is ambiguous, ask.
- Never edit a project file before the user approves the routing.
- If you cannot read `~/Projects/standards/INBOX.md`, stop and report precisely that — do
not guess what was captured.