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.

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.

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 with two modes:

• --workstream <id> — launch one specific workstream.
• --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 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. 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; operator review is required

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.
• --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, and a summary with total counts 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

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.

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