Workflows

Contributor mode, stealth mode, and maintainer mode for different collaboration scenarios

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:

Initialize

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:

Initialize

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:

Initialize

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

1. Fork and clone

   git clone https://github.com/you/some-project
   cd some-project
   
2. Initialize contributor mode

   bd init --contributor
   # Storage redirected to ~/.beads-planning/you-some-project/
   
3. 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
   
4. 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:

Auto-detected

# Beads auto-detects maintainer role via SSH URLs
git clone [e-mail]: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)

Create hierarchy

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

1. Find ready work

   bd ready --json
   

   Shows issues with no open blockers

2. Claim atomically

   bd update <id> --claim --json
   

   Sets assignee + status=in_progress in one operation

3. Work on it

   Implement, test, document the feature or fix

4. Discover new work

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

   Link discovered work back to parent

5. Complete

   bd close <id> --reason "Completed" --json
   
6. 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:

1. File remaining work

   bd create "Follow-up task" -t task -p 2 --json
   
2. Run quality gates

   make test
   make lint
   
3. Update issue status

   bd close <id> --reason "Completed" --json
   
4. Push to remote (MANDATORY)

   git pull --rebase
   git push
   git status  # Must show "up to date with origin"
   
5. 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

Related Documentation

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