| name | parallel-spec-fleet |
| description | Orchestrate the test-writer, qa-reviewer, and security-reviewer subagents to cover several user flows of the AI Skill Path Picker app AT ONCE. Use whenever Tim wants to demonstrate parallel subagents on stage, or needs end-to-end Playwright coverage across more than one flow in a single pass. Fans out test-writer across N flows concurrently, pipes each spec to qa-reviewer, and runs security-reviewer against the confirm.js innerHTML landmine in parallel. |
Parallel Spec Fleet
A one-command orchestration that puts multiple subagents to work at the same time against this app, then funnels their output through the real handoff contract. Built for the live Author Talk: it makes the fleet visible.
What this skill is for
- The demo: show three subagents (
test-writer, qa-reviewer, security-reviewer) working concurrently, not single-file.
- The work: generate and verify Playwright coverage for several flows of the AI Skill Path Picker in one pass instead of one flow at a time.
What this skill is NOT for
- A single flow. For one spec, just invoke
test-writer directly and let it run playwright-spec-generator.
- Anything needing a backend. This app has none — there is no network call anywhere.
The cast (read their contracts before dispatching)
| Subagent | Job | Never does |
|---|
test-writer | Writes ONE .spec.js per flow via the playwright-spec-generator skill. data-testid selectors only. | Run tests. |
qa-reviewer | Runs a spec, audits it, returns APPROVED or REJECTED with line-cited defects. | Edit specs. |
security-reviewer | Hunts the confirm.js innerHTML smell and similar issues. | Touch app behavior. |
The handoff strings are load-bearing. test-writer ends with SPEC WRITTEN / COVERAGE / HANDOFF TO: qa-reviewer. qa-reviewer ends with APPROVED or REJECTED / HANDOFF TO: test-writer. Do not let one agent do another's job.
Procedure
Step 0 — Preflight
- Confirm the dev server is up at
http://localhost:3000. If not, ask Tim to run cd app; npm run dev in a separate terminal (or ! npm run dev in-session).
- Inventory the selector surface ONCE so every
test-writer shares the same ground truth:
node .claude/skills/playwright-spec-generator/scripts/scan-testids.mjs app/public
Keep this table; pass it to each test-writer so none of them re-scan or hallucinate selectors.
Step 1 — Pick the flows to fan out
Default fleet (three flows, all backed by real data-testids):
| Flow | testids it exercises | Crosses pages? |
|---|
enroll-happy-path | path card → full-name-input, email-input, role-select, selected-path, submit-enroll → confirm-*, confirmation | Yes (needs a POM) |
enroll-form-validation | enroll-form, email-input, form-error (and assert NO navigation to confirm) | No |
path-selection-carryover | the four enroll-* cards on index.html → selected-path on enroll | Yes |
Let Tim override the list. If he names a flow whose control has no data-testid, that is the teaching moment — the dispatched test-writer will STOP and ask to add the attribute. Do not paper over it.
Step 2 — Fan OUT test-writer (the parallel beat)
Dispatch one test-writer subagent per flow, in a single message with multiple Agent tool calls so they run concurrently. This is the visible parallelism — three agents drafting three specs at once.
Each dispatch prompt must include:
- The flow name and a plain-language description of the journey.
- The shared
data-testid table from Step 0.
- The instruction: "Follow the
playwright-spec-generator skill. Selectors are data-testid only. Do not run the tests. Return your SPEC WRITTEN / COVERAGE / HANDOFF TO: qa-reviewer line."
Collect each agent's handoff line. If any test-writer halts asking for a missing testid, surface that to Tim verbatim — it is a feature of the demo, not a failure.
Step 3 — Pipe each spec to qa-reviewer (concurrent verify)
As specs land, dispatch one qa-reviewer per spec — again concurrently, one message, multiple Agent calls. Each reviewer runs its own spec:
cd app && npx playwright test ../tests/<flow>.spec.js --reporter=list
and returns APPROVED or REJECTED with line-cited defects.
Use a pipeline mindset, not a barrier: a spec that finishes review first does not wait for its siblings. If a spec is REJECTED, route the defect list back to a fresh test-writer for that one flow only — leave the approved specs alone.
Step 4 — Run security-reviewer in parallel (independent track)
In the SAME parallel wave as Step 2 or Step 3 (it has no dependency on the specs), dispatch security-reviewer against the app's known smell:
Review app/public/scripts/confirm.js for DOM-injection / XSS-shaped issues.
Report severity and cite file:line. Do not edit app behavior.
It should surface the empty-state innerHTML render. This proves the fleet does more than one KIND of work at once: authoring, verifying, and securing.
Step 5 — Synthesize the board
Report a single status table back to Tim:
| Flow / track | Subagent chain | Status |
|---|
| enroll-happy-path | test-writer → qa-reviewer | APPROVED / REJECTED |
| enroll-form-validation | test-writer → qa-reviewer | … |
| path-selection-carryover | test-writer → qa-reviewer | … |
| confirm.js security | security-reviewer | finding(s) |
Only after every chain reads APPROVED (and the security finding is acknowledged) is the branch ready to commit.
Guardrails
- Parallel where independent, sequential where dependent. test-writer instances are independent (fan out). A given spec's qa-reviewer depends on that spec existing (per-flow chain). security-reviewer is independent of all of them.
- Do not let a subagent cross lanes. test-writer never runs tests; qa-reviewer never edits; security-reviewer never changes behavior.
- Do not fix landmines silently. The
confirm.js innerHTML, the vulnerable dependencies, the CodeQL bait, and the planted secrets are intentional. Surface, never auto-remediate, unless Tim explicitly asks for a remediation demo.
- Selectors are
data-testid only. This is the rule the whole fleet defends.
Quickref
| Need | Move |
|---|
| Inventory selectors once | scan-testids.mjs app/public |
| Fan out authors | N× test-writer in ONE message |
| Verify concurrently | N× qa-reviewer in ONE message |
| Security track | 1× security-reviewer, same wave |
| Re-author on reject | fresh test-writer for that flow only |
