py-test-swarm
Core Role
Act as L1 orchestrator by default.
Decompose work into L2/L3 agents, enforce constraints, aggregate evidence, and produce final artifacts.
Startup Sequence
- Read memory:
../../../.ai/memory/agent-memory.md
../../../.ai/memory/memory-py-test-bot.md
../../../.claude/agents/ORCHESTRATION.md (sections 2-7)
- Read profile:
../../../.claude/agents/py-test-swarm.md
- Confirm input contract:
task-id (required)
mode (required): full-audit | fix-failures | coverage-boost | optimize | flakiness-scan
scope (optional, default all tests)
baseline-report (optional)
flakiness-runs (optional, default 5)
- Create artifact root:
reports/test-swarm/<task-id>/.
L1 Workflow
- Run Discovery baseline commands from l1-playbook.md.
- Build
00-swarm-plan.md with workload scores and parallel execution plan.
- Launch L2 agents with full task brief template from l2-l3-task-brief.md.
- Limit concurrent L2 agents to 4; run independent scopes in parallel.
- Collect all L2/L3
report.md, metrics.json, and telemetry JSONL.
- Build aggregated telemetry and flaky DB using telemetry-and-flaky-db.md.
- Produce
FINAL-REPORT.md from report-templates.md.
Decomposition Model
Use three axes:
- Architecture layers:
domain, application, infrastructure, composition, interfaces
- Test types:
unit, integration, e2e, architecture, contract, smoke, performance, security
- Infrastructure zones: adapters/providers, transformation, storage, DQ, retry/circuit-breaker, checkpoint/locking/heartbeat, observability, CLI
Delegation Rules
Calculate:
workload-score = files-count * complexity-factor * failing-factor * coverage-gap-factor
Decision:
< 40: self-execute
40-89: delegate to 2-3 child agents
>= 90: delegate to 4-6 child agents
Fallback delegation triggers (if formula is not practical):
- test files in scope
> 30
- failing tests
> 15
- modules without tests
> 10
- estimated runtime
> 20 min
- flaky rate
> 10% (spawn dedicated flaky triage agent)
Hierarchy limit: L1 -> L2 -> L3 only.
L2/L3 Protocol
L2 and L3 must follow 6 phases:
- Phase 0: discovery and workload scoring
- Phase 1: stabilization
- Phase 2: coverage expansion
- Phase 3: optimization
- Phase 4: telemetry/flakiness scan
- Phase 5: reporting
For L3 agents always prepend the mandatory leaf-agent instruction from l2-l3-task-brief.md.
Artifact Contract
Minimum required outputs:
reports/test-swarm/<task-id>/00-swarm-plan.md
reports/test-swarm/<task-id>/L2-*/report.md
reports/test-swarm/<task-id>/L2-*/metrics.json
reports/test-swarm/<task-id>/telemetry/raw/events-*.jsonl
reports/test-swarm/<task-id>/telemetry/aggregated/failure-stats.csv
reports/test-swarm/<task-id>/telemetry/aggregated/flaky-index.csv
reports/test-swarm/<task-id>/telemetry/failure-frequency-summary.md
reports/test-swarm/<task-id>/flakiness-database.json
reports/test-swarm/<task-id>/FINAL-REPORT.md
Constraints
MUST:
- Keep architecture boundaries and no I/O in domain.
- Use
uv run python -m pytest ... and uv run python -m mypy --strict ....
- Keep swarm changes in tests/reporting artifacts; do not modify production code unless explicitly requested outside swarm.
- Use VCR/respx for HTTP tests; keep secrets out of cassettes.
- Add regression tests for fixed failures when fixes are applied.
- Provide evidence (
file + lines + command) for architectural claims.
MUST NOT:
- Remove tests without rationale.
- Hide failures via unjustified
skip.
- Add test-only logic in
src/bioetl/.
- Exceed L3 depth.
- Leak secrets in logs/reports/cassettes.
Mode Matrix
full-audit: phases 0-5
fix-failures: phases 0-1
coverage-boost: phases 0 and 2
optimize: phases 0 and 3
flakiness-scan: phases 0 and 4
Completion Criteria
Treat task as done only when:
- all active agents wrote
report.md and metrics.json;
- L2 orchestrators aggregated L3 reports (if any);
- L1 generated
FINAL-REPORT.md;
- telemetry aggregates + flaky DB are generated;
- unresolved assumptions are explicitly marked
Requires Manual Review.
References
- L1 runbook and command sequence: l1-playbook.md
- L2/L3 task briefs and prompt templates: l2-l3-task-brief.md
- Report and metrics templates: report-templates.md
- Telemetry schema and flaky DB contract: telemetry-and-flaky-db.md
1---2name: py-test-swarm-23description: Orchestrate hierarchical BioETL test swarms (L1/L2/L3) for full-audit, fix-failures, coverage-boost, optimize, and flakiness-scan with workload-based delegation, telemetry aggregation, flaky analysis, and final reporting in reports/test-swarm/task-id/FINAL-REPORT.md. Use when users request broad test campaigns, failure triage at scale, coverage expansion, or stability diagnostics across layers/providers.4metadata:5 source: https://skillmd.com/skills/majiayu000/py-test-swarm-26---78# py-test-swarm910## Core Role11Act as L1 orchestrator by default.12Decompose work into L2/L3 agents, enforce constraints, aggregate evidence, and produce final artifacts.1314## Startup Sequence151. Read memory:16- `../../../.ai/memory/agent-memory.md`17- `../../../.ai/memory/memory-py-test-bot.md`18- `../../../.claude/agents/ORCHESTRATION.md` (sections 2-7)192. Read profile:20- `../../../.claude/agents/py-test-swarm.md`213. Confirm input contract:22- `task-id` (required)23- `mode` (required): `full-audit | fix-failures | coverage-boost | optimize | flakiness-scan`24- `scope` (optional, default all tests)25- `baseline-report` (optional)26- `flakiness-runs` (optional, default `5`)274. Create artifact root: `reports/test-swarm/<task-id>/`.2829## L1 Workflow301. Run Discovery baseline commands from [l1-playbook.md](references/l1-playbook.md).312. Build `00-swarm-plan.md` with workload scores and parallel execution plan.323. Launch L2 agents with full task brief template from [l2-l3-task-brief.md](references/l2-l3-task-brief.md).334. Limit concurrent L2 agents to 4; run independent scopes in parallel.345. Collect all L2/L3 `report.md`, `metrics.json`, and telemetry JSONL.356. Build aggregated telemetry and flaky DB using [telemetry-and-flaky-db.md](references/telemetry-and-flaky-db.md).367. Produce `FINAL-REPORT.md` from [report-templates.md](references/report-templates.md).3738## Decomposition Model39Use three axes:40- Architecture layers: `domain`, `application`, `infrastructure`, `composition`, `interfaces`41- Test types: `unit`, `integration`, `e2e`, `architecture`, `contract`, `smoke`, `performance`, `security`42- Infrastructure zones: adapters/providers, transformation, storage, DQ, retry/circuit-breaker, checkpoint/locking/heartbeat, observability, CLI4344## Delegation Rules45Calculate:46```text47workload-score = files-count * complexity-factor * failing-factor * coverage-gap-factor48```4950Decision:51- `< 40`: self-execute52- `40-89`: delegate to 2-3 child agents53- `>= 90`: delegate to 4-6 child agents5455Fallback delegation triggers (if formula is not practical):56- test files in scope `> 30`57- failing tests `> 15`58- modules without tests `> 10`59- estimated runtime `> 20 min`60- flaky rate `> 10%` (spawn dedicated flaky triage agent)6162Hierarchy limit: `L1 -> L2 -> L3` only.6364## L2/L3 Protocol65L2 and L3 must follow 6 phases:66- Phase 0: discovery and workload scoring67- Phase 1: stabilization68- Phase 2: coverage expansion69- Phase 3: optimization70- Phase 4: telemetry/flakiness scan71- Phase 5: reporting7273For L3 agents always prepend the mandatory leaf-agent instruction from [l2-l3-task-brief.md](references/l2-l3-task-brief.md).7475## Artifact Contract76Minimum required outputs:77- `reports/test-swarm/<task-id>/00-swarm-plan.md`78- `reports/test-swarm/<task-id>/L2-*/report.md`79- `reports/test-swarm/<task-id>/L2-*/metrics.json`80- `reports/test-swarm/<task-id>/telemetry/raw/events-*.jsonl`81- `reports/test-swarm/<task-id>/telemetry/aggregated/failure-stats.csv`82- `reports/test-swarm/<task-id>/telemetry/aggregated/flaky-index.csv`83- `reports/test-swarm/<task-id>/telemetry/failure-frequency-summary.md`84- `reports/test-swarm/<task-id>/flakiness-database.json`85- `reports/test-swarm/<task-id>/FINAL-REPORT.md`8687## Constraints88MUST:89- Keep architecture boundaries and no I/O in domain.90- Use `uv run python -m pytest ...` and `uv run python -m mypy --strict ...`.91- Keep swarm changes in tests/reporting artifacts; do not modify production code unless explicitly requested outside swarm.92- Use VCR/respx for HTTP tests; keep secrets out of cassettes.93- Add regression tests for fixed failures when fixes are applied.94- Provide evidence (`file + lines + command`) for architectural claims.9596MUST NOT:97- Remove tests without rationale.98- Hide failures via unjustified `skip`.99- Add test-only logic in `src/bioetl/`.100- Exceed L3 depth.101- Leak secrets in logs/reports/cassettes.102103## Mode Matrix104- `full-audit`: phases 0-5105- `fix-failures`: phases 0-1106- `coverage-boost`: phases 0 and 2107- `optimize`: phases 0 and 3108- `flakiness-scan`: phases 0 and 4109110## Completion Criteria111Treat task as done only when:112- all active agents wrote `report.md` and `metrics.json`;113- L2 orchestrators aggregated L3 reports (if any);114- L1 generated `FINAL-REPORT.md`;115- telemetry aggregates + flaky DB are generated;116- unresolved assumptions are explicitly marked `Requires Manual Review`.117118## References119- L1 runbook and command sequence: [l1-playbook.md](references/l1-playbook.md)120- L2/L3 task briefs and prompt templates: [l2-l3-task-brief.md](references/l2-l3-task-brief.md)121- Report and metrics templates: [report-templates.md](references/report-templates.md)122- Telemetry schema and flaky DB contract: [telemetry-and-flaky-db.md](references/telemetry-and-flaky-db.md)