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

name, description

name	description
subagent-implement-critical	Maximum-quality implementation pipeline: deep-scout → plan → review → Claude coder → build verify → review → fix. Use when the user invokes /implement-critical.

/implement-critical — Maximum Quality Pipeline

Same structure as /implement but with deeper scouting and a stronger coder.

Agent Roster

Agent	Role
deep-scout	Thorough architectural exploration
planner	Detailed implementation plans
plan-reviewer	Reviews plans for correctness and risk
coder-claude	Complex/unfamiliar implementation (elite coder)
reviewer	Cross-family code review
fixer	Applies review feedback precisely

Phase 1: Deep Scout → Plan → Review (chain)

await subagent({ chain: [
  { agent: "deep-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

await subagent({ agent: "coder-claude", task: `Read and implement the plan at <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: Workflow Summary

After all phases complete, give the user a brief honest summary:

• 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.

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: deep-scout fails silently, retry with fallback
subagent({ agent: "deep-scout", task: "...", model: "anthropic/claude-sonnet-4-6" })

Agent	Primary	Fallback
deep-scout	zai/glm-4.7	anthropic/claude-sonnet-4-6
planner	zai/glm-5.1	anthropic/claude-opus-4-6
plan-reviewer	anthropic/claude-opus-4-6	zai/glm-5.1
coder-claude	anthropic/claude-sonnet-4-6	zai/glm-5.1
reviewer	anthropic/claude-opus-4-6	zai/glm-5.1
fixer	anthropic/claude-sonnet-4-6	zai/glm-5.1