youhai020616/pi-extensions/plan-execution

Plan Execution

Overview

Execute implementation plans or tackle multiple independent problems with the right strategy for your environment.

Core principle: Match execution mode to task structure and environment capabilities.

Mode Selection

Have a plan with tasks?
├── Subagents available?
│   ├── Yes → Mode A: Subagent per task (best quality)
│   └── No  → Mode B: Sequential single-agent (Pi compatible)
│
Multiple independent bugs/problems?
├── Parallel dispatch available?
│   ├── Yes → Mode C: Parallel agents
│   └── No  → Mode D: Sequential isolation (Pi compatible)

Mode A: Subagent Per Task

Use when: plan with independent tasks + subagent support

For each task:

1. Dispatch implementer subagent with full task text + context
2. If subagent asks questions → answer, re-dispatch
3. Subagent implements, tests, commits, self-reviews
4. Dispatch spec reviewer → confirms code matches spec
5. Dispatch code quality reviewer → checks implementation quality
6. Both pass → mark task complete, next task

Handling subagent status:

• DONE → proceed to review
• DONE_WITH_CONCERNS → read concerns, address if needed, then review
• NEEDS_CONTEXT → provide missing context, re-dispatch
• BLOCKED → try more capable model, or break task smaller, or escalate to human

Model selection:

• Mechanical tasks (1-2 files, clear spec) → fast/cheap model
• Integration tasks (multi-file) → standard model
• Architecture/review → most capable model

Mode B: Sequential Single-Agent

Use when: plan with tasks + no subagent support (Pi)

1. Read the full plan, create task list
2. For each task:

• Re-read task requirements (stay aligned)
• Implement following TDD (test → fail → implement → pass)
• Self-review against spec
• Self-review for code quality
• Run ALL tests (no regressions)
• Commit with descriptive message

1. After all tasks, final review pass across all changes
2. Proceed to finishing-a-development-branch

Context management (critical for single-agent):

• Keep each task focused and small
• Commit after each task (checkpoint)
• Re-read plan before each new task
• Don't carry debugging context between tasks

Mode C: Parallel Dispatch

Use when: 2+ independent problems + parallel agent support

1. Identify independent domains — group by what's broken
2. Create focused prompts per domain:

• Specific scope (one test file / subsystem)
• All needed context (error messages, relevant code)
• Clear constraints ("don't change other code")
• Expected output format

1. Dispatch all agents simultaneously
2. When agents return:

• Review each summary
• Check for conflicts (same files edited?)
• Run full test suite
• Integrate changes

Good prompt example:

Fix the 3 failing tests in src/agent-tool-abort.test.ts:
1. "should abort tool with partial output" - expects 'interrupted' in message
2. "should handle mixed tools" - fast tool aborted instead of completed
 
Root cause is likely timing/race conditions.
Do NOT just increase timeouts - find the real issue.
Do NOT change files outside this test and its implementation.
Return: summary of root cause and changes made.

Bad prompts: "Fix all the tests" (too broad), "Fix the bug" (no context)

Mode D: Sequential Isolation

Use when: 2+ independent problems + no parallel support (Pi)

1. List all problem domains separately
2. For each domain, one at a time:

• Focus ONLY on this domain
• Investigate → identify root cause → fix → verify
• Commit the fix
• Mentally "reset" — don't carry assumptions to next domain

1. After all domains, run full verification

Why this works without parallelism:

• Domain isolation prevents cross-contamination
• Each problem gets full focused attention
• Per-domain commits make reverts easy
• "Mental reset" between domains mimics fresh agent context

Red Flags (All Modes)

Never:

• Start on main/master without explicit consent
• Skip reviews (self-review or subagent review)
• Proceed with failing tests
• Edit same files from parallel agents
• Skip TDD because "it's a small change"
• Ignore subagent questions or escalations

Always:

• Verify tests pass after each task
• Commit after each task
• Review before moving to next task
• Run full suite after all tasks complete

Integration

Requires: An implementation plan (from writing-plans) or identified independent problems Leads to: finishing-a-development-branch when all tasks complete Uses: test-driven-development for each task, using-git-worktrees for isolation