> ## Documentation Index
> Fetch the complete documentation index at: https://abil-shrestha-tracer.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash Basic Usage theme={null}
# Get unblocked work in JSON format
tracer ready --json
```

```bash Filter by Priority theme={null}
# Get highest priority work
tracer ready --priority 1 --json
```

```bash Limit Results theme={null}
# Get top 5 ready tasks
tracer ready --limit 5 --json
```

> [!TIP]
>
> Always start your session with `tracer ready` to orient yourself. This shows you exactly what can be worked on without blockers.

### Parsing Ready Work

```bash theme={null}
# 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:

```bash Update Status theme={null}
# Update issue to in_progress
tracer update bd-1 --status in_progress
```

```bash With JSON Output theme={null}
# Get the updated issue back
tracer update bd-1 --status in_progress --json
```

> [!NOTE]
>
> 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

```bash theme={null}
#!/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:

```bash Create Bug theme={null}
# Create a bug you found
tracer create "Fix edge case in validation" -t bug -p 0 --json
```

```bash Link to Parent theme={null}
# Link it back to parent work with discovered-from
tracer dep add <new-issue-id> <parent-issue-id> --type discovered-from
```

### Example: Discovered Work

```bash theme={null}
# 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
```

> [!TIP]
>
> **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:

```bash Blocking Dependency theme={null}
# bd-2 is blocked by bd-1
tracer dep add bd-2 bd-1 --type blocks
```

```bash Parent-Child (Epic) theme={null}
# bd-3 is a subtask of epic bd-1
tracer dep add bd-3 bd-1 --type parent-child
```

```bash Related Work theme={null}
# bd-4 and bd-1 are connected but don't block
tracer dep add bd-4 bd-1 --type related
```

### 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**

```bash theme={null}
tracer update bd-1 --status in_progress
```

**2. Hit a Blocker**

```bash theme={null}
tracer update bd-1 --status blocked
```

**3. Back to Work**

```bash theme={null}
tracer update bd-1 --status in_progress
```

**4. Complete**

```bash theme={null}
tracer close bd-1 --reason "Completed successfully"
```

## 6. Complete Work

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

```bash Single Issue theme={null}
# Close the issue
tracer close bd-1 --reason "Implemented and tested"
```

```bash Multiple Issues theme={null}
# Close multiple issues at once
tracer close bd-1 bd-2 bd-3 --reason "All completed"
```

```bash With JSON Output theme={null}
# Get closed issues back as JSON
tracer close bd-1 --reason "Done" --json
```

> [!NOTE]
>
> 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:

```bash View Issue Details theme={null}
# View specific issue
tracer show bd-1 --json
```

```bash Overall Statistics theme={null}
# See project stats
tracer stats --json
```

```bash Check Blocked Work theme={null}
# See what's blocked and why
tracer blocked --json
```

## Complete Integration Example

Here's a complete agent workflow script:

```bash theme={null}
#!/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:

```bash theme={null}
# 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**
>
> ```bash theme={null}
> # 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**
>
> ```bash theme={null}
> # 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**
>
> ```bash theme={null}
> # 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](https://abil-shrestha-tracer.mintlify.site/integration/json-output.md)**
>
> Learn about JSON response formats

> **[Best Practices](https://abil-shrestha-tracer.mintlify.site/integration/best-practices.md)**
>
> Follow proven patterns for success


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.