agentleFS
sssemilsssemil/SKILLS/skills/brutal/brutal-swarm/SKILL.md

brutal-swarm

Skill2 starsChanged 4 months agoMITView on GitHub

Drain a BRUTAL.md task graph through parallel isolated workers and stacked pull requests. Managed workers use append-only phases with fresh execution context.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read applicable repository workflow rules.

    line 18
  2. Distinctive:

    Never inherit uncommitted changes from the initiating worktree.

    line 25
  3. Distinctive:

    Ask for the maximum concurrent ticket workers on every run.

    line 26
  4. Very specific:

    Use scripts/swarm_wave.py on fresh normalized provider reads for every wave.

    line 36
  5. Distinctive:

    After handoff, do not claim, comment, transition, implement, push, review, or edit that task/PR.

    line 47
  6. Very specific:

    After terminal clean, remove the worktree only when the returned local head equals the verified pushed PR head.

    line 68
  7. Distinctive:

    Do not stop after the first wave.

    line 75
  8. Distinctive:

    Keep full tmux JSONL, test, diff, and provider output in protected run/attempt logs.

    line 87

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Brutal Swarm

Schedule exact-task workers without taking ownership of their tickets or pull requests.

Required Context

  1. Read ../brutal-shared/integration-resolver.md, ../brutal-shared/support/contracts.md, ../brutal-worker/SKILL.md, and references/parallel-execution.md completely.
  2. Resolve one work store and code host, load both support modules, and retain their normalized identities.
  3. Read applicable repository workflow rules.

Start A Run

  1. Discover resumable in_progress/in_review work and stack-ready todo artifacts of kind task or review_finding. Select one plan graph.
  2. Resolve the explicit or default root branch and record its remote head. Never inherit uncommitted changes from the initiating worktree.
  3. Ask for the maximum concurrent ticket workers on every run. Use the smaller of that answer and platform capacity.
  4. Resolve execution.worker_runtime with scripts/runtime_config.py before claiming or provisioning. Missing means tmux; accept only tmux or subagent and never fall back implicitly.
  5. For a local work store, resolve its canonical absolute root against the primary worktree.

Drain The Graph

Use scripts/swarm_wave.py on fresh normalized provider reads for every wave. Resume owned attempts before starting todo work.

For each selected artifact:

  1. Provision or safely resume its sibling worktree serially with scripts/worktree_manager.py.
  2. Pass the exact managed handoff from the execution reference. Use scripts/tmux_worker.py for tmux, or one persistent native collaboration worker for the subagent runtime. Instruct it to use $brutal-worker for only that task.
  3. After handoff, do not claim, comment, transition, implement, push, review, or edit that task/PR. The swarm may re-read state, advance managed phases, and relay progress.
  4. Preserve progress on failure. Remove only a verified empty worktree after claim loss. Exclude blocked descendants while independent work continues.

For tmux, count only live panes toward the concurrency cap. Retained dead panes occupy no slot. When a pane returns a valid zero-exit checkpoint, revalidate the task, ownership, PR, branch/base/head, and checks; write a mutable phase snapshot; then call tmux_worker.py advance with the active attempt id and revalidated snapshot. The controller derives the next phase. Never resume a completed checkpoint or reuse its Codex thread across phases.

Managed prompts contain only the phase, context-file path, and result path. Bulk ticket, diff, check, and finding data stays in one run-local context file.

Prioritize an interrupted same-phase resume before new work, still within the cap. Use exact-thread resume only for that interruption. Every phase and retry gets an append-only attempt directory; never overwrite or accept a stale attempt, missing exit record, or partial result.

After terminal clean, remove the worktree only when the returned local head equals the verified pushed PR head. Keep branches while PRs remain open. A zero_findings or materially_clean review gate is stack-ready; literal pr.clean remains a compatibility input, not the only readiness signal.

Rebuild the graph whenever a worker reaches a checkpoint or terminal result. Continue until no resumable, reconcilable, or stack-ready artifact remains. Do not stop after the first wave.

Reconcile Existing Stacks

Prioritize exact-task handoffs that complete merged tickets, update children after a base advances, or resume matching owned work. A child worker merges the new base normally, resolves conflicts, verifies, pushes, retargets when needed, and re-enters the material-correctness review/fix loop. Never merge a PR, force-push, or let a parent worker edit a child.

Operational Output

Keep full tmux JSONL, test, diff, and provider output in protected run/attempt logs. Relay only status, duration, checkpoint summary, and on failure the last 200 lines or 16 KiB, whichever is smaller. Logs and sessions are observability, not workflow truth.

Final Response

Report integrations, graph, requested/effective concurrency, runtime, worker and phase attempts, task/session/worktree/branch/PR mappings, completion kinds, residual lower-severity findings, blocked results, retained evidence, safe attach/cleanup commands, and reasons remaining artifacts are not stack-ready.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.