pi-missions

pi-missions is a pi extension for long-running, milestone-based coding missions.

It is inspired by Factory Missions for Droid: plan carefully in chat, approve execution, let scoped workers make progress through git-backed handoffs, validate at milestone boundaries, and monitor status in Mission Control.

Independence note: pi-missions is not affiliated with Factory and is not a copy or port of Factory Missions. It was built independently, without access to Factory Missions source code, and uses only public product concepts as inspiration.

Stability note: this project is active development software. Commands, APIs, artifact schemas, and behavior may change before a stable release.

What it does

• Plans missions in chat with the mission-plan skill.
• Saves milestone-canonical mission artifacts under ~/.pi/missions/<mission-id>/.
• Runs one worker feature at a time in fresh child contexts.
• Requires worker handoffs and git commits.
• Validates at milestone boundaries with scrutiny and optional user-testing validators.
• Routes recoverable blocks to a dedicated runtime mission-orchestrator session.
• Shows read-only mission status in /mission-control and the compact footer.

pi-missions intentionally favors sequential writes, inspectable artifacts, and recoverability over parallel implementation speed.

Install

From npm, once published:

pi install npm:@awtotty/pi-missions

Quick start

Start a mission planning conversation:

/missions

Then chat normally in the current/main chat session:

I want to add a settings UI for project X.
Split it into safe milestones.
Make validation strict around persistence and keyboard navigation.
Save the plan.
Start it.

Execution starts only after explicit confirmation. During execution, keep using main chat as the human command, question, and override channel:

Status update.
Pause after current.
Why is it blocked?
Turn that validator finding into repair work.
Resume when safe.

Mission Control is optional read-only monitoring:

/mission-control

Commands

/missions [goal]             Start chat-first mission planning
/missions new [goal]         Alias for /missions [goal]
/missions run [id]           Start or resume a persisted mission
/missions resume [id]        Resume a paused mission
/missions status [id]        Show mission status
/missions list               List missions
/missions clear              Hide completed missions from default visibility
/missions models             Inspect role model defaults
/missions models <role> <model>
                             Set a role model default
/mission-control [id]        Open read-only Mission Control
/mission ...                 Alias for /missions

Execution model

The deterministic runner has three roles:

• planner (mission-plan skill): collaborates with the user before execution starts;
• worker: implements one feature, commits changes, and writes a handoff;
• validator: runs milestone-boundary scrutiny or user-testing validation.

The runtime mission-orchestrator is event-driven. It runs in the dedicated runtime orchestrator session after recoverable blocks such as validation failure, worker block, no-runnable-work, retry-limit exceeded, or ambiguous/stale state, and runs only for that event. It may repair mission metadata/control state through mission tools/APIs, resume, ask the user, rerun validation when safe, or leave the mission blocked. It must not edit repository implementation code by default.

Mission Control is read-only observability. Start, pause, resume, cancel, recovery, and plan changes stay in chat/tools/runtime orchestration. Main chat remains the human command/override channel.

Mission Control

Open Mission Control with:

/mission-control [mission-id]

Without an id, it shows a multi-mission overview grouped by Blocked / Failed, Running, Paused, Planned, and Completed. With an id, it opens that mission's detail view.

Useful keys:

q / esc             Close from overview; execution continues
↑ / ↓ or j / k      Move selection or scroll detail output
enter               Open selected mission detail
b / esc             Return from detail to overview
r                   Refresh
?                   Toggle help
g / G               Jump to top / bottom

Full guide: docs/mission-control.md.

Artifact layout

Mission data is global so repositories do not need .gitignore changes and Mission Control can monitor work across repos. Set PI_MISSIONS_HOME to override the storage root.

~/.pi/missions/<mission-id>/
  mission.json              # runtime state; features live under milestones[].features
  event-log.jsonl
  plan/
    objective.md
    features.json           # derived review artifact, not runtime state
    validation-contract.json
    validation-contract.md
  skills/
    worker/SKILL.md
    validator-scrutiny/SKILL.md
    validator-user-testing/SKILL.md
  recovery-packets/
    <timestamp>-<run-id>.json / .md
  runs/<run-id>/
    transcript.jsonl
    stderr.txt
    handoff.json / handoff.md
    validation-report.json / validation-report.md
    user-testing-report.json / user-testing-report.md

Recovery packet details: docs/runtime-orchestrator-recovery-artifacts.md.

Roadmap snapshot

Recently completed:

• milestone-canonical mission schema
• milestone-level deterministic run loop
• read-only multi-mission Mission Control
• event-driven runtime orchestrator recovery
• split mission-plan from runtime mission-orchestrator
• release-critical runtime modularization

Next:

• planning readiness checklist and run estimates
• user config overrides
• token/cost tracking and budgets
• durable mission resume
• headless/remote execution

Full roadmap: docs/roadmap.md.

Development

npm run typecheck       # TypeScript checks
npm test                # Vitest tests
npm run validate        # Mission regression harnesses
npm run build           # Compile publishable JS to dist/
npm run check           # Full local gate
npm pack --dry-run      # Package contents smoke check

Release notes and manual validation: docs/release-validation.md.

The package manifest loads the built extension entrypoint (dist/missions/index.js). Preserve public commands, tools, artifact paths, and the read-only Mission Control model when changing runtime code.

License and attribution

MIT. pi-missions is an independent pi extension inspired by the public Factory Missions for Droid announcement. It is not affiliated with Factory.