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

name, description

name	description
subagent-implement	Full implementation pipeline: scout → plan → review → code → build verify → review → fix. Use when the user invokes /implement.

/implement — Standard Implementation Pipeline

Agent Roster

Agent	Role
scout	Fast codebase recon
planner	Detailed implementation plans
plan-reviewer	Reviews plans for correctness and risk
coder	Primary implementation
coder-parallel	Parallel implementation tasks (fan-out)
reviewer	Cross-family code review
fixer	Applies review feedback precisely

Phase 1: Scout → Plan → Review (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.

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, proceed to Phase 2.

Phase 2: Implement

// Single coder:
await subagent({ agent: "coder", task: `Read and implement the plan at <chain_dir>/plan.md` })

// Or parallel coders (if plan has independent sections):
await subagent({ tasks: [
  { agent: "coder-parallel", task: `Implement Part A from <chain_dir>/plan.md` },
  { agent: "coder-parallel", task: `Implement Part B from <chain_dir>/plan.md` }
]})

Use the chain dir path from Phase 1's result.

Phase 3: Build Verification

After the coder finishes, independently verify the build — don't trust the coder's report:

# Run a full build, not just type-check. Shaders, linkers, and bundlers may fail.
# Adapt to project: cargo build, npm run build, etc.

Phase 4: Review → Fix

await subagent({ agent: "reviewer", output: `${chainDir}/review.md`, task: "Review all changes made" })

Read review.md. If issues found:

await subagent({ agent: "fixer", task: `Read and apply the review feedback in ${chainDir}/review.md` })

Phase 5: Next Steps & Workflow Summary

After all phases complete, give the user a brief summary of what is next to take use of the implementation and an honoest evaluation of the workflow:

• What needs wiring and where: Point to where the user can take the implementation into use
• What happened: which phases ran, any plan review loops, whether fixes were needed
• Issues: any agent silent failures, fallbacks used, build errors, 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.

Parallel Coders Within a Chain

Fan-out/fan-in inside a chain (useful when plan sections are independent):

await subagent({ chain: [
  { agent: "scout", task: "Explore the codebase for: {task}" },
  { agent: "planner", task: "..." },
  { parallel: [
    { agent: "coder-parallel", task: "Read the plan at {chain_dir}/plan.md. Implement Part A" },
    { agent: "coder-parallel", task: "Read the plan at {chain_dir}/plan.md. Implement Part B" }
  ]},
  { agent: "reviewer", task: "Review all changes from {previous}" }
]})

Step Overrides

Override agent defaults per step:

await subagent({ chain: [
  { agent: "scout", output: "context.md" },
  { agent: "planner", reads: ["context.md"], output: "plan.md" },
  { agent: "plan-reviewer", reads: ["plan.md"] }
]})

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

Reviewer and fixer run as single agents (not in chains). Pass file paths in the task string and use the output parameter to capture their output.

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: "anthropic/claude-haiku-4-5" })

Agent	Primary	Fallback
scout	zai/glm-4.7-flash	anthropic/claude-haiku-4-5
planner, coder	zai/glm-5.1	anthropic/claude-opus-4-6
coder-parallel	zai/glm-4.7	anthropic/claude-sonnet-4-6
plan-reviewer, reviewer	anthropic/claude-opus-4-6	zai/glm-5.1
fixer	anthropic/claude-sonnet-4-6	zai/glm-5.1

Adaptive Routing

Do not run the full pipeline for a one-line fix. Use your judgment — a single coder call may suffice.