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

   (Workspace type is detected automatically).

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/. Active read-only environment probing is supported, while file modifications and destructive shell mutations 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 [id]). 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:

Core Daily Commands (3+2 Surface)

| Command | Usage | Description | | :--- | :--- | :--- | | /pt [request] | Primary Flow | One Command: Drive the next step, or start planning when passed a request. Automatically detects workspace type. | | /pt build [all] | Execution | Execute the next pending task (/pt build), or execute all remaining tasks in this session (/pt build all). | | /pt tasks | Progress | Tasks: Read-only view of the DAG task queue (Runnable, Waiting, Blocked breakdowns, status tags, and lock ownership). | | /pt adjust [id] [text] | Plan Living | Adjust / Rework: Unified command to modify pending tasks with feedback, or reopen completed tasks with impact closure. | | /pt config | Setup | Open the interactive configuration wizard in the TUI. |

Fast Verification & Recovery

| Command | Usage | Description | | :--- | :--- | :--- | | /pt test [id] | Direct | Zero-Token Local Test: Re-run declared Run: verification commands locally via Node child process. Auto-finalizes upon exit 0 with 0 LLM tokens (alias: /pt verify). | | /pt retry [id] | Recovery | Retry: Clears task blockers/failures, recovers crashed worker session ownership, and resumes execution (supports --check="<cmd>"). | | /pt skip [id] | Waiver | Skip: Waives missing checks with risk acceptance audit record and advances to the next task. |

Advanced & Headless Operations

| 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 [feedback] | Direct | Reject the plan with optional feedback (prompts interactively if omitted). | | /pt build sessions | Isolation | Execute each remaining task in a fresh, isolated session (recommended for large 10+ task plans). | | /pt --import <plan.md> | Direct | Import Mode: Convert an existing finalized markdown plan into strict task contracts (keeps plan read-only). |

⚙️ Configuration

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

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

{
  "unattended": false,
  "skills": ["docx-editor"],
  "buildContext": {
    "plan": "compact",
    "maxChars": 3000
  },
  "buildSession": {
    "model": "inherit",
    "thinkingLevel": "inherit"
  },
  "git": {
    "atomicCommits": true,
    "skipHooks": true
  }
}

• unattended: false (default: interactive plan review required) or true (auto-pilot: auto-approves plan and runs tasks unattended; legacy workflow: "auto" supported).
• buildContext.plan: compact (default, extracts cross-task decisions), full (entire plan capped by maxChars), or path (file reference only).
• buildContext.maxChars: Max character budget for injected build constraints (default: 3000).
• buildSession: Model and thinking level for /pt build sessions (off … max, or inherit).
• git.atomicCommits: Automatically create clean atomic Git commits (feat(task-N): ...) upon task verification (legacy gitTaskCommits supported).
• git.skipHooks: Pass --no-verify to atomic task commits when local hooks should be bypassed (legacy gitTaskCommitsSkipHooks supported).
• skills: Approved project skills required by task contracts.

🤖 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 (closure = dependents(G_old, focus) ∪ 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, or run /pt test to test locally with 0 tokens. | | 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