Fix YAML syntax errors in all agent files by quoting descriptions

[galezra]

Fix YAML syntax errors in agent description fields

Problem

Agent files were experiencing YAML parsing errors due to unescaped colons in the description field. The error message was:

Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 2 column [various positions]

This occurred because the description fields contained example dialogues with user: and assistant: labels, which YAML interpreted as mapping key-value pairs rather than string content.

Solution

Wrapped all description field values in double quotes to properly escape the content and treat it as a single string value. This allows YAML to correctly parse the colons within the descriptions as part of the string content rather than as mapping separators.

Changes

Fixed YAML syntax in the following agent files:

• refactor-planner.md
• web-research-specialist.md
• documentation-architect.md
• frontend-error-fixer.md
• auth-route-tester.md
• code-architecture-reviewer.md
• code-refactor-master.md
• auth-route-debugger.md
• plan-reviewer.md (fixed earlier)

Technical Details

Changed from:

description: Use this agent when... user: "example" assistant: "example"

To:

description: "Use this agent when... user: \"example\" assistant: \"example\""

The quotes ensure YAML treats the entire description as a string literal, and internal quotes are properly escaped with \n for newlines.

Testing

All agent files now parse correctly without YAML syntax errors.

[Job28703]

Confirmed and expanding on the diagnosis above. I cross-checked this against the currently-shipped Claude Code binary (v2.1.215): when frontmatter YAML fails to parse and name also comes back empty from the failed parse, the agent loader (getAgentDefinitionsWithOverrides) silently returns null for that agent — no error is logged and no tengu_agent_parse_error telemetry fires. So today, on a current Claude Code install, 7 of the 8 shipped agent files in .claude/agents/ (all except auto-error-resolver.md) don't just fail to parse strictly — they disappear from the agent list entirely with zero indication to the user.

I verified this independently with two YAML parsers (Python's PyYAML and Node's js-yaml) — both fail on the same 7 files for the reason already diagnosed here (unescaped user:/assistant: labels inside the unquoted description scalar).

Given the README's Quick Start explicitly promotes these as "8 production-tested agents ... Standalone - just copy and use!", and this issue has been open since 2025-11-12 with a ready-to-apply fix already written out in the description, wanted to flag that this currently makes that specific README claim inaccurate for most users following the setup wizard path. Happy to open a PR with the quoting fix if that's useful — it looks like a mechanical change (wrap the description: values in double quotes and escape embedded quotes).