leader-developer-handoff-contract
Shape the prompt a Leader sends when dispatching a sub-agent (Developer, Designer, Code Reviewer, drafting agent) so the result comes back verifiable and integrable. Use when about to call the Agent t
SKILL.mdcollaboration-skills/skills/leader-developer-handoff-contract/SKILL.md
GitHubLeader → Developer Handoff Contract
Native mechanism
Claude Code's 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 6 elements a prompt must contain regardless of how well-configured the subagent's own definition is.
- Official sources: when verifying or updating a factual or version-sensitive claim, read
references/official-docs.md.
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 6 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
apple-dev-skills:swift6-concurrency,apple-dev-skills:swiftpm-modularization,apple-dev-skills:swift-testing-baseline; review-style dispatches also listcollaboration-skills:subagent-review-cycles". - When the dispatch target is a custom agent (
.claude/agents/or a plugin'sagents/), list them in that agent'sskills:frontmatter instead — Claude Code preloads those at startup (the full skill content is injected, not only the description), so the prompt only needs to name skills the agent definition doesn't already carry. See https://code.claude.com/docs/en/sub-agents.
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; CLI is forbidden for probing API/runtime behavior (build, run, simctl, trial-and-error); read-only search (grep, rg, git log, git show) is allowed; allowed tools (WebSearch).
- For drafting agent: section structure, required subsections, required decisions.
6. Impl notes (non-trivial tasks)
Required when the task touches ≥2 files or adds new behavior (this catalog's M/L task-sizing
convention, if your workflow defines one); optional for a trivial one-file fix. Tell the sub-agent to open its running
impl-notes file at the start of the task, not when it first hits trouble — early assumptions
and scope calls are exactly what's 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.
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>
<...>
## Impl notes (non-trivial tasks)
Required if this task touches ≥2 files or adds new behavior: open `meetings/{date}_{topic}.impl-notes.md` at the start of the task (`collaboration-skills:agent-impl-notes-log`).
## Constraints (optional)
- DO NOT <forbidden action>
- DO use <required tool / approach>
- Base SHA (when `isolation:"worktree"`): <sha>; verify with `git log --oneline -5` before editing (see `subagent-conflict-detection`)
Examples drawn from real dispatches
Developer drafting design.md §How.3 (a feature section)
- Scope: draft
design.md §How.3for the feature named in §What, covering its component / protocol / auth-fallback / scope breakdown - Inputs:
design.md §What.<feature>,foundations.md §1-§4 - Skills:
apple-dev-skills:swift6-concurrency,apple-dev-skills:swiftpm-modularization,apple-dev-skills:swift-testing-baseline - Return: complete markdown section, ready to merge into design.md
- Verification: includes the entities §What enumerates, the protocol covers the scope §What defines, auth failure has a fallback path
Code Reviewer round 1 over §How 1–7
- Scope: review
design.md §How.1 – §How.7for technical correctness - Inputs: full design.md, foundations.md
- Skills:
collaboration-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: CLI is forbidden for probing API/runtime behavior (build, run, simctl, trial-and-error); read-only search (grep, rg, git log, git show) is allowed; 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 6 elements present (scope / inputs / skills / return format / verification / impl-notes).
- 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.
- Impl-notes slot included when the task touches ≥2 files or adds new behavior.
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.