Two-context execution pattern with Beads issue tracker for AI-assisted development

README.md

Two-Context Execution Pattern with Beads

A workflow pattern for AI-assisted development that separates planning from execution, using context isolation to keep each layer focused.

The Problem

Large tasks overwhelm a single Claude session:

• Context fills with implementation details
• Hard to track overall progress
• Easy to lose sight of the plan while deep in code
• Discovered work gets forgotten or mixed with current task

The Solution: Layered Contexts

┌─────────────────────────────────────────────────────────────────┐
│  PLANNING LAYER                                                 │
│  /bdplan "Build user auth with JWT"                            │
│  → Creates epic + task issues with dependencies                 │
│  → Output: dependency tree, ready tasks                         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  ORCHESTRATION LAYER (tmux panel 1)                             │
│  /bdexec [epic-id]                                              │
│                                                                 │
│  Loop:                                                          │
│    1. bd ready → find next unblocked task                       │
│    2. Show summary card                                         │
│    3. /bdissue [task-id] → fork to implementation               │
│    4. Show completion card                                      │
│    5. Repeat until done                                         │
│                                                                 │
│  This context stays CLEAN—only tracks which tasks done/blocked  │
└─────────────────────────────────────────────────────────────────┘
          ↓ (forked)                              ↓ (parallel)
┌──────────────────────────────┐    ┌─────────────────────────────┐
│  IMPLEMENTATION CONTEXT      │    │  TRIAGE CONTEXT             │
│  /bdissue task-5             │    │  /bdtriage                  │
│                              │    │                             │
│  - Claims issue immediately  │    │  - Captures discovered work │
│  - Reads issue details       │    │  - Creates new issues       │
│  - Implements code           │    │  - Sets dependencies        │
│  - Makes atomic commits      │    │  - Never implements         │
│  - Tracks progress (bd cmts) │    │                             │
│  - Closes when done          │    │  "The login is slow"        │
│                              │    │  → Creates perf bug issue   │
│  Context: FULL (all details) │    │                             │
│  Lifetime: ONE TASK          │    │  "Add dark mode someday"    │
│                              │    │  → Creates feature issue    │
└──────────────────────────────┘    └─────────────────────────────┘

The Commands

/bdplan — Create the Work

Takes requirements, outputs a structured plan as beads issues:

/bdplan "Build user authentication with email/password and JWT tokens"

What it does:

1. Creates an epic issue for the overall feature
2. Breaks down into task issues with clear acceptance criteria
3. Sets up dependency chains (what blocks what)
4. Outputs the dependency tree and first ready tasks

Output example:

Epic: proj-100 "User Authentication System"
├─ proj-101 "Design database schema" (ready)
├─ proj-102 "Implement registration" (blocked by 101)
├─ proj-103 "Password hashing" (blocked by 101)
├─ proj-104 "JWT token utility" (ready)
├─ proj-105 "Login endpoint" (blocked by 102, 104)
└─ proj-106 "Auth middleware" (blocked by 105)

Ready to start: proj-101, proj-104

/bdexec — Orchestrate Execution

Loops through ready tasks, dispatching each to /bdissue:

/bdexec proj-100  # Execute all tasks under this epic

What it does:

1. Finds ready work (bd ready)
2. Shows a summary card before each task
3. Invokes /bdissue [task-id] in a forked context
4. Shows completion status
5. Repeats until no ready work remains

The key insight: /bdexec stays lightweight. It only tracks:

• Which tasks were attempted
• Which completed vs blocked
• New issues that appeared

All implementation details live in the forked /bdissue contexts.

Example output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-101 (P1)
  Design database schema for users table
  Create migration with email, password_hash, timestamps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[forked context runs /bdissue proj-101]

✓ DONE: proj-101 — completed
  Created users migration, added indexes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-104 (P1)
  Create JWT token generation utility
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[forked context runs /bdissue proj-104]

✓ DONE: proj-104 — completed
  Added JwtService with sign/verify, specs passing

/bdissue — Single Task Execution

Executes one issue with full implementation context:

/bdissue proj-101

Critical first step: Claim immediately

bd update proj-101 --status in_progress

What it does:

1. Claims the issue (--status in_progress)
2. Reads full issue details and acceptance criteria
3. Implements the work with atomic commits
4. Tracks progress via bd comments add
5. Closes when done with summary

Handles blockers gracefully:

# Discovered a blocker
bd create "Config schema missing" --priority 0
bd dep add proj-101 proj-107 --type blocks
bd comments add proj-101 "Blocked by proj-107"
bd update proj-101 --status open
# Reports back: "blocked by proj-107"

/bdtriage — Capture Discovered Work

A dedicated context for creating issues without implementing:

/bdtriage

Behavior:

• Statements → Issues: "The login is slow" creates a performance bug
• Questions → Research: "Where is auth handled?" gets answered
• Never implements: Only captures work items

Why separate? When you're deep in implementation, you notice things: edge cases, tech debt, ideas. Triage captures these without derailing current work.

The Two-Panel Pattern

For sustained work sessions, run two tmux panels:

┌─────────────────────────────────┬────────────────────────────────┐
│  Panel 1: /bdexec               │  Panel 2: /bdtriage            │
│                                 │                                │
│  Orchestrating task execution   │  Capturing discovered work     │
│  - Shows current task progress  │  - "Add rate limiting"         │
│  - Tracks completion/blockers   │    → Creates feature issue     │
│  - Auto-advances to next task   │  - "That N+1 query is bad"     │
│                                 │    → Creates bug issue         │
│  You watch; it executes         │  You dictate; it files         │
└─────────────────────────────────┴────────────────────────────────┘

Why this works:

• /bdexec handles the queue—you don't have to track "what's next"
• /bdtriage captures drive-by observations without switching context
• Both feed into the same bd database
• New issues from triage may become blockers for exec's current work

Context Isolation: The Secret Sauce

The /bdissue command uses context: fork in its frontmatter:

---
context: fork
---

This means:

• Full conversation context available (can see what led here)
• Tool calls don't pollute the parent conversation
• When done, only the final summary returns to /bdexec

Result: /bdexec stays clean. It sees:

✓ DONE: proj-101 — completed
  Created users migration, added indexes

Not the 50 tool calls that made that happen.

When to Use This Pattern

Good fit:

• Multi-task features (5+ issues)
• Work that will span multiple sessions
• Projects where you want audit trail of decisions
• Teaching scenarios (progress is visible)

Overkill:

• Single-issue bug fixes
• Quick explorations
• Tasks where the full plan is in your head

Practical Tips

Starting a Session

# Check what's ready
bd ready

# If resuming work on an epic
bd dep tree proj-100
bd ready --epic proj-100  # (if your bd supports this filter)

During Execution

The /bdexec loop handles most things, but watch for:

• Repeated blockers: Same issue keeps blocking? Might need human input
• Scope creep: Triage creating lots of issues? Pause and prioritize
• Test failures: /bdissue should stop and report, not push through

Ending a Session

# Check state
bd list --status in_progress  # Should be empty
bd list --status open         # Remaining work

# Sync to git
bd sync
git status
git push

Summary

Layer	Command	Context	Purpose
Planning	/bdplan	Normal	Create structured issue tree
Orchestration	/bdexec	Normal (lightweight)	Loop through ready tasks
Implementation	/bdissue	Forked (isolated)	Execute single task with full detail
Capture	/bdtriage	Normal	File discovered work as issues

The magic is in the separation: planning happens once, orchestration stays clean, implementation gets full context, and discovered work doesn't get lost.

bdexec.md

description	allowed-tools
execute a set of bd issues sequentially	Bash(bd:*), Skill

Execute BD Plan

Overview

Execute a bd plan by running /bdissueexec for each ready issue. Each issue runs in a forked context (context isolation without summarization), so you see full progress while keeping the orchestrator context clean.

Arguments

$ARGUMENTS

Optional: epic ID or search term to scope which issues to work on. If not provided, works through all ready issues.

Instructions

How it works

bdplanexec
    ├── /bdissueexec issue-1  (forked context, full output)
    ├── /bdissueexec issue-2  (forked context, full output)
    └── /bdissueexec issue-N  (forked context, full output)

Each /bdissueexec runs in a forked context—you see full progress, but tool calls don't pollute the main conversation.

1. Initial Plan Review (if scoped)

If an epic ID or scope is provided:

bd show [epic-id]          # Understand the plan
bd dep tree [epic-id]      # See structure

2. Main Orchestration Loop

Repeat until no ready issues remain:

Step A: Find Ready Work

bd ready

If scoped to an epic, filter to relevant issues.

Step B: Select Next Issue

• Choose by priority (lower number = higher priority)
• If tied, take the first one
• Don't deliberate - just pick and go

Step C: Show Summary Card, then Run /bdissueexec [issue-id]

Before invoking bdissueexec, output a brief summary card so the user knows what's being worked on:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: [issue-id] (P[priority])
  [issue title]
  [1-2 line description or acceptance criteria summary]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then use the Skill tool to invoke bdissueexec with the issue ID.

Step D: Process Result and Show Completion Card

When the issue completes, output a completion card:

✓ DONE: [issue-id] — [outcome: completed/blocked/needs-attention]
  [brief summary of what happened]

• If blocked, bdissueexec should have created/linked blocker issues
• Continue to next ready issue

Step E: Repeat

bd ready

Loop back to Step B if issues remain.

3. Completion

When bd ready returns no issues:

bd list --status open    # Verify nothing remaining

If all issues in an epic are done:

bd close [epic-id] --reason "All subtasks completed"

Orchestrator State Tracking

Keep a simple mental log:

• Issues attempted
• Issues completed
• Issues blocked (and why)
• New issues discovered

Report summary at end.

Handling Blocked Issues

If an issue reports blocked:

1. Verify blocker issue was created
2. Check if blocker is something you can address
3. If blocker is ready, run /bdissueexec for it next
4. Otherwise, note it and continue with other ready work

Example Session

# Start
bd ready
→ proj-12 (p1), proj-15 (p2), proj-18 (p2)

# Summary card before running
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-12 (P1)
  Add user authentication to API endpoints
  Implement JWT validation middleware for protected routes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Run first issue
/bdissueexec proj-12
→ [forked context runs]

✓ DONE: proj-12 — completed
  Added JWT middleware, updated 3 endpoints, tests passing

# Check ready again
bd ready
→ proj-13 (p1, was blocked by proj-12), proj-15 (p2), proj-18 (p2)

# Summary card
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-13 (P1)
  Refactor database connection pooling
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/bdissueexec proj-13
→ [forked context runs]

✗ DONE: proj-13 — blocked
  Missing config schema, created proj-19 as blocker

# Check ready
bd ready
→ proj-19 (p0, blocker), proj-15 (p2), proj-18 (p2)

# Summary card for blocker
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-19 (P0)
  Add config schema for connection pool settings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/bdissueexec proj-19
→ [forked context runs]

✓ DONE: proj-19 — completed
  Added schema, proj-13 now unblocked

# Continue until bd ready returns empty...

Best Practices

1. Stay Lightweight - Orchestrator only tracks status, doesn't do implementation
2. Trust bdissueexec - Let it handle the details
3. React to Blockers - Check if newly-ready issues include just-created blockers
4. Report Progress - Keep user informed of overall status between issues

Stopping Conditions

Stop the loop when:

• bd ready returns no issues (success!)
• Critical blocker needs human input (report and ask)
• Repeated failures on same issue (escalate)

bdissue.md

description	argument-hint	allowed-tools	context
execute a single bd issue	<issue key>	Bash(bd *), Bash(git *), Bash(tea *), Read(.)	fork

Execute Single BD Issue

Overview

Execute a single bd issue with proper status tracking, commenting, and git workflow integration. This command handles one issue in isolation, keeping context clean.

Execute the bd issue [issue-id] following the bdissueexec workflow:

1. IMMEDIATELY mark in_progress: bd update [issue-id] --status in_progress
2. Review details: bd show [issue-id]
3. Implement the work with atomic commits
4. Track progress with bd comments adds after commits
5. Verify acceptance criteria and tests pass
6. Close when complete: bd close [issue-id] --reason "[summary]"

If blocked, create blocker issues and report back.

Report final status: completed, blocked, or needs-attention.

Arguments

$ARGUMENTS

The argument should be a bd issue ID (e.g., proj-5, app-12).

Instructions

1. Claim the Issue Immediately

bd update [issue-id] --status in_progress

⚠️ CRITICAL: Do this FIRST before any other work.

2. Review Issue Details

bd show [issue-id]

Read the description, acceptance criteria, and any existing comments carefully.

3. Implement the Work

Commit Strategy

• Commit early and often - each logical unit of working code
• Never commit broken code (except failing tests before TDD implementation)
• Clear messages - explain why, not just what
• No Claude references in commit messages

Track Progress with Comments

After each meaningful commit:

bd comments add [issue-id] "Commit [hash]: [what was done]"

4. Complete the Issue

Before Closing

• ✅ All acceptance criteria met
• ✅ Tests pass (run them!)
• ✅ All changes committed to git
• ✅ No uncommitted files related to this issue

Close with Summary

bd close [issue-id] --reason "Brief summary of what was completed"

5. Report Back

When done, provide a brief summary:

• What was implemented
• Key commits made
• Any issues discovered (should be filed with bd create)
• Final status

Handling Blockers

If you discover a blocker:

# Create blocker issue
bd create "Fix: [blocker description]" \
  --priority 0 \
  --description "Discovered while working on [issue-id]"

# Link dependency
bd dep add [issue-id] [blocker-id] --type blocks

# Comment on original
bd comments add [issue-id] "Blocked by [blocker-id]: [reason]"

# Reopen original issue
bd update [issue-id] --status open

Then report back that the issue is blocked.

Discovering New Work

If you find additional work needed:

bd create "[New task]" \
  --description "Discovered during [issue-id]: [context]"
bd comments add [issue-id] "Created [new-id] for [reason]"

Continue with the original issue unless it's truly blocked.

Error Handling

If you cannot complete the issue:

1. Document what was done in a comment
2. Document what's blocking completion
3. Either:
   • Create a blocker issue and link it
   • Or leave in_progress with clear comment about state
4. Report back with status and blockers

Best Practices

1. One Issue Focus - Don't work on other issues, stay focused
2. Atomic Commits - Small, working increments
3. Rich Comments - Reference commits, document decisions
4. Test Before Close - Verify functionality works
5. Clean Exit - Always leave issue in a valid state (closed or clearly documented)

bdplan.md

description	allowed-tools
plan a set of bd issues	Bash(bd:*)

Create BD Implementation Plan

Overview

Create a structured implementation plan as a series of linked bd issues with dependency management. Uses bd's native issue tracking and dependency chains to represent a complete project plan.

Plan Creation Process

Initialization

1. Ensure bd is initialized: Check if .beads/ directory exists
2. Parse Requirements: Extract key functionality, constraints, and goals from input
3. Structure Plan: Break down into hierarchical tasks with dependencies
4. Create Issues: Generate bd issues with proper blocking relationships

Issue Structure Strategy

Hierarchical Organization

Use bd's dependency system to create project structure:

• Epic Issues: High-level features (e.g., "Implement user authentication")
• Task Issues: Specific implementation steps
• Dependencies: Use bd dep add to chain tasks in execution order

Dependency Types to Use

• blocks: For sequential tasks (Task B must complete before Task A)
• parent-child: For epic/subtask relationships
• related: For tasks that share context but don't block

Creating the Plan

🔑 Best Practice: Use --parent and --blocks flags during creation

Instead of creating all issues first and then adding dependencies separately, set dependencies during issue creation for maximum efficiency:

# ✅ EFFICIENT: Dependencies set during creation
bd create "Task name" \
  --parent [epic-id] \
  --blocks [blocking-task-id] \
  --blocks [another-blocker]

# ❌ INEFFICIENT: Separate dep add commands
bd create "Task name"
bd dep add [epic-id] [task-id] --type parent-child
bd dep add [task-id] [blocker] --type blocks

Benefits:

• Fewer commands (1 instead of 3+)
• Clearer intent (dependencies visible in creation)
• Easier to script and automate
• Less error-prone (no ID tracking needed)

Step 1: Create Epic Issue

bd create "Plan: [Feature Name]" \
  --priority 0 \
  --type epic \
  --description "Executive summary and technical approach"

Step 2: Create Task Issues with Dependencies

For each implementation step, use --parent and --blocks flags to set dependencies during creation:

# Create task with parent and blocking relationships in one command
bd create "[Task Description]" \
  --priority [0-4] \
  --type [feature|bug|task] \
  --description "Detailed implementation notes" \
  --parent [epic-id] \
  --blocks [blocking-task-id] \
  --assignee [optional]

Using --parent flag:

• Automatically creates parent-child dependency
• Child task is created, parent epic depends on it
• More efficient than separate bd dep add command

Using --blocks flag:

• Automatically creates blocks dependency
• New task depends on (is blocked by) the specified task
• Multiple --blocks flags can be used for multiple blockers

Alternative: Manual Dependency Management If you need to add dependencies after creation:

# Task B blocks Task A (A depends on B)
bd dep add [prefix]-[A] [prefix]-[B] --type blocks

# Create parent-child for epic relationship
bd dep add [epic-id] [task-id] --type parent-child

⚠️ CRITICAL: Parent-Child Dependency Direction

The parent-child dependency type uses the format: parent depends_on child

# ✅ CORRECT: Parent epic depends on child task
bd dep add [parent-epic-id] [child-task-id] --type parent-child

# ❌ WRONG: Child depends on parent (backwards, won't show in tree)
bd dep add [child-task-id] [parent-epic-id] --type parent-child

Why this matters:

• The dependency tree shows issues that appear in the parent's depends_on_id field
• Backwards dependencies cause children to NOT appear under their parent in bd dep tree
• The semantics: "parent depends on child" means "parent is complete when children are done"

Verification:

# After adding dependencies, always verify:
bd dep tree [epic-id]
# You should see child tasks indented under the epic
# If children don't appear, dependencies are backwards

Step 4: Verify Plan Structure

bd dep tree [epic-id]  # Visualize the full plan
bd ready               # Verify what's ready to start

Issue Content Template

Each issue should include:

Title: Clear, action-oriented description (e.g., "Implement JWT token generation")

Description:

## Context
[Why this task is needed]

## Implementation Details
[Technical approach and key considerations]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Testing
[How to verify this works]

## Notes
[Additional context, links, references]

Priority Levels

• 0: Critical path, high priority
• 1: Important but not blocking
• 2: Normal priority
• 3: Low priority
• 4: Nice to have

Status Workflow

1. open: Issue created, ready to work when unblocked
2. in_progress: Actively being worked on
3. closed: Completed successfully

Use bd ready to find next available work.

Plan Workflow Commands

View Plan Status

bd list --type epic                    # See all epics
bd show [epic-id]                      # Epic details
bd dep tree [epic-id]                  # Full plan structure
bd ready                               # What can be worked on now
bd blocked                             # What's waiting on dependencies

Work on Plan

bd ready                               # Find next task
bd update [issue-id] --status in_progress  # Start work
bd comments add [issue-id]             # Add progress notes
bd close [issue-id]                    # Complete task
bd ready                               # Find next task

Track Progress

bd stats                               # Overall progress
bd list --status open                  # Remaining work
bd list --status closed                # Completed work
bd stale                               # Issues not recently updated

Input Processing

When user provides requirements:

1. Parse Requirements:

   • Identify main feature/change
   • Extract key components and phases
   • Determine logical groupings

2. Create Epic:

   • One epic for the overall plan
   • Summary in title
   • Full context in description

3. Break Down Tasks:

   • Each atomic step becomes an issue
   • Descriptive titles
   • Detailed descriptions with acceptance criteria

4. Map Dependencies:

   • Identify which tasks must happen first
   • Create blocking relationships
   • Link related tasks

5. Set Priorities:

   • Critical path items: priority 0
   • Supporting tasks: priority 1-2
   • Nice-to-haves: priority 3-4

6. Output Summary:

   • Show created issues
   • Display dependency tree
   • List first ready tasks

Example Plan Creation

Given requirements: "Build user authentication with email/password and JWT tokens"

Efficient approach using --parent and --blocks:

# Step 1: Create epic (assuming it gets ID proj-100)
EPIC=$(bd create "Plan: User Authentication System" \
  --type epic \
  --priority 0 \
  --description "Complete user auth with email/password and JWT" \
  --json | jq -r '.issues[0].id')

# Step 2: Create tasks with dependencies in one command each
# First task (no blockers)
SCHEMA=$(bd create "Design database schema for users table" \
  --parent $EPIC \
  --json | jq -r '.issues[0].id')

# Tasks that depend on schema
REG=$(bd create "Implement user registration endpoint" \
  --parent $EPIC \
  --blocks $SCHEMA \
  --json | jq -r '.issues[0].id')

HASH=$(bd create "Implement password hashing with bcrypt" \
  --parent $EPIC \
  --blocks $SCHEMA \
  --json | jq -r '.issues[0].id')

# JWT utility (no dependencies)
JWT=$(bd create "Create JWT token generation utility" \
  --parent $EPIC \
  --json | jq -r '.issues[0].id')

# Login needs JWT utility and registration
bd create "Implement login endpoint with token issuance" \
  --parent $EPIC \
  --blocks $JWT \
  --blocks $REG

# Middleware needs login (get login ID from previous command if needed)
bd create "Add authentication middleware" \
  --parent $EPIC \
  --blocks proj-105  # Login endpoint ID

# Tests need everything (use final --blocks for last critical task)
bd create "Write integration tests for auth flow" \
  --parent $EPIC \
  --blocks proj-106  # Middleware ID

# Step 3: View the plan
bd dep tree $EPIC
bd ready

Alternative: Old approach (less efficient but works)

# Create all issues first
bd create "Plan: User Authentication System" --type epic -p 0
bd create "Design database schema for users table"
bd create "Implement user registration endpoint"
# ... create all tasks

# Then add dependencies manually (20+ commands)
bd dep add proj-100 proj-101 --type parent-child
bd dep add proj-100 proj-102 --type parent-child
# ... repeat for all parent-child relationships

bd dep add proj-102 proj-101 --type blocks
bd dep add proj-103 proj-101 --type blocks
# ... repeat for all blocking relationships

Raw Requirements

$ARGUMENTS

Git Integration

bd auto-syncs with git:

• Issues export to .beads/*.jsonl automatically
• Changes sync across team members via git
• No manual export/import needed
• Plan persists in version control

Multi-Repository Plans

For plans spanning multiple repos:

bd init --prefix api    # In api repo
bd init --prefix web    # In web repo

# Reference across repos in descriptions
bd create "Integrate with API" \
  --description "Depends on api-15 being deployed"

Cleanup

When plan is complete:

bd cleanup --age 30d    # Archive old closed issues
bd compact              # Compress issue history

Advanced Features

Templates

Create issue templates for common task types:

bd template create feature-task
# Opens editor with template

Comments for Progress

bd comments add [issue-id]
# Add detailed progress notes, blockers, decisions

Labels

Organize by component:

bd label add [issue-id] "backend"
bd label add [issue-id] "database"
bd list --label backend

Benefits Over Traditional Planning

1. Dependency Awareness: bd ready always shows unblocked work
2. Git Native: Plans version controlled and synced
3. Programmatic: --json flags for agent integration
4. Flexible: Add/modify issues as plan evolves
5. Visible: bd dep tree shows complete structure
6. Audit Trail: Full history in git and issue comments

bdtriage.md

BD Triage Mode

You are an issue creation bot for the beads (bd) issue tracker. Your role is to research problems and create well-formed issues—NOT to implement solutions.

Behavior Rules

1. Statements = Issue Requests: When the user makes a statement about a problem, bug, feature idea, or work item, immediately create a bd issue for it. Do not ask for confirmation first.

2. Questions = Research & Answer: When the user asks a direct question, research and answer it. Only create an issue if they then request one.

3. Never Implement: Do not write code, fix bugs, or make changes. Your job is to capture work items, not execute them.

Issue Creation Process

For each issue:

1. Research the codebase to understand the context
2. Determine appropriate type (bug, feature, task, chore, epic)
3. Set priority (0=critical, 1=high, 2=medium, 3=low, 4=backlog)
4. Write a clear, self-contained title with file/method names where relevant
5. Include relevant context in the body
6. Create with: bd create --title="..." --type=<type> --priority=<n> --body="..."

Title Guidelines

• Make titles actionable and specific
• Include file/class/method names when relevant
• Bad: "Fix the bug"
• Good: "Fix nil error in UserService#authenticate when session expired"

Body Guidelines

Include:

• What the issue is (symptom or desired outcome)
• Where it occurs (files, lines, conditions)
• Why it matters (impact, frequency)
• Any reproduction steps or acceptance criteria

Example Interactions

User says: "The login page is slow when there are many users" You do: Research the login code, then create an issue like:

bd create --title="Optimize login page performance with large user counts" --type=bug --priority=2 --body="Login page has performance issues when user table is large. Likely N+1 query or missing index in SessionsController#create."

User asks: "Where is authentication handled?" You do: Research and answer the question. No issue created unless requested.

User says: "We should add dark mode" You do: Create a feature issue immediately.

Commands You Use

bd create --title="..." --type=<type> --priority=<n> --body="..."
bd list --status=open              # Check for duplicates
bd show <id>                       # Reference related issues
bd dep add <blocked> <blocker>     # Link dependencies

Remember

• Bias toward action: create issues, don't deliberate
• One statement = one issue (unless it's clearly multiple items)
• Research before creating to write informed issues
• Never say "I could create an issue for that"—just do it