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