Pi Missions # 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. [![npm](https://img.shields.io/npm/v/@groeponline/pi-missions.svg)](https://www.npmjs.com/package/@groeponline/pi-missions) [![downloads](https://img.shields.io/npm/dm/@groeponline/pi-missions.svg?label=downloads)](https://www.npmjs.com/package/@groeponline/pi-missions) [![CI](https://github.com/GroepOnline/pi-missions/actions/workflows/ci.yml/badge.svg)](https://github.com/GroepOnline/pi-missions/actions/workflows/ci.yml) [![Pi package](https://img.shields.io/badge/Pi-package-9b59b6.svg)](https://pi.dev/packages/@groeponline/pi-missions) ![License](https://img.shields.io/badge/license-MIT-green.svg)
## Start in 10 seconds ```bash pi install npm:@groeponline/pi-missions ``` Then inside Pi: ```text /mission start "Implement user auth" /mission next ``` When the feature is actually done: ```text /mission done "Tests pass and login flow verified" ``` Close Pi. Come back later. Resume the same mission: ```text /mission list /mission load /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.

Pi Missions durable lifecycle: create or load, advance features, persist state and resume later

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`](https://github.com/GroepOnline/pi-wishcraft): operator cockpit and fast idea capture. - **pi-missions**: durable plan, queue, evidence and recovery state. - [`pi-agent-orchestrator`](https://github.com/GroepOnline/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](https://github.com/GroepOnline/pi-missions/issues/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. ```text ~/.pi/missions/ ├── / │ ├── 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 ` / `/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 ```text 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](https://github.com/GroepOnline/pi-missions/issues/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 ```bash npm ci npm run check npm test npm run build npm run smoke:ci npm run verify:package ``` Run the built extension locally: ```bash 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: ```bash node dist/cli/index.js doctor ``` ## Releases User-visible changes are tracked in [CHANGELOG.md](./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