fix(agents): fix YAML frontmatter in 14 agent definitions + validation script

.claude/agents/git-rebase-coordinator.md

@@ -1,6 +1,7 @@
 ---
 name: git-rebase-coordinator
-description: Use this agent when you need to rebase a target branch onto the main branch, including handling merge conflicts and ensuring all tests pass. This agent manages the complete rebase workflow from preparation through validation. Examples: <example>Context: User needs to update their feature branch with latest main branch changes. user: "Please rebase my feature branch on main" assistant: "I'll use the git-rebase-coordinator agent to handle the rebase process" <commentary>The user needs to rebase their branch, so I'll launch the git-rebase-coordinator agent to manage the entire rebase workflow including conflict resolution and test validation.</commentary></example> <example>Context: User has a branch that's behind main and needs updating. user: "My branch is out of date with main, can you update it?" assistant: "Let me use the git-rebase-coordinator agent to rebase your branch onto the latest main" <commentary>The branch needs to be updated with main, which requires a rebase operation. The git-rebase-coordinator will handle this.</commentary></example>
+description: |
+  Use this agent when you need to rebase a target branch onto the main branch, including handling merge conflicts and ensuring all tests pass. This agent manages the complete rebase workflow from preparation through validation. Examples: <example>Context: User needs to update their feature branch with latest main branch changes. user: "Please rebase my feature branch on main" assistant: "I'll use the git-rebase-coordinator agent to handle the rebase process" <commentary>The user needs to rebase their branch, so I'll launch the git-rebase-coordinator agent to manage the entire rebase workflow including conflict resolution and test validation.</commentary></example> <example>Context: User has a branch that's behind main and needs updating. user: "My branch is out of date with main, can you update it?" assistant: "Let me use the git-rebase-coordinator agent to rebase your branch onto the latest main" <commentary>The branch needs to be updated with main, which requires a rebase operation. The git-rebase-coordinator will handle this.</commentary></example>
 model: opus
 color: blue
 ---

.claude/agents/pr-review-architecture.md

@@ -5,34 +5,34 @@ description: |
   Spawned by the pr-review orchestrator for changes that create/modify system boundaries (domains/packages/modules), alter cross-module workflows, or adopt new foundational runtime dependencies/frameworks that become shared primitives.
   Focus: "Will this age well?" — structural system design, not local convention conformance or micro-level code quality.
 
-<example>
-Context: PR introduces a new module boundary or changes dependency direction across packages
-user: "Review this PR that introduces a new `agents-api/src/domains/evals/` domain and refactors shared logic into `packages/agents-core/`."
-assistant: "This is a precedent-setting boundary and layering change. I'll use the pr-review-architecture agent to evaluate the system-level design impact."
-<commentary>
-New/modified boundaries and dependency direction have long-term architectural consequences and are core architecture scope.
-</commentary>
-assistant: "I'll use the pr-review-architecture agent."
-</example>
-
-<example>
-Context: PR changes a multi-step operation that must remain consistent/atomic
-user: "Review this PR that splits one database transaction into multiple operations with async background processing."
-assistant: "Transaction boundaries and partial-failure states are architectural concerns. I'll use the pr-review-architecture agent."
-<commentary>
-Changes to transaction/consistency semantics can create hard-to-debug data corruption and operational incidents.
-</commentary>
-assistant: "I'll use the pr-review-architecture agent."
-</example>
-
-<example>
-Context: User asks for naming or sibling-file convention conformance (near-miss)
-user: "Does this new endpoint follow our route naming conventions and match adjacent files?"
-assistant: "That's primarily a convention/sibling consistency check — not a structural architecture question. I won't use the architecture reviewer for this."
-<commentary>
-Local convention matching is about conformance to existing patterns, not evaluating structural system design.
-</commentary>
-</example>
+  <example>
+  Context: PR introduces a new module boundary or changes dependency direction across packages
+  user: "Review this PR that introduces a new `agents-api/src/domains/evals/` domain and refactors shared logic into `packages/agents-core/`."
+  assistant: "This is a precedent-setting boundary and layering change. I'll use the pr-review-architecture agent to evaluate the system-level design impact."
+  <commentary>
+  New/modified boundaries and dependency direction have long-term architectural consequences and are core architecture scope.
+  </commentary>
+  assistant: "I'll use the pr-review-architecture agent."
+  </example>
+
+  <example>
+  Context: PR changes a multi-step operation that must remain consistent/atomic
+  user: "Review this PR that splits one database transaction into multiple operations with async background processing."
+  assistant: "Transaction boundaries and partial-failure states are architectural concerns. I'll use the pr-review-architecture agent."
+  <commentary>
+  Changes to transaction/consistency semantics can create hard-to-debug data corruption and operational incidents.
+  </commentary>
+  assistant: "I'll use the pr-review-architecture agent."
+  </example>
+
+  <example>
+  Context: User asks for naming or sibling-file convention conformance (near-miss)
+  user: "Does this new endpoint follow our route naming conventions and match adjacent files?"
+  assistant: "That's primarily a convention/sibling consistency check — not a structural architecture question. I won't use the architecture reviewer for this."
+  <commentary>
+  Local convention matching is about conformance to existing patterns, not evaluating structural system design.
+  </commentary>
+  </example>
 
 tools: Read, Grep, Glob, Bash, mcp__exa__web_search_exa
 disallowedTools: Write, Edit, Task

.claude/agents/pr-review-breaking-changes.md

@@ -4,24 +4,24 @@ description: |
   Reviews for breaking changes in schema, migration, env, and contract files.
   Spawned by pr-review orchestrator when these file types are detected.
 
-<example>
-Context: PR modifies database schema or adds migrations
-user: "Review this PR that adds a new column to the users table and includes a migration."
-assistant: "Schema and migration changes need review for breaking change risks. I'll use the pr-review-breaking-changes agent."
-<commentary>
-Schema changes can cause data loss or break existing queries if not migrated correctly.
-</commentary>
-assistant: "I'll use the pr-review-breaking-changes agent."
-</example>
-
-<example>
-Context: Near-miss — PR adds new optional API field without schema changes
-user: "Review this PR that adds an optional field to the API response."
-assistant: "Additive, optional API changes without schema modifications aren't breaking changes. I won't use the breaking-changes reviewer for this."
-<commentary>
-Breaking-changes review focuses on schema, migrations, env, and contracts—not additive API changes.
-</commentary>
-</example>
+  <example>
+  Context: PR modifies database schema or adds migrations
+  user: "Review this PR that adds a new column to the users table and includes a migration."
+  assistant: "Schema and migration changes need review for breaking change risks. I'll use the pr-review-breaking-changes agent."
+  <commentary>
+  Schema changes can cause data loss or break existing queries if not migrated correctly.
+  </commentary>
+  assistant: "I'll use the pr-review-breaking-changes agent."
+  </example>
+
+  <example>
+  Context: Near-miss — PR adds new optional API field without schema changes
+  user: "Review this PR that adds an optional field to the API response."
+  assistant: "Additive, optional API changes without schema modifications aren't breaking changes. I won't use the breaking-changes reviewer for this."
+  <commentary>
+  Breaking-changes review focuses on schema, migrations, env, and contracts—not additive API changes.
+  </commentary>
+  </example>
 
 tools: Read, Grep, Glob, Bash, mcp__exa__web_search_exa
 disallowedTools: Write, Edit, Task

.claude/agents/pr-review-comments.md

@@ -4,24 +4,24 @@ description: |
   Reviews code comments for accuracy, staleness, and misleading information.
   Spawned by pr-review orchestrator for files with significant JSDoc or inline comments.
 
-<example>
-Context: PR modifies code with existing JSDoc or inline comments
-user: "Review this PR that refactors the auth flow and updates several functions with JSDoc comments."
-assistant: "Code changes with existing comments need review for comment accuracy and staleness. I'll use the pr-review-comments agent."
-<commentary>
-Refactors often leave comments outdated, creating misleading documentation that wastes future maintainer time.
-</commentary>
-assistant: "I'll use the pr-review-comments agent."
-</example>
-
-<example>
-Context: Near-miss — PR adds new code without comments
-user: "Review this PR that adds a new utility function with no documentation."
-assistant: "Missing documentation is a different concern than inaccurate comments. I won't use the comments reviewer for this."
-<commentary>
-Comment review focuses on accuracy of existing comments, not absence of comments.
-</commentary>
-</example>
+  <example>
+  Context: PR modifies code with existing JSDoc or inline comments
+  user: "Review this PR that refactors the auth flow and updates several functions with JSDoc comments."
+  assistant: "Code changes with existing comments need review for comment accuracy and staleness. I'll use the pr-review-comments agent."
+  <commentary>
+  Refactors often leave comments outdated, creating misleading documentation that wastes future maintainer time.
+  </commentary>
+  assistant: "I'll use the pr-review-comments agent."
+  </example>
+
+  <example>
+  Context: Near-miss — PR adds new code without comments
+  user: "Review this PR that adds a new utility function with no documentation."
+  assistant: "Missing documentation is a different concern than inaccurate comments. I won't use the comments reviewer for this."
+  <commentary>
+  Comment review focuses on accuracy of existing comments, not absence of comments.
+  </commentary>
+  </example>
 
 tools: Read, Grep, Glob, Bash, mcp__exa__web_search_exa
 disallowedTools: Write, Edit, Task

.claude/agents/pr-review-consistency.md

@@ -5,34 +5,34 @@ description: |
   Spawned by the pr-review orchestrator for most PRs, especially when introducing new public surface area, new files, new endpoints, new config keys, new SDK methods, new CLI commands/flags, new telemetry, or new domain concepts.
   Focus: "Does this fit how we already do things here?" and "Is this a precedent-setting change that needs explicit justification?"
 
-<example>
-Context: PR adds a new API route / response shape
-user: "Review this PR adding a new `/run/v1/...` endpoint and response fields."
-assistant: "This touches a customer-facing contract and needs strict convention conformance. I'll use the pr-review-consistency agent."
-<commentary>
-Customer-facing surfaces are hard to change; this reviewer checks naming/shape parity with existing endpoints and SDK usage.
-</commentary>
-assistant: "I'll use the pr-review-consistency agent."
-</example>
-
-<example>
-Context: PR introduces a new helper/utility and may duplicate existing ones
-user: "Review this PR that adds `src/utils/formatDate.ts` and uses it in a few places."
-assistant: "Helper proliferation is a common inconsistency/duplication risk. I'll use the pr-review-consistency agent to check for existing helpers and alignment."
-<commentary>
-This reviewer explicitly greps for existing primitives to prevent parallel 'same thing' helpers and divergent conventions.
-</commentary>
-assistant: "I'll use the pr-review-consistency agent."
-</example>
-
-<example>
-Context: User wants to judge whether a new architectural boundary is correct (near-miss)
-user: "Should we split this domain into a new package? Is this the right module boundary?"
-assistant: "That's an architectural judgment call — deciding whether a pattern/boundary is the right long-term design is not a consistency check. I won't use the consistency reviewer for this."
-<commentary>
-Consistency review checks conformance to existing patterns; it doesn't decide whether the pattern itself is correct.
-</commentary>
-</example>
+  <example>
+  Context: PR adds a new API route / response shape
+  user: "Review this PR adding a new `/run/v1/...` endpoint and response fields."
+  assistant: "This touches a customer-facing contract and needs strict convention conformance. I'll use the pr-review-consistency agent."
+  <commentary>
+  Customer-facing surfaces are hard to change; this reviewer checks naming/shape parity with existing endpoints and SDK usage.
+  </commentary>
+  assistant: "I'll use the pr-review-consistency agent."
+  </example>
+
+  <example>
+  Context: PR introduces a new helper/utility and may duplicate existing ones
+  user: "Review this PR that adds `src/utils/formatDate.ts` and uses it in a few places."
+  assistant: "Helper proliferation is a common inconsistency/duplication risk. I'll use the pr-review-consistency agent to check for existing helpers and alignment."
+  <commentary>
+  This reviewer explicitly greps for existing primitives to prevent parallel 'same thing' helpers and divergent conventions.
+  </commentary>
+  assistant: "I'll use the pr-review-consistency agent."
+  </example>
+
+  <example>
+  Context: User wants to judge whether a new architectural boundary is correct (near-miss)
+  user: "Should we split this domain into a new package? Is this the right module boundary?"
+  assistant: "That's an architectural judgment call — deciding whether a pattern/boundary is the right long-term design is not a consistency check. I won't use the consistency reviewer for this."
+  <commentary>
+  Consistency review checks conformance to existing patterns; it doesn't decide whether the pattern itself is correct.
+  </commentary>
+  </example>
 
 tools: Read, Grep, Glob, Bash, mcp__exa__web_search_exa
 disallowedTools: Write, Edit, Task

.claude/agents/pr-review-devops.md

@@ -5,50 +5,50 @@ description: |
   Spawned by the pr-review orchestrator for changes to: CI/CD workflows, dependencies, release engineering (changesets), build/container artifacts, self-hosting templates, local devex infrastructure, and AI artifact quality (AGENTS.md, skills, rules, agent definitions).
   Focus: "Will this build, ship, and run correctly across deployment contexts?" and "Will the AI infra still govern agent behavior reliably?"
 
-<example>
-Context: PR modifies a GitHub Actions workflow
-user: "Review this PR that updates the deploy workflow to add a new job step and changes action versions."
-assistant: "CI/CD workflow changes affect the build pipeline and have security implications (action pinning, permissions). I'll use the pr-review-devops agent."
-<commentary>
-Workflow changes are mechanical infrastructure that can break builds, leak secrets, or introduce supply-chain risk. Core DevOps scope.
-</commentary>
-</example>
-
-<example>
-Context: PR adds a new dependency or updates lockfile
-user: "Review this PR that adds `lodash` as a dependency and updates pnpm-lock.yaml."
-assistant: "New dependencies and lockfile changes affect supply chain and need hygiene review. I'll use the pr-review-devops agent."
-<commentary>
-Dependency justification, version pinning, and lockfile churn are DevOps hygiene concerns, not application logic.
-</commentary>
-</example>
-
-<example>
-Context: PR adds or modifies AGENTS.md, skills, or agent definitions
-user: "Review this PR that updates `.claude/agents/pr-review-types.md` and adds a new skill under `.agents/skills/`."
-assistant: "AI artifact quality directly affects how all agents behave. I'll use the pr-review-devops agent to check structure, freshness, and cross-artifact coherence."
-<commentary>
-AGENTS.md, skills, and agent definitions are infrastructure that governs AI behavior. Degradation here silently degrades the entire system.
-</commentary>
-</example>
-
-<example>
-Context: Near-miss — PR changes application code with auth/permission logic
-user: "Review this PR that adds a new API endpoint with authorization middleware."
-assistant: "Auth/permission logic is IAM security scope, not DevOps infrastructure. I won't use the DevOps reviewer for this."
-<commentary>
-Application-level security is out of scope. DevOps focuses on build/ship/configure infrastructure.
-</commentary>
-</example>
-
-<example>
-Context: Near-miss — PR changes system architecture or module boundaries
-user: "Review this PR that introduces a new package and refactors the domain structure."
-assistant: "Module boundaries and architectural layering are system design questions. I won't use the DevOps reviewer for this."
-<commentary>
-Architecture decisions are out of scope. DevOps covers the infra that builds and ships, not the app structure itself.
-</commentary>
-</example>
+  <example>
+  Context: PR modifies a GitHub Actions workflow
+  user: "Review this PR that updates the deploy workflow to add a new job step and changes action versions."
+  assistant: "CI/CD workflow changes affect the build pipeline and have security implications (action pinning, permissions). I'll use the pr-review-devops agent."
+  <commentary>
+  Workflow changes are mechanical infrastructure that can break builds, leak secrets, or introduce supply-chain risk. Core DevOps scope.
+  </commentary>
+  </example>
+
+  <example>
+  Context: PR adds a new dependency or updates lockfile
+  user: "Review this PR that adds `lodash` as a dependency and updates pnpm-lock.yaml."
+  assistant: "New dependencies and lockfile changes affect supply chain and need hygiene review. I'll use the pr-review-devops agent."
+  <commentary>
+  Dependency justification, version pinning, and lockfile churn are DevOps hygiene concerns, not application logic.
+  </commentary>
+  </example>
+
+  <example>
+  Context: PR adds or modifies AGENTS.md, skills, or agent definitions
+  user: "Review this PR that updates `.claude/agents/pr-review-types.md` and adds a new skill under `.agents/skills/`."
+  assistant: "AI artifact quality directly affects how all agents behave. I'll use the pr-review-devops agent to check structure, freshness, and cross-artifact coherence."
+  <commentary>
+  AGENTS.md, skills, and agent definitions are infrastructure that governs AI behavior. Degradation here silently degrades the entire system.
+  </commentary>
+  </example>
+
+  <example>
+  Context: Near-miss — PR changes application code with auth/permission logic
+  user: "Review this PR that adds a new API endpoint with authorization middleware."
+  assistant: "Auth/permission logic is IAM security scope, not DevOps infrastructure. I won't use the DevOps reviewer for this."
+  <commentary>
+  Application-level security is out of scope. DevOps focuses on build/ship/configure infrastructure.
+  </commentary>
+  </example>
+
+  <example>
+  Context: Near-miss — PR changes system architecture or module boundaries
+  user: "Review this PR that introduces a new package and refactors the domain structure."
+  assistant: "Module boundaries and architectural layering are system design questions. I won't use the DevOps reviewer for this."
+  <commentary>
+  Architecture decisions are out of scope. DevOps covers the infra that builds and ships, not the app structure itself.
+  </commentary>
+  </example>
 
 tools: Read, Grep, Glob, Bash, mcp__exa__web_search_exa
 disallowedTools: Write, Edit, Task