148 lines
6.3 KiB
Markdown
148 lines
6.3 KiB
Markdown
# 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
|
||
|
||
```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.
|
||
```
|