Issue Tracker
How the agent skills (to-spec, to-tickets, triage, wayfinder, …) track work in this repository. There is no hosted tracker: issues are tasks in TODO.md at the repository root, edited only under the rules of the todo-md skill (layout, line format, who approves what). Work that does not fit on one line (specs, wayfinder maps) lives under .scratch/.
Both TODO.md and .scratch/ are gitignored and stay local: this repository is public. Never commit or quote them in a commit message or pull request.
Conventions
- One ticket is one task line in
TODO.md:- [ ] <TYPE>: <description>, at most ~300 characters (seetodo-md). - Triage state is the section the line sits in, not a label (see
triage-labels.md). - Only the owner approves a ticket, by moving it to
🟡 To do. An agent adds a line to🟡 To doonly when asked to, or when it splits an approved task; otherwise new tickets go to🤖 Agent recommendations. - A ticket backed by a spec ends with a pointer:
— spec: .scratch/<feature-slug>/spec.md. - A spec is
.scratch/<feature-slug>/spec.md. Discussion is appended at its bottom under a## Commentsheading.
Working the tickets
/next-task is how tickets get implemented here: it picks from 🟡 To do, verifies, records the task in ✅ Done and proposes a commit. Do not use the implement skill in this repository: it ends by committing, and only the owner commits.
When a skill says "publish to the issue tracker"
- A single ticket: add a task line to
🤖 Agent recommendations, or to🟡 To dowhen the owner asked for the task. - A spec (
to-spec): write.scratch/<feature-slug>/spec.md(creating the directory), then add one task line pointing at it. - Tickets cut from a spec (
to-tickets): one task line per ticket, in implementation order, each pointing at the spec. No per-ticket files.
When a skill says "fetch the relevant ticket"
Find the line in TODO.md the owner names (by its words or its position) and follow its spec: pointer when it has one.
Wayfinding operations
Used by /wayfinder. Its tickets need more state than a TODO.md line holds, so they live in files; TODO.md gets a single line for the effort: - [ ] CHORE: wayfinder <effort> — map: .scratch/<effort>/map.md.
- Map:
.scratch/<effort>/map.md(the Notes / Decisions-so-far / Fog body). - Child ticket:
.scratch/<effort>/issues/NN-<slug>.md, numbered from01, with the question in the body. AType:line records the ticket type (research/prototype/grilling/task); aStatus:line recordsclaimed/resolved. - Blocking: a
Blocked by: NN, NNline near the top. A ticket is unblocked when every file it lists isresolved. - Frontier: scan
.scratch/<effort>/issues/for files that are open, unblocked, and unclaimed; first by number wins. - Claim: set
Status: claimedand save before any work. - Resolve: append the answer under an
## Answerheading, setStatus: resolved, then append a context pointer (gist + path) to the map's Decisions-so-far inmap.md.