Deep dive · developersRevised October 2026

Orchestrating
Agents.

Assign work, contain actions and review what returns.

David Budáč
2
In practice

Follow one invoice ticket to a reviewed patch

Coordinate

Assign work and resolve ownership.

Contain

Set the allowed files, network and runtime budget.

Integrate

Check evidence, combine changes and decide whether to accept.

One ticket: export net, VAT and gross invoice values as CSV.

3
In practice

Two separate design decisions

Orchestration

Who gets a task, what it depends on and who integrates the result.

Isolation

What files, credentials, processes and network endpoints the tools can access.

A dashboard or Git worktree does not by itself enforce a security boundary.

4
In practice

Choose from the bottleneck

BottleneckUseful capability
Too many sessions to trackA monitor with task state and evidence links.
Independent changes collideSeparate workspaces plus explicit file ownership.
Ready work waits unclaimedA queue with leases, retries and review gates.
Tools can touch too muchA restricted environment with scoped credentials.

Choose products only after these requirements are clear.

5
In practice

One ticket, explicit state transitions

Ready: invoice rule + scope + acceptance cases Claimed: one owner + lease + retry budget Working: permitted workspace + progress evidence Review: patch + checks + unresolved gaps Accepted: reviewer confirms the requested behavior

Failed or blocked work returns with evidence. A green tool run does not automatically publish a change.

6
In practice

Walk the invoice ticket without a live service

EventExpected state or action
Worker finds missing VAT ruleBlocked; request the rule before changing behavior.
Two workers claim the same ticketOne claim wins; the other does not start editing.
Tests pass but escaping is untestedReview records the gap and adds an acceptance check.

Exercise: explain who owns each decision and what evidence is attached.

7
In practice

Specify the environment the worker receives

  • Allow the repository paths and commands required by the ticket.
  • Scope credentials and network access to the necessary services.
  • Use separate edit workspaces; enforce time, attempt and spend limits outside the prompt.

Review mounts, egress and permissions in the actual runtime.

8
Define done

Match each failure to a control

FailureConcrete control
Repeats the same failed repairLimit attempts; require a new hypothesis before retrying.
Weakens tests to make them passReview the test diff; run independent acceptance checks.
Changes unrelated behaviorScope allowed paths; inspect the complete diff.

Prompts help communicate these rules. Enforce the important boundaries in tools, permissions and review.

9
In practice

Limit work in progress to what can be reviewed

Before starting

Assign the reviewer and agree on the return format.

While work runs

Stop filling the queue when review capacity is exhausted.

At acceptance

Inspect the integrated result, including interactions between patches.

More workers can move the queue downstream. Measure completed, accepted work.

10
Make it repeatable

Save the repeated invoice check as a skill

invoice-check/ SKILL.md when to use it + verification procedure scripts/ optional deterministic checks references/ VAT and rounding rules

Procedure: inspect the diff → run the cases → report evidence and gaps.

11
In practice

Give each part of the invoice workflow one job

NeedWhere it belongs
VAT rate comes from the orderShort project instruction.
How to verify an invoice exportSkill with cases and a reporting procedure.
Read the invoice specification ticketAn authorized CLI, API or MCP tool.

A procedure teaches how to use access. It does not grant that access.

12
Make it repeatable

Package useful checks for the team

Skill

The repeatable invoice-check procedure and supporting files.

Plugin or shared package

A versioned way to distribute the procedure and supported integrations.

Test discovery and behavior in a clean session before sharing. Installation does not replace review or permission boundaries.

13
In practice

Write a verification skill you can test

10 minutes Define the trigger: invoice or CSV export changes. Write four checks: VAT, zero VAT, rounding, escaping. Name the command and required evidence. Test with one matching task and one unrelated task.

Output: a small skill file and evidence that it is used when appropriate.

14
Skill reference

An invoice-check skill for Claude Code

--- name: invoice-check description: Verify changes to invoice totals or CSV export. --- 1. Read the invoice rule and inspect the proposed diff. 2. Run the invoice and export tests; keep the actual output. 3. Check VAT, rounding and CSV escaping coverage. 4. Report findings, exit status and untested cases.

Example path: .claude/skills/invoice-check/SKILL.md. Check discovery in a fresh session.

15
In practice

Compare the complete interaction

MCP

Tools exposed through a client/server protocol, with structured inputs and supported authentication paths.

CLI

Commands executed by a shell tool, with help, arguments, output and error handling.

Both can reach local or remote services. Both need appropriate credentials, permissions and review.

16
In practice

Definitions are only one part of the cost

  • MCP schemas may be loaded eagerly or discovered on demand, depending on the client.
  • CLI use also consumes shell definitions, help text, command output and repair attempts.
  • Compare successful completion, tool failures, total usage and latency.

Measure the actual client configuration. There is no universal cheaper interface.

17
In practice

Run the same read through both interfaces

Task: retrieve the invoice ticket and its acceptance cases. Hold data, access scope and requested output constant. For CLI and MCP, record: correctness; calls; failures; tokens; elapsed time Repeat after warm-up; report missing measurements.

This is an experiment design, not a completed case study.

18
In practice

Design the return and the review before fan-out

  • One owner per task and a clear integration point.
  • Enforced boundaries and a finite retry budget.
  • Evidence-bearing returns, checked against the original acceptance cases.

Choose interface and orchestration tools from observed needs.

Optional reference material

19
Sources

Sources and further reading

Primary documentation checked 3 October 2026. Examples are illustrative unless explicitly attributed.