Agents and Orchestration

With orchestration on, FlightDesk owns the phase and dispatches an agent at each step: a planning turn at Plan, a build turn at Build, a merge turn at Merge. With it off, the phase follows the pull request and QA, and you drive the work yourself. Both are supported; orchestration is off by default.

Turn it on at Project Settings → Orchestration — "FlightDesk dispatches agents on this project". It is refused without an agent to dispatch to, so create the agent first.

Agent Users and Keys

An agent is a user of kind AGENT in your organization, with its own API key. It is a member with an identity, which is what makes its actions attributable on the timeline.

Create one from Project Settings → Orchestration → Create an agent user, which mints the agent's organization-scoped API key in the same call. The key is shown once: write it straight into the runtime folder's .flightdeskrc and treat any transcript or log that captured it as exposed.

Over MCP the same two calls are create_agent and rotate_agent_key, both owner-or-admin only. Rotating revokes the agent's current keys and mints a fresh one.

An agent key is organization-scoped — it acts in one organization, and cannot reach another. Some things a key like this may not do at all: it cannot approve a plan, and it cannot clear a new-request triage flag. Those are human acts by design.

Binding an agent to a box

flightdesk agent-bind --path <folder> (MCP: bind_agent) records which folder on which machine an agent runs in. The folder's own .flightdeskrc is what supplies the credential, so a single box can host several agents for several organizations without them seeing each other's work. Credential precedence is described in the CLI Reference.

Which agent takes which kind of work

Project Settings → Orchestration maps dispatch kinds to agent users: a default, and optionally a different agent for planning and for building.

Native Claude Approvals

A cloud session will sometimes stop on a native Claude prompt — a permission card, or a question. Claude permission prompts and questions on the project decides what happens:

• The agent decides; dangerous or undecidable ones escalate (the default). The agent approves what the task needs, answers what it can from the task, and denies the rest. Destructive, secret-reading, force-push and out-of-scope requests are denied and escalated to the tech owner, then the organization owner. Every decision is recorded on the timeline — the agent records it with flightdesk questions decide, which is audited and pages nobody.
• A person decides every one. Every prompt becomes a blocking question routed to a person.

Either way, a prompt FlightDesk cannot classify is not guessed at. It raises a Hold flag, which stops further turns on that task until a person clears it. Same for an approval that resolved without a matching FlightDesk decision. See Pipeline and Gates.

Handing Over Work You Built Locally

You do not have to choose between building it yourself and letting the pipeline run it. Build it locally, open the pull request, and hand it over:

flightdesk task handoff --pr 412
flightdesk task handoff --pr https://github.com/acme/app/pull/412 --task <task-id>

The MCP equivalent is handoff_pull_request. Without --task it uses, or creates, the task for that pull request.

A hand-off is not a phase of its own — it is the end of a build turn that happened somewhere else. So it lands exactly where a build turn that pushed lands: waiting on CI. From there:

• CI goes green → straight to the QA gate, or to Merge if that gate is automatic.
• CI fails, or review threads are left unresolved → FlightDesk dispatches a fresh fix turn on the existing branch, which ends waiting on CI again. Once per pull request head, and counted against the project's dispatch limit so a hopeless pull request stops rather than looping.
• The task still has a live cloud session → the failure is relayed into that session instead of starting a new turn.

Work already in QA, merging, released or done has nothing to hand off, and the call says so.

Automatic Rebase

When approved work stops being mergeable because its base branch moved, FlightDesk asks the agent to rebase it. This is a turn of its own and never moves the phase.

By default the QA approval stands — a clean rebase changed nothing anybody looked at — and if conflicts had to be resolved, whoever approved it gets an FYI while the merge carries on. Turn on Send work back to QA when an automatic rebase had to resolve conflicts to have them look again instead. Clean rebases never send work back.

A rebase that fails raises a Blocked-by-failure flag.