agentleFS
syntropic137syntropic137/harness-app-template/.claude/skills/orchestrating-a-vps-agent-swarm/SKILL.md

orchestrating-a-vps-agent-swarm

Skill0 starsChanged 6 months agoMITView on GitHub

Guidance for managing a multi-agent swarm on this template's VPS environment. Use when coordinating multiple autonomous agents (Claude Code, Codex, Gemini) across parallel beads, handling double-claim collisions via Agent Mail, and using beads for global task state. Covers per-agent autonomy toggles (YOLO vs review-gated), multi-model layered review, the human framing gate, and the canonical CLI surface (`bd`, `bv`, `am`, `proj`, `ntm`).

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Lesson: If an agent is solving the wrong problem perfectly, the human must correct the frame before the next execution wave begins.

    line 57
  2. Distinctive:

    Pattern: Every significant Agent Mail finding should point to a bead ID.

    line 70
  3. Very specific:

    When bv --robot-next hands you a bead another agent has already claimed (visible in Agent Mail threads):

    line 136
  4. Very specific:

    Look up active Agent Mail threads referencing the bead ID: am status --agent <NAME> then am thread <ID> on any relevant subject lines.

    line 141
  5. Very specific:

    If the other agent has substantive work in the tree, stand down.

    line 144
  6. Distinctive:

    If the other agent appears wedged (no Agent Mail activity, no recent file edits), surface that to the human framing gate via an Agent Mail …

    line 149

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Orchestrating a VPS agent swarm

Overview

A VPS agent swarm is multiple specialized models running in shared or isolated workspaces on the same VPS. Success depends on: clear framing, asynchronous coordination via Agent Mail and beads, and a layered review stack across models with different defect lenses.

This template's VPS layout is documented in ~/CLAUDE.md. The phase model (ideation, task breakdown, swarm implementation, review, deploy) is at https://agent-flywheel.com/workflow. This skill covers phase 3 (swarm implementation) in operational detail.

Core lessons and patterns

1. Per-agent autonomy toggles (the YOLO switch)

Autonomy is a scheduling resource, not a binary state.

  • YOLO mode. Speed and execution on low-risk tasks (scaffolding, bulk refactors, doc edits). Launch with the host CLI's bypass flag: Claude Code --permission-mode bypassPermissions, Codex --dangerously-bypass-approvals, Gemini --yolo.
  • Review-gated mode. High-stakes architectural choices where each tool call should be audited. Drop the bypass flag; let prompts interrupt.
  • Rule. Launch each agent with the autonomy level tailored to its bead, not a session default.

2. Multi-model layered review

Different models catch different defect classes.

  • Author (Claude). High-level reasoning, complex spec generation, multi-file refactors.
  • Skeptical reviewer (Codex). Implementation consistency, boundary-condition checks, line-level correctness.
  • Consistency reviewer (Gemini). Cross-specification alignment, architectural split-brain detection, doc drift.
  • Outcome. A "passed" feature from one model should be cross-verified by another with a different lens before close.

3. The human framing gate

Models are excellent at local correctness but weaker at strategic pivots.

  • Pattern. Human intervention is most valuable at the beginning (framing the product, choosing the bead set) and middle (re-scoping based on research findings or an unexpected adversarial finding).
  • Lesson. If an agent is solving the wrong problem perfectly, the human must correct the frame before the next execution wave begins. The swarm cannot rescope itself.

4. Coordination: beads + Agent Mail

Structured state plus asynchronous communication.

  • beads. The global DAG. Provides stable IDs for claims, completions, and dependencies. The .beads/ directory is committed to the project repo.
  • Agent Mail. The rationale bus. Carries handoffs, merge negotiations, reservation announcements, and review findings.
  • Pattern. Every significant Agent Mail finding should point to a bead ID. Every bead claim should be preceded by an Agent Mail broadcast on the relevant thread when the work touches files multiple beads care about.

CLI surface (the template's actual tools)

# beads (per-project tracker; cwd-scoped)
bd create "..." -t task -d "..."      # new bead
bd update <id> --claim                # claim (atomic)
bd close <id> --reason "..."          # finalize (terminal-state)
bv                                    # interactive TUI
bv --robot-next                       # pick next ready bead (JSON)
bv --robot-triage                     # full recommendation set

# Agent Mail (cross-agent comms)
am macros start-session ...           # register an agent identity
am status --agent <NAME>              # inbox + reservation overview
am file_reservations reserve <PROJECT> <AGENT> <PATHS>...
am mail send --from <AGENT> --to <AGENT> --subject ... --body ...
am thread <ID>                        # read a coordination thread

# Project navigation (numbered)
proj                                  # list projects under /data/projects/
proj spawn <N> --cc=<K>                # ntm spawn an agent swarm at project N
proj attach <N>                       # re-attach
proj path <N>                         # absolute path of project N
ntm spawn <org>--<repo> --cc=<N>      # raw ntm form

# Sessions
systemctl --user status agent-mail    # the mail service is required

Operational checklist

  • Pre-trust environments. Folder trust and MCP server permissions must be granted before dispatching. Re-running claude login on the VPS is a known anti-pattern; ACFS services-setup from the operator's Mac is the only path.
  • Register the agent. Run am macros start-session --project <abs path> --program <cli> --model <id> on every fresh turn. Without an identity, am status cannot inspect inbox or reservations.
  • Claim before you edit. bd update <id> --claim is the authoritative claim. Two agents that both claim are a coordination bug; one of them must stand down via Agent Mail.
  • Reserve shared files. When a bead touches a file another bead also touches (e.g., justfile, lefthook.yml, .github/workflows/*), am file_reservations reserve it before editing. Skipped reservations cause edit races; recovery costs more than the reservation.
  • Exact file ownership. Every bead's description should call out a specific canonical file path. Name placeholders (<filename>) cause collisions.
  • Wedge detection. Watch for "busy" agents that have not touched the filesystem or Agent Mail in N minutes. Use am status --agent <NAME> to confirm a quiet agent is actually idle, not stuck.
  • Whole-template QA. After individual feature beads close, run just bootstrap && just test && just lint against a fresh clone (or a worktree) before declaring the swarm output green. Per-bead green does not imply assembled green.

Standard collision-recovery flow

When bv --robot-next hands you a bead another agent has already claimed (visible in Agent Mail threads):

  1. Re-read the bead state: bd show <id>. The status field is the shared source of truth.
  2. Look up active Agent Mail threads referencing the bead ID: am status --agent <NAME> then am thread <ID> on any relevant subject lines.
  3. If the other agent has substantive work in the tree, stand down. Send an Agent Mail reply on the existing thread (or a fresh one with a bd-<id>-coord style alphanumeric thread-id) naming the files you edited and confirming you will not commit. Then bv --robot-next for a fresh bead.
  4. If the other agent appears wedged (no Agent Mail activity, no recent file edits), surface that to the human framing gate via an Agent Mail message rather than unilaterally taking the bead. The wedge is the framing-gate event, not the failed claim.

Anti-patterns

  • Silent double-claim. Two agents both run bd update <id> --claim without checking Agent Mail. --claim is atomic and idempotent for the same agent, but it does not stop a second agent from taking a bead the first is already working: the claim is not exclusive at the beads layer. Recovery: stand down via Agent Mail.
  • Unilateral retirement. Removing or deprecating shared infrastructure (a hook, a sensor adapter, an ADR) without an Agent Mail broadcast first. The operator's preservation rule applies; see ADR-0017's "both-vs-reduce" framing.
  • Per-bead green declared as swarm green. Each bead's gate is per-file or per-slot. A swarm landing requires whole-template verification (see Operational checklist).
  • Mail without a bead ID. Coordination messages that name files but not beads decay into untrackable rationale. Cross-link every thread to at least one bead.

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.