@groeponline/pi-missions 0.3.8 → 0.3.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +44 -0
- package/README.md +142 -77
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,26 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.3.10] - 2026-08-30
|
|
11
|
+
|
|
12
|
+
### Maintenance
|
|
13
|
+
- prove durable mission fallback path (#17)
|
|
14
|
+
## [0.3.9] - 2026-08-30
|
|
15
|
+
|
|
16
|
+
### Documentation
|
|
17
|
+
- rebuild package story and release notes (#15)
|
|
10
18
|
## [0.3.8] - 2026-08-30
|
|
11
19
|
|
|
12
20
|
## [0.3.7] - 2026-08-30
|
|
13
21
|
|
|
22
|
+
### Fixed
|
|
23
|
+
- Removed the unrunnable `chef-linear-notion-sync` workflow caller (`GRO-1360`, #14) instead of shipping a repository workflow that could not execute with its local capabilities.
|
|
24
|
+
|
|
14
25
|
## [0.3.6] - 2026-08-28
|
|
15
26
|
|
|
27
|
+
### Maintenance
|
|
28
|
+
- Added the standard ignore block for OS metadata, Xcode output, editor-local state, and local environment files.
|
|
29
|
+
|
|
16
30
|
## [0.3.5] - 2026-08-23
|
|
17
31
|
|
|
32
|
+
### Added
|
|
33
|
+
- Added a Pi package contract verifier covering package identity, catalog discovery metadata, shipped files, registry targeting, and Pi peer dependency rules.
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
- Hardened package resource-path validation, including containment checks and protection against in-root symlink cycles.
|
|
37
|
+
|
|
18
38
|
## [0.3.4] - 2026-08-22
|
|
19
39
|
|
|
40
|
+
### Changed
|
|
41
|
+
- Refreshed the public package status and Pi catalog metadata.
|
|
42
|
+
- Aligned lockfile package-version metadata with the published package version.
|
|
43
|
+
|
|
20
44
|
## [0.3.3] - 2026-08-22
|
|
21
45
|
|
|
46
|
+
### Maintenance
|
|
47
|
+
- Release metadata only; no runtime or source-code changes were introduced between `v0.3.2` and `v0.3.3`.
|
|
48
|
+
|
|
22
49
|
## [0.3.2] - 2026-08-22
|
|
23
50
|
|
|
51
|
+
### Maintenance
|
|
52
|
+
- Release metadata only; no runtime or source-code changes were introduced between `v0.3.1` and `v0.3.2`.
|
|
53
|
+
|
|
24
54
|
## [0.3.1] - 2026-08-22
|
|
25
55
|
|
|
56
|
+
### CI
|
|
57
|
+
- Updated GitHub Actions that still depended on the deprecated Node 20 action runtime to their current major versions.
|
|
58
|
+
|
|
26
59
|
## [0.3.0] - 2026-08-22
|
|
27
60
|
|
|
61
|
+
### Added
|
|
62
|
+
- Added the Orchestra execution-correlation contract (`CHE-142`) so spawned workers can carry and report orchestration execution context.
|
|
63
|
+
- Added worker and integration tests for Orchestra correlation behavior and documented the execution boundary.
|
|
64
|
+
|
|
28
65
|
## [0.2.1] - 2026-08-22
|
|
29
66
|
|
|
67
|
+
### Security
|
|
68
|
+
- Cleared all high-severity npm audit findings present in the previous release line.
|
|
69
|
+
|
|
70
|
+
### Changed
|
|
71
|
+
- Widened the Pi peer ranges to include the current `0.85.x` line (`<0.86.0`).
|
|
72
|
+
- Added a weekly peer-range drift workflow that opens an issue when the latest Pi release falls outside the declared compatibility range.
|
|
73
|
+
|
|
30
74
|
## [0.2.0] - 2026-08-22
|
|
31
75
|
|
|
32
76
|
### Added
|
package/README.md
CHANGED
|
@@ -1,93 +1,146 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
<img src="https://raw.githubusercontent.com/GroepOnline/pi-missions/main/docs/images/missions_banner.png" alt="Pi Missions
|
|
3
|
+
<img src="https://raw.githubusercontent.com/GroepOnline/pi-missions/main/docs/images/missions_banner.png" alt="Pi Missions" width="100%">
|
|
4
4
|
|
|
5
5
|
# @groeponline/pi-missions
|
|
6
6
|
|
|
7
|
-
**
|
|
7
|
+
**Durable execution tracks for Pi coding agents.**
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Keep a multi-step job alive across restarts, compaction, forks and handoffs without reconstructing the plan from chat history.
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/@groeponline/pi-missions) [](https://www.npmjs.com/package/@groeponline/pi-missions) [](https://github.com/GroepOnline/pi-missions/actions/workflows/ci.yml) [](https://pi.dev/packages/@groeponline/pi-missions) 
|
|
10
12
|
|
|
11
13
|
</div>
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
## Why Pi Missions
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Agent sessions are temporary. Real implementation work is not.
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
Pi Missions gives a job a durable identity with a plan, ordered features, acceptance criteria, evidence, history and handoff state. The active session can end; the mission remains on disk and can be loaded again by Pi or another compatible worker.
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
Use it when a task is too large for one prompt, one context window or one uninterrupted coding session.
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
## Where it fits
|
|
22
24
|
|
|
23
|
-
|
|
24
|
-
- `npm test` passes in the current CI matrix.
|
|
25
|
-
- `npm run build` produces `dist/index.js`, `dist/index.d.ts`, `dist/cli/index.js`, and copied database schema assets.
|
|
26
|
-
- `./scripts/smoke-test.sh` confirms the Pi extension exports the default `piMissions` function.
|
|
27
|
-
- `node dist/cli/index.js doctor` works on Node.js 22 using `node:sqlite`.
|
|
25
|
+
Pi Missions owns **durable work state**: plans, features, evidence, history, recovery, and handoff context that must survive session boundaries. It does not replace Wishcraft's lightweight idea inbox and it does not execute multi-agent swarms itself.
|
|
28
26
|
|
|
29
|
-
|
|
27
|
+
`pi-wishcraft idea -> pi-missions mission -> pi-agent-orchestrator run` is the intended promotion path when a thought becomes durable work and then needs parallel or isolated execution.
|
|
28
|
+
|
|
29
|
+
- [`pi-wishcraft`](https://github.com/GroepOnline/pi-wishcraft): operator cockpit and fast idea capture.
|
|
30
|
+
- **pi-missions**: durable plan/task/evidence state.
|
|
31
|
+
- [`pi-agent-orchestrator`](https://github.com/GroepOnline/pi-agent-orchestrator): execution fabric for agents, worktrees, swarms, schedules, and handoffs.
|
|
30
32
|
|
|
31
|
-
|
|
32
|
-
- Pi coding agent packages compatible with the peer dependencies in `package.json`.
|
|
33
|
-
- Optional: install `better-sqlite3` manually in the host project if you prefer that native SQLite driver. Pi Missions will use it when available and fall back to `node:sqlite` otherwise.
|
|
33
|
+
GitHub, Slack and webhook integration classes remain lightweight scaffolding; production-readiness is tracked in [#13](https://github.com/GroepOnline/pi-missions/issues/13).
|
|
34
34
|
|
|
35
|
-
##
|
|
35
|
+
## 30-second start
|
|
36
36
|
|
|
37
37
|
```bash
|
|
38
|
-
# Install the extension
|
|
39
38
|
pi install npm:@groeponline/pi-missions
|
|
39
|
+
```
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
Inside Pi:
|
|
42
|
+
|
|
43
|
+
```text
|
|
42
44
|
/mission start "Implement user auth"
|
|
45
|
+
/mission status
|
|
46
|
+
/mission next
|
|
47
|
+
# work on the active feature
|
|
48
|
+
/mission done "Tests pass and login flow verified"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Resume later:
|
|
43
52
|
|
|
44
|
-
|
|
53
|
+
```text
|
|
54
|
+
/mission list
|
|
55
|
+
/mission load <mission-id>
|
|
45
56
|
/mission status
|
|
57
|
+
```
|
|
46
58
|
|
|
47
|
-
|
|
48
|
-
|
|
59
|
+
## Execution loop
|
|
60
|
+
|
|
61
|
+
```mermaid
|
|
62
|
+
flowchart LR
|
|
63
|
+
A[Create or load mission] --> B[Pending feature]
|
|
64
|
+
B -->|/mission next| C[Active feature]
|
|
65
|
+
C -->|evidence accepted| D[Done]
|
|
66
|
+
C -->|cannot proceed| E[Blocked]
|
|
67
|
+
D -->|more ready work| B
|
|
68
|
+
D -->|all features complete| F[Mission complete]
|
|
69
|
+
E -->|another feature is ready| B
|
|
70
|
+
C --> G[history.jsonl]
|
|
71
|
+
D --> H[evidence/Fxxx.md]
|
|
49
72
|
```
|
|
50
73
|
|
|
51
|
-
|
|
74
|
+
The agent is expected to work only on the active feature. Completion is explicit: `/mission done` or `mission_feature_done` records evidence before the queue advances.
|
|
52
75
|
|
|
53
|
-
|
|
54
|
-
npm ci
|
|
55
|
-
npm run check
|
|
56
|
-
npm test
|
|
57
|
-
npm run build
|
|
58
|
-
./scripts/smoke-test.sh
|
|
76
|
+
## What persists
|
|
59
77
|
|
|
60
|
-
|
|
61
|
-
pi -e ./dist/index.js
|
|
78
|
+
By default missions live under `~/.pi/missions`. `MISSIONS_ROOT` takes precedence over `PI_MISSIONS_ROOT` when you need a shared or custom absolute path.
|
|
62
79
|
|
|
63
|
-
|
|
64
|
-
|
|
80
|
+
```text
|
|
81
|
+
~/.pi/missions/
|
|
82
|
+
├── <mission-id>/
|
|
83
|
+
│ ├── plan.json # current mission state and feature queue
|
|
84
|
+
│ ├── plan.json.bak # recovery copy
|
|
85
|
+
│ ├── history.jsonl # append-only transition/event history
|
|
86
|
+
│ ├── evidence/
|
|
87
|
+
│ │ └── Fxxx.md # completion evidence per feature
|
|
88
|
+
│ └── sessions/ # session attachment / handoff metadata
|
|
89
|
+
└── database/
|
|
90
|
+
└── pi-missions.db # SQLite analytics/repository data
|
|
65
91
|
```
|
|
66
92
|
|
|
67
|
-
|
|
93
|
+
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.
|
|
94
|
+
|
|
95
|
+
## Mission Control
|
|
68
96
|
|
|
69
|
-
|
|
97
|
+
`/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.
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
## Core capabilities
|
|
101
|
+
|
|
102
|
+
| Capability | What it does |
|
|
70
103
|
| --- | --- |
|
|
71
|
-
|
|
|
104
|
+
| Durable state | Persists mission plan, active pointer, history, evidence and session metadata locally. |
|
|
105
|
+
| Ordered work | Tracks `pending`, `active`, `blocked` and `done` features with dependencies and acceptance criteria. |
|
|
106
|
+
| Evidence-first completion | Saves explicit proof when a feature is marked complete. |
|
|
107
|
+
| Crash-safe writes | Uses backup/atomic state writes and file locking around mission mutation. |
|
|
108
|
+
| Handoffs | Reload the same mission in a later Pi session without rebuilding the plan. |
|
|
109
|
+
| Workers | Spawn and inspect a separate Pi worker for the active feature. |
|
|
110
|
+
| Recovery | Retry recorded errors, inspect debug state and migrate older mission schemas. |
|
|
111
|
+
| Templates | Scaffold common mission shapes such as bug fixes, refactors, docs and security audits. |
|
|
112
|
+
| Metrics | Records mission/session metrics and exposes dashboard/history views. |
|
|
113
|
+
|
|
114
|
+
## Slash commands
|
|
115
|
+
|
|
116
|
+
| Command | Purpose |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `/mission new <title>` / `/mission start <title>` | Create a mission. |
|
|
72
119
|
| `/mission list` | List saved missions. |
|
|
73
|
-
| `/mission load <id>` |
|
|
74
|
-
| `/mission status` | Show
|
|
75
|
-
| `/mission
|
|
76
|
-
| `/mission
|
|
77
|
-
| `/mission
|
|
78
|
-
| `/mission
|
|
79
|
-
| `/mission block <reason>` | Block the active feature. |
|
|
120
|
+
| `/mission load <id>` | Attach an existing mission to the current session. |
|
|
121
|
+
| `/mission status` | Show progress, active feature and acceptance criteria. |
|
|
122
|
+
| `/mission next` | Activate the next ready feature. |
|
|
123
|
+
| `/mission done [evidence]` | Complete the active feature and persist evidence. |
|
|
124
|
+
| `/mission block <reason>` | Block the active feature with a reason. |
|
|
125
|
+
| `/mission run` / `/mission autopilot` | Run mission automation. |
|
|
80
126
|
| `/mission pause` / `/mission resume` / `/mission stop` | Control mission execution. |
|
|
81
|
-
| `/mission
|
|
82
|
-
| `/mission
|
|
83
|
-
| `/mission
|
|
84
|
-
| `/mission
|
|
85
|
-
| `/mission
|
|
86
|
-
| `/mission
|
|
127
|
+
| `/mission clear` | Detach the mission from the current session. |
|
|
128
|
+
| `/mission edit <feature-id>` | Edit feature state/criteria. |
|
|
129
|
+
| `/mission fork <reason>` | Create a linked alternative track from the active feature. |
|
|
130
|
+
| `/mission dashboard` | Open Mission Control. |
|
|
131
|
+
| `/mission metrics` | Show mission/session metrics. |
|
|
132
|
+
| `/mission history [filter]` | Inspect mission history. |
|
|
133
|
+
| `/mission debug` | Inspect recent runtime/debug information. |
|
|
134
|
+
| `/mission export [filename]` | Export a Markdown mission report. |
|
|
135
|
+
| `/mission templates ...` | List or scaffold built-in templates. |
|
|
136
|
+
| `/mission worker` | Spawn a worker for the active feature. |
|
|
137
|
+
| `/mission worker-status` | Inspect the active worker. |
|
|
138
|
+
| `/mission kill-worker` | Stop a worker. |
|
|
139
|
+
| `/mission migrate ...` | Inspect or migrate older mission state. |
|
|
87
140
|
|
|
88
141
|
## Agent tools
|
|
89
142
|
|
|
90
|
-
|
|
143
|
+
Pi Missions also exposes mission-native tools so an agent can advance work without pretending a feature is complete:
|
|
91
144
|
|
|
92
145
|
- `mission_feature_done`
|
|
93
146
|
- `mission_next_feature`
|
|
@@ -104,45 +157,57 @@ The extension registers these mission tools for agent workflows:
|
|
|
104
157
|
|
|
105
158
|
```text
|
|
106
159
|
src/
|
|
107
|
-
├── core/ #
|
|
108
|
-
├── commands/ # /mission command
|
|
109
|
-
├── tools/ #
|
|
110
|
-
├── engines/ #
|
|
160
|
+
├── core/ # state, transitions, migrations, extension lifecycle
|
|
161
|
+
├── commands/ # /mission command handlers
|
|
162
|
+
├── tools/ # agent-facing mission tools
|
|
163
|
+
├── engines/ # autopilot, completion, recovery, metrics, workers
|
|
111
164
|
├── database/ # SQLite schema and repository layer
|
|
112
|
-
├── templates/ #
|
|
113
|
-
├── ui/ #
|
|
114
|
-
├── utils/ #
|
|
165
|
+
├── templates/ # built-in mission templates
|
|
166
|
+
├── ui/ # terminal dashboard and UI helpers
|
|
167
|
+
├── utils/ # filesystem, context, markdown, logging helpers
|
|
115
168
|
└── cli/ # pi-missions CLI
|
|
116
169
|
```
|
|
117
170
|
|
|
118
|
-
|
|
171
|
+
GitHub, Slack and webhook integration classes are still lightweight scaffolding. They are not advertised as production integrations.
|
|
119
172
|
|
|
120
|
-
|
|
173
|
+
## Requirements
|
|
121
174
|
|
|
122
|
-
|
|
175
|
+
- Node.js `>=22.5.0` for the built-in `node:sqlite` driver.
|
|
176
|
+
- Pi packages compatible with the peer dependencies declared in `package.json`.
|
|
177
|
+
- Optional: install `better-sqlite3` in the host project to use it instead of `node:sqlite`.
|
|
123
178
|
|
|
124
|
-
|
|
179
|
+
## Local development
|
|
125
180
|
|
|
126
|
-
|
|
181
|
+
```bash
|
|
182
|
+
npm ci
|
|
183
|
+
npm run check
|
|
184
|
+
npm test
|
|
185
|
+
npm run build
|
|
186
|
+
npm run smoke:ci
|
|
187
|
+
npm run verify:package
|
|
188
|
+
```
|
|
127
189
|
|
|
128
|
-
|
|
190
|
+
Run the built extension locally:
|
|
129
191
|
|
|
130
|
-
|
|
131
|
-
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
192
|
+
```bash
|
|
193
|
+
pi -e ./dist/index.js
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Recovery behavior
|
|
197
|
+
|
|
198
|
+
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.
|
|
199
|
+
|
|
200
|
+
CLI diagnostics:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
node dist/cli/index.js doctor
|
|
204
|
+
```
|
|
136
205
|
|
|
137
|
-
##
|
|
206
|
+
## Releases
|
|
138
207
|
|
|
139
|
-
|
|
208
|
+
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.
|
|
140
209
|
|
|
141
|
-
|
|
142
|
-
2. Break the mission into features or load an existing plan.
|
|
143
|
-
3. Advance to the next unblocked feature with `/mission next`.
|
|
144
|
-
4. Let the agent work on the current feature.
|
|
145
|
-
5. Capture proof with `/mission done [evidence]`.
|
|
210
|
+
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.
|
|
146
211
|
|
|
147
212
|
## License
|
|
148
213
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@groeponline/pi-missions",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.10",
|
|
4
4
|
"description": "Persistent mission orchestration for Pi: durable plans, task queues, evidence trails, SQLite state, resumable execution, and handoffs across agent sessions.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|