Files

T

CI / check (push) Has been cancelled

Details

chore(agents): point Matt Pocock skills at the beads issue tracker

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.

2026-10-02 09:26:40 +03:00

3.3 KiB

Raw Blame History

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

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:

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

3.3 KiB Raw Blame History