swarm-implement - SKILL.md Agent Skill

name: swarm-implement description: Execute complex implementation work with a swarm-like Claude Code workflow: parallel exploration, scoped planning, objective validation, mandatory independent implementation review for changed work, and final critic approval. Use for feature work, bug fixes, refactors, and multi-file changes. disable-model-invocation: true

/swarm-implement

Use this skill for implementation work when you want Claude Code to behave like a fast, high-quality swarm rather than a single-threaded assistant.

Purpose

Complete real coding tasks across many projects while preserving Claude Code speed and adding swarm-style quality discipline.

Core operating model

Use this execution ladder:

Explore in parallel.
Build a scoped plan.
Implement in small, coherent units.
Run objective validation.
For any worktree edit, use independent reviewer validation on the latest diff and evidence.
For any worktree edit, use a separate final critic after reviewer approval.
Synthesize and report what changed, what was verified, and what remains risky.

This is not a slow full-swarm recreation. This is a speed-preserving, quality-maximizing workflow.

Command Namespace

Swarm commands: always /swarm — never bare subcommand names.

CRITICAL — these CC built-ins share names with swarm commands and MUST be avoided: /plan → use /swarm plan (reading) or do not invoke (entering plan mode) /reset → NEVER invoke — wipes conversation context /checkpoint → NEVER invoke bare — use /swarm checkpoint

HIGH — these CC built-ins produce wrong output: /status → use /swarm status (not CC /status)

Quality and speed policy

Quality and pre-ship defect detection are paramount.
Speed still matters.
Parallelism is the default speed lever.
Deep validation is concentrated where bugs are expensive.
Low-risk work should stay lightweight when extra depth would not materially improve quality.
High-risk work must always get the deeper validation path.

High-risk work

Always use the deeper validation path for:

auth, authz, identity, sessions, permissions
payments, billing, money movement, destructive actions
dependency changes, install scripts, lockfile changes
public API changes, schema changes, migrations
concurrency, queues, retries, state machines, caching
file access, subprocesses, parsing, secrets, security-sensitive logic
large cross-file refactors with correctness risk

Recommended workflow

Phase 0 — Establish scope

Determine the exact task scope first:

what changed or needs to change
what files are likely involved
what success looks like
what must not be broken
what verification is required

If the task is unclear, ask a small number of targeted questions or create a short written plan before coding.

Phase 0a — Parallel work check

Reference the parallel-work-check skill for the full protocol.

Before starting implementation on an existing branch, check for parallel work:

Fetch remote state and compare with local (git fetch + compare HEAD hashes).
If parallel swarm work is detected on the target branch:
- Read the new commits with git log origin/<branch> --not HEAD.
- Evaluate whether to integrate, supersede, or proceed with your planned work.
- Default stance: prefer the parallel swarm's work unless you can clearly articulate why your approach is better.
Document the decision before proceeding to Phase 1 using the PARALLEL WORK CHECK template from the parallel-work-check skill.

This check prevents wasted effort on stale branches and ensures you build on the latest remote state.

Phase 1 — Parallel exploration

Launch parallel subagents for disjoint investigation tasks such as:

repository mapping for relevant subsystems
locating existing patterns to follow
finding tests, schemas, contracts, and integration points
identifying likely side effects and touched modules
checking dependency or migration implications

Do not use the main thread for broad repo reading if subagents can do it. Keep the main context focused.

Phase 2 — Plan

Create a concrete implementation plan before editing for any non-trivial task. The plan should include:

files to change
intended behavior
risks and likely regressions
validation commands
whether reviewer and critic passes will be required

Phase 3 — Implement in scoped units

Implement in coherent, reviewable chunks. Avoid giant speculative rewrites. Follow existing repository patterns unless there is a strong reason not to.

Phase 4 — Objective validation

Always run the strongest objective checks available for the task:

tests
lint
typecheck
build
targeted repro scripts
local runtime verification where relevant

If you cannot verify it, do not claim it is done.

Phase 5 — Independent reviewer validation

Use an independent reviewer subagent when the task edits code, tests, docs, package metadata, release notes, or skill files. For read-only or answer-only tasks, scale this gate to the actual risk.

For changed-work tasks, this gate is mandatory when subagent delegation is available and swarm work is authorized. It is not satisfied by explorer output, plan critique, passing tests, or the implementation context reviewing its own work.

The reviewer must inspect the actual current diff and validation evidence after implementation. Any later edit invalidates the approval and requires re-review.

Reviewer responsibilities:

inspect the implementation with fresh context
look for correctness bugs, edge cases, regressions, claim-vs-actual mismatches, and test blind spots
be hyper-critical and suspicious
default to disbelief until evidence supports the change
identify whether issues are CONFIRMED, DISPROVED, UNVERIFIED, or PRE_EXISTING when useful
return APPROVE, NEEDS_REVISION, or BLOCKED

NEEDS_REVISION or BLOCKED blocks completion until fixed and re-reviewed.

This gate is especially important when the task is:

high-risk
cross-file
behavior-sensitive
likely to hide edge-case bugs
security-sensitive
likely to produce false confidence from the implementation context

Phase 6 — Critic challenge

Use a critic subagent after independent reviewer approval for any task that edits code, tests, docs, package metadata, release notes, or skill files. For read-only or answer-only tasks, use a critic only when risk justifies it.

The critic must challenge the reviewer-approved current diff and evidence, not the original plan. Any later edit invalidates the critic approval and requires another critic pass.

Critic responsibilities:

challenge reviewer conclusions and the final completion claim
look for requirement drift, weak evidence, missing sibling-file checks, package/docs/release drift, stale approvals, and poor actionability
return APPROVE, NEEDS_REVISION, or BLOCKED

NEEDS_REVISION or BLOCKED blocks completion until fixed and re-reviewed.

Phase 7 — Final synthesis

In the main thread, summarize:

what changed
what was verified
what reviewers found
what critic challenged
final remaining risks
whether the task is actually complete

Before final synthesis for changed-work tasks, record this gate in durable review artifacts. For issue-tracer work, use 08b-implementation-review.md and 09-final-critic.md. For other swarm implementation work, create or update task-local review artifacts with the reviewer verdict, critic verdict, commands reviewed, and responses to every blocker. If the repo forbids such artifacts, stop and disclose that limitation instead of claiming full swarm validation.

SWARM FINAL GATE
- Objective validation recorded: yes/no
- Independent implementation reviewer verdict on latest diff: APPROVE/...
- Final critic verdict on latest diff after reviewer approval: APPROVE/...
- Every NEEDS_REVISION/BLOCKED item fixed and re-reviewed: yes/no
- Latest edit occurred before final reviewer and critic approval: yes/no
- Fallback self-review used: no, or disclosed reason

If any answer is not satisfactory, do not claim completion.

Before declaring completion, run a no-unwired/no-deferred gate:

every new behavior is wired through config, registration, docs, tests, generated artifacts, and release notes as applicable,
no code path, command, skill, or documented feature is left unwired,
no work is deferred or declared out of scope without explicit user instruction,
no scope decision was made silently,
validation evidence covers every touched user-facing or runtime surface.

Hard rules

Do not let implementation context self-approve high-risk work.
Do not skip reviewer validation for high-risk work.
Do not skip objective verification because the code looks right.
Do not let perceived repo size or task size compress the workflow.
If quality and speed conflict, quality wins.
If extra validation does not materially improve quality, keep the path lightweight.
Never ship unwired code, silently defer work, or make scope decisions without explicit user instruction.

Suggested subagent prompts

Explorer-style

Use for broad discovery:

map the assigned subsystem quickly
identify likely files, patterns, contracts, tests, and risks
return a concise actionable summary
do not edit code

Reviewer-style

Use for implementation validation:

review the implementation with fresh context
be hyper-critical and suspicious
look for edge cases, regressions, hidden coupling, and claimed-vs-actual mismatches
verify whether the tests actually prove behavior
return only high-signal findings

Critic-style

Use for final challenge:

challenge high-impact conclusions
check whether findings are overclaimed or weakly evidenced
challenge severity and actionability
look for what the previous layer may have missed

Use across many repos

This skill is intentionally project-agnostic. It should adapt to each repository by exploring first, following local patterns, and scaling validation depth to actual risk.