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:

## <short plan title>

<context: one short paragraph. What the human wants and why.>

### 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 reminder cadence is copied from tintinweb/pi-tasks and the resync-after-compaction from tmonk/pi-goal-x.

Install

pi install npm:@wassname2/pi-goals

Or for development:

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. The full plan is printed in the transcript, then a menu asks Ready, Ready + compact, Grill me, open in $EDITOR, or keep planning. Grill me asks one understanding-check question and keeps plan mode active.
3. Work. The agent ticks subtasks, appends to ## Log and ## Learnings, fills evidence:, and calls CompleteGoal when a discriminator is satisfied. Every human reply in plan mode is saved verbatim under ## Interview. If it leaves the plan untouched for two turns, the working set is sent back with a short upkeep reminder.

Other commands: /goals --clear deletes this session's active plan file; /goals --judge <model-ref> picks a sign-off judge model (default: your current session model, else pi's default). The -- prefix keeps ordinary objectives such as judge model quality from being parsed as commands.

Prompts

All model-facing text lives in src/prompts.ts, in flow order.

Develop

pi -e ./src/index.ts        # load locally
npm test                    # vitest: judge argv invariants, appendLog, decideSignOff fail-forward
npm run typecheck
npm run lint

License

MIT