@recynie/pi-goal

A focused Goal Mode for Pi: agree on what “done” means, keep the agent working, and verify the result independently.

@recynie/pi-goal turns a request into a testable GoalSpec before execution. It then continues long-running coding work across model turns and sends the final result to a fresh-context verifier that checks the workspace independently.

Why use it?

• Clarify requirements together: Before execution, the agent discusses ambiguous requirements with you and turns them into a clear and testable Goal. For trivial task, you can also propose a Goal directly without refinement (see commands).
• Verify independently: a separate verifier inspects the result before completion.
• Stay in control: review, edit, start, pause, resume, or cancel the current Goal.

Ideal use cases:

• The task is complex or its requirements are unclear.
• You want the agent to persue the goal autonomously with minimal intervention.

Install

# global installation
pi install npm:@recynie/pi-goal

# local installation
pi install -l npm:@recynie/pi-goal

# try without installing
pi -e npm:@recynie/pi-goal

Restart Pi or run /reload after installation.

Quick start

Create a Goal from a plain request:

/goal Add JSON output to the status command without breaking the existing text format

The agent will:

1. Investigate relevant workspace context and ask questions.
2. Propose a GoalSpec with verifiable outcomes for your approval.
3. Continue working across turns after you start the Goal.
4. Submit the result to an independent verifier.
5. Complete the Goal on verification success, or resume work with verifier feedback.

Run bare /goal at any time to review or control the Goal.

How it compares

The Pi package catalog includes several popular Goal extensions with different priorities. This project focuses on a lightweight, single-Goal workflow with collaborative requirements and independent verification.

Extension	Primary focus	Choose @recynie/pi-goal when you want
@narumitw/pi-goal	Autonomous single-objective continuation, budgets, recovery, and optional ordered goals	A user-approved GoalSpec and a separate workspace verifier as the completion gate
pi-goal-x	Multiple goals, structured task trees, ordered Sisyphus workflows, dashboards, and completion auditing	One focused Goal per session branch with fewer concepts and commands
pi-goal-list-loop-audit	Goals, queues, continuous improvement loops, subagents, and detached auditing	A smaller workflow for ordinary long-running coding tasks without queue or loop orchestration
pi-codex-goal	Codex-style goal tracking, continuation, usage accounting, and model-managed goal tools	Collaborative acceptance-criteria refinement followed by independent verification

Commands

/goal <main goal>          # create a draft and begin agent-assisted refinement
/goal                      # open the Goal Control Panel
/goal propose <main goal>  # approve the text and start execution immediately
/goal status               # show a non-interactive status summary
/goal pause                # pause an active or verifying Goal
/goal resume               # resume a paused Goal and restart execution
/goal edit                 # edit the draft or return an approved Goal to refinement
/goal cancel               # cancel the current Goal

Use /goal propose for simple or already well-specified tasks. It skips the refinement and starts execution immediately.

Independent verification

After the worker calls goal_submit, the extension starts a fresh verifier with:

• the approved goal, subtasks, and acceptance details;
• the exact final result shown to the user;
• access to inspect the workspace and run checks.

The verifier does not receive the worker conversation or worker-only suggestions. A pass completes the Goal. A failure returns actionable feedback to the worker and continues execution.

Goal controls and continuity

The /goal Control Panel shows the current GoalSpec and available actions. During refinement you can approve the draft, continue discussing it, or edit its JSON in your configured external editor.

Active work continues automatically when Pi is idle. Built-in limits pause the Goal after excessive automatic runs or repeated no-progress responses. The current release supports one Goal per session branch.

Update or remove

pi update npm:@recynie/pi-goal
pi remove npm:@recynie/pi-goal

You can also install the latest GitHub source:

pi install git:github.com/recynie/pi-goal

Development

npm install
npm run check

# run from a local checkout:
pi -ne -e ./src/index.ts --no-session

Project documentation:

• DESIGN.md — product and lifecycle design
• docs/architecture.md — state, lifecycle, and verification architecture
• docs/testing.md — automated and interactive testing

License

MIT. See LICENSE.