---
name: repo-swarm
description: >-
  Run a repository-wide review swarm, ask the user how to handle each finding, then create a linear stacked PR series with one PR per accepted fix. Use when the user asks for "repo-swarm", for a whole-repo swarm, or for constrained scopes such as "repo-swarm all the code under foo/".
title: repo-swarm
canonical_url: https://skilld.dev/gh/scode/dotfiles/repo-swarm
last_updated: 2026-10-25T20:28:40.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install scode/dotfiles/repo-swarm`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/repo-swarm`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/scode/dotfiles/repo-swarm) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/repo-swarm`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/repo-swarm --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/repo-swarm --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# repo-swarm

Use this skill when the user wants a repository-wide quality pass that turns review findings into a clean stack of small
PRs. This is intentionally heavier than a normal review. The point is to find issues across a chosen scope, decide which
ones are real work, and land each accepted fix as its own reviewable PR.

Use the `pre-pr-review-swarm` skill for review passes. Use the `jjstack` skill for creating and updating the linear PR
stack. Adhere to the repo's own instructions for commit titles, PR titles, validation commands, formatting, comments,
and tests.

## Scope

Default scope is the whole repository. If the user gives constraints, keep both the initial review and all follow-up
fixes inside that scope unless fixing an issue requires touching a nearby support file. Examples:

- `repo-swarm`
- `repo-swarm the entire codebase`
- `repo-swarm all the code under foo/`
- `repo-swarm only the CLI commands`

State the interpreted scope before launching the initial review. If the scope is ambiguous but a reasonable reading
exists, proceed with that reading and say what you assumed.

## Initial Review

Run the `pre-pr-review-swarm` skill in `nofix` mode against the chosen scope. This initial pass is not a PR review. It
is a finding-generation pass over the selected repository area.

If the existing `pre-pr-review-swarm` workflow is diff-oriented, adapt the reviewer prompts so each reviewer reviews the
chosen scope directly. Keep the same reviewer categories, deduplication rules, and output discipline: actionable
findings only, tagged as definite or possible, with feedback identifiers, file references, and a short rationale.

After the initial review, merge and deduplicate findings. Do not start fixing yet.

## User Triage

Immediately after the initial review only, ask the user what to do with each finding. Do not ask this again for findings
discovered during individual PR review swarms; those are handled by the normal fix/reject rules below.

For each initial finding, present these three choices:

- **Fix it**: implement the fix and create a dedicated PR for it.
- **Ignore it**: do nothing for this finding. Record it in the final summary as ignored.
- **Document as intentional in `SPEC.md`**: update `SPEC.md` to make the behavior explicit. If `SPEC.md` does not exist,
  create it. If `AGENTS.md` exists and does not already require agents to conform to `SPEC.md`, update it to say agents
  must always conform to `SPEC.md`. If `AGENTS.md` is a symlink, edit the target file.

Interactive triage can be a compact checklist, but the user must make an explicit choice for every finding before
implementation starts. If several findings are duplicates or should clearly be handled by one change, ask whether to
combine them into one PR. Otherwise, default to one PR per accepted finding.

## Stack Shape

Create a linear stack. Each accepted finding becomes exactly one reviewable commit, one stable bookmark, and one PR,
unless the user explicitly approves combining findings.

Use the `jjstack` skill for the mechanics:

- Start from the current trunk/default branch or from the top of any existing stack the user asked to extend.
- Keep one stable bookmark per PR.
- Create PRs in bottom-up order.
- Each PR base must be the previous accepted PR's bookmark, or the default branch for the bottom PR.
- Push only the affected bookmarks.
- If rewriting a lower PR moves descendants, push every affected descendant bookmark and update GitHub PR bases when
  needed.

Use conventional commits and conventional PR titles if the repo instructions require them. Otherwise still keep titles
short and factual.

## Per-Finding Workflow

For each accepted finding, in stack order:

1. Move to the current top of the stack.
2. Implement only that finding's fix. Keep the diff narrow.
3. Add or update tests for behavior changes. If tests cannot be added, stop and ask for approval before continuing
   without them.
4. Run the repo's relevant local validation for that fix.
5. Run the `pre-pr-review-swarm` skill on the individual fix before creating the PR. This review should be scoped to the
   pending diff for that one fix.
6. Handle individual-fix review findings:
   - **Fix** findings that are clearly correct and improve the PR without major trade-offs.
   - **Reject** findings that are wrong, based on a misread, already addressed, or outside the PR's scope. Keep the
     reason for the final summary.
   - **Surface for user decision** only when the finding involves a real trade-off, API/behavior change, or scope
     expansion.
7. After applying any individual-fix review changes, rerun the relevant validation and rerun the `pre-pr-review-swarm`
   skill on that same PR until it is clean or only rejected/surfaced findings remain.
8. Commit the final diff, set or move the bookmark, push it, and create or update the PR.
9. Move to the next accepted finding.

Do not create a PR before the individual-fix `pre-pr-review-swarm` is clean enough to explain. The PR should be
review-ready at creation time.

## Documenting Intentional Behavior

When the user chooses "document as intentional in `SPEC.md`", treat that as its own accepted change. Create a dedicated
PR that updates `SPEC.md` and, if needed, the agent instruction file.

The `SPEC.md` entry should state the required behavior, the rationale, and any important constraints future code must
preserve. Do not write a vague note like "this is intentional"; make the intended behavior testable enough that future
reviews can use it.

If `AGENTS.md` needs updating, add a short instruction such as:

```markdown
Agents must conform to `SPEC.md`. If implementation and `SPEC.md` disagree, treat that as a bug or explicitly update
`SPEC.md` in the same change.
```

If there is already an equivalent instruction, do not duplicate it.

## Validation

Follow the repo's own validation instructions. If no repo-specific validation exists, run the relevant available checks
for the files touched, then run the broad test/lint/format commands that are practical for the project.

After all PRs have been opened or updated, check GitHub CI for the whole stack from bottom to top. Start with the bottom
PR because every descendant depends on it being correct. For each PR:

1. Wait for GitHub checks to finish.
2. If any check fails, inspect the failing check logs and fix the issue in that PR's commit.
3. Rerun the local validation that matches the failure.
4. Run the individual-fix `pre-pr-review-swarm` again if the fix changed behavior or materially changed the diff.
5. Push the updated bookmark.
6. Push every affected descendant bookmark and update GitHub PR bases if the lower fix moved the stack.
7. Recheck GitHub CI for the repaired PR before moving upward.

Do not treat the repo-swarm as done while any PR in the stack has pending, failing, missing, or cancelled required
checks. The final state must be that every PR in the stack is open, has the intended base, and is passing GitHub CI.

Before the final response, verify:

- every accepted fix has a PR,
- each PR has had its own `pre-pr-review-swarm` pass before creation or update,
- the GitHub PR bases match the local linear stack,
- every PR in the stack is passing GitHub CI,
- the working copy is clean,
- final validation has passed, or any failures are clearly reported.

## Final Summary

Keep the final summary compact. Include:

- initial findings and the user's triage decisions,
- PR links in stack order,
- fixes made during individual PR review swarms,
- rejected individual-PR findings with reasons,
- ignored initial findings,
- validation commands and results,
- GitHub CI status for every PR,
- current working-copy status.

Do not imply that ignored findings were fixed. Do not merge the stack unless the user explicitly asks.
