feat(beads): add Beads integration docs, skill template, and config by raykao · Pull Request #159 · ChrisRomp/copilot-bridge

raykao · 2026-03-26T04:00:54Z

Docs and config for Beads integration — no code changes. See #157 for the full journey, key decisions, and validation results.

Changes

docs/beads.md — setup guide, hook examples, 3-tier sync strategy, MCP alternative, troubleshooting
templates/agents/beads.agent.md — agent skill file with complete bd workflow; includes point-of-discovery memory discipline (bd remember inline, not batched to session end)
templates/agents/AGENTS.md — Beads section added; MEMORY.md kept as fallback
config.sample.json — shell(bd) added to default permissions allow list

No Breaking Changes

All additive. Workspaces without Beads are unaffected — conditional language throughout.

Relationship to PR #158

Independent — can be reviewed and merged in either order. PR #158 wires the session hooks that the hook examples here depend on.

Relates to: #157

Adds Phase 1 of the Beads integration (docs and config, no code changes): - docs/beads.md: full integration guide covering prerequisites, workspace setup, session hook automation, sync strategy (3 tiers), MCP alternative, and troubleshooting - templates/agents/beads.agent.md: agent skill file documenting the full bd workflow — session start (bd prime), task ops (create/claim/close/dep), session end (bd backup export-git), and troubleshooting - templates/agents/AGENTS.md: added "Task Memory (Beads)" section so agents know to use bd when available, with a pointer to the skill file for detail - config.sample.json: added shell(bd) to the default permissions allow list Relates to: ChrisRomp#157 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

This PR adds Beads (bd) integration documentation and templates so copilot-bridge workspaces can use Beads for persistent, structured task memory, plus a sample config update to pre-approve bd shell usage.

Changes:

Added a Beads integration guide covering setup, hooks, sync strategies, MCP alternative, and troubleshooting.
Added a Beads workflow template file and updated the default AGENTS.md template to point agents toward using Beads when available.
Updated config.sample.json to allow shell(bd) by default.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
`docs/beads.md`	New Beads integration guide (setup, hooks, sync, MCP alternative).
`templates/agents/beads.agent.md`	New Beads workflow template file (currently written as an agent definition).
`templates/agents/AGENTS.md`	Adds a “Task Memory (Beads)” section directing agents to use Beads when configured.
`config.sample.json`	Adds `shell(bd)` to the default allowlist for permissions.

Comments suppressed due to low confidence (1)

docs/beads.md:139

Same issue as session-start.sh: hooks must output JSON on stdout or the bridge will ignore the result. As written, bd backup export-git output (if any) will cause JSON parse failure, and the hook won’t report anything back to the bridge. Consider redirecting command output to stderr or suppressing it, and explicitly output {} (or structured fields) as JSON.

```bash
#!/usr/bin/env bash
set -euo pipefail

input=$(cat)  # JSON from copilot-bridge: { "sessionId": "...", "channelId": "..." }

if command -v bd &>/dev/null; then
  bd backup export-git 2>/dev/null || true
fi

</details>



---

💡 <a href="/ChrisRomp/copilot-bridge/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

Copilot · 2026-03-26T04:05:10Z

+### 5. Add `bd` to workspace permissions (optional)
+
+If using `permissionMode: "auto"`, add `bd` to the workspace allow list in `config.json`:
+
+```json
+"permissions": {
+  "allow": ["shell(bd)"]
+}
+```


permissionMode: "auto" isn’t a valid config value in this repo (supported values are interactive and autopilot). If the goal is just to avoid prompts for bd, it’s enough to add shell(bd) to permissions.allow (as this PR does in config.sample.json). Please adjust the wording/value here to match the actual config schema.

Copilot · 2026-03-26T04:05:11Z

+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Inject bd prime output as context at session start
+input=$(cat)  # JSON from copilot-bridge: { "sessionId": "...", "channelId": "..." }
+
+if command -v bd &>/dev/null; then
+  bd prime 2>/dev/null || true
+fi
+```


Workspace hook commands must write a single JSON object to stdout (the hooks loader parses stdout as JSON); emitting plain bd prime output will be treated as invalid JSON and ignored. Update this example to wrap the bd prime output in a JSON response (e.g., as an additionalContext field) if the intent is to inject it into the session context.

This issue also appears on line 130 of the same file.

Copilot · 2026-03-26T04:05:11Z

+If this workspace has Beads configured (`.beads/` directory exists and `bd` is on PATH), use it for structured task tracking instead of `MEMORY.md`:
+
+- **Session start**: run `bd prime` to recover task context, then `bd ready --json` to see what to work on
+- **During work**: `bd create`, `bd update --claim`, `bd close` — see the `Beads Task Memory` skill for the full workflow


This references the Beads Task Memory “skill”, but this PR adds templates/agents/beads.agent.md (an agent definition template), not a skill in .github/skills/<name>/SKILL.md. Either add a real skill in the supported skill directory format, or update this section to refer to selecting the Beads agent definition (and use the actual agent name, which is derived from the filename).

Suggested change

- **During work**: `bd create`, `bd update --claim`, `bd close` — see the `Beads Task Memory` skill for the full workflow

- **During work**: `bd create`, `bd update --claim`, `bd close` — see the `beads` agent definition for the full workflow

Copilot · 2026-03-26T04:05:11Z

+---
+name: Beads Task Memory
+description: Persistent task tracking for this workspace using bd (Beads). Use this skill to create, track, and close tasks across sessions.
+---
+
+# Beads Task Memory Skill
+
+This workspace uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent, structured task memory backed by [Dolt](https://github.com/dolthub/dolt). Tasks survive session restarts and can be shared across multiple bots via Dolt sync.
+
+## Prerequisites
+
+- `bd` CLI installed: `npm install -g @beads/bd` or `brew install beads`
+- `bd init --quiet --stealth` run in the workspace directory
+- `BEADS_DIR` and `BEADS_ACTOR` set in workspace `.env` (auto-injected by copilot-bridge)
+


This file is named *.agent.md, which the bridge treats as an agent definition (discoverable via /agents in <workspace>/.github/agents/ or <workspace>/agents/), not a skill. If the intent is a skill (as referenced by AGENTS.md/docs), it should be provided in the skill directory format (.github/skills/<skillName>/SKILL.md). If the intent is an agent definition, the surrounding docs/templates should be updated to describe it as an agent and how to enable it, and the copy instructions should point at the bridge’s template path (~/.copilot-bridge/templates/...) rather than templates/... inside this repo.

Copilot · 2026-03-26T04:05:12Z

+BEADS_DIR=<workspace>/.beads
+BEADS_ACTOR={{botName}}
+PATH=/home/<user>/.local/bin:$PATH   # if dolt is not on system PATH
+```


The .env parser used by the bridge does not expand $PATH/${PATH} in .env values (they’re treated literally). As written, PATH=/home/<user>/.local/bin:$PATH will likely break PATH for the session/MCP servers instead of prepending. Consider removing this line and instead ensure Dolt is on the real system PATH, or document a supported approach (e.g., set PATH in the hook script, or use mcp-config.json env with ${PATH} expansion).

Copilot · 2026-03-26T04:05:12Z

+### 3. Add the skill file
+
+Copy `templates/agents/beads.agent.md` to the workspace's skill directory (typically `.github/agents/`):
+
+```bash
+cp templates/agents/beads.agent.md <workspace>/.github/agents/beads.agent.md
+```
+
+copilot-bridge automatically discovers and surfaces skill files in `.github/agents/` to the agent. The agent will use this to learn the `bd` workflow without any system prompt changes.


This section describes a “skill directory” at .github/agents/ and copying beads.agent.md there, but .github/agents/ is for agent definition files (*.agent.md), not skills. In copilot-bridge, skills are discovered from .github/skills/<skillName>/SKILL.md (and related skill roots). Update the instructions to place the Beads workflow in the actual skills format/location, or rename the doc to describe an agent definition and how to select it (e.g., via /agent).

… warning copilot-bridge hooks-loader expects scripts to output JSON on stdout (used for preToolUse decision responses). sessionStart/sessionEnd scripts that output non-JSON text (e.g. bd prime output) cause a harmless but noisy warn. Fix: redirect bd command output to /dev/null and echo '{}' as the final line so hooks-loader parses it cleanly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

bd remember should be called immediately at the moment of discovery, not batched to session end. Dolt commits on every write so memories survive any shutdown — but only if the agent actually called bd remember in the first place. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

raykao · 2026-03-26T04:45:12Z

Two fixes added from local validation (commit 200bf5a, 32715af):

fix(beads): hook scripts must output valid JSON

hooks-loader expects JSON on stdout from all hook scripts (used for preToolUse decision responses). Scripts outputting plain text (e.g. bd prime) trigger a [WARN] Hook command returned invalid JSON log. Fixed by redirecting bd output to /dev/null and emitting echo '{}' as the final line.

docs(beads): add point-of-discovery memory discipline

Added explicit guidance to templates/agents/beads.agent.md: call bd remember at the moment of discovery, not batched to session end. Dolt commits immediately on every write so memories survive any shutdown — but only if the agent actually called bd remember. Includes trigger criteria and format guidance.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-26T04:45:47Z

    "allow": [
      "read",
      "shell(ls)",
      "shell(cat)",
      "shell(head)",
      "shell(tail)",
      "shell(find)",
      "shell(grep)",
-      "shell(wc)"
+      "shell(wc)",
+      "shell(bd)"
    ],


permissions.allow in the sample config currently includes only read-only shell commands; adding shell(bd) auto-approves a state-mutating CLI (writes to .beads/, may run Dolt/network ops) even when write isn’t allowed. Consider keeping this opt-in (commented out with guidance) or adding a warning comment so users don’t assume the default allowlist remains read-only/safe.

Copilot · 2026-03-26T04:45:48Z

+description: Persistent task tracking for this workspace using bd (Beads). Use this skill to create, track, and close tasks across sessions.
+---
+
+# Beads Task Memory Skill
+
+This workspace uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent, structured task memory backed by [Dolt](https://github.com/dolthub/dolt). Tasks survive session restarts and can be shared across multiple bots via Dolt sync.
+


This file is named *.agent.md and uses agent frontmatter, which makes it an agent persona definition in copilot-bridge/Copilot conventions—not a skill. However the content repeatedly calls itself a “Skill” and the rest of the PR references it as a skill. Please either repackage it as a skill (e.g., skills/beads/SKILL.md) or adjust wording to “agent persona” and document how it should be used (when to /agent beads).

Suggested change

description: Persistent task tracking for this workspace using bd (Beads). Use this skill to create, track, and close tasks across sessions.

---

# Beads Task Memory Skill

This workspace uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent, structured task memory backed by [Dolt](https://github.com/dolthub/dolt). Tasks survive session restarts and can be shared across multiple bots via Dolt sync.

description: Persistent task tracking for this workspace using bd (Beads). Use this agent persona to create, track, and close tasks across sessions.

---

# Beads Task Memory Agent Persona

This workspace uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent, structured task memory backed by [Dolt](https://github.com/dolthub/dolt). Tasks survive session restarts and can be shared across multiple bots via Dolt sync.

## How to use this agent persona

Invoke this agent persona with `/agent beads` when you want the assistant to:

- recover or summarize workspace task context using Beads at the start of a session,

- create, update, or close Beads tasks via `bd` commands, or

- interpret `bd` output and decide what to work on next.

The rest of this document describes the workflows this agent persona should follow while operating.

Copilot · 2026-03-26T04:45:48Z

+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "./session-start.sh",
+        "cwd": ".",
+        "timeoutSec": 15
+      }
+    ],
+    "sessionEnd": [
+      {
+        "type": "command",
+        "bash": "./session-end.sh",
+        "cwd": ".",
+        "timeoutSec": 30
+      }
+    ]
+  }


The hook scripts rely on bd finding the workspace’s Beads state via env/cwd, but hooks run as separate processes spawned by the bridge and do not automatically inherit workspace .env vars. With cwd set to .github/hooks, bd may not find .beads/ unless BEADS_DIR is set explicitly for the hook command (via hooks.json env) or the script sets cwd/BEADS_DIR itself. Please adjust the example to be self-contained (e.g., run from workspace root and/or pass BEADS_DIR via hook env).

Copilot · 2026-03-26T04:45:48Z

+- **During work**: `bd create`, `bd update --claim`, `bd close` — see the `Beads Task Memory` skill for the full workflow
+- **Session end**: run `bd backup export-git` to snapshot progress to git
+
+Prefer `bd remember` over `MEMORY.md` for persistent knowledge when Beads is available. See `docs/beads.md` for setup instructions.


The new section refers to the “Beads Task Memory” skill, but the PR adds templates/agents/beads.agent.md (an agent persona template) and docs/beads.md currently instructs copying it into .github/agents/. This is likely to confuse users because skills are discovered from .github/skills/<name>/SKILL.md whereas .agent.md files define switchable agents. Please align the terminology and the referenced location so users can actually enable the intended mechanism.

Suggested change

- **During work**: `bd create`, `bd update --claim`, `bd close` — see the `Beads Task Memory` skill for the full workflow

- **Session end**: run `bd backup export-git` to snapshot progress to git

Prefer `bd remember` over `MEMORY.md` for persistent knowledge when Beads is available. See `docs/beads.md` for setup instructions.

- **During work**: `bd create`, `bd update --claim`, `bd close` — see the Beads documentation for the full workflow

- **Session end**: run `bd backup export-git` to snapshot progress to git

Prefer `bd remember` over `MEMORY.md` for persistent knowledge when Beads is available. See `docs/beads.md` for workspace setup and usage instructions.

- beads.agent.md: rename from 'Skill' to agent definition; add /agent beads usage instructions. *.agent.md files are agent personas, not skills. - docs/beads.md: remove PATH from .env (bridge does not expand shell vars in .env values — PATH=/foo:$PATH would be taken literally). Set PATH, BEADS_DIR, BEADS_ACTOR explicitly in hook scripts instead, since hooks run as separate processes that do not inherit workspace .env. - docs/beads.md: fix allowWorkspaceHooks location — must be under defaults (getConfig().defaults.allowWorkspaceHooks), not config top level. - docs/beads.md: add note that cwd in hooks.json is relative to baseDir. - templates/agents/AGENTS.md: replace 'Beads Task Memory skill' reference with '/agent beads' — correct mechanism for agent definition files. - config.sample.json: remove shell(bd) from default allow list (bd is state-mutating — writes to .beads/, may start Dolt server). Added as commented guidance so users opt in deliberately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

raykao · 2026-03-26T05:16:50Z

Addressed all review feedback (commit 04a828f):

Agent vs skill terminology — beads.agent.md is now correctly described as an agent definition (invoke with /agent beads). Removed all 'skill' references from docs and AGENTS.md template.
PATH in .env — removed. Bridge does not expand shell vars in .env. PATH, BEADS_DIR, and BEADS_ACTOR now set explicitly inside hook scripts (hooks run as separate processes, don't inherit .env).
allowWorkspaceHooks location — docs now show it under defaults, not top-level.
cwd note — added explicit note that cwd is relative to baseDir (the hooks.json directory).
shell(bd) in config.sample.json — removed from default allow list, added as a commented opt-in with explanation that bd is state-mutating.

Copilot AI review requested due to automatic review settings March 26, 2026 04:00

Copilot started reviewing on behalf of raykao March 26, 2026 04:01 View session

raykao mentioned this pull request Mar 26, 2026

feat: Add Beads (bd) integration for persistent agent memory via CLI skill and session hooks #157

Open

7 tasks

Copilot AI reviewed Mar 26, 2026

View reviewed changes

raykao and others added 2 commits March 26, 2026 00:28

Copilot AI review requested due to automatic review settings March 26, 2026 04:41

Copilot started reviewing on behalf of raykao March 26, 2026 04:41 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

	- During work: `bd create`, `bd update --claim`, `bd close` — see the `Beads Task Memory` skill for the full workflow
	- During work: `bd create`, `bd update --claim`, `bd close` — see the `beads` agent definition for the full workflow

-description: Persistent task tracking for this workspace using bd (Beads). Use this skill to create, track, and close tasks across sessions.
----
-# Beads Task Memory Skill
-This workspace uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent, structured task memory backed by [Dolt](https://github.com/dolthub/dolt). Tasks survive session restarts and can be shared across multiple bots via Dolt sync.
+description: Persistent task tracking for this workspace using bd (Beads). Use this agent persona to create, track, and close tasks across sessions.
+---
+# Beads Task Memory Agent Persona
+This workspace uses [Beads](https://github.com/steveyegge/beads) (`bd`) for persistent, structured task memory backed by [Dolt](https://github.com/dolthub/dolt). Tasks survive session restarts and can be shared across multiple bots via Dolt sync.
+## How to use this agent persona
+Invoke this agent persona with `/agent beads` when you want the assistant to:
+- recover or summarize workspace task context using Beads at the start of a session,
+- create, update, or close Beads tasks via `bd` commands, or
+- interpret `bd` output and decide what to work on next.
+The rest of this document describes the workflows this agent persona should follow while operating.

Conversation

raykao commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

No Breaking Changes

Relationship to PR #158

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

raykao commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

raykao commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

raykao commented Mar 26, 2026 •

edited

Loading