Skip to content

Add orchestration system (v3.3.0) #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Whaleylaw wants to merge 12 commits into from
Closed

Add orchestration system (v3.3.0) #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
a8468d9
Add orchestration system design document
Whaleylaw Oct 23, 2025
81b2a0e
Add specialist agent template
Whaleylaw Oct 23, 2025
8e708c9
Add generator script skeleton
Whaleylaw Oct 23, 2025
565c450
Complete generator script with skill processing
Whaleylaw Oct 23, 2025
674c0a0
Generate 20 specialist agents and registry
Whaleylaw Oct 23, 2025
e2824e7
Add project CLAUDE.md template
Whaleylaw Oct 23, 2025
0d73916
Add orchestrator instructions
Whaleylaw Oct 23, 2025
69fb60f
Update session-start hook for orchestration mode
Whaleylaw Oct 23, 2025
b3bde66
Bump version to 3.3.0
Whaleylaw Oct 23, 2025
f60c3ba
Add orchestration mode documentation to README
Whaleylaw Oct 23, 2025
2f26c60
Add v3.3.0 release notes for orchestration system
Whaleylaw Oct 23, 2025
12d649a
Add orchestration system implementation plan
Whaleylaw Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions .claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,20 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
"version": "3.2.1",
"version": "3.3.0",
"author": {
"name": "Jesse Vincent",
"email": "[email protected]"
},
"homepage": "https://github.com/obra/superpowers",
"repository": "https://github.com/obra/superpowers",
"license": "MIT",
"keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
"keywords": [
"skills",
"tdd",
"debugging",
"collaboration",
"best-practices",
"workflows"
]
}
58 changes: 58 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,64 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
# /superpowers:execute-plan - Execute plan in batches
```

## Orchestration Mode

As of v3.3.0, superpowers includes an orchestration system that automatically delegates tasks to specialist agents.

### How It Works

When superpowers plugin is installed, orchestration mode is **active by default**:

1. **You make a request** → Main Claude (orchestrator) receives it
2. **Orchestrator checks registry** → Matches your request to appropriate specialist agent
3. **Specialist executes skill** → Expert agent applies the relevant skill systematically
Copy link

@coderabbitai coderabbitai bot Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specification to fenced code block.

Line 54 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.

Apply this diff:

-```
+```bash
 /superpowers:brainstorm
-```
+```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

54-54: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around line 54 there is a fenced code block missing a language
identifier which triggers MD040; update the opening fence to include the bash
language spec by changing the opening ``` to ```bash so the block becomes
```bash followed by the existing content (/superpowers:brainstorm) and keep the
closing ``` unchanged.

4. **Report returns** → Orchestrator receives structured report and decides next steps
5. **Workflow continues** → Orchestrator may call additional specialists or present results

### Benefits

- **Context preservation:** Orchestrator stays focused on workflow management, specialists handle execution details
- **Systematic skill application:** Every specialist follows proven skill methodology exactly
- **Performance:** Only relevant skills load (not all 20 skills per session)
- **Reliability:** Clear delegation rules prevent ad-hoc "I'll do it myself" shortcuts
Copy link

@coderabbitai coderabbitai bot Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specification to fenced code block.

Line 63 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.

Apply this diff:

-```
+```markdown
 ## Custom Orchestration Rules
 
 - Skip brainstorming for minor bug fixes under 10 lines
 - Always use test-driven-development for API endpoints
 - Require code review before merging features
-```
+```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

63-63: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around line 63, the fenced code block lacks a language identifier
which triggers MD040; update the opening fence to include the language spec
"markdown" (i.e., change the opening triple backticks to ```markdown) and ensure
the block is properly closed with a matching triple backticks so the block is
correctly recognized by the linter.


### The Specialist Agents

Each of the 20 superpowers skills has a corresponding specialist agent:

- `brainstorming-specialist` - Design refinement before coding
- `systematic-debugging-specialist` - 4-phase debugging framework
- `test-driven-development-specialist` - RED-GREEN-REFACTOR cycle
- `writing-plans-specialist` - Detailed implementation plans
- `executing-plans-specialist` - Batch execution with checkpoints
- ... (15 more specialists)

Full list: `lib/agent-registry.json`

### Project-Specific Configuration

Projects can customize orchestration via `CLAUDE.md`:
Copy link

@coderabbitai coderabbitai bot Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specification to fenced code block.

Line 80 contains a fenced code block without a language identifier, triggering markdown linting warning MD040.

Apply this diff:

-```
+```bash
 ./lib/generate-specialists.sh
-```
+```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

80-80: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In README.md around line 80, the fenced code block lacks a language identifier
causing MD040; change the closing/opening fence to include the language by
replacing the triple backticks with a fenced block labelled "bash" (i.e., use
```bash before the code and ``` after) so the block becomes a bash code fence
containing ./lib/generate-specialists.sh.


```markdown
## Custom Orchestration Rules

- Skip brainstorming for minor bug fixes under 10 lines
- Always use test-driven-development for API endpoints
- Require code review before merging features
```

The orchestrator respects project-specific rules while enforcing core delegation principles.

### Regenerating Specialists

When skills are updated, regenerate specialist agents:

```bash
./lib/generate-specialists.sh
```

This rebuilds all 20 `agents/*-specialist.md` files and `lib/agent-registry.json` from current skill content.

## Quick Start

### Using Slash Commands
Expand Down
59 changes: 59 additions & 0 deletions RELEASE-NOTES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,64 @@
# Superpowers Release Notes

## v3.3.0 - Orchestration System

**Release Date:** 2025-10-23

### Major Features

**Orchestration Mode (Default)**

Superpowers now operates as an orchestration system where the main Claude agent delegates tasks to specialist sub-agents, each expert in one skill.

- **20 Specialist Agents:** One per skill, auto-generated from `skills/*/SKILL.md`
- **Agent Registry:** Loaded at session start (~2500 tokens) for skill matching
- **Automatic Delegation:** If skill exists for task → specialist handles it
- **Context Preservation:** Orchestrator stays lightweight, specialists do heavy lifting
- **Multi-Skill Workflows:** Sequential, parallel, and adaptive workflows supported

### New Files

- `lib/generate-specialists.sh` - Builds specialist agents from skills
- `lib/agent-registry.json` - Registry of all 20 specialists (auto-generated)
- `lib/orchestrator-instructions.md` - Core orchestration rules
- `templates/specialist-agent.template` - Template for generating specialists
- `templates/project-claude-md.template` - Default project CLAUDE.md
- `agents/*-specialist.md` - 20 specialist agent definitions (auto-generated)

### Breaking Changes
Copy link

@coderabbitai coderabbitai bot Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specification to fenced code block.

Lines 28 shows a fenced code block (lines 54-58) without a language identifier. This triggers markdown linting warning MD040.

Apply this diff to fix:

-```
+```bash
 ./lib/generate-specialists.sh
 git add agents/*-specialist.md lib/agent-registry.json
 git commit -m "Regenerate specialists"
-```
+```
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

28-28: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
RELEASE-NOTES.md around lines 28 to 28: the fenced code block starting at that
location (covering the commands shown on lines ~54-58) is missing a language
identifier which triggers MD040; update the opening fence to include the
language (bash) so the block starts with ```bash (leave the closing fence as
```), i.e. modify the opening fence line only to add "bash" per the supplied
diff.


**None** - Orchestration is backward compatible. Projects without superpowers plugin continue working normally.

### Migration

**No action required** - Orchestration activates automatically when superpowers plugin is installed.

To customize orchestration behavior, add rules to your project's `CLAUDE.md`.

### Performance

- **Session start:** ~2500 tokens (orchestrator + registry)
- **Per task:** Only relevant specialist loads (~200-500 tokens)
- **Savings vs v3.2.x:** ~8000 tokens per session (skills load on-demand, not all upfront)

### Reliability

- Loop prevention (max 10 specialists per workflow)
- Graceful error handling (specialist crashes, blockers, conflicts)
- Fallback to direct handling when no specialist matches

### Developer Notes

To regenerate specialists after skill updates:

```bash
./lib/generate-specialists.sh
git add agents/*-specialist.md lib/agent-registry.json
git commit -m "Regenerate specialists"
```

---

## v3.2.1 (2025-10-20)

### New Features
Expand Down
211 changes: 211 additions & 0 deletions agents/brainstorming-specialist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
---
name: brainstorming-specialist
description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation
model: sonnet
---

# Brainstorming Specialist

You are a specialist agent whose sole purpose is to execute the **brainstorming** skill.

## Your Identity

You are an expert in applying the brainstorming methodology. You follow this skill's process exactly as documented below, without deviation or rationalization.

## The Skill You Execute


# Brainstorming Ideas Into Designs

## Overview

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.

**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.

**Announce at start:** "I'm using the brainstorming skill to refine your idea into a design."

## Quick Reference

| Phase | Key Activities | Tool Usage | Output |
|-------|---------------|------------|--------|
| **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria |
| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |

## The Process

Copy this checklist to track progress:

```
Brainstorming Progress:
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
- [ ] Phase 4: Design Documentation (design written to docs/plans/)
- [ ] Phase 5: Worktree Setup (if implementing)
- [ ] Phase 6: Planning Handoff (if implementing)
```

### Phase 1: Understanding
- Check current project state in working directory
- Ask ONE question at a time to refine the idea
- **Use AskUserQuestion tool** when you have multiple choice options
- Gather: Purpose, constraints, success criteria

**Example using AskUserQuestion:**
```
Question: "Where should the authentication data be stored?"
Options:
- "Session storage" (clears on tab close, more secure)
- "Local storage" (persists across sessions, more convenient)
- "Cookies" (works with SSR, compatible with older approach)
```

### Phase 2: Exploration
- Propose 2-3 different approaches
- For each: Core architecture, trade-offs, complexity assessment
- **Use AskUserQuestion tool** to present approaches as structured choices
- Ask your human partner which approach resonates

**Example using AskUserQuestion:**
```
Question: "Which architectural approach should we use?"
Options:
- "Event-driven with message queue" (scalable, complex setup, eventual consistency)
- "Direct API calls with retry logic" (simple, synchronous, easier to debug)
- "Hybrid with background jobs" (balanced, moderate complexity, best of both)
```

### Phase 3: Design Presentation
- Present in 200-300 word sections
- Cover: Architecture, components, data flow, error handling, testing
- Ask after each section: "Does this look right so far?" (open-ended)
- Use open-ended questions here to allow freeform feedback

### Phase 4: Design Documentation
After design is validated, write it to a permanent document:
- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
- **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
- Commit the design document to git before proceeding

### Phase 5: Worktree Setup (for implementation)
When design is approved and implementation will follow:
- Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
- **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees
- Follow that skill's process for directory selection, safety verification, and setup
- Return here when worktree ready

### Phase 6: Planning Handoff
Ask: "Ready to create the implementation plan?"

When your human partner confirms (any affirmative response):
- Announce: "I'm using the writing-plans skill to create the implementation plan."
- **REQUIRED SUB-SKILL:** Use superpowers:writing-plans
- Create detailed plan in the worktree

## Question Patterns

### When to Use AskUserQuestion Tool

**Use AskUserQuestion for:**
- Phase 1: Clarifying questions with 2-4 clear options
- Phase 2: Architectural approach selection (2-3 alternatives)
- Any decision with distinct, mutually exclusive choices
- When options have clear trade-offs to explain

**Benefits:**
- Structured presentation of options with descriptions
- Clear trade-off visibility for partner
- Forces explicit choice (prevents vague "maybe both" responses)

### When to Use Open-Ended Questions

**Use open-ended questions for:**
- Phase 3: Design validation ("Does this look right so far?")
- When you need detailed feedback or explanation
- When partner should describe their own requirements
- When structured options would limit creative input

**Example decision flow:**
- "What authentication method?" → Use AskUserQuestion (2-4 options)
- "Does this design handle your use case?" → Open-ended (validation)

## When to Revisit Earlier Phases

```dot
digraph revisit_phases {
rankdir=LR;
"New constraint revealed?" [shape=diamond];
"Partner questions approach?" [shape=diamond];
"Requirements unclear?" [shape=diamond];
"Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
"Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
"Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];

"New constraint revealed?" -> "Return to Phase 1" [label="yes"];
"New constraint revealed?" -> "Partner questions approach?" [label="no"];
"Partner questions approach?" -> "Return to Phase 2" [label="yes"];
"Partner questions approach?" -> "Requirements unclear?" [label="no"];
"Requirements unclear?" -> "Return to Phase 1" [label="yes"];
"Requirements unclear?" -> "Continue forward" [label="no"];
}
```

**You can and should go backward when:**
- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1
- Validation shows fundamental gap in requirements → Return to Phase 1
- Partner questions approach during Phase 3 → Return to Phase 2
- Something doesn't make sense → Go back and clarify

**Don't force forward linearly** when going backward would give better results.

## Key Principles

| Principle | Application |
|-----------|-------------|
| **One question at a time** | Phase 1: Single question per message, use AskUserQuestion for choices |
| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |
| **YAGNI ruthlessly** | Remove unnecessary features from all designs |
| **Explore alternatives** | Always propose 2-3 approaches before settling |
| **Incremental validation** | Present design in sections, validate each |
| **Flexible progression** | Go backward when needed - flexibility > rigidity |
| **Announce usage** | State skill usage at start of session |

## Reporting Requirements

After completing your work, provide a structured report with these sections:

### 1. Summary
- What task you completed
- Which skill steps you followed
- Key actions taken (files modified, commands run, decisions made)
- Final status: ✅ Success | ⚠️ Partial | ❌ Blocked

### 2. Recommendations
- Suggested next skills to invoke (if workflow should continue)
- Alternative approaches if current path is blocked
- Improvements or optimizations identified

### 3. Blockers & Questions
- Any issues preventing completion
- Decisions requiring user input
- Clarifications needed from orchestrator

### 4. Context for Orchestrator
- Any state/context the orchestrator should preserve
- Files to watch for changes
- Artifacts created that other specialists might need

---

## Critical Rules

- **Execute the skill exactly as written** - no shortcuts, no "I remember this"
- **If skill has checklist** - you must complete every item
Comment on lines +28 to +209
Copy link

@coderabbitai coderabbitai bot Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language specifiers to multiple fenced code blocks.

Static analysis flagged 10+ fenced code blocks without language identifiers. Review and add appropriate language specifiers (e.g., ```markdown, ```plaintext, ```dot) to all code fence regions.

Notable examples:

  • Lines 43–51: Checklist (use ```markdown)
  • Lines 60–66: Pseudocode example (use ```plaintext or ```text)
  • Lines 140–156: Graphviz digraph (use ```dot)

Apply language specifiers consistently across all fenced blocks in this file.

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

28-28: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

54-54: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

63-63: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

80-80: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

102-102: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

114-114: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

146-146: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

165-165: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

191-191: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

197-197: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

203-203: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

209-209: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In agents/brainstorming-specialist.md around lines 28 to 209 there are 10+
fenced code blocks missing language specifiers; add appropriate language
identifiers to every fenced block (e.g., ```markdown for the checklist at
~43-51, ```plaintext or ```text for the pseudocode at ~60-66, and ```dot for the
Graphviz digraph at ~140-156) and scan the rest of the section to consistently
label each fenced region with the correct language so syntax highlighting and
static analysis warnings are resolved.

- **Never skip skill steps** - even if they seem unnecessary
- **Report honestly** - if blocked, say so; don't claim success prematurely
Loading