Developer Reference Overview

Part of the AI-DLC documentation · User Guide · Harness Engineer Guide · Developer Reference

This reference documents the internal architecture and implementation of AI-DLC. It is intended for contributors changing the AI-DLC codebase itself -- the orchestrator, hooks, CLI tools, the stage-graph compile pipeline, the audit taxonomy, or the test suite.

If you are using AI-DLC to build software, start with the User Guide. If you are reshaping how AI-DLC behaves through configuration -- adding a stage or an agent, defining a scope, authoring rules and sensors, adding team knowledge -- start with the Harness Engineer Guide; those are data changes, not code changes, and the chapters there narrate the workflow before pointing back here for the exhaustive schema.

Paths in this reference. AI-DLC is authored once and generated per harness, so a file is named by one of three conventions, by intent: - core/… -- the hand-authored, harness-neutral source of truth (e.g. core/tools/aidlc-orchestrate.ts, core/aidlc-common/stages/). This is where you edit. When a path names where a file is authored or changed, it is a core/ path. - dist/<harness>/… -- the generated, committed, drift-guarded distribution (dist/claude/.claude/, dist/kiro/.kiro/, dist/kiro-ide/.kiro/, dist/codex/). Never hand-edited; reproduced byte-for-byte by bun scripts/package.ts. Cited only when describing what ships. - <harness-dir>/… (e.g. .claude/, .kiro/, .codex/) -- the runtime location inside an installed project, where commands run and the framework reads/writes during a workflow (bun .claude/tools/aidlc-graph.ts compile, loadAgents() reading .claude/agents/). The directory is a parameter of the harness.

Where this reference shows a bare .claude/ path, read it as the runtime location for the Claude harness specifically; the same file is authored in core/ and ships to each harness's own directory.

What This Reference Covers

Chapter	Topic
Architecture	5-layer model, Configuration layers routing principle, execution model, design decisions
Plane Architecture	The control / data / management plane separation and its boundaries
Orchestrator	The SKILL.md conductor: the forwarding loop, the gate ritual, the state machine it drives
Stage Protocol	Behavioral contract: approval gates, compliance checklist
Stages	Per-phase stage documentation (5 files)
Agent System	Agent structure, frontmatter contract, configuration matrix
Hooks and Tools	Hook system, CLI tools, 74-event audit taxonomy
Sensor System	Sensor manifest schema, PULL imports, fire model, default severity
Rule System	Rule file layout, scope derivation, the layer-chain resolver, conflict gates
Testing	Test pyramid, tiers, stubs, fixtures, test registry
Knowledge System	Two-tier architecture, loading order, templates
Contributing	Development workflow, utility handler checklist, documentation policy
State Machine	Workflow / phase / stage machines, 74-event taxonomy, audit-first rules
Runtime Graph	The compiled `runtime-graph.json` artifact: data-plane mirror of the stage graph
Harness Primitives Mapping	How each AI-DLC concept maps to a harness's native primitives (Claude Code in depth)
Stage Definition	YAML frontmatter contract, three-compartment body, compile pipeline
Artifact Vocabulary	Naming rules, collision policy, filesystem mapping, and how to view the live registry
Engine and Skill System	The orchestration engine (`next`/`report`/`park`), the typed directive contract, the conductor, plural skills, scope shape, and the swarm referee
Plugin Mechanism	The AIDLC plugin system: manifest, install-time composition as a real host plugin, the additive contribution seam, multi-tenant guards, and as-built status. Authoring walkthrough at harness-engineering/10
Diagrams	All Mermaid diagrams in one place
Agents	Technical agent reference (frontmatter, tooling, stage ownership)

How to Navigate

Where does a new concern (rule, methodology, knowledge fact) belong? Read Architecture: Configuration layers — the two-axis model (authorship × consumption) with boundary tests routes any new concern to the correct file.
Adding a new stage? Read Stage Protocol, then the relevant phase file in Stages, then Contributing.
Changing the stage definition format? Read Stage Definition before editing any stage .md file. Stage file format is data-driven; runtime reads a compiled JSON.
Adding or renaming an artifact? Read Artifact Vocabulary — the chapter explains the naming rules, the stability policy (rename/removal = major, addition = minor), and points at bun aidlc-graph.ts artifacts for the live list. The registry is derived from stage files, not written.
Adding a new scope? Read Contributing: Adding a Scope. Scopes are file-authored — a .claude/scopes/aidlc-<name>.md file plus a scopes: tag on each member stage — no TypeScript edits required.
Adding a new agent? Read Contributing: Adding an Agent. Agents are data-driven via their .md frontmatter — no TypeScript edits required.
Modifying an agent? Read Agent System and the agent's file in Agents.
Working on hooks? Read Hooks and Tools and Testing for hook test patterns.
Changing the orchestrator? Read Orchestrator and Architecture. If you're adding or modifying audit events, start with the State Machine chapter — the drift test will catch you if you don't.

Relationship to the User Guide

The User Guide (docs/guide/) explains what AI-DLC does and how to use it. This Developer Reference explains how it works and how to change it. Some topics appear in both:

Topic	User Guide	Developer Reference
Agents	What they do, when they appear	Frontmatter contract, how to add/modify
Knowledge	How to add company standards	Loading order internals, template system
Hooks	What gets logged	Hook implementation, audit event taxonomy