Missions

mission is the single-repo hierarchy layer above chained runs.

That distinction matters because AgentXchain already uses initiative for multi-repo coordination. These nouns are not interchangeable:

• Mission: repo-local long-horizon grouping inside one repository
• Initiative: multi-repo coordinator grouping across repositories

If the product blurs those terms, the operator loses the hierarchy boundary. This page keeps the repo-local mission model explicit.

Why Missions Exist

One governed run is often too small for the actual delivery goal. Chained runs solve the execution problem by continuing work with inherited context, but they still need a durable grouping layer so the repo can answer a basic operator question:

What long-horizon goal are these chains advancing?

Mission artifacts provide that grouping layer. They let one repository track:

• the mission identity and goal
• attached chain lineage
• aggregate run and turn counts across those chains
• active repo-decision carryover
• derived mission status without opening raw chain reports one by one

Artifact And API Surfaces

Mission data is repo-local and file-backed:

Surface	Purpose
.agentxchain/missions/<mission_id>.json	Durable mission artifact with title, goal, timestamps, and attached chain_ids
.agentxchain/missions/plans/<mission_id>/<plan_id>.json	Durable mission-plan artifact with workstreams, dependencies, approval state, and launch_records
.agentxchain/reports/chain-<id>.json	Chain report referenced by a mission
GET /api/missions	Dashboard/API surface returning newest-first mission snapshots plus the latest mission summary
GET /api/plans	Dashboard/API surface returning newest-first plan snapshots, workstream launch states, and launch-record chain linkage

The dashboard Mission view reads both GET /api/missions and GET /api/plans. It is intentionally separate from the coordinator Initiative view.

Primary Operator Flow

AgentXchain now exposes two real repo-local mission workflows. Use the simpler direct path when one chained run can advance the mission cleanly. Use mission decomposition when the mission needs explicit workstreams, dependency review, and staged launches.

Direct chained execution

This is still the fastest path. Do not default to manual chain attachment if the chain can be mission-bound at run start.

1. Start a mission

agentxchain mission start \
  --title "Release hardening" \
  --goal "Eliminate version-surface drift across release tooling"

This creates a durable mission artifact under .agentxchain/missions/.

2. Run chained work bound to the mission

# Bind to the most recent mission
agentxchain run --chain --mission latest --auto-approve

# Or bind to an explicit mission ID
agentxchain run --chain --mission mission-release-hardening --auto-approve

This is the main operator path. When mission binding is active, AgentXchain auto-attaches the emitted chain report after completion. The operator does not need to remember a separate mission attach-chain step.

3. Inspect mission state

agentxchain mission show
agentxchain dashboard

Use mission show for terminal inspection and the dashboard Mission view for a repo-local overview of the latest mission, attached-chain lineage, and recent missions. When a mission has a plan, mission show also includes the latest plan status, completion percentage, and workstream status breakdown so one terminal command can answer basic mission-health questions.

Decomposed mission planning

Use this path when the mission needs reviewed workstreams instead of one undifferentiated chain.

1. Create the mission and first proposed plan

agentxchain mission start \
  --title "Release hardening" \
  --goal "Eliminate version-surface drift across release tooling" \
  --plan \
  --constraint "Keep release automation idempotent" \
  --role-hint dev \
  --role-hint qa

mission start --plan is a convenience layer, not a governance shortcut. It creates the mission artifact first, then generates exactly one proposed plan for that same mission. It does not auto-approve or auto-launch anything.

If you already have a mission, or you want deterministic offline planner input, use the plan command directly:

agentxchain mission plan latest \
  --planner-output-file ./planner-output.json \
  --constraint "Keep release automation idempotent" \
  --role-hint dev \
  --role-hint qa

This creates a proposal under .agentxchain/missions/plans/<mission_id>/<plan_id>.json. The artifact contains workstreams, dependency edges, phases, acceptance checks, and per-workstream launch_status.

2. Review and approve the latest plan

agentxchain mission plan show latest
agentxchain mission plan approve latest

Approval is latest-only and fail-closed. Approving a newer plan supersedes older active plan revisions for that mission.

3. Launch approved workstreams

# Launch a single workstream
agentxchain mission plan launch latest \
  --workstream ws-release-alignment \
  --auto-approve

# Or launch all ready workstreams sequentially
agentxchain mission plan launch latest --all-ready --auto-approve

mission plan launch is not bookkeeping-only. It records real workstream_id -> chain_id linkage in launch_records, then executes the workstream immediately through the existing governed run/chaining path using that same chain ID. --auto-approve passes through to the launched governed run exactly as it does on agentxchain run.

--all-ready launches every currently ready workstream one at a time, stopping on first failure. Blocked workstreams are never included. The --workstream and --all-ready flags are mutually exclusive.

If a launched workstream ends in needs_attention, retry that same workstream explicitly:

agentxchain mission plan launch latest \
  --workstream ws-release-alignment \
  --retry \
  --auto-approve

Retry preserves the older launch record for audit, allocates a new chain_id, and returns the plan from needs_attention to active execution. When every workstream reaches completed, the plan auto-transitions to completed too.

Autopilot — unattended wave execution

For lights-out execution of a full plan across dependency waves, use mission plan autopilot:

# Execute the entire plan unattended — launches waves until completion or failure
agentxchain mission plan autopilot latest --auto-approve

# With safety limits: max 5 waves, 10s cooldown between waves, skip failures
agentxchain mission plan autopilot latest \
  --max-waves 5 \
  --continue-on-failure \
  --cooldown 10 \
  --auto-approve

Autopilot loops: scan for ready workstreams → launch wave → wait for outcomes → re-scan → repeat. It stops when the plan completes, a workstream fails (unless --continue-on-failure), the wave limit is reached, or the operator sends SIGINT.

Each wave launches all currently ready workstreams in declaration order. Between waves, the autopilot reloads the plan from disk to pick up dependency-unblocked workstreams. The --max-waves flag (default: 10) prevents runaway execution. The --cooldown flag (default: 5 seconds) adds a pause between waves for operator visibility.

Autopilot records trigger: autopilot in provenance with the wave number, so every launched run is traceable back to the autopilot invocation and its specific wave.

Coordinator-bound mission plans

When a mission is bound to a multi-repo coordinator (mission start --multi), the plan system operates differently. Instead of allocating a repo-local chain_id and running a single-repo chain, mission plan launch dispatches through the coordinator and writes coordinator-mode launch records.

# Launch a coordinator-backed workstream
agentxchain mission plan launch latest --workstream ws-auth-rollout

This does not run a local chain. Instead it:

1. Loads the coordinator config and state from the mission's bound workspace.
2. Selects the next assignable repo for the workstream via coordinator routing rules (phase alignment, dependency satisfaction, repo availability).
3. Dispatches the repo-local turn through the coordinator dispatcher.
4. Writes a coordinator-mode launch record instead of a chain-based one.

Subsequent dispatches for the same workstream append to the same launch record. Each repo dispatch is an entry in repo_dispatches[]:

{
  "workstream_id": "ws-auth-rollout",
  "dispatch_mode": "coordinator",
  "super_run_id": "srun_1713400000_abc12345",
  "launched_at": "2026-04-18T00:10:00.000Z",
  "status": "launched",
  "completion_barrier": {
    "barrier_id": "ws-auth-rollout_completion",
    "type": "all_repos_accepted"
  },
  "repo_dispatches": [
    {
      "repo_id": "api",
      "repo_turn_id": "turn_abc123",
      "role": "dev",
      "dispatched_at": "2026-04-18T00:10:00.000Z",
      "bundle_path": "/path/.agentxchain/dispatch/turns/turn_abc123",
      "context_ref": "ctx_..."
    },
    {
      "repo_id": "web",
      "repo_turn_id": "turn_def456",
      "role": "dev",
      "dispatched_at": "2026-04-18T00:12:00.000Z",
      "bundle_path": "/path/.agentxchain/dispatch/turns/turn_def456",
      "context_ref": null
    }
  ]
}

Completion synchronization. Coordinator-backed workstreams do not complete from chain reports. Instead, mission plan show synchronizes the plan against coordinator history, barrier state, and repo-local turn outcomes:

• Accepted repo projections count toward workstream progress.
• Failed repo-local dispatches surface as repo_failures[] on the launch record.
• A satisfied completion barrier marks the workstream completed.
• Once completed, dependent blocked workstreams become ready.
• If all workstreams complete, the plan auto-transitions to completed.

The synchronized view exposes coordinator_progress per workstream: accepted_repo_ids, pending_repo_ids, failed_repo_ids, repo_count, accepted_repo_count, repo_failure_count, and completion_barrier_status.

Coordinator wave execution. Coordinator-bound missions support batch operations with coordinator-native wave semantics:

• mission plan launch --all-ready — dispatches all ready workstreams sequentially, executing one repo-local turn per workstream, and syncing barrier state after each dispatch.
• mission plan autopilot — runs wave-based unattended execution. Each wave dispatches all ready workstreams, executes repo-local turns, and syncs coordinator barriers. Dependent workstreams are unblocked across wave boundaries as barriers are satisfied. A 2-repo workstream needs at least 2 waves to complete (one repo per workstream per wave).
• mission plan launch --workstream <id> --retry — reissues one failed repo-local turn inside a needs_attention coordinator workstream, appends retry metadata to the coordinator launch record, and executes the reissued repo-local turn immediately.

Wave execution respects coordinator barrier semantics — completion comes from barrier satisfaction, not chain reports.

4. Inspect plan and launch state

agentxchain mission plan list
agentxchain mission plan show latest
agentxchain dashboard

The dashboard Mission view now combines mission snapshots with the latest plan, workstream launch table, and launch-record chain linkage. Operators should not need to read raw plan JSON just to see which workstream launched, completed, or needs attention.

CLI Commands

agentxchain mission start --title <text> --goal <text> [--id <mission_id>] [--plan] [--constraint <text>]... [--role-hint <role>]... [--planner-output-file <path>] [--json] [--dir <path>]
agentxchain mission list [--limit <n>] [--json] [--dir <path>]
agentxchain mission show [mission_id] [--json] [--dir <path>]
agentxchain mission attach-chain [chain_id|latest] [--mission <mission_id>] [--json] [--dir <path>]
agentxchain mission plan [mission_id|latest] [--constraint <text>]... [--role-hint <role>]... [--planner-output-file <path>] [--json] [--dir <path>]
agentxchain mission plan show [plan_id|latest] [--mission <mission_id>] [--json] [--dir <path>]
agentxchain mission plan list [--mission <mission_id>] [--limit <n>] [--json] [--dir <path>]
agentxchain mission plan approve [plan_id|latest] [--mission <mission_id>] [--dir <path>]
agentxchain mission plan launch [plan_id|latest] --workstream <id> [--mission <mission_id>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan launch [plan_id|latest] --workstream <id> --retry [--mission <mission_id>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan launch [plan_id|latest] --all-ready [--mission <mission_id>] [--auto-approve] [--json] [--dir <path>]
agentxchain mission plan autopilot [plan_id|latest] [--mission <mission_id>] [--max-waves <n>] [--continue-on-failure] [--cooldown <seconds>] [--auto-approve] [--json] [--dir <path>]

mission start

Creates a single-repo mission artifact. Mission IDs are slugged and normalized to the mission-... form unless you override them with --id.

Add --plan when you want the CLI to create the mission and first proposed plan in one pass. --constraint, --role-hint, and --planner-output-file only apply in that mode. mission start --plan --json returns a combined { mission, plan } payload instead of the mission-only snapshot.

mission list

Lists mission artifacts newest-first by updated_at.

mission show

Shows one mission by ID or the latest mission when no ID is provided. The summary includes attached chain counts, aggregate run and turn totals, latest terminal reason, active repo-decision count, and when available the latest plan's status, completion percentage, and workstream counts.

mission attach-chain

Manual fallback for chains that were not mission-bound when run --chain started.

# Fallback path only
agentxchain run --chain --max-chains 2
agentxchain mission attach-chain latest

If no explicit --mission is passed here, the command defaults to attaching the latest chain report to the latest mission.

mission plan

Generates a decomposition plan for an existing mission. The planner uses the mission goal plus optional constraints and role hints to produce dependency-ordered workstreams. The output is a durable plan artifact, not a fake pre-created swarm of chains.

Use --planner-output-file <path> when you want deterministic or offline planning input. The file must contain the same structured JSON the live planner would have returned. Parse and schema validation still fail closed.

mission plan show

Shows one plan by ID or the latest plan revision for a mission. The summary includes workstreams, dependencies, acceptance checks, launch_status, and any recorded launch_records.

For coordinator-bound plans, mission plan show synchronizes the plan against the coordinator's acceptance projection history, barrier state, and the latest repo-local turn outcome for each dispatched repo before rendering. This surfaces real-time coordinator_progress per workstream including accepted, pending, and failed repo IDs, repo_failure_count, completion barrier status, and aggregated repo counts. When the latest repo-local dispatch for a repo enters failed_acceptance, failed, conflicted, retrying, or a rejected terminal state, the workstream transitions to needs_attention and the coordinator launch record exposes repo_failures[]. Workstreams auto-transition to completed when their completion barrier is satisfied, and downstream blocked workstreams become ready.

mission plan list

Lists plan artifacts newest-first for the target mission. This is the audit surface when a newer approved plan supersedes an older proposal.

mission plan approve

Approves only the latest proposed plan for a mission and supersedes older active revisions. This is the review boundary before any workstream can launch.

mission plan launch

Launches approved workstreams. Behavior depends on whether the mission is coordinator-bound:

Single-repo missions (default):

• --workstream <id> — launch one specific workstream. Allocates a chain_id, records a chain-mode launch record, and executes through the governed run path.
• --workstream <id> --retry — retry one needs_attention workstream with a new launch record and chain ID while preserving the previous failed attempt for audit.
• --all-ready — launch all currently ready workstreams sequentially. Stops on first failure — remaining workstreams are skipped. Blocked workstreams are never included.

All single-repo modes validate the approval boundary and dependency satisfaction, record preallocated workstream_id -> chain_id launch records, execute through the governed run path, and reconcile outcomes from real chain results.

Coordinator-bound missions:

• --workstream <id> — dispatches the next assignable repo for the workstream through the coordinator. Writes a coordinator-mode launch record with dispatch_mode: "coordinator" and an append-only repo_dispatches[] array. Does not run a local chain — returns immediately with dispatch metadata.
• Coordinator launch records may also surface repo_failures[] when the latest repo-local dispatch for a repo fails. Those failures are projected from repo-local governed state/history, not guessed from pending barriers.
• --all-ready — dispatches all ready coordinator workstreams sequentially, executing one repo-local turn per workstream, and syncing barrier state between dispatches. Stops on first failure unless --continue-on-failure.
• --workstream <id> --retry — retries one retryable repo-local failure inside a needs_attention coordinator workstream. The CLI reissues the failed repo-local turn from current HEAD, rewrites its dispatch bundle, appends a new repo_dispatches[] entry with is_retry / retry_of, marks the old dispatch with retried_at / retry_reason, and executes the reissued turn immediately.
• Coordinator retry remains deliberately narrow even after autopilot auto-retry shipped: it only supports one active retryable repo failure at a time, it fails closed when a dependent workstream has already dispatched since the failed repo turn, and autopilot will only spend a session-scoped --max-retries budget on that same narrow retry path instead of inventing broader coordinator recovery.

The launch modes are mutually exclusive where they would conflict.

Shipped workstream launch states:

Launch Status	Meaning
ready	Workstream can be launched now
blocked	Dependency workstreams have not completed successfully yet
launched	Workstream has been launched and is still in flight
completed	Bound chain finished successfully and unblocks dependents
needs_attention	Bound chain failed or blocked, or a coordinator-backed workstream has one or more failed repo-local dispatches

Shipped plan states relevant to execution and follow-up:

Plan Status	Meaning
proposed	Plan exists but has not been approved
approved	Plan is launchable
superseded	Newer plan revision replaced this one
needs_attention	At least one launched workstream failed or blocked
completed	Every workstream reached completed and the plan auto-closed

mission plan autopilot

Unattended wave execution of an approved plan. Autopilot loops through dependency waves — launching all ready workstreams, recording outcomes, and re-scanning for newly-unblocked workstreams — until the plan completes, a failure stops execution, or a safety limit is reached.

Options:

• --max-waves <n> — maximum dependency waves before stopping (default: 10).
• --continue-on-failure — skip failed workstreams and keep launching ready ones instead of stopping on first failure.
• --auto-retry — coordinator-only: if a workstream enters needs_attention with one retryable repo-local failure, reissue it immediately inside the same autopilot session.
• --max-retries <n> — coordinator-only per-session retry budget for each (workstream_id, repo_id) pair (default: 1).
• --cooldown <seconds> — pause between waves for operator visibility (default: 5).
• --auto-approve — auto-approve run gates during execution.

Terminal conditions:

Condition	Exit	Reason
All workstreams completed	0	plan_completed
Workstream failed (no --continue-on-failure)	1	failure_stopped
Launchable work exhausted but failures remain (--continue-on-failure)	1	plan_incomplete
Wave limit reached	1	wave_limit_reached
Blocked with unsatisfiable dependencies	1	deadlock
Operator SIGINT	1	interrupted

JSON output (--json) includes the full wave structure: which workstreams launched in each wave, their outcomes, retry metadata (retried, retry_count, retried_repo_turn_id), and a summary with total counts, total_retries, and terminal reason.

Run Chaining Integration

Mission binding is part of the chained-run surface, not an afterthought:

agentxchain run --chain --mission <mission_id|latest>

You can also set the binding in config:

agentxchain.json

{
  "run_loop": {
    "chain": {
      "enabled": true,
      "mission": "latest"
    }
  }
}

CLI flags override config values.

Binding Failure Behavior

These cases are intentionally asymmetric:

• Explicit mission ID: --mission mission-release-hardening fails closed if the mission does not exist. That is a configuration error, so the chain aborts.
• latest binding: --mission latest warns and continues if no missions exist. That is a bootstrapping condition, not a reason to discard the chain work.

If you want the repo-local hierarchy from the beginning, create the mission first. If you forget, use mission attach-chain afterward as a repair path.

Derived Mission Status

Mission status is evidence-backed. The current shipped surface derives status from attached chain reports rather than inventing a separate hidden lifecycle:

Status	Meaning
planned	Mission exists but has no attached chain reports yet
progressing	Attached chains exist and none show attention or degradation signals
needs_attention	At least one attached chain reports operator_abort, parent_validation_failed, or contains a run with blocked or failed status
degraded	The mission references one or more missing chain reports

The dashboard and mission show surfaces summarize these derived states so operators can see the mission condition without opening every chain report manually. When a plan exists, mission show also reports the latest plan's completion percentage and workstream-status breakdown.

Mission Plan Status

Mission decomposition adds its own repo-local planning states. These are evidence-backed plan artifacts, not hidden coordinator phases:

Plan Status	Meaning
proposed	A new plan artifact exists and still requires review
approved	The latest reviewed plan may launch workstreams
superseded	A newer plan revision replaced this artifact
needs_attention	A launched workstream failed or blocked and the plan requires intervention
completed	Every workstream reached completed and the plan auto-closed

The dashboard Mission view exposes the latest plan plus older revisions so operators can see which plan is current without diffing raw JSON files.

Dashboard Mission View

The dashboard Mission view is the browser surface for repo-local mission inspection. It shows:

• latest mission identity and goal
• derived mission status
• aggregate chain, run, and turn counts
• latest chain ID and latest terminal reason
• active repo-decision count
• attached-chain lineage summaries
• latest plan summary with approval metadata
• per-workstream launch states and dependency visibility
• launch records binding workstreams to real chain_id values
• newest-first recent missions
• prior plan revisions for the active mission

This is not the coordinator Initiative view with a renamed label. Mission is repo-local. Initiative remains the multi-repo coordinator surface.

Error Cases And Recovery

No missions exist yet

agentxchain run --chain --mission latest warns and continues. The chain still runs, but there is no mission grouping until you create one.

Explicit mission ID does not exist

The chained run fails closed before execution. Fix the mission ID or create the mission first.

Plan launch target is unapproved, missing, or blocked

mission plan launch --workstream <id> fails closed when the plan is not approved, the workstream does not exist, or dependencies remain unsatisfied. The command surfaces the blocking workstream IDs instead of silently starting partial execution.

--all-ready with no ready workstreams

mission plan launch --all-ready fails closed when no workstreams have launch_status: ready. The error message shows the current status distribution (how many are blocked, launched, completed, etc.) so the operator can diagnose the state.

--all-ready partial failure

If any workstream fails during a batch launch, the remaining workstreams are skipped. The command reports which workstreams completed, which failed, and which were skipped, then exits non-zero.

Launched workstream execution fails

The workstream is marked needs_attention, the plan becomes needs_attention, and dependents remain blocked. AgentXchain does not silently auto-replan around a failed approved workstream.

Coordinator-bound launch blocked

mission plan launch --workstream <id> on a coordinator-bound mission fails when:

• The coordinator workspace is missing or unreadable.
• The coordinator state is not active.
• The workstream exists in the plan but not in the coordinator config.
• The coordinator is in a different phase than the workstream requires.
• The target workstream is already completed.
• No repo is assignable (entry repo is busy, blocked, or a barrier prevents dispatch).

The error message includes the specific block reason from the coordinator so the operator can diagnose without inspecting raw coordinator state.

--all-ready or autopilot on a coordinator-bound mission

Both are shipped coordinator wave surfaces now:

• mission plan launch --all-ready dispatches one repo-local turn for each currently ready workstream, synchronizes coordinator barrier state between dispatches, and stops on first failure unless --continue-on-failure is set.
• mission plan autopilot repeats that wave loop until the plan completes, a failure stops execution, launchable work is exhausted (plan_incomplete with --continue-on-failure), the wave limit is hit, or the operator interrupts the run.

These commands do not allocate repo-local chain_id values for coordinator workstreams. The coordinator remains the control plane, and workstream completion still comes from synchronized barrier satisfaction rather than synthetic chain reports.

Recovering a failed coordinator workstream

When a repo-local dispatch inside a coordinator workstream fails, the workstream becomes needs_attention, mission plan show exposes repo_failures[], and autopilot either stops (failure_stopped) or exits plan_incomplete after exhausting other launchable work.

Use this recovery path:

1. Run agentxchain mission plan show latest --json and identify the failed workstream_id, repo_id, and any repo_failures[] details.
2. Open the affected child repo and inspect its governed state with agentxchain status, agentxchain events, or agentxchain doctor.
3. If the failed repo-local turn is still active and the failure is retryable (failed or failed_acceptance), use targeted coordinator retry from the workspace root:

agentxchain mission plan launch latest --workstream <id> --retry

This fails closed when:

• the workstream is not in needs_attention
• the latest repo failure is conflicted, retrying, or another non-retryable state
• the failed repo-local turn is no longer active
• a dependent workstream has already dispatched since the failed repo turn

4. Otherwise repair the repo-local problem using the normal governed recovery surface for that repo:
   • agentxchain reissue-turn --turn <turn_id> when the work is valid but the dispatch baseline drifted
   • agentxchain reject-turn --turn <turn_id> --reassign --reason "<reason>" when the staged result must be retried
   • agentxchain step --resume --turn <turn_id> after clearing a retained block or escalation
5. Return to the mission surface and resume coordinator execution with either agentxchain mission plan launch latest --workstream <id> for a targeted restart or agentxchain mission plan autopilot latest --auto-retry --max-retries 1 to let the coordinator spend a bounded retry budget before falling back to the normal failure boundary.

Coordinator workstreams now support both targeted --retry and unattended autopilot --auto-retry, but the unattended path is intentionally narrow: one retryable repo-local failure at a time, current-session budget only, same downstream-dispatch safety guard as targeted retry.

Chain report missing from a mission

The mission snapshot degrades instead of crashing. The Mission dashboard/API surface reports the missing chain IDs so operators can see the drift.

Malformed mission artifact

Malformed mission JSON is skipped rather than blanking the whole mission surface.

See Also

• Run Chaining
• CLI Reference
• Multi-Repo Orchestration