---
name: leader-developer-handoff-contract
description: When the main agent dispatches a sub-agent, the prompt MUST include 5 elements — (1) task scope with verifiable target, (2) files / docs the sub-agent should read, (3) explicit skill list to invoke, (4) expected return format (diff / markdown section / decision text), (5) verification criteria. Invoke when about to dispatch a sub-agent (Developer / Designer / Code Reviewer), writing the dispatch prompt, or when asked "what should the sub-agent prompt include".
---

# Leader → Developer Handoff Contract

## Native mechanism

Claude Code's [Subagents](https://code.claude.com/docs/en/subagents) feature already gives a dispatched agent "its own context window with a custom system prompt, specific tool access, and independent permissions" — but the platform doesn't require or shape what goes in the dispatch *prompt* itself. This skill is the discipline layer on top: the 5 elements a prompt must contain regardless of how well-configured the subagent's own definition is.

## When to invoke

- About to dispatch a sub-agent (Developer / Designer / Code Reviewer / drafting agent).
- Writing the dispatch prompt.
- User asks "what should the sub-agent dispatch include / which elements am I missing".

## The 5 required elements

Every dispatch prompt must contain:

### 0. Tell the sub-agent to keep impl notes

Non-trivial dispatches carry a sixth, standing instruction: the sub-agent opens its running
impl-notes file at the *start* of the task, not when it first hits trouble. That file is where
early assumptions and scope calls get recorded — exactly the ones that are invisible by the time
a report is written. `agent-impl-notes-log` owns the file's format and routing; this contract is
what makes it start on time, since that skill's own trigger fires on mid-task ambiguity.

### 1. Task scope with verifiable target

- One sentence stating the goal.
- Explicitly name **the output file / section / behaviour**.
- Include a mechanically checkable success / failure condition.

**Good**: "Draft §5 Logger for `docs/foundations.md`; output format: complete markdown section; scope: adopt `os.Logger` defaults, with subsystem / category conventions and privacy default"

**Bad**: "Write something about logger"

### 2. Files / docs the sub-agent should read

- List file names + sections.
- Don't say "read design.md"; say "read `design.md §How.2`, `foundations.md §3-§4`".
- Add grep targets / line ranges when useful to save the sub-agent's exploration tokens.

### 3. Explicit skill list to invoke

- List the skill names the sub-agent should invoke (with plugin prefix).
- Don't assume the sub-agent will guess.
- Example: "invoke `swift6-concurrency`, `swiftpm-modularization`, `swift-testing-baseline`; review-style dispatches also list `subagent-review-cycles`".

### 4. Expected return format

Pick one explicitly (or custom):
- **Code diff** (patch / full-file rewrite)
- **Markdown section** (drop into a specified file's §)
- **Decision text** (structured ACCEPT/REJECT/DEFER list)
- **Finding list** (BLOCKER / MAJOR / MINOR)

**Bad**: "Report results"
**Good**: "Return the complete §5 content as markdown, ready for the Leader to paste into `foundations.md`; no chit-chat"

### 5. Verification criteria

- The conditions under which it counts as done.
- For Developer: which tests must be green, which invariants must hold.
- For Code Reviewer: review dimensions, forbidden tools (CLI), allowed tools (WebSearch).
- For drafting agent: section structure, required subsections, required decisions.

## Template

```
You are a <role> dispatched by the Leader.

## Task scope
<verifiable target, output file/section, success condition>

## Inputs (read these in order)
1. <path> §<section>
2. <path>
<...>

## Skills to invoke
- <skill-name-1>
- <skill-name-2>
<...>

## Return format
<one of: code diff / markdown section / decision text / finding list>
<exact shape>

## Verification criteria
- <criterion 1>
- <criterion 2>
<...>

## Constraints (optional)
- DO NOT <forbidden action>
- DO use <required tool / approach>
```

## Examples drawn from real dispatches

### Developer drafting design.md §How.3 (Game Center)

- **Scope**: draft `design.md §How.3` GC integration section, covering leaderboard / achievement / protocol / auth fallback / friends scope
- **Inputs**: `design.md §What.GC`, `foundations.md §1-§4`
- **Skills**: `swift6-concurrency`, `swiftpm-modularization`, `swift-testing-baseline`
- **Return**: complete markdown section, ready to merge into design.md
- **Verification**: includes 3 leaderboards + 10 achievements, protocol covers friends scope, auth failure has a fallback path

### Code Reviewer round 1 over §How 1–7

- **Scope**: review `design.md §How.1 – §How.7` for technical correctness
- **Inputs**: full design.md, foundations.md
- **Skills**: `subagent-review-cycles`
- **Return**: BLOCKER / MAJOR / MINOR finding list; each item with section location + suggestion
- **Verification**: covers 4 dimensions (correctness / consistency / completeness / efficiency); cites Apple docs instead of CLI experimentation
- **Constraints**: DO NOT run CLI; DO use WebSearch

## Anti-patterns

- **Omitting verification criteria**: the sub-agent self-judges "done", often misaligned with the Leader's expectation.
- **Listing "related skills" instead of "skills to invoke"**: the sub-agent may not actually trigger them.
- **Return format written as "free-form"**: every round looks different and integration cost balloons.
- **Scope too large (multiple sections / files in one round)**: review and revision cost explodes; split fine.

## Verification checklist (for Leader before sending dispatch)

- All 5 elements present (scope / inputs / skills / return format / verification).
- Scope corresponds to "one verifiable target", not "a basket of work".
- Skill names spelled correctly, with plugin prefix.
- Return format is one of the four explicit categories.
- Verification conditions are mechanically checkable.

## Related skills

- `subagent-review-cycles`: handoff is the starting point of each review-cycle round.
- `spec-phase-orchestration`: every sub-agent dispatch in the spec phase follows this contract.
- `session-to-meeting-log`: dispatch + returned-result summary lands in the meeting log.