# Mission Product Spec

This page describes the target mission model for Anteroom. It is a design and product-spec artifact, not a statement that every detail below is already shipped.

## Summary

A mission is a versioned, live execution plan that determines how work will happen in the real environment, then orchestrates that work across workflows, subagents, tools, and humans.

Mission is the layer above workflows:

- specs define what is wanted
- missions define how it will happen
- workflows, subagents, and tools execute parts of that plan

## Core Rules

- Every mission must have an explicit plan before execution starts.
- A mission may be created from a spec or a prompt.
- Prompt-created missions still produce a formal `v1` plan before any execution begins.
- Mission planning gathers context before planning: artifacts, code when relevant, available workflows/adapters, prior mission state, and RAG only when needed.
- The current plan is always visible as a live outline.
- Every plan change creates a new mission version.
- Completed history is immutable. Undo is modeled as new compensating work.
- All execution is auditable across versions, items, workflows, subagents, tools, and artifacts.

## Mental Model

```text
spec or prompt
    |
    v
context gathering
    |
    v
mission plan v1
    |
    v
execution
    |
    +--> workflow runs
    +--> subagents
    +--> tools
    |
    v
replans -> v2, v3, ...
```

## Specs, Missions, and Workflows

### Specs

Specs define intent:

- desired outcome
- constraints
- acceptance criteria
- reviewed task breakdown

Specs are the durable contract for what should exist.

### Missions

Missions define execution:

- what work items exist now
- what depends on what
- what is running
- what changed
- why the plan changed
- which execution path each item uses

Missions are the live, versioned source of truth for execution.

### Workflows

Workflows execute durable multi-step work under mission control. They are execution backends, not the top-level orchestration model.

## Planning Pipeline

Mission planning should behave like an environment-aware execution compiler, not prompt-to-checklist glue.

1. Resolve the intent source from a spec or prompt.
2. Classify the mission type: coding, docs, ops, research, or mixed.
3. Gather context:
   - referenced artifacts and specs
   - codebase, if the mission is code-related
   - available workflows and adapters
   - prior mission state and revisions
   - RAG or indexed knowledge when local context is insufficient
4. Build an execution model with workstreams, dependencies, risks, and likely execution paths.
5. Produce `mission version v1` with items, priorities, dependencies, bindings, and provenance.
6. Only then begin execution.

## Execution Tree

Mission is the top-level authority.

```text
mission
  -> version
    -> item
      -> workflow run
        -> subagent
          -> tool calls
      -> subagent
        -> tool calls
      -> manual or noop work
```

A mission may run multiple eligible items in parallel. A workflow may spawn subagents. A subagent may call tools. All of those branches remain children of the same mission.

## Versioning and Replanning

Each mission has a stable `mission_id` and a mutable head version.

- `mission` = long-lived container
- `mission_version` = immutable plan snapshot
- `mission_revision` = the diff or event that created the next version

Version increments when the plan changes, not when work merely progresses.

Version bump examples:

- add or drop item
- reprioritize
- change dependencies
- split or merge item
- hold or resume when that changes the plan
- change execution binding
- add new context that causes replanning

No version bump examples:

- item moves from `planned` to `active`
- workflow heartbeat
- log polling

If a mission is running and the user replans it, the system creates `vN+1`, preserves completed work, reconciles active work, reshapes future work, and continues execution against the new head version.

## Runtime Reconciliation

When a running mission is replanned, active work must be treated explicitly. Supported outcomes should be:

- `keep_running`
- `cancel`
- `supersede_on_completion`
- `replace_now`

Recommended default: keep active work running unless the new plan conflicts materially.

Completed work is never deleted from history. Undo is modeled as new compensating work such as:

- revert
- replace
- revalidate

## Mission Item States

- `planned`
- `eligible`
- `active`
- `completed`
- `failed`
- `blocked`
- `held`
- `cancelling`
- `cancelled`
- `superseded`
- `dropped`

## Concurrency Model

Mission execution is concurrent, but bounded.

Control knobs should include:

- mission-level max concurrent items
- lane limits
- workflow concurrency
- subagent concurrency and depth
- budget, runtime, and token caps

Parallel execution should be intentional, visible, and safe.

## Steering Model

Mission steering changes execution strategy in real time without silently rewriting the underlying spec.

Useful plan mutation operations:

- `add_item`
- `drop_item`
- `hold_item`
- `resume_item`
- `change_priority`
- `change_dependencies`
- `split_item`
- `merge_items`
- `change_execution_binding`

If a mission discovers a spec gap, it may propose a spec update, but the spec remains the authority for intent.

## Interaction Modes

Mission UX should distinguish between two modes.

### Connect

Attach the current chat session to a mission for ongoing steering.

- `aroom mission talk <id>` should open an interactive REPL attached to the mission
- `/mission use <id>` should attach from inside chat
- `/mission clear` should detach

Connected sessions can expose mission mutation tools.

### Mention

Use mission state as single-turn context without attaching the session.

- `@mission:<id>`
- `/mission mention <id>`

Mention should inject a mission snapshot for one turn only and should not register mission mutation tools.

## User-Facing Views

The primary mission view should be the live outline.

It should show:

- mission title
- current version
- ordered items
- dependencies
- blockers
- what is active now
- what just completed
- recent replans

Secondary views:

- versions: `v1 -> v2 -> v3`
- timeline: chronological event stream
- trace: mission -> item -> workflow/subagent -> tools/artifacts

## History Model

Nothing should disappear.

Mission history should retain:

- all mission versions
- revision diffs
- user steering commands
- item state transitions
- workflow runs
- subagent runs
- tool calls
- artifacts read and written
- failures, retries, cancellations, and compensation

The default UI should stay readable, but the raw execution detail should remain available for audit and drill-down.

## Event Model

Mission needs a first-class append-only event model.

Minimum events:

- `mission_created`
- `plan_compiled`
- `version_created`
- `replan_requested`
- `replan_applied`
- `item_added`
- `item_changed`
- `item_dropped`
- `item_state_changed`
- `workflow_started`
- `workflow_completed`
- `workflow_failed`
- `subagent_started`
- `subagent_completed`
- `subagent_failed`
- `tool_called`
- `artifact_read`
- `artifact_written`
- `compensation_added`
- `mission_completed`
- `mission_cancelled`
- `mission_failed`

## Approval Rules

Recommended approvals:

- destructive replans
- cancellation of active work
- rollback or compensation actions
- scope expansion beyond original intent
- risky execution-path changes

Safe additive replans can auto-apply.

## Recommended Product Definition

A mission is a versioned, concurrent, steerable execution plan with a live outline, real-time replanning, and full audit history across workflows, subagents, tools, and artifacts.
