Harness Engineer Guide

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

AI-DLC is a methodology, and this implementation ships it working out of the box on the harness you use — Claude Code, Kiro CLI, Kiro IDE, Codex CLI, Cursor, opencode, or GitHub Copilot: 14 agents (11 domain experts, 2 reviewers, and the composer), 33 stages, 11 scopes, a set of rules and sensors. This guide is for the person who wants to reshape that methodology — change which stages run, add an agent for a domain the framework doesn't cover, tighten a scope, teach the framework a standing rule, or wire a deterministic check into a stage.

You do all of that without writing code.

Three readers, three guides

AI-DLC's documentation is split by what you're trying to do, not by topic:

The line between this guide and the Developer Reference is data versus code. Everything a harness engineer touches is a Markdown file with YAML frontmatter or a JSON config — declarative data the framework loads at runtime. Adding a stage, adding an agent, defining a scope: the framework's own design principle is that these require no TypeScript edits. The moment a change means editing .ts — the orchestrator, a hook, a tool — you've crossed into the Developer Reference.

The mental model: stages are what, agents are who

Two primitives carry most of the framework, and keeping them straight is the whole job:

• A stage is a unit of work — what happens. It declares the artifacts it consumes and produces, the agent that leads it, and how it executes. Stages are the nodes of the workflow graph.
• An agent is a persona — who does the work. It carries a domain expertise, a tool allowlist, and a model. Agents are loaded into stages.

A stage names its lead agent; an agent never names its stages. This asymmetry is deliberate: it lets you reassign work (edit the stage) without rewriting the worker, and add a worker (drop an agent file) without disturbing the workflow until a stage opts to use it.

Two pieces of machinery move work through these stages, and as a harness engineer you shape the data both of them read. The deterministic engine (core/tools/aidlc-orchestrate.ts, with exactly five subcommands: next, continue, report, park, and team-board; continue is internal steering transport and team-board is the read-only Team Construction query) reads aidlc-state.md and the compiled stage-graph.json, decides what runs next, and emits one typed directive. The conductor (skills/aidlc/SKILL.md) is a thin forwarding loop that carries each directive out. Routing lives in the engine; your stage files, scopes, and rules are the inputs that steer it.

Everything else a harness engineer configures hangs off these two:

• Scopes decide which stages run for a given kind of work (a bugfix runs 9 of 33 stages; an enterprise feature runs all of them).
• Rules are standing decisions that travel into every workflow — your team's "always do it this way."
• Sensors are deterministic checks bound to stages — they run on matching writes or at the approval gate, where a binding may be advisory or blocking.
• Knowledge is the domain context agents load before they work.

What you can change without code

You author all of these in core/ — the hand-authored, harness-neutral source — then regenerate the per-harness trees (see The build model below).

Each chapter narrates the how and links down to the Developer Reference for the exhaustive schema — the reference is the normative contract; this guide is the working narrative.

One row is the exception: team domain knowledge is the context you add in your own project at the space level (aidlc/knowledge/, a sibling of the space's memory/, codekb/, and intents/), at runtime — it is not part of core/ and the framework never overwrites it. Everything else above is framework source you author in core/.

Naming rules and where they are enforced

Stage filename stems must equal frontmatter slug; aidlc-graph compile rejects stem mismatches, duplicate stage slugs, and multiple producers for any consumed artifact as hard errors. The duplicate-producer error names the producing stage files and one consumer; shared artifact names remain valid when no stage consumes them. Sensor filename/id checks are compile-time hard errors. Scope and agent duplicate declared names are loader errors that name both files; scope/agent filename-to-name drift is reported by /aidlc --doctor as an advisory so authors can rename the file or fix name.

The build model: author in core/, regenerate the harnesses

Everything a harness engineer authors lives in core/ — the hand-authored, harness-neutral source of truth (stages under core/aidlc-common/stages/, agents under core/agents/, scopes, rules, sensors, knowledge, tools, hooks). The per-harness dist/<harness>/ trees used for source development (dist/claude/.claude/, dist/kiro/.kiro/, dist/kiro-ide/.kiro/, dist/codex/, dist/cursor/, dist/opencode/, and dist/copilot/) are generated from core/ plus a thin harness/<name>/ surface. They are ignored local outputs, never committed or hand-edited. The loop is always:

# 1. edit the source in core/ (never dist/)
$EDITOR core/aidlc-common/stages/inception/my-stage.md

# 2. regenerate both channels for every harness from core/ + harness/
bun scripts/package.ts

# 3. prove deterministic generation (the CI guard)
bun scripts/package.ts --check

Commit the authored core/ or harness/ edit, not the generated roots. --check builds all copy, native, and plugin projections twice in independent temporary roots and byte-compares them. When a recipe in the chapters below says to run aidlc engine graph compile (or another tool), the installed command resolves that tool against the project's active harness tree. Generated copy-channel prose uses the Bun dispatcher and native prose uses aidlc; authors use the channel-neutral route. It is not where you author. You author in core/; the dispatcher runs tools against the installed projection. That split between authored source and generated runtime is the one to keep straight throughout this guide. For the full build contract see Porting to a New Harness and the Developer Reference's Architecture § Source vs distribution.

When you cross into the Developer Reference

Reach for the Developer Reference when your change is to the framework's code rather than its data:

• The orchestrator's routing or state machine (Orchestrator, State Machine) — for the normative engine/conductor/directive/runner/scope-shape/swarm contract, see The Skill System
• A hook or a CLI tool (Hooks and Tools)
• The stage-graph compile pipeline or the audit event taxonomy
• The test suite (Testing)

Adding a stage or an agent touches the workflow graph but does not change the code that reads it — that's why it lives here. Changing how the graph is compiled, or adding a new audit event, is a code change — that lives there.

How this guide is organized

Read it in order the first time:

1. Anatomy of a Stage — the stage file format: frontmatter contract, the three-compartment body, how the graph compiles. The single most important thing to understand before changing anything.
2. Adding a Stage — end-to-end: author the file, wire the dependency edges, compile, watch it appear in a scope.
3. Adding an Agent — author a persona and bind it to the stages it leads or supports.
4. Scopes — define and tune the scope-to-stage mapping.
5. Rules and the Learning Loop — author rules across the layer chain, and let the loop promote corrections into rules.
6. Sensors — author a deterministic check and bind it to stages.
7. Team Knowledge — give agents your domain context.
8. Construction and the Swarm — set the team's Construction autonomy posture in the rule layer, and shape what the per-Unit Bolts in an autonomous swarm can run in parallel through units-generation.
9. Porting to a New Harness — add another CLI harness with one harness/<name>/ directory and a manifest row, no core/ edits: the manifest contract, the hook adapter, and emit.ts.
10. Authoring a Plugin — package a reusable, optional AIDLC plugin in plugins/<name>/: new stages/agents/scopes/ sensors/doctor checks + additive contributions to existing core stages, emitted as a real host plugin per harness. Design in the Developer Reference's single chapter (18 mechanism).

Next

Start with Anatomy of a Stage — the format every other change builds on.