refactor: rename agents from noun-persons to verb-actions

[dean0x]

Summary

Rename all agents from noun-person names (Coder, Reviewer, Scrutinizer) to verb-action names (code, review, scrutinize). The principle: agents should be named as the action itself, not the person performing it.

This aligns with the existing convention for ad-hoc agents (Explore, Plan) which are already verb-based.

Proposed Rename Mapping

Current (noun)	Proposed (verb)	File Rename	Notes
Coder	code	coder.md → code.md
Scrutinizer	scrutinize	scrutinizer.md → scrutinize.md
Simplifier	simplify	simplifier.md → simplify.md
Evaluator	evaluate	evaluator.md → evaluate.md
Skimmer	skim	skimmer.md → skim.md
Reviewer	review	reviewer.md → review.md
Resolver	resolve	resolver.md → resolve.md
Tester	test	tester.md → test.md	Decision needed: test vs qa — "test" is heavily overloaded
Validator	validate	validator.md → validate.md
Designer	design	designer.md → design.md
Synthesizer	synthesize	synthesizer.md → synthesize.md
Git	git	no rename needed	Already an action/tool name — just lowercase frontmatter name:
Knowledge	TBD	depends	Decision needed: not a person-noun; options: keep knowledge, or rename to catalog/codify/learn
claude-md-auditor	audit-claude	claude-md-auditor.md → audit-claude.md	Verb-first pattern

Open Design Decisions

1. Knowledge agent — Not an "-er"/"-or" noun. Options: keep knowledge, rename to catalog, codify, or learn
2. Tester → test vs qa — "test" is extremely overloaded in code contexts. qa matches its primary skill name and is unambiguous
3. Casing convention — Current: Title Case frontmatter/subagent_type (name: Coder, subagent_type="Coder"). Proposed: lowercase (name: code, subagent_type="code"). This changes the convention for ALL spawn calls

Complete Reference Inventory

All references found through exhaustive codebase search. Every location listed below must be updated.

Category 1: Agent Definition Files (14 files)

Source of truth: shared/agents/

Each file needs:

• File rename (git mv)
• Frontmatter name: update
• Self-references in prose (e.g., "the Coder agent")
• Cross-references to other agents (e.g., evaluator.md references "Coder", scrutinizer.md references "Coder")

File	Self-refs	Cross-refs to other agents
shared/agents/coder.md	Lines 2, 17, 37, 38, 40, 79, 96, 118	—
shared/agents/designer.md	Lines 2, 13	—
shared/agents/evaluator.md	Lines 2, 10, 12, 19, 40, 45	Coder (lines 12, 19, 40, 45)
shared/agents/git.md	Line 2	—
shared/agents/knowledge.md	Line 2	—
shared/agents/resolver.md	Lines 2, 15, 34, 39, 97, 126	—
shared/agents/reviewer.md	Lines 2, 12, 85	—
shared/agents/scrutinizer.md	Lines 2, 13	Coder (lines 15, 21)
shared/agents/simplifier.md	Lines 2, 10	—
shared/agents/skimmer.md	Lines 2, 10, 144	—
shared/agents/synthesizer.md	Lines 2, 11, 73	Designer (lines 133, 136), Reviewer (lines 172, 177)
shared/agents/tester.md	Lines 2, 12, 23, 115, 124	Coder (line 21)
shared/agents/validator.md	Lines 2, 10	—
plugins/devflow-audit-claude/agents/claude-md-auditor.md	Line 2	—

Category 2: Plugin Configuration (7 plugin.json + 1 TypeScript registry)

plugin.json files — update "agents" arrays (lowercase strings):

Plugin	File	Agents Listed
devflow-ambient	plugins/devflow-ambient/.claude-plugin/plugin.json	coder, validator, simplifier, scrutinizer, evaluator, tester, skimmer, reviewer, git, synthesizer, resolver, designer, knowledge
devflow-implement	plugins/devflow-implement/.claude-plugin/plugin.json	git, coder, simplifier, scrutinizer, evaluator, tester, validator
devflow-code-review	plugins/devflow-code-review/.claude-plugin/plugin.json	git, reviewer, synthesizer
devflow-resolve	plugins/devflow-resolve/.claude-plugin/plugin.json	git, resolver, simplifier
devflow-debug	plugins/devflow-debug/.claude-plugin/plugin.json	git, synthesizer
devflow-plan	plugins/devflow-plan/.claude-plugin/plugin.json	git, skimmer, synthesizer, designer, knowledge
devflow-self-review	plugins/devflow-self-review/.claude-plugin/plugin.json	simplifier, scrutinizer, validator
devflow-explore	plugins/devflow-explore/.claude-plugin/plugin.json	skimmer, synthesizer, knowledge
devflow-audit-claude	plugins/devflow-audit-claude/.claude-plugin/plugin.json	claude-md-auditor

TypeScript plugin registry — src/cli/plugins.ts (lines 44-135):

• Every plugin's agents array is duplicated here. All entries are lowercase strings matching file names.

Category 3: Command Files (~14 files)

Every Agent(subagent_type="AgentName") call must be updated, plus prose references.

Command File	Agents Referenced (subagent_type values)
plugins/devflow-implement/commands/implement.md	Git, Coder, Validator, Simplifier, Scrutinizer, Evaluator, Tester
plugins/devflow-implement/commands/implement-teams.md	Git, Coder, Validator, Simplifier, Scrutinizer, Evaluator, Tester
plugins/devflow-code-review/commands/code-review.md	Git, Reviewer, Synthesizer
plugins/devflow-code-review/commands/code-review-teams.md	Git, Reviewer, Synthesizer
plugins/devflow-plan/commands/plan.md	Skimmer, Synthesizer, Designer, Knowledge
plugins/devflow-plan/commands/plan-teams.md	Skimmer, Synthesizer, Designer, Knowledge
plugins/devflow-resolve/commands/resolve.md	Git, Resolver, Simplifier
plugins/devflow-resolve/commands/resolve-teams.md	Git, Simplifier
plugins/devflow-debug/commands/debug.md	Git, Explore, Synthesizer
plugins/devflow-debug/commands/debug-teams.md	Git
plugins/devflow-explore/commands/explore.md	Skimmer, Explore, Synthesizer, Knowledge
plugins/devflow-explore/commands/explore-teams.md	Skimmer, Explore, Synthesizer, Knowledge
plugins/devflow-self-review/commands/self-review.md	Simplifier, Scrutinizer, Validator
plugins/devflow-audit-claude/commands/audit-claude.md	claude-md-auditor

Category 4: Orchestration Skills (7 files)

Skill File	Agents Referenced
shared/skills/implement:orch/SKILL.md	Git, Coder, Validator, Simplifier, Scrutinizer, Evaluator, Tester, Knowledge
shared/skills/plan:orch/SKILL.md	Skimmer, Explore, Designer, Synthesizer, Plan, Knowledge
shared/skills/review:orch/SKILL.md	Git, Reviewer, Synthesizer
shared/skills/resolve:orch/SKILL.md	Resolver, Simplifier
shared/skills/debug:orch/SKILL.md	Explore, Simplifier
shared/skills/explore:orch/SKILL.md	Skimmer, Explore, Synthesizer, Knowledge
shared/skills/pipeline:orch/SKILL.md	Coder, Validator, Simplifier, Scrutinizer, Evaluator, Tester

Category 5: Other Skills (~10 files)

Skill File	Agents Referenced
shared/skills/router/SKILL.md	Simplifier, Skimmer
shared/skills/git/SKILL.md	Coder, Git, Resolver
shared/skills/quality-gates/SKILL.md	Scrutinizer, Coder
shared/skills/docs-framework/SKILL.md	Reviewer, Synthesizer, Resolver, Knowledge, Designer, Coder, Git
shared/skills/test-driven-development/SKILL.md	Coder, Resolver
shared/skills/review-methodology/SKILL.md	Reviewer
shared/skills/qa/SKILL.md	Tester
shared/skills/agent-teams/SKILL.md	Generic references (Explorers, Reviewers, Validators)

Category 6: TypeScript CLI Code (~5 files)

File	References	Context
src/cli/plugins.ts	All 14 agent names	Central plugin registry, agents arrays (lines 44-135)
src/cli/commands/init.ts	Simplifier, Scrutinizer	Plugin descriptions (line 292)
src/cli/commands/kb.ts	Knowledge	Agent prompt strings (lines 32, 190, 284)
src/cli/commands/skills.ts	Simplifier, Scrutinizer	Plugin descriptions (line 89)
src/cli/hud/transcript.ts	subagent_type	Generic extraction, no hardcoded names (line 103) — no change needed

Category 7: Tests (~5 files)

Test File	Agents Referenced	Context
tests/integration/subagent-skill-preload.test.ts	Simplifier, Scrutinizer, Reviewer, Coder, Designer, Git	Agent type strings in test cases (lines 45-96)
tests/integration/ambient-activation.test.ts	Skimmer	Comment text (line 68)
tests/uninstall-logic.test.ts	claude-md-auditor, coder	Test assertions (lines 18-81)
tests/knowledge/command-adoption.test.ts	resolver, designer, scrutinizer, reviewer, simplifier, Reviewer	Agent file references and descriptions (lines 132-215)
tests/memory.test.ts	Synthesizer	Test data string (lines 739, 748)

Category 8: Documentation (~15 files)

File	Scope of Changes
CLAUDE.md	Agent roster table, model strategy, pipeline descriptions
README.md	Feature descriptions, agent mentions
docs/reference/agent-design.md	Agent templates, examples
docs/reference/file-organization.md	File structure, install paths
docs/reference/skills-architecture.md	Skill-agent mapping, activation patterns
docs/commands.md	Command descriptions
docs/cli-reference.md	CLI usage examples
docs/self-learning.md	Agent references in learning context
docs/working-memory.md	Knowledge agent references
plugins/devflow-ambient/README.md	Agent list, routing descriptions
plugins/devflow-implement/README.md	Pipeline agent descriptions
plugins/devflow-plan/README.md	Planning agent descriptions
CHANGELOG.md	DO NOT UPDATE — historical record. Add a new entry for the rename instead

Category 9: Build System

File	Impact
scripts/build-plugins.ts	Reads agent names from plugin.json, copies files by name — automatic if files are renamed and plugin.json updated
.gitignore	Agent copies in plugins/*/agents/ are gitignored — no change needed (pattern-based, not name-based)

Implementation Plan

Phase 1: File Renames + Frontmatter (13 git mv operations)

# In shared/agents/
git mv shared/agents/coder.md shared/agents/code.md
git mv shared/agents/scrutinizer.md shared/agents/scrutinize.md
git mv shared/agents/simplifier.md shared/agents/simplify.md
git mv shared/agents/evaluator.md shared/agents/evaluate.md
git mv shared/agents/skimmer.md shared/agents/skim.md
git mv shared/agents/reviewer.md shared/agents/review.md
git mv shared/agents/resolver.md shared/agents/resolve.md
git mv shared/agents/tester.md shared/agents/test.md       # or qa.md
git mv shared/agents/validator.md shared/agents/validate.md
git mv shared/agents/designer.md shared/agents/design.md
git mv shared/agents/synthesizer.md shared/agents/synthesize.md
# git.md — no rename, just lowercase frontmatter name
# knowledge.md — TBD based on decision

# Plugin-specific:
git mv plugins/devflow-audit-claude/agents/claude-md-auditor.md plugins/devflow-audit-claude/agents/audit-claude.md

Then update name: frontmatter in each file.

Phase 2: Configuration Updates

1. Update all 9 plugin.json files — "agents" arrays
2. Update src/cli/plugins.ts — agents arrays in plugin registry
3. Update src/cli/commands/init.ts, kb.ts, skills.ts — prose references

Phase 3: Command + Skill Updates

1. Find-replace subagent_type="OldName" → subagent_type="newname" across all 14 command files
2. Find-replace in all 7 orchestration skill files
3. Find-replace in ~10 supporting skill files
4. Update prose references ("the Coder agent" → "the code agent", etc.)

Phase 4: Tests

1. Update agent type strings in test assertions
2. Update test descriptions and comments
3. Run full test suite: npm test

Phase 5: Documentation

1. Update CLAUDE.md agent roster and all references
2. Update README.md
3. Update docs/reference/*.md
4. Update plugin-level READMEs
5. Add CHANGELOG.md entry for the rename

Phase 6: Migration

Add a migration to src/cli/utils/migrations.ts that:

• Removes old agent files from ~/.claude/agents/devflow/ (the 13 old names)
• This ensures users who devflow init after upgrading get clean installs

Phase 7: Build + Verify

1. npm run build (recompiles CLI + distributes new agent files)
2. npm test (verify all tests pass)
3. node dist/cli.js init (verify clean install)
4. Spot-check that ~/.claude/agents/devflow/ has new names, not old ones

Key Safety Notes

• All references are literal strings — no dynamic name construction, no string interpolation, no partial matching. A systematic find-and-replace is safe.
• Build system is name-agnostic — build-plugins.ts reads names from plugin.json and copies files by name. Renaming files + updating plugin.json is sufficient.
• HUD/transcript code is generic — extracts subagent_type from any agent spawn, doesn't hardcode names.
• CHANGELOG.md should NOT be updated — it's a historical record. Add a new entry instead.
• .memory/ files are auto-regenerated — no manual update needed.

Estimated Scope

• ~60+ files modified
• ~400-600 individual text replacements
• 13 file renames (git mv)
• 1 new migration entry
• 1 new CHANGELOG entry