# 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):
   ```bash
   pi install npm:pi-subagents
   ```

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

### From npm (when published)

```bash
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

```bash
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