Pebble Guide

Pebble Guide

Git-backed issue tracker for AI agents. Track all work as Pebble issues.

Quick Reference

# What to work on
pb ready                    # Unblocked issues (start here)
pb ready -v                 # With full details
pb blocked -v               # What's blocked and WHY

# Epic overview
pb summary                  # Open epics with completion counts
pb dep tree <epic>          # Full hierarchy (epic → tasks → verifications)
pb list --parent <epic>     # All children of an epic

# Issue details
pb show <id>                # Full issue details
pb verifications <id>       # Verifications targeting this issue

# Create with dependencies (self-documenting)
pb create "Task B" -t task --blocked-by $TASK_A    # B needs A
pb create "Task A" -t task --blocks $TASK_B        # A blocks B

# Basic workflow
pb create "Title" -t task -p 1 --parent $EPIC | jq -r .id
pb claim <id>               # Set in_progress
pb comments add <id> "What was done, file:line"
pb close <id> --reason "Done"

# Dependencies
pb dep add <blocked> <blocker>  # B blocked BY A: pb dep add B A
pb dep tree <id>                # View hierarchy

Types: task, bug, epic, verification | Priority: 0 (critical) to 4 (backlog) | Status: open, in_progress, blocked, pending_verification, closed

Core Rules

1. One Task at a Time

Only ONE issue in_progress. Transition current issue (block/close) before claiming another.

2. Comment Before Closing

Every close needs a comment with file paths, line numbers, and what was done. No comment = work isn't verified.

pb comments add <id> "Implemented X in src/foo.ts:45-78. Tests in foo.test.ts."
pb close <id> --reason "Done"

3. Every Code Change Gets an Issue

Found and fixed a bug? Create issue → fix → comment → close. Issues are audit records. No issue = invisible fix.

4. Dependencies: Blocked BY

pb dep add B A means "B is blocked by A" (A must close before B is ready).

Think: "B needs A" → pb dep add B A

Self-documenting alternative: Use --blocked-by or --blocks when creating:

pb create "Task B" --blocked-by $TASK_A   # B needs A (clearer)
pb create "Task A" --blocks $TASK_B       # A blocks B (clearer)

5. Parent ≠ Sequence

--parent creates hierarchy only. Children run in parallel unless you add explicit pb dep add between them.

6. No Orphans

Every issue connects to the work graph (parent epic or dependencies).

7. Comprehensive Descriptions

Write like a PM: Purpose, Why It Matters, Requirements, Acceptance Criteria. Future agents need full context.

8. Approved Plan Decomposition (Required)

If implementation is based on an approved plan with explicit phases/steps, create Pebble child tasks for each phase/step before or at implementation start (and immediately after resume if missing).

• Parent each step task under the epic (or current phase task for subplans)
• Add dependencies to match required sequence from the plan
• Keep exactly one task in_progress, but preserve full step-level traceability in Pebble
• Do not collapse multi-phase execution into a single long-running task

Verification Issues

Verification issues are post-completion checks — they become ready AFTER their target is closed.

# Create verification that targets a task
pb create "User can log in" --verifies $TASK_ID

# List verifications for an issue
pb verifications $TASK_ID

# Ready verifications (target closed, verification open)
pb ready --type verification

Ready Behavior

Creating Verifications from Plans

When plans have Verification sections, each verification step can become a verification issue:

TASK=$(pb create "Implement login" -t task --parent $PHASE | jq -r .id)

# Each feature = verification issue targeting the task
pb create "User can log in with valid credentials" --verifies $TASK \
  --description "Navigate to /login, enter valid creds, verify redirect to dashboard"
pb create "Invalid password shows error" --verifies $TASK \
  --description "Navigate to /login, enter wrong password, verify error message"

Performing Verification

When a verification appears in pb ready, its target is done. Verify immediately while context is fresh and environment is set up.

Steps:

1. Follow the steps in the description
2. Capture evidence (screenshots, responses, output)
3. Comment with proof
4. Close if passing, or create bug if failing

Evidence varies by type:

• UI: Screenshot or description of what you observed
• API: Request sent, response received (status, body)
• CLI: Command run, output produced
• Data: Query executed, results returned

# Good: evidence included
pb comments add $ID "POST /login with valid creds → 200, session cookie set, redirected to /dashboard"
pb close $ID --reason "Verified"

# Bad: no evidence
pb comments add $ID "Works"

If verification fails: Don't close. Create a bug issue, link it, fix, then re-verify.

If you can't verify right now (no browser session, backend not running, need user action):

# Comment what's blocking, leave open
pb comments add $ID "Cannot verify: backend not running. Need to start server first."

Don't close without verification. Don't delete the issue. The record shows verification was attempted and blocked.

Pending Verification Status

When you close an issue that has open verification issues targeting it, it goes to pending_verification instead of closed. This enforces that verification actually happens.

pb close $TASK_ID --reason "Implementation done"
# Output: Issue set to pending_verification. Pending: BEAD-abc123, BEAD-def456

# Complete the verification issues first
pb close BEAD-abc123 --reason "Verified"
pb close BEAD-def456 --reason "Verified"

# Now the task auto-closes, or close it again
pb close $TASK_ID --reason "All verifications passed"

Epic Management

Overview with pb summary

See all open epics with completion progress:

pb summary --pretty

## Open Epics (2)

BEAD-abc123: Implement authentication
  Created: 2 days ago | Updated: 1 hour ago
  Issues: 2/5 done | Verifications: 1/3 done

  Build user auth with login, logout, session management.

Include recently closed epics (last 72h):

pb summary --include-closed --pretty

Full Hierarchy with pb dep tree

See complete epic structure including nested children:

pb dep tree $EPIC --pretty

✓ BEAD-abc123: Implement authentication [epic] P1 ◀
├─ ✓ BEAD-def456: User registration [task] P2
│  ├─ ✓ BEAD-v001: Can register with email [verification]
│  └─ ✓ BEAD-v002: Invalid email shows error [verification]
├─ ○ BEAD-ghi789: Login flow [task] P2
│  ├─ ○ BEAD-v003: Can login [verification]
│  └─ ○ BEAD-v004: Wrong password shows error [verification]
└─ ○ BEAD-jkl012: Session management [task] P2

The ◀ marker indicates the requested issue. ✓ = closed, ○ = open.

List Children with pb list --parent

Flat list of all direct children:

pb list --parent $EPIC --pretty

Related Links

Use pb dep relate for issues that share context but don't block each other. Unlike blocks, related links are bidirectional and don't affect pb ready.

# Link related issues (bidirectional, non-blocking)
pb dep relate $ISSUE1 $ISSUE2

# Remove the link
pb dep unrelate $ISSUE1 $ISSUE2

# View all dependencies including related
pb dep list $ISSUE1

Use cases:

• Issues that touch the same code but can run in parallel
• Cross-references for context without ordering requirements
• Grouping conceptually linked issues

Finding Issues

Search

pb search "auth bug" --pretty          # Search titles and descriptions
pb search "login" --type bug --pretty  # Filter by type
pb search "refactor" --status open     # Filter by status

See Why Something Is Blocked

pb blocked -v --pretty

## Blocked Issues (2)

BEAD-ghi789: Session management
  Type: Task | Priority: P2 | Created: 12 hours ago
  Epic: BEAD-abc123 (Implement authentication)
  Blocked by: BEAD-def456

The -v (verbose) flag shows which issues are causing the block.

Common Workflows

Create Epic with Phases and Tasks (Nested)

For larger work, create a hierarchy: Epic → Phases → Tasks → Subtasks

# Create epic
EPIC=$(pb create "Feature X" -t epic | jq -r .id)

# Create phases under epic
P1=$(pb create "Phase 1: Design" -t task --parent $EPIC | jq -r .id)
P2=$(pb create "Phase 2: Implementation" -t task --parent $EPIC | jq -r .id)
P3=$(pb create "Phase 3: Testing" -t task --parent $EPIC | jq -r .id)

# Sequence phases
pb dep add $P2 $P1    # Phase 2 needs Phase 1
pb dep add $P3 $P2    # Phase 3 needs Phase 2

# Create tasks under Phase 1
T1A=$(pb create "Design data model" -t task --parent $P1 | jq -r .id)
T1B=$(pb create "Design API contracts" -t task --parent $P1 | jq -r .id)

# Create tasks under Phase 2 (can have subtasks too)
T2A=$(pb create "Implement backend" -t task --parent $P2 | jq -r .id)
T2B=$(pb create "Implement frontend" -t task --parent $P2 --blocked-by $T2A | jq -r .id)

# Create verification issues targeting tasks
pb create "API returns correct schema" --verifies $T2A
pb create "UI displays data correctly" --verifies $T2B

Result:

Epic: Feature X
├── Phase 1: Design
│   ├── Design data model
│   └── Design API contracts
├── Phase 2: Implementation (blocked by Phase 1)
│   ├── Implement backend
│   └── Implement frontend (blocked by backend)
└── Phase 3: Testing (blocked by Phase 2)

Create Simple Epic (Flat)

For smaller work, flat structure is fine:

EPIC=$(pb create "Feature X" -t epic | jq -r .id)
T1=$(pb create "Design" -t task --parent $EPIC | jq -r .id)
T2=$(pb create "Implement" -t task --parent $EPIC --blocked-by $T1 | jq -r .id)
T3=$(pb create "Test" -t task --parent $EPIC --blocked-by $T2 | jq -r .id)

Discovered Blocker

NEW=$(pb create "Found: auth needs refactor" -t bug -p 1 | jq -r .id)
pb dep add $CURRENT $NEW    # Current blocked by new
pb update $CURRENT --status blocked
pb claim $NEW               # Work on blocker

Work Loop

pb ready                    # What's unblocked
pb claim <id>               # Start work
# ... implement ...
pb comments add <id> "Done: file:line, tests added"
pb close <id> --reason "Implemented"

Pitfalls