# Missions

Missions are an orchestration layer above workflows. A mission decomposes a goal (from a spec or a prompt) into a structured plan of items, manages their dependencies and execution, and tracks every change as an auditable revision.

## Key Concepts

- **Mission session** — a named plan with lifecycle status, source provenance, and referenced artifacts
- **Mission item** — a work unit with status, priority, adapter binding, lane, concurrency group, and hold state
- **Dependency** — an edge between items: item B depends on item A completing before it becomes eligible
- **Execution** — an attempt to run an item through an adapter (workflow, noop, or future backends)
- **Revision** — a snapshot of every plan mutation with the operations applied and the artifacts that informed the decision
- **Event** — a runtime event (launch, completion, failure, hold) for observability

## Architecture

```
Spec or Prompt
    │
    ▼
Mission Compiler  ──→  CompiledPlan / CompiledPatch
    │
    ▼
Mission Storage   ──→  Sessions, Items, Dependencies, Revisions
    │
    ▼
Mission Scheduler ──→  Evaluates eligibility, launches via adapters
    │
    ▼
Adapters          ──→  NoopAdapter (instant), WorkflowAdapter (enqueue)
```

The **scheduler** is the only launch authority. Tools and CLI commands mutate state; the scheduler reacts by evaluating eligibility and launching items through adapters.

## CLI Commands

### Create a mission from a spec

```bash
aroom mission create --spec @ns/spec/auth --adapter workflow --workflow-path defs/build.yaml
aroom mission create --spec @ns/spec/auth --profile parallel-review
```

This compiles the spec's approved tasks into mission items, previews the plan, and asks for confirmation before launching. Use `--launch` to skip confirmation. Use `--profile` to apply an execution profile that auto-selects adapters and configures lanes (see [Execution Profiles](#execution-profiles) below).

### Create a mission from a prompt

```bash
aroom mission create --prompt "Build the authentication module with login, signup, and password reset"
aroom mission create --prompt "Build auth module" --profile plan-then-execute
```

Uses the AI service to decompose the prompt into structured items. `--profile` applies execution preferences to the compiled plan.

### List missions

```bash
aroom mission list
aroom mission list --status active
```

### Show mission status

```bash
aroom mission status <session_id>
```

Shows items, progress, blockers, lanes, and referenced artifacts.

### Steer a mission conversationally

```bash
aroom mission talk <session_id>
```

Launches an interactive chat session with mission tools registered. You can:

- Ask about blockers: "Why is the deploy task blocked?"
- Add items: "Add a database migration task before the deploy"
- Hold items: "Hold the deploy task until I verify staging"
- Reprioritize: "Make the security audit highest priority"
- Drop items: "Drop the optional caching task"

### Update a plan

```bash
aroom mission update <session_id> --instruction "Split the backend task into API and database layers"
```

Compiles a structured patch from the instruction, previews the operations, and asks for confirmation. Use `--force` to apply operations targeting active items.

### View revision history

```bash
aroom mission revisions <session_id>
```

Shows every plan mutation with operation types, reasons, and the artifact references that informed each revision.

### Cancel a mission

```bash
aroom mission cancel <session_id>
```

## REPL Commands

Inside `aroom chat`, use `/mission` for quick access:

| Command | Description |
|---------|-------------|
| `/mission list` | List mission sessions |
| `/mission status <id>` | Show mission details |
| `/mission talk <id>` | Register mission tools in the current session |

After `/mission talk <id>`, all 10 mission tools become available to the AI for conversational steering.

## Adapters

Missions use adapters to execute items:

| Adapter | Behavior |
|---------|----------|
| `noop` | Instantly completes. For tracked work not executed by Anteroom. |
| `workflow` | Enqueues a workflow run. Scheduler polls until completion. |

Specify the adapter when creating a mission:

```bash
aroom mission create --spec @ns/spec/auth --adapter workflow --workflow-path defs/build.yaml
aroom mission create --spec @ns/spec/auth --profile hands-off
```

When using `--profile`, the compiler discovers available workflows, scores them against the profile's preferences, and auto-selects the best fit. Explicit `--adapter`/`--workflow-path` flags override profile-derived bindings.

## Execution Profiles

An execution profile captures reusable execution preferences — plan-first, parallel lanes, review gates, runner preferences — and translates them into concrete adapter bindings at compile time. Profiles bridge the gap between user intent ("work in parallel with review on each item") and the mission's item-level adapter/lane/dependency configuration.

### Built-in Profiles

| Profile | Description |
|---------|-------------|
| `default` | No special preferences; noop adapter, single lane |
| `plan-then-execute` | Adds a planning phase; execution items depend on planning completing first |
| `parallel-review` | Parallel lanes (limit 3) with review gate items after each work item; prefers `cli_claude` workflows |
| `hands-off` | Parallel execution (limit 3) with hold-on-failure escalation; prefers `cli_claude` workflows |

### How Binding Selection Works

When `--profile` is specified:

1. The compiler discovers all available workflow definitions (built-in + examples)
2. Each workflow is scored against the profile's preferences:
   - **Runner match** (40%): does the workflow use the profile's preferred runners?
   - **Input match** (30%): does the workflow accept the profile's required inputs?
   - **Tag match** (20%): do the workflow's tags match the profile?
   - **Structure match** (10%): does the workflow have gates/parallel steps matching the profile?
3. The highest-scoring workflow above the threshold (0.3) is selected
4. Items still on the `noop` adapter are bound to the matched workflow
5. If no workflow matches, items fall back to the profile's default adapter

Each item records a `_binding_reason` in its adapter config explaining why it was bound to a specific adapter — visible in the plan preview table.

### Precedence

Explicit CLI flags override profile-derived values:

- `--adapter workflow --workflow-path defs/build.yaml` always wins over profile selection
- `--profile` is applied after `--adapter` defaults, so items already bound by `--adapter` are not overridden

## V1 Limitations

- Mission is CLI-first. Web UI mission steering will come in a future release.
- `aroom mission talk` launches a chat session; full inline steering TUI is planned.
- No retry semantics. Failed items stay failed. Retry support is planned for a future release.
- Lane and concurrency limits are enforced by the scheduler, not configurable per-session yet.
