Flatten agents/ to collapse the plugin-agent namespace

[azevedo]

Problem

Claude Code now namespaces plugin agents by their subdirectory under agents/. The invocable name is:

<plugin-name>:<subdirectory>:<agent-name>

Our agents live in three subdirs, so they're exposed as dev-workflow:research:*, dev-workflow:review:*, and dev-workflow:workflow:*. The subdirectory is now load-bearing — it's part of the agent ID, not just organization.

Our command files dispatch agents by bare name (e.g. Task spec-flow-analyzer(...)). There is no bare spec-flow-analyzer registered anymore, so the model must translate the bare name into a namespaced ID at dispatch time — and nothing tells it which subdirectory the agent lives in. It guesses, often wrong.

Observed failure

dev-workflow:research:spec-flow-analyzer(...)
  ⎿ Error: Agent type 'dev-workflow:research:spec-flow-analyzer' not found.
    Available agents: ... dev-workflow:workflow:spec-flow-analyzer ...

spec-flow-analyzer lives in agents/workflow/, but the model guessed research. It self-corrects after reading the error, but burns a round-trip on most runs and looks broken. This is new behavior — the folder layout didn't affect invocation before.

Chosen fix: flatten agents/

Move all 18 agents out of the research/, review/, and workflow/ subdirs into agents/ directly. The namespace collapses to dev-workflow:<name> — a single segment with no subdirectory to guess wrong.

Tradeoff: we lose the research/review/workflow directory grouping. Conceptual grouping can be preserved in docs (README/CLAUDE.md) without affecting invocation.

Scope / tasks

• Move files: agents/{research,review,workflow}/*.md → agents/*.md (18 files; git mv to preserve history)
• Update command dispatches to dev-workflow:<name> (subdir segment removed):
  • commands/ba/plan.md — repo-researcher (L73), learnings-researcher (L74), spec-flow-analyzer (L169), convention-checker (L434)
  • commands/ba/brainstorm.md — repo-researcher (L71, L124), learnings-researcher (L125), interface-design-generator (L185–187), convention-checker (L314)
  • commands/ba/review-plan.md — plan-iteration-gate (L224)
• commands/ba/review.md — the reviewer table (L222–228) and the dynamic name-resolution steps (L394–399, "check if the bare name is a registered agent type") must account for the namespaced IDs; the resolver should match dev-workflow:<name> rather than bare names
• CLAUDE.md — agent-naming convention (L72) references agents/review/ and agents/workflow/; update to the flat layout
• README.md — update any agent listing / paths that imply subdirs
• Bump version in .claude-plugin/plugin.json (auto-update cache key)
• Verify each command's agents dispatch cleanly end-to-end after the rename

Notes

• Built-in agents (general-purpose, Explore, Plan, etc.) are not namespaced and need no changes.
• Alternative approaches considered: (A) fully-qualify names while keeping subdirs — keeps grouping but couples command text to agents/ layout and still requires the subdir segment; (C) add a bare-name→ID mapping table per command — least invasive but another thing to keep in sync. Flattening was chosen for determinism.