AllBeads Development Process Skill

Use this skill when planning features, creating documentation, tracking work with beads, or understanding how the documentation system works.

Quick Reference

Specs: specs/PRD-00.md

• Core architecture specification Issues: .beads/
• Git-tracked issue database Plans: plans/
• Preserved plan history (git-tracked)

The 5-Style Documentation System

AllBeads uses 5 distinct doc types, each with a specific purpose:

Style Purpose Location Update Trigger

1. Plan Mode Deep exploration before coding plans/

Per feature

2. Beads Issues Track work across sessions .beads/

Throughout feature

3. Evergreen Specs System truth ("how it works") specs/

Architecture changes

4. Skills Agent guides ("how to implement") .claude/skills/

Pattern changes

5. User Docs Human communication README, CLAUDE.md Major features

Workflow: From Idea to Code

Step 1: Enter Plan Mode

For any non-trivial feature:

1. Use EnterPlanMode tool
2. Launch Explore agents to understand existing patterns
3. Read relevant specs (specs/PRD-00.md, specs/SPEC-*.md, etc.)
4. Ask clarifying questions via AskUserQuestion
5. Design implementation approach
6. Write plan to plan file
7. Exit plan mode with ExitPlanMode for approval
8. Copy approved plan to plans/ directory (see naming below)

Plan file naming: plans/YYYY-MM-DD-feature-name.md

Example: plans/2026-01-15-external-plugins.md

Plans are preserved even if abandoned - they document design decisions and exploration history.

Step 2: Create Beads Issues

After plan approval:

Create feature epic

bd create --title="Feature X" --type=feature --priority=2

Break into tasks

bd create --title="Implement X logic" --type=task --priority=2 bd create --title="Add X tests" --type=task --priority=2

Set dependencies

bd dep add <task-id> <feature-id> # Task depends on feature

Claim work

bd update <id> --status=in_progress

Step 3: Implementation

During coding:

1. Read skills for "how to" guidance
2. Reference specs for architecture
3. Update beads (bd update <id> --status=in_progress)
4. Write code already formatted and linted (cargo fmt, cargo clippy)
5. Follow patterns from specs + skills
6. Run tests frequently (cargo test)

Step 4: Update Specs & Skills (if architecture changed)

• Specs: Declarative ("the Sheriff daemon syncs repos like this")
• Skills: Prescriptive ("implement a new sync adapter like this")

Step 5: Complete

Verify quality gates

cargo fmt -- --check && cargo clippy -- -D warnings && cargo test

Commit code

git add . git commit -m "Implement Feature X"

Sync beads

bd sync

DO NOT close issues (user does after testing/pushing)

DO NOT push to remote (user does)

Decision Framework

Situation Action

Starting new feature Enter plan mode

Feature spans sessions Create beads issue

New architectural pattern Update spec in specs/

New implementation pattern Update skill in .claude/skills/

Public-facing change Update README.md

Agent guidance needed Update CLAUDE.md

Plan Preservation

Plans are git-tracked in plans/ to preserve institutional memory:

• Approved plans - Document the "why" behind implementations

• Abandoned plans - Show alternatives considered and why they were rejected

• Partial plans - Capture exploration that may be revisited later

Plans complement beads issues: beads track what work was done, plans track how decisions were made.

When to save a plan:

• After plan approval (before implementation)

• When abandoning a plan (add note explaining why)

• When significantly revising approach mid-implementation

Specs vs Skills

Specs say WHAT (evergreen truth):

Sheriff Daemon Architecture

The Sheriff polls all registered Rigs for bead updates. Shadow Beads MUST contain a pointer URI to the source bead.

Skills say HOW (implementation guide):

Adding a New Integration

// Implement the Adapter trait
impl Adapter for JiraAdapter {
    async fn sync(&self) -> Result<Vec<ShadowBead>> {
        // Use ShadowBead::external() builder
        let shadow = ShadowBead::external(id, summary, uri)
            .with_status("open")
            .build();
        // ...
    }
}

Beads Essentials

Finding Work

bd ready # Show issues ready to work (no blockers) bd list --status=open # All open issues bd blocked # Show blocked issues bd show <id> # View issue details

Managing Work

bd update <id> --status=in_progress # Claim work bd close <id> # Mark complete (ONLY after user tests) bd sync # Sync with git remote

Dependencies

bd dep add <issue> <depends-on> # Add dependency

Quality Gates

AllBeads requires ALL THREE to pass before commits:

cargo fmt -- --check # Code formatting cargo clippy -- -D warnings # Linting cargo test # Tests

Run all three with:

cargo fmt -- --check && cargo clippy -- -D warnings && cargo test

Anti-Patterns

DON'T:

• Write RFC-style docs that get stale ("We plan to add X")

• Document temporary decisions in specs (use issues)

• Put implementation details in specs (use skills)

• Put architectural constraints in skills (use specs)

• Close beads issues before user tests and pushes

• Push to remote without user approval

• Skip quality gates (fmt, clippy, test)

DO:

• Use plan mode for all non-trivial features

• Save plans to plans/ directory after approval (or abandonment)

• Keep specs declarative and evergreen

• Keep skills prescriptive and code-focused

• Track multi-session work in beads

• Update specs/skills when patterns change

• Write formatted, linted code from the start

• Run cargo test frequently during development

Issue Lifecycle Rules

CRITICAL: Follow this order:

• Code complete - Implementation is done, tests pass

• Commit code - Create git commit(s)

• Wait for user - DO NOT close issues yet

• User tests - Let user test the implementation

• User pushes - User pushes code to remote

• Then close issues - Only close after code is pushed and tested

Epics should only be closed after:

• All child issues are closed

• The feature has been tested by user

• The code has been pushed to remote

Key Specs Reference

Spec Purpose

specs/PRD-00.md

Core architecture (Sheriff, Boss Board, Federated Graph)

specs/PRD-01-context-onboarding.md

Context and onboarding flows

specs/SPEC-handoff.md

Agent handoff patterns

specs/SPEC-governance.md

Issue governance model

specs/SPEC-aiki-integration.md

Aiki integration spec