waldstorm

Multi-agent orchestration that brings together specialized experts to analyze, plan, and execute tasks with comprehensive coverage.

Overview

1. Analyze the task and select 3-5 relevant experts
2. Create a team and dispatch expert teammates in parallel
3. Collect findings from teammate messages and synthesize into prioritized action items
4. Write implementation plan to file using superpowers:writing-plans
5. Execute with checkpoints and progress journaling

Expert Panel

General Agents (Built-in)

Each expert has a dedicated agent definition in agents/ with frontmatter (name, description, tools, model, memory) and persona prompt:

Domain-Specific Agents (Project-Local)

Projects can define domain-specific agents in their plugin agents/ directories or in .claude/agents/.

Discovery: At task start, check for project-local agent definitions:

• Plugin agents: plugins/*/agents/*.md
• Project agents: .claude/agents/*.md

Each agent file uses frontmatter (name, description, tools, model, memory) followed by persona prompt and analysis instructions.

Usage: Domain agents are selected alongside general agents when their description triggers match the task. Spawn them as teammates like general agents.

Instructions

Step 1: Understand the Task

Ask the user to describe the task if not already provided. Gather:

• What needs to be accomplished
• Any constraints or requirements
• Relevant context (files, systems involved)

Step 2: Discover Domain Agents

Check for project-local domain agents:

1. Look for plugin agents/ directories and .claude/agents/ in the project
2. If found, read agent descriptions to understand their specialties
3. Note available domain agents and their trigger keywords

Domain agents bring specialized knowledge that general agents lack (e.g., specific APIs, data models, deployment patterns).

Step 3: Select Relevant Agents

Analyze the task domain and select 3-5 agents from both pools:

• General agents (built-in) for cross-cutting concerns
• Domain agents (project-local) for specialized knowledge

Use this guide for general agents:

Announce: "Selected agents for this task: [list agents and why]"

If domain agents are selected, note their source.

Step 4: Create Team and Dispatch Agent Teammates

Create a team and spawn agent teammates for parallel analysis:

1. Create team: Use TeamCreate with team_name: "waldstorm-{task-slug}" (e.g., waldstorm-add-auth)
2. Create tasks: Use TaskCreate for each agent's analysis task, including:
   • Subject: "{Agent Name} analysis"
   • Description: the task description + what the agent should analyze
3. Spawn teammates: Use the Task tool with team_name and name params to launch one teammate per agent. Each teammate's prompt should include the agent's persona and instructions from their agent definition file in agents/.
4. Assign tasks: Use TaskUpdate with owner to assign each task to its teammate

Each agent returns via message:

• Concerns (prioritized HIGH/MEDIUM/LOW)
• Recommendations (specific actions)
• Questions (clarifications needed)

Step 5: Collect and Synthesize

Wait for all teammate messages. Use TaskList to verify all expert tasks are completed.

Gather all expert outputs from messages and synthesize into prioritized action items:

## Prioritized Action Items

### Critical
1. [Expert tags] Description of critical action

### Important
2. [Expert tags] Description of important action

### Nice to Have
3. [Expert tags] Description of optional improvement

### Conflicts to Resolve
- [Expert A] recommends X; [Expert B] flags concern Y
  - Options presented for user decision

Present synthesis to user. Ask if they want to:

• Proceed with all recommendations
• Modify priorities
• Exclude certain items
• Add additional concerns

Step 6: Generate Implementation Plan

REQUIRED: Invoke superpowers:writing-plans to write the implementation plan to file.

The plan MUST be saved to: docs/plans/YYYY-MM-DD-<feature-name>.md

The plan should:

• Incorporate expert recommendations
• Order tasks by dependency and priority
• Include checkpoints for review
• Note which expert's recommendation each task addresses
• Follow the bite-sized task granularity from writing-plans (each step is one action)

Step 7: Execute with Checkpoints

Invoke superpowers:executing-plans to begin implementation.

During execution:

• Journal all TODOs to a todo file for the plan
• Track completed items as you go
• Pause at checkpoints for review
• Flag if implementation reveals new concerns

Step 8: Cleanup

After execution is complete:

1. Use SendMessage with type: "shutdown_request" to gracefully shut down all teammates
2. Use TeamDelete to clean up the team and task list

Example Flow

User: "Add user authentication to the API"

waldstorm:
1. Selected experts: Security Engineer, API Designer, Senior Dev, QA
2. TeamCreate: "waldstorm-add-auth"
3. Spawning 4 expert teammates in parallel...
   - Each reads their persona from experts/*.md
   - Each analyzes and sends findings via SendMessage
4. Synthesis (from teammate messages):
   - [CRITICAL] [Security] Use bcrypt for password hashing, not MD5
   - [CRITICAL] [Security, API] Implement rate limiting on auth endpoints
   - [HIGH] [API] Use JWT with short expiry + refresh tokens
   - [HIGH] [QA] Add integration tests for auth flows
   - [MEDIUM] [Senior Dev] Extract auth logic into dedicated service

5. User approves, writing plan...
6. Executing plan with checkpoints...
7. Shutdown teammates, TeamDelete

Superpowers Used

• superpowers:writing-plans - Convert recommendations to implementation plan
• superpowers:executing-plans - Execute with review checkpoints