| name | fleet-supervisor |
| description | Disciplines and references for acting as fleet coordinator/supervisor across the dp-web4 project ecosystem (SAGE, ARC-SAGE, shared-context, private-context). Use when coordinating multi-machine work, reviewing fleet state, deciding what to pull/commit/merge, evaluating training results with agent-zero defenses, or making fleet-wide architectural decisions. Applies regardless of which machine invokes it. |
| disable-model-invocation | false |
| allowed-tools | Read, Glob, Grep, Bash, Edit, Write |
Fleet Supervisor
This skill exists because coordinator work keeps making the same mistakes when done cold: hardcoding machine-specific paths, trusting headline metrics, pulling the wrong repo, overwriting a peer's commits, not checking daemon concurrency. Each mistake is cheap to avoid if you remember — and expensive to recover from if you don't.
The disciplines below are ordered by when they apply.
1. WAKE before FOCUS — always
Before taking any fleet-scale action, run the wake checklist: checklists/wake.md.
Short version:
- What is the user actually asking? Is the frame right, or am I optimizing the wrong question?
- What has the fleet committed since I last pulled? (git log the four repos)
- Am I working on the right machine for this task? (CBP is WSL; don't run
./fleet_gameplay_capture.sh thor from CBP)
- Is there an in-flight operation on another machine I'd step on?
If any answer is uncertain, pull + read before acting. A 2-minute pull beats a 2-hour recovery.
2. Directory map — know where things live
Four repos, four purposes. Load references/directory-map.md when unsure where an artifact belongs.
Rule of thumb:
- Gemma could train on it →
shared-context/
- Competition deliverable →
ARC-SAGE/
- How the kernel learns →
SAGE/
- How we operate →
private-context/
- Credentials, session logs, operational state →
private-context/ only
Never cross-contaminate. A plan file in SAGE is an infrastructure leak. A solver in shared-context is an ARC-SAGE leak. If unsure, ask where consumers look for it.
3. Machine-specificity — no hardcoded paths
Load references/machine-paths.md when writing fleet-wide code.
Short version:
- WSL (CBP, Nomad-on-Windows):
/mnt/c/exe/projects/ai-agents/
- Linux (Legion, Sprout, Thor, Nomad-on-Linux):
/home/dp/ai-workspace/
- macOS (McNugget):
~/ai-agents/ or ~/repos/
Path-resolution order for fleet-wide code:
- Explicit env var override (
$SAGE_ROUTER_DATA_DIR, $ARC_SAGE_DIR, $SAGE_INSTANCE)
- Walk up from
__file__ to find repo root + siblings
- Fall back to a list of known layouts (WSL, Linux, macOS)
Hardcoding one machine's layout breaks the other five. Nomad fixed my hardcoded /mnt/c/exe/ in gameplay_capture.py during the fleet capture run — that's a self-correcting federation, but I should not have shipped the bug in the first place.
4. Pull protocol — what to pull, when
Load checklists/wake.md for the session-start protocol.
Fast reference:
- Session start:
git pull the four repos in parallel. Always.
- Before a fleet-wide write (shared-context commits, plans, PRDs): pull shared-context immediately before committing. Other machines may have landed work while you read.
- Before running training/capture: pull SAGE to get the latest code. Captured data is local — no need to pull
private-context before running a capture.
- After long computation: pull shared-context + check the convergence JSONL for any newly-landed reframe triggers before you commit your result.
Do NOT pull ARC-SAGE unless you're touching competition artifacts or game traces. It's big and not usually relevant to coordination.
5. Merge discipline — never discard federated work
Load references/federation.md when resolving conflicts.
Core rule: Every machine's commits represent another agent's work. You are not resolving a text conflict — you are integrating another agent's reasoning with yours. Read their diff. Understand what they were solving. Integrate both intents.
Specifically:
- Never
git checkout --ours or git checkout --theirs blindly
- Never force-push to shared branches
- When two machines both updated a JSONL, the merge is append-both (rows don't conflict)
- When two machines both updated a markdown doc, integrate by topic — synthesize their thoughts, don't pick one
- When a test suite conflicts, run both tests — the union is probably correct
Federation is a creative act, not a bureaucratic one. Other machines are peers, not noise.
6. Agent-zero discipline — every metric needs a dummy
Load references/agent-zero.md before quoting any training result.
Short version: a number without a dummy baseline is a mirror, not a measurement. An always-output-modal-class policy can score 88% on a class-imbalanced task and teach us nothing. Every metric must appear paired with its dummy and the margin.
phase1_training.py encodes this by construction. Never quote an accuracy without also quoting the dummy. Never promote an adapter on aggregate-only. INCONCLUSIVE with diagnosis is a valid and valuable verdict.
7. Concurrency gotchas — know the traps
Load references/concurrency-gotchas.md before introducing any writer.
Known traps hit this session:
- gzip.open("at") is NOT concurrency-safe. Two processes appending to the same
.jsonl.gz will corrupt each other's streams. Use separate subdirs per writer.
- Hook files (web4 sessions) race on read-while-write. Atomic
.tmp + os.replace() + try/except on read.
- router-shadow.env is per-machine. Gitignore it. Ship
.env.example. Don't let one machine's local state clobber another's.
Before introducing any new writer, ask: who else writes to this path? If the answer is non-trivial, either serialize via a lock file or give each writer its own subtree.
8. Version drift — things age out
Load references/concurrency-gotchas.md §2 for specifics.
Short version:
- Trace files pin SDK versions (
dc22-fdcac232). SDKs keep only the latest (dc22-4c9bff3e). Traces age out silently.
- Python packages can ship compatibility-breaking changes that look like code bugs.
arc.make(stale_id) returned None rather than raising.
- Always build the fallback in. Try the pinned, then the family id, then raise with context.
- A
version_fallback note in output provenance is honest signal, not a bug.
9. Reframe triggers — when to halt
Load references/agent-zero.md §3 for the full list.
Quick reference — stop and reframe when:
- All machines INCONCLUSIVE on the same head for the same reason → the head's framing is wrong
- Two machines return contradictory verdicts on the same aggregate data → reproducibility failure, not data failure
- You keep making the same class of fix (hardcode path, hardcode version, hardcode assumption) → the abstraction is missing
- The efficient path passes the gate but doesn't solve the problem → you're being fooled by your own metrics
Reframes are commits, not conversations. File the trigger to phase-1-convergence.jsonl (or equivalent convergence record) and let the fleet see it.
10. Account and resource hygiene
Load references/federation.md §3 for account/token routing.
Short version:
- Account 1 (CLAUDE_SYNTH_TOKEN): Thor, Sprout, Legion, McNugget. Weekly reset Thursday 10pm Pacific.
- Account 2 (CLAUDE_ADMIN_TOKEN): CBP, Nomad. Max 200 weekly.
- Don't run synthesis-scale work on Account 2 unless necessary. Legion hit 41% in <1 day doing autonomous sessions on Account 2.
ATP analog: every fleet-wide action costs coordination budget. Batch commits. Don't ping for routine work. Ping for reframe triggers + novel findings + load-bearing divergence.
11. Scope discipline
Match the scope of action to what was requested.
- User asked for a bug fix? Fix the bug, then stop. Don't refactor surrounding code.
- User asked for a plan? Write the plan, don't start implementing.
- User asked for a doc? Write one doc, not three, unless the task requires it.
- User granted coordinator authority? Use it — but for what was delegated, not unilateral scope expansion.
Productive failure > safe summaries. But "I did more than asked" is neither productive nor failure — it's just overreach.
12. Commit discipline
Load checklists/commit.md before any commit.
Short version:
- Pull before commit (§4)
- Include why, not just what, in the commit message
Co-Authored-By line with model name- Never
--no-verify unless the user explicitly asked
- Push immediately unless a reviewer is expected
Unpushed work is invisible to the fleet. A commit that only exists locally is a bet against federation.
Files in this skill
SKILL.md — this file, index + short-form disciplinechecklists/wake.md — pre-action wake checkchecklists/fleet-action.md — before any fleet-wide changechecklists/commit.md — commit + push protocolreferences/directory-map.md — repo responsibilities, what-goes-wherereferences/machine-paths.md — per-machine filesystem conventionsreferences/agent-zero.md — evaluation discipline, gate set, reframe triggersreferences/federation.md — pull/merge/account routingreferences/concurrency-gotchas.md — known write-contention + version-drift traps
Load references as needed. Not everything applies to every session — but the discipline does.
