skills/agent-swarm/references/packets.md

Work packets

A packet is everything one agent needs and nothing else. The lead writes packets; workers read them. Packets live on disk so the workflow prompt stays short and every worker sees the same facts.

The context ladder

1. .swarm/brief.md — shared by all tasks: goal, success criteria, stack, commands, conventions, hazards, forbidden actions.
2. .swarm/tasks/Txx.md — one task: objective, inputs, deliverables, write scope, contract, acceptance, stop conditions.
3. .swarm/contracts.md — frozen interfaces; read the relevant section only.
4. Pointers — path:line ranges, not pasted code.
5. Examples — one short example only where the format is ambiguous.

If a worker needs the lead's conversation, the packet is incomplete. If a packet exceeds one page, split the task.

Brief

Copy assets/brief.md.tmpl. Rules:

• Goal is one paragraph; success criteria are checkable.
• List the exact build/test/lint commands. Workers should not guess.
• Map only the paths a worker may need; link the rest.
• Hazards: generated files, migrations, flaky tests, shared ports, secrets. Name what not to touch.
• Global forbidden actions are identical in every packet; keep them in the brief to save prompt space.
• No solution design, no task list, no worker-specific details.

Task card

Copy assets/task.md.tmpl. Rules:

• Objective: what must exist when done, in 1–3 sentences.
• Inputs: brief, contract section, and exact code ranges.
• Deliverables: paths, including tests.
• Write scope: globs. Everything else is read-only.
• Contract: exact signature or output shape. If it is not written, it is not frozen.
• Acceptance: 1–3 commands a verifier can re-run. "Code is clean" is not a check.
• Stop conditions: time/attempt limit (25 min for S/M, 45–60 for L) plus "ask, do not guess" for load-bearing unknowns.
• Never include another task's internal details; workers do not need the whole plan.

Verifier card

Copy assets/verifier.md.tmpl. Rules:

• State plainly: you did not write this; do not fix it.
• State that the tree is frozen: no source/test/docs/manifest edits during verification.
• Give criteria, changed paths, and commands; withhold the worker's rationale.
• Require a table: criterion, command, observed, pass/fail.
• Ask for scope, contract, and test-quality checks.
• Require the full review file first, then a minimal {task_id, verdict, summary, review_file} return (assets/verdict.schema.json). The review file is the source of truth; a schema miss must not erase the verification work.

Report

Copy assets/report.schema.json to .swarm/report.schema.json and assets/verdict.schema.json to .swarm/verdict.schema.json during bootstrap; workers/verifiers read those copies. Field discipline:

• status: done (acceptance met), partial (some criteria met, listed), blocked (needs a lead decision), failed (attempted, cannot proceed).
• verdict (verifiers only): pass, pass_with_risks, or fail; the detailed findings belong in the review file, not a required workflow array.
• files_changed: exact deliverable/code paths, no globs. Coordination artifacts under .swarm/ are implicit and may be omitted.
• evidence: commands and observed results, one line each.
• acceptance: per check, pass|fail|not_run plus evidence.
• assumptions: load-bearing assumptions the lead must confirm.
• blocked_question: one precise question, only when status=blocked.

Keep summary under ~300 characters. The lead reads summaries first and opens a report only for blocked/failed.

Common mistakes

Mistake	Fix
Pasting the whole conversation into every prompt	Write a brief; point to files
Vague acceptance ("works well")	A command and an expected result
No non-goals	List what not to touch
Two tasks own one file	Serialize or merge
Task needs 2+ hours	Split by deliverable, not by file count
Worker invents an interface	Freeze it in contracts.md
Report is an essay	Schema + one-line evidence
No stop condition	S/M 25 min, L 45–60 min / 3 attempts, then blocked
Verifier reads the worker's summary	Give the artifact and the criteria only
Verifier returns prose and loses its verdict	Write review file first; minimal verdict schema
Source edited during verification	Freeze, then re-run the affected verifier
Lead re-reads every report	Read summary + evidence; open only exceptions

Example: code task

# T04 — Add retry to the HTTP client

Role: worker | Wave: 1 | Depends on: T02 | Effort: M

## Objective
`fetchJson` retries idempotent GET requests up to 2 times on 5xx and network errors, with a 100 ms base delay and no retry on 4xx.

## Inputs
- `.swarm/brief.md`
- `.swarm/contracts.md` §HTTP client
- `src/http/client.ts:40-120`
- `src/http/client.test.ts:1-60`

## Deliverables
- `src/http/client.ts` — retry loop
- `src/http/client.test.ts` — 3 cases: 5xx retry, 4xx no retry, network retry

## Write scope
- `src/http/client.ts`
- `src/http/client.test.ts`

## Read-only
- `src/http/types.ts`, `package.json`

## Contract
`fetchJson(url: string, init?: RequestInit): Promise<Json>` — unchanged signature; retries only when `init.method` is absent or `GET`.

## Constraints
- No new dependencies; use the existing `sleep` helper.
- Do not change error types or messages.

## Acceptance
1. `pnpm vitest run src/http/client.test.ts` → all pass.
2. `pnpm tsc --noEmit` → no new errors.

## Stop conditions
25 minutes for S/M (45–60 for L) or 3 failed attempts at the same step; a needed change outside the write scope → `blocked`.

Example: research task

# T07 — Compare three vendors on data residency

Role: worker | Wave: 1 | Depends on: — | Effort: S

## Objective
A 400–600 word comparison of Vendor A/B/C on data residency, with a source URL for every factual claim.

## Inputs
- `.swarm/brief.md`
- `.swarm/contracts.md` §Report format
- `research/questions.md` §2

## Deliverables
- `research/vendors/data-residency.md`

## Write scope
- `research/vendors/data-residency.md`

## Acceptance
1. Every factual claim has a source URL that resolves.
2. All three vendors covered on: storage region, subprocessors, deletion policy.
3. No claims older than 18 months without a date.

## Stop conditions
If a vendor publishes nothing on a criterion, write "not disclosed" with the source checked; do not infer.