PAPER-2026-002

Beads Integration Patterns

Issue Tracking for AI Agent Workflows

Research Paper • 8 min read • Intermediate

Abstract

How can issue tracking systems be designed to support nondeterministic, context-limited AI agent workflows? This paper analyzes Beads integration patterns across the CREATE SOMETHING monorepo, documenting patterns for context survival, work extraction, and dependency tracking that enable agents to pick up where they left off.

Research Question

Traditional issue trackers assume human operators with continuous context. AI agents face different constraints: context windows fill, sessions restart, and multiple agents may work in parallel. How do we design persistence that survives these conditions?

Methodology

Analyzed Beads implementation across multiple packages:

  • /packages/harness/src/beads.ts
  • /packages/agent-sdk/src/create_something_agents/tools/beads.py
  • /.claude/rules/beads-patterns.md

Integration Patterns

Context Survival

Preserve work across session restarts and context limits

bd create "Refactor authentication"
bd update cs-123 --status in-progress

Work Extraction

Convert review findings into actionable issues

createIssueFromFinding({
  severity: 'high',
  title: 'Add input validation',
  description: 'Prevent potential security risks'
})

Dependency Tracking

Model complex work relationships and blockers

bd dep add cs-auth blocks cs-dashboard

Work Discovery Taxonomy

Issues emerge from three sources during agent execution:

blocker

Critical findings that immediately halt progress

Critical security vulnerability requiring immediate fix

supervisor

Standard review findings about architecture, quality

Performance optimization suggestion

related

Secondary work items discovered during primary task

Potential refactoring during feature implementation

Limitations

  • Relies on CLI tool availability across environments
  • Potential race conditions in multi-agent environments
  • Requires consistent tooling across development environments
  • Git-based persistence adds commit overhead

Related Papers