playbook/outfitter-agents/.agents/notes/superpowers-subagent-patterns.md

Superpowers Subagent Patterns

Analysis of obra/superpowers orchestration skills for potential improvements to baselayer/skills/subagent-coordination.

Source: ~/.claude/plugins/cache/superpowers-marketplace/superpowers/4.0.1/skills/

Key Skills Reviewed

subagent-driven-development

Execution workflow for implementing plans with subagents.

Core pattern: Fresh subagent per task + two-stage review (spec then quality)

Process:

1. Controller reads plan, extracts all tasks with full text upfront
2. Per task:
   • Dispatch implementer subagent (with full task text, not file reference)
   • Implementer asks questions if needed, then implements + tests + commits + self-reviews
   • Dispatch spec reviewer → verify code matches spec (nothing more, nothing less)
   • Dispatch code quality reviewer → verify implementation is well-built
   • Both reviews loop until approved
3. After all tasks: final code review of entire implementation

Key insight: Controller provides context, subagents execute. Don't make subagents read plan files.

dispatching-parallel-agents

When and how to parallelize subagent work.

Use when:

• 3+ independent failures/tasks
• Different root causes or problem domains
• No shared state between investigations
• Each problem understood without context from others

Don't use when:

• Failures are related (fix one might fix others)
• Need full system state understanding
• Agents would interfere (editing same files)

Good prompts are:

• Focused: One clear problem domain
• Self-contained: All context needed
• Specific about output: What should agent return?

Comparison: Our Skill vs Superpowers

Pattern	subagent-coordination	superpowers	Gap
Routing decisions	✓ Primary focus	Assumes known	None
Prompt templates	✗	✓ Three templates	Could add
Two-stage review	✗	✓ Spec → Quality	Could add
Parallel dispatch	Brief mention	✓ Full skill	Could expand
Controller role	Implicit	✓ Explicit	Could clarify
Process diagrams	Text-based	✓ Dot graphs	Could add
Red flags	Anti-patterns	✓ "Never" list	Could enhance

Patterns Worth Adopting

1. Two-Stage Review

Separate concerns:

• Spec compliance: Did we build what was asked? Nothing missing, nothing extra.
• Code quality: Is it well-built? Clean, tested, maintainable.

Different mindsets, different reviewers. Spec first, quality second.

2. Controller Provides Full Context

Don't make subagents read plan files. Controller:

• Extracts all tasks upfront
• Provides full task text to each subagent
• Includes scene-setting context (where task fits, dependencies)
• Answers questions before subagent starts work

3. Fresh Subagent Per Task

Each task gets clean subagent. Prevents:

• Context pollution from previous tasks
• Confusion about what's already done
• State leaking between tasks

4. Prompt Templates

Superpowers provides templates for:

implementer-prompt.md:

• Task description (full text)
• Context (where it fits)
• "Ask questions before starting"
• Self-review checklist before reporting

spec-reviewer-prompt.md:

• What was requested (requirements)
• What implementer claims (report)
• "Do NOT trust the report" — verify by reading code
• Check: missing requirements, extra work, misunderstandings

code-quality-reviewer-prompt.md:

• Uses code-review skill template
• Only dispatched after spec compliance passes
• Returns: strengths, issues (critical/important/minor), assessment

5. Parallel Dispatch Criteria

Safe to parallelize:

• Independent problem domains
• No shared files being edited
• Each agent has complete context
• Results can be integrated without conflicts

Not safe:

• Related failures (fix one might fix others)
• Sequential dependencies
• Shared state or resources

Potential Enhancements

If we want to incorporate these patterns:

1. references/prompts.md — Templates for implementer, spec-reviewer, code-quality-reviewer

2. references/parallel-dispatch.md — Expand on when/how to parallelize, criteria for independence

3. Update SKILL.md:

   • Add two-stage review to workflow patterns
   • Make controller role explicit
   • Add dot diagrams for complex flows
   • Enhance anti-patterns with specific "never" items

4. Consider: Should we have a separate plan-execution skill (like superpowers' subagent-driven-development) vs our routing-focused subagent-coordination? Different purposes.

Notes

• Superpowers is very process-oriented (how to execute)
• Our skill is more routing-oriented (who handles what)
• Both are valuable, potentially complementary
• Superpowers uses dot/graphviz diagrams for flow visualization
• "Do NOT trust the report" is a strong pattern for spec review