dotfiles/pi/.pi/agent/skills/subagent-plan/SKILL.md

name, description

name	description
subagent-plan	Plan-only pipeline: scout → plan → review. Produces a reviewed implementation plan without coding. Use when the user invokes /plan.

/plan — Plan Only (No Implementation)

Agent Roster

Agent	Role
scout	Fast codebase recon
planner	Detailed implementation plans
plan-reviewer	Reviews plans for correctness and risk

Workflow (single chain)

await subagent({ chain: [
  { agent: "scout",         task: "Explore the codebase for: {task}" },
  { agent: "planner",       task: "Create a detailed implementation plan for: {task}" },
  { agent: "plan-reviewer", task: "Review the plan for correctness, completeness, and risk." }
]})

The chain creates scout.md, plan.md, plan-review.md in the chain artifact dir (/tmp/pi-chain-runs/<id>/).

Handling the Verdict

Read plan-review.md from the artifact dir. If NEEDS_REVISION or REJECTED, loop: tell the planner what to fix, re-run the reviewer. If APPROVED, present the plan path to the user.

Show the user the path to plan.md.

Workflow Summary

After the chain completes, give the user a brief honest summary:

• What happened: did the plan pass review on the first try, or did it need revision loops?
• Issues: any agent silent failures, fallbacks used, or unexpected behavior
• Agent quality: did any agent misinterpret the task, produce poor output, or need hand-holding? Name the agent and the problem
• Skill improvements: did this workflow reveal gaps in the skill instructions or agent prompts? Note what should change

Be concise — a few lines is enough when things went well. Only expand on problems.

Chain Mechanics

Chain mode (subagent({ chain: [...] })) runs agents sequentially in a shared temp directory ({chain_dir}). Each step:

1. The framework injects [Read from:] and [Write to:] directives from the agent's defaultReads and output frontmatter
2. The agent reads upstream files, does its work, and writes its deliverable to the [Write to:] path using the write tool
3. The agent returns a brief text summary; {previous} carries this summary to the next step
4. Variable substitution: {task} = original task, {previous} = prior step's brief ack, {chain_dir} = artifact dir path

Key behaviors:

• Data flows through FILES (scout.md → plan.md → plan-review.md), not through {previous}
• {previous} contains only a brief summary from the prior step — do NOT rely on it for full context
• The framework validates that the expected output file was created
• The chain result includes 📁 Artifacts: /tmp/pi-chain-runs/<id>/ — use this path to read files for branching decisions

Fallback Strategy

When a subagent call returns no output (silent failure), apply cross-family model fallback. Do not fall back to doing the work yourself — always retry with the fallback model first.

1. First attempt: Use the agent's default model
2. If silent failure or error: Retry with the fallback model using model override
3. If the fallback also fails: Report the double-failure to the user. Still do not do the work yourself.

// Example: scout fails silently, retry with fallback
subagent({ agent: "scout", task: "...", model: "opencode/big-pickle" })

Agent	Primary	Fallback
scout	opencode-go/mimo-v2-pro	opencode/big-pickle
planner	opencode/qwen3.6-plus-free	opencode-go/glm-5
plan-reviewer	opencode-go/kimi-k2.5	opencode/qwen3.6-plus-free