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 authored agent is a flat .md file in core/agents/ with YAML frontmatter followed by a markdown body. The packager projects those personas into each harness's agent surface; the conductor reads the projected files to frame inline work or delegated execution.

Frontmatter Contract

Every authored core 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 domain design,
  NFR design, and component decomposition.
disallowedTools: Task               # Agents cannot spawn subagents
tier: judgment                      # judgment | balanced | templated (see Agent Tiers)
---

Kiro IDE projects this core contract differently: it removes disallowedTools, adds tools: ["read", "write", "shell"], and adds capability-scoped permissions.rules. Omitting subagent from tools: carries the same no-nested-delegation constraint in the IDE's native vocabulary.

Markdown Body Sections

Below the frontmatter, the markdown body defines:

Shared Configuration

All 14 authored agents share a common configuration baseline. On Claude Code, none declares a tools: allowlist, so every agent inherits the full session toolset plus provisioned MCP tools, with disallowedTools: Task as the shipped denial. Other harnesses project that intent into native surfaces: Kiro agent Markdown omits disallowedTools, Kiro CLI delegate JSON omits subagent from tools, and Kiro IDE delegate tools: grants likewise exclude delegation.

The Claude Code session toolset

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

Common Disallowed Claude Code Tools

Tools each persona is expected to exercise

On Claude Code, 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 Claude persona, add an optional tools: allowlist (which drops inherited MCP unless mcp__<server>__<tool> ids are also listed).

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 templated. 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-advised 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).
• Writing up is dialable, not downgraded by default. The former templated downgrade is now a per-install choice through aidlc config models; the authored templated tier remains unchanged so policy continues to address delivery, pipeline/deploy, and operations as one group.
• 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).
• Cursor never pins a model either. Model availability on Cursor is plan-dependent (a Free account rejects every named model and can only run Auto), so a pinned agent model would hard-fail installs on lower plans. Every Cursor tier therefore omits the .md frontmatter model: line (Cursor has no per-agent effort key -- effort rides the model-id suffix), and all agents inherit the session model; the cursor slots in TIER_PROJECTIONS are model-only, dormant, should a plan-independent pinning mechanism appear.

Tier cap (projection override)

A project can select a lower tier projection at pack time, without editing any agent file. This is a taxonomy ceiling, not a guaranteed cost ceiling now that the templated baseline inherits:

• 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 maps judgment to the measured reviewer baseline in every harness's projection. A templated ceiling maps higher tiers to the inheriting Writing up projection; use aidlc config models when the goal is an explicit lower-cost policy.
• 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 and both temporary check builds use the same repository-defined cap. The environment variable is a one-shot write knob and is ignored under --check; a stray AIDLC_TIER_CAP in CI must not change the determinism measurement. The packager prints a notice when it ignores one and names the active cap and source on every capped write run.

To opt a SINGLE agent out instead, edit the projected value in the installed harness directory (for example, set model: opus on one Claude agent .md). The edit survives until a later aidlc config refresh replaces that framework-owned file after reporting the local modification.

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 (10 stages across 3 phases). - Across the full 14-agent roster, nine agents carry the judgment tier, three carry the inheriting templated tier, and only the two balanced reviewers step down on Claude Code, Codex, and opencode. On Kiro, Cursor, and Copilot all tiers inherit the session model and effort. 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 generated output.
4. Materialize the ignored local distributions with bun scripts/package.ts, then run --check to build twice and verify deterministic output.
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 project instead, edit the projected model: in its harness agent file (Claude Code accepts aliases, full ids, and inherit).
• Change behavior: Edit the markdown body sections (responsibilities, principles).
• Change stage assignments: Edit lead_agent / support_agents in 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