How to Structure Specs for Complex Multi‑Agent Tasks

1. Multi‑Agent: One Orchestrator + A Team of Dedicated Executors

The first decision for a complex task is to avoid a single Agent handling everything from start to finish. A single Agent quickly loses context and mixes responsibilities, leading to rule violations. The recommended approach is an orchestrator (entry Agent) that only coordinates and decides the current stage, gate checks, and which sub‑Agent to dispatch.

Sub‑Agents run in fresh contexts and only load the knowledge needed for that step. The author lists typical roles:

Requirement analyst – converts requirements into structured inputs.

Architect – creates technical designs, cross‑platform contracts, and ADRs, but does not write implementation code.

Platform implementer – one per platform, writes only its own code.

Code reviewer – validates security, performance, standards, and reference implementations.

Test engineer – defines test scope and writes failing‑first acceptance tests.

Integration engineer – runs end‑to‑end builds, installations, logs, and cross‑platform consistency checks.

Efficiency engineer – extracts repeatable patterns into reusable assets.

Choosing the wrong role not only mis‑allocates work but also bypasses the role‑bound rules. For example, assigning UI implementation to an architect skips the implementation‑level checks, causing visual alignment issues. Dispatch decisions must follow a two‑step validation: select role by stage, then verify the file‑path‑to‑role mapping; any conflict stops the process for clarification.

Parallelism is limited: at most five sub‑Agents per main line, typically four, with the fifth as a reserve. Each sub‑Agent declares its deliverable, format, location, and acceptance criteria. After execution, the output is verified before the Agent is released.

2. Orchestrator Entry (CLAUDE.md / AGENTS.md) Content

The orchestrator’s behavior is driven by its entry file. The author’s first principle is that the entry should contain only the startup index and hard boundaries, not detailed steps.

Many people overload the entry with all rules and processes, making it thousands of lines long and slow for the model to read. The correct approach is a thin entry that tells the model: "When a task arrives, first determine its type, then read the appropriate file." Detailed steps go into skill, hard rules into rules, role contracts into agents, and background/decision records into docs.

The second principle is to hard‑code the orchestrator’s contract. The entry includes statements such as:

It is an orchestrator and a closer, not an executor.

It only decides stage, gate, handoff, continuation, and assignee.

Minor mechanical revisions, index updates, and validation can be done by itself; everything else is delegated.

It never edits production code or bypasses gates, reviews, and validations.

For non‑fatal issues, it records owner, route, evidence, and next steps instead of stopping.

Only fatal errors or explicit gate blocks allow a stop.

Complex workflows should not pause for every minor issue; the contract must specify when to continue automatically and when a human decision is required. The entry file itself is generated from a template; editing the generated file directly will be overwritten on the next sync.

3. Organizing rules / docs / skills

Spec assets are not just processes; they also include knowledge, constraints, and step locations. The author separates them into three directories:

skills – how to do something (specific steps and flow).

rules – mandatory constraints and checklists.

docs – why the current design exists (architecture, background, long‑term decisions).

This separation ensures a single authoritative location for each piece of knowledge. Changing a process edits skill, changing a constraint edits rule, and tracing a design decision reads docs.

Skill file structure

skill/
  SKILL.md          # entry: routing + responsibilities + boundaries + output contract
  references/       # long content loaded on demand: methodologies, templates, checklists
  scripts/          # deterministic scripts (only for script‑backed skills)

Test cases live in a parallel evals directory, not inside the skill directory. SKILL.md follows a fixed skeleton:

frontmatter – name, description (must include "applicable / not applicable / typical trigger"), level, risk, manual review flag.

responsibility boundary – what the skill governs.

applicable & not applicable – when to invoke or avoid.

working method – minimal flow plus "when to read which reference".

on‑demand references – a list mapping scenarios to reference files.

output & verification – deliverable and pass criteria.

The key rule is that SKILL.md must be thin; it is a routing card for the model, not a full knowledge base.

How a skill references rule, docs, and knowledge base

Three citation mechanisms are used:

references – long content stored under references and loaded explicitly when the skill’s workflow reaches that step.

rules – not copied into the skill; they are attached automatically via path bindings or role bindings. The most critical constraints are always resident.

docs – long‑term knowledge and decision records; each doc entry must have an explicit consumer (a skill, rule, or role). Orphaned docs are considered dead knowledge.

Combined, they form a citation network where the skill is thin, references are loaded on demand, rules are attached by path or role, and docs are consulted for background.

Script organization

The scripts directory holds deterministic tools: validators, command wrappers, and workflow‑assist scripts. Their purpose is to narrow the Agent’s freedom; any task with a single correct answer should be scripted rather than generated each time.

Script requirements:

Prefer standard libraries and POSIX shell; avoid external dependencies.

State files must be written atomically with locking for concurrency.

Command wrappers may only invoke configured entry points; full logs are persisted, and the main session returns only a summary.

New scripts must have tests; changes to workflow scripts must run regression tests, not just syntax checks.

4. Skill layering and why it matters

Skills are divided into three non‑overlapping layers:

Orchestrator layer – usually a single component that maintains the state machine and dispatches control; it does not perform concrete work.

Phase layer – corresponds to each segment of the delivery chain (requirement, design, development, review, test, release). Each phase governs its own inputs, outputs, and gates.

Atom layer – the lowest level, a single deterministic capability that does one thing, does not orchestrate other skills, and does not invent commands.

Each phase ends with a four‑state gate: pass, blocked (with owner and fallback), not_required, or risk_accepted. If evidence is missing, the phase prefers to block rather than pretend completion.

All nodes are recorded in a single checklist file with fixed fields: layer, execution method (script‑backed or model‑driven), routing description (must contain "applicable / not applicable / typical trigger"), I/O, tools, risk level, and manual review flag.

Edges between nodes are of three types:

handoff – flow driven by the orchestrator between phases.

dynamic_load – loads the appropriate capability into a new sub‑Agent context based on task type.

semantic – evidence dependencies; downstream skills must consume the evidence before it can be considered conclusive.

Layering is essential because each layer changes at a different frequency and has distinct failure modes. Orchestration logic changes rarely but affect the whole system; phase contracts change at a medium rate; atomic abilities change frequently but affect only a single point. Layering enables independent routing, testing, and modification without unintended side effects.

Complex‑task spec core: three assets – workflow orchestration, skill organization, and knowledge‑base linking. Explaining each separately is far more effective than a longer prompt.

The article concludes that a well‑structured spec makes AI actions traceable: who does what, which rules are enforced, what evidence is produced, and where a blockage leads, all recorded in the spec rather than hidden in ad‑hoc dialogue.