Task Workflow

Understanding the Clotion task lifecycle

Task Workflow

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

State Machine

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

States

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

Lifecycle Flow

1. Task Pickup (PENDING)

When you move a Notion card to "Todo":

Poller detects the status change
Clotion verifies it's a Todo status
Task record created in SQLite
Clotion ID assigned (CLO-001, etc.)
Task enters PENDING state

2. Starting Work (IN_PROGRESS)

Clotion then:

Creates a git worktree at .worktrees/{clotion-id}
Creates branch clotion/{clotion-id}
Updates Notion card:
- Status → "In Progress"
- Branch → branch name
- Current Status → "Starting work..."
Starts Claude Code session with the task prompt

3. Working

Claude Code:

Analyzes the card title and description
Explores the codebase
Implements the solution
Writes/updates tests
Commits changes

During this phase, the Current Status property updates in real-time:

"Reading files..."
"Writing code..."
"Running tests..."

4. Blocked (BLOCKED)

If Claude encounters an issue:

Outputs BLOCKED: [reason]
Clotion detects the blocked state
Updates Notion card:
- Blocked checkbox → ✓
- Current Status → reason
Polls for new comments
When you comment, Claude resumes

5. Completion (COMPLETED → IN_REVIEW)

When Claude outputs TASK_COMPLETE:

Pushes branch to origin
Creates PR via gh pr create
Updates Notion card:
- Status → "In Review"
- PR URL → GitHub PR link
- Current Status → "PR created"

6. Merging (DONE)

When you move the card to "Done":

PR is merged (if not already)
Worktree is cleaned up
Branch is optionally deleted
Task marked as DONE
Current Status → "Completed"

Notion Properties Updated

Property	When Updated	Example Value
Status	State changes	"In Progress"
Blocked	When blocked/unblocked	✓ / ✗
Current Status	Continuously	"Running tests..."
Clotion ID	On pickup	"CLO-042"
Branch	On worktree creation	"clotion/CLO-042"
PR URL	On PR creation	"https://github.com/..."

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
Notion card gets a comment with the error
Blocked checkbox is set
Current Status shows the error
Task enters FAILED state
Worktree is preserved for debugging

To retry a failed task:

Fix the underlying issue
Uncheck the Blocked checkbox
Move the card back to "Backlog"
Move it to "Todo" again