Problem
Currently docs/AGENTS.md is a static plugin doc describing the shipped agent set (swe, pr-reviewer, consultant templates). When a user creates a local agent via tmb_agent-creator, it lands in <project>/.claude/agents/ but no registry is updated.
User's concern (verbatim)
I have a question since user may have local agents we must avoid conflicts.
Specific scenarios
-
User-first naming: user creates .claude/agents/architect.md (custom domain expert). Plugin later adds a generic templates/agents/architect.md. Resolution rule says local wins, so user's file serves — good. But if user runs tmb_agent-creator to copy the new template, it overwrites their custom file. Bad.
-
Plugin-first naming: plugin ships pr-reviewer globally. User creates their own pr-reviewer.md to override (intended). Works correctly per current rules.
-
Concurrent creation: bro proposes a new legal-reviewer agent. Project already has user-created legal-reviewer.md. tmb_agent-creator should detect + ask before overwriting, not silently replace.
Proposed strategy options
A. Naming convention: project-local agents created by tmb_agent-creator use a local_ prefix (or similar). User-created agents use any name. Plugin-shipped never collide. Predictable, but verbose for users.
B. Detection-and-confirm: tmb_agent-creator always checks .claude/agents/<name>.md first; if present, AskUserQuestion before overwriting. Works for interactive sessions; the tmb_headless-fallback doctrine says HALT for file-writing skills in headless mode, so safe by default.
C. Per-project AGENTS.md: separate from plugin's docs/AGENTS.md. Lives at project root or <project>/.claude/AGENTS.md. tmb_agent-creator appends to it. Bro reads it on demand to know what local agents exist. Also requires a name-collision check when creating.
Acceptance
Came up where
User audit on PR #129 (CLAUDE.md slim-down). Filed during PR #130.
Problem
Currently
docs/AGENTS.mdis a static plugin doc describing the shipped agent set (swe,pr-reviewer, consultant templates). When a user creates a local agent viatmb_agent-creator, it lands in<project>/.claude/agents/but no registry is updated.User's concern (verbatim)
Specific scenarios
User-first naming: user creates
.claude/agents/architect.md(custom domain expert). Plugin later adds a generictemplates/agents/architect.md. Resolution rule says local wins, so user's file serves — good. But if user runstmb_agent-creatorto copy the new template, it overwrites their custom file. Bad.Plugin-first naming: plugin ships
pr-reviewerglobally. User creates their ownpr-reviewer.mdto override (intended). Works correctly per current rules.Concurrent creation: bro proposes a new
legal-revieweragent. Project already has user-createdlegal-reviewer.md.tmb_agent-creatorshould detect + ask before overwriting, not silently replace.Proposed strategy options
A. Naming convention: project-local agents created by tmb_agent-creator use a
local_prefix (or similar). User-created agents use any name. Plugin-shipped never collide. Predictable, but verbose for users.B. Detection-and-confirm:
tmb_agent-creatoralways checks.claude/agents/<name>.mdfirst; if present, AskUserQuestion before overwriting. Works for interactive sessions; thetmb_headless-fallbackdoctrine says HALT for file-writing skills in headless mode, so safe by default.C. Per-project AGENTS.md: separate from plugin's
docs/AGENTS.md. Lives at project root or<project>/.claude/AGENTS.md.tmb_agent-creatorappends to it. Bro reads it on demand to know what local agents exist. Also requires a name-collision check when creating.Acceptance
tmb_agent-creatorskill specdocs/AGENTS.mdto document the resolution rule clearlyCame up where
User audit on PR #129 (CLAUDE.md slim-down). Filed during PR #130.