pi-goals

Make a short list of goals in one Markdown plan file. The main chat keeps the high-level context, supervises a worker in a visible Herdr pane, and checks whether each goal is complete.

Abridged text from the isolated test, with approval and completion shown together. Paths are shortened; bracketed labels are annotations. Model names and token counts below illustrate the intended supervisor/worker split, not measurements from this capture.

+-----------------------------------------------------------+-----------------------------------------------------------+
| SUPERVISOR                                                | WORKER                                                    |
|                                                           |                                                           |
| Review .pi/plan/...-main.md                               | Task 2 — verify command run, real output saved:           |
| > Ready    Discuss    Edit    Cancel                      | - Exit code 0 (pass only)                                 |
|                                                           | - evidence/verified.log (112 bytes)                       |
| [scheduled prompt: hourly check-in]                       |   PASS: 9 bytes: verified + LF                            |
|                                                           |                                                           |
| The supervisor independently inspected both artifacts     | Task 3 — plan evidence filled                             |
| before sign-off.                                          |                                                           |
|                                                           | Completion report sent via Intercom to supervisor         |
| Schedule: job wS79fJFPbB removed;                         | 01a089c9. My pane remains open for the supervisor’s       |
| .pi/schedule-prompts.json shows 0 jobs.                   | independent inspection before sign-off.                   |
|                                                           |                                                           |
| ✓ verified.txt holds exactly the 9 bytes                  | ○ verified.txt holds exactly the 9 bytes                  |
|   verified + LF                                           |   verified + LF                                           |
|   evidence/verified.log records a real byte check         |   evidence/verified.log records a real byte check         |
|                                                           |                                                           |
| Agents · 1 running                                        | [idle widget still shows its earlier snapshot]            |
|   verified-bytes-worker [goals-worker]                    |                                                           |
|                                                           |                                                           |
| >                                                         | >                                                         |
| astra · 50k tokens                                        | terra · 200k tokens                                       |
+-----------------------------------------------------------+-----------------------------------------------------------+

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>

### Preferences

- preferred worker model: <provider/model>

### 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 (optional)

### Learnings (optional)

### Papercuts - problems, gotchas, suggestions (optional)

Related work

Like pi-milestones and burneikis/pi-plan, it guides rather than guards. The reminder cadence is copied from tintinweb/pi-tasks and the resync-after-compaction from tmonk/pi-goal-x.

Install

Requires Herdr. The package includes the worker, messaging and scheduled-prompt extensions. Remove separate installations of pi-subagents, pi-intercom and pi-schedule-prompt to avoid loading them twice.

pi install git:github.com/wassname/pi-goals@experiment/main-supervisor-edxeth

Copy agents/goals-worker.md into ~/.pi/agent/agents/, then start a fresh Pi session.

Or for development:

git clone -b experiment/main-supervisor-edxeth https://github.com/wassname/pi-goals
cd pi-goals && npm install
pi -e ./src/index.ts

Use

/goals

/goals opens the action menu. New plan 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, Discuss, Edit, or Cancel. Discuss continues the conversation. Edit opens the full plan in Pi's editor.
3. Work. Ready is the only review action that starts work. It opens the worker in a Herdr pane. The worker ticks subtasks, appends to ## Log and ## Learnings, and fills evidence:. The supervisor inspects the actual results and calls CompleteGoal when a discriminator is satisfied. They communicate through pi-intercom. After eight turns without a change above ## Log, the agent gets an upkeep reminder. The supervisor also sets an hourly check-in through pi-schedule-prompt.

Other commands: /goals stop pauses work; /goals resume continues it; /goals exit leaves goal mode, preserving the plan. /goals attach <path> reconnects an existing plan. /goals solo lets the main chat do the work after confirming other workers stopped; completion is then self-verification. /goals model <model-ref> picks the worker model. /schedule-prompt manages check-ins.

Stop workers before reloading the supervisor: the subagent package can otherwise crash it when a worker later exits. The scheduler deletes disabled jobs on reload. Restart the saved Pi session and reattach the plan.

Prompts

You can read all the prompts in conversation order in src/prompts.ts.

Develop

pi -e ./src/index.ts     # load locally; do not also load the installed copy
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

To measure recorded usage since the latest planning start:

node scripts/session-usage.mjs <supervisor.jsonl> <worker.jsonl>

This separates output, uncached input and repeated cached input. It excludes subprocess API calls. Isolated Herdr test setup.

License

MIT

Branch-specific edits: Pi/OpenAI.