@gr8ful/spf 0.1.0

package/assets/skill/cookbooks/roster.md

@@ -0,0 +1,197 @@
+# Roster
+
+Add or retune agents in `spf.config.yaml`. There's nothing to generate — `spf
+init` seeds a starter `.spf/spf.config.yaml` with a couple of commented
+examples; everything else is inherited from the packaged defaults until you
+override it. `spf doctor` always shows what's actually in effect and where it
+came from.
+
+## The rule
+
+**One agent, one prompt, one purpose.** A roster entry defines who an agent
+*is*: its model, thinking level, and exactly one system prompt plus one user
+prompt. How it's *used* — the output type, a per-call prompt override —
+lives at the chain call site, never here. See `authoring_chains.md`.
+
+## Retune model or thinking
+
+```yaml
+agents:
+  - name: builder
+    model: anthropic/claude-sonnet-4-6   # ALWAYS provider/model-id
+    thinking: high                       # was medium
+```
+
+Write the model as `provider/model-id`, never a bare id — SPF has no live
+model catalog to check against (that was `pi --list-models`; Flue has no
+public equivalent), so an unqualified or malformed pattern is only caught by
+shape at `agents.validate()` time, and a genuinely wrong id surfaces at the
+first real dispatch. Thinking levels: `off | minimal | low | medium | high |
+xhigh | max` — inert (no error, no effect) on a model that isn't a reasoning
+model.
+
+**This is Flue's model vocabulary, not every backend's.** An agent with
+`coding_agent: claude_code` (see below) writes `model:` in Claude Code's own
+vocabulary instead — a bare alias (`sonnet`, `opus`) or a full model name —
+never `provider/model-id`. `agents.validate()` knows which shape check
+applies from `coding_agent`, so mixing the two conventions in the same
+roster is fine as long as each agent's own `model:` matches its own
+backend.
+
+**A model change means a fresh session.** `agent_map.json` records the
+model each agent's Flue conversation was created with. When a joined run
+(`--adw-id`) finds the config's model no longer matches, that agent starts a
+**new** conversation rather than resuming — never a bad resume. Thinking
+changes don't invalidate a session; model changes do.
+
+## Recolor an agent's lane
+
+```yaml
+agents:
+  - name: builder
+    color: "#22d3ee"      # hex; the starter roster ships violet/cyan/amber/red/magenta
+```
+
+Cosmetic, safe mid-project — rides the `agent_start` event and the
+`agent_sessions` row, so the UI picks it up on the next run without
+touching past sessions. Omit it for the UI's fallback palette.
+
+## Coding agent backends
+
+`coding_agent: flue` (the default) or `coding_agent: claude_code` — set per
+agent or in `defaults`. Both read the same roster shape (`tools:`,
+`writes:`, `thinking:`), but each backend interprets a couple of fields in
+its own vocabulary:
+
+```yaml
+agents:
+  - name: builder
+    coding_agent: claude_code
+    model: sonnet              # Claude Code's own alias/name, NOT provider/model-id
+    thinking: high
+    tools: [read, edit, bash]  # same canonical names either way — see "Retune tools" below
+```
+
+`claude_code` shells out to your own installed `claude` CLI (`spf doctor`
+checks it's on `PATH`) — it needs no separate npm install, since SPF never
+depends on it directly. A missing `ANTHROPIC_API_KEY` is informational, not
+a hard failure: Claude Code also supports its own `claude login` flow.
+
+**Pointing a `claude_code` agent at Ollama** — local or cloud — needs no
+config at all, just environment variables set before you run `spf` (Claude
+Code's CLI reads them itself):
+
+```bash
+# local Ollama
+export ANTHROPIC_BASE_URL=http://localhost:11434
+export ANTHROPIC_AUTH_TOKEN=ollama   # any non-empty value; Ollama doesn't check it locally
+
+spf build "..." --config .spf/spf.config.yaml   # any chain naming a claude_code agent
+```
+
+For Ollama's cloud offering, point `ANTHROPIC_BASE_URL` at that instead and
+set `ANTHROPIC_AUTH_TOKEN` to a real Ollama Cloud API key. This is exactly
+the same environment-variable pass-through every agent already gets — no
+SPF-specific plumbing, no `provider:` config section to write.
+
+## Retune tools
+
+Known tool names: `read`, `bash`, `edit`, `write`, `grep`, `glob` (`find` is
+accepted as an alias for `glob`). These are canonical across BOTH backends —
+Flue maps them to its own lowercase tool functions, Claude Code maps them to
+its own capitalized names (`Read`, `Bash`, ...); a roster entry never has to
+say which. `ls` is a recognized name with **no built-in on either backend**
+— bash/glob cover it, so listing it is harmless but it never mounts as its
+own tool.
+
+```yaml
+defaults:
+  tools: [read, bash, edit, write, grep, glob]
+
+agents:
+  - name: reviewer
+    tools: [read, grep, glob, bash, write]   # explicit list wins over defaults
+```
+
+**Resolution:** the agent's own list wins → else it inherits `defaults.tools`
+→ else unset, meaning every built-in tool. An empty list is not "all tools";
+it's a tool-less agent, and it will stall. `agents.validate()` rejects an
+unknown tool name at startup, before anything spawns.
+
+Narrow by role, not by reflex:
+
+- Any agent producing a `context_handoff/` artifact needs **`write`** — the
+  session runtime under `data_dir` is always writable regardless of
+  `writes:` (below), but the agent still needs the `write` tool itself to
+  use that grant.
+- Withhold `edit`/`write` only where the restriction *is* the guarantee — a
+  reviewer's contract is "change nothing," so dropping `edit` makes that
+  structural rather than merely prompted. (`writes: []`, below, is what
+  actually enforces it either way.)
+- Recon agents get the full read surface (`read`, `grep`, `glob`) — cheaper
+  and more legible in the trace than the equivalent `bash` calls.
+
+`harness_engineering` has **no analogue on any current backend** and must
+stay empty — `agents.validate()` fails loudly if any entry is non-empty.
+(Flue's equivalent surface — extra tools, subagents — is added via
+`useTool()`/`useSandbox()` inside `src/core/agent_flue.ts` itself; Claude
+Code's is an MCP server or plugin passed to `agent_cc.ts`. Either way it's
+an engine change, not a config one; see `authoring_chains.md`.)
+
+## Add a new agent
+
+Three steps, all required — skipping any one fails `agents.validate()` at
+startup, before anything spawns:
+
+1. **Prompts.** Create `<name>/system.md` (Purpose + Instructions — static
+   identity only) and `<name>/user.md` (one h3 per incoming datum —
+   `{{prompt}}`, `{{previous_envelope}}`, `{{context_handoff_dir}}` — then
+   the task, then a `## Report` section showing the exact output JSON).
+   Copy an existing pair as the shape. If you're overriding in `.spf/`, put
+   them under `.spf/prompt_engineering/<name>/`.
+2. **Config entry.** Name, purpose, prompt refs, plus anything that differs
+   from `defaults`.
+3. **An output type.** Pick an existing envelope type or add one — see
+   `authoring_chains.md`. The user prompt's `## Report` section must show
+   exactly that JSON shape.
+
+Then name the agent in a chain's `REQUIRED_AGENTS` and call it.
+
+## Write permissions — `writes` and `protected_files`
+
+`tools` cannot express a safety boundary: `bash` runs anything (including
+`git checkout`, which discards uncommitted work) and `write` reaches any
+path, not only the one report file an agent was granted it for.
+`core/permissions.ts` enforces the real boundary, after the fact, by
+fingerprinting the working tree's change-set before an agent runs and
+comparing it after. A path that was modified beforehand and is clean
+afterward has been **reverted** — a reversion counts as a modification.
+That's what catches the `git checkout` case.
+
+```yaml
+defaults:
+  protected_files: [.spf/, spf.config.yaml]   # the machinery that grades an agent's work
+
+agents:
+  - name: builder      # no `writes` key -> unrestricted, minus protected_files
+  - name: scout
+    writes: []          # no repo writes; findings still land in context_handoff/
+  - name: planner
+    writes: [specs/]
+  - name: documenter
+    writes: [app_docs/, docs/, "**/*.md", "*.md"]
+```
+
+A breach is **not** a gate violation — a gate is for work an agent can be
+asked to redo, but a write already happened. Instead: everything the agent
+introduced outside its allowlist is rolled back (tracked files via `git
+checkout --`, untracked files by deletion), anything that was *already*
+dirty before the agent ran is left untouched (the operator's own
+uncommitted work is not this module's to discard), and the phase fails
+naming every path and what happened to it.
+
+**The session runtime under `data_dir` is always writable, for every
+agent**, regardless of `writes:`. `writes: []` means read-only with respect
+to the repo, not unable to write its own report.
+
+Full field-by-field spec: `references/config.md`.

package/assets/skill/cookbooks/run_adw.md

@@ -0,0 +1,92 @@
+# Run a Chain
+
+Run a workflow and report on it. **You run and observe — you never step
+into the process or do the work yourself.**
+
+## Step 0 — translate the request
+
+**Read [how_to_prompt_for_the_eng.md](how_to_prompt_for_the_eng.md) before
+you launch anything.** The prompt you pass is read by every agent in the
+chain, so it gets written deliberately. This cookbook starts once you have
+that prompt.
+
+## Launch
+
+`spf list` shows every chain this install knows, its phases, and what it
+requires — the names are shape, not a fixed menu; read the actual output.
+
+```bash
+spf <chain> "<prompt>"                          # e.g. spf plan-build-test "add a /health endpoint"
+spf <chain> requests/health.md                  # prompt can be a file path instead of inline text
+spf <chain> "implement the plan" --adw-id a1b2c3d4   # join an existing session
+spf <chain> "..." --config path/to/other.config.yaml # a non-default roster
+spf <chain> "..." --cwd /path/to/other-repo          # run against a different repo
+```
+
+Launch in the background so you can poll while it works. `spf` prints the
+`adw_id` on startup — capture it, everything else keys off it.
+
+### Naming a roster
+
+The chain says *what runs*; the config says *who runs it*. If the engineer
+references a roster, a config file, or a model tier, pass `--config` — never
+fall through to the default silently. Two things bite:
+
+- **Never swap rosters on your own.** A different roster is a different
+  cost and a different result. If the default's model looks wrong, say so
+  and let the engineer choose.
+- **Switching rosters mid-session breaks resumption.** `agent_map.json`
+  records the model each agent's session was created with; a joined run
+  whose config now names a different model starts that agent **fresh**
+  instead of resuming — deliberate (a bad resume is worse), but it means
+  "plan on one roster, build on another" costs the builder its accumulated
+  context. Say so when you report it.
+
+`--adw-id` is optional on every chain. Given one, the run joins that session
+if it exists, or creates it pinned to exactly that id — same session
+directory, same `context_handoff/`, envelopes appended, each agent resumes
+its own Flue conversation via `agent_map.json`. That's how you chain runs:
+plan under one id, then build under the same id.
+
+## Observe
+
+```bash
+spf sessions [--limit N]              # recent runs
+spf phases <adw_id>                   # phase-by-phase status for one run
+spf events <adw_id> [--follow]        # the trace, live-tailable
+spf abort <adw_id>                    # signal a stuck run's process to stop
+```
+
+`spf events --follow` polls the same rowid cursor the visualizer does — safe
+to leave running. `spf phases` marks each phase ✓/✗/… — remember **every
+phase defaults to fail**, so `✗` may mean it never completed, and `…` means
+still running, not stuck.
+
+For a visual view of the same data: `spf ui` — opens a browser, renders
+sessions as cards and runs as swim lanes, phases and tool calls drill in.
+
+## When a run is stuck
+
+A hung agent produces no events at all, so the trace goes quiet rather than
+red.
+
+```bash
+spf phases <adw_id>       # which phase is still "running"
+spf abort <adw_id>        # stop it
+```
+
+`spf abort` sends `SIGTERM` to the OS process running the chain (there's no
+separate per-agent handle to target from a different CLI invocation — Flue
+runs in-process, so stopping the run means stopping that process). A killed
+run finalizes its own trace: it lands on `fail` with its process rows
+closed, never left claiming `running` forever.
+
+## Report
+
+Tell the engineer, in order: which chain and which roster you launched (name
+the config whenever it wasn't the default), which phase is running now or
+which failed, phase statuses in sequence, and for a failure the gate
+violations or the error verbatim, from `spf phases`/`spf events`. Don't dress
+up a partial run as a success.
+
+Full trace schema and what each column means: `references/observability.md`.

package/assets/skill/cookbooks/spf_overview.md

@@ -0,0 +1,111 @@
+# SPF Overview
+
+The map, not the procedure — read this once to know how the pieces fit
+before touching any of the other cookbooks.
+
+## What SPF is
+
+SPF runs **ADWs**: TypeScript chains that own sequencing, retries, and
+acceptance, calling bounded agent phases and deterministic code phases in
+between. "Agent proposes, code disposes" — an agent's response is a claim,
+and code (a gate, a quality check, a permissions check) verifies it before
+the chain moves on.
+
+SPF is a global CLI (`npm i -g @gr8ful/spf`), not a template stamped into
+the target repo. It ships:
+
+- a packaged **default roster** (`spf.config.yaml`) and **default prompts**,
+  usable with zero setup;
+- an optional per-repo **`.spf/` override directory** (`spf init` seeds it) —
+  merged on top of the packaged defaults, field by field;
+- an optional per-repo **`.spf/data/`** runtime home for the sqlite trace and
+  session files, created on first run, always gitignored.
+
+There is no `adws/` tree to stamp, no `bun install`. The default
+coding-agent backend is **Flue** (`@flue/runtime`), an in-process agent
+harness with no subprocess and no separate CLI to have on `PATH`.
+`coding_agent: claude_code` is a second backend — it shells out to your own
+installed `claude` CLI instead, for repos that want to run agents on
+Claude Code (including pointed at a local or cloud Ollama server). See
+`roster.md`.
+
+## Layout, once you run something
+
+```
+<repo>/
+  .spf/                          # optional — only if you ran `spf init`
+    spf.config.yaml              # your overrides, merged over the built-in defaults
+  .spf/data/                     # runtime — always gitignored
+    spf.db                       # the trace: sessions, phases, events, envelopes, gates
+    flue.db                     # Flue's own conversation store (session resumption)
+    sessions/<adw_id>/
+      agent_map.json            # agent name -> its Flue conversation id + model
+      context_handoff/          # the ONE place agents hand files to each other
+      <agent_name>/
+        prompts/                # exact system.md + user.md sent, saved before the call
+        envelope.json           # the final parsed, validated response
+```
+
+`spf doctor` prints exactly what resolved and from where — config paths,
+prompt paths, the trace db path — so "is my override even taking effect" is
+always a one-command answer.
+
+## The phase model
+
+Three phase kinds, all run through the one primitive, `run.phase(params, fn)`:
+
+- **`engineer`** — captures human input; no agent, no gate.
+- **`agent`** — `ph.call({output_type, prompt, gates})`: sends a prompt,
+  gets back a typed envelope, verifies it against every declared gate.
+  A parse failure or gate violation triggers a bounded same-session
+  correction, never a cold restart.
+- **`code`** — deterministic work: running a quality suite, capturing a git
+  diff, committing. If you can write down the command, it's `code`, not an
+  agent that has to rediscover it every run.
+
+Every phase defaults to `fail`; only a clean exit earns `success`. The chain
+calls `run.finish(accepted, reason)` exactly once at the end — separate from
+per-phase success, because a red test suite that *ran correctly* is still a
+successful phase; whether the whole run is *accepted* is a different
+question.
+
+## Envelopes
+
+Every agent call declares a concrete output type — an envelope schema built
+with Valibot's `envelopeType()`. The agent's final JSON is parsed against
+exactly that type; there are no untyped handoffs. The schema, the JSON shown
+in that agent's `user.md` `## Report` section, and the `output_type:` named
+at the call site are the same fact in three places — the "synced triad."
+Full contract: `references/handoff.md`.
+
+## Running a chain
+
+```bash
+spf list                                        # every chain, its phases, what it needs
+spf <chain-name> "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id <id>] [--cwd <dir>]
+spf doctor                                      # confirm the roster/config/quality all resolve first
+spf sessions                                    # recent runs
+spf phases <adw_id>                             # one run's phase-by-phase status
+spf events <adw_id> --follow                    # the live trace
+spf ui                                          # the visualizer, browser-based
+```
+
+`spf <chain-name> ...` and `spf run <chain-name> ...` are identical — the bare
+form exists because naming the chain *is* choosing what runs.
+
+## When you've finished reading this
+
+Startup discipline still applies: run `spf list`, don't volunteer more state
+than the engineer asked for, and read `how_to_prompt_for_the_eng.md` before
+launching anything.
+
+## Where to go next
+
+| Need | Go to |
+|---|---|
+| Launch a chain, watch it, report on it | `cookbooks/run_adw.md` (after `how_to_prompt_for_the_eng.md`) |
+| Retune the roster, add an agent | `cookbooks/roster.md` |
+| Add or extend a chain | `cookbooks/authoring_chains.md` |
+| Envelope/gate/session contract | `references/handoff.md` |
+| Trace schema, spend vs. context | `references/observability.md` |
+| Full config field reference | `references/config.md` |

package/assets/skill/references/config.md

@@ -0,0 +1,188 @@
+# Config Reference
+
+The full `spf.config.yaml` spec: every field, how defaults merge, and how
+model / thinking / tools map onto each coding-agent backend (Flue by
+default, or Claude Code). The schema is Valibot-enforced —
+`agents.validate()` refuses a bad config before anything spawns — so this is
+semantics and gotchas, not a shape you have to memorize by hand; `spf doctor`
+always shows the resolved, merged result for the repo you're in.
+
+## Resolution order
+
+1. The packaged built-in default (`assets/defaults/spf.config.yaml` inside
+   the installed CLI).
+2. `.spf/spf.config.yaml` in the target repo, if present — merged on top,
+   field by field (`defaults`/`observability`/`quality` merge key-by-key;
+   `agents` merges by `name`: a matching name patches that entry, a new name
+   appends).
+3. An explicit `--config <path>` replaces both — standalone, no built-in
+   underneath it.
+
+`spf init` seeds step 2 with a commented starter; omitting it entirely means
+running off pure built-ins, which is a fully supported, valid state.
+
+## Shape
+
+```yaml
+defaults:
+  coding_agent: flue                       # the only implemented value
+  model: google/gemini-3.6-flash           # ALWAYS provider/model-id
+  thinking: medium
+  tools: [read, bash, edit, write, grep, glob]
+  protected_files: [.spf/, spf.config.yaml]
+  data_dir: .spf/data
+
+observability:
+  db: .spf/data/spf.db
+  poll_ms: 500
+
+quality:
+  checks:
+    - {name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 600}
+  suites:
+    test: [test]
+    all: [test]
+
+agents:
+  - name: planner
+    model: google/gemini-3.6-flash
+    thinking: high
+    color: "#a78bfa"
+    purpose: Turn a request into a plan the builder can implement without asking questions.
+    prompt_engineering:
+      system: planner/system.md
+      user: planner/user.md
+    writes: [specs/]
+    tools: [read, grep, glob, bash, write]
+```
+
+## Fields
+
+### `defaults`
+
+| Field | Type | Meaning |
+|---|---|---|
+| `coding_agent` | `"flue"` \| `"claude_code"` | Which backend runs the agent. Default `flue`. `claude_code` shells out to your own installed `claude` CLI — `spf doctor` checks it's on `PATH`. |
+| `model` | string | Vocabulary depends on `coding_agent`: Flue wants `provider/model-id`; Claude Code wants its own bare alias/full name (`sonnet`, `claude-sonnet-5`, ...). Default `google/gemini-3.6-flash`. |
+| `thinking` | enum | `off\|minimal\|low\|medium\|high\|xhigh\|max`. Default `medium`. On a `claude_code` agent this maps to `--effort` (`off`/`minimal` both floor to Claude Code's own minimum — it has no true "disabled" level for a headless run). |
+| `color` | hex string | Lane color fallback for agents that don't set their own. |
+| `harness_engineering` | string[] | **Must stay `[]`** — no analogue on any current backend; a non-empty entry fails validate(). |
+| `tools` | string[] \| null | Roster-wide allowlist. Unset/null = every built-in tool usable. |
+| `protected_files` | string[] | Paths no agent may touch unless named in its own `writes`. Default `[".spf/", "spf.config.yaml"]`. |
+| `data_dir` | path | Runtime home, repo-relative. Default `.spf/data`. |
+
+### `observability`
+
+| Field | Type | Meaning |
+|---|---|---|
+| `db` | path | The trace sqlite db. Default `.spf/data/spf.db`. |
+| `poll_ms` | int | UI live-poll cadence. Default `500`. |
+
+### `quality`
+
+`checks[]`: `{name, area: "frontend"|"backend", operation: "lint"|"typecheck"|"build", argv: string[], timeout_seconds}`.
+`suites`: `{suite_name: [check_name, ...]}`. No packaged default suite exists
+on purpose — a chain that needs one and finds it unconfigured fails loudly
+at `agents.validate()` time, not with a placeholder green. Adding a check
+whose result is really a test run, not a lint/typecheck/build, still needs
+one of those three `operation` values — it only affects how the trace/UI
+labels the check, never what actually runs — `build` is the closest fit.
+
+```yaml
+quality:
+  checks:
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    test: [test]              # what build-test/plan-build-test's fix loop runs
+    all: [typecheck, build, test]   # what plan-build-test-quality/quality run
+```
+
+A full worked example, including the `defaults.coding_agent`/`watch:`
+sections: `docs/examples/node-typescript.spf.config.yaml` in the spf
+repo (or wherever this skill's own package is installed from).
+
+### `agents[]`
+
+| Field | Required | Meaning |
+|---|---|---|
+| `name` | yes | The identifier chains use. Chains name agents, never models. |
+| `prompt_engineering.system` / `.user` | yes | Paths to the two prompt files. Resolved against the repo root, then `.spf/`, then `.spf/prompt_engineering/`, then the packaged assets — first hit wins; a total miss throws listing every path tried. |
+| `purpose` | no | One sentence; should match the system prompt's stated purpose. |
+| `coding_agent`, `model`, `thinking`, `color`, `harness_engineering` | no | Override the matching `defaults` key. |
+| `tools` | no | Allowlist. Omitting it means all tools usable. A capability list, not a boundary — see `writes`. |
+| `writes` | no | What this agent may modify **in the repo**, enforced after every call. `undefined`/`null` = unrestricted (still barred from `protected_files`); `[]` = no repo writes; a list = only those paths (trailing `/` = directory prefix, `*` = one path segment, `**` = crosses segments, anything else = exact path). |
+
+Output types are deliberately absent from config: an entry defines who an
+agent *is*; the call site defines how it's *used*.
+
+## Model resolution
+
+**For `coding_agent: flue` (the default):** always write `model` as
+`provider/model-id`. There is no live catalog to validate against (Flue has
+no public model-registry API) — `agents.ts` checks only the static shape at
+`agents.validate()` time; a genuinely wrong provider or id surfaces at the
+first real dispatch instead. Provider credentials come from the
+environment, matching the provider you named (`GEMINI_API_KEY`/
+`GOOGLE_API_KEY` for `google/...`, `ANTHROPIC_API_KEY` for `anthropic/...`,
+etc.) — `spf doctor` checks the common ones are set.
+
+**For `coding_agent: claude_code`:** write `model` in Claude Code's own
+vocabulary — a bare alias (`sonnet`, `opus`) or a full model name — never
+`provider/model-id`. `agents.validate()` only checks it's non-empty; a
+genuinely wrong name surfaces at the first real dispatch, same as Flue.
+Credentials come from whatever the `claude` CLI itself is authenticated
+with (`ANTHROPIC_API_KEY`, or its own `claude login` flow) — `spf doctor`
+treats a missing key as informational for this backend, not a failure.
+
+The resolved model is recorded per agent in `agent_map.json`, mirrored in
+the `agent_sessions` table. **Changing an agent's model invalidates its
+session** — a joined run starts that agent fresh instead of resuming.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `read` | read file contents |
+| `bash` | execute bash commands |
+| `edit` | find/replace edits |
+| `write` | create/overwrite files |
+| `grep` | search file contents |
+| `glob` (alias: `find`) | find files by pattern |
+| `ls` | recognized name, **no built-in on either backend** — harmless to list, never mounts |
+
+These names are canonical across backends — a roster entry never says
+which; each backend module (`agent_flue.ts`, `agent_cc.ts`) maps them to
+its own tool vocabulary (Flue's lowercase functions, Claude Code's
+capitalized `Read`/`Bash`/...).
+
+**Resolution order:** an agent's own `tools` wins → else `defaults.tools` →
+else unset (all tools usable). An empty list is a tool-less agent, and it
+will stall — not "all tools."
+
+## Write permissions — `writes` and `protected_files`
+
+Full mechanism and rationale: `roster.md`'s "Write permissions" section.
+Short version: `permissions.ts` fingerprints the working tree's diff before
+and after an agent runs; anything outside its allowlist is rolled back
+(reverting a previously-clean file counts as a change; a file that was
+already dirty is left alone) and the phase fails, naming every path. This is
+not a gate — it's checked in code, not by asking the model to redo work.
+
+## Harness engineering — no longer applicable
+
+Kept as a field for config-shape stability, but it must be empty. Each
+backend's own equivalent (Flue: extra tools/subagents via `useTool()`/
+`useSandbox()`; Claude Code: an MCP server or plugin) is an engine-level
+change made inside that backend's own module, not config — see
+`authoring_chains.md`.
+
+## Pointing `claude_code` at Ollama
+
+No config section for this — it's an environment-variable recipe, since
+`agent_cc.ts` passes the operator's environment straight through to the
+`claude` subprocess, exactly like every other env var. Set
+`ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` (local or cloud Ollama) before
+running `spf`; see `roster.md`'s "Coding agent backends" section for the
+exact commands.