|
1 | 1 | # Agent Naming Guide |
2 | 2 |
|
3 | | -This guide clarifies naming conflicts and helps you choose the right agent for your task. |
| 3 | +This guide helps you choose the right agent when more than one agent shares the same name. Name collisions happen when an installed Claude Code plugin ships an agent whose name matches another plugin's agent — or a local agent in `.claude/agents/`. |
4 | 4 |
|
5 | | -## Code Reviewer Variants |
| 5 | +> **The `plugin/agent` references below are illustrative, not a claim about what is installed.** This template's own agents live in `.claude/agents/`; any additional agents come from whatever plugins you have installed (see `.claude/PLUGINS-REFERENCE.md` for the plugins this project documents). There is **no** local `code-reviewer` agent in this template. Verify what is actually available with `/plugin list` before assuming a specific `plugin/agent` exists. |
6 | 6 |
|
7 | | -There are **three agents** named "code-reviewer" with different purposes. Use this guide to select the correct one: |
| 7 | +## Resolving "code-reviewer" (and similar) collisions |
8 | 8 |
|
9 | | -### 1. feature-dev/code-reviewer |
10 | | -**When to use:** General code quality review during active development |
| 9 | +If you have multiple plugins installed that each provide a similarly-named agent (for example, a `code-reviewer`), prefer the one most specific to your task. The common review situations are: |
11 | 10 |
|
12 | | -**Focus:** |
13 | | -- Bug detection |
14 | | -- Security vulnerabilities |
15 | | -- Code smells and anti-patterns |
16 | | -- Best practices compliance |
| 11 | +### General development review |
| 12 | +For bug detection, security smells, code smells, and best-practice checks during active development. Favor a fast, read-only reviewer. |
17 | 13 |
|
18 | | -**Model:** Sonnet (faster reviews) |
| 14 | +### Pull-request / merge review |
| 15 | +For PR-specific analysis: cross-file impact, integration concerns, and merge readiness before shipping. Favor a comprehensive reviewer that can run tests and check dependencies. |
19 | 16 |
|
20 | | -**Tools:** Read-only (Glob, Grep, Read) |
| 17 | +### Plan-alignment review |
| 18 | +For verifying that an implementation matches an agreed plan or architecture: requirement traceability and completeness. Favor a reviewer that can read both the plan and the diff. |
21 | 19 |
|
22 | | -**Confidence:** Reports issues ≥80% confidence |
23 | | - |
24 | | -**Example scenarios:** |
25 | | -- "Review this function for bugs" |
26 | | -- "Check if this code is secure" |
27 | | -- "Is this following best practices?" |
28 | | - |
29 | | ---- |
30 | | - |
31 | | -### 2. pr-review-toolkit/code-reviewer |
32 | | -**When to use:** Pull request reviews before merging |
33 | | - |
34 | | -**Focus:** |
35 | | -- PR-specific analysis |
36 | | -- Cross-file impact assessment |
37 | | -- Merge readiness |
38 | | -- Integration concerns |
39 | | - |
40 | | -**Model:** Opus (comprehensive reviews) |
41 | | - |
42 | | -**Tools:** Full access (can run tests, check dependencies) |
43 | | - |
44 | | -**Confidence:** Reports issues ≥80% confidence |
45 | | - |
46 | | -**Example scenarios:** |
47 | | -- "Review this PR for merge" |
48 | | -- "What's the impact of these changes?" |
49 | | -- "Is this PR ready to ship?" |
50 | | - |
51 | | ---- |
52 | | - |
53 | | -### 3. superpowers/code-reviewer |
54 | | -**When to use:** Verifying implementation matches the plan |
55 | | - |
56 | | -**Focus:** |
57 | | -- Plan alignment verification |
58 | | -- Architectural decision validation |
59 | | -- Implementation completeness |
60 | | -- Requirement traceability |
61 | | - |
62 | | -**Model:** Inherits from parent (flexible) |
63 | | - |
64 | | -**Tools:** Full access |
65 | | - |
66 | | -**Example scenarios:** |
67 | | -- "Does this implementation match our plan?" |
68 | | -- "Did we follow the architecture we agreed on?" |
69 | | -- "Are all planned features implemented?" |
70 | | - |
71 | | ---- |
| 20 | +**Quick rule:** match the agent to the moment — general coding vs. PR/merge vs. plan verification — and pick the most specific reviewer your installed plugins provide. |
72 | 21 |
|
73 | 22 | ## Quick Decision Tree |
74 | 23 |
|
75 | 24 | ``` |
76 | 25 | Need to review code? |
77 | 26 | │ |
78 | | -├─ Is there an implementation plan? ────> superpowers/code-reviewer |
| 27 | +├─ Is there an implementation plan? ────> plan-alignment reviewer |
79 | 28 | │ |
80 | | -├─ Is this for a PR/merge? ────────────> pr-review-toolkit/code-reviewer |
| 29 | +├─ Is this for a PR/merge? ────────────> PR / merge reviewer |
81 | 30 | │ |
82 | | -└─ General development review ─────────> feature-dev/code-reviewer |
| 31 | +└─ General development review ─────────> general-purpose reviewer |
83 | 32 | ``` |
84 | 33 |
|
85 | | ---- |
86 | | - |
87 | | -## Code Simplifier Location |
88 | | - |
89 | | -**Previously:** Had both standalone `code-simplifier` plugin AND `pr-review-toolkit/code-simplifier` agent (duplicate) |
| 34 | +## Other Name Collisions |
90 | 35 |
|
91 | | -**Now:** Only `pr-review-toolkit/code-simplifier` remains (standalone plugin removed) |
| 36 | +The same "prefer the most specific" principle applies whenever agents overlap: |
92 | 37 |
|
93 | | -**When to use:** After code review suggests simplification, invoke this agent to refactor complex code while preserving functionality. |
94 | | - |
95 | | ---- |
| 38 | +### Code simplifiers / refactorers |
| 39 | +If more than one refactoring agent is available, use the one intended to run **after** a review — it refactors the flagged code while preserving behavior. |
96 | 40 |
|
97 | | -## Other Naming Clarifications |
98 | | - |
99 | | -### Test Agents |
100 | | -- **test-writer-fixer** (custom): Writes tests, runs them, fixes failures |
101 | | -- **pr-test-analyzer** (pr-review-toolkit): Analyzes test coverage in PRs |
102 | | -- **Use both:** They're complementary (active vs. passive testing) |
103 | | - |
104 | | -### Frontend Agents |
105 | | -- **frontend-developer** (custom): Full-stack frontend implementation |
106 | | -- **frontend-design** (plugin): UI/UX design and prototyping |
107 | | -- **Use both:** Design first, then implement |
108 | | - |
109 | | ---- |
| 41 | +### Test agents |
| 42 | +This template ships a local **test-writer-fixer** (writes tests, runs them, fixes failures). If a plugin also provides a test-coverage analyzer, treat them as complementary: active fixing vs. passive analysis. |
110 | 43 |
|
111 | | -## WordPress FSE Development Stack |
112 | | - |
113 | | -For WordPress block theme development, your core agents are: |
114 | | - |
115 | | -**Code Quality:** |
116 | | -- feature-dev/code-reviewer (development reviews) |
117 | | -- pr-review-toolkit/code-reviewer (PR reviews) |
118 | | - |
119 | | -**Development:** |
120 | | -- frontend-developer (JS/CSS implementation) |
121 | | -- test-writer-fixer (PHP unit tests) |
122 | | - |
123 | | -**Performance:** |
124 | | -- performance-benchmarker (optimization) |
125 | | - |
126 | | -**Design:** |
127 | | -- ui-designer (block patterns, theme design) |
128 | | -- ux-researcher (usability testing) |
129 | | - |
130 | | -**Infrastructure:** |
131 | | -- php-lsp (code intelligence) |
132 | | -- security-guidance (WordPress security) |
133 | | - |
134 | | ---- |
| 44 | +### Frontend agents |
| 45 | +This template ships a local **frontend-developer** (full-stack FSE implementation). If a plugin also provides a UI/UX design agent, design first, then implement. |
135 | 46 |
|
136 | 47 | ## When in Doubt |
137 | 48 |
|
138 | | -If you're unsure which agent to use: |
139 | | -1. Check this guide's decision tree |
140 | | -2. Use the more specific agent (e.g., pr-review-toolkit for PRs) |
141 | | -3. Ask Claude Code: "Which code-reviewer should I use for [task]?" |
| 49 | +1. Run `/plugin list` to see which plugins — and therefore which plugin agents — are actually installed. |
| 50 | +2. Check the decision tree above. |
| 51 | +3. Prefer the more specific agent for your task (e.g., a PR reviewer for PRs). |
| 52 | +4. Ask Claude Code: "Which agent should I use for [task]?" |
142 | 53 |
|
143 | 54 | --- |
144 | 55 |
|
145 | | -**Last Updated:** 2026-01-18 |
| 56 | +**Last Updated:** 2026-06-28 |
0 commit comments