Super power

[pelikhan]

Investigate how to use https://github.com/obra/superpowers with agentic workflows

[pelikhan]

/scout

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

Superpowers is a comprehensive software development workflow system for coding agents that enforces structured development practices through composable "skills" and automatic workflow enforcement. The integration opportunity with GitHub Agentic Workflows (gh-aw) is significant, as both projects share the goal of bringing structure and safety to AI-driven automation.

Key Integration Opportunities:

• Skills-based workflow enforcement for gh-aw agents
• Test-Driven Development (TDD) patterns for workflow development
• Subagent-driven execution models for complex tasks
• Systematic debugging and verification patterns

Click to expand detailed findings

Research Findings

What is Superpowers?

Superpowers is a plugin system for Claude Code (and other AI coding assistants like Codex/OpenCode) that transforms ad-hoc AI interactions into structured development workflows. Created by Jesse Vincet (obra), it has accumulated 33,700+ GitHub stars and was officially accepted into Anthropic's Claude plugins marketplace in January 2026.

Core Philosophy:

• Test-Driven Development - Write tests first, always
• Systematic over ad-hoc - Process over guessing
• Complexity reduction - Simplicity as primary goal
• Evidence over claims - Verify before declaring success

How it Works:

1. Brainstorming - Agent refines rough ideas through Socratic questioning before writing code
2. Git Worktrees - Creates isolated workspace on new branch with clean test baseline
3. Writing Plans - Breaks work into 2-5 minute tasks with exact file paths and verification steps
4. Subagent-Driven Development - Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality)
5. Test-Driven Development - Enforces RED-GREEN-REFACTOR cycle, deletes code written before tests
6. Code Review - Reviews against plan, reports issues by severity
7. Finishing Branch - Verifies tests, presents merge/PR options, cleans up worktree

Key Architecture Components

Skills Library (14+ composable skills):

• brainstorming - Interactive design refinement
• writing-plans - Detailed implementation plans
• executing-plans - Batch execution with human checkpoints
• subagent-driven-development - Fast iteration with staged review
• test-driven-development - RED-GREEN-REFACTOR enforcement
• systematic-debugging - 4-phase root cause process
• using-git-worktrees - Parallel development branches
• dispatching-parallel-agents - Concurrent subagent workflows
• requesting-code-review / receiving-code-review - Structured feedback loops
• verification-before-completion - Ensure fixes actually work
• writing-skills - Meta-skill for creating new skills

Agent Types:

• code-reviewer - Specialized agent for reviewing code quality, patterns, and architecture

Integration Methods:

• Claude Code: Plugin marketplace installation (/plugin install superpowers@superpowers-marketplace)
• Codex/OpenCode: Manual installation via system prompt injection
• Skills System: Markdown-based skill definitions that agents automatically discover and use

Integration Patterns with Agentic Workflows

1. Skills as Workflow Patterns

The Superpowers skills system directly maps to gh-aw's markdown-based workflow definitions. Key patterns:

Progressive Workflow Execution:

# Superpowers Pattern
1. Brainstorm design → Save design doc
2. Approve design → Create git worktree  
3. Write plan → Break into tasks
4. Execute plan → Spawn subagents
5. Review & merge → Create PR

# gh-aw Integration Opportunity
Define agent behaviors as composable workflow modules
that enforce development best practices

Skill-Based Safety:

• Superpowers enforces TDD by deleting code written before tests
• gh-aw could adopt similar enforcement patterns for safe-outputs validation
• Skills can include pre/post execution hooks for verification

2. Subagent Architecture

Superpowers' subagent-driven development model aligns with gh-aw's multi-agent orchestration:

Two-Stage Review Process:

1. Spec Compliance - Does it match the plan?
2. Code Quality - Is it well-written?

gh-aw Application:

• Workflow could spawn specialized agents for different phases
• Parent agent orchestrates, child agents execute specific tasks
• Each subagent has focused context (prevents bloat)
• Results aggregated and reviewed systematically

3. System Prompt Injection Patterns

Superpowers uses sophisticated prompt engineering to make skills "mandatory workflows, not suggestions":

Key Techniques:

• Auto-discovery - Agent checks for relevant skills before any task
• Progressive disclosure - Skills reveal information in digestible chunks
• Conditional activation - Skills trigger based on context (e.g., "when writing code, use test-driven-development")
• Verification loops - Skills include explicit verification steps

gh-aw Integration:

# Current gh-aw Pattern
---
on: issue_comment
permissions: read
---
## Task
Do something...

# Enhanced with Superpowers Pattern
---
on: issue_comment
permissions: read
skills: [brainstorming, writing-plans, verification-before-completion]
---
## Task
Before implementing, brainstorm the approach with the user.
Then create a detailed plan. Execute the plan systematically.
Verify results before reporting completion.

4. MCP Integration

Both Superpowers and gh-aw use Model Context Protocol (MCP) for tool integration:

Superpowers + Claude Code:

• MCP servers provide tools like GitHub, Slack, database access
• Skills can invoke MCP tools through standardized interface
• Tools are allow-listed for security

gh-aw Already Has:

• GitHub MCP server integration
• Safe-outputs for controlled write operations
• Security boundaries and sandboxing

Integration Opportunity:

• Adopt Superpowers' skill-based tool usage patterns
• Create gh-aw skills that wrap safe-outputs with verification
• Use subagents for tool-heavy workflows (e.g., one agent reads, another writes, third verifies)

Industry Context: Agentic AI in 2026

Market Growth:

• Agentic AI market projected to grow from $7.8B → $52B by 2030
• Gartner predicts 40% of enterprise apps will embed AI agents by end of 2026 (up from <5% in 2025)
• MCP ecosystem grew 80x in 5 months (100k → 8M downloads)

Key Trends:

1. Multi-Agent Systems - Gartner reported 1,445% surge in multi-agent inquiries (Q1 2024 → Q2 2025)
2. Workflow Ownership - Agents moving from single-task to end-to-end workflow management
3. Bounded Autonomy - Production systems use checkpoints, escalation paths, human oversight
4. Long-Running Agents - Task horizons expanding from minutes to days/weeks
5. Standardization - MCP and A2A protocols becoming HTTP-equivalent for agents

Relevance to gh-aw:

• Superpowers represents production-ready patterns for agent workflow management
• 33.7k stars indicates significant community validation
• Integration with Claude Code's plugin marketplace shows Anthropic endorsement
• Skills system provides reusable, tested patterns for common development workflows

Technical Integration Approaches

Approach 1: Skills as Workflow Templates

Implementation:

# .github/aw/skills/tdd-workflow.md
---
description: Enforce TDD for code changes
triggers: [code_change, pull_request]
---

## Test-Driven Development Workflow

Before writing any code:
1. Write a failing test that captures the requirement
2. Run the test suite - verify it fails
3. Write minimal code to make the test pass
4. Run the test suite - verify it passes
5. Refactor if needed
6. Commit with message "test: (description)" then "feat: (description)"

If you write code before tests, delete it and start over.

Benefits:

• Reusable across workflows
• Enforces best practices
• Can be composed (one workflow uses multiple skills)

Approach 2: Subagent Orchestration

Implementation:

# .github/workflows/complex-feature.lock.yml
name: Complex Feature Development
on:
  issue_comment:
    types: [created]
jobs:
  orchestrator:
    runs-on: ubuntu-latest
    steps:
      - name: Run orchestrator agent
        uses: githubnext/gh-aw@main
        with:
          agent: orchestrator
          subagents:
            - design-agent (brainstorm)
            - implementation-agent (execute-plan)  
            - review-agent (code-review)
          workflow: .github/aw/complex-feature.md

Benefits:

• Parallel execution of independent tasks
• Specialized agents for different concerns
• Natural checkpoints between phases

Approach 3: Verification Hooks

Implementation:

# .github/aw/workflows/safe-deployment.md
---
verification-required: true
verification-hooks:
  pre-execution: verify-permissions
  post-execution: verify-safe-outputs
---

## Deployment Task

Execute deployment steps...

[After agent generates plan, verification hook runs]
[After agent completes task, output validation runs]
[Only if both pass does workflow proceed]

Benefits:

• Safety by default
• Catches issues before they cause damage
• Aligns with gh-aw's safe-outputs philosophy

Recommended Integration Strategy

Phase 1: Skill System Foundation (Week 1-2)

• Add skills/ directory to gh-aw project structure
• Create core skills: brainstorming, writing-plans, verification-before-completion
• Implement skill discovery mechanism (agents read skills before execution)
• Document skill authoring guidelines

Phase 2: Workflow Enhancement (Week 3-4)

• Update existing workflows to reference skills
• Create workflow templates that combine multiple skills
• Add skill-based validation to CLI (gh aw validate)
• Test with pilot workflows

Phase 3: Subagent Support (Week 5-6)

• Implement subagent spawning mechanism
• Add orchestration patterns for multi-agent workflows
• Create review and verification agents
• Update documentation with subagent examples

Phase 4: Advanced Patterns (Week 7-8)

• Add systematic debugging skills
• Implement git worktree patterns for parallel development
• Create meta-skills for workflow authoring
• Community feedback and iteration

Recommendations

For gh-aw Project

1. Adopt Skills Architecture

   • Create .github/aw/skills/ directory
   • Port Superpowers' core skills (brainstorming, writing-plans, TDD, verification)
   • Make skills discoverable to agents via system prompt

2. Implement Subagent Orchestration

   • Add multi-agent workflow support
   • Parent agent orchestrates, child agents execute
   • Each phase has focused context and clear responsibilities

3. Enforce Verification Patterns

   • Require verification steps in workflows
   • Block completion without evidence
   • "Show, don't tell" - agents must prove success

4. Structured Development Workflow

   • Brainstorm → Plan → Execute → Review → Verify → Merge
   • Each phase has clear entry/exit criteria
   • Agents can't skip steps

5. Community Engagement

   • Document integration with Superpowers
   • Create migration guide for Superpowers users
   • Contribute patterns back to Superpowers project

For Development Teams

1. Start with Pilot Workflows

   • Choose 2-3 workflows to enhance with skills
   • Measure quality improvements
   • Iterate based on results

2. Build Skill Library

   • Document common patterns as skills
   • Share across team
   • Version control in repository

3. Train on Patterns

   • Systematic debugging
   • Test-driven development
   • Code review processes

Key Sources

• Superpowers GitHub Repository - 33.7k stars, comprehensive skill library
• [Superpowers Blog Post]((redacted) - Philosophy and design principles
• [Medium: Superpowers Explained]((redacted) - Deep dive into architecture
• [Claude Code MCP Integration Guide]((redacted) - Technical reference for MCP and skills
• Anthropic 2026 Agentic Coding Trends Report - Industry context
• [Machine Learning Mastery: 7 Agentic AI Trends]((redacted) - Multi-agent systems and orchestration patterns
• [Medium: Agentic CI/CD with GitHub Actions]((redacted) - GitHub Actions integration examples

Suggested Next Steps

1. Prototype Integration - Create proof-of-concept skill in gh-aw that mirrors Superpowers' brainstorming skill
2. Design RFC - Write design proposal for gh-aw skills system architecture
3. Community Discussion - Open issue to gather feedback on integration approach
4. Pilot Implementation - Convert 2-3 existing workflows to use skills pattern
5. Documentation - Create guide for authoring gh-aw skills
6. Upstream Collaboration - Reach out to @obra about collaboration opportunities

---

Bottom Line: Superpowers provides battle-tested patterns for structured agent workflows that directly address gh-aw's goal of safe, reliable agentic automation. The skills system, subagent architecture, and verification patterns are immediately applicable and would significantly enhance gh-aw's capability for complex, multi-step workflows.

AI generated by Scout