implement

Imported from MisterVitoPro/qa-swarm (skills/implement/SKILL.md). Install upstream with npx skills add MisterVitoPro/qa-swarm --skill implement. Copyright stays with the author.

Orchestrate QA Swarm implementation: write tests, fix code, and loop until green. Parse the three file paths (and the optional --model option) from the text supplied with the skill invocation.

Model selection

Three model tiers are supported: opus, sonnet, and haiku. Each dispatch below lists its default. The user can override the whole run with one option:

• --model opus | --model sonnet | --model haiku anywhere in the invocation text (also accept model=opus and plain-language forms such as "use opus").
• Remove the option from the text before parsing the three file paths.
• Store the result as swarm_model. When absent, swarm_model is auto and every role uses its default (TDD writers: sonnet, P0 implementation: opus, P1-P3 implementation: sonnet).

When swarm_model is set, pass it as the model for EVERY agent dispatched by this skill. Model labels are recommendations; if the host cannot provide the requested tier, use the closest available model and print one line saying which model was substituted -- never block the run.

Host model mapping

Tier names are host-neutral. Resolve each role's tier (default or swarm_model) and translate it to the host's model name at dispatch time:

On Codex, also accept --model terra (= opus) and --model luna (= sonnet) as aliases. Keep printed labels in tier terms and show the mapped name the first time each tier is used on Codex (for example opus -> Terra).

Portable role loading and dispatch

Resolve bundled files relative to this SKILL.md, not the current working directory. The role directory is ../../agents/ from this file. Before dispatching a qa-tdd test writer, read ../../agents/qa-tdd.md and include its body in the subagent prompt. Claude Code may expose bundled files as namespaced agent types, but never depend on that registration.

Use the host's native subagent facility. Parallelize independent test-writer slices in one batch when supported. Model labels are recommendations; use the closest available model without blocking. Use an available structured-input facility at user gates, or ask in plain chat when none exists.

Progress Tracking

Use the host's progress/task facility when available. Otherwise maintain and print a concise checklist with the same task hierarchy and update it after each transition. The user should always be able to see what has been done, what is in progress, and what remains.

Reference the implementation plan: The spec and report files contain the prioritized findings and fix details. All tasks you create should reference the relevant finding IDs and spec sections so that agents and the user can trace each task back to the plan.

Task Creation Strategy

After ingesting the report and the user selecting phases, create tasks structured as follows:

1. One top-level task per selected phase (e.g., "Phase 1: P0 Critical (3 issues)")
2. One sub-task per individual finding within that phase (e.g., "Fix P0-001: SQL injection in get_user_by_id")
3. Pipeline tasks for cross-cutting steps (e.g., "TDD Setup", "Final Test Run", "Write Results Report")

Task Status Updates

Mark tasks in_progress when starting work on them. Mark completed immediately when done -- do not batch completions. If a task fails or is skipped, update it with the reason.

Use these conventions in task descriptions:

• Include the finding ID (e.g., P0-001) and title
• Reference the spec file and section for fix details (e.g., "See {spec_path} > P0 Fixes > Fix P0-001")
• Include the relevant test file path once TDD setup is complete
• For retry tasks, include the attempt number and prior error

IMPORTANT: Before modifying any code, verify that the current working tree is clean or committed. If there are uncommitted changes, warn the user:

Warning: You have uncommitted changes. If fixes go wrong, you may lose work.
Recommendation: Commit or stash your changes before proceeding.
Continue anyway? (Y/n)

Wait for confirmation before proceeding.

Arguments

Parse the three file paths from the skill invocation input, after removing any --model option.

Expected: <report_path> <spec_path> <test_plan_path> [--model opus|sonnet|haiku]

Step 1: VALIDATE AND INGEST

1. Parse the three file paths from the arguments. If fewer than three paths are provided, print:

   Error: Expected 3 file paths, got {N}.
   
   Claude Code: /qa-swarm:implement <report.md> <spec.md> <test_plan.md> [--model opus|sonnet|haiku]
   Codex: $qa-swarm:implement <report.md> <spec.md> <test_plan.md> [--model opus|sonnet|haiku]
   Example: $qa-swarm:implement docs/qa-swarm/2026-04-02-report.md docs/qa-swarm/2026-04-02-spec.md docs/qa-swarm/2026-04-02-tests.md
   
   Run the QA Swarm attack skill first to generate these files.
   

   Then STOP.

2. Check that all three files exist. For EACH missing file, collect the error. If any are missing, print:

   Cannot start implementation -- missing files:
     {path_1}  <-- not found
     {path_2}  <-- not found
   
   Expected files in docs/qa-swarm/:
     {date}-report.md   (ranked findings)
     {date}-spec.md     (implementation spec)
     {date}-tests.md    (TDD test plan)
   
   Run the QA Swarm attack skill first to generate these files.
   

   Then STOP.

3. Read all three files.

4. Parse the report to extract findings grouped by priority (P0, P1, P2, P3).

5. Count total findings per priority level. If total findings is 0, print:

   No findings to implement -- the report contains 0 actionable findings.
   

   Then STOP.

6. Check for an existing results file at docs/qa-swarm/{DATE}-results.md.

   • If found, read it and mark already-fixed issues as complete.
   • This enables incremental runs across sessions.

Step 2: PHASE SELECTION

Present the user with a summary table and let them choose what to tackle:

QA Swarm Implementation
========================
Report:    {report_path}
Spec:      {spec_path}
Test Plan: {test_plan_path}

 Phase | Priority    | Issues | Status
-------|-------------|--------|------------
   1   | P0 Critical |   {N}  | {status}
   2   | P1 High     |   {N}  | {status}
   3   | P2 Medium   |   {N}  | {status}
   4   | P3 Low      |   {N}  | {status}

Status key: Not started | Partial (N/M) | Done (N/N)

Options:
  [A]   All phases (P0 -> P1 -> P2 -> P3)
  [1]   Phase 1 only
  [2]   Phase 2 only
  [3]   Phase 3 only
  [4]   Phase 4 only
  [1-2] Phases 1 through 2
  [1,3] Phases 1 and 3

Select phases:

Wait for user selection before proceeding. Parse their input to determine which phases to run.

Create Tasks After Phase Selection

Once the user selects phases, create the full task tree with the host's progress/task facility or the fallback checklist:

1. Create a pipeline task: "TDD Setup: Write test files for selected phases"
2. For each selected phase, create a phase task:
   • "Phase 1: P0 Critical ({N} issues)" with description referencing the spec: "Fix {N} P0 findings. See {spec_path} > P0 Fixes for implementation-ready details. Strict ordering: one at a time, 4 retry max, halt on failure."
3. For each finding within each selected phase, create a sub-task:
   • "Fix {finding_id}: {title}" with description: "Location: {file}:{line}. Fix details: {spec_path} > P0 Fixes > Fix {finding_id}. Test: {test_file_path (once known)}. Confidence: {confidence}. Corroborated by: {N} agents."
4. Create pipeline tasks for wrap-up:
   • "Final test suite verification"
   • "Write results report to docs/qa-swarm/{DATE}-results.md"

Step 3: TDD SETUP (3 parallel test-writer agents)

Mark the TDD Setup task as in_progress.

3a. Detect Context7 MCP availability

Check whether the Context7 MCP server is available in this session by looking for the tools mcp__context7__resolve-library-id and mcp__context7__query-docs. Record the result as context7_available: true | false. You will pass this flag to each test-writer agent.

If available, print: Context7 MCP detected -- test-writer agents will use it for current framework docs. If not available, print: Context7 MCP not detected -- test-writer agents will rely on existing test conventions only.

3b. Partition the test plan across 3 agents

1. Read the test plan file and filter to findings in the SELECTED PHASES ONLY. Skip any finding already marked ALREADY COVERED in the plan.
2. Group the remaining findings by their test_file_path. Each group represents one test file's worth of work.
3. Distribute the groups across up to 3 buckets, balanced by the total number of test cases per bucket. Rule: each test file is assigned to exactly one bucket -- no two agents ever write the same file (prevents write conflicts).
4. If there are fewer than 3 distinct test files, use fewer agents (1 agent per file). Do not spawn empty agents.
5. Name the buckets slice-A, slice-B, slice-C.

Print a partition summary:

TDD partitioning:
  slice-A: {N} findings across {M} test files
  slice-B: {N} findings across {M} test files
  slice-C: {N} findings across {M} test files

3c. Launch 3 qa-tdd agents in parallel

Launch the test-writer agents in one parallel batch when supported. Include the full qa-tdd role definition loaded from ../../agents/qa-tdd.md in every prompt. Each agent (default model: sonnet, or swarm_model when set; Mode 2) receives:

• Its assigned slice of the test plan (only its bucket's findings + test code blocks, inlined into the prompt)
• The list of test file paths it owns -- with an explicit instruction that it MUST NOT write to any file outside this list
• The context7_available boolean
• Conventions guidance: read 2-3 existing test files in the project to detect framework, naming, and file layout before writing
• Instruction: DO NOT run the test suite. The orchestrator runs the suite once after all 3 agents finish.

Each agent returns a structured JSON summary:

{
  "slice": "slice-A",
  "files_written": ["tests/unit/test_auth.py", ...],
  "tests_written": [{"finding_id": "P0-001", "test_name": "test_sql_injection_login", "file": "..."}],
  "context7_queries": [{"library": "pytest", "purpose": "confirm fixture API"}],
  "skipped": [{"finding_id": "...", "reason": "..."}]
}

3d. Run the full test suite once

After all 3 agents return, run the FULL test suite (detected test command for the project).

Classify each new test:

• FAIL (expected): finding stays in the implementation queue -- red phase verified.
• PASS (unexpected): finding is likely already fixed or false positive. Remove from queue, print:

  Tests already passing (removed from queue):
    - {finding_id}: {title} -- likely already fixed or false positive
  

  Mark that finding's sub-task completed with the "already passing" note.
• ERRORED (did not run): treat as a TDD setup bug. Print the error, mark the sub-task in_progress with a note, and continue -- the fix agent in Step 4 may correct it.

Update each remaining finding sub-task description to include its test file path.

Mark the TDD Setup task as completed.

Step 4: PHASE EXECUTION

Execute selected phases in priority order (P0 always runs first even if user selected [2,1]).

P0 Phase (Strict Ordering)

Mark the Phase 1 task as in_progress.

For EACH P0 finding, one at a time:

1. Mark the finding sub-task as in_progress.

2. Print: Fixing P0: [{finding_id}] {title} (attempt 1/{max_retries})

3. Launch an implementation agent (default model: opus, or swarm_model when set) with:

   • The specific P0 finding from the report
   • The implementation-ready fix steps from the spec (tell the agent: "Read {spec_path} > P0 Fixes > Fix {finding_id} for the exact steps.")
   • The relevant test file(s) for this finding
   • Instruction: "Read the spec's fix steps for this finding. Implement the fix exactly. Do not modify test files."

4. After the agent completes, run the FULL test suite (not just the new tests).

5. Check results:

   • All tests pass: Print P0 [{finding_id}] FIXED. Mark the sub-task as completed. Move to next P0.
   • New test failures appeared: The fix broke something.
     • Launch the implementation agent again with the error output.
     • Instruct: "Your fix for {finding_id} caused these test failures: {failures}. Fix the regression without reverting the original fix."
     • Retry up to 4 total attempts. Update the sub-task description with each attempt's outcome.
   • After 4 failed attempts: HALT. Update the sub-task with: "HALTED after 4 attempts. Last error: {error}. Awaiting user guidance."

     HALTED: P0 [{finding_id}] could not be fixed after 4 attempts.
     
     What was tried:
     {summary of each attempt}
     
     Last error:
     {test output}
     
     Options:
       1. Type your fix guidance and I will retry
       2. Type "skip" to move on
       3. Type "abort" to stop implementation entirely
     

     Wait for user input. If they provide guidance, retry with their instructions. If "skip", mark sub-task as completed with note "Skipped by user". If "abort", jump to Step 5.

Mark the Phase 1 task as completed when all P0 findings are processed.

P1-P3 Phases (Batched by Priority)

For each selected priority level (P1, then P2, then P3):

1. Mark the phase task as in_progress. Mark all finding sub-tasks in this phase as in_progress.

2. Print:

   Implementing {N} P{level} fixes...
   

3. Launch an implementation agent (default model: sonnet, or swarm_model when set) with:

   • All findings for this priority level from the report
   • The corresponding fix details from the spec (tell the agent: "Read {spec_path} > P{level} Fixes for approach details.")
   • The relevant test files
   • Instruction: "Implement all these fixes. Read the spec for approach details. Do not modify test files."

4. After the agent completes, run the FULL test suite.

5. Check results:

   • All tests pass: Print P{level} fixes complete: {N}/{N} fixed. Mark all sub-tasks and the phase task as completed.
   • Some tests fail: Identify which findings' tests are still failing.
     • Launch the implementation agent again with the failures.
     • Retry up to 2 total attempts.
   • After 2 failed attempts: Skip the failing fixes. Mark passing sub-tasks as completed. Mark failing sub-tasks as completed with note: "Unresolved after 2 attempts: {error_summary}".

     Skipped {N} P{level} fixes (unresolved after 2 attempts):
       - [{finding_id}] {title}: {error_summary}
     

     Mark the phase task as completed. Continue to next priority level.

Step 5: PHASE COMPLETE + CONTINUE PROMPT

After all selected phases finish:

1. Mark the "Final test suite verification" task as in_progress.

2. Run the full test suite for verification.

3. Mark it as completed.

4. Mark the "Write results report" task as in_progress.

5. Update the results file incrementally at docs/qa-swarm/{DATE}-results.md.

6. Mark it as completed.

7. Print phase summary:

   Phase(s) complete.
   Fixed:      {N}/{N} issues
   Unresolved: {N} issues
   Halted:     {N} (required intervention)
   Tests:      {N} passing, {N} failing
   

8. If unselected phases remain, present the continue prompt:

   Remaining phases:
   
    Phase | Priority    | Issues | Status
   -------|-------------|--------|------------
      3   | P2 Medium   |   {N}  | Not started
      4   | P3 Low      |   {N}  | Not started
   
   Continue? [3/4/3-4/A/done]
   

9. If user selects more phases:

   • Create new phase tasks and finding sub-tasks for the newly selected phases (same structure as Step 2).
   • Create new pipeline tasks for the next round's TDD setup, final test run, and results update.
   • Loop back to Step 3 (TDD Setup for new phases).

10. If user selects "done" or no phases remain, proceed to Step 6.

Step 6: FINAL REPORT

Get today's date and save/update the results:

Write to docs/qa-swarm/{DATE}-results.md:

# QA Swarm Implementation Results
**Date:** {DATE}
**Source spec:** {spec_path}
**Duration:** {elapsed time if available}

## Summary
- Fixed: {N}/{total} issues
- Unresolved: {N} issues
- Halted: {N} P0s (required human intervention)
- Skipped (phases not selected): {N} issues
- Already passing: {N} issues

## Test Results
- Total tests: {N}
- Passing: {N}
- Failing: {N}

## Fixed Issues
{for each fixed issue}
### [{finding_id}] {title}
**Priority:** {P0|P1|P2|P3}
**Phase:** {N}
**Attempts:** {N}
**Fix applied:** {brief description of what was changed}
**Files modified:** {list}

## Unresolved Issues
{for each unresolved issue}
### [{finding_id}] {title}
**Priority:** {P0|P1|P2|P3}
**Attempts:** {max_retries}
**Last error:** {error message}
**What was tried:** {brief summary}
**Recommendation:** {what a human should look at}

## Halted Issues
{for each halted P0}
### [{finding_id}] {title}
**Attempts:** 4
**What was tried:** {summary of all 4 attempts}
**Why it failed:** {analysis}
**Recommendation:** {what needs human attention}

## Phases Not Selected
{list of phases the user chose not to run, with issue counts}

## Already Passing (Skipped)
{for each finding whose tests already passed}
- [{finding_id}] {title} -- {likely already fixed / false positive}

Print the summary:

QA Swarm Implementation Complete
===================================
Fixed:      {N}/{total} issues
Unresolved: {N} issues
Halted:     {N} P0s
Skipped:    {N} (phases not selected)
Already OK: {N} (tests already passing)

Tests: {passing} passing, {failing} failing

Results: docs/qa-swarm/{DATE}-results.md

Next steps:
  1. Review changes:  git diff
  2. Run your tests:  {detected test command, or "your test command"}
  3. Run linter:      {detected lint command, if any}
  4. Commit:          git add -A && git commit -m "fix: resolve QA swarm findings"
  5. Open a PR for review