Task Workflow

Understanding the Claudear task lifecycle

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

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/{identifier}
2. Creates branch claudear/{identifier} (e.g., claudear/ENG-123 or claudear/N-ABC123-001)
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 use the task identifier:

Shared Resources

These are shared across all provider instances:

• Claude Code runner pool
• SQLite task store
• Webhook server (if Linear enabled)

Timeouts

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