pi-mission-control

Visual mission orchestration extension for pi with agent hierarchy and durable state.

Overview

Mission Control provides a structured, visual approach to complex software development tasks. It orchestrates a hierarchy via the mission-orchestrator skill loaded into the main pi agent — the Orchestrator (Tech Lead/PM) delegates to Workers (Implementers) and Auditors (QA Reviewers) — to break down, execute, and verify work through durable file-based state.

Architecture Note: The Orchestrator is a skill representing the main user-facing pi agent behavior, not a standalone subagent. Only Worker and Auditor are spawned as subagents.

Features

• Agent Hierarchy: Heavy-model Orchestrator delegates to light-model Workers and Auditors
• Durable State: File-based state survives restarts and enables resume
• Visual TUI: Real-time progress tracking with phases, tasks, and status
• Quality Gates: Every task verified through Worker → Auditor PASS/FAIL cycle
• Memory: Short-term per-run learnings distilled into long-term cross-run knowledge

Installation

Prerequisites

1. Install pi-subagents (required):

   pi install npm:pi-subagents

2. Install pi-ask-user (required for structured approvals and guided interviews):

   pi install npm:pi-ask-user

From npm (when published)

pi install npm:pi-mission-control

Usage

Starting a Mission

Once the extension is loaded, use the /mission command:

/mission

This will:

1. Scaffold worker/auditor agents and skills into .pi/ if first use
2. Show the Mission Control TUI (idle state with "Init new mission" button)
3. When initiated, the Orchestrator interviews you and produces requirements

Mission Lifecycle

/mission
  ├─ Scaffolds worker/auditor agents + skills (first run)
  ├─ Shows idle TUI with "Init new mission" button
  └─ When initiated:
       1. mission-orchestrator → Interview user, produce 00-requirements.md
       2. mission-tech-lead → Design system → 01-architecture.md + 02-validation.md
       3. mission-pm → Break work into phases/tasks via add_phase/add_task tools
       4. mission-orchestrator → Execute via Worker → Auditor cycle
       5. mission-memory → Distill learnings to long_term.md

Resuming a Mission

To resume a previous mission:

resume mission run-20260411-143022

The Orchestrator will load the previous state from run.json and continue.

Architecture

Agents

| Agent | Model | Role | |-------|-------|------| | orchestrator | heavy (skill) | Tech Lead, PM, Interviewer. Main pi agent behavior via mission-orchestrator skill. Manages workflow and spawns subagents. | | worker | light (subagent) | Implementer. Executes tasks in isolated git worktrees. Spawned by orchestrator. | | auditor | light (subagent) | QA Reviewer. Verifies work against contracts with PASS/FAIL. Spawned by orchestrator. |

Skills

| Skill | Purpose | |-------|---------| | mission-orchestrator | Primary orchestration skill representing the main pi agent behavior. Loaded first, routes between requirements, architecture, planning, execution, and closeout. | | mission-research | Detailed requirements/interview workflow used by the orchestrator when requirements are missing or unclear. | | mission-tech-lead | Detailed architecture and validation workflow used by the orchestrator after requirements are approved. | | mission-pm | Detailed planning workflow used by the orchestrator to register phases/tasks. | | mission-memory | Closeout and long-term memory distillation workflow. |

Runtime Files

.pi/
├── agents/                      # Scaffolded subagent definitions
│   ├── worker.md
│   └── auditor.md
├── skills/                      # Scaffolded skill definitions
│   ├── mission-research/
│   ├── mission-tech-lead/
│   ├── mission-pm/
│   ├── mission-orchestrator/
│   └── mission-memory/
└── mission-control/
    ├── state.json               # Volatile: active_run_id, phase, status
    ├── memory/
    │   └── long_term.md         # Cross-run distilled knowledge
    └── runs/
        └── run-<timestamp>/
            ├── run.json         # Source of truth: phases, tasks, timestamps
            ├── 00-requirements.md
            ├── 01-architecture.md
            ├── 02-validation.md
            ├── short_term_memory.md
            └── tasks/
                └── <task-id>/
                    ├── contract.md
                    ├── worker-output.md
                    └── auditor-report.md

Development

Project Structure

pi-mission-control/
├── package.json              # Package manifest with pi configuration
├── tsconfig.json             # TypeScript configuration
├── src/
│   ├── index.ts              # Extension entry point
│   ├── state.ts              # State types and file helpers
│   ├── tools/                # Mission control tools
│   │   ├── scaffold.ts       # mission_scaffold (command-only)
│   │   ├── init.ts           # mission_init (command-only)
│   │   ├── add-phase.ts      # add_phase (agent tool)
│   │   ├── add-task.ts       # add_task (agent tool)
│   │   ├── update-phase.ts   # update_phase (agent tool)
│   │   ├── update-task.ts    # update_task (agent tool)
│   │   ├── mission-complete.ts
│   │   └── mission-resume.ts
│   └── tui/                  # TUI components (read-only observer)
│       ├── dashboard.ts
│       ├── header.ts
│       ├── phases-panel.ts
│       ├── tasks-panel.ts
│       ├── progress-bar.ts
│       ├── past-runs.ts
│       └── idle-view.ts
├── agents/                   # Worker/auditor templates (copied on scaffold)
├── skills/                   # Skill templates (copied on scaffold)
└── templates/
    └── state.json            # Initial state template

Scripts

npm run build      # Compile TypeScript to dist/
npm run dev        # Watch mode compilation
npm run typecheck  # Type-check without emitting

Testing Workflow

1. Make changes to source files in src/
2. Run npm run typecheck to validate TypeScript
3. Test with pi -e ./src/index.ts
4. Build with npm run build for production testing

Dependencies

Required Extensions

| Extension | Required | Purpose | |-----------|----------|---------| | pi-subagents | Required | Spawns Worker and Auditor subagents in isolated git worktrees | | pi-ask-user | Required | Structured Q&A for user approvals, interviews, and ambiguity resolution |

Peer Dependencies

These are provided by pi and should not be bundled:

• @mariozechner/pi-agent-core
• @mariozechner/pi-ai
• @mariozechner/pi-coding-agent
• @mariozechner/pi-tui
• @sinclair/typebox

Dev Dependencies

• typescript — TypeScript compiler
• @types/node — Node.js type definitions

License

MIT