The subagent I built silently - never existed

I built a reviewer agent. The file was perfect. The agent was not there, and nothing told me.

I was adding a new sub-agent to the system, a reviewer whose job was to check other work. I wrote the agent file. The frontmatter was valid and parsed clean. Two sibling agents I created in the same batch, from the same template, registered fine and showed up ready to dispatch.

The reviewer just was not there. Not broken. Not erroring. Absent. The system loaded, reported no problem, and behaved as if I had never written the file at all.

i.A silent failure with a clean conscience

The cause turned out to be a naming collision. The name reviewer is one the harness silently reserves for itself. When my agent claimed that name on load, the harness dropped it without complaint, because from its point of view nothing was wrong: the name was taken, so the new one did not get registered, and that is a normal outcome, not an error worth surfacing.

So every signal I had said success. The file existed. It was well-formed. Its siblings worked. The only thing that did not happen was the one thing that mattered, the agent actually becoming available, and that absence produced no log line, no warning, no failure. The system was working exactly as designed, and my agent did not exist, both at the same time.

ii.Existence is not behavior

Here is the trap, and it is everywhere once you start looking. When you write a config file, define a route, register a handler, add a plugin, the natural assumption is that writing it correctly means it works. The file is the deliverable, so a valid file feels like a working feature. But the file is just the input. Whether the system did anything with it is a separate question, and a valid file can produce no working behavior at all if something downstream rejects it quietly.

The reviewer file was a perfect input that produced no agent. The gap between those two, valid artifact and working artifact, is exactly where silent failures live, and naming collisions love that gap because they are the kind of rejection a system treats as routine rather than exceptional.

iii.The smoke test that caught it

The only reason I found this is that the smoke test did not check whether the file existed. It checked whether the agent worked: could it be dispatched, did it run, did it stay within its bounds. When the dispatch found nothing to dispatch to, the behavior check failed, and the failure pointed straight at the absence the existence check would have papered over.

If I had verified by confirming the file was written and well-formed, I would have signed off on an agent that was not real. The behavior check asked the question that matters, did the thing do its job, and that question has no false positive from a valid-but-ignored file.

iv.Verify the thing did its job

The renamed agent registered and worked, and the fix took a minute once I knew the cause. The lesson took longer to digest, because it argues against an instinct: that producing a correct artifact is the same as having a working thing. It is not. The artifact is a claim. The behavior is the proof.

So when you add anything that a larger system has to accept, a config, an agent, a route, a key, do not verify that you created it. Verify that it does its job. Silent failures hide in the space between those two, and a naming collision is happy to leave you with a perfect file and nothing behind it.

Drafted with Bishop, my AI partner.
Words picked, edited, and approved by me. Model provenance: Claude Code (Claude Opus and Sonnet)