Pi Missions

Keep long-running coding work alive after the chat is gone.

Turn a big implementation into a durable mission with ordered features, acceptance criteria, evidence and resumable state across Pi sessions.

Start in 10 seconds

pi install npm:@groeponline/pi-missions

Then inside Pi:

/mission start "Implement user auth"
/mission next

When the feature is actually done:

/mission done "Tests pass and login flow verified"

Close Pi. Come back later. Resume the same mission:

/mission list
/mission load <mission-id>
/mission status

Why Pi Missions

Agent sessions are temporary. Real implementation work is not. Pi Missions stores the plan, current feature, acceptance criteria, evidence, history and handoff state on disk so progress survives restarts, compaction, forks and context loss.

Use it when a job is too large for one prompt, one context window or one uninterrupted coding session.

The important bit is not the queue UI. It is that the active pointer, transition history and completion evidence survive the session that created them.

Where it fits

Pi Missions owns durable work state. Wishcraft captures lightweight ideas; Missions turns serious work into a resumable track; Agent Orchestrator executes parallel or isolated work when that becomes useful.

pi-wishcraft idea → pi-missions mission → pi-agent-orchestrator run

• pi-wishcraft: operator cockpit and fast idea capture.
• pi-missions: durable plan, queue, evidence and recovery state.
• pi-agent-orchestrator: agents, worktrees, swarms, schedules and execution handoffs.

Explicit non-goal: pi-missions ships no GitHub, Slack or webhook integrations — there are no such integration classes in this package, no network calls to those providers, and no webhook listeners. Mission state stays local (SQLite/JSONL under MISSIONS_ROOT). If provider integrations are ever proposed, production-readiness gates are tracked in #13.

Runtime contract

The agent works only on the active feature. Completion is explicit: /mission done or mission_feature_done records evidence before the queue advances. A blocked feature records its reason instead of being silently skipped.

What persists

By default missions live under ~/.pi/missions. MISSIONS_ROOT takes precedence over PI_MISSIONS_ROOT when you need a shared or custom absolute path.

~/.pi/missions/
├── <mission-id>/
│   ├── plan.json              # current mission state and feature queue
│   ├── plan.json.bak          # recovery copy
│   ├── history.jsonl          # append-only transition/event history
│   ├── evidence/
│   │   └── Fxxx.md            # completion evidence per feature
│   └── sessions/              # session attachment / handoff metadata
└── database/
    └── pi-missions.db         # SQLite analytics/repository data

The file-backed mission state is the resumable runtime record. SQLite is a structured repository/analytics layer; it does not replace the per-mission plan.json, history and evidence files.

Mission Control

/mission dashboard renders the terminal dashboard for the active mission. /mission status gives the compact progress view, while /mission metrics, /mission history and /mission debug expose deeper runtime information.

Core capabilities

| Capability | What it does | | --- | --- | | Durable state | Persists mission plan, active pointer, history, evidence and session metadata locally. | | Ordered work | Tracks pending, active, blocked and done features with dependencies and acceptance criteria. | | Evidence-first completion | Saves explicit proof when a feature is marked complete. | | Crash-safe writes | Uses backup/atomic state writes and file locking around mission mutation. | | Handoffs | Reload the same mission in a later Pi session without rebuilding the plan. | | Workers | Spawn and inspect a separate Pi worker for the active feature. | | Recovery | Retry recorded errors, inspect debug state and migrate older mission schemas. | | Templates | Scaffold common mission shapes such as bug fixes, refactors, docs and security audits. | | Metrics | Records mission/session metrics and exposes dashboard/history views. |

Slash commands

| Command | Purpose | | --- | --- | | /mission new <title> / /mission start <title> | Create a mission. | | /mission list | List saved missions. | | /mission load <id> | Attach an existing mission to the current session. | | /mission status | Show progress, active feature and acceptance criteria. | | /mission next | Activate the next ready feature. | | /mission done [evidence] | Complete the active feature and persist evidence. | | /mission block <reason> | Block the active feature with a reason. | | /mission run / /mission autopilot | Run mission automation. | | /mission pause / /mission resume / /mission stop | Control mission execution. | | /mission clear | Detach the mission from the current session. | | /mission edit <feature-id> | Edit feature state/criteria. | | /mission fork <reason> | Create a linked alternative track from the active feature. | | /mission dashboard | Open Mission Control. | | /mission metrics | Show mission/session metrics. | | /mission history [filter] | Inspect mission history. | | /mission debug | Inspect recent runtime/debug information. | | /mission export [filename] | Export a Markdown mission report. | | /mission templates ... | List or scaffold built-in templates. | | /mission worker | Spawn a worker for the active feature. | | /mission worker-status | Inspect the active worker. | | /mission kill-worker | Stop a worker. | | /mission migrate ... | Inspect or migrate older mission state. |

Agent tools

Pi Missions also exposes mission-native tools so an agent can advance work without pretending a feature is complete:

• mission_feature_done
• mission_next_feature
• mission_ask_user
• mission_block_self
• mission_fork
• mission_error_status
• mission_retry_error
• mission_spawn_worker
• mission_worker_status
• mission_kill_worker

Architecture

src/
├── core/        # state, transitions, migrations, extension lifecycle
├── commands/    # /mission command handlers
├── tools/       # agent-facing mission tools
├── engines/     # autopilot, completion, recovery, metrics, workers
├── database/    # SQLite schema and repository layer
├── templates/   # built-in mission templates
├── ui/          # terminal dashboard and UI helpers
├── utils/       # filesystem, context, markdown, logging helpers
└── cli/         # pi-missions CLI

Explicit non-goal: GitHub, Slack and webhook integrations are out of scope for this package (no integration classes, no provider network calls, no webhook listeners). They are not advertised as features; any future proposal must meet the gates tracked in #13.

Requirements

• Node.js >=22.5.0 for the built-in node:sqlite driver.
• Pi packages compatible with the peer dependencies declared in package.json.
• Optional: install better-sqlite3 in the host project to use it instead of node:sqlite.

Local development

npm ci
npm run check
npm test
npm run build
npm run smoke:ci
npm run verify:package

Run the built extension locally:

pi -e ./dist/index.js

Recovery behavior

Safe mission saves keep the previous valid plan.json as plan.json.bak. When the primary plan is unreadable or invalid, loading automatically tries the backup before giving up. Schema migrations create a separate timestamped plan.json.pre-migration-*.bak before rewriting state. Recovery is automatic for a corrupt primary plan; operators can inspect the backup files directly when diagnosing a failed migration or filesystem problem.

CLI diagnostics:

node dist/cli/index.js doctor

Releases

User-visible changes are tracked in CHANGELOG.md. GitHub Releases are generated from the matching changelog section and link the exact npm version.

The release helper also derives fallback notes from commit subjects when [Unreleased] is empty, so an automated publish cannot silently create another blank release entry.

License

MIT © GroepOnline