chore(agents): point Matt Pocock skills at the beads issue tracker
CI / check (push) Has been cancelled

The engineering skills (to-tickets, triage, spec, wayfinder) need to know
where issues live for this repo. It is not the Gitea forge remote; it is
bd/beads, which AGENTS.md already mandates for all task tracking.

Adds docs/agents/issue-tracker.md (bd commands and wayfinding mapping),
docs/agents/triage-labels.md (five canonical roles kept as-is, applied
with bd tag / bd label add), docs/agents/domain.md (single-context
layout: CONTEXT.md plus docs/adr/ at the root), and an 'Agent skills'
index block in AGENTS.md. The pre-existing staged deletion of CLAUDE.md
is left out of this commit and stays in the index.
This commit is contained in:
2026-10-02 09:26:40 +03:00
parent 704b8e577a
commit 864447de71
4 changed files with 162 additions and 0 deletions
+63
View File
@@ -0,0 +1,63 @@
# Issue tracker: bd (beads)
Issues and specs for this repo live in the beads database at `.beads/`. The source of truth is `.beads/issues.jsonl`, managed through the `bd` CLI (v1.3.0). beads state is versioned in the repo and synced with `git push`; there is no separate Dolt remote.
The forge remote (`git.millerson.name`, self-hosted Gitea) is not the issue tracker. Do not open Gitea, GitHub, or GitLab issues for work in this repo.
## Core commands
```bash
bd ready # open issues with no active blockers
bd show <id> # full issue detail
bd list # list issues
bd search "<text>" # text search
bd create "title" -d "description" -p 2 -l label1,label2
bd q "quick capture" # create and print only the id
bd update <id> --claim # claim before starting work
bd close <id> --reason "..."
bd reopen <id>
bd comment <id> "..." # conversation history
bd note <id> "..." # append a note
bd tag <id> <label> # shorthand for: bd update <id> --add-label <label>
bd label add <id> <label>
bd label remove <id> <label>
bd status # database overview
```
Issue ids look like `nix-overlay-4g1`. New work must be claimed with `bd update <id> --claim` before it starts.
## When a skill says "publish to the issue tracker"
Run `bd create`. Use one issue per ticket. Put the full body in `--description` (markdown is fine). Add labels per `triage-labels.md`. For a multi-part spec, create a parent issue and link children with `--deps`.
## When a skill says "fetch the relevant ticket"
Run `bd show <id>` and read the description plus comments (`bd show <id> --include-comments --json` when full comment bodies are needed). The user normally passes the issue id directly.
## Dependencies
`bd create --deps 'blocked-by:nix-overlay-4g1,discovered-from:nix-overlay-2a3'`
Bare ids, `depends-on:` and `blocked-by:` all make the new issue depend on the target. `blocks:` reverses the direction. `bd link`, `bd dep`, and `bd children` manage the graph after creation. `bd ready` already excludes anything with an unresolved blocker, so a ticket is unblocked when every issue that blocks it is closed.
## Wayfinding operations
Used by `/wayfinder`. The map is a parent bead; the children are its sub-issues.
- **Map**: a bead created for the effort. Its description holds the Notes / Decisions-so-far / Fog body.
- **Child ticket**: a bead linked to the map with `--deps depends-on:<map-id>`. The question goes in the description. Record the ticket type as a label (`research`, `prototype`, `grilling`, `task`).
- **Blocking**: a `blocked-by:<id>` dependency on the blocking bead.
- **Frontier**: `bd ready` output, restricted to children of the map (`bd children <map-id> --ready` or filter `bd ready` by parent). Lowest priority number, then oldest, wins.
- **Claim**: `bd update <id> --claim` before any work starts.
- **Resolve**: append the answer with `bd note <id> "..."` or `bd comment`, then `bd close <id> --reason "<answer gist>"`, then add a context pointer (gist plus issue id) to the map's Decisions-so-far with `bd note <map-id> "..."`.
## Session end
Work is not complete until pushed. The project workflow requires:
```bash
git pull --rebase
bd dolt push # prints "No remote is configured - skipping." here; expected, not a failure
git push
git status # must show up to date with origin
```