pi-goals/README.md

pi-goals

Make a short list of goals in one Markdown plan file. The main Pi agent is a thin coordinator for a retained supervisor, which runs one foreground implementation worker at a time through pi-subagents.

The plan file looks like this:

## <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 and burneikis/pi-plan, it guides rather than guards. The plan resync after compaction follows tmonk/pi-goal-x.

Install

Requires pi-subagents 0.65.1 or newer. Install pi-processes so the supervisor can check managed processes.

pi install npm:pi-subagents
pi install npm:@aliou/pi-processes
pi install npm:@wassname2/pi-goals

Or for development:

git clone https://github.com/wassname/pi-goals && cd pi-goals && npm install
pi -e npm:pi-subagents -e .

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. Ready forks the retained supervisor and preserves the main context. Ready (compact) forks the supervisor, compacts its planning history before its first turn, then compacts the main session. The implementation worker starts later. Refine collects short notes. Edit opens the full plan in Pi's editor.

3. Work. The topology is:

   main coordinator
   └── retained supervisor
       └── foreground implementation worker
   

   The retained goal-supervisor rereads the full current plan on each direction or review and runs its packaged pi-goals-worker-v1 in the foreground. The worker must finish before the supervisor can inspect the repository and evidence or write a private approval checkpoint in .pi/pi-goals/approvals/. A correction starts a new foreground worker. Pi-goals stores no nested worker ID or status. The versioned name avoids ordinary name collisions. A user or project agent with the same name still overrides the package agent. The worker is the implementation writer. Main and supervisor block direct edit, write, and write-like shell commands, but can inspect and run standard verification commands. This is not a filesystem sandbox: allowed scripts and custom tools can still mutate. CompleteGoal is mechanical. It checks that worker/supervisor/process work is idle and that the latest review ID, goal block, clean worktree, and committed HEAD/tree still match. The review ID prevents stale approval; it is not a security boundary against a worker that deliberately writes Pi state. CheckGoalWork, FleetView, and /subagents-fleet inspect the retained tree and transcripts. Every human reply and Refine note in plan mode is saved verbatim under ## Interview. Pi and pi-subagents own normal compaction and retained-run recovery.

Other commands: /goals clear stops the retained tree and disconnects the active plan, preserving its file. /goals auto [minutes|off] changes the check interval; Ready enables 60 minutes. /goals model <model-ref> sets the supervisor model; /goals worker-model <model-ref> separately sets the implementation-worker model. Checks continue until all goals close, auto off, or clear.

Prompts

Planning and coordinator sign-off prompts live in src/prompts.ts. Supervisor registration and RPC calls live in src/worker.ts. The packaged worker contract lives in agents/pi-goals-worker-v1.md. The supervisor-only launch and approval gates live in src/supervisor-runtime.ts.

Manual check

1. Reload pi-goals with pi-subagents, create a small plan, and choose Ready. Open FleetView or run subagent({ action: "status", view: "fleet" }). It should show goal-supervisor and its foreground pi-goals-worker-v1, not sibling runs from the main session.
2. Ask the main session to edit a project file. Its direct edit, write, or shell redirection call should be blocked. Call CompleteGoal before a supervisor review. It should fail because no matching private approval exists.
3. Let the worker implement, commit, and save verify output. Ask the supervisor to inspect the plan, repository, evidence, and output. Its nested worker instruction should appear in the nested transcript. After it calls ApproveGoal, inspect the JSON under .pi/pi-goals/approvals/.
4. Call CompleteGoal with the exact goal text. It should tick only while the checkpoint's goal-block hash and committed clean repository still match. Change the plan block or worktree and retry; it should fail closed until a new supervisor review.

Develop

pi -e .  # after installing pi-subagents above
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