Make agent-swarm domain-neutral and adaptive

agent-swarm/references/domains.md

@@ -0,0 +1,69 @@
+# Domain adapters
+
+The swarm protocol is domain-neutral. A domain adapter says what "work", "ownership", "evidence"
+and "done" mean for this kind of task. Pick one, combine several, or write a project-specific
+adapter in `.swarm/profile.md`. Do not treat these as mandatory pipelines.
+
+## Software / code
+
+- Units: module, feature, crate, service, migration, test cluster.
+- Ownership: source + test paths; shared manifests/lockfiles/barrels/schemas are integrator-only.
+- Acceptance: build/test/lint commands, typecheck, generated-code compile, runtime smoke.
+- Verifier: reruns commands, reads the diff, checks edge cases and API compatibility; no self-review.
+- Evidence: command + observed result, test names, compiler output, benchmark numbers.
+
+## Research / analysis
+
+- Units: one question, source cluster, claim set, or section.
+- Ownership: one notes/report file per unit; no shared notes file.
+- Acceptance: every factual claim has a source URL; dates are explicit; counter-evidence is considered.
+- Verifier: samples claims against sources, checks citation resolvability and recency, looks for
+  unsupported synthesis.
+- Evidence: source URL, quote/paraphrase, access date, confidence, open questions.
+
+## Content / documents / translation
+
+- Units: one section, chapter, page, or locale.
+- Ownership: separate section files; the editor/integrator owns the assembled document and style.
+- Acceptance: section brief, word/character budget, terminology/glossary, citations, style guide,
+  rendered artifact (PDF/HTML/DOCX) where applicable.
+- Verifier: reads the rendered artifact, checks structure/voice/term consistency, samples facts.
+- Evidence: rendered path, word count, diff, terminology check, citation check.
+
+## Data / analytics
+
+- Units: one dataset, metric, query, notebook, or chart.
+- Ownership: input data read-only; one output table/notebook/report per unit; shared schemas need an
+  integrator.
+- Acceptance: reproducible script with pinned inputs; output schema; row counts; metric definitions;
+  checksums or input hashes.
+- Verifier: reruns the pipeline on a sample or full dataset; recomputes key numbers; checks nulls,
+  duplicates, units and time zones.
+- Evidence: command, input hash, output rows, metric values, notebook/report path.
+
+## Design / UX / visual
+
+- Units: screen, component, flow, illustration, design token set.
+- Ownership: one source/design file per unit; shared tokens/components/integrator.
+- Acceptance: rendered artifact at required sizes/states; accessibility (contrast, focus, keyboard,
+  labels); interaction states; visual regression.
+- Verifier: renders the artifact in an isolated display; checks default/minimum/empty/error states;
+  never accepts a shared-desktop screenshot.
+- Evidence: screenshot path, dimensions, command, contrast/focus notes.
+- See `visual-testing.md` for isolation and deterministic capture; it is optional for non-visual work.
+
+## Operations / infrastructure
+
+- Units: one service, deployment, migration, runbook, or config change.
+- Ownership: infra files and runbooks; live environments are not "write scopes".
+- Acceptance: dry-run/plan output, diff, rollback procedure, monitoring/health check, no production
+  writes without explicit human approval.
+- Verifier: reviews the plan/diff, runs read-only checks, confirms rollback and blast radius.
+- Evidence: dry-run output, diff, health check, rollback command, approval record.
+
+## How to adapt without inventing a pipeline
+
+1. Write `.swarm/profile.md` with: domain, artifacts, commands, evidence types, approval boundaries.
+2. In `.swarm/brief.md`, replace command-only success criteria with "evidence type + check".
+3. In each task card, name the artifact and the verifier action, not the steps.
+4. In verification, use the matching adapter above; independent evidence is the invariant.

agent-swarm/references/orchestration.md

@@ -144,6 +144,20 @@ The verifier writes the review file first and returns only `{task_id, verdict, s
 
 Use `run_in_background: true` when a wave may exceed ~10 minutes or you want live progress in the job list. The call returns a job id; `job_output` with `wait: true` blocks until settlement. If a wave hangs, `job_kill` cancels the run and disposes children. A background run's result arrives once, at settlement.
 
+## Tool availability
+
+The protocol does not require the `workflow` tool. At preflight check what exists:
+
+- `workflow` + sufficient slots → batched runner (`wave.workflow.js`).
+- `subagent` only → lead dispatches 2–5 long-lived packets directly, or runs sequentially with
+  structured reports.
+- Neither → the lead executes the packets itself and still uses independent review/evidence; the
+  skill becomes a planning/verification checklist, not a parallel runtime.
+
+The same brief, task cards, ownership map and report schema apply in all three modes. Do not
+fabricate a workflow if the tool is unavailable, and do not force a full swarm for a task that a
+single agent can finish.
+
 ## Archetypes
 
 ### Code
@@ -152,6 +166,18 @@ Use `run_in_background: true` when a wave may exceed ~10 minutes or you want liv
 - Acceptance: targeted test command, typecheck, lint on changed files.
 - Verify: a fresh agent runs the tests and reads the diff; no self-review.
 
+### Data / analysis
+- Units: dataset, metric, query, notebook or chart per agent.
+- Ownership: inputs read-only; one output table/report per unit.
+- Acceptance: reproducible script, input hash, row counts, metric definitions.
+- Verify: rerun on a sample or full data; recompute key numbers.
+
+### Design / UX
+- Units: screen/component/flow/token set per agent.
+- Ownership: source design files; shared tokens are integrator-only.
+- Acceptance: rendered artifact at required sizes/states, accessibility checks.
+- Verify: isolated display, screenshot path, keyboard/focus/contrast notes.
+
 ### Research
 - Units: one question or one source cluster per agent; output files under `research/`.
 - Ownership: one file per agent; no shared notes file.

agent-swarm/references/packets.md

@@ -4,7 +4,7 @@ A packet is everything one agent needs and nothing else. The lead writes packets
 
 ## The context ladder
 
-1. `.swarm/brief.md` — shared by all tasks: goal, success criteria, stack, commands, conventions, hazards, forbidden actions.
+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.
@@ -16,7 +16,7 @@ If a worker needs the lead's conversation, the packet is incomplete. If a packet
 
 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.
+- 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.
@@ -26,11 +26,11 @@ Copy `assets/brief.md.tmpl`. Rules:
 
 Copy `assets/task.md.tmpl`. Rules:
 - Objective: what must exist when done, in 1–3 sentences.
-- Inputs: brief, contract section, and exact code ranges.
+- 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 commands a verifier can re-run. "Code is clean" is not a check.
+- 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.
@@ -40,8 +40,8 @@ Copy `assets/task.md.tmpl`. Rules:
 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.
+- 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.
@@ -51,8 +51,8 @@ Copy `assets/verifier.md.tmpl`. Rules:
 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.
+- `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`.
@@ -64,7 +64,7 @@ Keep `summary` under ~300 characters. The lead reads summaries first and opens a
 | 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 |
+| 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 |

agent-swarm/references/playbook.md

@@ -1,10 +1,11 @@
 # Swarm playbook
 
-Detailed runbook for `agent-swarm`. Read this after the fit check passes. Keep `.swarm/state.json` current; it is the resume point if the session restarts.
+Detailed runbook for `agent-swarm`. Read this after the fit check passes. The runbook is domain-neutral; choose an adapter from `domains.md` and put its details in `.swarm/profile.md`. Keep `.swarm/state.json` current; it is the resume point if the session restarts.
 
 ## 0. Fit check and budget
 
 Answer these before spawning:
+- **Mode.** Is this really a swarm, or does a direct run / paired critic cover the risk with less overhead?
 - **Units.** Can you list 8+ deliverables that different agents can finish without waiting for each other?
 - **Writes.** Can every unit get a disjoint write scope? Name the shared files now.
 - **Checks.** Does every unit have a command or criterion a verifier can re-run?
@@ -12,13 +13,13 @@ Answer these before spawning:
 - **Breadth.** Is the time dominated by many independent pieces, not one deep chain?
 
 Budget:
-- `agents ≈ units + ceil(units / 5) verifiers + 1–2 integrators + 2–4 recon`; add retries and re-verifications explicitly.
+- `agents ≈ units + ceil(units / 5) verifiers + 1–2 integrators + 2–4 recon`; add retries and re-verifications explicitly. Set `max_agents` only after checking available tools and slot cap.
 - Tokens ≈ `agents × 20k` (10–40k per agent depending on code reads).
 - Waves ≈ `ceil(units / batch_size)` + verify + integrate, where `batch_size` comes from the **real** active-child cap, not from a documented default.
 - Stop at `max_agents` or `max_waves`, whichever comes first. Record both, plus `slot_cap`, `active_at_dispatch`, `batch_size`, retries and re-verifications in `state.json`.
 
-Go: a 40-file migration with per-module tests, a 30-source research report, a 20-section document with a style guide.
-No-go: one failing test, one architectural decision, a refactor where every file imports the same core module.
+Go: a 40-file migration with per-module tests, a 30-source research report, a 20-section document with a style guide, a multi-dataset analysis, a multi-screen visual redesign, a multi-service runbook.
+No-go: one failing test, one architectural decision, a detail pass where every unit touches the same artifact.
 
 ## 1. Recon (2–4 agents)
 
@@ -44,13 +45,13 @@ cp <skill>/assets/verdict.schema.json .swarm/verdict.schema.json
 node <skill>/scripts/audit-scope.mjs --init
 ```
 
-Write the plan before any worker starts.
+Write the plan before any worker starts. Keep the plan proportionate: a small domain task may need only a brief and a verifier, not a full `.swarm` tree.
 
-**Decomposition.** One task = one deliverable, one writer, one acceptance check, at most one page. Budget **5–25 minutes for S/M** and **40–60 minutes for L**; the old blanket 25-minute rule underestimates large UI/refactor files. If a task is expected to produce a single source file over ~1,500 lines, split it by module or accept that it will be a long, integration-heavy task. If it needs two writers, split it; if it needs the whole repo, it is not a task.
+**Decomposition.** One task = one deliverable, one writer, one acceptance check, at most one page. The deliverable may be a module, a research question, a document section, a dataset, a design artifact, or a runbook. Budget **5–25 minutes for S/M** and **40–60 minutes for L**; if a task is expected to produce a single source file over ~1,500 lines (or a very large document/dataset), split it or accept an integration-heavy task. If it needs two writers, split it; if it needs the whole repo, it is not a task.
 
-**Ownership.** Every path in exactly one `write` list. Add an explicit `LEAD` task whose `write` list contains lead/integrator-owned shared files, screenshots, licenses and the final report; without it, audit-scope reports the lead's own integration edits as unowned. Shared files are integrator-only: `package.json`, lockfiles, `tsconfig`, CI config, barrel/index files, schemas, migrations, i18n catalogs, snapshots, generated code. If two tasks must touch one file, serialize them with `depends_on` or merge them.
+**Ownership.** Every artifact/path in exactly one `write` list: files, sections, datasets, source notes, design files. Add an explicit `LEAD` task whose list contains lead/integrator-owned shared artifacts, screenshots, licenses and the final report; without it, audit-scope reports the lead's own integration edits as unowned. Shared files are integrator-only: manifests, lockfiles, indexes/barrels, schemas, shared style/token files, migrations, i18n catalogs, snapshots, generated code. If two tasks must touch one artifact, serialize them with `depends_on` or merge them.
 
-**Contracts.** Freeze what crosses a boundary: function signatures, types, file names, CLI flags, error behavior, output format. Put them in `.swarm/contracts.md`; workers may not change them without returning `blocked`.
+**Contracts.** Freeze what crosses a boundary within the chosen domain: function signatures/types/file names/CLI behavior for software; source/date/citation format for research; section structure/terminology/render target for content; schema/units/definitions for data; breakpoints/states/tokens for design; approval/rollback boundaries for operations. The invariant is the same: a verifier can check the contract independently. Put it in `.swarm/contracts.md`; workers may not change it without returning `blocked`.
 
 **Coverage matrix.** Each success criterion → task(s) → check. A criterion with no task is a hole; a task with no criterion is scope creep.
 

agent-swarm/references/visual-testing.md

@@ -5,6 +5,11 @@ modals, dialogs that do not close, wrong DPI, a viewport that renders a blank ba
 screenshot that captures a different agent's window. Treat visual verification as a separate test
 tier with its own infrastructure.
 
+The commands below use Linux Xvfb + ImageMagick as one concrete provider. On macOS/Windows use a
+container or the platform's virtual-display tooling; the invariant is **isolation and deterministic
+capture**, not Xvfb itself. If the app can capture its own framebuffer, that is preferred on every
+platform.
+
 ## Rule zero: never share one desktop
 
 Do not run several visual agents against the same X11/Wayland session. They steal focus, overlap
@@ -17,7 +22,7 @@ Each visual agent gets:
 - its own display (`DISPLAY=:N` / Wayland socket),
 - its own `HOME`, `XDG_CONFIG_HOME`, `XDG_RUNTIME_DIR`, `TMPDIR`,
 - its own project copy/worktree and artifact directory,
-- its own `CARGO_TARGET_DIR` (or a read-only prebuilt cache + writable per-agent target),
+- its own build target/cache directory (or a read-only prebuilt cache + writable per-agent target),
 - its own service port (BRP, dev server, websocket),
 - a cleanup trap that kills the app, the X server and any helper processes.
 
@@ -66,7 +71,7 @@ export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.x86_64.json
 # Start the app *after* the X socket exists. A small WM helps focus/IME.
 sleep 0.5
 # openbox &   # optional
-timeout 120s cargo run -p app -- --screenshot-mode "$ART/app.png" &
+timeout 120s <run command> --screenshot-mode "$ART/app.png" &
 APP_PID=$!
 
 # Prefer an in-app deterministic screenshot. Fallback: capture the root window.
@@ -84,7 +89,7 @@ Containers are useful for reproducibility and cleanup, not as a default for ever
 - Build one pinned image with Rust, Xvfb, Mesa/lavapipe, ImageMagick, xdotool and a minimal WM.
 - Run one container per visual agent: `--rm --network=none --userns=keep-id`, no host `$HOME`, a
   read-only repo mount plus a writable worktree/artifact mount.
-- Keep cargo registry/cache in a named read-only volume; use a per-container target dir.
+- Keep package-manager/build caches in a named read-only volume; use a per-container target dir.
 - GPU: `--device /dev/dri` for Intel/AMD; NVIDIA needs the container toolkit/CDI. Prefer software
   rendering for UI tests and reserve GPU containers for one final Tier 3 run.
 - Limit visual containers to 2–4 concurrently; llvmpipe uses CPU aggressively.