pi-plan-task

A safe, approval-gated, and resumable Plan → Review → Approve → Build → Verify workflow for Pi.

pi-plan-task prevents agents from jumping directly into implementation. It turns software changes and document production into reviewed plans, bounded task contracts, and verified execution. Use it for existing repositories, new projects, technical specifications, research reports, and Word technical-solution deliverables.

Plan → Review → Approve → Execute one task → Verify → Continue or stop

Planning cannot modify product code or final deliverables. Execution starts only after the submitted plan is explicitly approved.

Key features

• Approval-gated execution — Plan mode cannot modify product code or final deliverables. Build tools become available only after explicit approval.
• Task-by-task delivery — The agent receives one bounded task contract at a time instead of implementing the whole plan at once.
• Verification before completion — Implementation and verification are separate states. A task is checked only after its declared checks pass and evidence is recorded.
• Safe resume and recovery — Plans, progress, approval state, block reasons, and verification evidence survive reloads, forks, and replacement sessions.
• Plan-drift detection — Approval is bound to the submitted plan, generated Build context, and task contracts. Structural changes revoke approval and stop execution.
• Controlled context and session cost — Tools are enabled only when needed, Build uses compact cross-task context by default, and clean per-task sessions prevent long plans from accumulating one large conversation.
• Flexible Build modes — Run one task interactively, all remaining tasks in the current session, or every task in a separate clean session.
• Code and document workflows — Apply the same approval process to software changes, specifications, reports, Word documents, and technical diagrams.
• Configurable tools, skills, and models — Configure Plan tools, DOCX and diagram skills, Build context, clean-session models, thinking levels, and optional token diagnostics.

Requirements and installation

Requirements:

• Pi with package/extension support.
• @juicesharp/rpiv-ask-user-question, which supplies the ask_user_question tool used for consequential decisions.
• Optional: a plannotator CLI executable on PATH for browser-based review.
• Word workflows: installed DOCX and technical-diagram skills selected through /pt-config.

Install the required question UI and this package:

pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:pi-plan-task

Restart Pi or run:

/reload

Quick start

Create a plan for an existing repository:

/pt-plan-existing Add OAuth login with GitHub and Google

Review the generated .plan_task/plan.md and .plan_task/task.md, then approve it:

/pt-plan-review      # optional; requires Plannotator
/pt-plan-approve

Execute the next task and inspect progress:

/pt-build
/pt-tasks

Use /pt-plan-new for a new or empty workspace. Approval does not start execution; run /pt-build, /pt-build all, or /pt-build sessions explicitly.

Other common inputs:

/pt-plan-existing docs/auth-spec.md reuse the existing session service
/pt-plan-new Build a CLI that converts Markdown files to HTML

How the workflow works

Plan

The agent inspects the workspace in a restricted mode and may write only:

.plan_task/draft/plan.md
.plan_task/draft/task.md

The plan records architecture, phases, risks, and decisions. The task file defines a numbered queue with dependencies, acceptance criteria, likely files, estimated scope, and repository-specific verification. Blocking decisions that cannot be resolved from requirements or repository evidence should be asked through ask_user_question.

Review and approve

After both drafts validate, they are submitted as .plan_task/plan.md and .plan_task/task.md. Read them directly or open the optional Plannotator review. Approve the submitted structure or reject it with revision feedback.

Approval is tied to the submitted plan, generated Build context, and task contracts. Structural edits after approval revoke approval instead of allowing execution to continue against changed requirements.

Build and verify

Build exposes the current approved task contract and permits implementation. Tasks move through:

pending → implementation-complete → verified

Finishing implementation does not mark a task complete. Its verification steps must pass and evidence must be recorded first. A blocked unfinished task stops the queue; all and sessions never skip it.

Commands

The extension registers exactly eight top-level commands. all, sessions, rework, and unblock are arguments, not separate commands.

Command	Purpose
/pt-config	Configure project or global settings interactively.
/pt-plan-new <request>	Plan work for a new or empty workspace.
/pt-plan-existing <request>	Plan work for an existing project.
/pt-plan-review	Open optional Plannotator review for the submitted plan.
/pt-plan-approve	Approve the submitted plan without starting execution.
/pt-plan-reject [feedback]	Reject the plan and initialize a revision draft.
/pt-build [all|sessions]	Execute approved tasks.
/pt-tasks [rework|unblock]	Inspect progress, reopen work, or restore a blocked task.

Planning and review

The command explicitly selects workspace type; the model does not infer it:

/pt-plan-new <request>
/pt-plan-existing <request>

A request may reference a specification file. Files up to 20,000 characters are inlined. Larger files provide a Unicode-safe preview of up to 10,000 characters plus the full path so the agent can search headings and read relevant ranges.

If incomplete work already exists, interactive mode asks before replacing it with different work; non-interactive mode refuses. Review is available while the workflow is ready, approved, or executing:

/pt-plan-review
/pt-plan-approve
/pt-plan-reject Split the migration into smaller reversible tasks

Build modes

Command	Best for	Behavior
/pt-build	Careful interactive work	Runs one task, then offers to continue here, continue in a new session, or stop.
/pt-build all	Small plans with enough context budget	Runs all remaining tasks in the current session without prompting between tasks.
/pt-build sessions	Long plans or strict isolation	Runs every remaining task, including the first, in its own clean session.

--all and --sessions are accepted aliases. Build modes are mutually exclusive. Legacy new, fresh, and approval flags are rejected.

Execution requires an approved workflow, a valid unchanged task queue, and at least one runnable task.

Progress, rework, and unblock

/pt-tasks
/pt-tasks rework 2
/pt-tasks unblock 2

• /pt-tasks opens a task list in the TUI and emits text in print, JSON, or RPC-oriented flows.
• rework 2 reopens task 2 and every later task, revokes approval, and requires review and approval again.
• unblock 2 restores the task after its dependency or decision is resolved.

Context and session efficiency

pi-plan-task limits unnecessary context growth without weakening approval or verification.

Mode-scoped tools

Plan and Build tools are enabled only while their phase needs them. The extension also activates ask_user_question only during Plan and Build, so idle conversations do not carry extension-added tool schemas. Leaving a phase removes only tools added by this extension.

Compact Build context

The current task contract is always injected in full. Cross-task plan context is controlled separately:

Mode	Behavior
compact	Inject approved build-context.md containing the cross-task overview, architecture decisions, and risks. This is the default.
full	Inject submitted plan.md up to maxChars.
path	Inject no plan body; point the agent to .plan_task/plan.md for selective reading.

This avoids repeatedly injecting the full plan for every task.

Clean task sessions

For long plans, use:

/pt-build sessions

A clean Build session does not inherit the planning conversation as parent context. It reconstructs the task from approved files, persisted workflow state, and the repository. The model and thinking level can inherit the launcher session or be configured explicitly.

Prompt layout and diagnostics

Stable workflow rules precede task-specific content to improve provider prompt-cache reuse. Phase instructions are injected once per Plan phase or Build task, stale phase framing is filtered from model context, and a resumed implementation-complete task receives verification-only framing.

Optional UI-only diagnostics report:

• estimated framing tokens and exact framing characters;
• current Pi context usage when available;
• Build plan-context mode and character count;
• current task-contract character count.

Counts use a stable characters / 4 estimate because provider tokenizers differ. Diagnostics are not appended to the conversation or sent to the model. Provider cache-read usage is unavailable at the framing injection point.

Document and Word workflows

The extension applies the same reviewable workflow to technical specifications, architecture documents, research reports, Word (.docx) technical solutions, and technical diagrams embedded in Word deliverables.

It orchestrates planning and delivery; it does not contain a DOCX editor or diagram engine. Use /pt-config to bind installed DOCX and diagram skills. Missing required capabilities block the task instead of triggering an unapproved fallback implementation.

Choose the workspace explicitly

/pt-plan-new Write a Word technical solution for a new multi-tenant SaaS system
/pt-plan-existing Write a Word technical solution based on this project

• /pt-plan-new treats the workspace as new or empty.
• /pt-plan-existing treats it as an existing project.
• Ordinary code plans remain unchanged unless the request explicitly requires Word.
• The workflow creates a new DOCX; DOCX template input is not supported.

The planner presents two or three complete outline alternatives for confirmation before finalizing a Word plan.

Document task sizing

Document work is divided by chapter boundaries, target pages or words, diagram count, evidence scope, and independent themes—not by the number of final files.

Area	Rule
Writing scope	One first-level chapter or two to three tightly related second-level sections per task.
Maximum task size	10 pages or 6,000 words/Chinese characters.
Diagram budget	At most three related diagrams per writing task.
Intermediate output	Every chapter task writes to a distinct content/*.md file.
Required plan sections	Document Work Breakdown and Quality and Verification.
Disallowed task	A single task that writes the entire document.

Plans map chapters to task IDs, intermediate paths, size targets, diagrams, dependencies, and checks. The approved queue separates:

1. creation of root AGENTS.md;
2. chapter drafting;
3. diagram generation through the configured skill;
4. consistency and coverage review;
5. DOCX assembly through the configured skill;
6. structural validation;
7. visual layout review;
8. final delivery verification.

Task count follows the approved outline and quality stages; there is no fixed minimum task count or 100-page threshold. Prefer /pt-build sessions for long documents.

Task contracts and verification

.plan_task/task.md is the canonical execution queue:

# Tasks

- [ ] 1. Add the login API
- [ ] 2. Add the login UI

## Task 1: Add the login API

**Description:** Reuse the existing authentication service.

**Acceptance criteria:**
- [ ] Invalid requests return a validation error.
- [ ] Valid requests create a session.

**Verification:**
- [ ] Run the focused authentication tests.
- [ ] Run the typecheck.

**Dependencies:** None.

**Files likely touched:** `src/auth/`, `tests/auth/`.

**Estimated scope:** S.

Every top-level task must have one matching ## Task N: Title contract. Nested checkboxes are criteria, not execution-completion markers. Do not manually check top-level tasks; successful verification does that.

During Build, the model uses the plan_task tool:

Action	Behavior
status	Read workflow and task status.
complete	Record implementation-complete; it does not check the task.
verify	Require non-empty evidence, check the task, and permit progression.
block	Require a reason and remember the previous active state.
unblock	Restore the task to that previous state.

Example:

{"action":"complete","id":1}
{"action":"verify","id":1,"reason":"Focused auth tests and typecheck passed"}

Invalid actions fail without partially changing workflow files.

Project files and safety

.plan_task/
├── plan.md           # submitted plan; immutable during execution
├── build-context.md  # approved compact cross-task context
├── task.md           # canonical execution queue
├── state.json        # workflow and per-task runtime state
├── draft/            # planning or revision drafts
│   ├── plan.md
│   └── task.md
├── history/          # submitted-plan snapshots
└── .lock/            # short-lived workflow lock

Safety guarantees:

• Plan mode allows configured read-only tools but restricts write and edit to the two draft files.
• Shell and implementation tools are blocked during planning.
• Submitted plans, workflow state, history, product files, and final deliverables cannot be modified before approval.
• Repository and specification content are treated as untrusted project data.
• Approval stores a SHA-256 structure hash derived from the plan, generated Build context, and task contracts.
• Normal top-level checkbox progress is normalized, so successful verification does not revoke approval; structural edits do.
• Writes use an in-process queue, project lock, temporary files, atomic replacement, and rollback for multi-file submissions.
• Malformed or inconsistent state fails closed instead of guessing.

Do not hand-edit state.json, manually check top-level tasks, or alter history snapshots to bypass the workflow.

Resume and recovery

The extension restores workflow behavior after startup, reload, resume, or fork:

State	Restored behavior
planning	Restore Plan mode, draft boundaries, and planning framing.
ready	Leave the submitted plan ready for review or approval.
approved	Validate the hash and wait for an explicit Build command.
executing	Restore the current task and continuation policy.
blocked	Preserve the reason without claiming completion.
completed	Preserve verified history and allow explicit rework.

If approved files changed while Pi was not running, approval is revoked. Unsupported or malformed state fails closed.

Configuration

Run the interactive wizard:

/pt-config

Choose project scope (.pi/plan_task.json) or global scope (~/.pi/agent/plan_task.json), then configure Skills, Plan tools, Build context, Build session, Diagnostics, or the full wizard. The final JSON and destination are previewed before writing.

Configuration merges in this order:

built-in defaults → global configuration → project configuration

Example:

{
  "planTools": ["read", "grep", "find", "ls", "rg"],
  "skills": {
    "docx": "docx-editor",
    "diagram": "architecture-diagram"
  },
  "buildContext": {
    "plan": "compact",
    "maxChars": 12000
  },
  "buildSession": {
    "model": "inherit",
    "thinkingLevel": "inherit"
  },
  "diagnostics": {
    "promptTokens": false
  }
}

Plan tools

Values are filtered through the safe allowlist:

read grep find ls rg plan_task ask_user_question

write and edit are added only for the two draft files. trustedPlanTools is for external read-only tools supplied by trusted Pi extensions and can be granted only in global configuration; project configuration cannot expand this trust boundary.

Skills

skills.docx and skills.diagram must match the name field in each installed skill's SKILL.md. The mapping is injected into Plan and Build prompts, persisted in workflow state, and copied into the generated root AGENTS.md task. Changing skills after approval requires revising and approving the plan again.

Build context

buildContext.plan accepts compact (default), full, or path as described above. maxChars must be a positive integer and defaults to 12000; it bounds compact and full inline context. The current task contract is always injected separately and in full.

Build session

Field	Values
model	"inherit" or a fixed "provider/modelId".
thinkingLevel	"inherit", off, minimal, low, medium, high, xhigh, or max.

For /pt-build sessions, inherited values are captured once and reused for the clean-session chain. Pi clamps thinking level to model capabilities. If a fixed model is unavailable, the extension warns and keeps Pi's default model.

Diagnostics

Set diagnostics.promptTokens to true to enable the UI-only framing diagnostics described under Context and session efficiency.

Structured user questions

@juicesharp/rpiv-ask-user-question supplies the supported questionnaire UI, including validation, multi-select, option previews, localization, and RPC fallback. It is activated only during Plan and Build modes.

Its default model guidance is detailed. Because pi-plan-task already provides phase-specific decision rules, users who want lower prompt overhead may replace only the repeated guidance while preserving the complete schema and UI behavior.

Configuration is read from:

• $XDG_CONFIG_HOME/rpiv-ask-user-question/config.json when XDG_CONFIG_HOME is absolute;
• otherwise ~/.config/rpiv-ask-user-question/config.json;
• on Windows, ~ is the user profile, such as C:\Users\you\.config\rpiv-ask-user-question\config.json.

Create or merge this object without removing unrelated settings such as collapseKey:

{
  "guidance": {
    "description": "Ask the user structured questions only when a blocking decision cannot be resolved from requirements or repository evidence.",
    "promptSnippet": "Ask the user before guessing on a blocking decision",
    "promptGuidelines": [
      "Batch related blocking decisions into one ask_user_question call.",
      "Use 2-4 described options and put the recommended option first with (Recommended)."
    ]
  }
}

Restart Pi or run /reload. With rpiv-ask-user-question 2.8.0, this changes approximate schema-and-guidance metadata from about 5,000 to 2,362 characters, saving roughly 660–755 tokens while active. This is a user-level setting that affects other workflows, so keep the default guidance if they depend on it.

Optional Plannotator review

/pt-plan-review launches the external plannotator CLI through pi.exec, so browser review requires that executable on PATH. Check it with:

plannotator --version

Follow the current Plannotator installation instructions if it is missing. A minimal or binary-only installation is sufficient.

The separate Pi package is optional:

pi install npm:@plannotator/pi-extension

Install it only if you also want Plannotator's own Pi commands, tools, and skills. pi-plan-task still invokes the external CLI and does not import that package as a runtime dependency.

An approved browser result maps to approval; annotations or rejection map to revision feedback. If the CLI is missing, fails to start, or returns no usable decision, the workflow remains unchanged and the built-in text flow remains available:

/pt-tasks
/pt-plan-approve
/pt-plan-reject <feedback>

Integration events

Other extensions and external executors may subscribe to:

pi-plan-task:plan-ready
pi-plan-task:plan-approved
pi-plan-task:plan-rejected
pi-plan-task:task-started
pi-plan-task:task-completed
pi-plan-task:task-verified
pi-plan-task:task-blocked
pi-plan-task:execution-finished

Payloads include relevant metadata such as cwd, plan and task paths, plan hash, task ID, session file, feedback, or block reason. Events are emitted only after the corresponding file or state update succeeds.

Troubleshooting

ask_user_question is missing

Install the companion package and reload Pi:

pi install npm:@juicesharp/rpiv-ask-user-question

/reload

“Plan files or contract changed after approval”

Inspect the current state and approve the submitted structure again:

/pt-tasks
/pt-plan-approve

“Implementation is complete but verification is pending”

Run the task's declared checks. Build then records successful evidence with plan_task verify; do not manually check the task.

“Execution blocked”

Resolve the reported dependency or decision, then restore and resume the task:

/pt-tasks unblock 1
/pt-build

The model may also call plan_task unblock while Build mode is active.

Invalid state.json

The extension fails closed. Do not weaken validation or fabricate completion state. Inspect .plan_task/history/, restore known-good files, or explicitly start a new plan.

Stale .plan_task/.lock

Normal operations remove the lock automatically. A lock older than ten minutes may be recovered as stale. Do not remove a recent lock while another Pi process is using the project.

Plannotator is unavailable

Run plannotator --version in the environment that launches Pi and restart Pi after installation. Installing @plannotator/pi-extension alone does not provide the external command. Until it is available, use /pt-plan-approve or /pt-plan-reject <feedback>.

Development

Install the local checkout with:

pi install /absolute/path/to/pi-plan-task

Alternatively, add the package path to packages in ~/.pi/agent/settings.json.

Run project checks:

npm test
npm run typecheck
npm run bundle
npm pack --dry-run

Plan framing loads the compact extensions/planning-method-runtime.md. The full extensions/planning-and-task-breakdown.md remains the human-facing methodology and maintenance reference.

License

MIT