know.2nth.ai Software Orchestrating agents
software · Orchestrating agents · Skill Leaf

Stop pairing. Start orchestrating.

The teams getting durable value from coding agents in 2026 aren't pointing one assistant at one file. They run a small number of coordinated agents against a codebase whose conventions, guardrails, and backlog are written down in a form the agent can read. The shift is from pairing — guiding one agent in real time, bounded by one context window — to orchestrating: planning work, handing it out, and verifying results. That's the skill set of an engineering manager, not a coder. This leaf is the execution playbook; the foundation it stands on lives one link away.

Orchestrate, not pair 3 execution modes Forge automation Honest tradeoffs

Plan the work, hand it out, verify the result.

Pairing is sequential and real-time: you steer one agent through one task inside one context window. Orchestrating is a different job — you decompose work, dispatch it to agents that don't share your memory, and check what comes back. Five ideas do most of the work, and none of them is “a bigger model”:

  • The environment around the model matters as much as the model. Convention files, hooks, skills, and scoped permissions are what make an agent reliable on a large codebase. Invest there before reaching for more agents or bigger context windows.
  • The backlog is the interface. Agents are stateless between tasks, so context must travel with each unit of work. A well-specified ticket is the prompt; your issue tracker becomes the coordination layer.
  • Separate planning from implementation. The most expensive mistake is letting an agent write code before the team agrees what to build. Reviewing intent is cheap; unwinding a wrong multi-file diff is not.
  • Isolate parallel work. Multiple agents against one working directory collide. Give each its own branch and checkout; coordinate through shared state, not shared files.
  • Keep humans on the diff. An agent-assisted change is done when the diff is reviewed, comments are resolved, CI is green, and it still merges cleanly — not when the bot posts a comment.

When this is overkill

A single-maintainer repo with one workstream needs almost none of the apparatus below. It earns its cost specifically when multiple people and multiple parallel streams share one codebase. Scale the ceremony to the coordination you actually have — running an orchestration fleet against a solo side-project just burns tokens and attention.

Foundation before fleet.

Orchestration only works on top of two things this branch already covers in full. This leaf assumes them rather than repeating them — get them right first.

An agent-legible codebase: a lean root convention file (the map and the non-negotiables) with scoped per-directory detail, deterministic hooks that enforce guardrails instead of trusting the model to remember them, path-scoped skills for on-demand expertise, language-server (LSP) access so the agent searches by symbol not string, and all of it bundled into a version-controlled unit so a new developer — or a fresh agent session on another machine — inherits identical setup on day one. And a backlog that carries context: a “ready” gate, stream/size/agent-ready fields, and tickets written as specifications, not reminders.

The two prerequisite leaves

Software for agents is the agent-legible codebase in full — repo-as-context, CLAUDE.md / SKILL.md, agent PRs, CI as the safety net. Planning with agents is the backlog as interface — spec-as-prompt, the ready gate, cadence, and what to measure. If those aren't in place, start there; nothing below compensates for a codebase an agent can't navigate or a ticket it can't execute.

At scale, this work needs a named owner

Several organisations have created a hybrid PM/engineer role — an “agent manager” or DRI — sitting under developer experience, responsible for the conventions, the guardrails, and keeping them current as models and tools change. Without a named owner, good setups stay tribal and fragment. The rollouts that spread fastest had this infrastructure built by a small team, sometimes one person, before broad access — so the first experience was productive rather than frustrating (practitioner-reported).

Match the mode to the task's size and coordination.

Three ways to task an agent, from most-supervised to least. Most day-to-day work is Mode 1; the others earn their place as the work gets wider or more parallel.

Mode 1 · default

Interactive planning

Run the agent read-only: it investigates and proposes an approach touching no files, you correct the plan in a sentence, then it implements. The highest-leverage habit for multi-file work — a wrong plan costs one sentence, a wrong 300-line diff costs hours.

Mode 2 · parallel

Isolated worktrees

Give each stream its own branch checked out into its own directory. Git worktrees are the native, cheap way — they share one underlying repository, so no re-cloning or duplicated dependencies. One session per stream; serialise anything touching shared files.

Mode 3 · batch

Headless / scripted

For wide mechanical work (a migration, an audit, a coverage sweep), drive the agent non-interactively from a script or CI, one invocation per unit, with tightly scoped permissions. Use a cheaper model for triage and classification; reserve the stronger one for the build.

ModeBest forSupervisionIsolation
Interactive planningAnything non-trivial & multi-filePlan boundary + diffOne session
Isolated worktrees2+ streams running at oncePer-stream, at the diffBranch + directory each
Headless / scriptedWide mechanical fan-outEvidence + CI gatesScoped tool permissions
Mode 2 — a worktree per stream (illustrative; verify flags against git docs)
# one shared repo, two isolated checkouts — no re-clone, no dep duplication
git worktree add ../proj-auth    -b stream/auth     origin/main
git worktree add ../proj-billing -b stream/billing  origin/main

# run one agent session in each directory; they never touch the same files
# serialise work on genuinely shared files (root config, shared components)

Two coordination models — and the token bill.

When one person managing a handful of agents stops scaling, two patterns exist. Understand the distinction before reaching for either — and price the tokens honestly.

PatternHow it worksBest whenThe cost
Orchestrator / subagent
(hierarchical)
One lead holds the plan and delegates bounded subtasks to workers, each with its own context; workers report concise summaries; the lead reconciles them into one reviewable change set.Tasks split into specialised responsibilities (backend, frontend, tests, review) that don't need to talk to each other.The orchestrator's context accumulates every summary — on large pipelines it can balloon.
Peer team / shared list
(lateral)
Agents coordinate through a shared queue — like a kanban board — claiming tasks, posting outputs, unblocking each other, with a lead seeding the top-level items.Workers genuinely need to share findings and challenge each other across a change that spans layers.More coordination surface; no single agent holds the whole history (which keeps per-agent context lean).

The honest token tradeoff

Multi-agent setups use substantially more tokens than a single session doing the same work sequentially — a three-worker team roughly three-to-four times the tokens is a commonly cited figure (largely vendor-reported; verify against your own runs). They pay off on large, genuinely divisible work and waste money on sequential tasks, same-file edits, or anything with heavy dependencies. Built-in team features in agent runtimes are, at time of writing, often experimental and off by default — treat them as promising, not production-hardened, and keep humans approving anything that ships.

Verification is not optional

Have agents show evidence rather than assert success: the command run and its output, the test result, the diff between the branch and the base. Reviewing evidence is faster than re-deriving it, and it works for runs you didn't watch. The powerful pattern is a fresh-context reviewer — one agent (or a human) whose only job is to try to refute the first agent's claim of success, because a worker is biased toward the code it just wrote. One hard constraint of most subagent models: a worker can't pause to get your approval mid-task — so investigation belongs in subagents, approval-gated edits belong in the parent session or a human.

GitHub (or equivalent) is where agents and humans meet.

Three layers of forge automation, from least to most automated. Each is useful on its own; together they close the loop from an incoming issue to a merged, reviewed change.

Layer 1

Agent in issues & PRs

A mention (@-tag in an issue or PR comment) hands the agent a bounded task; it reads the repo, opens or revises a PR honouring your convention files, and reports back. Install adds the app, a workflow file, and an API secret — usually needs repo-admin rights.

Layer 2

Read-only CI review

Run the agent in CI on PR events as a read-only reviewer — no write access, so it advises but can't modify. Turns a 30–60-minute first review pass into a sub-five-minute one (vendor/practitioner-reported), catching style, missing error handling, and pattern violations so humans focus on architecture.

Layer 3

Structured outputs → automation

Have the agent return validated JSON that downstream steps branch on: auto-triage an incoming issue into stream/size/ready fields and move it to the right column; detect a flaky test and re-run CI. A cheap model is enough for most classification, so it can run on every issue.

Permissions & safety — the most common failure

  • Grant the narrowest scope that works and escalate only when a specific action fails. An explicit permissions block typically resets every unnamed scope to none, so the recurring error is “not accessible” — the token lacks exactly one scope. Add that one, nothing more. Posting comments, pushing branches, and reading CI are each distinct scopes.
  • Exclude bots from triggering the agent, or it responds to itself and other bots — an infinite loop that also burns budget.
  • Never run agent review against untrusted fork code in a context that exposes your secrets. Use the event type that keeps secrets away from forks as the default; a fork PR then sees no key and exits before spending anything.
  • Treat pushing to shared branches as high-risk — require explicit human confirmation; it changes shared state and shouldn't be silent. Pin the versions of any actions you depend on, and vet MCP servers and external integrations as part of your trusted computing base.

In order — foundation, board, planning, parallelism, forge, fleet.

  1. Get the convention-file hierarchy and guardrails right (see §02).
  2. Make the board agent-legible — a ready gate and stream fields.
  3. Adopt interactive planning mode as the team default.
  4. Add isolated parallel checkouts for streams that genuinely run concurrently.
  5. Wire the forge integration — mention-driven, then read-only review, then triage automation.
  6. Only then experiment with multi-agent orchestration on a genuinely divisible pilot task.

Name an owner early. And review the whole configuration every few months or after a major model release — instructions written for a weaker model can actively constrain a stronger one.

Readiness checklist (the load-bearing items)

  • Lean root convention file + scoped per-directory files; guardrails enforced by hooks, not prose.
  • Board with a ready gate and stream / size / agent-ready fields; a filtered agent queue.
  • A ticket template that enforces spec-as-prompt: context, checkable definition of done, constraints, explicit out-of-scope.
  • Interactive planning the default; evidence-based verification expected on every task.
  • Worktrees documented for parallel streams; shared-file work serialised.
  • Forge integration installed (write-scoped + bot-guarded mention agent; read-only review); permissions start narrow; fork-secret safety verified.
  • A named owner for conventions and permissions policy; a standing review cadence (every 3–6 months or on major model releases).

What this doesn't fix.

Read these before you scale

  • Cost scales with parallelism. Multi-agent runs multiply token spend; the payoff is real only on large, divisible work. Measure it on your own tasks rather than trusting headline multipliers.
  • Experimental features are experimental. Built-in team orchestration in current runtimes has known rough edges around session resumption, coordination, and shutdown. Treat as preview.
  • Context length is not competence. A larger window lets an agent see more; it doesn't make it finish correctly. Scoping, verification, and gates keep an agent on track — not raw context.
  • The human is still accountable. Everything that reaches production goes through human review of the diff and the behaviour. Agents compress the time to a first draft and first review; they don't remove the reviewer.
  • This is a moving target. Commands, flags, feature availability, and best practice shift on a monthly cadence — re-verify anything version-specific against current docs before you rely on it.

Orchestration is discipline, not budget.

Scale the ceremony to the coordination you actually have

For SA teams the good news is the same as the rest of this branch: the apparatus that makes agents productive at scale is engineering hygiene, not a frontier budget. Worktrees, a ready-gated board, and a read-only CI reviewer are free discipline anyone can adopt. A small team — often one agent-manager — builds the convention files, guardrails, and forge config once, and every contributor (and every fresh agent session) inherits it. Start with interactive planning and one repo; add parallelism and multi-agent orchestration only when you genuinely have the concurrent streams to justify the token bill. And the by-product is the compliance artifact POPIA and FSCA reviews ask for: the versioned spec, the PR trail, and the evidence each agent showed are your change-control record, produced as you work.

Where this links in the tree.

Primary sources — verify version-specifics before adopting.

Provenance: the load-bearing patterns come from primary vendor documentation and engineering writing; practitioner and community sources corroborate the permissions, orchestration, and token-economics points. Figures on time saved and token multipliers are vendor- or practitioner-reported and labelled as such in the text — indicative, not independently benchmarked. Feature names and version-specific mechanics reflect mid-2026 tooling and should be re-checked before you rely on them.