2026-09-10 · ai · claudecode · devops · productivity

The Workflow Ran With Four Personas Instead of Five and Looked Fine

I run Claude Code as five separate subagents with different permissions — architect, coder, reviewer, conflict resolver, UI designer. One of them stopped loading.

Nothing said so. The work still got done, by whoever was left. It got slower, review got softer, declared scopes stopped being respected. Every one of those looks like "the model is having a bad day".

The symptom has the shape of not working well. The cause was not being there.

A file in `.claude/agents/` is skipped silently

Five conditions in the frontmatter, any one of which means the file is not treated as a subagent:

Condition	What happens
No `name`	Treated as documentation — a note kept beside your agents
The opening `---` is not line 1	Read as having no frontmatter, so documentation again
A `name` starting with `-`, or containing `:`	The whole file is skipped
A `name` but no `description`	Skipped
YAML that does not parse	Nothing is read, file skipped

None of these appear in the session. The reason goes to the debug log, which you see with --debug, which you are not running when things seem fine.

The second row is the one I hit. I had pasted content into a persona file and an editor put something above the opening ---. From then on the file was prose sitting next to four agents, and Claude distributed its work to them.

: is unavailable because it is reserved for plugin-scoped names like my-plugin:reviewer. A leading - is out for the same class of reason.

Copying a persona is where this gets interesting

Adding a persona by duplicating an existing one is the obvious move, and forgetting to change name is the obvious mistake.

Which of two files with the same name loads is not documented. It is decided by filesystem read order.

So the same repository can run a different persona on a different machine, and both machines are "working". I do not have a story about being burned by this one, and I am fairly sure that is luck rather than care.

`claude plugin validate` gets you part of the way

claude plugin validate .claude/agents
claude plugin validate ~/.claude/agents

It finds frontmatter that fails to parse. Two limits worth knowing:

it looks only at the directory you name — user scope is a separate run
it does not flag a file that parses but has no name

Which is most of the list above. It is worth running and it is not sufficient.

The one that was my own fault

My coder persona had this:

tools: *

meaning "this one gets everything". tools accepts exact tool names or the server patterns mcp__<server> / mcp__<server>__*. A bare * is not among them, and an entry resolving to nothing makes Claude Code refuse to launch the subagent.

The documented way to say "everything" is to omit the field.

Why my own linter could not see that is written up separately.

https://quintetkit.github.io/en/articles/blind-spot-from-refusing-to-check.html

The short version is that the rule I wrote to avoid false positives was phrased as "don't look at the tools field".

That one is worse than a missing persona, because coder is the one that writes the code. The other four keep working, so it presents as the coder being unreliable today.

What I do now

Two checks, and I only run them twice: after setup, and after adding or copying a persona.

npx @quintetkit/ccheck        # the five conditions, duplicate names, tools: *
claude --debug                # once, to see what was skipped and why

And a habit that is cheaper than either: count them. If the configuration says five personas, the thing you want to confirm is that five loaded — not that the work is getting done. The work getting done was never the question.

The five conditions and every frontmatter field, in one table:

https://quintetkit.github.io/en/reference/claude-code-subagent-frontmatter.html

I publish the configuration for splitting Claude Code into separate personas — Architect, Coder, Reviewer, Conflict Resolver — under MIT. Copy it, run ./setup.sh, and it works. It does not depend on your tech stack.

https://github.com/quintetkit/quartet

I built one real tool using nothing but this workflow. Every Issue, PR, review and merge is still there. The parts that went wrong were not deleted.

https://github.com/quintetkit/mdlinkcheck

The version that adds a UI Designer persona, review criteria, a per-Issue parallel execution script and a 11-chapter guide is on the product page.

The full kit — five personas, the scripts and the complete guide — is available here.

https://quintetkit.gumroad.com/l/quintet

The workflow itself is available

Quartet, the four-persona version, is published free under MIT. Quintet adds a UI Designer persona, review criteria, a per-Issue parallel execution script, and a 11-chapter guide.

See the free version Product page