Authoring agents

An agent is one markdown file with YAML frontmatter and a system prompt. The structure is the contract — Claude Code reads it directly at install time. This page covers the conventions Synthex itself follows when adding to its agent roster, so you can write agents that compose cleanly with the rest.

#When to write a new agent

Reach for a new agent when an existing agent's prompt would have to grow significantly to cover the new responsibility. The signal is irreducible scope:

• The work uses a different mental model than the parent agent (e.g. compliance review vs. code review).
• The work has its own peer-review style (a domain-specific reviewer that complements code review).
• The work is invoked from multiple commands and benefits from a stable identity.

Don't write a new agent when:

• The work is a one-off step in a single command's workflow — describe it inline in the command instead.
• The new "agent" is just a reformulation of an existing agent's prompt with different emphasis — improve the existing prompt.

A useful test: can you write a one-sentence identity statement that doesn't overlap any existing agent? If you can't, the new agent isn't yet differentiated enough.

#File structure

Agents live in agents/<slug>.md inside your plugin (or agents/ of a Synthex-style fork):

---
model: sonnet
---

# Compliance Reviewer

## Identity

You are a Compliance Reviewer. Your scope is regulatory and audit-trail concerns
in the diff under review. You complement the Security Reviewer (security-vulnerability
focus) and the Code Reviewer (correctness focus) with a compliance lens.

## Core mission

Review the diff against the project's compliance specification (default
`docs/specs/compliance.md`). Produce a structured PASS / WARN / FAIL verdict
covering:

- Audit-trail coverage on data mutations
- PII handling (redaction, retention, access logging)
- Required regulatory disclosures in user-facing surfaces

You are PURELY ADVISORY. You produce findings; the orchestrator decides what to do.

## How to review

1. Read the diff…
2. Cross-reference compliance.md…
3. Emit findings with severity (`critical | high | medium | low`)…
4. Return a verdict.

#Frontmatter conventions

Model selection rule of thumb.

• Opus for end-to-end orchestration with significant judgment (the Tech Lead, the Multi-Model Review Orchestrator).
• Sonnet for domain reviewers and orchestrators with bounded scope (most agents).
• Haiku for mechanical work — finding consolidation, commit-message authoring, context bundling. The agent's job is structural; the cheaper model is correct here.

When in doubt, start with Sonnet and step down to Haiku only after you've confirmed the quality holds.

#Identity is the contract

The most important section of an agent file is its Identity. A good identity:

• Names the role explicitly (You are a Compliance Reviewer.).
• States scope (Your scope is regulatory and audit-trail concerns…).
• States non-scope (You complement the Security Reviewer; you do not assess vulnerabilities.).
• States ethos (You are objective, helpful, and never overly pedantic.).

Synthex's existing agents all follow this shape. Reading two or three of them — Code Reviewer, Architect, Performance Engineer — is the fastest way to absorb the convention.

#Reviewer agents have an explicit advisory clause

Every reviewer agent in Synthex includes some variant of:

You are PURELY ADVISORY. You provide findings and a verdict. The caller decides what action to take.

This is load-bearing. Reviewers that overstep — making merge decisions, modifying the diff, escalating without delegation — break the orchestrator's control. Keep reviewers strictly advisory and the rest of the system stays composable.

#Findings format

When your agent emits findings, follow the structured shape every Synthex reviewer uses:

### Finding — {severity}: {one-line summary}

**Location:** `path/to/file.ts:42`
**Category:** {convention | security | performance | … }

{Two-to-five sentence explanation of what's wrong and why it matters,
written as mentorship — explain the underlying principle, not just the rule.}

**Suggested change:**

{Concrete code or design suggestion, where applicable.}

The Findings Consolidator agent expects this shape. Producing it lets your agent compose cleanly with the rest of the reviewer pipeline; deviating means the consolidator can't merge your findings with the others and your output gets dropped or duplicated.

#Specialist agents and the plan reviewer roster

If your agent should automatically participate in plan reviews or code reviews for projects that use it, register it in .synthex/config.yaml:

implementation_plan:
  reviewers:
    - agent: compliance-reviewer
      enabled: true
      focus: "Regulatory compliance, audit-trail requirements, PII handling"

code_review:
  specialists:
    - agent: compliance-reviewer
      focus: "Regulated-industry concerns"

The roster is per-project. Synthex ships sensible defaults; specialists attach where they're relevant.

#Testing

There's no automated test for an agent's prompt — its quality emerges from running it. Two sanity checks before you ship:

1. Run the agent against an obviously good diff. It should produce no critical/high findings. If it does, the prompt is too aggressive.
2. Run the agent against a known-bad diff. It should catch the issue at the appropriate severity. If it doesn't, the prompt is missing the relevant rules.

Synthex's findings-consolidator and multi-model-review-orchestrator agents include explicit test suites in their files; that's a higher bar than most agents need, but the pattern is available if your agent's behavior is mechanical enough to merit it.

#Next

• Authoring commands — how to wire your agents into a slash command
• Plugin architecture — the plugin shape your agents install into
• The reviewer pipeline — how reviewer agents compose