board

Files (4)

• SKILL.md
• attribution-backfill.mjs · scripts/
• board.mjs · scripts/
• events.mjs · scripts/

SKILL.md (first lines)

# Board — one visual beads board per repo

`scripts/board.mjs` turns a repo's beads data into one self-contained HTML page.
The generator lives in this skill, not in the repo, so every board has the same
layout and a fix here fixes every project. It is **read-only**: it runs
`bd export`, `bd comments`, `gh pr list` and `gh api` inside the repo, writes a
single file outside it, and refuses to write inside it. It never changes bd
data.

## When to run it

- Right after issues are seeded (`prd-seed`, `bd mol pour`, a manual batch).
- At every check-in: a PR opened, a PR merged, an issue closed or reopened.
- Whenever the user asks to see or refresh the board.

Keep one board per repo for the life of the project. Never publish a second.

## Steps

1. **Find the existing board.** Call the Artifact tool with `action: "list"`
   (raise `limit` if needed) and look for the title `<Project> Board`. If the
   URL is not in the listing, ask the user for it before creating a new one.
2. **Read it back** with `action: "read"` on that URL. The result names the
   saved HTML file. Pass that file as `--from` so the board keeps its name and
   accent colour: both are stored in `<meta name="board-name">` and
   `<meta name="board-accent">` inside the page.
3. **Generate** into the scratchpad directory (never the repo):

   ```bash
   node "<skill dir>/scripts/board.mjs" <repo> \
     --out "<scratchpad>/<project>-board.html" \
     --from "<saved file from step 2>"
   ```

   Options:
   - `--accent <#rrggbb>` sets the project colour. Use it on the first board, or
     to change the colour. Without it, and without `--from`, the default is a
     neutral teal.
   - `--name "<Project>"` overrides the name. The default is the repo folder
     name in title case.
   - `--log <file.json>` merges an older hand-kept log (`[{ "at", "note" }]`)
     into the check-ins. This is only for boards that predate this skill.
   - `--activity-days <n>` sets the Activity window (default 30); `--no-activity`
     leaves the view out. bd only gives history per issue, a few seconds each,
     so only issues touched in the window are read, and the result is cached
     outside the repo. The first run on a busy repo takes minutes; later runs
     re-read only issues that changed. `--refresh` ignores the cache.

   The script prints one JSON line: issue, PR and deploy counts, lanes,
   milestones, diagram size and output bytes. Check the counts against
   `bd list` before publishing.
4. **Publish** to the existing URL: Artifact `publish` with `url` set to the
   board's URL and `file_path` set to the generated file. On a first board only,
   omit `url` and pass `icon: "board"`.
5. **First board only:** record the URL in the project's vault note and add one
   line to the central artifact index `3. Resources/Artifacts.md`. Write both
   through the `obsidian` CLI, following the vault rules; never edit vault files
   directly.

## What the page shows

| View | Contents |
|---|---|
| Status | Lane tiles (queued, ready, in progress, in review, done, deferred), open PRs with their issues and preview URL, the next ready issues, deploys from the last 30 days, and a progress card per open epic. |
| Board | One board per milestone with tabs and a progress bar, or a single board when the repo has no milestones. Five lanes plus a deferred strip. Done shows the 8 most recent. |
| Issues and build order | A diagram, left to right, where each issue sits one column after its deepest blocker or parent. Solid arrows are `blocks` links, green once the blocker is done. Dashed lines run parent to child. Every box and row opens the issue. |
| Issue record | Description, design, acceptance, notes, close reason, comments, parent and children, blocked by, unblocks, related links, PRs, execution metadata and dates. |
| Check-ins | Grouped by day: issues opened and closed, PRs opened, merged or closed, and notes. Days more than 14 days before the latest are collapsed. |
| Activity | Every change beads recorded in the window, newest first, with who made it: `Claude`, `Claude · <agent type>`, or a person's name. Changes matched to Claude after the fact carry an *inferred* tag with their confidence. PRs opened and merged are included. |
| Done | Every closed issue, newest first. |

How the data maps:

- **Lanes.** Closed means done. `deferred` means deferred. An issue with an open
  PR is in review. `in_progress` means in progress. `blocked`, or any open
  `blocks` dependency, means queued. Everything else is ready.
- **PR links.** `external_ref: gh-<n>` first. Otherwise, a PR whose branch,
  title or body names the full id, or whose body names the short id in
  backticks.
- **Milestones.** Labels of the form `milestone:<name>`, with underscores read
  as spaces, ordered by each milestone's first issue.
- **Diagram scope.** On a project with 80 issues or fewer, every issue is drawn.
  On a larger one, only groups that still hold open work are drawn, plus
  unconnected open issues.
- **Deploys.** GitHub deployments from the last 30 days, the latest per
  environment. A deploy whose ref matches an open PR's branch appears on that
  PR as its preview.
- **People.** Owner and comment author show only the part before an `@`, since
  boards are often shared by link.
- **Who did it.** braynee's `beads-actor-sign` hook adds `--actor claude` (or
  `claude/<agent type>` inside a subagent) to every bd command Claude runs, so
  bd's audit events carry the real actor. A person running bd themselves is
  still signed with their git name. Changes bd makes on its own (git-hook
  imports, other hooks calling bd) are signed with the git name too.

## Signing the past: the attribution backfill

Before the signing hook, every change Claude made was recorded under the
owner's git name. `scripts/attribution-backfill.mjs` matches those events to
the bd commands in Claude Code's session transcripts and records each match in
bd's append-only provenance log, next to the history rather than in it. Dolt
history is never rewritten, and no session ids are written.

```bash
node "<skill dir>/scripts/attribution-backfill.mjs" <repo>            # dry run: prints what it would record
node "<skill dir>/scripts/attribution-backfill.mjs" <repo> --apply    # records it
```

- Transcripts default to the repo's own folder under `~/.claude/projects/`.
  Add `--transcripts <dir>` (repeatable) for folders the work also ran from: a
  moved checkout, or sessions started in another directory.
- Each match carries a confidence: 0.95 for a bd command running when the
  event happened, lower for weaker evidence (a nearby command, a script or git
  command that fires bd, an event stored in local time). Matches under
  `--min-confidence` (default 0.65) are counted and left out. Two actors in the
  same window is ambiguous and left out.
- Events older than the oldest surviving transcript stay as recorded.
- Re-running is safe: provenance records are idempotent.
- `--debug <id>` prints one issue's events next to the commands found for it;

From hamchowderr/braynee, MIT.

More from hamchowderr/braynee