pi-plan-task

A Pi extension that brings an approved, structured, and resilient workflow to AI coding: Plan → Review → Approve → Build → Verify — driven by a single command: /pt.

💡 One-Command Mental Model: You don't need to memorize a complex CLI. After entering your initial request, simply run /pt at each step. The extension inspects the current state and presents the exact next valid action.

---

⚡ Quick Start (30 Seconds)

1. Install

pi install npm:pi-plan-task

Optional but strongly recommended:

pi install npm:@juicesharp/rpiv-ask-user-question   # Visual interactive menus in the TUI
npm install -g plannotator                        # Side-by-side browser UI for visual plan reviews

In your Pi session, reload extensions:

/reload

2. The 3-Step Flow

1. Start Planning:

   /pt Add OAuth login with GitHub and Google
   

   (Select existing codebase or greenfield project when prompted).

2. Approve the Plan: When the AI finishes the draft, run:

   /pt
   

   Select Approve (or Review to inspect diffs in Plannotator). Until you approve, the AI cannot touch your source code.

3. Build & Verify: Run:

   /pt
   

   Select Build to execute the task. Tasks are only marked done when verification requirements (e.g., tests passing, file existence) strictly succeed. Repeat /pt until all tasks are complete.

---

💎 Why pi-plan-task? (Core Advantages)

Advantage	What it means for you
🔒 Strict Sandbox Isolation	During planning, the AI can only write .plan_task/draft/. Product code and shell commands are blocked. During build, the AI cannot rewrite its own contracts.
⚡ Extreme Token & Cache Efficiency	Designed for Prompt Caching (Anthropic, DeepSeek, OpenAI). Achieves 85%–95% cache hit rates and avoids re-injecting entire plans into every turn.
🌳 DAG-Aware Task Scheduling	Tasks are structured as a Directed Acyclic Graph (DAG). Independent branches run without waiting for unrelated tasks; a blocked task only isolates its downstream dependents.
🧬 Living Plan & Impact Closure	Modify or rework tasks on the fly (/pt adjust, /pt rework). Computes exact transitive impact closures across old and new graphs, protecting verified parallel work.
🧪 Objective Verification (No Hallucinations)	AI "saying it works" is ignored. Tasks require deterministic shell exit codes (exit 0), zero-token filesystem probes, or explicit human sign-off.
📝 Deterministic Markdown Tolerance	Parser tolerates formatting quirks (bullets, punctuation, case, whitespace) while strictly preserving code fences and refusing to guess missing fields.
🛡️ Session & Crash Resilience	Built-in directory locks, atomic multi-file commits with automatic rollback, and cross-session task recovery. If a process dies, work is never lost.

---

🧠 Token Efficiency & Prompt Cache Architecture

In standard agent workflows, dumping long task lists and full design docs into every turn quickly exhausts model context, degrades reasoning quality (Context Rot), and results in ballooning API bills.

pi-plan-task is engineered from the ground up to minimize token waste and maximize modern Prompt Cache hits:

1. Static Prefix Alignment (Prompt Cache Optimization)

LLM prompt caching (e.g., Anthropic Prompt Caching, DeepSeek Context Caching, OpenAI Cached Tokens) relies on stable prefix matching.

• Invariant system rules (PLAN_SYSTEM_RULES, BUILD_SYSTEM_RULES) and core execution contracts are strictly positioned at the very front of the prompt context.
• Dynamic task parameters and ephemeral observations are appended at the end.
• Result: Subsequent interactions and build steps hit cached prefixes reliably, cutting latency and reducing API input token costs by up to 90%.

2. Compact Build Context (Task-Scoped Injection)

• Rather than re-injecting a 3,000-line plan.md into every task build turn, the extension automatically extracts cross-task decisions (architecture constraints, security rules, tech stack choices) into a compact build-context.md.
• Each task turn receives only the current task contract + compact constraints, trimming 60%–80% of redundant tokens per interaction.

3. Fresh Session Isolation (/pt build sessions)

• For long queues (10–30+ tasks), running in a single session accumulates massive conversational history.
• /pt build sessions launches each remaining task in a clean, dedicated Pi session while carrying forward verified state and approval receipts.
• Result: Task 25 executes with the same razor-sharp context and zero conversational bloat as Task 1.

4. Zero-Token Local Probes

• File and content verifications (file-exists, dir-exists, grep-match, json-match) are executed locally by Node.js, consuming 0 LLM tokens.
• Avoids expensive "read this 500KB file and tell me if X is implemented" agent turns.

5. Smart Log Truncation & Redaction

• Terminal test and build failure outputs are automatically truncated at MAX_FAILURE_EXCERPT_CHARS (keeping only relevant error tails) and scrubbed of sensitive secrets (tokens, passwords, database URLs).
• Prevents runaway terminal dumps from blowing out context limits.

---

📖 Command Reference

Daily use requires only /pt. The commands below are available when you want direct or scriptable control:

Planning & Setup

Command	Usage	Description
/pt <request>	Interactive	Start planning (prompts for existing vs new workspace).
/pt --existing <request>	Headless/Direct	Plan against the current codebase.
/pt --new <request>	Headless/Direct	Plan for an empty or greenfield workspace.
/pt --import @path/to/spec.md	Direct	Compile an existing markdown specification into strict task contracts.

Review & Approval

Command	Usage	Description
/pt review	Direct	Open the plan in Plannotator for visual, side-by-side review.
/pt approve	Direct	Sign off on the plan and generate a trusted cryptographic receipt.
/pt reject	Interactive	Reject the plan and provide feedback for full re-planning.
/pt --reject <feedback>	Headless/Direct	Reject the plan inline with feedback (ideal for CI/scripts).

Build & Execution

Command	Usage	Description
/pt build	Direct	Execute the next pending task, then pause.
/pt build all	Direct	Execute all remaining tasks sequentially in the current session.
/pt build sessions	Direct	Execute each remaining task in a fresh, isolated session (recommended for large plans).

Exception Handling & Workflow Control

Command	Usage	Description
/pt retry [id]	Direct	Retry: Clears task blockers/failures, recovers crashed worker session ownership, and returns the task to a retryable runtime state.
/pt skip [id]	Direct	Skip: Waives missing checks with risk acceptance audit record and advances to the next task.
/pt adjust [id] [feedback]	Direct	Adjust (Living Plan): Amends subsequent tasks with feedback, or automatically delegates to rework if the target task was already verified.
/pt rework [id]	Direct	Rework: Reopens a verified/waived task and its downstream dependents with exact impact preview and interactive confirmation.
/pt tasks	Direct	Tasks: View the DAG task queue (Runnable, Waiting, Blocked breakdowns, status tags, and lock ownership).

---

⚙️ Configuration

Run /pt config for an interactive wizard, or edit configuration files:

• Project: .pi/plan_task.json
• Global: ~/.pi/agent/plan_task.json

{
  "workflow": "interactive",
  "planTools": ["read", "grep", "find", "ls"],
  "trustedPlanTools": [],
  "skills": ["docx-editor"],
  "buildContext": {
    "plan": "compact",
    "maxChars": 3000
  },
  "buildSession": {
    "model": "inherit",
    "thinkingLevel": "inherit"
  },
  "diagnostics": {
    "promptTokens": false
  },
  "gitTaskCommits": false,
  "gitTaskCommitsSkipHooks": false
}

• workflow: "interactive" (prompts for greenfield vs existing workspace) or "auto" (detects workspace automatically).
• buildContext.plan: compact (default, extracts cross-task decisions), full (entire plan capped by maxChars), or path (file reference only).
• buildSession: Model and thinking level for /pt build sessions (off … max, or inherit).
• trustedPlanTools: Extra tools permitted during planning (user config only; cannot be write/shell tools).
• diagnostics.promptTokens: Show live token estimates in the TUI status bar.
• gitTaskCommits: Automatically create clean atomic Git commits (feat(task-N): ...) upon task verification.
• gitTaskCommitsSkipHooks: Pass --no-verify to atomic task commits when local hooks should be bypassed.

---

🤖 Headless & CI Automation

For automated pipelines or headless execution, omit interactive menus by supplying explicit flags:

# 1. Plan against existing repository
/pt --existing Add OAuth login with GitHub and Google

# 2. Approve plan
/pt approve

# 3. Build all tasks unattended
/pt build all

---

🔬 Under the Hood (Architecture & Specs)

Workflow Lifecycle

idle ──► planning ──► ready ──► approved ──► executing ──► completed
           │            ▲                      │
           │            └── reject / rework ───┤
           │                                   ▼
           └──────────────────────────────► blocked

Directory Structure

.plan_task/
├── plan.md              # Approved high-level architecture & design
├── build-context.md     # Deterministically extracted cross-task constraints
├── task.md              # Canonical task definitions & verification contracts (v3)
├── state.json           # Canonical v4 runtime state & verification evidence
├── draft/               # Sandbox directory during planning (untrusted)
├── history/             # Snapshots of previous plan iterations
└── .lock/               # Heartbeat directory lock (prevents concurrency races)

DAG Task Graph & Living Plan Engine

• Directed Acyclic Graph (DAG): Tasks declare explicit upstream dependencies via **Dependencies:** 1, 2 or **Dependencies:** None. The serial scheduler prioritizes runnable tasks whose prerequisites are verified or waived.
• Isolated Branch Scheduling: If a task encounters a blocker, independent tasks and parallel branches continue executing. The overall workflow only blocks when all remaining tasks are either blocked or dependent on a blocked task.
• Dual-Graph Impact Closure: Reworking or amending tasks computes the transitive closure across both the original and amended graphs ($\text{closure} = \text{dependents}{G{old}}(focus) \cup \text{dependents}{G{new}}(focus)$). Independent parallel branches strictly retain their verified status and evidence.
• DAG Status Visibility & Impact Previews: /pt tasks prints an exact breakdown of Runnable, Blocked, and Waiting tasks. Before reopening satisfied tasks, the system renders an impact preview detailing invalidated tasks vs unaffected work, requiring interactive confirmation.
• Deterministic Markdown Tolerance: Parser normalizes line endings (CRLF/LF), bullets (- / *), Chinese punctuation (：, ，, 、, 和), and label casing while strictly protecting code fences and refusing to guess ambiguous contracts.

Strict Task Contracts (v3)

.plan_task/task.md enforces a strict machine-readable format. Heading titles must strictly match numbered checklist items. Top-level checkboxes are a display projection of state.json; editing them manually does not verify, waive, reopen, or skip a task:

<!-- pi-plan-task:task:v3 -->
# Tasks

- [x] 1. Implement Token Verification Service
- [ ] 2. Implement User Route Auth Middleware
- [ ] 3. Implement Audit Logger
- [ ] 4. End-to-End Auth Integration Tests

## Task 1: Implement Token Verification Service
**Description:** Validate JWTs using existing keys in `src/config/keys.ts`.
**Acceptance criteria:**
- [ ] Valid tokens return a parsed payload.
- [ ] Expired or corrupt tokens reject with HTTP 401.
**Verification:**
Run `npm test -- tests/auth/jwt.test.ts`
Inspect: file-exists `src/services/jwt.ts`
**Dependencies:** None
**Estimated scope:** S
**Files likely touched:** `src/services/jwt.ts`, `tests/auth/jwt.test.ts`

## Task 2: Implement User Route Auth Middleware
**Description:** Add auth guard middleware to `/api/user/*`.
**Acceptance criteria:**
- [ ] Unauthenticated requests return HTTP 401.
**Verification:**
Run `npm test -- tests/auth/middleware.test.ts`
**Dependencies:** 1
**Estimated scope:** S
**Files likely touched:** `src/middleware/auth.ts`

## Task 3: Implement Audit Logger
**Description:** Record security event logs.
**Acceptance criteria:**
- [ ] Security events persist to audit log.
**Verification:**
Run `npm test -- tests/logging/audit.test.ts`
**Dependencies:** None
**Estimated scope:** XS
**Files likely touched:** `src/logging/audit.ts`

## Task 4: End-to-End Auth Integration Tests
**Description:** Integration test auth middleware and audit logging.
**Acceptance criteria:**
- [ ] Complete auth journey tests pass.
**Verification:**
Run `npm test -- tests/e2e/auth.test.ts`
**Dependencies:** 2, 3
**Estimated scope:** M
**Files likely touched:** `tests/e2e/auth.test.ts`

Three-Tier Verification Engine

1. Run <command>: The declared shell command must execute after the task code is written and exit with code 0. Any code modifications after execution wipe prior run evidence.
2. Inspect:: Machine probes (file-exists, dir-exists, grep-match, json-match) evaluate automatically via native filesystem calls. Custom inspections require structured evidence (passed/failed + observation).
3. Human:: Prompts the user in the TUI; requires explicit human confirmation.

Extension Event Bus

Integrate or build sidecars on top of pi-plan-task:

pi.events.on("pi-plan-task:plan-ready", handler);
pi.events.on("pi-plan-task:plan-approved", handler);
pi.events.on("pi-plan-task:plan-rejected", handler);
pi.events.on("pi-plan-task:task-started", handler);
pi.events.on("pi-plan-task:task-completed", handler);
pi.events.on("pi-plan-task:task-verified", handler);
pi.events.on("pi-plan-task:task-blocked", handler);
pi.events.on("pi-plan-task:task-waived", handler);
pi.events.on("pi-plan-task:execution-finished", handler);

Troubleshooting Reference

Error Code	Meaning	Resolution
PT-APPROVAL-INVALID	Plan or task files changed out-of-band after approval.	Inspect differences, then run /pt approve again.
PT-TASK-OWNED	Another active session owns the task.	Resume that session or run /pt retry <id> if the worker died.
PT-VERIFICATION-FAILED	A declared Run command exited non-zero.	Resolve the test/build failure and rerun the verification command.
PT-TASK-RUNTIME-INVALID	state.json task records do not match the task contract.	Recreate the workflow or restore a valid state.json.
PT-STORAGE-PROTECTED	An unauthorized tool attempted to write .plan_task/.	Edit project files instead, or use /pt actions.
PT-PLAN-MISSING	No active workflow found in the workspace.	Run /pt --new, /pt --existing, or /pt --import.

---

🛠️ Development

npm test              # Run full unit and integration test suite (tsx)
npm run typecheck     # TypeScript strict validation
npm run bundle        # esbuild production bundle
npm pack --dry-run    # Verify packaged artifact contents

📄 License

MIT © pi-plan-task contributors