diff --git a/MULTI_AGENT_UPDATES.md b/MULTI_AGENT_UPDATES.md new file mode 100644 index 00000000..57ce2bd6 --- /dev/null +++ b/MULTI_AGENT_UPDATES.md @@ -0,0 +1,338 @@ +# Multi-Agent Enhancement Updates + +## Summary + +Enhanced superpowers plugin with generic multi-agent invocation capability. When similar agents exist (e.g., multiple code-reviewers), the system now automatically discovers and invokes all of them in parallel, then synthesizes their findings for comprehensive coverage and consensus validation. + +## Changes Made + +### 1. New Skill: `invoking-similar-agents` + +**Location:** `skills/invoking-similar-agents/SKILL.md` + +**Purpose:** Generic mechanism for discovering and invoking multiple agents with similar capabilities. + +**Key Features:** +- **Automatic agent discovery** - Finds agents with similar names/roles across all sources: + - Built-in agents (Claude Code system prompt) + - Superpowers agents (plugin-provided) + - Custom agents (`~/.claude/agents/`) +- **Parallel dispatch** - Invokes all discovered agents simultaneously +- **Result synthesis** - Aggregates findings with: + - Consensus issues (found by 2+ agents) - HIGH PRIORITY + - Unique findings (found by single agent) + - Contradictions (where agents disagree) + - Positive highlights (consensus on strengths) + +**Agent Discovery Algorithm:** +1. Normalize agent name (handle variations: dashes, underscores, prefixes) +2. Search all agent sources via direct filesystem search: + - Custom agents: `~/.claude/agents/` (filesystem search) + - Superpowers templates: `~/.claude/plugins/cache/superpowers/skills/` + - Built-in agents: Known from system prompt +3. Filter by capability/role matching +4. Deduplicate results + +**When to Use:** +- Security-critical code reviews +- Major feature implementations +- Before merging to main branch +- Complex architectural decisions + +### 2. Updated Skill: `requesting-code-review` + +**Location:** `skills/requesting-code-review/SKILL.md` + +**Changes:** +- Now uses `invoking-similar-agents` skill for agent discovery +- Automatically finds and invokes all code-reviewer agents +- Enhanced examples showing: + - Single reviewer workflow (backward compatible) + - Multiple reviewer workflow (new capability) + - Synthesis of multiple reviews + +**Benefits:** +- No manual tracking of which agents exist +- Automatic discovery of new agents +- Consensus validation of findings +- Diverse perspectives (project-specific + general best practices) + +## Usage Example + +### Before (Manual, Single Agent) + +``` +You: Let me request code review. +[Dispatch code-reviewer] +[Review single agent's findings] +[Fix issues] +``` + +### After (Automatic, Multiple Agents) + +``` +You: Let me request code review using invoking-similar-agents. + +[Automatically discovers]: +- code-reviewer (custom, security-focused) +- superpowers:code-reviewer (general best practices) + +[Dispatches both in parallel] + +[Synthesizes results]: + CONSENSUS (HIGH PRIORITY): + - Both: Unencrypted credentials (auth.js:42) + + UNIQUE FINDINGS: + - Custom: Rate limiting missing + - Superpowers: CLI help text missing + + ACTION PLAN: + 1. Fix credential encryption (Critical, consensus) + 2. Add rate limiting (Major) + 3. Add CLI help (Important) + +[Fix issues in priority order] +``` + +## Benefits + +### 1. Comprehensive Coverage +- Different agents have different blind spots +- Multiple perspectives catch more issues +- Specialized expertise from custom agents +- General best practices from built-in agents + +### 2. Consensus Validation +- Issues found by 2+ agents are high confidence +- Reduces false positives +- Prioritizes fixes based on agreement + +### 3. Automatic Discovery +- No manual configuration needed +- Works with any agents that follow naming conventions +- Extensible to new agent types + +### 4. Generic Pattern +- Not limited to code-review +- Can be applied to: + - Debugging (multiple debugging agents) + - Architecture review (multiple architecture agents) + - Performance optimization (multiple perf agents) + - Security review (multiple security agents) + +## Architecture + +### Agent Sources (Priority Order) + +1. **Custom Agents** (`~/.claude/agents/`) + - User-defined, project-specific + - Highest priority for local context + +2. **Superpowers Agents** (`~/.claude/plugins/cache/superpowers/agents/`) + - Plugin-provided templates + - General best practices + +3. **Built-in Agents** (Claude Code system prompt) + - Core agents available by default + - Known from system prompt + +### Discovery Flow + +``` +User requests code review + ↓ +Use invoking-similar-agents skill + ↓ +Search custom agents directory + ↓ +Search superpowers templates + ↓ +Check built-in agents + ↓ +Find matching agents + ↓ +Dispatch all in parallel (Task tool) + ↓ +Collect results + ↓ +Synthesize findings + ↓ +Present unified review +``` + +### Synthesis Algorithm + +```python +def synthesize_reviews(reviews): + consensus = find_issues_in_multiple_reviews(reviews, threshold=2) + unique = find_unique_issues(reviews) + contradictions = find_disagreements(reviews) + strengths = find_common_praise(reviews) + + return { + 'consensus': sort_by_severity(consensus), # HIGH PRIORITY + 'unique': group_by_agent(unique), + 'contradictions': analyze_tradeoffs(contradictions), + 'strengths': strengths, + 'action_plan': prioritize(consensus, unique, contradictions) + } +``` + +## Configuration + +### Agent Naming Conventions + +For automatic discovery, agents should follow naming patterns: + +**Code Review Agents:** +- `code-reviewer` +- `code_reviewer` +- `*code*review*` +- `superpowers:code-reviewer` + +**Other Agent Types:** +- `debugger`, `debugging-agent`, `superpowers:debugger` +- `architect`, `architecture-reviewer`, `design-reviewer` +- `performance-optimizer`, `perf-agent` +- `security-reviewer`, `security-guardian` + +### Agent Metadata (Future Enhancement) + +Agents could include metadata for better discovery: + +```yaml +--- +name: code-reviewer +description: Security-focused code reviewer +tags: [code-review, security, python, javascript] +expertise: [authentication, cryptography, rate-limiting] +specialization: web-security +--- +``` + +## Testing + +### Test Scenarios + +1. **Single agent available** - Should work as before +2. **Multiple agents available** - Should invoke all and synthesize +3. **No agents available** - Should gracefully handle +4. **Agents with different formats** - Should normalize and discover +5. **Contradictory findings** - Should flag and explain + +### Manual Testing + +```bash +# Test 1: Verify skill file exists +ls ~/.claude/plugins/cache/superpowers/skills/invoking-similar-agents/SKILL.md + +# Test 2: List custom agents +find ~/.claude/agents -name "*code*review*.md" + +# Test 4: In Claude Code session +# Request code review and verify multiple agents are invoked +``` + +## Future Enhancements + +### 1. Agent Tagging System +- Add metadata/tags to agents for better discovery +- Support capability-based matching (e.g., "find all security agents") + +### 2. Configurable Discovery Rules +- User-defined matching rules +- Fuzzy matching threshold configuration +- Priority/preference settings + +### 3. Performance Optimization +- Parallel synthesis +- Incremental reviews (only changed files) +- Cache discovery results per session + +### 4. Result Caching +- Cache agent reviews by git SHA +- Reuse reviews for same code +- Invalidate on code changes + +### 5. Agent Specialization Routing +- Route specific issues to specialized agents +- E.g., security issues → security-reviewer +- E.g., performance issues → performance-optimizer + +### 6. Weighted Consensus +- Weight findings by agent expertise +- Higher confidence for specialized agents in their domain +- Lower weight for general findings + +## Migration Guide + +### For Existing Users + +**No breaking changes!** The `requesting-code-review` skill still works as before when only one agent exists. + +**To enable multi-agent:** +1. Add custom agents to `~/.claude/agents/` +2. Follow naming conventions (e.g., `code-reviewer`, `code_reviewer`) +3. Request code review as normal +4. System automatically discovers and uses all available agents + +### For Plugin Developers + +**To make your agents discoverable:** +1. Follow naming conventions for your agent type +2. Add clear description in frontmatter +3. Consider adding tags/metadata (future) +4. Document agent capabilities + +**Example agent frontmatter:** +```yaml +--- +name: my-code-reviewer +description: TypeScript-focused code reviewer specializing in React +tools: Read, Grep, Glob, Bash +expertise: [typescript, react, hooks, performance] +--- +``` + +## Rollback Plan + +If issues arise, rollback is simple: + +```bash +# Remove new skill +rm -rf ~/.claude/plugins/cache/superpowers/skills/invoking-similar-agents + +# Restore requesting-code-review from git +cd ~/.claude/plugins/cache/superpowers +git checkout skills/requesting-code-review/SKILL.md +``` + +## Files Modified + +``` +~/.claude/plugins/cache/superpowers/ +├── skills/ +│ ├── invoking-similar-agents/ [NEW] +│ │ └── SKILL.md [NEW] - Generic multi-agent pattern +│ └── requesting-code-review/ +│ └── SKILL.md [MODIFIED] - Uses invoking-similar-agents +└── MULTI_AGENT_UPDATES.md [NEW] - This document +``` + +## Related Skills + +- `requesting-code-review` - Updated to use multi-agent +- `subagent-driven-development` - Could integrate multi-agent reviews +- `systematic-debugging` - Could benefit from multiple debuggers +- `writing-plans` - Could use multiple reviewers for plan validation + +## Notes + +This enhancement makes the superpowers plugin more powerful and flexible by: +1. Providing a **generic pattern** for multi-agent invocation (not just code review) +2. **Automatic discovery** reducing manual configuration +3. **Consensus validation** improving review quality +4. **Backward compatible** - works with single or multiple agents + +The pattern can be extended to any domain where multiple perspectives add value. diff --git a/skills/invoking-similar-agents/SKILL.md b/skills/invoking-similar-agents/SKILL.md new file mode 100644 index 00000000..287c8d04 --- /dev/null +++ b/skills/invoking-similar-agents/SKILL.md @@ -0,0 +1,273 @@ +--- +name: invoking-similar-agents +description: Use when you need comprehensive perspective on a task - automatically discovers and invokes all agents with similar names or roles in parallel, then synthesizes their findings for better coverage and consensus validation +--- + +# Invoking Similar Agents + +Discover and dispatch multiple agents with similar capabilities to get diverse perspectives and comprehensive coverage. + +**Core principle:** Multiple perspectives catch more issues and validate findings through consensus. + +## When to Use + +**Mandatory:** +- Security-critical code reviews +- Major feature implementations +- Before merging to main branch +- Complex architectural decisions + +**Optional but valuable:** +- Code reviews for important features +- Design decisions with trade-offs +- Debugging complex issues +- Performance optimization reviews + +## How It Works + +### 1. Agent Discovery + +**Find all agents matching the role:** + +Discover agents through multiple sources: +- **Name matching**: Find agents with similar names (e.g., "code-reviewer", "code_reviewer", "superpowers:code-reviewer") +- **Role matching**: Find agents with similar descriptions or capabilities +- **Sources**: Check built-in agents, superpowers agents, and custom agents + +**Discovery methods:** + +1. **Direct filesystem search**: + - Custom agents: `~/.claude/agents/**/*.md` + - Superpowers templates: `~/.claude/plugins/cache/superpowers/skills/*/` + - Built-in agents: Known from Claude Code system prompt + +**Note:** Agent discovery uses direct filesystem search - no registry or configuration file needed. + +### 2. Parallel Dispatch + +**Invoke all discovered agents in parallel:** + +Use Task tool to dispatch agents simultaneously: +- Each agent receives the same context/prompt +- All agents work independently +- No shared state between agents +- Results collected when all complete + +**Example for code review:** +```bash +# Get context +BASE_SHA=$(git rev-parse HEAD~1) +HEAD_SHA=$(git rev-parse HEAD) + +# Dispatch all code-reviewer agents in parallel +Task 1: code-reviewer (custom agent) +Task 2: superpowers template-based reviewer +Task 3: security-focused-reviewer (if exists) +``` + +### 3. Result Aggregation + +**Synthesize findings from all agents:** + +**Consensus Issues (HIGH PRIORITY):** +- Issues found by 2+ agents +- High confidence these are real problems +- Fix immediately + +**Unique Findings:** +- Issues found by single agent +- May indicate specialized knowledge +- Evaluate based on agent's expertise area + +**Contradictions:** +- Agents disagree on approach/severity +- Investigate to understand trade-offs +- May require human judgment + +**Strengths:** +- Positive feedback from multiple agents +- Validates good design decisions + +### 4. Synthesis Format + +```markdown +## Multi-Agent Review Summary + +### Agents Consulted +- code-reviewer (custom, security-focused) +- superpowers:code-reviewer (general best practices) +- performance-optimizer (if performance-related) + +### Consensus Findings (High Confidence) +[Issues found by 2+ agents] + +🔴 **Critical** (found by N agents): +- Issue description +- File:line references +- Suggested fix + +🟡 **Important** (found by N agents): +- ... + +### Unique Findings by Agent +**code-reviewer:** +- [Issues only this agent found] + +**superpowers:code-reviewer:** +- [Issues only this agent found] + +### Contradictions/Trade-offs +[Where agents disagree and why] + +### Positive Highlights (Consensus) +[What multiple agents praised] + +### Recommended Actions +1. [Prioritized list based on consensus + severity] +``` + +## Algorithm: Finding Similar Agents + +### Step 1: Normalize agent name + +```text +Input: "code-reviewer" +Variations to check: +- code-reviewer +- code_reviewer +- coderereviewer +- superpowers:code-reviewer +- *code*review* +``` + +### Step 2: Search agent locations + +```bash +# Primary: Direct filesystem search (always works) +find ~/.claude/agents -name "*code*review*.md" + +# Check superpowers templates +find ~/.claude/plugins/cache/superpowers/skills -name "*code*review*" -type d + +# Built-in agents are known from Claude Code system prompt +# No filesystem search needed - they're in the agent list +``` + +### Step 3: Filter by capability + +- Read agent descriptions +- Match against desired role/capability +- Include agents with overlapping expertise + +### Step 4: Deduplicate + +- Remove duplicate references to same agent +- Keep highest-specificity version + +## Example: Code Review + +```text +[Just completed authentication feature] + +You: Let me use invoking-similar-agents to get comprehensive code review. + +Step 1: Discover code-reviewer agents + Found: + - code-reviewer (custom, security-focused) + - superpowers template (general practices) + +Step 2: Dispatch both in parallel + [Task 1: code-reviewer with context] + [Task 2: superpowers template with context] + +Step 3: Collect results + code-reviewer: + 🔴 Critical: Plain-text credentials (auth.js:42) + 🟡 Major: Missing rate limiting + 🟢 Minor: Variable naming + + superpowers: + Critical: Unencrypted credentials (auth.js:42) + Important: No CLI help text + Strengths: Good test coverage + +Step 4: Synthesize + CONSENSUS (FIX NOW): + - Both: Unencrypted credentials at auth.js:42 + + UNIQUE FINDINGS: + - Custom: Rate limiting missing + - Superpowers: CLI help text missing + + POSITIVE (CONSENSUS): + - Good test coverage + + ACTION PLAN: + 1. Fix credential encryption (Critical, consensus) + 2. Add rate limiting (Major, security-focused) + 3. Add CLI help (Important, UX) + 4. Improve naming (Minor, optional) + +[Implement fixes in priority order] +``` + +## Integration with Existing Skills + +**requesting-code-review:** +- Uses this skill to discover all code-reviewer agents +- Dispatches discovered agents in parallel +- Synthesizes review results + +**systematic-debugging:** +- Could use to get multiple debugging perspectives +- Especially for complex/unclear bugs + +**writing-plans:** +- Could use to validate plan quality from multiple angles +- Architecture review agents + +## Benefits + +**Comprehensive Coverage:** +- Different agents have different blind spots +- Multiple perspectives = better coverage + +**Consensus Validation:** +- Issues found by multiple agents are high confidence +- Reduces false positives + +**Specialized Expertise:** +- Custom agents may have project-specific knowledge +- Built-in agents have general best practices +- Security agents focus on vulnerabilities + +**Redundancy:** +- If one agent misses something, others may catch it +- Safety net for critical reviews + +## Red Flags + +**Don't:** +- Invoke similar agents for trivial tasks +- Ignore consensus findings +- Cherry-pick only favorable reviews +- Skip synthesis step + +**Do:** +- Use for high-stakes decisions/reviews +- Prioritize consensus issues +- Investigate contradictions +- Balance cost (multiple agents) vs benefit (better coverage) + +## Configuration + +**Agent matching rules** can be customized: +- Fuzzy name matching threshold +- Description keyword matching +- Expertise area tagging +- Priority/preference for certain agents + +**Future enhancement:** Create agent tags/metadata for better discovery +- Tags: ["code-review", "security", "performance"] +- Specializations: ["react", "node.js", "python"] +- Expertise level: ["junior", "senior", "expert"] diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index f8b1a565..dc8c9e80 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/skills/requesting-code-review/SKILL.md @@ -1,13 +1,13 @@ --- name: requesting-code-review -description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches superpowers:code-reviewer subagent to review implementation against plan or requirements before proceeding +description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - uses invoking-similar-agents to discover and dispatch all code-reviewer agents in parallel, then synthesizes their findings --- # Requesting Code Review -Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. +Dispatch code-reviewer subagent(s) to catch issues before they cascade. -**Core principle:** Review early, review often. +**Core principle:** Review early, review often. Uses invoking-similar-agents skill for comprehensive coverage. ## When to Request Review @@ -29,24 +29,42 @@ BASE_SHA=$(git rev-parse HEAD~1) # or origin/main HEAD_SHA=$(git rev-parse HEAD) ``` -**2. Dispatch code-reviewer subagent:** +**2. Use invoking-similar-agents skill:** -Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md` +This skill automatically: +- Discovers all code-reviewer agents (built-in, superpowers, custom) +- Dispatches them in parallel with the same context +- Synthesizes findings with consensus validation -**Placeholders:** +**Agent discovery methods:** +- Direct filesystem search of custom agents: `~/.claude/agents/**/code*review*.md` +- Superpowers templates: `requesting-code-review/code-reviewer.md` +- Built-in agents from Claude Code system prompt + +**3. Prepare context for agents:** + +All discovered agents receive the same context: - `{WHAT_WAS_IMPLEMENTED}` - What you just built - `{PLAN_OR_REQUIREMENTS}` - What it should do - `{BASE_SHA}` - Starting commit - `{HEAD_SHA}` - Ending commit - `{DESCRIPTION}` - Brief summary -**3. Act on feedback:** +**4. Review synthesis (automatic):** + +The invoking-similar-agents skill handles: +- **Consensus issues**: Found by 2+ agents (HIGH PRIORITY) +- **Unique findings**: Found by single agent (evaluate by expertise) +- **Contradictions**: Where agents disagree (investigate trade-offs) +- **Positive highlights**: What multiple agents praised + +**5. Act on synthesized feedback:** - Fix Critical issues immediately - Fix Important issues before proceeding - Note Minor issues for later - Push back if reviewer is wrong (with reasoning) -## Example +## Example: Single Reviewer ``` [Just completed Task 2: Add verification function] @@ -56,7 +74,7 @@ You: Let me request code review before proceeding. BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}') HEAD_SHA=$(git rev-parse HEAD) -[Dispatch superpowers:code-reviewer subagent] +[Dispatch code-reviewer subagent] WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md BASE_SHA: a7981ec @@ -74,6 +92,47 @@ You: [Fix progress indicators] [Continue to Task 3] ``` +## Example: Multiple Reviewers + +``` +[Just completed Task 3: Implement authentication] + +You: Let me request code review. I have both custom and superpowers reviewers available. + +BASE_SHA=$(git rev-parse HEAD~1) +HEAD_SHA=$(git rev-parse HEAD) + +[Dispatch BOTH reviewers in parallel]: + - code-reviewer (custom agent) + - superpowers template (filled with context) + +[Custom code-reviewer returns]: + 🔴 Critical: Plain-text API key in auth.js:42 + 🟡 Major: Missing rate limiting + 🟢 Minor: Improve variable naming + Assessment: Major Issues - needs security fixes + +[Superpowers reviewer returns]: + Strengths: Good test coverage, clean error handling + Issues: + Critical: Credentials not encrypted + Important: No help text in CLI + Assessment: With fixes + +You: Synthesizing reviews... + CONSENSUS (HIGH PRIORITY): + - Both found: Unencrypted credentials (auth.js:42) + + UNIQUE FINDINGS: + - Custom: Rate limiting missing + - Superpowers: No CLI help text + + Action: Fix credential encryption immediately, then address rate limiting and help text. + +[Fix all critical/important issues] +[Continue to Task 4] +``` + ## Integration with Workflows **Subagent-Driven Development:** @@ -102,4 +161,19 @@ You: [Fix progress indicators] - Show code/tests that prove it works - Request clarification -See template at: requesting-code-review/code-reviewer.md +## Benefits of Multiple Reviewers + +**Why use invoking-similar-agents:** +- **Automatic discovery**: No manual tracking of which agents exist +- **Diverse perspectives**: Custom agents (project-specific) + built-in (general practices) +- **Comprehensive coverage**: Different agents catch different issues +- **Consensus validation**: Issues found by multiple agents are high-confidence +- **Reduced blind spots**: One agent's weakness is another's strength + +**When to use single vs multiple:** +- **Single**: Quick reviews, small changes, time-constrained (skip invoking-similar-agents) +- **Multiple**: Major features, security-critical code, before merge to main (use invoking-similar-agents) + +See also: +- invoking-similar-agents skill (generic multi-agent pattern) +- Template at: requesting-code-review/code-reviewer.md