Skip to content

ADR-0001: Agents are Markdown subagents

Guide

ADR-0001: Agents are Markdown subagents

  • Status: Accepted · Date: 2026-05-30

Context

Employees need to be definable, versionable, and invokable without bespoke tooling.

Decision

Every employee is a Claude Code subagent defined as a Markdown file in .claude/agents/<slug>.md (YAML frontmatter + system-prompt body). Lifecycle is managed via /agents:* commands.

Consequences

  • Roles are plain text — diffable, archivable, reviewable.
  • The org layer (ORG.md, policies) is a narrative overlay on standard subagents.
  • Tooling is added later per GR-4 (see ADR for the Archivist’s GitHub tooling).