Files

Peter Chanthamynavong 025142d55e docs(skill): restructure for progressive disclosure pattern (#857 )

Align beads skill with Claude Code best practices:

- Restructure SKILL.md from 3,306 to ~510 words (85% reduction)
- Use bd prime as CLI reference source of truth (DRY)
- Rename references/ to resources/ per Claude Code conventions
- Add v0.43.0 feature documentation (agents, gates, worktrees)
- Add ADR-0001 documenting the bd prime decision
- Add CLAUDE.md maintenance guide

New resources:
- agents.md - Agent bead tracking
- async-gates.md - Human-in-the-loop gates
- chemistry-patterns.md - Mol vs Wisp decision tree
- worktrees.md - Parallel development patterns

BREAKING: references/ path changed to resources/

Fixes #855

2026-01-02 12:39:45 -08:00

2.6 KiB

Raw Blame History

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	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:

Check for new features: bd --help for new commands
Update SKILL.md frontmatter: version: "X.Y.Z"
Add resources for conceptual features (agents, gates, chemistry patterns)
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 changes
adr/*.md	Decision records	When making architectural decisions
resources/*.md	Deep-dive guides	New conceptual content

Testing Changes

After skill updates:

# Verify SKILL.md is within token budget
wc -w skills/beads/SKILL.md  # Target: 400-600 words

# Verify links resolve
# (Manual check: ensure all resource links in SKILL.md exist)

# Verify bd prime still works
bd prime | head -20

Attribution

Resources adapted from other sources should include attribution header:

# Resource Title

> Adapted from [source]

2.6 KiB Raw Blame History