@groeponline/pi-missions 0.3.8 → 0.3.9
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 +40 -0
- package/README.md +129 -80
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,26 +7,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [0.3.9] - 2026-08-30
|
|
11
|
+
|
|
12
|
+
### Documentation
|
|
13
|
+
- rebuild package story and release notes (#15)
|
|
10
14
|
## [0.3.8] - 2026-08-30
|
|
11
15
|
|
|
12
16
|
## [0.3.7] - 2026-08-30
|
|
13
17
|
|
|
18
|
+
### Fixed
|
|
19
|
+
- 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.
|
|
20
|
+
|
|
14
21
|
## [0.3.6] - 2026-08-28
|
|
15
22
|
|
|
23
|
+
### Maintenance
|
|
24
|
+
- Added the standard ignore block for OS metadata, Xcode output, editor-local state, and local environment files.
|
|
25
|
+
|
|
16
26
|
## [0.3.5] - 2026-08-23
|
|
17
27
|
|
|
28
|
+
### Added
|
|
29
|
+
- Added a Pi package contract verifier covering package identity, catalog discovery metadata, shipped files, registry targeting, and Pi peer dependency rules.
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
- Hardened package resource-path validation, including containment checks and protection against in-root symlink cycles.
|
|
33
|
+
|
|
18
34
|
## [0.3.4] - 2026-08-22
|
|
19
35
|
|
|
36
|
+
### Changed
|
|
37
|
+
- Refreshed the public package status and Pi catalog metadata.
|
|
38
|
+
- Aligned lockfile package-version metadata with the published package version.
|
|
39
|
+
|
|
20
40
|
## [0.3.3] - 2026-08-22
|
|
21
41
|
|
|
42
|
+
### Maintenance
|
|
43
|
+
- Release metadata only; no runtime or source-code changes were introduced between `v0.3.2` and `v0.3.3`.
|
|
44
|
+
|
|
22
45
|
## [0.3.2] - 2026-08-22
|
|
23
46
|
|
|
47
|
+
### Maintenance
|
|
48
|
+
- Release metadata only; no runtime or source-code changes were introduced between `v0.3.1` and `v0.3.2`.
|
|
49
|
+
|
|
24
50
|
## [0.3.1] - 2026-08-22
|
|
25
51
|
|
|
52
|
+
### CI
|
|
53
|
+
- Updated GitHub Actions that still depended on the deprecated Node 20 action runtime to their current major versions.
|
|
54
|
+
|
|
26
55
|
## [0.3.0] - 2026-08-22
|
|
27
56
|
|
|
57
|
+
### Added
|
|
58
|
+
- Added the Orchestra execution-correlation contract (`CHE-142`) so spawned workers can carry and report orchestration execution context.
|
|
59
|
+
- Added worker and integration tests for Orchestra correlation behavior and documented the execution boundary.
|
|
60
|
+
|
|
28
61
|
## [0.2.1] - 2026-08-22
|
|
29
62
|
|
|
63
|
+
### Security
|
|
64
|
+
- Cleared all high-severity npm audit findings present in the previous release line.
|
|
65
|
+
|
|
66
|
+
### Changed
|
|
67
|
+
- Widened the Pi peer ranges to include the current `0.85.x` line (`<0.86.0`).
|
|
68
|
+
- Added a weekly peer-range drift workflow that opens an issue when the latest Pi release falls outside the declared compatibility range.
|
|
69
|
+
|
|
30
70
|
## [0.2.0] - 2026-08-22
|
|
31
71
|
|
|
32
72
|
### Added
|
package/README.md
CHANGED
|
@@ -1,93 +1,134 @@
|
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
</div>
|
|
12
|
-
|
|
13
|
-
`pi-missions` keeps the work alive when a Pi session ends. A mission carries its plan, task queue, state, history, evidence, and handoff context forward, so multi-step implementation can survive restarts, compaction, forks, and interruptions without rebuilding the plan from memory.
|
|
9
|
+
Keep a multi-step job alive across restarts, compaction, forks and handoffs without reconstructing the plan from chat history.
|
|
14
10
|
|
|
15
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) 
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
The public package is on the `0.3.x` line and is actively maintained as a durable local mission/runtime layer for Pi. The extension entrypoint, state management, mission commands, tools, analytics dashboard, CLI, database repositories, and tests are wired. Integration classes for GitHub/Slack/webhooks are still lightweight scaffolding and should not be advertised as production integrations yet.
|
|
13
|
+
</div>
|
|
20
14
|
|
|
21
|
-
|
|
15
|
+
## Why Pi Missions
|
|
22
16
|
|
|
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`.
|
|
17
|
+
Agent sessions are temporary. Real implementation work is not.
|
|
28
18
|
|
|
29
|
-
|
|
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.
|
|
30
20
|
|
|
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.
|
|
21
|
+
Use it when a task is too large for one prompt, one context window or one uninterrupted coding session.
|
|
34
22
|
|
|
35
|
-
##
|
|
23
|
+
## 30-second start
|
|
36
24
|
|
|
37
25
|
```bash
|
|
38
|
-
# Install the extension
|
|
39
26
|
pi install npm:@groeponline/pi-missions
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Inside Pi:
|
|
40
30
|
|
|
41
|
-
|
|
31
|
+
```text
|
|
42
32
|
/mission start "Implement user auth"
|
|
33
|
+
/mission status
|
|
34
|
+
/mission next
|
|
35
|
+
# work on the active feature
|
|
36
|
+
/mission done "Tests pass and login flow verified"
|
|
37
|
+
```
|
|
43
38
|
|
|
44
|
-
|
|
39
|
+
Resume later:
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
/mission list
|
|
43
|
+
/mission load <mission-id>
|
|
45
44
|
/mission status
|
|
45
|
+
```
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
47
|
+
## Execution loop
|
|
48
|
+
|
|
49
|
+
```mermaid
|
|
50
|
+
flowchart LR
|
|
51
|
+
A[Create or load mission] --> B[Pending feature]
|
|
52
|
+
B -->|/mission next| C[Active feature]
|
|
53
|
+
C -->|evidence accepted| D[Done]
|
|
54
|
+
C -->|cannot proceed| E[Blocked]
|
|
55
|
+
D -->|more ready work| B
|
|
56
|
+
D -->|all features complete| F[Mission complete]
|
|
57
|
+
E -->|another feature is ready| B
|
|
58
|
+
C --> G[history.jsonl]
|
|
59
|
+
D --> H[evidence/Fxxx.md]
|
|
49
60
|
```
|
|
50
61
|
|
|
51
|
-
|
|
62
|
+
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
63
|
|
|
53
|
-
|
|
54
|
-
npm ci
|
|
55
|
-
npm run check
|
|
56
|
-
npm test
|
|
57
|
-
npm run build
|
|
58
|
-
./scripts/smoke-test.sh
|
|
64
|
+
## What persists
|
|
59
65
|
|
|
60
|
-
|
|
61
|
-
pi -e ./dist/index.js
|
|
66
|
+
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
67
|
|
|
63
|
-
|
|
64
|
-
|
|
68
|
+
```text
|
|
69
|
+
~/.pi/missions/
|
|
70
|
+
├── <mission-id>/
|
|
71
|
+
│ ├── plan.json # current mission state and feature queue
|
|
72
|
+
│ ├── plan.json.bak # recovery copy
|
|
73
|
+
│ ├── history.jsonl # append-only transition/event history
|
|
74
|
+
│ ├── evidence/
|
|
75
|
+
│ │ └── Fxxx.md # completion evidence per feature
|
|
76
|
+
│ └── sessions/ # session attachment / handoff metadata
|
|
77
|
+
└── database/
|
|
78
|
+
└── pi-missions.db # SQLite analytics/repository data
|
|
65
79
|
```
|
|
66
80
|
|
|
67
|
-
|
|
81
|
+
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.
|
|
82
|
+
|
|
83
|
+
## Mission Control
|
|
84
|
+
|
|
85
|
+
`/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.
|
|
68
86
|
|
|
69
|
-
|
|
87
|
+
|
|
88
|
+
## Core capabilities
|
|
89
|
+
|
|
90
|
+
| Capability | What it does |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| Durable state | Persists mission plan, active pointer, history, evidence and session metadata locally. |
|
|
93
|
+
| Ordered work | Tracks `pending`, `active`, `blocked` and `done` features with dependencies and acceptance criteria. |
|
|
94
|
+
| Evidence-first completion | Saves explicit proof when a feature is marked complete. |
|
|
95
|
+
| Crash-safe writes | Uses backup/atomic state writes and file locking around mission mutation. |
|
|
96
|
+
| Handoffs | Reload the same mission in a later Pi session without rebuilding the plan. |
|
|
97
|
+
| Workers | Spawn and inspect a separate Pi worker for the active feature. |
|
|
98
|
+
| Recovery | Retry recorded errors, inspect debug state and migrate older mission schemas. |
|
|
99
|
+
| Templates | Scaffold common mission shapes such as bug fixes, refactors, docs and security audits. |
|
|
100
|
+
| Metrics | Records mission/session metrics and exposes dashboard/history views. |
|
|
101
|
+
|
|
102
|
+
## Slash commands
|
|
103
|
+
|
|
104
|
+
| Command | Purpose |
|
|
70
105
|
| --- | --- |
|
|
71
|
-
| `/mission new <title>` / `/mission start <title>` | Create a
|
|
106
|
+
| `/mission new <title>` / `/mission start <title>` | Create a mission. |
|
|
72
107
|
| `/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. |
|
|
108
|
+
| `/mission load <id>` | Attach an existing mission to the current session. |
|
|
109
|
+
| `/mission status` | Show progress, active feature and acceptance criteria. |
|
|
110
|
+
| `/mission next` | Activate the next ready feature. |
|
|
111
|
+
| `/mission done [evidence]` | Complete the active feature and persist evidence. |
|
|
112
|
+
| `/mission block <reason>` | Block the active feature with a reason. |
|
|
113
|
+
| `/mission run` / `/mission autopilot` | Run mission automation. |
|
|
80
114
|
| `/mission pause` / `/mission resume` / `/mission stop` | Control mission execution. |
|
|
81
|
-
| `/mission
|
|
82
|
-
| `/mission
|
|
83
|
-
| `/mission
|
|
84
|
-
| `/mission
|
|
85
|
-
| `/mission
|
|
86
|
-
| `/mission
|
|
115
|
+
| `/mission clear` | Detach the mission from the current session. |
|
|
116
|
+
| `/mission edit <feature-id>` | Edit feature state/criteria. |
|
|
117
|
+
| `/mission fork <reason>` | Create a linked alternative track from the active feature. |
|
|
118
|
+
| `/mission dashboard` | Open Mission Control. |
|
|
119
|
+
| `/mission metrics` | Show mission/session metrics. |
|
|
120
|
+
| `/mission history [filter]` | Inspect mission history. |
|
|
121
|
+
| `/mission debug` | Inspect recent runtime/debug information. |
|
|
122
|
+
| `/mission export [filename]` | Export a Markdown mission report. |
|
|
123
|
+
| `/mission templates ...` | List or scaffold built-in templates. |
|
|
124
|
+
| `/mission worker` | Spawn a worker for the active feature. |
|
|
125
|
+
| `/mission worker-status` | Inspect the active worker. |
|
|
126
|
+
| `/mission kill-worker` | Stop a worker. |
|
|
127
|
+
| `/mission migrate ...` | Inspect or migrate older mission state. |
|
|
87
128
|
|
|
88
129
|
## Agent tools
|
|
89
130
|
|
|
90
|
-
|
|
131
|
+
Pi Missions also exposes mission-native tools so an agent can advance work without pretending a feature is complete:
|
|
91
132
|
|
|
92
133
|
- `mission_feature_done`
|
|
93
134
|
- `mission_next_feature`
|
|
@@ -104,45 +145,53 @@ The extension registers these mission tools for agent workflows:
|
|
|
104
145
|
|
|
105
146
|
```text
|
|
106
147
|
src/
|
|
107
|
-
├── core/ #
|
|
108
|
-
├── commands/ # /mission command
|
|
109
|
-
├── tools/ #
|
|
110
|
-
├── engines/ #
|
|
148
|
+
├── core/ # state, transitions, migrations, extension lifecycle
|
|
149
|
+
├── commands/ # /mission command handlers
|
|
150
|
+
├── tools/ # agent-facing mission tools
|
|
151
|
+
├── engines/ # autopilot, completion, recovery, metrics, workers
|
|
111
152
|
├── database/ # SQLite schema and repository layer
|
|
112
|
-
├── templates/ #
|
|
113
|
-
├── ui/ #
|
|
114
|
-
├── utils/ #
|
|
153
|
+
├── templates/ # built-in mission templates
|
|
154
|
+
├── ui/ # terminal dashboard and UI helpers
|
|
155
|
+
├── utils/ # filesystem, context, markdown, logging helpers
|
|
115
156
|
└── cli/ # pi-missions CLI
|
|
116
157
|
```
|
|
117
158
|
|
|
118
|
-
|
|
159
|
+
GitHub, Slack and webhook integration classes are still lightweight scaffolding. They are not advertised as production integrations.
|
|
119
160
|
|
|
120
|
-
|
|
161
|
+
## Requirements
|
|
121
162
|
|
|
122
|
-
|
|
163
|
+
- Node.js `>=22.5.0` for the built-in `node:sqlite` driver.
|
|
164
|
+
- Pi packages compatible with the peer dependencies declared in `package.json`.
|
|
165
|
+
- Optional: install `better-sqlite3` in the host project to use it instead of `node:sqlite`.
|
|
123
166
|
|
|
124
|
-
|
|
167
|
+
## Local development
|
|
125
168
|
|
|
126
|
-
|
|
169
|
+
```bash
|
|
170
|
+
npm ci
|
|
171
|
+
npm run check
|
|
172
|
+
npm test
|
|
173
|
+
npm run build
|
|
174
|
+
npm run smoke:ci
|
|
175
|
+
npm run verify:package
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Run the built extension locally:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
pi -e ./dist/index.js
|
|
182
|
+
```
|
|
127
183
|
|
|
128
|
-
|
|
184
|
+
CLI diagnostics:
|
|
129
185
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
- `history.jsonl`: Append-style event log for transitions.
|
|
134
|
-
- `evidence/`: Completion proof and artifacts.
|
|
135
|
-
- `sessions/`: Session attachment and handoff metadata.
|
|
186
|
+
```bash
|
|
187
|
+
node dist/cli/index.js doctor
|
|
188
|
+
```
|
|
136
189
|
|
|
137
|
-
##
|
|
190
|
+
## Releases
|
|
138
191
|
|
|
139
|
-
|
|
192
|
+
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
193
|
|
|
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]`.
|
|
194
|
+
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
195
|
|
|
147
196
|
## License
|
|
148
197
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@groeponline/pi-missions",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.9",
|
|
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,
|