git:20260907.575583f to git:20260907.6297feb

---

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:

### 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.