Skip to content

Enhance bd setup opencode with skill file support #3145

@nickveenhof

Description

@nickveenhof

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:

  1. Reference bd prime as the command source of truth (per ADR-0001)
  2. Define the task-agent loop: ready -> show -> claim -> work -> close
  3. State that only the agent loading this skill should call bd
  4. Document delegation: create task before spawning subagent, close on return
  5. Cover discovered-from for tracking work found during execution
  6. 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions