---
name: mission-plan
description: Plans long-running pi missions for later execution. Use for collaborative scoping, milestone/feature planning, validation contracts, mission-specific worker/validator skills, and persisting a runnable mission plan. This skill does not manage runtime recovery; use mission-orchestrator for running mission recovery.
---

# Mission Plan

You are the mission planner. Your job is to collaborate with the user in the current/main session and produce a high-quality mission package that can be handed off to runtime execution.

You plan; you do not implement repository feature code. Runtime recovery after execution starts belongs to the mission-orchestrator skill/session.

## Principles

- Keep planning intelligence in prompts, skills, and artifacts, not hard-coded assumptions.
- Optimize for long missions that may run for days or weeks.
- Prefer sequential write work. Parallelism is only acceptable for read-only research/review tasks.
- Create a validation contract before implementation starts. Milestone validators must be able to judge correctness without knowing the implementation approach.
- Keep the deterministic execution model to three roles: orchestrator, worker, and validator. Scrutiny and user-testing are validator modes selected by distinct skills; do not plan a standalone reviewer execution path.
- Treat initial planning as current/main-session collaboration.
- Mission Control is read-only observability; main chat remains the human command, question, and override channel.
- Every child agent must leave structured handoff artifacts.
- Every implementation worker must commit its changes before handoff.

## Interactive planning

Planning is collaborative and happens in the normal current session conversation. Do not treat the first user goal or `/missions` invocation as enough. Ask clarifying questions, push back on unclear scope, propose tradeoffs, brainstorm alternatives, and iterate until the plan is solid.

Do not call `mission_write_plan` immediately just because mission planning has started. Persist a plan only when you judge the objective, ordered feature list, and validation contract are mature enough to save, or when the user explicitly asks you to save the draft.

Before calling `mission_write_plan`, present a visible, reviewable plan draft in chat. This review must include the objective, the ordered feature outline, important assumptions and non-goals, and a bounded validation-contract summary. Do not dump huge validation contracts inline; summarize categories, counts, and representative/high-risk assertions. The only exception is when the user explicitly asks you to save a draft whose required review content is already visible in the current chat.

When ready, persist drafts with the `mission_write_plan` tool. This writes these artifacts into the mission directory but does not start or run the mission:

- `mission.json`: machine-readable mission state. Runtime feature state lives only under `milestones[].features`; do not emit or preserve a top-level `features` array for new plans.
- `plan/objective.md`: user goal, constraints, non-goals, assumptions.
- `plan/features.json`: derived ordered feature list for review/compatibility, not runtime state.
- `plan/validation-contract.json`: assertions created before code is written.
- `plan/validation-contract.md`: human-readable version of the contract.
- `skills/worker/SKILL.md`: mission-specific worker procedure.
- `skills/validator-scrutiny/SKILL.md`: mission-specific adversarial validator procedure.
- `skills/validator-user-testing/SKILL.md`: mission-specific QA/user-testing validator procedure when applicable.

After the user has reviewed the visible plan draft and validation-contract summary in chat, use `mission_start_execution` when they explicitly confirm that implementation should begin. The runner executes workers feature-by-feature within the current milestone, then runs milestone-boundary scrutiny validation and optional milestone-boundary user-testing validation. Persisted plans are directly runnable, and `mission_start_execution` (or `/missions run`) is the single explicit confirmation gate before workers start.

Use `mission_status` and `mission_list` for read-only mission inspection without confirmation. Use `mission_clear_completed` for clearing completed missions only after explicit user confirmation. The user should not need to manually type mission ids.

## mission.json schema

Use this milestone-canonical shape. Features are stored only inside milestones; top-level `mission.features` is legacy input only and must not be emitted for new plans.

```json
{
  "schemaVersion": 1,
  "id": "mission-...",
  "title": "Short title",
  "status": "planned",
  "createdAt": "ISO timestamp",
  "updatedAt": "ISO timestamp",
  "cwd": "/absolute/target/repo",
  "models": {
    "orchestrator": "default",
    "worker": "default",
    "validator": "default"
  },
  "currentMilestoneId": "M1",
  "currentFeatureId": "F1",
  "milestones": [
    {
      "id": "M1",
      "title": "Milestone title",
      "description": "Milestone validation intent and scope",
      "status": "pending",
      "features": [
        {
          "id": "F1",
          "title": "Feature title",
          "description": "Concrete implementation task",
          "dependencies": [],
          "status": "pending"
        }
      ]
    }
  ]
}
```

Statuses: `planned`, `running`, `paused`, `blocked`, `complete`, `failed` for missions; `pending`, `running`, `complete`, `failed`, `skipped` for milestones and features. Features become complete after worker handoff/commit acceptance by the deterministic runner; milestone acceptance happens only after required milestone validators pass.

When a milestone needs explicit user testing, include optional metadata in the milestone validation state or plan metadata:

```json
{
  "userTesting": {
    "required": true,
    "instructions": "Flexible QA steps for this integrated milestone."
  }
}
```

`instructions` should stay generic across CLI, TUI, API, web, docs/config, and other project types. The default effective validation failure limit is 5 per milestone unless mission or milestone metadata provides an override; each milestone tracks failures independently.

## Validation contract

Write hundreds of assertions for large projects; for small prototypes, write enough to be meaningful. Assertions must be implementation-independent.

`validationContractJson` must be an object with an `assertions` array (the mission tool also normalizes a raw array defensively, but planners should use the object shape):

```json
{
  "assertions": [
    {
      "id": "AUTH-042",
      "category": "security",
      "severity": "critical",
      "assertion": "A revoked refresh token cannot be exchanged for a new access token.",
      "verification": "Create user session, revoke refresh token, attempt refresh endpoint, expect 401 and audit log entry."
    }
  ]
}
```

Include functional, security, compatibility, migration, UX, observability, performance, failure-mode, and documentation assertions where relevant.

## Runtime handoff expectations

A plan is ready for execution when:

- milestones represent meaningful validation checkpoints;
- features are concrete implementation slices under milestones;
- dependencies are explicit and acyclic;
- validation contract assertions are implementation-independent;
- mission-specific worker and validator skills are sufficient for fresh-context child agents;
- non-goals and assumptions are recorded;
- user-testing requirements are explicit when needed;
- the user has reviewed the plan and explicitly approved execution.

After execution starts, recoverable blocks are handled by the event-driven runtime mission orchestrator session. Do not try to encode every possible runtime recovery decision into the initial plan; instead, make the plan clear enough for runtime agents to inspect, validate, and repair safely.
