Sub-agents
Sub-agents are specialized Claude Code agents dispatched via the Task tool to own a particular domain — platform infrastructure, WordPress engineering, code review, documentation accuracy, planning, and more. Each agent is a Markdown file with YAML frontmatter (a name and a description that defines when to route to it) plus a body that gives the agent its expertise, conventions, and safety boundaries.
Unlike skills (deterministic workflows), an agent is a focused worker with its own context. It receives a self-contained brief, does specialized work, and returns a result. Independent agents can run in parallel.
When the platform routes to an agent
Operating Protocol 4 in the platform CLAUDE.md, "Orchestrate, Don't Inline," makes agent dispatch the default for non-trivial work:
- Skill first (Protocol 2) — skills are deterministic and cheap.
- Agent next — if an agent's description fits the task, dispatch it via the Task tool. Independent dispatches go in parallel.
- Brief well — hand the agent the search results, file paths, and success criterion already gathered. The agent has no conversation history.
- Synthesize, don't re-do — summarize the agent's result rather than repeating its work.
- No match? Propose creation — if a pattern recurs and nothing fits, propose creating an agent via
wdg-agent-architect.
The rule is not "spawn an agent for everything." It is: don't inline non-trivial work when a specialist exists. Single-line edits, typo fixes, factual lookups from loaded context, and one-shot CLI calls stay inline.
💡 TIP
Match agents by description, not by a memorized name. The roster is dynamic; reading the live list of agents is itself part of the protocol.
Two kinds of agent
As with skills, agents come in two tiers that follow the Projects vs Platform boundary.
| Platform agents | Project agent templates | |
|---|---|---|
| Location | .claude/agents/ | cli/templates/project-agents/ |
| Context | Platform infrastructure, WDG-wide concerns | A single WordPress project's codebase |
| Available to | The platform Claude instance | Individual WordPress projects, once synced |
| Distribution | Present in the platform repo | Copied into projects via wdg ai-config sync |
| Count | 8 | 4 |
How project agents are distributed
Project agent templates are copied from cli/templates/project-agents/ into each project's .claude/agents/ directory. This happens during project creation and can be re-run with wdg ai-config sync:
wdg ai-config sync # Sync agents (and other AI config) to all projects
wdg ai-config sync --force # Overwrite existing files
wdg ai-config sync --project=ccusa # Sync only the named project
# Project-scoped form
wdg <project> ai-config sync [--all] [--force]By default, existing project agent files are preserved; --force overwrites them with the latest templates.
Platform agent catalog
These 8 agents live in .claude/agents/ and specialize in platform-level work.
| Agent | What it does |
|---|---|
docs-auditor | Audits and maintains documentation accuracy across the environment — verifies CLAUDE.md against the filesystem, checks skill consistency, reviews inline-doc compliance, and validates cross-references. Reports findings; edits docs only when explicitly asked. |
planner-agent | Validates and stress-tests implementation plans (refactors, migrations, features, infra changes) against the platform's actual structure before execution. Never executes — only analyzes and improves. |
platform-engineer | Senior platform engineer for infrastructure: MCP server (Python), indexer (Python), CLI (Bash), dashboard (React), Docker orchestration, and service configs. Not for WordPress/PHP project code. |
platform-sentinel | Quality engineer that tests, breaks, and improves the platform by running real commands and showing real output — hunting silent failures, auditing CLI commands, stress-testing Docker, and validating MCP search quality. |
senior-wordpress-engineer | WordPress engineer for project development with the Wikit framework — CPTs, blocks, REST endpoints, theme features in PHP/JS. Extends Wikit, never modifies it. |
skill-creator | Designs, builds, and validates Claude Code skills — new SKILL.md files, audits, workflow-to-skill conversion, and conflict detection between skill descriptions, across both skill tiers. |
wdg-agent-architect | Creates specialized Claude Code agents for the platform — writes the agent file with platform-accurate context and safety boundaries, validates it, and saves it to .claude/agents/. Creates agents, not skills. |
wordpress-code-reviewer | Reviews project PHP for WPCS compliance, security, performance, and Wikit adherence — runs phpcs/phpstan when available and produces structured reports with before/after fixes. Reviews project code only. |
Project agent template catalog
These 4 templates live in cli/templates/project-agents/ and are distributed into projects.
| Template | What it does |
|---|---|
agent-architect | Creates specialized Claude Code agents tailored to this project's codebase, integrations, and workflows; validates and saves them to the project's .claude/agents/. Creates agents, not skills. |
skill-creator | Designs, builds, and validates Claude Code skills, including conflict detection between skill descriptions. (Project-distributed copy of the skill-creator agent.) |
wordpress-engineer | WordPress development agent for the project using Wikit — features, bug fixes, post types/taxonomies, integrations, PHP/JS. Works only within the project repository; never modifies framework or platform files. |
wordpress-site-auditor | Comprehensive site auditor running five phases (code quality, security, performance, accessibility, SEO) and producing a scored report in Markdown, HTML, and PDF. Audits the whole site holistically — not a per-file/PR reviewer. |
Creating or updating agents
Use the wdg-agent-architect agent (platform) or the agent-architect template (project) to scaffold a new agent. Under Operating Protocol 6, when an agent's output is wrong in a way that traces to a specific instruction or omission in its .md file, the fix is propagated back to that file rather than left in conversation — so every future dispatch benefits.
See also
- Skills — deterministic auto-triggered workflows
- Projects vs Platform — the scoping boundary agents follow
- MCP Server — the semantic search tools agents use to orient