Task Workflow

Every task in FlightDesk moves through a defined lifecycle. Most transitions happen automatically — FlightDesk listens to GitHub webhooks and the CLI to detect what's happening in real time.

The Full Lifecycle

Pending → Dispatched → In Progress → Branch Created → PR Open →
Preview Starting → Preview Ready → Review Running → Review Done →
QA Approved → Merged

Status Descriptions

Pending

The task has been created but work hasn't started. This is the planning state — you've defined what needs to be built, but haven't sent it to Claude Code yet.

Dispatched

You clicked Dispatch. FlightDesk generated a prompt for Claude Code and marked the task as sent. The CLI is watching for session activity.

In Progress

The CLI detected active Claude Code session activity for this task. Work is underway.

Branch Created

Claude Code created a git branch. The branch name is captured by the CLI and synced to the task. From this point, FlightDesk can correlate GitHub PR events to this task.

PR Open

GitHub sent a webhook for a new pull request on this branch. The PR number and URL are stored on the task. Review integrations activate at this point.

Preview Starting

A preview environment is being spun up. The container is being created, the repo is being cloned, setup commands are running.

Preview Ready

The preview container is healthy and serving traffic. A URL like fix-auth.preview.flightdesk.dev is attached to the task.

Review Running

One or more review integrations are actively checking the PR — SonarQube scan in progress, Copilot review pending, etc.

Review Done

All active review checks have completed. Results are visible in the Checks panel. This doesn't mean everything passed — it means the checks have finished and results are available.

QA Approved

A human tested the preview and approved the changes. This is a manual step: someone on the team clicks Approve in FlightDesk after verifying the preview works.

Merged

The PR was merged. FlightDesk receives the merge webhook from GitHub and marks the task complete.

How Transitions Happen

| Transition | Trigger | |---|---| | Pending → Dispatched | You click Dispatch in FlightDesk | | Dispatched → In Progress | CLI detects Claude Code session activity | | In Progress → Branch Created | CLI detects branch creation and syncs name | | Branch Created → PR Open | GitHub PR webhook | | PR Open → Preview Starting | Automatic (if preview is enabled for the project) | | Preview Starting → Preview Ready | Container health check passes | | PR Open → Review Running | Integrations activate after PR opens | | Review Running → Review Done | All integration checks complete | | Review Done → QA Approved | Manual — team member clicks Approve | | QA Approved → Merged | GitHub merge webhook |

The Three Human Decisions

FlightDesk automates everything it can, but you retain control at three points:

1. Defining the task — you write the title, description, and context
2. QA approval — you test the preview and confirm the changes work
3. Merging — you review the code and click merge (or configure auto-merge)

Everything else — branch tracking, PR events, review checks, preview URLs — happens without you needing to do anything.

Archived Tasks

Tasks can be archived at any point to keep your task list clean. Archived tasks are not deleted — they're still searchable and their full timeline is preserved. You can unarchive a task if work needs to resume.

Timeline

Every task has a timeline of events: status changes, check results, preview events, comments, and context updates. The timeline is append-only and provides a full audit trail of what happened and when.