---
title: Task Workflow
description: Understanding the Claudear task lifecycle
section: How It Works
order: 4
---

# Task Workflow

Claudear manages tasks through a state machine that mirrors your project management workflow. Understanding this lifecycle helps you work effectively with automated development.

## State Machine

```
PENDING → IN_PROGRESS ⟷ BLOCKED → FAILED
              ↓
         COMPLETED → IN_REVIEW → DONE
```

### States

| State | Linear State | Notion Status | Description |
|-------|--------------|---------------|-------------|
| `PENDING` | Todo | ToDo | Task picked up, waiting to start |
| `IN_PROGRESS` | In Progress | In Progress | Claude is actively working |
| `BLOCKED` | In Progress | In Progress | Claude needs human input |
| `COMPLETED` | In Progress | In Progress | Work done, pushing code |
| `IN_REVIEW` | In Review | In Review | PR created, awaiting review |
| `DONE` | Done | Done | Merged and cleaned up |
| `FAILED` | (varies) | (varies) | Task failed (terminal) |

## Lifecycle Flow

### 1. Task Pickup (PENDING)

When you move a task to "Todo":

**Linear:**
- Webhook receives the state change event instantly

**Notion:**
- Poller detects the status change (within poll interval)

Then:
1. Claudear verifies it's a Todo state
2. Task record created in SQLite
3. Task enters `PENDING` state

### 2. Starting Work (IN_PROGRESS)

Claudear then:

1. Creates a git worktree at `.worktrees/claudear-{identifier}`
2. Creates branch `claudear/{provider}-{identifier}` (e.g., `claudear/linear-ENG-123`)
3. Updates task status to "In Progress"
4. Starts Claude Code session with the task prompt

### 3. Working

Claude Code:

1. Analyzes the task title and description
2. Explores the codebase
3. Implements the solution
4. Writes/updates tests
5. Commits changes

**Real-time updates:**
- Linear: Updates via label changes
- Notion: Updates "Current Status" property

### 4. Blocked (BLOCKED)

If Claude encounters an issue:

1. Outputs `BLOCKED: [reason]`
2. Claudear detects the blocked state
3. Posts a comment asking for help
4. Polls for new comments
5. When you reply, Claude resumes

### 5. Completion (COMPLETED → IN_REVIEW)

When Claude outputs `TASK_COMPLETE`:

1. Pushes branch to origin
2. Creates PR via `gh pr create`
3. Posts PR link to task
4. Moves task to "In Review"

### 6. Merging (DONE)

When you move the task to "Done":

1. PR is merged (if not already)
2. Worktree is cleaned up
3. Branch is optionally deleted
4. Task marked as `DONE`

## Multi-Provider Considerations

### Task Isolation

Each provider instance (team/database) has its own:
- Repository path
- WorktreeManager
- GitHubClient

Tasks from different instances never interfere with each other.

### Branch Naming

Branches include provider info to prevent conflicts:

| Provider | Example Branch |
|----------|----------------|
| Linear | `claudear/linear-ENG-123` |
| Notion | `claudear/notion-abc123-N-001` |

### Shared Resources

These are shared across all provider instances:
- Claude Code runner pool
- SQLite task store
- Webhook server (if Linear enabled)

## Timeouts

| Situation | Default | Configuration |
|-----------|---------|---------------|
| Blocked timeout | 1 hour | `BLOCKED_TIMEOUT` |
| Task stall detection | 5 minutes | Built-in |

## Error Handling

If a task fails:

- Error is logged
- Task gets a comment with the error
- Task enters `FAILED` state
- Worktree is preserved for debugging

To retry a failed task:
1. Fix the underlying issue
2. Move the task back to "Backlog"
3. Move it to "Todo" again
