The Agentic Development System

A map of composable patterns, primitives, and principles for building with Claude Code — from CLI pipelines and web-scale Conductors to meta-artifacts and self-improving domain experts. These are not the only models. They are the ones that have proven themselves, and they constantly evolve.

AI Developer Workflows — The Building Blocks of Agentic Engineering

The Agentic Development System

Start here

Three separate systems. Mixing them up produces the wrong artifacts in the wrong places.

Codebase work Does engineering work on a product codebase. Plans bugs, features, chores. Implements, commits, opens PRs.

Product repos The application code. Phoenix, Portal, Karl. This is where output ships.

Agentic layer building Builds and maintains the infrastructure that makes codebase work better. Generates agents, commands, skills, expertise files.

production-factory The command center. Never holds product code.

Custom programmatic agents SDK-level agents deployed out-of-loop as backend services, data streamers, terminal UIs, or UI backends.

Product repos / deployed services Deployed alongside product code or as standalone services.

The progression is a path, not a menu: better agents → more agents → custom agents. You don't jump to System 3. You exhaust what out-of-the-box Claude Code can do first. System 2 is what makes System 1 compound over time.

How you interact with it

Three mediums of interaction. The same building blocks apply across all three.

Medium 1 — Out-of-loop

GitHub Issues + Webhooks + Mac Mini

Open an issue with a workflow command. A persistent server receives the webhook and runs the full pipeline — plan, build, commit, PR — as a detached process. Two touchpoints: create the issue, review the PR. Parallelization is free.

Medium 2 — Orchestrated

Frontend Web UI + Orchestration + Multi-Agents

A Conductor Agent coordinates named worker agents via management tools. Every event streams live. State persists in a database. Choose this when you need to see what agents are doing, intervene mid-run, or work across sessions.

Medium 3 — In-loop

Claude Code Interactive

Terminal or IDE. You are present. /slash-commands trigger agents and workflows directly. You guide, approve, and course-correct. This is where templates are built and proven — what earns trust here becomes the next headless pipeline.

The core loop

Every artifact exists to close one of three steps.

Act→Learn→Reuse

An agent that acts but never learns starts from zero every run. A mental model that's never maintained drifts into misinformation. The loop only compounds when all three steps are wired together.


Meta prompt	A prompt that builds other prompts
Template meta prompt	Builds prompts with a specific, repeatable structure
Self-improving template meta prompt	An agent expert. Updates itself or a related file with new information after acting. The expertise.yaml is the related file. The self-improve command is the meta prompt doing the updating.

The concrete example

What actually happens when you open that issue.

Issue #31 — "Document ADW directory" — body: /chore

Step 1 — Trigger

Webhook fires

GitHub POSTs to yourmac.local:8001/gh-webhook. FastAPI responds in <10s. Spawns adw_plan_build.py 31 in background.

Step 2 — Classify

Issue class detected

Claude reads issue body, extracts /chore. Selects chore workflow. Generates ADW ID: 45635fc8.

Step 3 — Plan

chore.md + issue title → plan

Spawns fresh Claude agent. chore.md is the meta prompt, issue title is the high-level prompt. Agent reads codebase, writes plan to specs/.

Step 4 — Build

implement.md + plan path → code

Spawns second fresh agent. Receives plan file path. Reads plan, writes code, commits. Plan is the prompt — no additional instructions.

Step 5 — PR

Pull request opened

Branch chore-31-45635fc8-document-adw-directory → PR opened against main. Comment posted to original issue.

org/repo · Issue #31

Document ADW directory

opened by vilovieta · no assignees

Description of the ADW directory and its modules.

/chore

BOT

[ADW-BOT] just now

Starting ADW workflow · ID: 45635fc8

Classifying issue as chore

BOT

[ADW-BOT] 42s

Plan created: specs/adw-documentation-plan.md

Implementing solution...

BOT

[ADW-BOT] 2m 18s

Solution implemented.

PR opened → #32 Document ADW directory

You opened one issue, wrote one word, received a PR. Two touchpoints: create the issue, review the result.

adw_plan_build.py — running headlessly on Mac Mini

$claude-p"$(cat .claude/commands/chore.md) Document ADW directory"

--output-formatstream--dangerously-skip-permissions

--modelclaude-sonnet-4-20250514

agents/45635fc8/plan/output.jsonl

# Phase 1 complete. Extracting plan path from JSONL...

plan_path = "specs/adw-documentation-plan.md"

$claude-p"$(cat .claude/commands/implement.md) specs/adw-documentation-plan.md"

--output-formatstream--dangerously-skip-permissions

agents/45635fc8/build/output.jsonl

# Phase 2 complete. Opening PR...

Two claude -p invocations. Each is a fresh agent. Each runs headlessly. The orchestrator is just Python reading JSONL and chaining phases.

The Trigger is the bottleneck

The most common failure: good Plan, good Implement — no Trigger. The engineer manually starts each run. The agentic layer exists but the out-loop mechanism doesn't. Without it, you have L0 with better tools — not L1.

Parallelization is free at L1+

Each Execute fires as a detached process in an isolated worktree. Five GitHub issues → five parallel pipelines. N pipelines = 1 Trigger setup, not N × engineer time.

The insight

The GitHub issue flow reveals why templates exist.

Every step of the ADW maps to a concept. These are the WHY behind each piece.

Issue title = high-level prompt

"Document ADW directory" — one sentence, void of implementation details. Gives the agent maximum freedom to interpret requirements using its domain knowledge. You said what you wanted, not how to do it.

/chore = selects the meta prompt

chore.md is a meta prompt — a reusable prompt that, given a high-level input, generates a full implementation plan. It encodes: how to search the codebase, what a chore plan looks like, what validation commands to include.

chore.md + title → specs/plan.md

The meta prompt receives the high-level prompt and produces a plan file. Not documentation — the instruction set for the next agent. Relevant files, step-by-step tasks, validation commands. Everything the build agent needs to act without asking anything.

implement.md + plan path = higher-order prompt

implement.md is a higher-order prompt (HOP) — it receives another prompt as its input. The plan file path is the argument. The plan IS the agent's instructions. Intelligence goes in the plan, not the executor's prompt. The builder is intentionally minimal — 12 lines.

Fresh agent per phase = programmable isolation

The planner and builder are separate fresh agents. Each phase is a complete standalone prompt: no conversational history, no prior context required. This is what makes the ADW runnable off-device — each phase is fully self-contained. Isolation is what enables programmatic automation.

The ADW isn't magic. It's four concepts chained together: high-level prompt → meta prompt → plan → HOP. Every piece of the system either builds these chains or makes them more reliable.

Foundations

Four prompt primitives. Every prompt in the system is one of these.

Primitive 1

High-level prompt

States desired outcome, not steps. Void of implementation details. Gives agent maximum freedom.

Example: "replace all server print statements with proper logging"

Primitive 2

Meta prompt

A reusable prompt that generates other prompts. A command .md file IS a meta prompt.

Example: chore.md — produces a full plan

Primitive 3

Template

A meta prompt with a fixed, reusable structure. Encodes domain-specific practices for a class of work.

Example: feature template with relevant_files

Primitive 4

Higher-order prompt

Receives another prompt as input. The plan file IS the instruction set.

Example: implement.md $1 (path to plan)

Plans are prompts scaled up

"Plans are prompts scaled up. The plan is the prompt. Great planning is great prompting." — Push intelligence into the plan document, not the executor's prompt. The minimal Builder principle — 12-line user prompt — is this principle made concrete. Every plan's validation_commands section contains the exact commands to run at completion. The executor runs them before marking done.

Autonomy spectrum

In-loop → Out-of-loop → Zero-Touch. The progression is always supervised first.

Plan → Implement → Trigger → Execute → Review. Every workflow sits somewhere on this spectrum.

In-Loop — engineer present at every step

You type /chore in your terminal. You watch the agent plan. You guide when it drifts. You commit the result. Every phase requires your presence. Powerful, but throughput is bounded by attention. Parallelization is impossible.

Out-Loop ( PITER) — 2 touchpoints: initiate + review

Open a GitHub issue. The Trigger detects it. Execute runs the full pipeline as a detached process. You return to review the PR. Two touchpoints: create, review. Everything between is autonomous. This is the concrete example in this guide.

ZTE — Zero-Touch Engineering, the asymptote

Trigger fires automatically (cron detects eligible issues). Automated review gates the merge. ZTE is not the default state — it's what you build toward after the pipeline has proven reliable enough to trust without supervision. Do not skip stages.

Template specialization

Start generic. Specialize over time. Each level requires the previous to be working.

Level	What it is
1. Generic templates	chore.md, bug.md, feature.md. Work across any codebase. Start here. One hour improving a template pays off on every future invocation.
2. Specialized templates	Templates for recurring problem classes. Encodes how your codebase solves specific problems. `chore-db-migration.md` knows your migration system.
3. Domain templates	Know your architecture. The frontend feature template knows your component structure, routing, state patterns. Produced by reading real codebase.
4. Meta-templates	Generate self-improving domain experts. The template builds the expert that maintains itself. Level 4 is where the system builds the system.

The discipline

"Build the system that builds the system." One hour improving a template pays off on every future invocation. One hour directly writing a plan pays off once.

Architecture is agent performance

Every structural decision is an agent performance decision.

fails the test

utils.py

Unknown without opening. A cold agent reads the name, learns nothing, opens the file, burns context tracing imports to understand scope. At thousands of invocations per month, this is a compounding tax.

passes the test

adw_plan.py

Planning phase script. A cold agent reads the name, knows exactly what it does, can act without opening it. Flat, Named, Obvious. The orientation test: a cold agent should understand what each file does from its name alone.

Workflow composition

Five levels. Match to the cost of getting it wrong.

Single phaseclaude -p "$(cat plan.md) [task]"

One call. No chaining. Fast but unverified — you are still the orchestrator. No artifact contract, no validation.

atomic tasks, exploration

Plan + Buildadw_plan_build.py [issue]

Two fresh agents. Planner produces specs/plan.md. Builder receives plan path (HOP). Plan file is the artifact contract.

chores, bugs, defined features

Plan + Build + Reviewadw_plan_build_review.py

Three agents. Review reads original spec + actual diff — not the builder's description. PASS or FAIL with evidence.

user-facing features, API changes

Full SDLCadw_sdlc.py [issue]

All five phases chained. Plan → Build → Test → Review → Document. Every output is an artifact input for the next phase.

new features, multi-session work

Product Spec Pipeline/product-spec → /planning-products

Before any code: Vision → MRD → BRD → PRD → SDD → TDD. The TDD §2 File Manifest drives task decomposition. Each task gets a builder+validator pair with filesExpected contracts.

major features, architectural changes

/test-feature — the orthogonal quality layer

/test-feature is not a phase in the pipeline — it's a quality audit deployable after any workflow. Traces the feature end-to-end, inventories existing tests, identifies gaps, writes missing tests, runs the suite, does visual QA. Run it after build, after review, or against features that have accumulated test debt.

What each artifact does

Six artifacts. One discipline each.

PrimitiveTask

Not a to-do item. A formal contract: filesExpected declares what the builder will touch. Stop hook verifies disk state at completion. Phantom edit s are impossible.

Rule: every builder task needs at least one filesExpected entry. Without it the hook has nothing to verify.

PrimitiveCommand / Meta-command

A .md file with Variables + Instructions + Workflow + Report. Usable as /slash-command interactively and as claude -p "$(cat cmd.md) ..." programmatically. Write once, runs forever, works both modes.

Rule: every repeatable engineering action is a candidate. If you typed the same instructions twice, extract them.

PrimitiveSkill

One reusable behavioral rule. 30–60 lines. Declared in agent frontmatter. Any rule that applies to ≥2 agents becomes a skill. Progressive disclosure: metadata always loaded, body only when triggered.

Rule: one skill = one capability. If it's over 100 lines, it's doing two things.

PrimitiveExpertise.yaml

Dense YAML, 10 sections, 1000-line cap. Not documentation — a mental model. Verified claims only. No tildes. Every file path and line number checked against real code.

Rule: a tilde (~) means unverified. An expertise.yaml with tildes is worse than none — it misleads with false confidence.

PatternBuilder-Validator Pair

Every file-touching task gets two agents: builder writes code, validator audits against the TDD — not the builder's summary. No agent certifies its own output. The selfAudit field is the validator's targeted attack map.

Rule: a validator that reads the builder's summary and agrees is not verification — it's corroboration. The spec is ground truth.

MethodADW Script

Python orchestrator. Calls claude -p per phase, captures JSONL output, extracts artifacts, chains to next phase. The ADW is just Python reading JSONL and spawning CLIs. No magic.

Rule: orchestrators are dumb. Intelligence lives in templates. A smarter orchestrator is the wrong direction — smarter templates compound.

Artifact formats

The classic agentic prompt. Every prompt in the system uses this five-section structure.

Classic prompt format — command, user prompt, system prompt

# Title

## Variables
DYNAMIC_VAR: $1          ← injected at invocation time
STATIC_VAR:  fixed/path  ← fixed values known at write time

## Instructions
- Rule 1
- Rule 2

## Workflow
1. Step one
2. Step two

## Report
What to return and in what format.
# The Report section is the machine-readable interface to the next stage.
# When reports are file paths, they feed the next agent.
# When reports are JSON, the orchestrator parses them to continue or abort.

Agent format

---
name: kebab-case-name
description: WHEN to delegate, not what it does
tools: Read, Write, Grep
model: sonnet
color: cyan
---

# Purpose
## Instructions
## Workflow
## Report

Skill format

---
name: gerund-form-name
description: Third-person. WHAT and WHEN.
allowed-tools: Read, Grep
---

# Skill Name
## Instructions
## Examples

# Name: gerund form — reviewing-code not code-reviewer
# Body: under 500 lines

The generator layer

Meta-agentics: artifacts that generate other artifacts.

Three levels of the meta-creation hierarchy. Each requires the previous.

Meta-agentics — act only, do not learn

What they are: Artifacts that generate other artifacts — new agent .md files, new command files, new skill directories, new expertise.yaml. They act — they do not learn. Nothing updates automatically after running. They are velocity tools, not expertise compounders.

Key design: The meta-agent doesn't bake the template in. It reads a companion skill file at runtime — the knowledge lives in the skill loaded on demand. Agent lean; skill carries depth.

Agent experts — act + learn + reuse

What they are: A three-file system — expertise.yaml (the mental model), question.md (the Reuse command), self-improve.md (the Learn command). The Act→Learn→Reuse loop applied to domain knowledge.

Why they exist: A generic agent searching for a function spends 3 minutes tracing 6 files. A domain expert reads that fact in 2 seconds from expertise.yaml. After 10 self-improve runs, the expert knows things no generic agent will discover in a single session.

Meta expert — generates other agent experts

What it is: An agent expert whose domain is "building other agent experts." Its expertise.yaml knows the self-improve prompt structure, the 10 YAML sections, what good seeding looks like.

Why it's the ceiling: When you add a new domain, the meta-expert generates the self-improve prompt for it. You are no longer writing prompts — you are running a prompt that writes prompts. This is what "build the system that builds the system" means in concrete terms.

The Scout Pattern

Scout (read-only) → Generator (write artifact) → Self-Improve (maintain artifact). The scout explores the codebase and produces verified file+line citations — it cannot write files. The generator acts on scout findings. The self-improve maintains the result over time. Multi-LLM variant: multiple competing models search in parallel, deduplicate overlapping ranges, feed merged results into the next phase.

Orchestration

One agent, one prompt, one purpose.

Each agent has one job, one context window, one output artifact. A planner that also builds is a bottleneck. A validator that reads the builder's summary is corroboration, not verification. Collapsing roles creates context pollution and ambiguous outputs.

ADW method

Subprocess + env vars

Fresh agents per phase via claude -p. Context handed off through artifact files — plan paths, JSONL outputs. Agents are ephemeral, script-duration. Right for CI pipelines, local automation, AFK batch workflows.

Orchestration method

Conductor + persistent workers via MCP

A single Conductor coordinates named worker agents via management tools. Agents persist across commands, remember sessions, stream events live. Right for interactive, inspectable, multi-session systems with a browser UI.

The SDLC phases — five distinct agent jobs

Phase 01

Plan

What are we building? Complete instruction set before any code is touched.

→ specs/plan.md

Phase 02

Build

Did we make it real? Read the plan, implement, run validation commands.

→ committed code

Phase 03

Test

Does it work? Edge cases, failure modes, inputs it was built for.

→ test suite

Phase 04

Review

Is what we built what we asked for? Prove it against the spec.

→ review-report.md

Phase 05

Document

How does it work? For the next agent, session, engineer.

→ CLAUDE.md, expertise.yaml

Collapsing two phases into one agent creates context pollution and ambiguous outputs. These are distinct agent jobs — each with a different role, context, and output artifact.

Enforcement

Agents can self-certify. Hooks cannot be reasoned around.

the problem

The builder marks itself done.

Without enforcement, a builder agent can write task_update completed without touching the declared files. The orchestrator continues. The PR contains nothing. Self-certification is not verification.

the solution

The Stop hook is the judge.

The planner declares filesExpected when creating the task. At completion, a Stop hook checks disk state against the declaration. If the files weren't touched, the agent is blocked from finishing.

Three-layer pipeline

Skills — Orchestrators

/product-spec, /planning-products. Call task_create.py once per file group. They declare what builders will touch. They never enforce.

↓

CLI Tools — State Mutators

task_create.py, task_update.py, task_get.py. Read and write task-list.json. Every agent interacts with the task system only through these tools. Never edit task-list.json directly.

↓

Hooks — Enforcers

Fire on tool events. Cannot be overridden by agent reasoning. A system-level fix for a class of failure — not one issue. Adding more prompt instructions is not enforcement. A hook is.

Hook	Fires on	Blocks
product-spec-stop-verify.sh	Stop	Phantom completion. Builder cannot mark done until every declared file exists on disk with required symbols present.
context-gate.sh	Write / Edit	Uninformed writes. Builder cannot write code until it has Read every file in `requiredReads`.
task-description-quality.sh	task_create	Underbriefed tasks. Descriptions under 800 characters are rejected. A thin description is an incomplete brief.
build-summary-gate.sh	Stop	Missing deliverable. Builder cannot stop until `build-summary.md` exists in `agent-outputs/`.

Every hook encodes a class fix. "Block phantom completion" fires on every task, forever. You write the hook once — it enforces on every future run without your presence.

Robustness

Most workflows aren't robust enough. Here's the difference.

thin workflow

The agent says it's done. You take its word for it.

✗

No input artifact. Prompt typed in terminal. Nothing to inspect, version, or chain from. Next session starts from scratch.

✗

No output artifact. Code changed, but no build-summary.md, no plan file. The next agent doesn't know what happened.

✗

No validation step. Workflow ends when agent stops responding. Whether the code works is an open question.

✗

No state written. Nothing chainable. Nothing resumable. If the process dies halfway, you restart from zero.

✗

No hook enforcement. Agent self-certifies. If it claims files were modified, you trust it. Phantom edits are invisible.

robust workflow

The hook is the judge. The artifact is the evidence.

✓

Defined input artifact. The issue title, the spec file, the task record via task_get.py. Starting point is inspectable and versioned.

✓

Named output artifact.specs/plan.md, build-summary.md, review-report.md. The next phase has something to read.

✓

Embedded validation. The plan's validation_commands run at build completion. Agent reports results before marking done.

✓

State written on completion. ADW ID, branch name, plan path — all in adw_state.json. Chainable. Resumable. Auditable.

✓

Hook enforcement.filesExpected checked against disk state at Stop. The agent cannot self-certify. The hook is the judge.

The diagnostic question

"If the agent lied about finishing, how would you know?"

If the answer is "I wouldn't" — that's where a hook goes. The robustness of a workflow is exactly the strength of its answer to that question.

The goal isn't maximum phases for every task. It's matching the workflow's robustness to the cost of failure. A thin workflow on a throwaway script is fine. A thin workflow on a billing change is not.

Context & memory

Three mechanisms. Different scopes, different purposes.

These serve different purposes and cannot be substituted for each other.

@file references — task-level injection

Direct file injection at command execution time. Surgical. The agent receives specific files as context for the current task. Right for: providing the plan file, the spec, the relevant module. Does not persist across sessions.

expertise.yaml — domain-level memory

The expert reads the expertise file before acting. A 300-line expertise file replaces 30 minutes of codebase exploration. Prescriptive, domain-level. Updated by self-improve after significant changes. Persists indefinitely.

Context bundle — session-level replay

A session replay log built by a hook. Fires on PostToolUse (Read, Write) and UserPromptSubmit, writing each event to JSONL. /load_bundle reads it back, deduplicates, re-reads files — restoring the prior agent's context as efficiently as possible. Historical, session-level.

Plan-as-prompt

The plan file IS the next agent's instructions — not documentation of what happened. A plan that can be read cold by an agent with no prior context is a good plan.

Dynamic variable injection

{{SUBAGENT_MAP}} is filled at session boot from a live registry. Static variables belong in the system prompt. Dynamic variables belong in user prompts. Putting dynamic vars in the system prompt invalidates cache on every call.

Self-improvement

The Act → Learn → Reuse loop. The expert system — four files.

.claude/commands/experts/<domain>/

expertise.yaml          ← mental model (the load-bearing artifact)
question.md             ← read-only Q&A with file+line citations (Reuse)
self-improve.md         ← validate + update the expertise file (Learn)
plan-build-improve.md   ← full Act→Learn→Reuse loop in one invocation

wrong approach

Edit expertise.yaml directly.

Direct edits bypass the validation loop and create claims that are never checked against the codebase. The stale fact propagates silently. The expert misleads with false confidence.

correct approach

Update the self-improve prompt. Then rerun.

If the expertise is wrong, the self-improve instructions are wrong. Fix those, rerun. The agent reads the codebase, verifies claims, updates the file. Every claim backed by actual code read.

Domain	Why build an expert
Database / Schema	Schema decisions cascade. Every wrong migration is production data at risk.
Billing	Revenue risk. One wrong webhook handler is expensive.
Auth / Permissions	Wrong change opens a security hole silently.
WebSockets / Real-time	Complex event flows a generic agent won't trace correctly in one session.
Anywhere generic agents make the same class of mistake repeatedly	The expert learns what the generic agent has to rediscover every time.

Don't build one for domains you don't yet have your own mental model of — you can't evaluate whether the expert is performing well.

The compound effect

Mental models persist across sessions. This is where the leverage lives.

A generic agent searching for a key function spends 3 minutes tracing through 6 files. A domain expert reads that fact in 2 seconds from expertise.yaml and gets straight to the task. The compounding happens through self-improve. Every time a significant change ships, the expert runs against the diff. Claims that are now stale get corrected. New patterns get added. After 10 iterations, the expert knows things about the domain that no generic agent will ever discover in a single session.

The discipline

Do not work on the application layer. Work on the agentic layer — the system that builds the system. Every unverified tilde, every missing section, every direct edit to expertise.yaml — these are all the same mistake. They are spending time on the output instead of the system that produces the output.

ADW workflows — the full command menu

Eleven composable pipeline commands. Every ADW run has a named workflow.

—

Plan only/adw_plan_iso

Runs the planning phase. Produces specs/plan.md. Stops before any code is written. Right for large features where you want to review the plan before committing to build.

planning, spec review

—

Plan → Build/adw_plan_build_iso

Two phases. Plan produces the spec; build implements it. The baseline pipeline. Most chores and bugs run at this level.

chores, bugs, defined features

—

Plan → Build → Test/adw_plan_build_test_iso

Three phases. Test agent writes and runs the test suite after build. Returns a coverage report as the next phase's input.

features that need test coverage

—

Plan → Build → Test → Review/adw_plan_build_test_review_iso

Four phases. Review agent reads original spec + actual code diff — not the builder's description. Reports PASS or FAIL with line-level evidence. JSON gate: success: false with blocker severity aborts the pipeline.

user-facing features, API changes

—

Full SDLC + auto-merge/adw_sdlc_ZTE_iso

Complete SDLC (Plan → Build → Test → Review → Document) + auto-merge to production. ZTE must be uppercase to prevent accidental execution — the classifier enforces this. Lowercase zte runs the non-merge variant.

ZTE only — trusted pipeline, proven templates

Individual phases can also run standalone: /adw_build_iso, /adw_test_iso, /adw_review_iso, /adw_document_iso, /adw_ship_iso. Each requires an adw_id to locate the existing worktree.

_iso = isolated worktree

Every ADW script runs in its own git worktree at trees/{adw_id}/. Each run gets its own branch, directory, and ports. Multiple workflows run in parallel without conflicting. When done, purge_tree.sh {adw_id} cleans up.

Phases communicate via return values

Planner → returns path to specs/issue-{N}-adw-{id}-sdlc_planner-{name}.md

Builder → returns git diff output

Reviewer → returns JSON: {success, review_summary, review_issues[], screenshots[]}

Document → returns path to app_docs/feature-{id}-{name}.md

ADW KPI tracking — the system measures itself

track_agentic_kpis.md measures per run: Attempts (Plan/Patch invocations needed — ≤2 = good), Plan size (lines in spec file), Diff size (lines changed), Current streak (consecutive ADWs with ≤2 attempts), Average presence (attempts across all runs). KPIs surface whether agents are getting it right on the first attempt or requiring repeated replanning.

task_create.py — the task contract

The planner declares. The builder executes. The hook verifies. Never the agent.

filesExpected — the enforcement contract

task_create.py \
  --task-id         "build-user-auth" \
  --description     "[800+ char description of exactly what to build]" \
  --files-expected  '{"path":"src/auth/session.ts","op":"create","symbolsRequired":["createSession","validateSession"]}' \
  --files-expected  '{"path":"src/routes/auth.ts","op":"modify","symbolsRequired":["authRouter"]}' \
  --required-reads  "planner-workflows/{PLAN}/AGENT_SYSTEM.md" \
  --required-reads  "{TDD_OUTPUT_PATH} §3" \
  --self-audit      '{"check":"session token never stored in localStorage","severity":"blocker"}'

filesExpected — three operations

op: "create" — file must exist on disk after build

op: "modify" — file must have been touched (mtime changed)

op: "delete" — file must no longer exist

symbolsRequired — each symbol must be present in the file

symbolsForbidden — each symbol must be absent (prevents anti-patterns)

requiredReads — context gating

Files the agent must Read before it can Write or Edit. The context-gate.sh hook intercepts every Write/Edit call and blocks until the read ledger matches. Context priming made mandatory — closes the gap between "the agent should read the TDD" and "the agent actually read the TDD."

TDD row → task_create.py — plan drives tasks

# TDD §2 File Manifest row:
NEW      src/auth/session.ts
# → becomes:
task_create.py --files-expected '{"path":"src/auth/session.ts","op":"create","symbolsRequired":["createSession"]}'

# TDD §2 row:
MODIFIED src/auth/session.ts (add validateSession)
# → becomes:
task_create.py --files-expected '{"path":"src/auth/session.ts","op":"modify","symbolsRequired":["validateSession"]}'

# TDD §2 row:
DELETED  src/auth/legacy.ts
# → becomes:
task_create.py --files-expected '{"path":"src/auth/legacy.ts","op":"delete"}'

Spec

/product-spec

Produces TDD with §2 File Manifest. Each row declares a file operation.

→ produces: TDD §2

Decompose

/planning-products

Reads TDD §2, calls task_create.py once per file group. Registers contracts.

→ produces: task-list.json

Execute

builder-product

Reads task via task_get.py. context-gate blocks Write/Edit until requiredReads done.

→ produces: committed code

Verify

Stop hook

Checks filesExpected against disk. symbolsRequired present. symbolsForbidden absent.

→ passes or blocks

Audit

validator-product

Reads build-summary.md + TDD §N. Runs selfAudit claims. Writes PASS or BLOCK.

→ produces: report.md

The presence KPI goal — zero human interventions per pipeline run — applies directly here. When the pipeline is correctly specified, the planner creates tasks, the builder executes, the hook verifies, and the validator audits without a human bridging any step.

Hook enforcement — how it actually works

A hook is a class fix. Not one issue. Every future invocation, forever.

Four hooks. Each encodes one class of failure that can never happen again.

product-spec-stop-verify.sh — fires on Stop

When a builder agent tries to stop, this hook checks every entry in filesExpected against disk state. If any declared file wasn't created, modified, or deleted as expected — or if any symbolsRequired is absent from the file — the agent is blocked from finishing. It cannot exit. It must fix the gap first. Self-certification is structurally impossible.

context-gate.sh — fires on Write / Edit

Every time an agent tries to write or edit a file, this hook checks whether every file in requiredReads appears in the session's read ledger. If the agent hasn't read the TDD section governing this phase, the Write/Edit is blocked. The agent must Read first. Context priming is not a suggestion — it is enforced at the tool level, not the prompt level.

task-description-quality.sh — fires on task_create

When the orchestrator calls task_create.py, this hook validates the description field. Descriptions under 800 characters are rejected. A thin description is an incomplete brief — the builder fills gaps with guesses. The hook turns "please write better descriptions" into a mechanical gate. Cannot create a task with an inadequate brief.

build-summary-gate.sh — fires on Stop

When a builder agent tries to stop, this hook checks whether build-summary.md exists in agent-outputs/. The agent cannot exit without producing a structured self-report. The build-summary is what the validator reads — without it, the validator has nothing to audit against. This enforces the output artifact discipline: no output artifact, no completion.

Hook function anatomy — PreToolUse vs Stop

# File-based hooks live in .claude/hooks/*.sh
# Inline hooks (for SDK agents) use HookMatcher in Python

# File-based hook fires on tool events:
# PreToolUse  — before tool runs (can block)
# PostToolUse — after tool runs (can react, can't un-run)
# Stop        — before agent exits (can block exit)
# SubagentStop — before a spawned subagent exits

# Hook returns 0 → allow. Returns non-zero → block with message.

# Inline SDK hook (HookMatcher):
hooks = {
    "PreToolUse": [\
        HookMatcher(matcher="Write", hooks=[check_required_reads]),\
        HookMatcher(hooks=[log_tool_usage]),  # no matcher = all tools\
    ],
}
# HookMatcher gates ALL tool calls including subagents.
# can_use_tool is the older API — do not use it (only gates main agent).

The orchestration system — in full

The Conductor coordinates. Workers execute. The Conductor never writes code.

Analyze

Understand intent

What does the user actually want? Decompose into which agents are needed.

→ decision: reuse or create?

Plan

list_agents()

Check for existing agents before creating. Reuse if suitable. Agents remember prior sessions.

→ or: create_agent()

Create

create_agent()

Spawn with template from SUBAGENT_MAP. Template handles system prompt, tools, model selection.

→ registered in DB

Dispatch

command_agent()

Send specific, complete instructions. Quality of dispatch = quality of result. Vague commands produce vague output.

→ fire-and-forget

Report

Synthesize

Collect results. check_agent_status() only if requested. Synthesize back to user.

→ to user

Fire-and-forget discipline: the Conductor dispatches and trusts the agents. Checking status too eagerly doesn't speed up agents — it burns context. Check only when the user asks or something appears wrong.

Tool	Signature	Purpose
create_agent	(name, system_prompt?, model?, subagent_template?)	Spawn a new worker. If `subagent_template` is set, the template provides system prompt, tools, model — `model` param can still override.
command_agent	(agent_name, command)	Send prompt to running agent. Agent retains prior session memory. Use `'ultrathink'` keyword to trigger extended thinking mode.
list_agents	()	All registered agents with status + metadata. Run before create_agent — reuse existing before spawning new.
check_agent_status	(name, tail_count=10, offset=0, verbose_logs=false)	`verbose_logs=false` → AI summaries. `verbose_logs=true` → raw event details. offset + tail_count = pagination for long histories.
interrupt_agent	(agent_name)	Send stop signal to running agent mid-execution. Use when the agent is going in the wrong direction.
delete_agent	(agent_name)	Terminate agent + clean up resources. Agents persist until explicitly deleted or session ends.
read_system_logs	(offset=0, limit=50, message_contains?, level?)	Returns newest logs first. level: DEBUG \| INFO \| WARNING \| ERROR. Use `message_contains` to filter noise.
report_cost	()	Orchestrator token usage, cost, session ID. Run this when user asks "what's your session ID?"

{{SUBAGENT_MAP}} — runtime template registry injection

# The Conductor's system prompt contains:
## Available Subagent Templates

{{SUBAGENT_MAP}}

# At session boot, OrchestratorService._load_system_prompt() resolves this:
# 1. Scans .claude/agents/*.md
# 2. Parses each file's frontmatter (name, description, tools, model, color)
# 3. Formats as: "- **{name}**: {description}"
# 4. Replaces {{SUBAGENT_MAP}} with the live registry

# Effect: Conductor calls create_agent(subagent_template="scout-report-suggest")
# without knowing the template's system prompt internals.
# Template handles system prompt, tools, model selection automatically.

# COMMAND_LEVEL_COMPACT_PERCENTAGE: 80%
# When a worker's context reaches 80%, Conductor proposes /compact to user.
# After /compact: agent retains system prompt + tools, clears conversation history.
# Never auto-compact — always confirm with user (history loss is destructive).

When to use Orchestration

Browser UI needed, multi-session persistence, interactive inspection of agent state, real-time event visibility, ability to intervene mid-run. Agents persist across commands. State in a real database. Choose when you need to watch and steer.

When to use ADW

CI pipelines, local automation, AFK batch workflows, GitHub issue triggers. Agents are ephemeral per phase. State in JSONL files. No UI needed. Choose when you want to walk away and return to a PR.

The expert system — bootstrapping a new domain

/new-expert creates the scaffold. /craft:expert seeds it. /self-improve maintains it.

one-shot collapse

new-expert does everything in one run.

Creates files AND reads the codebase AND seeds expertise AND validates — all in one agent invocation. Collapses creation, generation, and maintenance. Expertise claims mix verified reads with inferred structure. Hard to rerun correctly when stale.

three operations, three disciplines

Creation ≠ generation ≠ maintenance.

new-expert.md — creates directory structure and empty files only. No codebase reading.

craft:expert — scouts codebase, fills expertise.yaml from verified reads.

self-improve.md — maintains expertise after code changes.

The four files — and the discipline enforced by each one.

expertise.yaml — the load-bearing artifact

Dense YAML, 10 sections (overview, core_implementation, patterns, data_structures, configuration, key_operations, error_handling, testing, best_practices, known_issues), 1000-line cap. Not documentation — a mental model. Every claim backed by actual code read. No tildes. Every file path and line number verified. The known_issues section includes severity (Low / Medium / High), description, impact, workaround, and fix — because a known bug not in the mental model is a known bug the next agent will replicate.

question.md — read-only Q&A

Enforces read-only discipline explicitly in its Instructions: "This is a question-answering task only — DO NOT write, edit, or create any files." Reads expertise.yaml as the mental model, validates key claims against the actual codebase before answering, returns answers with file+line citations. The expert's Reuse interface — how you extract value without changing state.

self-improve.md — the Learn step

Optional git diff scope and focus-area targeting. Validates every claim against actual code. Fixes stale entries, adds new findings, removes what no longer exists. Enforces 1000-line cap. Validates YAML syntax. Returns a structured report: discrepancies found/fixed, line count before/after, added/updated/removed. Must include the statement "After searching, there may be nothing to do — this is perfectly acceptable." Without this, agents over-update when stability is the correct answer. The terminal state: "everything is accurate, nothing to update."

plan-build-improve.md — the full loop

One invocation = one complete Act→Learn→Reuse cycle: load expertise → plan with domain context → build → run pre-merge gate → self-improve based on the diff. The compound loop in a single command. After the build completes and passes, the expert automatically updates its mental model based on what changed. Every build tightens the domain knowledge.

Seeding protocol — from blank file to stable mental model

# Step 1: /new-expert creates the scaffold
# Creates: .claude/commands/experts/{domain}/
#          expertise.yaml (blank), question.md, self-improve.md, plan-build-improve.md
# Copies command files from a template domain, replaces all 'datahub' → '{domain}'

# Step 2: /craft:expert seeds expertise.yaml from codebase
# Scout reads all domain-scoped files, traces functions, verifies line numbers
# Fills every section from actual code reads — no inferred claims
# Returns: expertise.yaml with verified data, YAML syntax validated

# Step 3: /experts:{domain}:self-improve (rerun until stable)
# First few runs: finds new things, updates claims
# Terminal state: "everything is accurate, nothing to update" → expertise is seeded

# Step 4: /experts:{domain}:question — start using the expert
# Step 5: /experts:{domain}:plan-build-improve — run the full loop
# After every significant change: rerun self-improve against the diff

The interface rule

Never edit expertise.yaml directly. Update the self-improve prompt instead. If the expertise is wrong, the self-improve instructions are wrong. Fix those, rerun. Direct edits bypass the validation loop and create claims that are never checked against the codebase.

Command routing — three-level nesting

Files at .claude/commands/experts/{domain}/{command}.md register as /experts:{domain}:{command}. This is a Claude Code capability — verified working. The nesting is intentional: domain scopes the expert, command scopes the operation.

Where to go when the concept isn't enough.

→\ how-to-enforce-plan-execution\ \ Deep dive on tasks, filesExpected contracts, Stop hook enforcement, builder-validator pair. →\ how-to-build-agent-experts\ \ The Act→Learn→Reuse loop in full. When to build a domain expert vs. generic agent, seeding, the four-file system. →\ how-to-build-metaagents\ \ Routing, delegation, Agent Delegation Hierarchy (subprocess depth-2) and the Web Conductor pattern (MCP, persistent sessions). →\ how-to-build-metaskills\ \ Composition vs. spawning, skill reuse, progressive disclosure in skill files. →\ how-to-use-hooks\ \ Hook event selection. PreToolUse vs. PostToolUse vs. Stop vs. SubagentStop. →\ how-to-use-adaptive-templates\ \ Conditional plan sections by task type. Templates that produce exactly what the task needs.