Skip to main content

​
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: 
# 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 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 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: 
# 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: 
# 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 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

# 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

# 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

# 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

Build docs developers (and LLMs) love

Get started for freeTalk to us