mirror of
https://github.com/wassname/pi-plan.git
synced 2026-09-26 14:10:23 +08:00
118 lines
4.5 KiB
Markdown
118 lines
4.5 KiB
Markdown
# pi-goals
|
|
|
|
Make a short list of goals in one Markdown plan file. This is easy to review, and a subagent can check whether each goal is complete.
|
|
|
|
The plan file looks like this:
|
|
|
|
```md
|
|
## <short plan title>
|
|
|
|
<context: one short paragraph. What the human wants and why.>
|
|
|
|
### User-visible result
|
|
|
|
<one concrete sentence naming the final artifact or behavior the human will inspect>
|
|
|
|
### User voice
|
|
|
|
- │ "<the human's requirement, quoted in full word for word (with spelling fixes)>"
|
|
|
|
### Goals
|
|
|
|
1. [ ] goal: <one short judgeable imperative outcome>
|
|
- subtle failure mode: <a way this could look done but isn't>
|
|
- discriminator: <the concrete observation that tells real success from that failure>
|
|
- tasks:
|
|
1. [ ] <subtask>
|
|
- evidence: (empty until sign-off)
|
|
|
|
### Future work / out of scope
|
|
|
|
### Log
|
|
|
|
### Interview
|
|
|
|
### Learnings
|
|
|
|
### Papercuts - problems, gotchas, suggestions
|
|
```
|
|
|
|
|
|
|
|
## Related work
|
|
|
|
Like [pi-milestones](https://github.com/Neuron-Mr-White/UniPi/tree/main/packages/milestone) and
|
|
[burneikis/pi-plan](https://github.com/burneikis/pi-plan), it guides rather than guards. The
|
|
reminder cadence is copied from [tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks) and the
|
|
resync-after-compaction from [tmonk/pi-goal-x](https://github.com/tmonk/pi-goal-x).
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pi install npm:@wassname2/pi-goals
|
|
```
|
|
|
|
Or for development:
|
|
|
|
```bash
|
|
git clone https://github.com/wassname/pi-goals && cd pi-goals && npm install
|
|
pi -e ./src/index.ts
|
|
```
|
|
|
|
## Use
|
|
|
|
```
|
|
/goals CSV export for the report view
|
|
```
|
|
|
|
`/goals` enters plan mode and starts a conversation; the objective is an optional seed. From there:
|
|
|
|
1. Plan. The agent explores read-only and drafts the plan.
|
|
2. Review. After Pi settles, the full plan is printed in the transcript. Check that User-visible
|
|
result names the final artifact or behavior you expect. The menu offers Ready, Refine, Edit, or
|
|
Cancel. Refine collects short notes. Edit opens the full plan in Pi's editor.
|
|
3. Work. Ready is the only review action that starts work. The agent ticks subtasks, appends to
|
|
`## Log` and `## Learnings`, fills `evidence:`, and calls `CompleteGoal` when a discriminator is
|
|
satisfied. Every human reply and Refine note in plan mode is saved verbatim under `## Interview`.
|
|
After eight turns without a change above `## Log`, the working set is sent back with a short upkeep
|
|
reminder.
|
|
|
|
Optional persistent perspective requires the separate `pi-subagents` package (`pi install
|
|
npm:pi-subagents`, then restart or reload Pi). `/goals steward on` forks one non-writing Oracle
|
|
when Ready is selected. Work waits for its plan decision. The child process exits after the
|
|
review, while its session is retained. The first `CompleteGoal` call resumes that same session for a
|
|
trajectory and scope check; after approval, a second call runs the normal fresh evidence judge. The
|
|
steward cannot complete goals or make unresolved human decisions. `/goals steward off` disables it.
|
|
Between reviews there is no running child process or model call. The retained session receives a
|
|
bounded contract view: evidence detail stays with the fresh judge, approved checkbox state is
|
|
normalized, and current goal status remains visible. The Oracle's profile includes inspection-only
|
|
bash by contract; pi-goals rejects its decision if pi-subagents reports a file-mutation effect. This
|
|
is not an OS sandbox. If pi-subagents is absent, Ready stays in planning after a visible RPC timeout;
|
|
install it, retry Ready, or use `/goals steward off`. The integration is process-local and does not
|
|
require `pi-intercom`.
|
|
|
|
Other commands: `/goals --clear` disconnects this session from its active plan, preserving the
|
|
versioned file on disk; `/goals --auto [minutes|off]` continues active goals after the agent settles
|
|
and then on that interval. It pauses after two automatic wakes with no working-plan change;
|
|
`/goals --judge <model-ref>` picks a sign-off judge model (default: your current session model, else
|
|
pi's default); `/goals steward [on|off|status]` controls the optional persistent plan steward. The
|
|
older `--` forms remain only for the existing clear, auto, and judge controls.
|
|
|
|
## Prompts
|
|
|
|
All model-facing text lives in [`src/prompts.ts`](src/prompts.ts), in flow order.
|
|
|
|
## Develop
|
|
|
|
```bash
|
|
pi -e ./src/index.ts # load locally
|
|
npm test # all unit, flow, and Pi RPC tests
|
|
npm run test:rpc # Pi RPC review flow with a local offline model
|
|
npm run typecheck
|
|
npm run lint
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|