Skip to content

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 four 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>/… -- an ignored local generated source/development projection (dist/claude/.claude/, dist/kiro/.kiro/, dist/kiro-ide/.kiro/, dist/codex/, dist/opencode/, dist/copilot/). Never hand-edited or committed; materialized by bun scripts/package.ts. Release payloads use runtime/<harness>/ inside aidlc-runtime-X.Y.Z.tar.gz. - <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 ({{INVOKE}} engine graph 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, 91-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, DocumentKB derived catalog, loading order, templates
Contributing Development workflow, utility handler checklist, documentation policy
State Machine Workflow / phase / stage machines, 91-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
Supply-Chain Security Release attestations, SLSA provenance, checksums, workflow hardening, installer defenses, ownership, and enterprise transport
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 aidlc engine graph 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