pi-mission

Factory.ai-inspired mission orchestration for pi

Install · Usage · How it works · Modes

Run structured, multi-phase development missions inside pi. Describe your goal, approve the plan, and let the orchestration layer track progress through milestones, features, and validation — with a real-time Mission Control overlay.

Inspired by Factory.ai Missions.

Install

From npm:

pi install npm:pi-missions

From GitHub:

pi install git:github.com/itisbryan/pi-missions

From a local checkout:

pi install /path/to/pi-missions

If pi is already running, use /reload to pick up the new extension.

Requires Pi v0.64.0+.

Usage

/mission Build a user authentication system

Pi opens a planning questionnaire — choose your mode, autonomy level, and optionally assign different models to different phases — then kicks off the mission.

Commands

| Command | Description | |---------|-------------| | /mission <description> | Start a new mission (interactive planner) | | /mission | Quick-check current mission status | | /mission-status | Detailed status with phase/feature durations | | /mission-features | Browse features grouped by milestone (full mode) | | /mission-validate | Show validation assertion status | | /mission-skip | Skip the current phase or feature | | /mission-done | Mark the entire mission as complete | | /mission-pause | Toggle pause/resume | | /mission-reset | Clear mission state and widget |

Keyboard shortcut

| Shortcut | Action | |----------|--------| | Ctrl+Shift+M | Open Mission Control overlay |

Mission Control

A dashboard overlay with inline actions — no need to type commands:

┌─ Current Feature ──────────────────┐ ┌─ Features ──────── 12/15 ─┐
│ cart-api                            │ │ ● cart-api                 │
│ skill: backend-worker               │ │ ✓ user-auth                │
│ milestone: checkout                 │ │ ✓ product-catalog          │
│                                     │ │ ○ payment-integration      │
│ preconditions                       │ ├─ Progress Log ────────────┤
│  • Auth service running             │ │ <1m  ● Feature started     │
│ expected behavior                   │ │ 5m   ✓ user-auth done      │
│  • Returns 200 with cart items      │ │ 23m  ⏸ Mission paused      │
└─────────────────────────────────────┘ └────────────────────────────┘
P: Pause  S: Skip  D: Done  R: Redirect  M: Models  V: Validate  Esc: Close

| Key | Action | |-----|--------| | P | Pause / Resume | | S | Skip current phase or feature | | D | Mark mission done | | R | Redirect — type a new instruction for the agent | | M | Edit per-phase model assignment | | V | Show validation contract status |

Modes

Choose your mode when starting a mission:

| Mode | Structure | Best for | |------|-----------|----------| | Standard | 6 phases: Architect → Review → Implement → Test → Audit → Verify | Most development tasks | | Full | Milestones + features + validation assertions | Large multi-feature projects | | Minimal | 3 phases: Plan → Build → Verify | Quick fixes and small changes |

Standard / Minimal — phase widget

🎯 Build user authentication
████▓░░░ 📐 Phase 2/6: Review Plan (1/6 done)

Full — feature widget

● Running  ██████████▓░░░  12/15 features
🎯 Build user authentication · Milestone: auth · Feature: jwt-tokens

Paused

⏸ PAUSED (3m) — Build user authentication
████▓░░░ Phase 2/6: Review Plan

How It Works

┌─────────────────────────────────────────────────────────────┐
│  pi session (cwd: /my-project)                              │
│                                                             │
│  /mission Build a CRM                                       │
│     │                                                       │
│     ├─► Planning questionnaire                              │
│     │     Mode? Standard / Full / Minimal                   │
│     │     Autonomy? Low / Medium / High                     │
│     │     Models? (optional per-phase assignment)           │
│     │                                                       │
│     ├─► Mission protocol injected into system prompt        │
│     │   on every turn (before_agent_start)                  │
│     │                                                       │
│     ├─► LLM output scanned after each turn                  │
│     │   (message_end) for:                                  │
│     │     Phase transitions ("Phase 1 complete")            │
│     │     Feature transitions ("Feature cart-api done")     │
│     │     Milestone transitions                             │
│     │     Assertion results ("VAL-AUTH-001 passed")         │
│     │     Spec approval ("Plan approved")                   │
│     │                                                       │
│     ├─► State persists in session entries                   │
│     │   (survives /compact and session restarts)            │
│     │                                                       │
│     └─► Widget + Mission Control show live progress         │
│                                                             │
│  Full mode: AI uses mission_update tool to register         │
│  features and assertions after spec approval                │
└─────────────────────────────────────────────────────────────┘

What gets injected into the system prompt

On every turn, the extension appends:

• Mission protocol — instructions for the current phase (planning, execution, audit, verify)
• Current status — mission description, phase/feature/milestone position, progress counts
• Autonomy guidance — when to pause based on Low/Medium/High setting
• Pause notice — if paused, tells the agent to wait for direction

Per-phase model assignment (optional)

Assign different models to different roles during the planner:

🧠 Planning & Architecture  →  claude-opus-4-6
🔨 Implementation           →  claude-sonnet-4
🔍 Code Review / Audit      →  claude-opus-4-6
✅ Validation               →  claude-opus-4-6

Models switch automatically when phases transition. Uses your actual modelRegistry — no hardcoded list.

Autonomy levels

| Level | Behavior | |-------|----------| | Low | Pause after every feature, wait for "continue" | | Medium | Pause at milestone boundaries and decision points (default) | | High | Run to completion, only pause on critical failure |

State persistence

Mission state is stored via pi.appendEntry() — custom entries survive /compact and session restarts. When you resume a session, the widget and session name are automatically restored.

/mission-reset appends a null marker that tells the restore logic to stay cleared — the old state won't reappear.

Full mode — mission_update tool

In full mode, a custom LLM-callable tool (mission_update) is registered. After spec approval, the AI calls it to:

• Add features to milestones
• Add validation assertions
• Update feature status (active / done / failed)

This keeps the state in sync with what the AI is actually doing, not just what it announces in text.

Architecture

extensions/
├── index.ts             # Thin orchestrator (~290 lines)
├── types.ts             # All interfaces (MissionState, Feature, Milestone, etc.)
├── config.ts            # Mission templates (standard / full / minimal)
├── state.ts             # Persistence + TypeBox runtime validation
├── tools.ts             # Custom LLM-callable tool (mission_update)
├── widget.ts            # Progress widget (phase bar / feature bar / pause)
├── mission-control.ts   # Mission Control overlay (P/S/D/R/M/V)
├── progress-log.ts      # Event timeline with relative timestamps
├── detector.ts          # Phase / feature / milestone / assertion detection
├── protocol.ts          # System prompt generation (planning, audit, verify)
├── planner.ts           # Interactive planning questionnaire
├── commands.ts          # 8 commands + Ctrl+Shift+M shortcut
└── utils.ts             # Shared helpers

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Lint
npm run lint

# Run tests
npm test

# Test in watch mode
npm run test:watch

# Test locally without installing
pi -e /path/to/pi-missions/extensions/index.ts

Tests

The test suite covers core logic that doesn't depend on the pi runtime:

tests/
├── state.test.ts     — state persistence, advancePhase, advanceFeature, addProgressEvent
├── detector.test.ts  — phase/feature/milestone/assertion detection patterns
└── utils.test.ts     — formatDuration, icons, extractText, truncate, generateId

Inspired By

• Factory.ai Missions — multi-agent orchestration with milestones, features, and validation
• Factory's orchestrator/worker architecture, validation contracts, and skill-aware execution patterns

License

MIT