Agent roster — the Claude Code subagent layer

Scope of this page

This page documents the Claude Code native subagent system — the Tier A layer of the estate (see client tiers). Claude Code is one of several supported AI clients; for the cross-tool configuration model (AGENTS.md, per-tool config, MCP wiring for Codex/Gemini/Cursor/Copilot) see the agents standard. Single-agent (Tier B) clients do not have this subagent layer and must not emulate it — they run the same workstreams sequentially per the Tier B digest.

Claude Code supports specialized subagents — Markdown files with YAML frontmatter that declare a name, model, tool list, and system prompt. When Claude Code spawns an agent, the harness loads the matching file and runs it with those settings.

The canonical agent roster for all HCS repos is documented in D:\git\azurelocal\demo-repository\AGENTS-PLAN.md. This file explains the format, conventions, and strategy. The roster is the source of truth for which repos have agents and which model each uses.

---

⚠️ HARD COST RULE — agents never use the metered API

Agents and automation MUST run under the Claude Code subscription/harness. Never call the Anthropic API directly.

Concretely:

• No agent definition may shell out to anthropic SDK / use an ANTHROPIC_API_KEY in its code or scripts.
• Subagents are spawned through the Claude Code harness (Agent tool / subagent_type field), which bills under the plan.
• The only sanctioned external-model path is the gemini-runner agent / /second-opinion command (Gemini key in kv-hcs-vault-01) for second opinions. No other external model API calls.
• A proposed agent that would call the paid API is rejected in review and must be rearchitected.

This rule exists because direct API calls bypassed the plan and incurred large unexpected charges. It is a hard rule enforced by the MCP agent_selection prompt and the HARD_RULES_GLOBAL rules block, and it binds every client tier.

---

Agent-selection procedure — follow this before creating or spawning any agent

Always invoke the MCP agent_selection prompt (get_guidance("agent-selection") + which_standards_apply(repo)) before creating a new agent or spawning subagents for a task. The procedure is:

Step 1 — Check the shared HCS roster first

The shared roster is available in every HCS repo session. Use a shared agent unless the work is demonstrably repo-specific (see Step 3).

User-level shared agents (~/.claude/agents/):

Agent	Model	Use when
triage-lookup	haiku	"What does this file say?" — fast read-only lookup, log triage, find references
markdown-prose-editor	sonnet	Editing Markdown/MDX docs — runbooks, READMEs, ADRs, blog drafts
azurelocal-domain-expert	opus	Deep cross-repo Azure Local / Hyper-V / S2D / Network ATC research
mkdocs-material-doctor	sonnet	MkDocs Material theme, plugins, nav config, mike versioning (14 repos)
turner-module-scaffold-engineer	sonnet	Turner Legacy scaffold modules (board, budget, calendar, finance, travel)
mms-2026-demo-presenter	sonnet	MMS 2026 session demos only
cloudsmith-pm	sonnet	CloudSmith project manager — CloudSmith repos only. Never invoke for any other project.

Platform workstream agents (D:\git\platform\.claude\agents\):

Agent	Model	Use when
planner	sonnet	Plans complex changes — reads code, produces step plan; no code changes
coder	sonnet	Implements changes within a planner's scope
reviewer	sonnet	Reviews diffs for correctness and security
documenter	sonnet	Writes and edits docs — READMEs, runbooks, ADRs
investigator	opus	Root cause analysis — structured findings only, read-only
operator	opus	Infra/secrets/permissions changes after security review + human approval
security-reviewer	sonnet	Security audit: injection, secrets, auth/authz, PII
router	sonnet	Classifies a task into a workstream
test-writer	sonnet	Writes tests — no production code changes
gemini-runner	sonnet	Wraps Gemini for second-opinion analysis (requires Phase 0b)

Orchestration agents (platform session, same directory):

Agent	Model	Use when
orchestration-pm	sonnet	Multi-repo dispatch coordinator — reads registry, builds waves, aggregates results
security-waf-caf	opus	WAF 5-pillar + CAF naming gate — hard merge blocker; verdict:block cannot be overridden
terraform-validator / bicep-validator / arm-validator / ansible-linter / powershell-linter	haiku or sonnet	Type-specific deterministic checks (run via /dispatch)

Step 2 — Check the scope-specific roster

Resolve the repo's scope with which_standards_apply(repo_name). The scope field determines which additional agents apply.

Scope	Additional agents
hcs (default)	No additions beyond the shared HCS roster above
tierpoint-prodtech	Also use tp-standards-auditor (in D:/git/tierpoint/prodtech/docs/docs/.claude/agents/) for prodtech compliance checks before committing docs

The agentRoster field in the which_standards_apply response confirms which roster to use.

Step 3 — When to create a repo-specific custom agent

Create a repo-specific agent (in <repo>/.claude/agents/) only when all of these are true:

1. The task requires deep project-specific knowledge that would be wrong or misleading in any other repo (e.g., the exact module naming convention in this repo, a one-of-a-kind GUID folder requirement, a unique publish flow).
2. The work recurs across multiple sessions in this repo — custom agents for one-off tasks are wasteful.
3. No shared agent covers it — you have genuinely checked Step 1 and Step 2.
4. The new agent does not call the Anthropic API (see Hard Cost Rule above).

Do NOT create a custom agent when:

• A shared agent exists that covers the task (even partially) — extend or configure it instead.
• The task is a one-off — use the main Claude Code session directly.
• You would be duplicating a shared agent with slightly tweaked instructions — update the shared agent instead (or file a request in AGENTS-PLAN.md).
• The agent would only be used once, then abandoned.

---

Agent definition format

---
name: agent-name
description: One-line description. Used by the harness to match spawn requests. Be specific.
model: haiku|sonnet|opus
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
  - WebSearch
  - mcp__claude_ai_Microsoft_Learn__microsoft_docs_search
  - mcp__claude_ai_Microsoft_Learn__microsoft_docs_fetch
  - mcp__claude_ai_Microsoft_Learn__microsoft_code_sample_search
---

Plain-text system prompt for this agent.
Tell it what it is, what it knows, what its constraints are.
Do not use YAML or JSON in the system prompt — plain prose only.

Rules:

• name must match the filename (minus .md) exactly
• description is shown in the agent list and matched when spawning — write it to be unambiguous at a glance
• Only list tools the agent actually needs — narrower is safer
• The system prompt body has no length limit but shorter is faster and cheaper
• No secrets, credentials, or hardcoded values in any agent file
• No agent may call the Anthropic API directly (see Hard Cost Rule above)

---

Model assignment strategy

Tier	Model alias	When to assign	Cost vs opus
Cheap	haiku	Read-only: "what does this file say", log triage, cheap one-shots	~20%
Default	sonnet	Most agents — code, writing, research, planning	~60%
Heavy	opus	Only for deep cross-repo research (azurelocal-domain-expert), hard gate (security-waf-caf), root cause analysis (investigator), infrastructure execution (operator)	100%

The rule is: default to sonnet. Opus is ~5× more expensive per output token. Use it only when the task genuinely requires deep multi-source synthesis or is a hard decision gate.

Other clients (Tier B) select their model with the tool's own picker (codex -m, gemini -m, or the IDE UI) and honour an optional suggested-model: hint in .ai/state/CURRENT_TASK.md. See the agents standard for the cross-tool model-override model.

---

Two scopes

User-level (~/.claude/agents/)

Available in every repo session on this machine. Used for:

• Domain expertise that spans many repos (e.g., Azure Local research)
• Utilities that are repo-agnostic (e.g., Markdown editor, log triage)
• Agents that serve multiple related repos where a separate agent per repo would be wasteful

Repo-level (<repo>/.claude/agents/)

Only available inside that specific repo. Used for:

• Deep project-specific knowledge (module structure, cmdlet naming, test patterns, PSGallery publish flow)
• Hard constraints that are unique to that repo (e.g., NEVER touch versioned_docs/, GUID folder requirement)
• Anything that would be misleading or wrong if applied outside that repo

---

Current user-level agents

Agent file	Model	Tools	Purpose
triage-lookup.md	haiku	Read, Grep, Glob	Fast read-only: "what does this file say", find references, summarize logs. No writing.
markdown-prose-editor.md	sonnet	Read, Write, Edit, Glob	General Markdown/MDX editing — runbooks, READMEs, ADRs, blog drafts. Stack-agnostic.
azurelocal-domain-expert.md	opus	Read, Grep, Glob, WebFetch, WebSearch, Microsoft Learn MCP tools	Deep cross-repo research on Azure Local, Hyper-V, S2D, Network ATC. Only opus user-level agent.
mkdocs-material-doctor.md	sonnet	Read, Write, Edit, Glob, WebFetch	MkDocs Material theme, plugins, nav config, mike versioning. Covers 14 repos.
turner-module-scaffold-engineer.md	sonnet	Read, Write, Edit, Glob, Grep	Turner Legacy scaffold modules (board, budget, calendar, finance, travel). All share the same Vite/React/TypeScript stub pattern.
mms-2026-demo-presenter.md	sonnet	Read, Write, Edit, Glob	MMS 2026 session demos (AVD demo, Hybrid Update Blues).
cloudsmith-pm.md	sonnet	Read, Write, Edit, Glob, Grep, Agent	CloudSmith project manager — status reports, ADO work items, agent orchestration, phase tracking. CloudSmith repos only. Never invoke for any other project.

Archived agents (replaced 2026-04-30): azure-local-researcher.md, docs-writer.md, quick-lookup.md — in _archive_2026-04-30/.

---

Current repo-level agents

All repo-level agents use sonnet except demo-scratchpad-curator (haiku). See AGENTS-PLAN.md for the full table including which repos are pending and which are explicitly skipped.

Repo	Agent name
azurelocal.github.io	docusaurus-doctor-azurelocal
azure-scout	azure-scout-engineer
azurelocal-ranger	ranger-engineer
azurelocal-s2d-cartographer	cartographer-engineer
azurelocal-vm-hydration	vm-hydration-engineer
azurelocal-toolkit	azl-toolkit-engineer
azurelocal-azloflows	azloflows-engineer
azurelocal-surveyor	surveyor-engineer
azurelocal-platform	platform-standards-keeper
demo-repository	demo-scratchpad-curator (haiku)

Project 42 repos (project42.github.io, project42dev.github.io, project42dev/project42.github.io, thisismydemo/project-x) ship a 9-agent set as part of the framework — do not modify them.

---

Workstream pipeline agents

The full workstream pipeline agent set is instantiated in D:\git\platform\.claude\agents\ and available in every platform session. Templates for per-repo deployment are in templates/claude/agents/ — copy and prefix with the repo's short name (e.g., turner-coder.md).

Agent file	Model	Role	Read-only?
planner.md	sonnet	Plans complex changes — reads code, produces written step plan, no code changes	Yes
coder.md	sonnet	Implements changes within planner's scope; stops at 160K tokens	No
reviewer.md	sonnet	Reviews correctness, security, RBAC; approve/request_changes/block	Yes
documenter.md	sonnet	Writes docs — READMEs, runbooks, ADRs, inline comments	No (docs only)
investigator.md	opus	Root cause analysis — structured findings only, no changes	Yes
operator.md	opus	Infra/secrets/permissions changes after security review + human approval	No
security-reviewer.md	sonnet	Security audit: injection, secrets, auth/authz, PII	Yes
router.md	sonnet	Classifies tasks into workstreams	Yes
test-writer.md	sonnet	Writes tests — no production code changes	No (tests only)

Cross-family reviewer requirement: the reviewer must run on a different model family than the coder. In the HCS estate, all agents are Anthropic models. The skill documents this limitation in model_family_note; findings are not suppressed.

Maximum 2 revision cycles in any coder ↔ reviewer loop. Escalate to human after 2.

See Skills for the workstream pipelines that drive these agents. Tier B clients run these same workstreams sequentially — see the Tier B digest.

Orchestration system agents

Multi-agent orchestration for the ~157-repo HCS estate lives in D:\git\platform. The system validates, security-gates, and sweeps repos at scale. All orchestration agents are in the platform repo (D:\git\platform\.claude\agents\) — NOT in user-level ~/.claude/. This makes them portable across machines. Commands live in D:\git\platform\.claude\commands\.

See Orchestration overview for the full dispatch flow.

Orchestration PM

Agent file	Model	Purpose
orchestration-pm.md	sonnet	Coordinator. Resolves targets from master-registry.db, decomposes work into waves (max 8 concurrent, max 1 per repo), aggregates outcomes. Read/write scope: registry, profiles, AGENTS-PLAN.md, docs/agents/*, persona files — never product code.

Pluggable persona — the PM's personality is runtime-switchable. At session start it reads ~/.claude/agents/personas/ACTIVE (one-line name), then loads personas/<name>.md and adopts that persona's tone and sign-off. Switch with /persona <name>. Available personas:

File	Personality	Sign-off
personas/jarvis.md	J.A.R.V.I.S. — calm chief-of-staff, dry wit, addresses Kris as "Sir"	— J.A.R.V.I.S.
personas/neutral.md	Plain professional PM voice, no roleplay	— Orchestration PM
personas/brain.md	The Brain — grand methodical strategist, extraordinary precision	— The Brain

Security gate

Agent file	Model	Purpose
security-waf-caf.md	opus	WAF 5-pillar (Reliability, Security, Cost, OperationalExcellence, Performance) + CAF naming/governance gate. Hard merge blocker — verdict: block cannot be overridden by the PM. Uses Microsoft Learn MCP for live doc lookups.

Validator agents

Agent file	Model	Repo types	Key tools run
terraform-validator.md	haiku	iac-terraform	terraform fmt -check, terraform validate -backend=false, tfsec
bicep-validator.md	haiku	iac-bicep	az bicep build, Invoke-PSRule -Module PSRule.Rules.Azure
arm-validator.md	haiku	iac-arm	ARM-TTK (Test-AzTemplate)
ansible-linter.md	haiku	iac-ansible	yamllint, ansible-lint, ansible-playbook --syntax-check (syntax-check ONLY — never runs playbook)
powershell-linter.md	sonnet	iac-powershell	Invoke-ScriptAnalyzer, Invoke-Pester, HCS script-header conformance check

Review and bulk agents

Agent file	Model	Purpose
reviewer.md	sonnet	Code correctness, security, performance review on diffs. Instantiated from templates/claude/agents/reviewer.md.
security-reviewer.md	sonnet	Security audit: injection, secrets, auth/authz, PII. Instantiated from template.
documenter.md	sonnet	Writes and edits docs — READMEs, runbooks, ADRs. Instantiated from template.
gemini-runner.md	sonnet	Wraps scripts/Invoke-HCSGeminiPrompt.ps1 for bulk sweeps and second-opinion analysis. Requires Phase 0b (Gemini key in kv-hcs-vault-01) to be complete.

Orchestration commands

Command	Invocation	Purpose
dispatch.md	/dispatch [type|repo|--dry-run]	Classify task, resolve repos via registry, spawn validators + security gate, aggregate report
sweep.md	/sweep <dimension>	Cross-repo read-only scan (e.g., CAF naming drift, secrets grep, docs style)
second-opinion.md	/second-opinion <file> [-- question]	Send one artifact to Gemini for independent analysis
persona.md	/persona [name]	List or switch the PM's active persona (writes to personas/ACTIVE)

Registry and profiles

File	Purpose
D:\git\platform\master-registry.db	All ~157 repos: name, platform, local_path, type, validation_profile, standards_scope, pilot
D:\git\platform\profiles\iac-terraform.yaml	Terraform validation profile (fmt, validate, tfsec, CAF, WAF)
D:\git\platform\profiles\iac-bicep.yaml	Bicep validation profile (build, PSRule.Rules.Azure, CAF, WAF)
D:\git\platform\profiles\iac-arm.yaml	ARM validation profile (ARM-TTK, CAF, WAF)
D:\git\platform\profiles\iac-ansible.yaml	Ansible validation profile (yamllint, ansible-lint, syntax-check)
D:\git\platform\profiles\iac-powershell.yaml	PowerShell validation profile (PSScriptAnalyzer, Pester, header-check)
D:\git\platform\profiles\docs.yaml	Docs validation profile (markdownlint, link-check, structure-review)
D:\git\platform\profiles\web.yaml	Web app validation profile (lint, type-check, dep-audit, structure)
D:\git\platform\profiles\app.yaml	General app validation profile (lint, type-check, unit-tests, dep-audit)

---

Adding a new agent

1. Invoke the agent-selection gate first: call get_guidance("agent-selection") from the MCP and work through the procedure. Document why no shared agent is sufficient.
2. Decide the scope: user-level (serves multiple repos) or repo-level (project-specific)
3. Pick the model: haiku for cheap reads, sonnet for everything else, opus only if genuinely needed
4. Copy templates/claude/agent.md.template (generic scaffold) or a specific agent from templates/claude/agents/ as a starting point
5. Fill in all fields — name, description, model, tools, system prompt. No API calls in the agent.
6. Update AGENTS-PLAN.md in D:\git\azurelocal\demo-repository with the new entry
7. If repo-level, add the "Subagents available" stanza to the repo's CLAUDE.md
8. Commit: feat(claude): add <agent-name> agent

---

Retiring an agent

Do not delete agent files — move them to an _archive_<date>/ folder in the same directory. This preserves the audit trail and makes it possible to restore if needed.

Update AGENTS-PLAN.md to show the agent as archived.

---

MCP relationship & retirement

~8 agents fold into the HCS Governance MCP and become portable to any AI client: the five validators (*-validator/*-linter) → MCP validate; triage-lookup/router → MCP find_repos/which_standards_apply; platform-standards-keeper → MCP resources. They're retired (archived) once orchestration-pm is rewired to call the MCP validate tool instead of spawning validators. orchestration-pm, security-waf-caf, and the reasoning workers stay. See mcp-server/docs/HCS-Platform-MCP-Design.md §6.

The MCP enforces agent-selection via the agent_selection prompt — invoke it (get_guidance("agent-selection")) before spawning agents.