development

name	development
description	AllBeads development process. Use when planning features, creating documentation, tracking work with beads, or understanding the documentation system.
allowed-tools	Read, Edit, Write, Bash, Grep, Glob, Task, EnterPlanMode, ExitPlanMode, AskUserQuestion, TodoWrite

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

```rust
// 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:

1. Code complete - Implementation is done, tests pass
2. Commit code - Create git commit(s)
3. Wait for user - DO NOT close issues yet
4. User tests - Let user test the implementation
5. User pushes - User pushes code to remote
6. 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