Enhance bd setup opencode with skill file support
Context
bd setup opencode ships with bd v1.0.0. It writes a workflow block to
AGENTS.md covering the basic loop: ready, claim, work, close, push.
Output of bd setup opencode --print today:
# Core Rules
- Track ALL work in bd (never use markdown TODOs or comment-based task lists)
- Use `bd ready` to find available work
- Use `bd create` to track new issues/tasks/bugs
- Use `bd dolt push` at end of session to sync with remote
- Run `bd prime` for complete workflow context (SSOT for operational commands)
This covers single-agent usage. It does not address multi-agent systems
where an orchestrator delegates to specialized subagents.
Problem
OpenCode supports multi-agent systems natively. A primary agent spawns
subagents via the task tool. Each subagent runs independently.
In these setups, AGENTS.md is read by every agent. The current recipe
tells "the agent" to use bd. That means every subagent may call bd,
causing duplicate claims on bd update --claim and confusion about
which agent owns which task.
The fix: put task-tracking instructions in a skill file instead of
AGENTS.md. OpenCode skills live in SKILL.md files loaded on-demand
via the skill tool. Only the orchestrator agent loads the beads skill.
Worker agents never see it.
Proposed change
Add a --skill flag to bd setup opencode:
bd setup opencode # Current behavior, unchanged
bd setup opencode --skill # Also creates .opencode/skills/beads/SKILL.md
The skill file would:
- Reference
bd prime as the command source of truth (per ADR-0001)
- Define the task-agent loop:
ready -> show -> claim -> work -> close
- State that only the agent loading this skill should call
bd
- Document delegation: create task before spawning subagent, close on return
- Cover
discovered-from for tracking work found during execution
- Document the boundary between
bd (persistent) and session-scoped checklists
Skill file location
OpenCode searches for skills in this order (per opencode.ai/docs/skills):
.opencode/skills/<name>/SKILL.md (project)
~/.config/opencode/skills/<name>/SKILL.md (global)
So bd setup opencode --skill would write to .opencode/skills/beads/SKILL.md.
Skill frontmatter
Per OpenCode docs, recognized fields are name, description, license,
compatibility, and metadata. Example:
---
name: beads
description: >
Dolt-powered issue tracker. Canonical task-agent loop, delegation
patterns, session close protocol. Load for multi-session task tracking.
license: MIT
---
What stays in AGENTS.md
The existing bd setup opencode output remains unchanged. It provides
universal rules (use bd, not markdown TODOs) that all agents should follow.
The skill adds orchestrator-specific patterns that only one agent needs.
Scope
- Extends the existing
opencode recipe only
- No changes to
claude, junie, cursor, or other recipes
- No new
integrations/ directory needed
Sources
Enhance
bd setup opencodewith skill file supportContext
bd setup opencodeships with bd v1.0.0. It writes a workflow block toAGENTS.md covering the basic loop:
ready,claim,work,close,push.Output of
bd setup opencode --printtoday:This covers single-agent usage. It does not address multi-agent systems
where an orchestrator delegates to specialized subagents.
Problem
OpenCode supports multi-agent systems natively. A primary agent spawns
subagents via the
tasktool. Each subagent runs independently.In these setups, AGENTS.md is read by every agent. The current recipe
tells "the agent" to use
bd. That means every subagent may callbd,causing duplicate claims on
bd update --claimand confusion aboutwhich agent owns which task.
The fix: put task-tracking instructions in a skill file instead of
AGENTS.md. OpenCode skills live in
SKILL.mdfiles loaded on-demandvia the
skilltool. Only the orchestrator agent loads the beads skill.Worker agents never see it.
Proposed change
Add a
--skillflag tobd setup opencode:The skill file would:
bd primeas the command source of truth (per ADR-0001)ready->show->claim-> work ->closebddiscovered-fromfor tracking work found during executionbd(persistent) and session-scoped checklistsSkill file location
OpenCode searches for skills in this order (per opencode.ai/docs/skills):
So
bd setup opencode --skillwould write to.opencode/skills/beads/SKILL.md.Skill frontmatter
Per OpenCode docs, recognized fields are
name,description,license,compatibility, andmetadata. Example:What stays in AGENTS.md
The existing
bd setup opencodeoutput remains unchanged. It providesuniversal rules (use bd, not markdown TODOs) that all agents should follow.
The skill adds orchestrator-specific patterns that only one agent needs.
Scope
opencoderecipe onlyclaude,junie,cursor, or other recipesintegrations/directory neededSources
bd setup --listconfirmsopencoderecipe exists (bd v1.0.0)bd setup opencode --printshows current template