Skip to content

[Refactor] Role/agent naming consistency — only Rex + Shield have names; 5 roles + 3 agents don't #204

Description

@atlas-apex

Driver

The marketing slide "Treat Claude Code Like A Team" presents 7 personas as equal team members. Framework reality:

  • 2 have proper names: code-reviewer is "Rex", security-reviewer is "Shield"
  • 5 roles have only titles: Product Manager, Tech Lead, Backend Engineer, Frontend Engineer, QA Engineer
  • 3 other agents have NO names either: dependency-auditor, pr-manager, ticket-manager

The naming is inconsistent: not all agents have names (3 don't), and no roles have names. The marketing implies all 7 are equivalent named personas; the code says only 2 are.

This creates two problems:

  1. Adopter confusion — adopters reading the marketing slide expect to invoke "Pat the QA Engineer" or "Maya the PM" and find no such handle anywhere in the framework.
  2. Inconsistent agent UX — when running /audit-deps, the dependency auditor's output is unsigned; when running /code-review, Rex's output is signed. Same shape of tool, different visibility.

Scope

Pick one approach and apply it consistently.

Option A — Give every role + agent a proper name

Add a persona_name field (or similar) to every role file in roles/{dept}/{role}.md and every agent file in .claude/agents/*.md. Examples:

Role / Agent Proposed name
Product Manager Maya
Tech Lead Luca
Backend Engineer Alex
Frontend Engineer Jamie
QA Engineer Pat
Code Reviewer (Rex) unchanged
Security Reviewer (Shield) unchanged
Dependency Auditor ??? (TBD)
PR Manager ??? (TBD)
Ticket Manager ??? (TBD)

The marketing slide updates to show all names. When a role activates, the main agent introduces itself with the persona name.

Option B — Drop names from Rex and Shield, use titles uniformly

Rename code-reviewer agent's introduction from "I'm Rex" to "I'm the Code Reviewer". Same for Shield → "Security Reviewer". Marketing slide updates to remove the "(REX)" / "(SHIELD)" labels.

Recommendation

Option A. Names create memorable identity, ease team-feel framing the marketing already invested in, and adopters can refer to them as "Pat said the AC isn't met yet" — natural team-language. Drop-the-names is technically simpler but loses the brand equity already built around Rex/Shield.

Acceptance Criteria

  • Every role file declares a persona name in frontmatter (or designated field), OR every persona is referenced by title only — pick one
  • Marketing slide 5 ("Treat Claude Code Like A Team") matches the implementation 1:1
  • Sibling tickets ([Feature] Spike: Claude Opus/Sonnet/Haiku model-tier routing for bounded sub-tasks (sibling to #195) #197 role-activation visibility) reference names consistently
  • CLAUDE.md role table either shows all names or no names
  • AgDR captures the naming convention as a framework-level decision (so future agents/roles follow it)

Risks / Dependencies

  • Naming bikeshed — picking specific names is opinion-territory. Recommendation: file one AgDR with the names + reasoning, ship it, move on. Adopters can override per-fork via roles/*/ edits if they want their own names.
  • Marketing slide drift — the slide is a separate artifact; when this lands, slide 5 needs an update PR. Track as a linked task in this ticket.

Refs

  • Surfaced during marketing-vs-reality audit (mid-session in atlas-apex's adoption test).
  • Related: role-activation visibility ticket (sibling — being filed alongside this).

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium — plan-worthy, not urgent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions