Dev Fleet

Dev Fleet Orchestrator

This skill tells the main session (the orchestrator — you) how to drive the development agents as a pipeline. The agents live in agents/; the main session dispatches each by name via the Agent tool, reads its JSON, and gates on the result.

Two ways to run the pipeline — pick by how much determinism you need:

• This skill (in-the-loop). You follow these steps and invoke each agent explicitly. A

skill is instructions you follow, not a mechanical orchestrator — so it's only as reliable as your adherence. Don't lean on auto-delegation for a stage you care about; name the agent. (A human driving Claude Code can force a stage with an @agent-… mention.)

• The dev-story Workflow (hands-off, deterministic). For a guaranteed

plan→build→verify→cohere→review→full-suite run, dispatch it via the Workflow tool with the absolute scriptPath ~/.claude/skills/dev-fleet/dev-story.workflow.js (a relative path won't resolve from your repo). It moves orchestration into code and hands back a ready-to-merge branch; it mirrors the two-point fact discipline and gates coherence on change size automatically (coherence: auto|always|never). See Running for scale.

See docs/agent-fleet-architecture.md for the why.

The pipeline

plan & scope ─▶ verify load-bearing facts ─▶ code-builder ─▶ fact-verifier (gate) ─▶ coherence-check (gate, if complex) ─▶ code-reviewer ─▶ full-suite gate ─▶ [you decide] ─▶ commit-pr
 (explore · calibrate)        (up front)                       (did it hold up?)

Each agent returns JSON (see its definition). You read that JSON and decide whether to proceed, loop, or stop. You stay in the loop between stages — this is a skill, not an unattended workflow.

Facts get verified at two points — load-bearing facts before the build (stage 1, so the builder writes against evidence) and the finished change's claims after (stage 3, to catch drift/assumption/hallucination). Same fact-verifier agent, two jobs (detailed in those stages).

Loop-back semantics (what a failing gate does)

Every gate loops back to code-builder carrying the specific problem — never a vague "try again". Re-run the gate after the fix (bound the loop to ~2 rounds, then hand the residue to a human). Do the fix work on the builder's branch and merge once — see Patterns: reconcile in the worktree.

Resume the same builder — don't spawn a fresh one blind. To continue the original builder in its worktree, use SendMessage to that agent (it still knows its branch and worktree_path). A new Agent call starts a fresh agent with no memory of the worktree path — if you must start fresh (e.g. the original is gone), you MUST pass worktree_path and branch explicitly in the prompt, or the fix lands in the wrong tree. Reaching for a fresh Agent when you meant to resume is an easy slip; check which one you're calling. (The dev-story workflow sidesteps this — every fix stage re-passes the worktree path as data — but the in-the-loop path is on you.)

| Gate result | Loop back to builder with | |---|---| | fact-verifier REFUTED | the correct value to use | | coherence fail | the specific structural mismatch (+ its loop_back_target) | | code-reviewer blocking | the specific bug + suggested fix | | full-suite RED | the failing test name(s) |

0. Plan & scope — explore, calibrate, surface the facts

For anything beyond a trivial edit, agree the approach before dispatching a builder — but scoping is more than writing a brief. It's where you explore the real code/data, calibrate any rule the change depends on, and surface the facts it will rest on. A builder with a fuzzy brief produces fuzzy code. The plan is the pipeline's weakest link — a gap written into the plan survives every gate that isn't looking for it. Four disciplines keep the plan honest:

• Audit before you write the tasks. Before writing a single step, grep/read the last few

examples of the same kind of change (recent migrations, the tables/handlers/modules of the same shape). Note in the plan header that you audited and what you found. A plan written from spec

• memory instead of an audit skips the established pattern the audit would have surfaced — that's

a shortcut that costs a full review turnaround. (Real example: reading the two most recent SQL migrations would have shown the RLS-plus-GRANT pattern was universal for the tables in scope; the plan was written without that read and shipped a security gap the reviewer then caught.)

• Mirror the pattern; cite it with file:line. For any task touching schema, security, or an

established convention, the plan must say "mirror the pattern at ``", not just describe the goal. The builder copies a real example, not a remembered one.

• Write positives, not just negatives. For every prohibition ("do NOT add RLS to

schema_postgres.sql") write the matching positive for every parallel case ("DO add RLS + GRANT to the other two schemas, mirroring entities/memory_entities"). A negative-only requirement tells the builder what to skip and nothing about what to do — it implements only what's asked and the gap ships. This is the recurring plan failure; treat a lone "do NOT" as unfinished.

• Resolve inconsistencies now, don't flag-and-defer. If you notice a count that doesn't match

its list or a name used unevenly, fix it in the plan before dispatching. A "note: 15 vs 16, keep honest" left in the plan is a noticed-but-unfixed bug — you already did the hard part (spotting it); finish it.

• Calibrate a detector/gate against real data before you freeze the builder brief. A gate's

predicate ("X is a violation") is a domain claim, and the domain usually has exceptions the plan doesn't know yet. Hand the builder a naive rule and the exceptions surface as false positives after merge — expensive to unwind. Run the naive rule against real data first (a throwaway script or one inline pass), triage hits into real-vs-benign, and hand the builder a predicate that already encodes the exclusions. (Real example: a naive "catalog var absent from pinned module = error" gate threw 6 hits, 5 benign — calibration moved that discovery to the front.)

• Surface the load-bearing facts the change will depend on — an API/module input surface, a

version's behaviour, a resource/schema shape. These feed stage 1.

• Flag combinatorial features for pairwise design. If behaviour turns on ≥3 interacting

parameters, say so — the builder designs the case matrix with pairwise/PICT, not ad-hoc cases (TDD by default; see code-builder's test-first guidance).

• Capture out-of-scope / deferred work (what you're leaving to a companion change) and forward

it to the coherence and review stages — otherwise they'll treat a deliberate deferral as a bug.

1. Verify load-bearing facts — up front, before building

When the change's correctness rests on external facts you don't already hold, gather and verify them before the builder starts; it should write against verified facts, not offline guesses it can't check. Dispatch fact-verifier on the load-bearing facts from stage 0, using its sources — MS Learn / official docs, source-snapshot, c7search/Context7, schema dumps.

• Front-loading surfaces real findings early — "this pinned version dropped that input" shows up

now, not in reconcile after the build.

• The verified facts (and any corrected values) become the builder's oracle — pass them as

data into stage 2.

• External facts only — don't over-fire. Verify things that need a source outside this repo:

versions, API/CLI shapes, resource IDs, pricing, "library X supports Y", "the spec says Z". Internal-consistency questions ("does this new table follow our own RLS pattern") are not fact-verifier's job — they're audit (stage 0) and coherence (stage 4) concerns, and firing the verifier at them burns a turnaround for a verdict that can't change the recommendation. For a schema/SQL change against an internally-consistent codebase with no external claim, the up-front fact pass is often marginal; the builder's own deviations/open_questions will surface a gap faster. Fire it when a real external claim is load-bearing, not reflexively.

• Skip only when the change rests on nothing external (e.g. a pure refactor with green tests).

2. code-builder — implement

Dispatch with: the agreed plan, the target files/area, the verified facts from stage 1, and a calibrated predicate if a gate is involved. Tell it to work in a worktree/branch.

• If it returns missing_facts, do not push it to guess. Resolve them with the stage-1 tools,

then re-dispatch with the facts filled in.

• If it returns open_questions that change scope, decide before continuing.
• If the change needs a network-dependent artifact the offline builder can't produce, split the

work — see Patterns: network-dependent artifact.

3. fact-verifier — gate (did the build hold up?)

Now verify the claims the finished change asserts or depends on — the drift check: did the builder assume, invent, or hallucinate a value/API/behaviour along the way? Run it on config values, "library X supports Y", resource IDs, version constraints, "the spec says Z".

• Gate rule: if any verdict is REFUTED, fix the code/claim (loop back to builder) before

proceeding. If UNVERIFIABLE, run the returned lookup_command (or have the caller run it) and re-verify — never commit on an unresolved fact.

• Skip only when the finished change asserts no external facts (pure refactor with green tests).

4. coherence-checker — structural gate (non-trivial changes)

Runs after fact-verifier (so refuted assumptions are known) and before code-reviewer (a cheaper structural pass than line-level review). It checks whether the implementation that exists structurally matches the plan, the spec it cites, and the verified facts — a different lens from the reviewer's line-level correctness. Its five checks:

1. Spec-to-code traceability — every cited spec section / MUST has code + a test.
2. Inverse-pair fidelity — every (encode,decode)/(write,read)/(export,import) pair has a

decode(encode(x)) == x test with no normalization tricks (.rstrip()/.lower()/set()/ sorted() that paper over the real delta).

1. Plan-to-commit traceability — every plan task has a change; skips are explicit, not silent.
2. Cross-implementation parity — when >1 impl of an interface changed, a test drives the same

input through each and asserts equivalent observable behaviour (not just "all have the method").

1. Contract-docstring fidelity — docstrings/schemas match what the code actually does.
2. Pattern-mirror coverage — every pattern the plan said to mirror is applied to every case

in its applies_to, not just the one the story named. A pattern present on the exception but absent on a parallel case (RLS+GRANT on one new table but not its siblings) is a coherence fail. This is the automated form of the "verify new tables match the last 3 tables added" self-review.

Dispatch with the plan (incl. out_of_scope and patterns_to_mirror), the fact verdicts (so it can confirm the code used corrected values, not refuted ones), and the branch/diff.

• When to run: non-trivial changes only — files_changed > 5, commits > 3, or a multi-part

plan. A one-file, one-commit change doesn't earn the stage; skip it — unless the plan has a patterns_to_mirror entry, which pulls coherence in regardless of size, because its failure mode (pattern on the exception but not its siblings) is exactly a small, low-file-count change. (The dev-story workflow gates this automatically — coherence: auto|always|never, plus an auto-on when a pattern is present.)

• Gate rule: verdict: fail → loop back to code-builder with the structural mismatch, then

re-run. Advisory like the reviewer — you weigh it; a deliberate out_of_scope deferral is never a coherence failure.

• Boundary: keep it on structure/traceability/parity. If its only finding is a line-level bug,

that's the reviewer's lane — don't double-report.

5. code-reviewer — review

Dispatch on the builder's branch/diff. Read the findings:

• blocking / needs-rework → loop back to code-builder with the specific findings.
• ship-with-fixes → apply the minor fixes (small enough to do inline, or another

builder pass) then continue.

• It is advisory. You weigh it and decide (disagree-and-commit); don't treat the

verdict as a veto, but don't ignore a well-evidenced blocking finding either.

6. Full-suite gate — the orchestrator's job

code-builder bounds its own test runs (targeted + the relevant module once) to avoid minutes-long full-suite runs that risk a dropped session, and reports tests.full_suite_command. Running the whole suite once is your job, not the builder's — run it before landing and require green. (The dev-story workflow does this as an explicit phase.) Never merge on an unrun or red suite.

7. Commit & land

When green and reviewed, hand to commit-pr for the commit/PR message (it reads the commit-style playbook). Landing (push/merge/PR open) is a human decision — confirm before pushing, per the global git rules. Never auto-push from the pipeline.

Choosing an agent (quick routing)

| Need | Agent | |---|---| | Write/modify code or tests | code-builder | | "Is this fact/version/ID/claim true?" | fact-verifier | | "Does the impl structurally match the plan/spec/verified facts?" | coherence-checker | | "Is this change correct / safe to land?" | code-reviewer | | Commit or PR/MR message | commit-pr | | Security-focused pass | /security-review | | Design/architecture trade-offs | architecture agent (e.g. azure-architect) |

Passing context between agents

Agents run in isolated context windows — they see only the prompt you pass. So:

• Forward the relevant prior output explicitly (the builder's branch name and

files_changed into the reviewer; a verifier's correct_value into the builder).

• Pass facts as data, not "as discussed" — the agent has no memory of the conversation.
• Tell each agent where to read project conventions; don't assume it knows them.

Principles

• Explicit over auto. Dispatch by name; gate on results. Determinism beats luck.
• Fact-gate at both ends. Load-bearing facts before the build, the change's claims before

commit — nothing lands on an unresolved or refuted fact.

• Advisory, not adversarial. The reviewer and any red-team inform your decision;

they don't make it.

• Least privilege. Verifier/coherence-checker/reviewer are read-only; only the builder

writes; only a human pushes/merges.

Generating infrastructure-as-code (extra governance)

Infrastructure changes are high-blast-radius and often irreversible, so when the fleet generates IaC (Terraform/OpenTofu/Terragrunt) the bar is higher than for app code. The pattern the field has converged on — "through IaC, not instead of it" — is that the agent produces reviewable IaC, never direct cloud changes. (Hard-won dogfooding a graph→IaC generator: the model is the contract; the gates are the moat.)

• Generate code, never touch the cloud. No agent runs apply/destroy or calls cloud

APIs directly against real environments. It emits IaC + a plan for a human/pipeline to apply.

• Plan → review → apply, always. State-changing infra routes through a plan a human or

the pipeline reviews; the pipeline is the only path to prod. (The same rule terragrunt-skill states for human authors binds doubly for agents.)

• Query state before acting. Read existing state/graph first; never assume the cache is

current. Acting blind breaks idempotency and create

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kevin-burns
• Source: kevin-burns/claude-skills
• License: MIT
• Homepage: https://techblog.kevinburns.de

Install and usage instructions live in the source repository linked above.