Workflows

Beads supports different workflow modes to handle various collaboration scenarios, from solo local work to multi-contributor open-source projects.

Workflow Modes Overview

Mode	Use Case	Beads Location	Git Integration
Standard	Default mode	`.beads/` (committed)	Full git integration
Stealth	Local-only work	`.beads/` (gitignored)	No git integration
Contributor	Fork with planning	`~/.beads-planning/`	Redirected storage
Maintainer	Repo with write access	`.beads/` (committed)	Full git integration

Standard Mode

The default mode for most projects:

bd init

When to Use

Solo projects or small teams

Issues should be versioned with code

Everyone has write access to the repo

Characteristics

.beads/ directory is committed to git
Issues sync via Dolt push/pull
Full git integration (hooks, branches)
Issues visible to all collaborators

Stealth Mode

Local-only work without committing files to the main repo:

bd init --stealth

When to Use

Personal task tracking on shared projects

Don’t want to clutter repo with issue tracking

Experimenting with beads before team adoption

Contributing to projects that don’t use beads

Characteristics

.beads/ added to .gitignore automatically
Database stays local (no push/pull)
No git hooks or integration
Perfect for personal use

Stealth mode is ideal for trying beads on existing projects without affecting other team members.

Example: Personal Task Tracking

# Clone a project
git clone https://github.com/company/project
cd project

# Initialize stealth mode
bd init --stealth

# Track your personal work
bd create "Understand auth flow" -p 1
bd create "Fix bug in validator" -p 0
bd create "Refactor tests" -p 2

# Git status shows no beads files
git status  # Clean working directory

Contributor Mode

Fork workflow that routes planning issues to a separate repo:

bd init --contributor

When to Use

Contributing to open-source projects

Working on a fork without write access

Want to use beads for planning without affecting PR

How It Works

Characteristics

Issues stored in ~/.beads-planning/
.beads/ directory not created in repo
PRs remain clean (no beads files)
Full issue tracking for your planning

Example: Contributing to Open Source

Fork and clone

git clone https://github.com/you/some-project
cd some-project

Initialize contributor mode

bd init --contributor
# Storage redirected to ~/.beads-planning/you-some-project/

Track your work

bd create "Fix issue #123" -p 1
bd create "Add tests for new feature" -p 1
bd dep add tests fix

bd ready  # See your planned work

Submit clean PR

git add .
git status  # No .beads/ files!
git commit -m "Fix issue #123"
git push origin feature-branch
# PR is clean, no beads files included

Contributor mode keeps your planning private. If you want to share issues with maintainers, use standard mode instead.

Maintainer Mode

For repositories where you have write access:

# Beads auto-detects maintainer role via SSH URLs
git clone [email protected]:you/project.git
bd init  # Automatically uses maintainer mode

When to Use

You have write access to the repository

Team uses beads for issue tracking

Issues should be shared with all contributors

Characteristics

Same as standard mode
Auto-detected via SSH URLs or HTTPS with credentials
Issues committed to repo
Full Dolt sync capabilities

Maintainer mode is usually auto-detected. Only configure manually if using HTTPS without credentials.

Switching Between Modes

Stealth → Standard

# Move from local-only to committed
rm .gitignore  # Remove beads exclusion
git add .beads/
git commit -m "Add beads tracking"
bd dolt push  # Enable sync

Standard → Stealth

# Move to local-only
echo ".beads/" >> .gitignore
git rm -r --cached .beads/
git commit -m "Remove beads from version control"

Contributor → Standard

# Stop redirection, use local storage
rm .beads/metadata.json  # Remove redirect config
bd init  # Re-initialize as standard
# Manually import from ~/.beads-planning/ if needed

Hierarchical IDs

All modes support hierarchical IDs for organizing work:

bd-a3f8       (Epic)
├── bd-a3f8.1     (Task)
│   ├── bd-a3f8.1.1 (Sub-task)
│   └── bd-a3f8.1.2 (Sub-task)
└── bd-a3f8.2     (Task)

bd create "Auth System" -t epic
# Returns: bd-a3f8

bd create "OAuth flow" --parent bd-a3f8
# Returns: bd-a3f8.1

bd create "Session management" --parent bd-a3f8
# Returns: bd-a3f8.2

Agent Workflows

Beads is optimized for AI-supervised coding workflows:

Standard Agent Flow

Find ready work

bd ready --json

Shows issues with no open blockers

Claim atomically

bd update <id> --claim --json

Sets assignee + status=in_progress in one operation

Work on it

Implement, test, document the feature or fix

Discover new work

bd create "Found bug" -t bug -p 1 \
  --deps discovered-from:<parent-id> --json

Link discovered work back to parent

Complete

bd close <id> --reason "Completed" --json

Check unblocked

bd ready --json

See what became available

Agent Memory with `bd prime`

bd prime outputs essential workflow context for AI agents:

bd prime

Designed for Claude Code hooks (SessionStart, PreCompact) to prevent agents from forgetting bd workflow after context compaction.

Customizing prime output

Place a .beads/PRIME.md file to override default output:

# Export default for customization
bd prime --export > .beads/PRIME.md

# Edit to your preferences
vim .beads/PRIME.md

# Future bd prime calls use your custom version
bd prime

Session Completion Protocol

When ending an agent session:

File remaining work

bd create "Follow-up task" -t task -p 2 --json

Run quality gates

make test
make lint

Update issue status

bd close <id> --reason "Completed" --json

Push to remote (MANDATORY)

git pull --rebase
git push
git status  # Must show "up to date with origin"

Sync Dolt

bd dolt push

Work is NOT complete until git push succeeds. Never end a session before pushing.

Configuration

Configure workflow behavior via .beads/config.yaml:

# Disable git operations in session close
no-git-ops: true

# Set role explicitly
beads:
  role: maintainer  # or contributor

# Stealth mode detection
git:
  ignore-beads: true

Environment Variables

Variable	Purpose
`BEADS_DIR`	Override `.beads` location
`BEADS_ROLE`	Force role (contributor/maintainer)
`BD_NO_GIT_OPS`	Disable git operations

Best Practices

Choose the right mode

Solo/small team: Standard mode
Personal tracking: Stealth mode
Open source fork: Contributor mode
Repo maintainer: Maintainer mode (auto-detected)

Use discovered-from links

Always link side quests and bugs back to parent work:

bd create "Bug found" --deps discovered-from:bd-parent

Sync regularly

In standard/maintainer mode, sync often:

bd dolt pull   # Before starting work
bd dolt push   # After completing work

Clean PRs in contributor mode

Always verify no beads files in PRs:

git status  # Should show no .beads/ files

Architecture

Understand the two-layer data model

Dependencies

Learn about blocking and non-blocking relationships

Memory

Persistent agent knowledge across sessions

Protected Branches

Advanced sync branch configuration

Get Started

Core Concepts

Guides

Integrations

Workflow Modes Overview

Standard Mode

When to Use

Characteristics

Stealth Mode

When to Use

Characteristics

Example: Personal Task Tracking

Contributor Mode

When to Use

How It Works

Characteristics

Example: Contributing to Open Source

Maintainer Mode

When to Use

Characteristics

Switching Between Modes

Stealth → Standard

Standard → Stealth

Contributor → Standard

Hierarchical IDs

Agent Workflows

Standard Agent Flow

Agent Memory with `bd prime`

Session Completion Protocol

Configuration

Environment Variables

Best Practices

Architecture

Dependencies

Memory

Protected Branches

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Integrations

​Workflow Modes Overview

​Standard Mode

​When to Use

​Characteristics

​Stealth Mode

​When to Use

​Characteristics

​Example: Personal Task Tracking

​Contributor Mode

​When to Use

​How It Works

​Characteristics

​Example: Contributing to Open Source

​Maintainer Mode

​When to Use

​Characteristics

​Switching Between Modes

​Stealth → Standard

​Standard → Stealth

​Contributor → Standard

​Hierarchical IDs

​Agent Workflows

​Standard Agent Flow

​Agent Memory with bd prime

​Session Completion Protocol

​Configuration

​Environment Variables

​Best Practices

​Related Documentation

Architecture

Dependencies

Memory

Protected Branches

Build docs developers (and LLMs) love

Workflow Modes Overview

Standard Mode

When to Use

Characteristics

Stealth Mode

When to Use

Characteristics

Example: Personal Task Tracking

Contributor Mode

When to Use

How It Works

Characteristics

Example: Contributing to Open Source

Maintainer Mode

When to Use

Characteristics

Switching Between Modes

Stealth → Standard

Standard → Stealth

Contributor → Standard

Hierarchical IDs

Agent Workflows

Standard Agent Flow

Agent Memory with `bd prime`

Session Completion Protocol

Configuration

Environment Variables

Best Practices

Related Documentation