# 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, domain/evidence, commands or sources, 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 commands or evidence sources for the domain. 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 file/source 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 checks a verifier can re-run independently: commands, artifacts, citations, metrics or renders. "Works well" is not a check.
- GUI: acceptance includes a deterministic screenshot command, fixed window sizes and an isolated display; see `references/visual-testing.md`.
- 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/artifacts, and evidence checks; withhold the worker's rationale.
- Require a table: criterion, evidence, 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.
- GUI: require an isolated Xvfb/display, screenshots at default and minimum sizes, and the exact commands used; shared-desktop screenshots are not evidence.
- Product profile: require release-build performance numbers (p95 frame time, input latency, startup), the real UX scenario and a baseline comparison. A technical pass is not product acceptance; the user still gives the final verdict.

## 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 paths/artifacts, no globs. Coordination artifacts under `.swarm/` are implicit and may be omitted.
- `evidence`: commands, artifact paths, citations, metrics or renders with 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 re-runnable check 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

```markdown
# 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

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