Flywheel Admin

Flywheel Admin — Drive the ACFS Fleet

Scope: orchestration of remote Flywheel VPSs running ACFS. NOT per-tool reference for ntm/agent-mail/cass/etc. — those have their own skills; this one tells you which to reach for and in what order.

Read first. Always resolve the fleet from your device profile before acting — profile.servers[] (entries tagged flywheel) is the source of truth for the current fleet inventory, SSH aliases, and per-host notes. This skill captures the patterns; your profile captures today's state. See Fleet Resolution below.

Found a bug or missing pattern in this skill? Do NOT try to fix it inline. File an issue at https://github.com/evolv3-ai/vibe-skills/issues with a clear title (e.g. flywheel-admin: <symptom>), what you were trying to do, the exact command(s) that misbehaved, and the actual vs expected outcome. A repo-side dev workflow watches this tracker and will generate a fix + push a commit. The reason: external agents driving this skill rarely have the full operator context (current fleet inventory, Tailscale state, in-flight session notes) and inline fixes tend to drift from the canonical source. Report → don't patch.

Mental Model

A flywheel is a remote VPS running ACFS: Ubuntu + the Dicklesworthstone agent stack (ntm, agent-mail, beads, cass, dcg, slb, …) + Claude Code / Codex CLI / Gemini CLI. The local machine (Windows host or wsl-hermes) is the operator — it never runs agents itself, it drives swarms on flywheels via SSH (preferred over Tailscale MagicDNS).

Three layers, in dependency order:

1. Transport — SSH over Tailscale. If Tailscale is down, fall back to public IP.
2. Project — a directory under /data/projects/<name> on the flywheel with a PRD.md, AGENTS.md, and (usually) a beads database.
3. Swarm — an ntm session of tmux panes, one per agent (Claude/Codex/Gemini), coordinated via Agent Mail + Beads.

You operate at layer 3 most of the time. When something breaks, work down: probe transport, then check project state, then inspect panes.

Fleet Resolution

The fleet is defined in your device profile ($ADMIN_ROOT/profiles/$ADMIN_DEVICE.json), never in this skill. Each fleet host is a servers[] entry tagged flywheel:

{
  "name": "flywheel-1",
  "role": "swarm-host",
  "sshAlias": "flywheel-1",
  "provider": "oci",
  "tags": ["flywheel"],
  "notes": "Ubuntu 24.04 LTS; watch disk headroom"
}

Enumerate the fleet, then pick a host by role (or by notes when several qualify):

source ~/.admin/.env   # ADMIN_ROOT, ADMIN_DEVICE
PROFILE="$ADMIN_ROOT/profiles/$ADMIN_DEVICE.json"

# All flywheel hosts: name, role, sshAlias, notes
jq -r '.servers[]? | select((.tags // []) | index("flywheel"))
       | [.name, .role, .sshAlias, (.notes // "")] | @tsv' "$PROFILE"

# One host by role
HOST=$(jq -r '.servers[]? | select((.tags // []) | index("flywheel"))
              | select(.role == "swarm-host") | .sshAlias' "$PROFILE" | head -n1)
ssh "$HOST" 'acfs doctor'

No matching entries? STOP. Do not guess hostnames or fall back to hardcoded values — run the one-time migration in references/connect.md to register your fleet, then retry.

Connection is always ssh <sshAlias>; the alias→address mapping lives in your ~/.ssh/config (see references/connect.md for every operator surface and the public-IP fallback pattern). Throughout this skill, flywheel-N (and flywheel-N-oci in older examples) stands for a resolved sshAlias from your profile.

The Operator Loop

Every Flywheel session follows this loop. Skip phases you've already done.

1. Discover — what's the fleet doing right now?

# Health snapshot per host (run in parallel if you can)
for h in $(jq -r '.servers[]? | select((.tags // []) | index("flywheel")) | .sshAlias' "$PROFILE"); do
  ssh "$h" 'uptime; free -h | head -2; df -h / | tail -1; acfs doctor 2>&1 | tail -5; ntm list'
done

Red flags: load > #CPUs, memory >85 %, disk >75 %, acfs doctor red lines, dead ntm list.

2. Pick a target — which flywheel for this work?

Pick by the role and notes fields of your servers[] entries — per-host facts (OS version, disk headroom, installed extras like PostgreSQL or beads_rust) belong in notes, not in this skill. Rules of thumb:

If both are loaded, prefer scaling on the host with the most free RAM rather than spinning a third VPS.

3. Prepare the project

# Create the project dir if new
ssh flywheel-N-oci 'mkdir -p /data/projects/<name>'

# Copy in PRD + AGENTS.md
scp PRD.md AGENTS.md flywheel-N-oci:/data/projects/<name>/

# Optional: clone an existing repo to seed
ssh flywheel-N-oci 'cd /data/projects/<name> && git clone <url> .'

Confirm NTM_PROJECTS_BASE resolves to /data/projects:

ssh flywheel-N-oci 'ntm config get projects_base'

The session name MUST equal the directory basename. Cross-tool breakage between ntm, agent-mail, and beads almost always traces to a mismatch here.

4. Spawn the swarm

# 2 Claude + 1 Codex, classic starter swarm
ssh flywheel-N-oci 'cd /data/projects/<name> && ntm spawn <name> --cc=2 --cod=1'

# Add a Gemini for review-only work
ssh flywheel-N-oci 'cd /data/projects/<name> && ntm spawn <name> --cc=2 --cod=1 --gmi=1'

# Worktree isolation when agents will touch the same files
ssh flywheel-N-oci 'cd /data/projects/<name> && ntm spawn <name> --cc=3 --worktrees'

# Kick the swarm
ssh flywheel-N-oci 'ntm send <name> --all "Read PRD.md and AGENTS.md, then begin."'

For all spawn knobs (recipes, workflows, personas, stagger modes), use the ntm companion skill, not this one.

5. Drive / monitor

Prefer event-driven tending over polling. Bootstrap once with a snapshot, then block on the attention feed until something happens.

ssh flywheel-N-oci 'ntm --robot-snapshot --robot-format=toon'
ssh flywheel-N-oci 'ntm --robot-wait=<name> --wait-until=attention --timeout=5m'

# Tail a specific pane
ssh flywheel-N-oci 'ntm --robot-tail=<name> --panes=2 --lines=50'

# Inbox / coordination
ssh flywheel-N-oci 'ntm mail inbox <name> --json'
ssh flywheel-N-oci 'ntm locks list <name> --all-agents'

# Send corrective input
ssh flywheel-N-oci 'ntm send <name> --pane=2 "Refactor: extract validateInput into auth/validate.go"'

The fully-developed operator loop (probe-before-interrupt, stuck-pane unstick ladder, when to checkpoint vs respawn) is in references/operator-loop.md.

6. Wrap / recover

# Checkpoint before anything risky (migrations, force-pushes, schema changes)
ssh flywheel-N-oci 'ntm checkpoint save <name> -m "before <thing>"'

# Pull artifacts back to the operator
scp -r flywheel-N-oci:/data/projects/<name>/dist ./

# Tear down a finished swarm
ssh flywheel-N-oci 'ntm swarm stop <name>'

If a swarm is stuck and the panes won't respond, use the unstick ladder in references/operator-loop.md before killing anything.

Skill Mirror

The local .claude/skills/ bundle is the canonical source. After non-trivial changes here, push to every flywheel so all three remote agent families (Claude / Codex / Gemini) see the same set:

# Repeat per flywheel
ssh flywheel-N-oci 'mkdir -p ~/skills-staging ~/.claude/skills ~/.codex/skills ~/.gemini/skills'
# SKILLS_SRC = your canonical local skills bundle (e.g. <repo>/.claude/skills)
scp -r "$SKILLS_SRC/." flywheel-N-oci:~/skills-staging/
ssh flywheel-N-oci 'cp -r ~/skills-staging/. ~/.claude/skills/ \
  && cp -r ~/skills-staging/. ~/.codex/skills/ \
  && cp -r ~/skills-staging/. ~/.gemini/skills/ \
  && rm -rf ~/skills-staging'

For Hermes operators, also mirror to ~/.hermes/skills/ on wsl-hermes (the format is the agentskills.io open standard — identical to Claude Code). See references/hermes-notes.md.

Provisioning a New Flywheel

This is the rare path. Don't reach for it unless the existing fleet can't absorb the work.

1. Pick a provider — admin-devops:oci, admin-devops:hetzner, admin-devops:digital-ocean, etc. (each has a dedicated skill). OCI ARM64 Always-Free is the current default.
2. Bring the VM up via the provider's skill; install Ubuntu 24.04 LTS (LTS, not interim).
3. Join your tailnet (sudo tailscale up --authkey=...).
4. Bootstrap ACFS: curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/agentic_coding_flywheel_setup/main/install.sh | bash -s -- --easy-mode --skip-ubuntu-upgrade.
5. Verify with acfs doctor; expect ≥ 40/45 green.
6. Patch known ACFS-v0.5.0/v0.6.0 quirks — see references/known-quirks.md (ARM64 DCG binary, agent-mail Rust vs Python, bubblewrap, SSH keepalive).
7. Mirror the skills bundle (see above).
8. Add the new host to profile.servers[] (tagged flywheel) and a Host block to ~/.ssh/config on each operator surface (see references/connect.md).

Quirks (must-know)

• ACFS v0.5.0 is the current pinned version on existing fleet hosts; v0.6.0 is upstream. Refresh ~/.acfs/checksums.yaml before acfs-update --stack or it bails.
• DCG aarch64 release tarball ships the wrong-arch binary. Build from source.
• Agent Mail comes in Python and Rust flavors; the Rust one is what ACFS actually wants. Don't trust acfs doctor recommending the Python repo.
• ntm send excludes the operator pane by default. --all includes it. Don't blast a --all to a session you haven't checked.
• Session name MUST equal <projects_base>/<name> basename, or agent-mail registers under a different key than ntm. Most common breakage.

Full list with fixes in references/known-quirks.md.

References

• connect.md — every SSH path from every operator surface (Windows / WSL / tailnet / public-IP fallback) with keys.
• operator-loop.md — phase 5 in depth: tending cadence, unstick ladder, when to checkpoint vs respawn vs swarm-stop.
• known-quirks.md — every ACFS / flywheel-specific gotcha with the exact fix.
• hermes-notes.md — adjustments when this skill is driven by a Hermes agent on wsl-hermes instead of Claude Code on the Windows host.

Companion Skills

This skill orchestrates; the per-tool skills do the actual work. Reach for them when: