Sub-agent conventions: codify from latest official docs, then audit all plugins

[kyle-sexton]

Intent

We suspect custom sub-agent features are going unleveraged because we do not have a complete picture of what the platform offers — preloaded/auto-loaded skills, conversation forking, per-agent status line (semantics currently unclear to us), and likely unknown unknowns beyond those. This issue closes that gap in two sequenced parts: first research and codify sub-agent conventions from the latest official documentation, then audit every plugin in this repo against them.

HARD RULE — pointer, not copy. The conventions doc (and this issue) must LINK to the upstream official documentation pages, never restate schema, field lists, or feature content inline. Restating creates maintenance burden and drifts as upstream evolves. Codify our decisions and conventions; point at upstream for the facts.

Part 1 — Research and codify sub-agent conventions

Exhaustive pass over the latest official Claude Code sub-agent documentation, plus every configuration page that ties into sub-agents (settings, plugin/skill surfaces, frontmatter references, etc.). Assume our current knowledge is stale; enumerate the full current feature surface, including capabilities we have never used.

Deliverable: codified conventions covering at minimum —

1. Existence qualifier — a categorization for when a custom sub-agent earns its existence versus delegating to general-purpose/built-in agents.
2. Frontmatter surface — the full YAML frontmatter surface for sub-agents and its usage patterns (as pointers to the upstream reference, with our conventions layered on top).
3. Rationale and best practices — why/when guidance and a catalog of available features (again by pointer), including the ones prompting this issue: preloaded/auto-load skills, conversation forking, per-agent status line, and anything else discovered.

Part 2 — Audit all plugins (gated on Part 1)

Do not start until Part 1's conventions are codified. Then audit the full plugin inventory in this repo against them: every existing custom sub-agent (does it pass the existence qualifier? does it use the frontmatter surface correctly?) and every plugin that lacks sub-agents but would benefit under the new conventions. Output: a findings list with per-plugin dispositions; remediation can be follow-up issues.

Locked decisions (do not re-litigate)

• One issue, two parts; Part 2 is gated on Part 1.
• Conventions home: the existing plugin-authoring conventions surface in this repo — extend it, do not stand up a parallel surface (reuse-or-replace). Verify the actual current location at execution time.
• Escalation (USER-RESERVED): if research shows the content is a cross-cutting org-wide standard rather than Claude-Code-specific, it routes to melodic-software/standards instead — but that call is reserved for the user; surface it before placing content there.
• Pointer-not-copy (hard rule above) applies to all deliverables.

Cross-link

#1226 (git-history archaeology skill) consumes Part 1's existence qualifier for its sub-agent evaluation, so Part 1 should land before that issue finishes design.

Priority

MEDIUM-LOW (no exact label tier exists; priority: medium applied as nearest). Elevated only by the sequencing note above: Part 1 feeds the git-history archaeology skill issue's design.

[kyle-sexton]

This was generated by AI during the /work-items:work-loop autonomous drain cycle.

Surfaced in the --autonomous frontier (unassigned, unblocked, not human-gated) but carries no role label — already triaged (priority set) yet never routed to agent-ready or needs-human. Content reads as structural/cross-cutting (convention, contract, or design-space work) rather than a scoped bug fix, so this cycle's admission gate classifies it C4-shaped or unclassified and routes it human-gated per the fail-closed default rather than admitting it to autonomous dispatch.

Routing: added needs-human. No other state changed — priority and existing labels are left as-is. If this is actually scoped/delegable, re-label to agent-ready (+ status: ready) and it will be picked up by a later drain cycle.

[kyle-sexton]

Proposed boundary, not a ruling — surfacing this so you can push back before anything is built against it.

A parallel effort (context-engineering rightsizing) has two deliverables that looked, from a distance, like they might collide with this issue's Part 2 all-plugin audit. Its own decision record required reconciling with #1225 before building anything sweep-shaped, so I read this issue first-hand rather than working from a summary. The boundary doc is in #1280.

Finding: no collision. The populations and the questions are different.

• Part 2 here audits sub-agent definitions. Enumerated in the checkout: 7 agent .md files across 2 of 60 plugins (plugins/plugin-quality/agents/auditor.md and plugins/review/agents/ ×6), widening only to the "would this plugin benefit from one" question over the other 58.
• The other effort operates on instruction surfaces — 188 SKILL.md files plus CLAUDE.md, .claude/rules/, prompt-type hook text, and output styles.

The one place they touch the same files is claude-config:audit-instructions, which inventories agent definition markdown as one of its surfaces (plugins/claude-config/skills/audit-instructions/SKILL.md:78, :82, scope arg at :67). It reads those files for instruction content vs current model capability; this issue reads them for existence qualification and frontmatter conformance. Same files, orthogonal questions — neither effort blocks the other, and neither needs a new router to reach those 7 files.

One thing worth your attention before Part 1 is written. The existence qualifier may have a partial incumbent. claude-config:audit-automation-gaps already treats subagents as an audited automation category (SKILL.md:3, :43) and already asks the existence question:

Subagents — for each quality concern:

• Would a subagent provide value over a hook or skill?
• Does context isolation actually help?
• Is there a plugin that already provides this?

(plugins/claude-config/skills/audit-automation-gaps/context/gap-analysis.md:21-25)

That is narrower than what deliverable 1 describes, and it is a gap-analysis lens rather than a codified qualifier — so this is not "already done." But it is prior art on the same question, and reconciling against it seems worth doing before writing a qualifier fresh. Entirely your call; flagging it, not claiming it.

Nothing in #1280 changes this issue's scope, sequencing, or its locked decisions.