name: issues-beads-prime description: Minimal quick reference for beads commands when context is constrained.

Beads quick reference

Symlink location: ~/.claude/skills/issues-beads-prime/SKILL.md Slash command: /issues:beads-prime

Minimal quick reference when context is constrained. For session lifecycle, prefer /session-orient (start) and /session-checkpoint (wind-down). In repos without the full workflow, use /issues:beads-orient and /issues:beads-checkpoint directly. For comprehensive reference: /issues:beads (complete workflows, concepts, and operations).

This module serves as the common conventions and quick-reference layer that other beads skills reference for core context. In particular, orient loads prime as a conventions preamble before performing session diagnostics. All beads-related skills should treat the conventions defined here as authoritative.

Command index

• beads-init - Initial setup for beads issue tracking
• beads-seed - Generate issues from architecture documentation
• beads-orient - Session start diagnostics and work selection
• beads-evolve - Issue graph refactoring patterns
• beads-checkpoint - Session wind-down and handoff prep
• beads-audit - Database health check and validation

Conventions

Epic structure

• Single-layer parent-child only: epics contain issues, not sub-epics. Do not create nested epics without explicit human request.
• Use --type parent-child when wiring parent-child relationships via bd dep add. Do not use --type parent or --type child-of — beads silently accepts both but neither is recognized for epic tracking. The only valid containment type is parent-child.
• Every issue should be a child of an epic. Standalone orphan issues are discouraged.
• Create children with bd create "title" --parent <epic-id> for auto-incrementing hierarchical IDs, or create standalone and wire with bd dep add <child> <epic> --type parent-child.

Dependency type discipline

Two dependency types serve fundamentally different purposes and must never be conflated.

Containment (issue belongs to an epic) uses parent-child type exclusively. Establish at creation via bd create "title" --parent <epic-id>, or post-hoc via bd dep add <child> <epic> --type parent-child. Every non-epic issue must have exactly one parent-child relationship to an epic. An epic does not "block" its children — children are ready to work as soon as their sibling and cross-epic dependencies allow.

Sequencing (A must complete before B can start) uses blocks type, the default. Establish via bd dep add <blocked> <blocker> between siblings, across epics, or between epics themselves.

The antipattern to avoid: wiring an issue as "blocked by" its containing epic instead of as a "child of" that epic. This causes bd epic status to report 0 children for the epic and makes the issue appear blocked when it should be ready.

When an issue relates to multiple epics, use parent-child for the primary and related for secondary associations. An issue can have at most one parent-child relationship.

Valid dependency types: blocks, tracks, related, parent-child, discovered-from, until, caused-by, validates, relates-to, supersedes. Any other value is silently accepted but functionally broken.

Verification after bulk operations:

# Any epic showing 0/0 children that has BLOCKS deps to non-epic issues has the antipattern
bd epic status

If bd epic status shows 0/0 children for an epic known to contain issues, the containment relationships were likely wired as blocks instead of parent-child.

Status management

• When starting work on an issue, mark it in_progress: bd update <id> --status in_progress
• When starting work on any issue under an epic, also mark the parent epic in_progress if not already.
• Use bd update <id> --status in_progress before beginning implementation, not after.

Closure policy

• LLMs and subagent Tasks can close individual issues automatically: bd close <id> --reason "Implemented in $(git rev-parse --short HEAD)"
• Never close epics without explicit human request. Epics whose children are all closed are intentionally kept open for human validation, follow-up issue creation, and iterative refinement. This is a normal steady-state, not an action item. Do not prompt, offer, or suggest closing eligible epics during orientation, checkpoint, or any other workflow phase. The human will request epic closure when ready, at which point bd epic close-eligible --dry-run can confirm readiness.
• After closing issues, check whether additional follow-up issues are needed. Use bd close <id> --suggest-next to see newly unblocked work.

Working branch workflow

Bead implementation work uses isolated working branches; non-bead work uses plain branches. Branch naming follows the {ID}-descriptor pattern in lowercase kebab-case, with dots in bead IDs replaced by dashes. Default granularity is per-issue; use epic-level branches only when the orchestrator explicitly specifies.

Create a working branch for the issue following the branch naming pattern {ID}-descriptor. See the "Working branch isolation" section of git-preferences for mode-specific commands (git worktree add in git-native mode, but branch new in GitButler mode, or jj bookmark create in jj mode).

The subagent creates the working branch as its first action before any implementation work begins. For non-bead or quick-fix work, use a plain branch instead of the full isolation workflow.

In git-native mode with worktrees, initialize the direnv environment before hook-triggering operations. This does not apply in GitButler mode or jj mode (both operate in a single working tree).

In jj mode, when working across multiple epics simultaneously, the orchestrator creates a multi-parent @ (development join) via jj new epic-a epic-b and routes changes to the correct epic bookmark via jj absorb or jj squash --into after subagent completion. See the "Subagent dispatch in jj mode" subsection of git-preferences for the full routing workflow.

All agents (including parallel agents) share the same @ working copy. Coordination protocol: atomic one-file changes, periodic jj log review, prompt absorb/squash to keep @ clean. jj absorb works when modifying files with blame history in a specific chain (it routes changes to the ancestor that last touched each line). Fall back to jj squash --into <chain> for new files or when blame ancestry is ambiguous (e.g. file touched by multiple chains). See the multi-parent composite workflow in ~/.claude/skills/jj-version-control/SKILL.md for the full edit-route cycle.

In jj mode, bookmarks are created at chain differentiation, not before the first edit. A single anonymous chain needs no bookmark. Create bookmarks when initiating a second chain or when working on beads epics. See bookmark creation threshold in ~/.claude/skills/jj-version-control/SKILL.md.

Dispatch clarity:

• When dispatching subagent Tasks, the prompt must specify the working context: worktree path (git-native), GitButler branch name, or jj bookmark name.
• In jj mode, subagents edit files directly in the shared @ working copy; the orchestrator routes changes to the correct bookmark post-hoc.
• Subagents working on the same issue share a working context.
• Subagents working on different issues get different working contexts.
• If a dispatch prompt does not mention a working context, the subagent should ask rather than assuming.

When issue work is complete, integrate the working branch back to the parent branch and clean up. See git-preferences for the mode-specific integration and cleanup procedure.

All merges to main must be fast-forward. See the "Fast-forward-only merge policy" section of git-preferences for enforcement details.

Dolt persistence

Beads mutations auto-commit to the dolt database when dolt.auto-commit is enabled (the default after migration). After a batch of mutations, push to the dolt remote for backup:

bd dolt push

For explicit checkpoint labels:

bd dolt commit -m "checkpoint: <description>"
bd dolt push

Additional dolt operations:

bd dolt pull                     # Pull from dolt remote
bd dolt status                   # Check dolt server status
bd dolt remote add <name> <url>  # Dual-surface remote management
bd dolt remote list              # Show remotes with surface status
bd history <id>                  # View version history for an issue (requires running Dolt server)
bd backup                        # Manual JSONL export (auto-backup disabled)
bd backup restore [path]         # Restore from JSONL backup
bd doctor --agent                # AI-agent diagnostics

Port is set by the BEADS_DOLT_SERVER_PORT environment variable, managed via home-manager. Do not set dolt_server_port in .beads/metadata.json as this breaks fork auto-start behavior.

Orient

bd status                   # quick human-readable summary (~20 lines)
bd epic status              # epic progress
bd ready | head -1          # top ready-to-work issue

Select work

# Top ready-to-work issues (priority-sorted, no blockers)
bd ready

# Show blocked issues
bd blocked

# Full dependency context (upstream + downstream)
bd dep tree <id> --direction both

# Issue details
bd show <id>

During work

# Create discovered issue (priority: 0=highest, 4=lowest, default=2)
bd create "Found: ..." -t bug -p 2
bd dep add <new-id> <current-id> --type discovered-from

# Add blocker to current issue
bd create "Need X first" -t task -p 1
bd dep add <current-id> <blocker-id>

Complete work

bd close <id> --reason "Implemented in commit $(git rev-parse --short HEAD)"
bd epic close-eligible --dry-run  # on-demand only, when user requests epic closure review

Health

bd dep cycles               # must be zero
bd doctor                   # check and fix installation health
bd lint                     # check issues for missing template sections

Key patterns

• bd status for quick summary, bd ready for actionable work, bd blocked for bottlenecks
• bd dep tree <id> --direction both shows full context (blockers + what completing it unblocks)
• Always close with --reason referencing the implementation
• Use --type discovered-from when creating issues found during other work
• After bd modifications, push to the dolt remote for backup: bd dolt push