# Swarm Improve

> Planner-led repo improvement loops with subagents, review gates, Mermaid DAGs, and workflow-aware commits. Use for improve, refactor, audit, or continue-loop requests.

- Skill: `george-rd/swarm-improve` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add george-rd/swarm-improve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/george-rd/swarm-improve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: george-rd (https://skillmd.com/u/george-rd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/george-rd/swarm-improve

---


# Swarm Improve

Use this skill for repo improvement loops that benefit from subagents and review gates.

Core principle: small ranked tasks, independent workers, explicit evidence, review before submit, stop at diminishing returns. This is Jcode's lightweight first-class RPI-style loop: plan, implement, validate, review, learn, and continue only while value remains clear.

## Default loop

1. Inspect repo state: working tree, branch workflow, docs, tests, active specs, and recent commits.
2. Write or refresh a ranked `todo` list with 3-7 high-leverage safe improvements.
3. Choose a review budget from `references/review-budget.md` before dispatching work.
4. If 3+ tasks have non-obvious dependencies, put a small Mermaid DAG in the visible progress update or swarm shared context.
5. Dispatch implementer subagents with `subagent` for bounded tasks, or `swarm spawn/assign_task` only for persistent multi-agent coordination.
6. Before parallel workers, map intended files to owners, order dependencies, cap at 4 workers per wave by default, and serialize overlapping file claims.
7. Choose and run validation gates by change type after each meaningful diff or wave. When behavior, UI/UX, CLI/TUI, docs/config, or refactor risk is in scope, use `references/change-type-validation.md` to confirm the gate.
8. Use `simplify` based on change scale: inline/skip for tiny fixes, normal pass after medium or large implementation, repeat only if review feedback causes medium or large code changes.
9. Use `request-code-review` as the main review entrypoint. Use quick/standard/deep mode based on risk; deep mode calls `deep-review` for milestone, risky, process-sensitive, high-impact, or pre-submit diffs.
10. If simplify, review, or gates fail, loop back within the caps in `references/review-budget.md`. If clean, commit with the repo's native workflow.
11. At checkpoints, use `references/development-checkpoints.md`: review the plan before code when scope is non-obvious, refactor/extend tests, create follow-ups for valid out-of-scope findings, capture durable learnings when high-value, and rerun broader validation before the next wave.
12. Reassess. Continue only while remaining work is clearly worth the churn.

## Context funnel

Keep this skill light. Read references only when needed:

- `references/planner-led-loop.md`: task DAGs, waves, claims, checkpoints, and dead-letter handling.
- `references/review-budget.md`: task-size budgets, scale-based simplify repeats, loop caps, and reviewer arbitration.
- `references/development-checkpoints.md`: planning review, milestone simplify/review, and out-of-scope follow-up rules.
- `references/change-type-validation.md`: route backend, UI/UX, CLI/TUI, docs/config, and refactor work to appropriate validation gates.
- `references/model-routing.md`: choose kimi, minimax, Claude, or inline work when dispatching non-trivial subagents or adversarial review.
- `references/mermaid-patterns.md`: compact workflow diagrams for plans, simplify, reviews, loopbacks, and checkpoints.
- `references/repo-workflow-adapters.md`: Graphite, OpenSpec/cflx, and generic repo workflow checks.
- `references/subagent-prompt-template.md`: implementer prompt template with gates and reporting.
- `references/evidence-packets.md`: compact shared context packets for workers and reviewers.
- `references/pre-post-mortem.md`: lightweight risk prediction and learning checkpoints.
- `assets/swarm-improve-loop.mmd`: default end-to-end loop diagram.
- `scripts/validate.sh`: behavioral contract checks for this skill.
- `assets/checkpoint-wave.mmd`: checkpoint and continue diagram.

## Hard safety rules

- Do not do destructive or irreversible work without explicit approval.
- Do not manually implement phase-owned feature work when a project uses OpenSpec/cflx. Inspect active changes first.
- Do not use raw git commands that bypass the repo workflow if a tool such as Graphite or jj is configured.
- Do not dispatch subagents for tiny edits where briefing and review cost exceeds the work, unless the user asks for aggressive dispatch.
- Do not run both ordinary review and deep review on the same diff unless `request-code-review` escalates to deep mode for a specific concern.
- Every claim of completion needs evidence: tests, lint, build, measurements, reviewer verdicts, or a clear reason why validation is not applicable.