acfs

# acfs — drive the agent-flywheel substrate

The operator skill for the ACFS substrate. `~/acfs/bin/acfs` is a **fork-and-own provisioner** (idempotent, additive, cross-platform Mac + Ubuntu/WSL) over Dicklesworthstone's flywheel tools. This skill teaches you to check the substrate's health, wire it, and run the operating loop on top of it.

## Overview / When to Use

ACFS is the **runtime layer** of Bo's three-layer factory: AgentOps = the mind, Mount Olympus = the factory/control-plane, **ACFS = the substrate the work actually runs on**. The doctrine is **invoke-never-rebuild**: you operate these binaries, you do not re-author them.

Use this skill when you need to: confirm the flywheel is healthy before doing real work, init/wire a host, decide whether a tool is *installed* vs *actually working*, or run a session through the Plan→Coordinate→Execute→Scan→Remember loop. It composes with `ntm` (swarms), `caam` (auth lanes), `cass-memory` (procedural memory), `dcg` (destructive-command guard), and `fleet-ops` (the `~/dev` virtual monorepo).

## ⚠️ Critical Constraints

- **Installed ≠ worked-on.** `acfs doctor` printing ✓ for a tool means the binary is on PATH — NOT that it's wired, indexed, or producing value (e.g. `cm` present but 0 rules, `cass` index stale, `am` daemon down). **Why:** the substrate lies green while the loop is starved; always read past the binary check to the `wiring` section. **Verify by use, not by presence.**
- **Invoke, never rebuild.** These are forked tools. Do not edit/recompile the binaries or "improve" them here. **Why:** rebuilding the substrate is the cathedral trap — it's a runtime to *use*; gaps are wiring, not design. Fork-and-own changes happen deliberately, not mid-loop.
- **Never `claude -p` for workers.** Loop/swarm workers run on `ntm` panes (interactive Claude = OAuth/sub auth) or `codex exec` — never `claude -p`/`--print`, which bills the API per-token. **Why:** `claude -p` burns metered API instead of the Max subscription; it is banned for worker dispatch.
- **`acfs` is additive — it never truncates configs, reboots, or sudo-installs.** **Why:** upstream's installer overwrites `~/.zshrc` + `~/.codex/settings.json` and reboots; ours doesn't. Trust `acfs init` to be safe to re-run, but per-tool *install* is still manual (see Troubleshooting).
- **dcg stays wired.** The destructive-command guard hook must be present in `~/.codex/settings.json`. **Why:** it's the safety floor for autonomous loops; `acfs doctor` flags it if missing.

## Workflow / Methodology

### Phase 1: Health — know the ground truth
```bash
~/acfs/bin/acfs doctor      # lanes · core flywheel · extras · wiring · summary
```
Reads four bands: **lanes** (claude/codex/agy/gemini auth), **core flywheel** (br, bv, am, ntm, dcg, cass, cm, ubs), **extras** (caam, ru, rch, fsfs, casr, sbh, pt), and **wiring** (cm store rules count, cass semantic model, ntm `projects_base`, dcg hook, am daemon). Exit code = number of blocking gaps.

**Checkpoint:** Read the `wiring` lines, not just the ✓/✗ on binaries. A green core with `cm store (0 rules)`, a stale cass index, or a dead `am` daemon means the loop is present but **not fed**. Resolve gaps before running real work.

### Phase 2: Init — wire what's installed
```bash
~/acfs/bin/acfs init        # cm init · ntm projects_base · cass freshness · auth-lane reminder
ACFS_PROJECTS_BASE=~/dev ~/acfs/bin/acfs init   # override swarm root per host
```
Idempotent and additive: inits the `cm` mind store, sets `ntm config projects_base` (default `~/dev`), reports cass index freshness, and reminds you to validate auth lanes (`caam doctor --validate`; expired lanes need interactive `caam login <lane>`).

**Checkpoint:** Re-run `acfs doctor` and confirm `0 blocking gap(s)` before proceeding. `acfs up` does doctor → init → doctor in one shot.

### Phase 3: Operate — run the loop
The operating conventions on the wired substrate:

- **`~/dev` is the work-root** (the `ntm` swarm base / `ACFS_PROJECTS_BASE`). Use `mani` (fleet-ops) for repo org — don't hand-walk repos.
- **Spawn a swarm:** `ntm spawn <name>` to start a pane/agent on a repo; coordinate via `am` (Agent Mail) for locks/messaging. (See the `ntm` skill for send/read/triage.)
- **The loop — Plan → Coordinate → Execute → Scan → Remember:**
  1. **Plan** — decompose into a work-DAG in `br` (beads): `br ready` for available work.
  2. **Coordinate** — `am` for file reservations + inter-agent messaging; `caam` to pick the auth lane.
  3. **Execute** — `ntm spawn` workers (interactive Claude on sub, or `codex exec`); `dcg` guards destructive commands throughout.
  4. **Scan** — `ubs` (ultimate bug scanner) over the result before closing.
  5. **Remember** — `cm` (cass-memory) captures the learning; publish the compression to shared state (beads close + committed artifact). **Loop-close is required** — an un-published result is invisible to the next agent.

**Checkpoint:** Every loop iteration ends with a `Remember` write (cm rule + br close + committed artifact). Skipping it leaves work stranded and starves the flywheel.

## Output Specification

**Format:** terminal report (human-readable bands from `acfs doctor`/`init`) plus a stated next action. This skill writes **no files** of its own.
**Persisted state (by sub-tools):** `cm` rules in the XDG mind store; `br` issues in `.beads/*` JSONL; `ntm`/`am` runtime state. Report these as evidence, not as skill output.
**Verdict line to relay:** the doctor `summary` (`core complete (N checks, 0 blocking gaps)` or `M blocking gap(s) of N`) + the chosen next move.

## Quality Rubric

- [ ] Ran `acfs doctor` and read the **wiring** band, not just binary presence.
- [ ] Confirmed `0 blocking gaps` (or named each gap + its install-hint) before real work.
- [ ] Auth lanes validated (`caam doctor --validate`); no expired lane in use.
- [ ] No worker dispatched via `claude -p` — only `ntm` panes or `codex exec`.
- [ ] `dcg` hook confirmed present in `~/.codex/settings.jso