Beads

# ADR-0001: Use bd prime as CLI Reference Source of Truth

## Status

Accepted

## Context

The beads skill maintained CLI reference documentation in multiple locations:

- `SKILL.md` inline (~2,000+ words of CLI reference)
- `references/CLI_REFERENCE.md` (~2,363 words)
- Scattered examples throughout resource files

This created:
- **Duplication**: Same commands documented 2-3 times
- **Drift risk**: Documentation can fall behind bd versions
- **Token overhead**: ~3,000+ tokens loaded even for simple operations

Meanwhile, bd provides `bd prime` which generates AI-optimized workflow context automatically.

## Decision

Use `bd prime` as the single source of truth for CLI commands:

1. **SKILL.md** contains only value-add content (decision frameworks, cognitive patterns)
2. **CLI reference** points to `bd prime` (auto-loaded by hooks) and `bd --help`
3. **Resources** provide depth for advanced features (molecules, agents, gates)

## Consequences

### Positive

- **Zero maintenance**: CLI docs auto-update with bd versions
- **DRY**: Single source of truth
- **Accurate**: No version drift possible
- **Lighter SKILL.md**: ~500 words vs ~3,300

### Negative

- **Dependency on bd prime format**: If output changes significantly, may need adaptation
- **External tool requirement**: Skill assumes bd is installed

## Implementation

Files restructured:
- `SKILL.md` — Reduced from 3,306 to ~500 words
- `references/` → `resources/` — Directory rename for consistency
- New resources added: `agents.md`, `async-gates.md`, `chemistry-patterns.md`, `worktrees.md`
- Existing resources preserved with path updates

## Related

- Claude Code skill progressive disclosure guidelines
- Similar pattern implemented in other Claude Code skill ecosystems

## Date

2025-01-02


interface:
  display_name: "Beads"
  short_description: "Project task tracking with bd"
  default_prompt: "Use $beads to inspect ready work and manage durable project tasks."


# Beads Skill Maintenance Guide

## Architecture Decisions

ADRs in `adr/` document key decisions. These are NOT loaded during skill invocation—they're reference material for maintainers making changes.

| ADR | Decision |
|-----|----------|
| [ADR-0001](adr/0001-bd-prime-as-source-of-truth.md) | Use `bd prime` as CLI reference source of truth |

## Key Principle: DRY via bd prime

**NEVER duplicate CLI documentation in SKILL.md or resources.**

- `bd prime` outputs AI-optimized workflow context
- `bd <command> --help` provides specific usage
- Both auto-update with bd releases

**SKILL.md should only contain:**
- Decision frameworks (bd vs TodoWrite)
- Prerequisites (install verification)
- Resource index (progressive disclosure)
- Pointers to `bd prime` and `--help`

## Keeping the Skill Updated

### When bd releases new version:

1. **Check for new features**: `bd --help` for new commands
2. **Update SKILL.md frontmatter**: `version: "X.Y.Z"`
3. **Add resources for conceptual features** (agents, gates, chemistry patterns)
4. **Don't add CLI reference** — that's `bd prime`'s job

### What belongs in resources:

| Content Type | Belongs in Resources? | Why |
|--------------|----------------------|-----|
| Conceptual frameworks | ✅ Yes | bd prime doesn't explain "when to use" |
| Decision trees | ✅ Yes | Cognitive guidance, not CLI reference |
| Advanced patterns | ✅ Yes | Depth beyond `--help` |
| CLI command syntax | ❌ No | Use `bd <cmd> --help` |
| Workflow checklists | ❌ No | `bd prime` covers this |

### Resource update checklist:

```
[ ] Check if bd prime now covers this content
[ ] If yes, remove from resources (avoid duplication)
[ ] If no, update resource for new bd version
[ ] Update version compatibility in README.md
```

## File Roles

| File | Purpose | When to Update |
|------|---------|----------------|
| SKILL.md | Entry point, resource index | New features, version bumps |
| README.md | Human docs, installation | Structure changes |
| CLAUDE.md | This file, maintenance guide | Architecture