pi-plan-task

A safe, resumable plan → review → approve → build → verify workflow for Pi. It supports both software development and document writing workflows, including Word technical-solution documents with approved technical diagrams.

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

pi-plan-task turns requests into an explicit, file-backed workflow instead of jumping directly into implementation or document production. Use it to plan repository changes, write technical specifications, or produce a .docx deliverable. Plans and task progress are stored in the repository, approval is bound to the submitted plan, and every code or document task proceeds one verified task at a time.

For document workflows, the extension orchestrates planning and delivery while your configured DOCX and technical-diagram skills create the Word file and diagrams. The document outline requires confirmation, and the final .docx is validated before delivery. DOCX template input is not supported.

Why use it?

Review before code or document changes

Planning runs inside a restricted mode. The agent may inspect the repository and write only the two planning drafts:

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

Product code and final document deliverables cannot be modified until the submitted plan is explicitly approved. This same approval gate applies to technical specifications, Word documents, and diagram-producing workflows.

Keep execution focused

Build mode exposes exactly one approved task contract at a time. A task must move through:

pending → implementation-complete → verified

Finishing implementation does not silently mark work done. The task is checked only after its verification steps pass and verification evidence is recorded.

Resume safely

The workflow is file-backed. Plans, tasks, approval state, block reasons, and verification evidence survive Pi reloads, forks, and replacement sessions.

Detect plan drift

Approval is bound to the submitted plan, generated build context, and task contracts. If those files change after approval, execution fails closed and asks for review and approval again.

Control context and session cost

• Plan and Build tools are active only while their mode needs them.
• Build defaults to a compact cross-task context instead of repeatedly injecting the full plan.
• Stable prompt rules are placed before task-specific content to improve provider prompt-cache reuse.
• Optional UI-only token diagnostics show framing and context sizes without sending the diagnostics to the model.
• /pt-build sessions gives every task a clean session so long plans do not accumulate one huge conversation.

Eight commands

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

/pt-config         configure project or global settings interactively
/pt-plan-new       create a plan for a new project workspace
/pt-plan-existing  create a plan for an existing project workspace
/pt-plan-review    review the submitted plan
/pt-plan-approve   approve the submitted plan
/pt-plan-reject    reject the submitted plan with optional feedback
/pt-build          execute approved tasks
/pt-tasks          inspect progress or reopen verified work

Requirements

• Pi with package/extension support.
• @juicesharp/rpiv-ask-user-question, which provides the ask_user_question tool used for consequential decisions.
• Plannotator is optional. The review action requires a plannotator CLI executable on PATH; without it, use the built-in text approval flow.

Installation

Install the question UI first, then this package:

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

Restart Pi or run:

/reload

For local development:

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

You can also add the package path to packages in ~/.pi/agent/settings.json.

Quick start

1. Configure the extension (optional)

/pt-config

Use the wizard to bind installed DOCX and diagram skills or adjust Plan/Build settings. Defaults are sufficient for ordinary code plans.

2. Ask Pi to create a plan

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

You can also plan from a specification file:

/pt-plan-existing docs/auth-spec.md focus on reusing the existing session service

Pi explores the repository and creates two draft files:

.plan_task/draft/plan.md   # architecture, phases, risks, and decisions
.plan_task/draft/task.md   # executable task contracts and verification steps

Plan a greenfield Word technical solution

The workspace does not need to be a Git repository or contain source code. When the request explicitly requires Word, the planner applies the Word workflow; ordinary code plans remain unchanged.

The Word workflow creates a new DOCX; do not provide a DOCX template. The command name selects the workspace type:

/pt-plan-new Write a Word technical solution for a new system
/pt-plan-existing Write a Word technical solution based on an existing project

• pt-plan-new treats the workspace as empty or new.
• pt-plan-existing treats the workspace as an existing project.
• The model no longer infers the workspace type.

/pt-plan-new Design a multi-tenant SaaS technical solution, deliver it as deliverables/saas-solution.docx, and include technical diagrams

The planner presents 2–3 complete outline alternatives for confirmation before it finalizes the plan. DOCX template inputs are rejected.

Document task granularity

Word plans are sized by chapter boundaries, target pages or words, diagram count, evidence scope, and independent themes—not by the number of final files.

• One writing task covers one first-level chapter or 2–3 tightly related second-level sections.
• Each writing task must declare its size and diagram budget; approval rejects tasks above 10 pages, 6,000 words/Chinese characters, or 3 related diagrams.
• Every chapter task writes to a distinct intermediate content/*.md file.
• The plan must include Document Work Breakdown and Quality and Verification, mapping chapters to task IDs, intermediate paths, size targets, diagrams, dependencies, and checks.
• Chapter drafting, diagram generation, consistency review, DOCX assembly, structural validation, visual layout review, and final verification remain separate tasks.

Task count is derived from the approved outline and quality stages; there is no 100-page threshold or fixed minimum task count. A single “write the entire document” task is always rejected.

The approved task queue starts by creating root AGENTS.md, then drafts content, generates technical diagrams through the configured diagram skill, and creates/verifies a new Word document through the configured DOCX skill. Missing capabilities block the task instead of triggering a fallback DOCX or diagram implementation.

Supported document workflows

The extension supports document work as a first-class workflow, not only code changes:

• technical specifications and architecture documents;
• Word (.docx) technical-solution documents;
• technical diagrams generated by a configured diagram skill and embedded into the final Word document;
• reviewable, approved, task-by-task document production with final validation.

The extension does not contain a DOCX editor or diagram engine. Configure the skills that should perform those operations, then use pt-plan-new or pt-plan-existing to start the workflow.

For long document workflows, prefer:

/pt-build sessions

3. Review the submitted plan

After both drafts are valid, the extension submits them as .plan_task/plan.md and .plan_task/task.md. You can review the submitted plan during the ready, approved, or build lifecycle:

/pt-plan-approve  approve the submitted plan
/pt-plan-review   open optional Plannotator browser review
/pt-plan-reject   return to planning with optional feedback

You can also use the commands directly:

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

4. Build the plan

Run one task in the current session:

/pt-build

Run every remaining task in the current session:

/pt-build all

Run every remaining task in its own clean session:

/pt-build sessions

5. Inspect progress

/pt-tasks

If a verified task needs to be changed again:

/pt-tasks rework 2

Rework reopens task 2 and every later task, revokes approval, and requires another review and /pt-plan-approve before execution resumes.

Choosing a Build mode

| Command | Best for | Behavior | | --- | --- | --- | | /pt-build | Careful, interactive execution | Runs one task. After verification, choose whether 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 and strict task isolation | Opens a clean session for each remaining task, including the first. |

A clean Build session does not inherit the planning conversation as parent context. It reconstructs the task from the approved files, persisted workflow state, and repository. This keeps each task focused and limits context growth.

After /pt-plan-approve, the plan remains approved but idle. Start execution explicitly with /pt-build, /pt-build all, or /pt-build sessions.

Command reference

Configuration and plan commands

| Command | Description | | --- | --- | | /pt-config | Interactively configure project or global settings. | | /pt-plan-new <request> | Create a plan for a new project workspace. | | /pt-plan-existing <request> | Create a plan for an existing project workspace. | | /pt-plan-review | Open Plannotator review for the submitted plan at any time. | | /pt-plan-approve | Approve the submitted plan without executing it. Run a /pt-build command to start. | | /pt-plan-reject [feedback] | Reject the submitted plan and initialize a revision draft. |

/pt-config requires interactive UI. It first selects project (.pi/plan_task.json) or global (~/.pi/agent/plan_task.json) scope, then one of: Skills, Plan tools, Build context, Build session, Diagnostics, or Full wizard. The final JSON and destination are shown before confirmation.

There is no /pt-plan command. The command name selects the workspace mode, so the model never needs to infer it: use pt-plan-new for a new/empty workspace and pt-plan-existing for an existing project.

Spec files up to 20,000 characters are inlined. For larger files, Pi receives a Unicode-safe preview of up to 10,000 characters plus the full path and instructions to search headings and read only relevant ranges. When an incomplete plan already exists, interactive mode asks before starting different work. Non-interactive mode refuses to replace incomplete work.

/pt-build

| Command | Description | | --- | --- | | /pt-build | Execute the next pending task in this session. | | /pt-build all | Execute all remaining tasks in this session. | | /pt-build sessions | Execute each remaining task in a separate clean session. |

--all and --sessions are accepted aliases. Build modes are mutually exclusive. Legacy new, fresh, and approval command flags are rejected; session placement is selected after approval or through /pt-build sessions.

Execution requires:

• an approved workflow;
• a valid task queue;
• an unchanged approved structure;
• at least one runnable task.

/pt-tasks

| Command | Description | | --- | --- | | /pt-tasks | Show workflow status and the canonical task checklist. | | /pt-tasks rework <id> | Reopen a verified task and every later task. | | /pt-tasks unblock <id> | Restore a blocked task after its dependency or decision is resolved. |

In the TUI, /pt-tasks opens a task list view. In print, JSON, or RPC-oriented flows, it emits a textual status notification.

How planning stays safe

During Plan mode:

• configured read-only tools may inspect the repository;
• write and edit may target only the two draft files;
• shell and implementation tools are blocked;
• submitted plans, state, history, and project files cannot be modified;
• repository and spec content are treated as untrusted project data;
• consequential decisions should be resolved through ask_user_question before the plan is finalized.

The extension validates that the task file has a strict numbered queue and matching task contracts. Invalid or half-written drafts never replace the current submitted plan.

Task contracts and verification

.plan_task/task.md is the canonical execution queue. It starts with numbered top-level tasks:

# 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 section. The planner also supplies dependencies, likely files, bounded scope, acceptance criteria, and repository-specific verification.

Nested acceptance and verification checkboxes are criteria, not execution completion markers. Do not manually check top-level tasks; only successful plan_task verify does that.

Model-facing plan_task tool

The model uses plan_task during Build mode:

{"action":"status"}
{"action":"complete","id":1}
{"action":"verify","id":1,"reason":"Focused auth tests and typecheck passed"}
{"action":"block","id":1,"reason":"Waiting for an API decision"}
{"action":"unblock","id":1}

Important behavior:

• complete records implementation-complete but does not check the task.
• verify requires non-empty evidence, checks the task, and permits progression.
• block requires a reason and remembers whether the task was pending or awaiting verification.
• unblock restores that previous active state.
• Any unfinished blocked task stops the whole queue; all and sessions never skip ahead to later tasks.
• Invalid actions fail without partially changing workflow files.

Durable project files

.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/            # temporary planning/revision files
│   ├── plan.md
│   └── task.md
├── history/          # submitted-plan snapshots
└── .lock/            # short-lived workflow lock

Writes use an in-process queue, a project workflow lock, temporary files, and atomic replacement. Multi-file submissions use rollback if a later write fails.

Approval stores a SHA-256 structure hash derived from the submitted plan, generated build context, and task contracts. Normal top-level checkbox progress is normalized so successful verification does not revoke approval. Structural edits do revoke it.

Do not hand-edit state.json, check top-level tasks manually, 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 | Restores Plan mode, the draft write boundary, and planning framing. | | ready | Leaves the submitted plan ready for review or approval. | | approved | Leaves the plan ready to build after hash validation. | | executing | Restores the current task and continuation policy. | | blocked | Preserves block reasons without claiming completion. | | completed | Preserves verified history and allows explicit rework. |

If approved files changed while Pi was not running, approval is revoked. Malformed or unsupported state fails closed instead of guessing.

Configuration

Run the interactive configuration wizard:

/pt-config

The wizard lets you choose project or global scope, then edit Skills, Plan tools, Build context, Build session, Diagnostics, or run the full wizard. It previews the target path and final JSON before writing. When the target file does not exist, it creates a complete configuration template. Project configuration cannot grant trustedPlanTools; that trust remains global-only.

Configuration is merged in this order:

1. built-in defaults;
2. global ~/.pi/agent/plan_task.json;
3. project .pi/plan_task.json.

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
  }
}

planTools

Read-only tools available during Plan mode. Values are filtered through the extension's safe allowlist:

read grep find ls rg plan_task ask_user_question

write and edit are added specifically for the two draft files. Calls targeting anything else are blocked. Tools are mode-scoped: idle conversations do not keep Plan or Build tools active, and leaving a mode removes only tools that this extension added.

skills

Use project configuration to bind this workflow to specific installed skills:

{
  "skills": {
    "docx": "docx-editor",
    "diagram": "architecture-diagram"
  }
}

The names must match the name field in each 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. Do not substitute another skill without revising and re-approving the plan. trustedPlanTools is only for additional external read-only tools supplied by trusted Pi extensions. Project configuration cannot grant this trust.

buildContext

Controls how plan context appears in each task's Build framing. The current task contract is always injected separately and in full.

| plan | Behavior | | --- | --- | | compact | Default. Inline approved build-context.md, generated from cross-task overview, architecture decisions, and risks. | | full | Inline submitted plan.md up to maxChars. | | path | Inline no plan content; point the agent to .plan_task/plan.md for selective reading. |

maxChars must be a positive integer and defaults to 12000. It bounds generated compact context and full inline context.

buildSession

Controls model and thinking level when the extension creates replacement Build sessions.

{
  "buildSession": {
    "model": "inherit",
    "thinkingLevel": "inherit"
  }
}

| Field | Values | Behavior | | --- | --- | --- | | model | "inherit" | Capture the launcher session's current provider/modelId. | | model | "provider/modelId" | Use a fixed model for extension-created Build sessions. | | thinkingLevel | "inherit" | Capture the launcher session's current thinking level. | | thinkingLevel | off, minimal, low, medium, high, xhigh, max | Request a fixed level. Pi clamps it to model capabilities. |

Either field may be omitted. For /pt-build sessions, inherited values are captured once and reused for the clean-session chain. If a configured model is unavailable, the extension warns and keeps Pi's default model.

diagnostics

Enable UI-only framing diagnostics:

{
  "diagnostics": {
    "promptTokens": true
  }
}

At the beginning of a Plan phase or Build task, the UI reports:

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

Token counts use a stable characters / 4 estimate because provider tokenizers differ. Diagnostics use ctx.ui.notify; they are not appended to the conversation or sent to the model. Provider cache-read usage is not shown because it is not exposed at the framing injection point.

rpiv-ask-user-question

@juicesharp/rpiv-ask-user-question is the recommended and supported questionnaire tool for this workflow. It provides a mature UI, validation, multi-select, option previews, localization, and RPC fallback. pi-plan-task activates ask_user_question only during Plan and Build modes, so idle conversations do not pay this extension-added tool-schema cost.

Install it with:

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

Optional compact guidance

rpiv-ask-user-question has intentionally detailed default model guidance. Because pi-plan-task already includes phase-specific instructions for blocking decisions, users who want lower prompt overhead can replace only that repeated guidance while preserving the complete schema and all questionnaire behavior.

The package reads its configuration from:

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

Create or merge this guidance object:

{
  "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)."
    ]
  }
}

If the file already has settings such as collapseKey, preserve them and merge only guidance:

{
  "collapseKey": "ctrl+]",
  "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 after editing this file. The guidance is read when the extension registers.

With rpiv-ask-user-question 2.8.0, approximate metadata size changes from:

default schema + guidance:  about 5,000 characters (1,250-1,430 tokens)
compact schema + guidance:  about 2,362 characters (590-675 tokens)
estimated saving:           about 660-755 tokens per request while active

Exact counts depend on the provider tokenizer and Pi's tool serialization. This is a user-level setting and affects other workflows that use rpiv-ask-user-question; keep the default guidance if those workflows rely on its longer instructions.

Optional Plannotator review

Plannotator is an optional external runtime dependency, not an npm dependency of pi-plan-task. The extension launches it with pi.exec("plannotator", ...), so browser review works when a plannotator executable is available on PATH. Keeping it optional avoids installing a browser-review runtime for users who only want the Markdown approval workflow.

Check availability with:

plannotator --version

If the command is missing, install Plannotator using its official installer. A minimal/binary-only installation is sufficient for the review action because pi-plan-task calls the CLI directly. Follow the current commands in the Plannotator installation documentation, then restart Pi or ensure the installed binary directory is on PATH.

The separate Pi package is optional for this plugin:

pi install npm:@plannotator/pi-extension

Install @plannotator/pi-extension only if you also want Plannotator's own Pi commands, plan mode, review tools, and skills. Installing that npm package alone is not treated by pi-plan-task as an imported library dependency; this plugin still checks the external plannotator command at runtime.

Use /pt-plan-review to open browser-based Markdown review at any time after submission:

• An approved result becomes /pt-plan-approve.
• Annotated or rejected feedback becomes /pt-plan-reject <feedback>.
• If the CLI is missing, cannot start, or returns no usable decision, the workflow remains safe and you can continue with /pt-tasks, /pt-plan-approve, or /pt-plan-reject <feedback>.

Prompt and context behavior

• Phase instructions are injected once per Plan phase or Build task, not permanently patched into the system prompt.
• Stable rules precede dynamic requests and task contracts to improve prefix-cache reuse.
• Stale phase framing is filtered from model context without rewriting session history.
• Build framing defaults to compact approved cross-task context plus the complete current task contract.
• Plan and Build tools are activated only while needed.
• A resumed implementation-complete task receives verification-only framing and must not call complete again.

These optimizations improve cost, cache reuse, and focus. They do not weaken approval or verification rules.

Events for integrations

Other extensions or 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 workflow metadata such as cwd, planPath, taskPath, planHash, taskId, sessionFile, feedback, or block reason. Events are emitted only after their corresponding file/state update succeeds.

Troubleshooting

ask_user_question is missing

Install the required companion package and reload Pi:

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

/reload

“Plan files or contract changed after approval”

The submitted structure no longer matches the approved hash. Inspect the plan and tasks, then approve again:

/pt-tasks
/pt-plan-approve

“Implementation is complete but verification is pending”

The model has called complete, but verification has not succeeded. Run the task's declared checks and then use:

{"action":"verify","id":1,"reason":"Describe the successful checks"}

“Execution blocked”

Resolve the reported dependency or decision, restore the task, then resume the desired Build mode:

/pt-tasks unblock 1
/pt-build

The model can still call plan_task unblock while Build mode is active. Do not edit .plan_task/state.json manually.

Invalid state.json

The extension fails closed. Do not weaken validation or fabricate completion state. Inspect .plan_task/history/, restore known-good project 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 working on the same project.

Plannotator is unavailable

pi-plan-task needs the external CLI command for its review action. Verify it from the same environment that launches Pi:

plannotator --version

If your terminal can find it but Pi cannot, restart Pi after installation and confirm the binary directory is included in the parent process's PATH. Installing npm:@plannotator/pi-extension adds Plannotator's native Pi integration, but pi-plan-task still invokes the external command rather than importing that package.

Until the CLI is available, use the built-in text workflow:

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

Development

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.

The test suite covers parsing, draft validation, state validation, approval hashes, transactional mutation, command behavior, task lifecycle, blocking, rework, recovery, session handoff, prompt framing, and token diagnostics.

Safety summary

• Review before implementation.
• Approve the exact submitted structure.
• Execute one bounded contract at a time.
• Verify before checking a task.
• Fail closed when files or state disagree.
• Preserve durable Markdown and state across sessions.
• Use /pt-tasks rework <id> instead of manually rewriting progress.

License

MIT