beadsmith

CLI tool for AI-first development environments. Skills and commands are bundled at compile time and installed via beadsmith init.

Plan-to-Bead Workflow

Beadsmith supports a complete workflow from high-level planning to autonomous execution:

/beads SEED → branch → org-mode → context → plan → validate → harness
                                                                  │
                              ←────── complete-to-org ────────────┘

Architectural principle: Org-mode is the canonical planning layer. The /beads command integrates with org-mode automatically.

Quick Start

# Install beadsmith
cargo install --path crates/beadsmith

# Initialize project (installs skills and commands)
beadsmith init

# PRIMARY WORKFLOW: Plan, validate, and prepare for execution
/beads "Add user authentication with JWT tokens"

# Execute (after validation passes)
beads-harness <epic-id>

The /beads command handles everything: creates a feature branch, integrates with org-mode, detects work type, acquires context, plans the work, validates the plan, and outputs the harness command.

Bundled Skills

24 skills bundled at compile time:

Skill	Purpose
research	Multi-source research methodology with source evaluation and synthesis
skill-compiler	Transform input.yaml specifications into versioned SKILL.md files
autonomous-testing	Use Puppeteer/Playwright automation instead of asking humans to verify
iterative-debugging	Systematic fix-verify-iterate cycles with hypothesis-driven debugging
human-gating-antipattern	Recognize and avoid using humans as button-clicking proxies
agents-md	Create and optimize AGENTS.md files for AI coding agents
transmission	Lossless agent-to-agent communication across context boundaries
codebase-exploration	Systematic codebase survey methodology
iterative-planning-context	Acquire codebase context for planning iterative changes
org-planning	Agent-accessible project planning via org-mode
spawn-readiness	Validate org task is ready for delegation to beads
spawn-to-beads	Delegate org-mode tasks to beads execution layer
complete-to-org	Callback when bead epic completes to update org-mode
beads-plan	Transform specifications into executable beads dependency graphs
beads-execute	Execute beads tasks with proper claim/work/close workflow
bdd-scenario-design	Transform acceptance criteria into Gherkin scenarios
bdd-step-implementation	Write rstest-bdd step definitions wired to fixtures
bdd-red-green-refactor	Guide TDD inner loop: red, green, refactor
bdd-scenario-evolution	Evolve scenarios as requirements change
validate-pipeline	Orchestrate validation steps before closing beads
fixture-validate	Validate fixture registry integrity
epic-validation	Epic-level quality gate after 100% completion
decision-audit	Record quality trade-offs and decisions
coherence-audit	Systematic audits when discrepancies reveal systemic issues

See each skill's SKILL.md in skills/<name>/ for detailed usage and triggers.

Installation

cargo install --path crates/beadsmith

Usage

# Initialize a project with all skills and commands
beadsmith init

# Initialize with specific skills only
beadsmith init --skills research,skill-compiler

# Initialize without installing commands (manual setup)
beadsmith init --skip-commands

# Check installation and list available skills
beadsmith doctor

# Dry run - see what would be created
beadsmith init --dry-run

OpenCode Commands

Commands are installed automatically by beadsmith init to ~/.config/opencode/commands/.

Primary Interface

Command	Purpose
/beads	Unified entry point - branch, plan, validate, prepare for execution

Advanced Commands

For power users who need direct access to pipeline stages:

Command	Purpose
/beads-plan	Direct planning without branch/validation (used internally by /beads)
/beads-loop	Execution loop (used internally by harness)
/beads-start	Manual session start
/beads-land	Manual session end - sync, push, handoff
/spawn-readiness	Validate org task is ready for delegation

Skip command installation: Use beadsmith init --skip-commands if you want to manage commands manually.

Beads Harness

The harness script (scripts/beads-harness.sh) orchestrates autonomous bead execution across context windows:

# Execute epic autonomously
beads-harness <epic-id>

# With options
beads-harness --project /path/to/project --model anthropic/claude-sonnet-4 <epic-id>

# View statistics
beads-harness --stats

Features:

• Server lifecycle management
• Continuation loop for context exhaustion
• Statistics tracking (beads/hour, run history)
• Multi-project support via port hashing

Setup: Symlink scripts/beads-harness.sh to ~/.local/bin/beads-harness

Architecture

Skills and commands are source files that get compiled INTO the binary via Rust's include_str!(). When you run beadsmith init:

• Skills are extracted to .opencode/skill/ in your project
• Commands are installed to ~/.config/opencode/commands/ (user-global)

Directory Ownership

Directory	Owner	Purpose
.beads/	bd CLI	Beads database, sync state
.beadsmith/	Harness	Logs, stats, context files
.opencode/skill/	Beadsmith	Installed skills

beadsmith/
├── crates/beadsmith/     # CLI binary
├── skills/               # Skill source files (24 skills)
│   ├── research/
│   │   ├── input.yaml    # Declarative specification
│   │   └── SKILL.md      # Compiled skill
│   └── ...
├── commands/             # OpenCode slash commands (6 commands)
│   ├── beads.md          # Primary interface - unified workflow
│   ├── beads-loop.md
│   ├── beads-plan.md
│   ├── beads-start.md
│   ├── beads-land.md
│   └── spawn-readiness.md
└── scripts/              # Automation scripts
    └── beads-harness.sh  # Autonomous execution orchestrator

Why bundle skills and commands?

Coherence: Skills, commands, and CLI version together. No compatibility matrix. One install = complete toolset.

Skill Structure

Each skill has:

• input.yaml - Declarative specification (the source of truth)
• SKILL.md - Compiled skill output

When the skill-compiler improves, skills can be regenerated from their input artifacts.

Development

# Build
cargo build

# Test
cargo test

# Run locally
cargo run -- doctor
cargo run -- init --dry-run

License

MIT