# Dev Fleet > Orchestration playbook for driving the development agent fleet (code-builder, fact-verifier, coherence-checker, code-reviewer) through a build → verify → cohere → review → commit pipeline with explicit, deterministic hand-offs. Use when implementing a non-trivial change where correctness and fact-accuracy matter and you want the steps to actually run in order rather than hoping the orchestrator d… - **Type:** Skill - **Install:** `agentstack add skill-kevin-burns-claude-skills-dev-fleet` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [kevin-burns](https://agentstack.voostack.com/s/kevin-burns) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [kevin-burns](https://github.com/kevin-burns) - **Source:** https://github.com/kevin-burns/claude-skills/tree/main/dev-fleet - **Website:** https://techblog.kevinburns.de ## Install ```sh agentstack add skill-kevin-burns-claude-skills-dev-fleet ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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). 3. **Plan-to-commit traceability** — every plan task has a change; skips are explicit, not silent. 4. **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"). 5. **Contract-docstring fidelity** — docstrings/schemas match what the code actually does. 6. **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](https://github.com/kevin-burns) - **Source:** [kevin-burns/claude-skills](https://github.com/kevin-burns/claude-skills) - **License:** MIT - **Homepage:** https://techblog.kevinburns.de Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-kevin-burns-claude-skills-dev-fleet - Seller: https://agentstack.voostack.com/s/kevin-burns - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.