Agent System

This chapter documents the agent architecture: how agents are structured, configured, loaded by the framework, and how to add or modify them.

For user-facing agent descriptions, see the User Guide -- Agents.

Agent Structure

Each agent is a flat .md file in .claude/agents/ with YAML frontmatter followed by a markdown body. The conductor reads these files to frame its perspective during inline stage execution or to build context for subagent delegation.

Frontmatter Contract

Every agent file must include this YAML frontmatter:

---
name: aidlc-architect-agent               # Agent identifier (matches filename without .md)
description: >                      # Brief role summary (shown in Claude Code agent list)
  System architect responsible for application design,
  NFR design, and component decomposition.
disallowedTools: Task               # Agents cannot spawn subagents
tier: judgment                      # judgment | balanced | templated (see Agent Tiers)
---

Markdown Body Sections

Below the frontmatter, the markdown body defines:

Shared Configuration

All 14 agents share a common configuration baseline. None declares a tools: allowlist, so every agent inherits the full session toolset — all of Claude Code's built-in tools plus any MCP tools provisioned to the session. The one shipped restriction is disallowedTools: Task.

The session toolset (inherited by every agent)

Every agent inherits the built-in Claude Code tools, including:

Common Disallowed Claude Code Tools

Tools each persona is expected to exercise

Every agent can reach Bash and WebSearch by inheritance; the table records which personas the methodology expects to use them in their stage work, not a per-agent grant. To genuinely restrict a persona, add an optional tools: allowlist (which drops inherited MCP unless mcp__<server>__<tool> ids are also listed) — this implementation ships no such restrictions.

Agent Tiers

The authored dial on every agent is tier: -- it names the KIND of work the persona does, and the packager (bun scripts/package.ts) projects it into each harness's native model/effort form. Previous behaviour (v2.2.15 through v2.2.19; before that the key was the inert modelOverride:) pinned a raw model: opus|sonnet per agent, which forcibly downgraded sessions running a bigger model; the tier projection replaces that pin.

The projection per harness (core/tools/aidlc-tiers.ts is the single source of truth):

Key facts behind the table:

• Omission is the inherit mechanism. On Claude Code an agent .md with no effort: key inherits the session effort, and a pinned effort: overrides the session in BOTH directions (a pin is a cap, not a floor) -- so absence is the contract for judgment and balanced. On Codex a role TOML without model spawns on the shipped .codex/config.toml session defaults (verified live on codex-cli 0.139.0 and 0.142.5; the current doctor-enforced minimum is 0.145.0 for immediate compact-session reload). On Kiro the agent-v1 schema documents the absent-"model" fallback: "If not specified, uses the default model" (the /model persisted preference).
• Kiro never pins a model. A shipped Kiro model ID resolves only when that model is enabled on the user's install; a session running any other model rejects every delegated spawn with Invalid model ID, and Kiro rejects the Claude-dialect tier aliases (opus/sonnet) outright -- so there is no universally safe pinnable value. Every Kiro tier therefore omits "model" (and the .md frontmatter model: line): all agents inherit the session model. The kiro slots in TIER_PROJECTIONS and the kiroModelDefaults() machinery remain in place, dormant, should a resolvable per-install pinning mechanism appear.
• Kiro has NO per-agent effort surface. kiro-cli fail-closes on any effort-like key in agent JSON, so a per-model effort default can only ride on settings/cli.json chat.modelDefaults[<modelId>].output_config.effort. With no tier pinning a model, only the authored conditional entry ships (claude-opus-4.8 -> xhigh, applied only when the session actually runs that model). That file is CLI-only: the Kiro IDE ignores cli.json entirely and applies its extension-embedded per-model default (or the user's /effort session state).

Tier cap (cost override)

A project can cap every projection at pack time, without editing any agent file:

• Persistent knob: a tier_cap: key in the YAML frontmatter of the space memory layer files (core/memory/org.md -> team.md -> project.md, last writer wins -- a project may lower OR raise the org ceiling). Example: tier_cap: balanced collapses judgment to balanced in every harness's projection (on Kiro, where no tier pins a model, the cap is inert -- all tiers already inherit the session model).
• Per-invocation override: the AIDLC_TIER_CAP env var beats the memory layers for one packager run (AIDLC_TIER_CAP=templated bun scripts/package.ts). To build UNCAPPED once while a memory cap is in force, set it to the top tier -- AIDLC_TIER_CAP=judgment -- which beats the memory layer and clamps nothing (an empty value means unset, not uncapped).

The two knobs differ in scope: the memory cap travels with the repo, so it applies in BOTH write and --check modes (a project that commits a capped dist stays self-consistent). The env var is a one-shot WRITE knob and is IGNORED under --check - the drift guard compares what the committed dist was legitimately built from, and a stray AIDLC_TIER_CAP in a CI or test runner's environment must neither fail nor mask drift (the packager prints a notice when it ignores one). The packager also prints the active cap and its source on every capped run.

To opt a SINGLE agent out instead, edit the projected value in your installed dist/<harness>/ copy (e.g. set model: opus on one Claude agent .md) -- the edit survives until you re-copy the dist shell.

Agent Comparison Matrix

Yes in the next two columns means expected use of an inherited tool, not an access grant.

Observations: - aidlc-architect-agent has the broadest stage involvement (9 stages across 3 phases). - Across the full 14-agent roster, nine agents carry the judgment tier and five step down on Claude Code, Codex, and opencode (the two balanced reviewers plus the three templated planners; on Kiro all tiers inherit the session model and effort, so no agent steps down there); the stepped-down agents produce reviews against explicit checklists or dominantly templated planning, CI/CD, and runbook work. The matrix above covers the 11 domain-expert agents. - aidlc-compliance-agent operates purely in an advisory capacity (4 support stages, no lead stages). - Six of 11 agents are expected to use Bash for CLI interaction. - Three agents are expected to use WebSearch for research tasks.

Phase Participation

L = Lead, S = Support

How to Add an Agent

Agent display names and example knowledge files are authoritative in each agent's .md frontmatter via the display_name and examples fields — no TypeScript edits required. See Contributing: Adding an Agent for the full recipe (required frontmatter fields, verification steps, and what validates automatically vs. manually). Quick summary of the steps:

1. Create core/agents/{name}-agent.md with the required frontmatter: name, display_name, examples, description, disallowedTools (including Task), tier. Never author raw model:/effort: in core frontmatter -- they are projection outputs (see Agent Tiers above). An optional tools: allowlist narrows the inherited toolset; omit it to inherit the full session toolset. loadAgents() in core/tools/aidlc-lib.ts discovers the file on next invocation.
2. Add knowledge files to core/knowledge/{name}-agent/
3. Add the agent to the stage files (core/aidlc-common/stages/) where it participates — set lead_agent / support_agents in each stage's frontmatter. The compiled tools/data/stage-graph.json is GENERATED from that frontmatter by bun scripts/package.ts; never hand-edit it (the package.ts --check drift guard fails CI on a hand-edited dist).
4. Regenerate the distributions: bun scripts/package.ts (then --check to confirm no drift)
5. Add the agent→examples row to the hand-maintained knowledge tables (the space-level team-knowledge dir is aidlc/knowledge/{name}-agent/, created by the team when it has content — the engine does not scaffold it)
6. Update tests: smoke tests for file existence, feature tests for stage-agent cross-references
7. Update documentation in this file and reference/agents/

How to Modify an Agent

• Change tools: Add or edit a tools: allowlist in frontmatter to narrow the agent; omit it to inherit the full session toolset. A tools: list drops inherited MCP tools unless the mcp__<server>__<tool> ids are also listed.
• Change tier: Edit tier: to judgment, balanced, or templated and regenerate (bun scripts/package.ts). To force a specific model on ONE agent in an installed copy instead, edit the projected model: in your dist/<harness>/ agent file (Claude Code accepts aliases, full ids, and inherit).
• Change behavior: Edit the markdown body sections (responsibilities, principles).
• Change stage assignments: Edit both the agent file (Stages Owned section) and the relevant stage files (core/aidlc-common/stages/), then regenerate with bun scripts/package.ts — the compiled stage graph is derived from stage frontmatter, never hand-edited.

Cross-References

• Architecture -- 5-layer model including agent layer
• Knowledge System -- knowledge loading order
• Agents Technical Reference -- per-agent technical details
• Stage Protocol -- agent persona loading rules