Delegation Patterns

Delegation is the mechanism by which the lead assigns work to workers. The quality of the delegation determines the quality of the worker's output. A good delegation includes five elements: the task description (what to do), the acceptance criteria (how to know it is done), the context payload (what files to read, what patterns to follow), the constraints (what not to do), and the expected output format (structured JSON, patch file, branch name).

Three delegation patterns cover most orchestration scenarios. Direct delegation: the lead specifies exactly what to do, file by file, function by function. This produces the most predictable output but requires the lead to understand the codebase at implementation level. Goal-based delegation: the lead specifies the desired outcome and lets the worker determine the implementation. This produces more creative solutions but risks deviation from project conventions. Spec-based delegation: the lead writes a detailed specification and the worker implements it. This balances predictability with worker autonomy.

from agents import Agent, handoff, Runner

# Spec-based delegation — the lead writes specs, workers implement
lead = Agent(
    name="lead",
    model="o3",
    instructions="""
    You are a technical lead. For each subtask:
    1. Write a specification with:
       - Task description (one paragraph)
       - Acceptance criteria (bullet list)
       - Files to modify (explicit paths)
       - Patterns to follow (reference existing code)
       - Constraints (what NOT to do)
    2. Delegate to the appropriate worker
    3. Review the worker's output against the spec
    4. Request revisions if criteria are not met
    """,
    handoffs=[
        handoff(
            Agent(name="implementer", model="codex-1",
                  instructions="Implement exactly per the spec."),
            "Delegate implementation tasks",
        ),
        handoff(
            Agent(name="tester", model="gpt-4.1",
                  instructions="Write tests per the spec."),
            "Delegate testing tasks",
        ),
    ],
)

1. Write the spec template Create a standard delegation template: task description, acceptance criteria, files to modify, patterns to follow, constraints, output format. Every delegation uses this template.
2. Include examples Reference existing code that follows the pattern you want. "Follow the pattern in src/middleware/auth.ts" is more effective than describing the pattern in prose.
3. Define "done" Acceptance criteria must be verifiable: "tests pass", "type-check succeeds", "no lint warnings". Avoid subjective criteria like "clean code" that the lead cannot evaluate programmatically.