Emil_Shanaty/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add prerequisite gate before dispatch

Browse Source
This commit is contained in:
Emil Shanaty
2026-10-27 19:41:36 +03:00
parent c3f58ceb40
commit 2309fda7b7
9 changed files with 180 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agent-swarm/SKILL.md
+14 -10
View File
@@ -40,14 +40,15 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived
## Protocol
0. **Fit check & preflight** — go/no-go, budget (`max_agents`, `max_waves`, **tokens**), and **discover the available tools and real active-child cap** before sizing a wave. Record in `state.json`: tool availability (`workflow`, `subagent`, display/artifact command, build commands), slot cap, active children, planned batch size, chosen domain adapter, token budget/soft cap/reserve, and whether usage is measured or estimated (see `references/token-economy.md`).
1. **Recon** — 2–4 parallel agents return findings with paths and line numbers. Timebox them, merge into `.swarm/brief.md` and `.swarm/map.md`, then stop them; recon must not hold slots during the build wave.
2. **Plan gate** — write `.swarm/plan.json`, `plan.md`, `ownership.md`, `contracts.md`, and one `tasks/Txx.md` per unit. Every success criterion maps to a task and a check. No two tasks write the same path. Include a `LEAD`/`INTEGRATOR` task owning lead-owned shared files, screenshots, licenses and the final report. Freeze interfaces. Prefer vertical slices and files under ~800 lines; a task that requires reading a 3k-line file is too broad. **Do not dispatch until this gate passes.**
3. **Build wave** — one `workflow` call per build wave when the tool exists, using the batched runner in `assets/wave.workflow.js`; its `concurrency` must fit the available slots (see Sizing). If `workflow`/`subagent` is unavailable, the lead executes the same packets sequentially. Retry `null`/`failed` once; if the runtime reports an active-child limit, halve the next batch and dispatch the remaining tasks — never relaunch the same oversubscribed fan-out.
4. **Audit** — run `scripts/audit-scope.mjs` from the skill base directory; revert or reassign out-of-scope changes. Run the build/test gate.
5. **Verify wave** — **freeze source changes**, run automated gates first (compile/tests/artifact), then 4–6 fresh verifiers by risk cluster (or 1–2 for a small domain task). Use `assets/verdict.schema.json` and, when available, `assets/verify.workflow.js`; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. Match evidence to the domain adapter: rerun commands, read rendered artifacts, sample citations, recompute metrics. For GUI products, use per-agent isolated displays, never a shared desktop (see `references/visual-testing.md`). If you fix findings, re-run only the affected **delta** and mark the old review stale.
6. **Integrate** — one integrator for shared files and cross-cutting fixes; re-run the full acceptance suite; then a final verification pass on the integrated build.
7. **Close** — freeze the build and run a final independent review against the original request (not the plan), then write `final-report.md`.
0. **Fit check & prerequisite gate** — go/no-go, budget (`max_agents`, `max_waves`, **tokens**), and **discover the available tools and real active-child cap** before sizing a wave. Check every required toolchain/runtime/service/display/credential with a real command; record the result in `.swarm/prerequisites.md` and `state.json`. Prefer project-local pinned setup; **never install globally/system-wide or run `sudo`/`curl | sh` without explicit user approval**. If a required prerequisite is missing and cannot be resolved safely, ask the user with the exact item, command, scope and alternatives **before any worker starts**. Workers never install; they return `blocked`.
1. **Resolve prerequisites** — after approval/install, re-run the checks and the baseline suite. No build or verify wave starts while a required item is `needs_user` or `blocked`; optional items may be skipped only with a recorded reduced scope. See `references/prerequisites.md`.
2. **Recon** — 2–4 parallel agents return findings with paths and line numbers. Timebox them, merge into `.swarm/brief.md` and `.swarm/map.md`, then stop them; recon must not hold slots during the build wave.
3. **Plan gate** — write `.swarm/plan.json`, `plan.md`, `ownership.md`, `contracts.md`, and one `tasks/Txx.md` per unit. Every success criterion maps to a task and a check. No two tasks write the same path. Include a `LEAD`/`INTEGRATOR` task owning lead-owned shared files, screenshots, licenses and the final report. Freeze interfaces. Prefer vertical slices and files under ~800 lines; a task that requires reading a 3k-line file is too broad. **Do not dispatch until this gate passes.**
4. **Build wave** — one `workflow` call per build wave when the tool exists, using the batched runner in `assets/wave.workflow.js`; its `concurrency` must fit the available slots (see Sizing). If `workflow`/`subagent` is unavailable, the lead executes the same packets sequentially. Retry `null`/`failed` once; if the runtime reports an active-child limit, halve the next batch and dispatch the remaining tasks — never relaunch the same oversubscribed fan-out.
5. **Audit** — run `scripts/audit-scope.mjs` from the skill base directory; revert or reassign out-of-scope changes. Run the build/test gate.
6. **Verify wave** — **freeze source changes**, run automated gates first (compile/tests/artifact), then 4–6 fresh verifiers by risk cluster (or 1–2 for a small domain task). Use `assets/verdict.schema.json` and, when available, `assets/verify.workflow.js`; the review file on disk is the source of truth, not the workflow return. Verifiers never fix. Match evidence to the domain adapter: rerun commands, read rendered artifacts, sample citations, recompute metrics. For GUI products, use per-agent isolated displays, never a shared desktop (see `references/visual-testing.md`). If you fix findings, re-run only the affected **delta** and mark the old review stale.
7. **Integrate** — one integrator for shared files and cross-cutting fixes; re-run the full acceptance suite; then a final verification pass on the integrated build.
8. **Close** — freeze the build and run a final independent review against the original request (not the plan), then write `final-report.md`.
## Hard rules
@@ -60,7 +61,8 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived
7. **Freeze during verification.** Once the verify wave starts, do not edit source/tests/docs except to fix a verified finding. After a fix, re-run the affected verifier; an old review is stale.
8. **Stop rules.** Two waves with no net progress → stop and re-plan. Verification failure rate > 30% → fix briefs/contracts, not agent count. Budget exhausted → report partial and list unverified areas.
9. **No shared visual desktop.** Visual agents get their own display/config/project copy; see `references/visual-testing.md`. A screenshot from a shared desktop is not evidence. Computer-use is a last-resort, single-agent tier on a disposable desktop/VM; it is never the sole evidence and never runs in parallel with other visual agents.
10. **Token budget is a quality constraint.** Record spend per phase, keep a 20–30% reserve for verification/integration, and stop at the hard cap with a partial report. Cut redundant context, agents, full-file reads and full re-reviews — never cut tests or independent review. See `references/token-economy.md`.
10. **Prerequisites before dispatch.** A required tool/runtime/service/credential is checked, installed with explicit approval if needed, and re-checked before workers start. Ask the user before work if it cannot be resolved; never let a worker install or silently skip a required check.
11. **Token budget is a quality constraint.** Record spend per phase, keep a 20–30% reserve for verification/integration, and stop at the hard cap with a partial report. Cut redundant context, agents, full-file reads and full re-reviews — never cut tests or independent review. See `references/token-economy.md`.
## Sizing
@@ -79,6 +81,7 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived
```
.swarm/
brief.md shared context: goal, domain, commands, conventions, hazards
prerequisites.md tool/runtime/display/credential gate + approvals
map.md repository/source map from recon: paths, entry points, hazards
contracts.md frozen interfaces between tasks
profile.md domain adapter: artifacts, commands, evidence types (optional)
@@ -91,7 +94,7 @@ Otherwise: one agent for small work; 2–5 `subagent` calls for a few long-lived
baseline.json pre-swarm file manifest (`--init`)
report.schema.json report contract for workers
verdict.schema.json minimal contract for verifiers
state.json wave, token budget/spend per phase, open issues
state.json wave, token budget/spend, prerequisites, open issues
final-report.md
tmp/T01/ worker scratch, never shared
```
@@ -109,6 +112,7 @@ For a `blocked` task: apply the smallest contract/shared-file change, update `co
- `references/orchestration.md` — `workflow` cookbook: script patterns, schema subset, retries, background runs, archetypes (code / research / content).
- `references/domains.md` — adapters for software, research, content, data, design and operations.
- `references/token-economy.md` — measurement, budgets, context discipline, delta verification, vertical slices.
- `references/prerequisites.md` — preflight checks, install/approval policy, degraded-scope record.
- `references/visual-testing.md` — isolated Xvfb/container visual tests, deterministic screenshots, verifier procedure (GUI adapter).
- `assets/` — copyable brief, task, and verifier templates; `report.schema.json`, `verdict.schema.json`; `wave.workflow.js` (batched workers), `verify.workflow.js` (frozen verification).
- `scripts/audit-scope.mjs` — compares changed files to the ownership map.