Agent Workflow

Detailed workflow for AI agents using Tracer, from finding ready work to completing tasks

Complete Agent Workflow

This page describes the recommended workflow for AI agents using Tracer. Follow these steps in every session to maintain context and coordinate work effectively.

1. Find Ready Work

At the start of any session, check for unblocked work:

Basic Usage

# Get unblocked work in JSON format
tracer ready --json

Always start your session with tracer ready to orient yourself. This shows you exactly what can be worked on without blockers.

Parsing Ready Work

# Check if there's ready work
WORK=$(tracer ready --limit 1 --json)
if [ "$(echo $WORK | jq length)" -gt 0 ]; then
  ISSUE_ID=$(echo $WORK | jq -r '.[0].id')
  echo "Working on: $ISSUE_ID"
fi

2. Claim and Start Work

Once you’ve selected an issue, claim it by updating the status:

Update Status

# Update issue to in_progress
tracer update bd-1 --status in_progress

When you update an issue to in_progress, Tracer automatically assigns it to you (based on the TRACE_ACTOR environment variable) if no assignee is set.

Example: Claiming Work

#!/bin/bash

# 1. Get ready work
WORK=$(tracer ready --limit 1 --json)

if [ "$(echo $WORK | jq length)" -eq 0 ]; then
  echo "No ready work found"
  exit 0
fi

# 2. Extract issue details
ISSUE_ID=$(echo $WORK | jq -r '.[0].id')
ISSUE_TITLE=$(echo $WORK | jq -r '.[0].title')

echo "Working on: $ISSUE_ID - $ISSUE_TITLE"

# 3. Claim the work
tracer update $ISSUE_ID --status in_progress

3. Create Issues During Work

As you discover new work, file it immediately to ensure nothing gets lost:

Create Bug

# Create a bug you found
tracer create "Fix edge case in validation" -t bug -p 0 --json

Example: Discovered Work

# Discovered a bug while working on bd-5
NEW_ID=$(tracer create "Fix null pointer in parser" -t bug -p 0 --json | jq -r '.id')
tracer dep add $NEW_ID bd-5 --type discovered-from

File issues liberally - it’s better to have too many tracked issues than to lose important work.

4. Add Dependencies

When you realize work blocks other work, model it explicitly:

Blocking Dependency

# bd-2 is blocked by bd-1
tracer dep add bd-2 bd-1 --type blocks

Dependency Types

• blocks: “bd-2 cannot start until bd-1 is done”
• parent-child: “bd-2 is a subtask of epic bd-1”
• discovered-from: “bd-2 was found while working on bd-1”
• related: “bd-2 and bd-1 are connected but don’t block”

5. Update Status Regularly

Keep the tracker in sync with reality:

1. Starting Work

   tracer update bd-1 --status in_progress
   
2. Hit a Blocker

   tracer update bd-1 --status blocked
   
3. Back to Work

   tracer update bd-1 --status in_progress
   
4. Complete

   tracer close bd-1 --reason "Completed successfully"
   

6. Complete Work

When you finish a task, close it with a meaningful message:

Single Issue

# Close the issue
tracer close bd-1 --reason "Implemented and tested"

Provide meaningful completion messages in --reason. This helps with audit trails and understanding what was accomplished.

7. Check Status

Regularly review the overall state of your work:

View Issue Details

# View specific issue
tracer show bd-1 --json

Complete Integration Example

Here’s a complete agent workflow script:

#!/bin/bash

# 1. Check for ready work
WORK=$(tracer ready --limit 1 --json)

if [ "$(echo $WORK | jq length)" -eq 0 ]; then
  echo "No ready work found"
  exit 0
fi

# 2. Get issue details
ISSUE_ID=$(echo $WORK | jq -r '.[0].id')
ISSUE_TITLE=$(echo $WORK | jq -r '.[0].title')

echo "Working on: $ISSUE_ID - $ISSUE_TITLE"

# 3. Claim the work
tracer update $ISSUE_ID --status in_progress

# 4. Do the work...
# (your implementation here)

# 5. Discover new work during execution
if [ "$FOUND_BUG" = "true" ]; then
  BUG_ID=$(tracer create "Fix discovered issue" -t bug -p 0 --json | jq -r '.id')
  tracer dep add $BUG_ID $ISSUE_ID --type discovered-from
fi

# 6. Complete the work
tracer close $ISSUE_ID --reason "Implemented and tested"

# 7. Show stats
tracer stats

Example Session

Here’s what a typical agent session looks like:

# Session start - what's ready?
$ tracer ready --limit 3

✓ Ready work: 2 issue(s)

bd-5 Implement user profile page [P1, feature]
  Status: open
  Created: 2025-10-15 10:00 | Updated: 2025-10-15 10:00

bd-8 Fix validation bug [P0, bug]
  Status: open
  Created: 2025-10-15 11:00 | Updated: 2025-10-15 11:00

# Pick the highest priority
$ tracer update bd-8 --status in_progress

# Work on it, discover an issue
$ tracer create "Add tests for validation" -t task -p 1 --deps "discovered-from:bd-8"
✓ Created issue bd-12 Add tests for validation

# Complete the work
$ tracer close bd-8 --reason "Fixed validation and added tests"

# Check stats
$ tracer stats

Issue Statistics

  Total Issues:      12
  Open:              8
  In Progress:       1
  Blocked:           0
  Closed:            3

  Ready to Work:     7

  Avg Lead Time:     2.3 hours

Advanced Workflows

Query and Filter

# List all open bugs
tracer list --status open --type bug --json

# Find issues by priority
tracer list --priority 0 --json

# Search by assignee
tracer list --assignee "agent-1" --json

Dependency Management

# View dependency tree
tracer dep tree bd-1 --max-depth 10

# Detect cycles (issues blocking each other)
tracer dep cycles

# Remove a dependency
tracer dep remove bd-2 bd-1

Batch Operations

# Close multiple issues
tracer close bd-1 bd-2 bd-3 --reason "Sprint complete"

# Create issues with dependencies inline
tracer create "Task B" -p 1 --deps "blocks:bd-1"

Next Steps

JSON Output

Learn about JSON response formats

Best Practices

Follow proven patterns for success