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