From 3fa2af63f4206d986561062d262516d24d13a8e0 Mon Sep 17 00:00:00 2001 From: Grant Callaghan Date: Sat, 25 Oct 2025 08:54:47 -0700 Subject: [PATCH 1/5] Add generic multi-agent invocation for comprehensive reviews MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit introduces a generic mechanism for discovering and invoking multiple agents with similar capabilities in parallel, then synthesizing their findings with consensus validation. Changes: - New skill: invoking-similar-agents * Generic pattern for multi-agent discovery and invocation * Works across all agent sources (built-in, superpowers, custom) * Parallel dispatch with result synthesis * Consensus validation (issues found by 2+ agents = high priority) * Generic - not limited to code-review - Updated skill: requesting-code-review * Now uses invoking-similar-agents for agent discovery * Automatically finds all code-reviewer agents * Added examples for single and multiple reviewer workflows * Backward compatible with single agent usage - Documentation: MULTI_AGENT_UPDATES.md * Comprehensive implementation guide * Usage examples and benefits * Architecture and testing results * Migration guide for users Benefits: - Automatic discovery - no manual configuration - Diverse perspectives from multiple agents - Consensus validation reduces false positives - Comprehensive coverage - multiple agents catch different issues - Extensible to any agent type (debugging, architecture, performance, etc.) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- MULTI_AGENT_UPDATES.md | 339 ++++++++++++++++++++++++ skills/invoking-similar-agents/SKILL.md | 266 +++++++++++++++++++ skills/requesting-code-review/SKILL.md | 95 ++++++- 3 files changed, 690 insertions(+), 10 deletions(-) create mode 100644 MULTI_AGENT_UPDATES.md create mode 100644 skills/invoking-similar-agents/SKILL.md diff --git a/MULTI_AGENT_UPDATES.md b/MULTI_AGENT_UPDATES.md new file mode 100644 index 00000000..c6b755d6 --- /dev/null +++ b/MULTI_AGENT_UPDATES.md @@ -0,0 +1,339 @@ +# 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: + - Agent registry (`~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md`) + - Custom agents (`~/.claude/agents/`) + - Built-in agents (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 + - Listed in AGENT_REGISTRY.md + +### Discovery Flow + +``` +User requests code review + ↓ +Use invoking-similar-agents skill + ↓ +Query AGENT_REGISTRY.md + ↓ +Search custom agents directory + ↓ +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: Check agent registry +cat ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md | grep -i "code.*review" + +# Test 3: 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 +- Cache agent registry +- Parallel synthesis +- Incremental reviews (only changed files) + +### 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..40cc3346 --- /dev/null +++ b/skills/invoking-similar-agents/SKILL.md @@ -0,0 +1,266 @@ +--- +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:** + +Query the agent registry for similar agents: +- **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 (`~/.claude/agents/`) + +**Agent Registry locations:** +- Built-in: Claude Code system prompt +- Superpowers: `~/.claude/plugins/cache/superpowers/agents/` +- Custom: `~/.claude/agents/` +- Registry index: `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` + +### 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** +``` +Input: "code-reviewer" +Variations to check: +- code-reviewer +- code_reviewer +- coderereviewer +- superpowers:code-reviewer +- *code*review* +``` + +**Step 2: Search agent locations** +```bash +# Check registry +grep -i "code.*review" ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md + +# Check custom agents +find ~/.claude/agents -name "*code*review*.md" + +# Check system prompt (built-in agents) +# These are listed in AGENT_REGISTRY.md +``` + +**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 + +``` +[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..59c41179 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,43 @@ 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 checks:** +- Custom: `~/.claude/agents/**/code*review*.md` +- Superpowers: Template at `requesting-code-review/code-reviewer.md` +- Built-in: Any code-review agents in system prompt +- Registry: `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` + +**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 +75,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 +93,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 +162,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 From 0fef11076ab9ec01a76c124ad3789f4bbee6fca1 Mon Sep 17 00:00:00 2001 From: Grant Callaghan Date: Sat, 25 Oct 2025 09:18:36 -0700 Subject: [PATCH 2/5] Clarify Agent Registry is optional for agent discovery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Agent Registry (AGENT_REGISTRY.md) is now clearly documented as: - Optional - not required for agent discovery - Serves as documentation and reference - Used as an optional cache for faster lookups Agent discovery primarily works via direct filesystem search of: - Custom agents in ~/.claude/agents/ - Superpowers templates in skills directories - Built-in agents from system prompt Changes: - Updated invoking-similar-agents/SKILL.md - Updated requesting-code-review/SKILL.md - Updated MULTI_AGENT_UPDATES.md - Clarified discovery algorithm and flow diagrams 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- MULTI_AGENT_UPDATES.md | 27 +++++++++++------ skills/invoking-similar-agents/SKILL.md | 40 +++++++++++++++++-------- skills/requesting-code-review/SKILL.md | 10 +++---- 3 files changed, 50 insertions(+), 27 deletions(-) diff --git a/MULTI_AGENT_UPDATES.md b/MULTI_AGENT_UPDATES.md index c6b755d6..abeb4bc6 100644 --- a/MULTI_AGENT_UPDATES.md +++ b/MULTI_AGENT_UPDATES.md @@ -26,13 +26,16 @@ Enhanced superpowers plugin with generic multi-agent invocation capability. When **Agent Discovery Algorithm:** 1. Normalize agent name (handle variations: dashes, underscores, prefixes) -2. Search all agent sources: - - Agent registry (`~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md`) - - Custom agents (`~/.claude/agents/`) - - Built-in agents (system prompt) +2. Search all agent sources (primary method: direct filesystem search): + - Custom agents: `~/.claude/agents/` (filesystem search) + - Superpowers templates: `~/.claude/plugins/cache/superpowers/skills/` + - Built-in agents: Known from system prompt + - Agent registry (optional): `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` 3. Filter by capability/role matching 4. Deduplicate results +**Note:** Agent Registry is optional - discovery works via direct filesystem search. The registry serves as documentation and an optional cache for faster lookups. + **When to Use:** - Security-critical code reviews - Major feature implementations @@ -135,7 +138,7 @@ You: Let me request code review using invoking-similar-agents. 3. **Built-in Agents** (Claude Code system prompt) - Core agents available by default - - Listed in AGENT_REGISTRY.md + - Known from system prompt ### Discovery Flow @@ -144,9 +147,13 @@ User requests code review ↓ Use invoking-similar-agents skill ↓ -Query AGENT_REGISTRY.md +Search custom agents directory (primary) + ↓ +Search superpowers templates + ↓ +Check built-in agents ↓ -Search custom agents directory +Optional: Query AGENT_REGISTRY.md (cache) ↓ Find matching agents ↓ @@ -225,8 +232,10 @@ specialization: web-security # Test 1: Verify skill file exists ls ~/.claude/plugins/cache/superpowers/skills/invoking-similar-agents/SKILL.md -# Test 2: Check agent registry -cat ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md | grep -i "code.*review" +# Test 2: Check agent registry (optional, for reference) +if [ -f ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md ]; then + cat ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md | grep -i "code.*review" +fi # Test 3: List custom agents find ~/.claude/agents -name "*code*review*.md" diff --git a/skills/invoking-similar-agents/SKILL.md b/skills/invoking-similar-agents/SKILL.md index 40cc3346..11f2b2a7 100644 --- a/skills/invoking-similar-agents/SKILL.md +++ b/skills/invoking-similar-agents/SKILL.md @@ -29,16 +29,25 @@ Discover and dispatch multiple agents with similar capabilities to get diverse p **Find all agents matching the role:** -Query the agent registry for similar agents: +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 (`~/.claude/agents/`) +- **Sources**: Check built-in agents, superpowers agents, and custom agents -**Agent Registry locations:** -- Built-in: Claude Code system prompt -- Superpowers: `~/.claude/plugins/cache/superpowers/agents/` -- Custom: `~/.claude/agents/` -- Registry index: `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` +**Discovery methods (in order):** + +1. **Direct filesystem search** (primary, always works): + - Custom agents: `~/.claude/agents/**/*.md` + - Superpowers templates: `~/.claude/plugins/cache/superpowers/skills/*/` + - Built-in agents: Known from Claude Code system prompt + +2. **Agent Registry** (optional, for faster lookup): + - Registry file: `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` + - Auto-generated by `~/.claude/scripts/sync_agent_docs.sh` + - Serves as documentation and reference + - **Not required** - discovery works without it + +**Note:** Agent discovery is resilient - it uses direct filesystem search as the primary method. The Agent Registry is an optional cache for faster lookups and documentation purposes. ### 2. Parallel Dispatch @@ -138,14 +147,19 @@ Variations to check: **Step 2: Search agent locations** ```bash -# Check registry -grep -i "code.*review" ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md - -# Check custom agents +# Primary: Direct filesystem search (always works) find ~/.claude/agents -name "*code*review*.md" -# Check system prompt (built-in agents) -# These are listed in AGENT_REGISTRY.md +# Check superpowers templates +find ~/.claude/plugins/cache/superpowers/skills -name "*code*review*" -type d + +# Optional: Check registry for faster lookup (if it exists) +if [ -f ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md ]; then + grep -i "code.*review" ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md +fi + +# 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** diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index 59c41179..22556f23 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/skills/requesting-code-review/SKILL.md @@ -36,11 +36,11 @@ This skill automatically: - Dispatches them in parallel with the same context - Synthesizes findings with consensus validation -**Agent discovery checks:** -- Custom: `~/.claude/agents/**/code*review*.md` -- Superpowers: Template at `requesting-code-review/code-reviewer.md` -- Built-in: Any code-review agents in system prompt -- Registry: `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` +**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 +- Optional: Agent Registry (if available) for faster lookup **3. Prepare context for agents:** From 56abd211f64ae5b60d5e56e50feae7388368d82b Mon Sep 17 00:00:00 2001 From: Grant Callaghan Date: Sat, 25 Oct 2025 09:21:44 -0700 Subject: [PATCH 3/5] Remove Agent Registry - use direct filesystem search only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Agent Registry (AGENT_REGISTRY.md) has been completely removed. Agent discovery now works entirely via direct filesystem search: Discovery sources: - Custom agents: ~/.claude/agents/**/*.md (filesystem search) - Superpowers templates: skills directories (filesystem search) - Built-in agents: Known from Claude Code system prompt Benefits: - Simpler - no registry to maintain - More reliable - direct search always works - No sync script needed - No stale registry data Changes: - Removed all Agent Registry references from invoking-similar-agents - Removed all Agent Registry references from requesting-code-review - Updated MULTI_AGENT_UPDATES.md discovery algorithm - Simplified discovery flow diagrams - Updated test scripts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- MULTI_AGENT_UPDATES.md | 18 ++++-------------- skills/invoking-similar-agents/SKILL.md | 17 +++-------------- skills/requesting-code-review/SKILL.md | 1 - 3 files changed, 7 insertions(+), 29 deletions(-) diff --git a/MULTI_AGENT_UPDATES.md b/MULTI_AGENT_UPDATES.md index abeb4bc6..57ce2bd6 100644 --- a/MULTI_AGENT_UPDATES.md +++ b/MULTI_AGENT_UPDATES.md @@ -26,16 +26,13 @@ Enhanced superpowers plugin with generic multi-agent invocation capability. When **Agent Discovery Algorithm:** 1. Normalize agent name (handle variations: dashes, underscores, prefixes) -2. Search all agent sources (primary method: direct filesystem search): +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 - - Agent registry (optional): `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` 3. Filter by capability/role matching 4. Deduplicate results -**Note:** Agent Registry is optional - discovery works via direct filesystem search. The registry serves as documentation and an optional cache for faster lookups. - **When to Use:** - Security-critical code reviews - Major feature implementations @@ -147,14 +144,12 @@ User requests code review ↓ Use invoking-similar-agents skill ↓ -Search custom agents directory (primary) +Search custom agents directory ↓ Search superpowers templates ↓ Check built-in agents ↓ -Optional: Query AGENT_REGISTRY.md (cache) - ↓ Find matching agents ↓ Dispatch all in parallel (Task tool) @@ -232,12 +227,7 @@ specialization: web-security # Test 1: Verify skill file exists ls ~/.claude/plugins/cache/superpowers/skills/invoking-similar-agents/SKILL.md -# Test 2: Check agent registry (optional, for reference) -if [ -f ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md ]; then - cat ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md | grep -i "code.*review" -fi - -# Test 3: List custom agents +# Test 2: List custom agents find ~/.claude/agents -name "*code*review*.md" # Test 4: In Claude Code session @@ -256,9 +246,9 @@ find ~/.claude/agents -name "*code*review*.md" - Priority/preference settings ### 3. Performance Optimization -- Cache agent registry - Parallel synthesis - Incremental reviews (only changed files) +- Cache discovery results per session ### 4. Result Caching - Cache agent reviews by git SHA diff --git a/skills/invoking-similar-agents/SKILL.md b/skills/invoking-similar-agents/SKILL.md index 11f2b2a7..0e67c767 100644 --- a/skills/invoking-similar-agents/SKILL.md +++ b/skills/invoking-similar-agents/SKILL.md @@ -34,20 +34,14 @@ Discover agents through multiple sources: - **Role matching**: Find agents with similar descriptions or capabilities - **Sources**: Check built-in agents, superpowers agents, and custom agents -**Discovery methods (in order):** +**Discovery methods:** -1. **Direct filesystem search** (primary, always works): +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 -2. **Agent Registry** (optional, for faster lookup): - - Registry file: `~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md` - - Auto-generated by `~/.claude/scripts/sync_agent_docs.sh` - - Serves as documentation and reference - - **Not required** - discovery works without it - -**Note:** Agent discovery is resilient - it uses direct filesystem search as the primary method. The Agent Registry is an optional cache for faster lookups and documentation purposes. +**Note:** Agent discovery uses direct filesystem search - no registry or configuration file needed. ### 2. Parallel Dispatch @@ -153,11 +147,6 @@ find ~/.claude/agents -name "*code*review*.md" # Check superpowers templates find ~/.claude/plugins/cache/superpowers/skills -name "*code*review*" -type d -# Optional: Check registry for faster lookup (if it exists) -if [ -f ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md ]; then - grep -i "code.*review" ~/.claude/plugins/cache/superpowers/agents/AGENT_REGISTRY.md -fi - # Built-in agents are known from Claude Code system prompt # No filesystem search needed - they're in the agent list ``` diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md index 22556f23..dc8c9e80 100644 --- a/skills/requesting-code-review/SKILL.md +++ b/skills/requesting-code-review/SKILL.md @@ -40,7 +40,6 @@ This skill automatically: - 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 -- Optional: Agent Registry (if available) for faster lookup **3. Prepare context for agents:** From c9fc55c7e532e97d98572d278c226b6fa3febdad Mon Sep 17 00:00:00 2001 From: Grant Callaghan Date: Sat, 25 Oct 2025 09:36:41 -0700 Subject: [PATCH 4/5] Fix markdown formatting in invoking-similar-agents skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert bolded step headings to proper markdown headings: - **Step 1:** → ### Step 1: - **Step 2:** → ### Step 2: - **Step 3:** → ### Step 3: - **Step 4:** → ### Step 4: This improves: - Document outline structure - Markdown rendering - Table of contents generation - Accessibility 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/invoking-similar-agents/SKILL.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/skills/invoking-similar-agents/SKILL.md b/skills/invoking-similar-agents/SKILL.md index 0e67c767..93d683dc 100644 --- a/skills/invoking-similar-agents/SKILL.md +++ b/skills/invoking-similar-agents/SKILL.md @@ -128,7 +128,8 @@ Task 3: security-focused-reviewer (if exists) ## Algorithm: Finding Similar Agents -**Step 1: Normalize agent name** +### Step 1: Normalize agent name + ``` Input: "code-reviewer" Variations to check: @@ -139,7 +140,8 @@ Variations to check: - *code*review* ``` -**Step 2: Search agent locations** +### Step 2: Search agent locations + ```bash # Primary: Direct filesystem search (always works) find ~/.claude/agents -name "*code*review*.md" @@ -151,12 +153,14 @@ find ~/.claude/plugins/cache/superpowers/skills -name "*code*review*" -type d # No filesystem search needed - they're in the agent list ``` -**Step 3: Filter by capability** +### Step 3: Filter by capability + - Read agent descriptions - Match against desired role/capability - Include agents with overlapping expertise -**Step 4: Deduplicate** +### Step 4: Deduplicate + - Remove duplicate references to same agent - Keep highest-specificity version From 3bafec02125c27612189ac389337fc5e4ea721ac Mon Sep 17 00:00:00 2001 From: Grant Callaghan Date: Sat, 25 Oct 2025 09:38:55 -0700 Subject: [PATCH 5/5] Add language identifiers to code blocks in invoking-similar-agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated all code blocks to include proper language specifiers: - ```bash for shell commands - ```text for plain text examples and non-executable content - ```markdown for markdown template examples Benefits: - Proper syntax highlighting - Better tooling support - Improved accessibility - Correct rendering in documentation viewers 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/invoking-similar-agents/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/invoking-similar-agents/SKILL.md b/skills/invoking-similar-agents/SKILL.md index 93d683dc..287c8d04 100644 --- a/skills/invoking-similar-agents/SKILL.md +++ b/skills/invoking-similar-agents/SKILL.md @@ -130,7 +130,7 @@ Task 3: security-focused-reviewer (if exists) ### Step 1: Normalize agent name -``` +```text Input: "code-reviewer" Variations to check: - code-reviewer @@ -166,7 +166,7 @@ find ~/.claude/plugins/cache/superpowers/skills -name "*code*review*" -type d ## Example: Code Review -``` +```text [Just completed authentication feature] You: Let me use invoking-similar-agents to get comprehensive code review.