@gr8ful/spf 0.8.3 → 0.9.0

package/README.md

@@ -7,6 +7,8 @@ A software factory does one thing: it gives you more leverage on your prompt. Ho
 
 Everyone can get an agent to write code once. Almost nobody gets the same result twice. This fixes that by moving the control plane out of the prompt and into TypeScript. A chain script owns sequencing, retries, and acceptance. Agents work inside named phases. Typed JSON envelopes carry context across the seams. Every event streams into SQLite while it is still happening. **Agent proposes, code disposes.**
 
+> **Beta.** SPF is under active development — config schema, chain/CLI surface, and trace/event shapes may change between releases without a deprecation period. Pin a version if you depend on any of these staying stable.
+
 ---
 
 ## Install
@@ -124,17 +126,34 @@ Set `coding_agent: claude_code` on any agent (or in `defaults`) to run it on you
 
 #### Proxy or wrapper launchers
 
-To route the `claude` command through a wrapper, proxy server, or launcher (e.g., [Ollama](https://ollama.com)), set the `SPF_CLAUDE_CMD` environment variable before running `spf`. Space-separated command chains are supported:
+To route the `claude` command through a wrapper, proxy server, or launcher (e.g., [Ollama](https://ollama.com)), set `SPF_CLAUDE_CMD` — as a declarative `env:` entry in `spf.config.yaml`, since it's a launcher choice, not a secret (see [Declarative env vars](#declarative-env-vars) below), or as a plain shell export for a one-off override. Space-separated command chains are supported:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+```
 
 ```bash
-# Route through Ollama's launcher
-export SPF_CLAUDE_CMD="ollama launch claude --model granite4.1:8b"
 spf build "your prompt"
 ```
 
 `ollama launch <cmd>` uses cobra flag parsing, which treats anything typed after it as its own flags unless a literal `--` says otherwise — without one, `claude`'s own flags (`-p`, `--json-schema`, ...) fail with `unknown shorthand flag: 'p' in -p` before `claude` is ever reached. `agent_cc.ts` detects exactly this `ollama launch ...` shape and inserts that `--` automatically, so you never add the separator by hand for this specific launcher.
 
-That `--` alone is not enough to reach `claude`, though: `ollama launch` also needs its OWN `--model <tag>` flag (a tag from `ollama list`), typed BEFORE the auto-inserted `--`, whenever it runs headless — which it always does under SPF, since SPF spawns with piped stdio. Without it, `ollama launch` falls back to an interactive model picker that can never run, and fails one step later than the `--` problem, with `model selection requires an interactive terminal; use --model to run in headless mode`. A `--model` typed after the `--` doesn't help — at that point it belongs to `claude`, not to `ollama launch`. So `SPF_CLAUDE_CMD` must include `ollama launch`'s `--model` yourself, exactly as written above; `spf doctor` hard-fails if it's missing.
+That `--` alone is not enough to reach `claude`, though: `ollama launch` also needs its OWN `--model <tag>` flag, typed BEFORE the auto-inserted `--`, whenever it runs headless — which it always does under SPF, since SPF spawns with piped stdio. Without it, `ollama launch` falls back to an interactive model picker that can never run, and fails one step later than the `--` problem, with `model selection requires an interactive terminal; use --model to run in headless mode`. A `--model` typed after the `--` doesn't help — at that point it belongs to `claude`, not to `ollama launch`. So `SPF_CLAUDE_CMD` must include `ollama launch`'s `--model` yourself; `spf doctor` hard-fails if it's missing.
+
+**Per-agent model choice:** a literal `{model}` token in `SPF_CLAUDE_CMD` is substituted with each call's own agent-config `model:` field before spawning. Since `ollama launch`'s `--model` (its OWN flag) is what actually pins the model serving the whole launched process — not `claude`'s own `--model`, appended after the `--` — a FIXED tag in `SPF_CLAUDE_CMD` means every `claude_code` agent runs on that one model regardless of what each agent's `model:` says. Using `{model}` instead makes it genuinely per-agent:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+agents:
+  - name: planner
+    coding_agent: claude_code
+    model: kimi-k2.7-code:cloud
+  - name: builder
+    coding_agent: claude_code
+    model: qwen3-coder:cloud
+```
 
 ```bash
 # Or use a custom wrapper script
@@ -144,6 +163,18 @@ spf build "your prompt"
 
 The command/launcher must support the full Claude Code CLI interface: `-p` for prompt, `--json-schema`, `--model`, `--session-id`/`--resume`, `--output-format stream-json`, and all other flags `agent_cc` uses. When unset, `SPF_CLAUDE_CMD` defaults to `claude` (resolved from `PATH` normally). A cmdSpec that already contains its own literal `--` is left completely alone — `agent_cc.ts` never inserts a second one.
 
+#### Declarative env vars
+
+`spf.config.yaml` supports an `env:` block for settings like `SPF_CLAUDE_CMD` that are configuration, not secrets — so they can be committed as plain, reviewable text instead of hidden in an out-of-band shell export:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+  SOME_TOKEN: "${SOME_SECRET_FROM_DOTENV}"
+```
+
+Applied to `process.env` before any command runs. A plain value commits as literal text; `${VAR}` interpolates from whatever's already in `process.env` at that point (the real shell, or `.env`, both of which load first) — so a real secret can live in `.env` (gitignored) and be referenced here without ever being written into this file. An already-set `process.env` value always wins over `env:`'s — `spf.config.yaml` supplies the default, a real export still overrides it per machine/session. A `${VAR}` reference to something that's genuinely unset fails loudly at startup, naming the missing variable, rather than silently interpolating to an empty string.
+
 ### flue + local Ollama
 
 Point the default `flue` backend at a local Ollama server the same way you'd pick any other Flue provider — the model string's own prefix, `ollama/<tag>` (whatever `ollama list` shows on your machine) instead of `openai/...`/`anthropic/...`:

package/assets/skill/cookbooks/roster.md

@@ -99,11 +99,25 @@ SPF-specific plumbing, no `provider:` config section to write.
 
 There's a second, different way to reach Ollama through `claude_code`: route
 the `claude` command itself through `ollama launch claude` via
-`SPF_CLAUDE_CMD`, instead of pointing `ANTHROPIC_BASE_URL` at Ollama's
-OpenAI-compatible surface. That launcher form needs its own `--model <tag>`
-flag (from `ollama list`) in the command string, since SPF always spawns
-headless — see README.md's "Proxy or wrapper launchers" section for the
-full command and why `--model` is mandatory there, not optional.
+`SPF_CLAUDE_CMD` — as a declarative `env:` entry in `spf.config.yaml`
+(non-secret; see `config.md`'s "Declarative env vars" section), not a raw
+shell export. That launcher form needs its own `--model <tag>` flag in the
+command string, since SPF always spawns headless — use the literal token
+`{model}` there (substituted with each call's own agent `model:` field)
+rather than one fixed tag, or every `claude_code` agent ends up sharing the
+same model regardless of its own `model:`:
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+agents:
+  - name: builder
+    coding_agent: claude_code
+    model: kimi-k2.7-code:cloud
+```
+
+See README.md's "Proxy or wrapper launchers" section for the full command
+and why `--model` is mandatory there, not optional.
 
 ## Retune tools
 

package/assets/skill/references/config.md

@@ -12,7 +12,7 @@ always shows the resolved, merged result for the repo you're in.
 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`/`watch`/`notifications`/`review`/`tiering`
+   field by field (`env`/`defaults`/`observability`/`quality`/`watch`/`notifications`/`review`/`tiering`
    merge key-by-key — `notifications.channels` replaces wholesale, same as
    `quality.checks` and `tiering.tiers`/`tiering.roles`; `agents` merges by
    `name`: a matching name patches that entry, a new name appends).
@@ -20,7 +20,9 @@ always shows the resolved, merged result for the repo you're in.
    underneath it.
 
 `spf init` seeds step 2 — on a TTY, via an interview that asks the fields
-below and appends whatever secrets they imply to `.env`; non-interactively
+below and appends whatever secrets they imply to `.env` (a non-secret,
+declarative setting like `SPF_CLAUDE_CMD` goes into this file's own `env:`
+block instead — see "Declarative env vars" below); non-interactively
 (`--yes`, `--template <name>`, or no TTY) it writes a commented starter
 instead. Omitting `.spf/spf.config.yaml` entirely means running off pure
 built-ins, which is a fully supported, valid state.
@@ -497,28 +499,60 @@ change made inside that backend's own module, not config — see
 
 ## 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. `spf doctor` probes `ANTHROPIC_BASE_URL` (informational — a
-down endpoint or wrong path is reported, never a hard failure) and flags a
-base URL that already ends in `/v1` as a likely double-path mistake, since
+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. `spf doctor` probes `ANTHROPIC_BASE_URL` (informational
+— a down endpoint or wrong path is reported, never a hard failure) and flags
+a base URL that already ends in `/v1` as a likely double-path mistake, since
 the `claude` CLI appends `/v1/messages` itself.
 
-Routing through `SPF_CLAUDE_CMD="ollama launch claude --model granite4.1:8b"`
-instead needs an explicit `--` before `claude`'s own flags (cobra flag
-parsing otherwise consumes them as `ollama launch`'s own) — `agent_cc.ts`
-detects this exact `ollama launch ...` token shape and inserts that
-separator automatically, so you never add it by hand. The `--model` before
-that separator is NOT optional, though: it's `ollama launch`'s own flag, and
-it's mandatory in headless mode (SPF always pipes stdio, so the interactive
-model picker `ollama launch` falls back to without it can never run) — a
-`--model` typed after the `--` belongs to `claude`, not to `ollama launch`,
-and doesn't help. `spf doctor` hard-fails a `SPF_CLAUDE_CMD` missing it. See
-README.md's "Proxy or wrapper launchers" section for the full explanation.
+Routing through `SPF_CLAUDE_CMD` instead — e.g.
+`env: { SPF_CLAUDE_CMD: "ollama launch claude --model {model}" }` in
+`spf.config.yaml` (declarative, not a secret — see "Declarative env vars"
+below; a plain shell export also works and still wins) — needs an explicit
+`--` before `claude`'s own flags (cobra flag parsing otherwise consumes them
+as `ollama launch`'s own) — `agent_cc.ts` detects this exact
+`ollama launch ...` token shape and inserts that separator automatically, so
+you never add it by hand. The `--model` before that separator is NOT
+optional, though: it's `ollama launch`'s own flag, and it's mandatory in
+headless mode (SPF always pipes stdio, so the interactive model picker
+`ollama launch` falls back to without it can never run) — a `--model` typed
+after the `--` belongs to `claude`, not to `ollama launch`, and doesn't help.
+`spf doctor` hard-fails a `SPF_CLAUDE_CMD` missing it. A literal `{model}`
+token anywhere in `SPF_CLAUDE_CMD` is substituted with the calling agent's
+own `model:` field before spawning — since `ollama launch`'s `--model` is
+what actually pins the model for the whole launched process, a FIXED tag
+there means every `claude_code` agent shares one model regardless of its own
+`model:`; `{model}` is what makes per-agent model choice real under this
+launcher. See README.md's "Proxy or wrapper launchers" section for the full
+explanation.
 
 For `flue` (the default backend) pointed at Ollama instead of `claude_code`
 — i.e. `model: ollama/<tag>` — see "Model resolution" above and README.md's
 "flue + local Ollama" section.
+
+## Declarative env vars
+
+A top-level `env:` map in `spf.config.yaml` sets `process.env` defaults for
+settings that are configuration, not secrets — `SPF_CLAUDE_CMD` above is the
+motivating case. Applied once, in `cli/index.ts`'s `main()`, right after
+`.env` loads and before any command runs. Merge is key-by-key (like
+`defaults`/`watch`), so a `.spf/spf.config.yaml` override can add one key
+without repeating the rest.
+
+```yaml
+env:
+  SPF_CLAUDE_CMD: "ollama launch claude --model {model}"
+  SOME_TOKEN: "${SOME_SECRET_FROM_DOTENV}"
+```
+
+A plain value commits as literal text. `${VAR}` interpolates from whatever's
+already in `process.env` at that point — the real shell, or `.env`, both of
+which load first — so a genuine secret can stay in `.env` (gitignored) and
+be referenced here without ever being written into this (committed) file.
+Precedence: an already-set `process.env` value always wins over `env:`'s —
+this block supplies a default, never forces an override, the same way
+`process.loadEnvFile()` itself never overwrites an already-set var. A
+`${VAR}` reference to something genuinely unset fails loudly at startup,
+naming the missing variable — see `agents.ts`'s `interpolateEnvValue`/
+`applyConfigEnv`.

package/dist/cli/index.js

@@ -5,6 +5,7 @@
  * common case. Everything else is a named subcommand.
  */
 import path from "node:path";
+import * as agents from "../core/agents.js";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
 import * as notify from "../core/notify/notifier.js";
@@ -57,6 +58,11 @@ function findCwdFlag(argv) {
     const idx = argv.indexOf("--cwd");
     return idx !== -1 ? argv[idx + 1] : undefined;
 }
+/** Same idea, for `--config` — needed before dispatch too, to resolve `cfg.env` early. */
+function findConfigFlag(argv) {
+    const idx = argv.indexOf("--config");
+    return idx !== -1 ? argv[idx + 1] : undefined;
+}
 /**
  * The moment someone types a chain name that doesn't resolve is the highest-
  * traffic place a broken `.spf/chains/*.yaml` file is ever discovered — and,
@@ -104,6 +110,20 @@ export async function main() {
     catch {
         // no .env there — fine, nothing to load
     }
+    // `cfg.env` (spf.config.yaml's declarative env-var defaults — see
+    // data_types.ts's SFConfigSchema doc comment) has to land in process.env
+    // BEFORE any command reads it (SPF_CLAUDE_CMD, a provider key, ...), and
+    // .env/the real shell (just loaded above) must still win over it. Best-
+    // effort only: a config that fails to load here (missing, invalid yaml) is
+    // reported properly by whatever the actual command's own `agents.loadConfig`
+    // call does moments later — this pass exists purely to apply `env`, early.
+    try {
+        const resolution = paths.resolveConfigPaths(anchor, findConfigFlag(rest));
+        agents.applyConfigEnv(agents.loadConfig(resolution.paths).env);
+    }
+    catch {
+        // reported properly by the real command dispatch below, if it matters there
+    }
     // Repo-local chains as DATA: a `.spf/chains/*.yaml` file names existing
     // step factories, it never imports repo code — SPF's own dispatcher stays
     // the one thing that ever executes. Registered here, before the command

package/dist/cli/interview.js

@@ -79,6 +79,11 @@ export async function runInterview(asker, ctx) {
     const defaults = {};
     const agentOverrides = [];
     const env = {};
+    // Declarative, non-secret env vars — written to spf.config.yaml's `env:`
+    // (committable) rather than `.env` (gitignored, and read once from the
+    // shell rather than declared). `SPF_CLAUDE_CMD` is the one case so far:
+    // it names a launcher/wrapper command, not a credential.
+    const configEnv = {};
     const envExampleKeys = [];
     const notes = [];
     // ── 1. coding agent ────────────────────────────────────────────────────────
@@ -92,9 +97,9 @@ export async function runInterview(asker, ctx) {
         if (!ctx.claudeOnPath) {
             asker.note("warning: `claude` was not found on PATH — install it (or set a launch command below) before running spf.");
         }
-        const launchCommand = await asker.text('Launch command for the `claude` CLI — e.g. "ollama launch claude" to route through a wrapper (SPF_CLAUDE_CMD)', { default: "claude" });
+        const launchCommand = await asker.text('Launch command for the `claude` CLI — e.g. "ollama launch claude --model {model}" to route through a wrapper, with {model} substituted per-agent (writes env.SPF_CLAUDE_CMD to spf.config.yaml)', { default: "claude" });
         if (launchCommand !== "claude")
-            env["SPF_CLAUDE_CMD"] = launchCommand;
+            configEnv["SPF_CLAUDE_CMD"] = launchCommand;
         const model = await asker.select("Model (Claude Code's own vocabulary — not provider/model-id)", [
             { value: "sonnet", label: "sonnet" },
             { value: "opus", label: "opus" },
@@ -432,6 +437,8 @@ export async function runInterview(asker, ctx) {
     const quality = defaults["__quality__"];
     delete defaults["__quality__"];
     const config = { defaults };
+    if (Object.keys(configEnv).length > 0)
+        config.env = configEnv;
     if (agentOverrides.length > 0)
         config.agents = agentOverrides;
     if (quality)

package/dist/core/agent_cc.d.ts

@@ -8,8 +8,11 @@
  * dependencies, the same trade the pre-Flue `agent_pi.ts` made for `pi`.
  *
  * The `claude` command is resolved from `PATH` by default. To route it through
- * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD`
- * before running spf. Space-separated command chains are supported:
+ * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD` —
+ * ordinarily via `env: { SPF_CLAUDE_CMD: "..." }` in `spf.config.yaml`
+ * (see `SFConfigSchema`'s doc comment), since this is a declarative launcher
+ * choice, not a secret; a real shell export still works and still wins, for
+ * a one-off local override. Space-separated command chains are supported:
  *   - `SPF_CLAUDE_CMD="claude"` (default)
  *   - `SPF_CLAUDE_CMD="ollama launch claude --model <tag>"` (Ollama launcher —
  *     the `--model` is `ollama launch`'s OWN flag, and is mandatory in
@@ -17,6 +20,17 @@
  * The command/launcher must support the full Claude Code CLI interface.
  * When unset, defaults to `claude`.
  *
+ * A literal `{model}` token anywhere in `SPF_CLAUDE_CMD` is substituted with
+ * THIS call's own `request.model` before spawning — e.g.
+ * `SPF_CLAUDE_CMD="ollama launch claude --model {model}"` with one agent's
+ * `model: kimi-k2.7-code:cloud` and another's `model: qwen3-coder:cloud`
+ * genuinely dispatches each to its own model, since `ollama launch`'s
+ * `--model` (its OWN flag, resolved BEFORE `--`, not `claude`'s) is what
+ * actually pins which model serves the whole launched process — without
+ * `{model}`, that flag would have to be one fixed value for every
+ * claude_code agent in the roster, making each agent's own `model:` field
+ * inert no matter what it said.
+ *
  * Wrapper contract for the flags this module appends (`-p`, `--json-schema`,
  * `--model`, ...): a wrapper token chain is spawned as `[...cmdTokens,
  * ...args]`, so a plain passthrough shim needs nothing special, and a
@@ -101,6 +115,14 @@ export declare class CcToolCallTracker {
     private finish;
 }
 export declare function isKnownToolName(name: string): boolean;
+/**
+ * Resolve `SPF_CLAUDE_CMD` for THIS call, substituting a literal `{model}`
+ * token with `model` — see the module doc comment for why a fixed tag baked
+ * into the wrapper string can't give per-agent model choice under a
+ * launcher like `ollama launch`. Exported as its own pure function so this
+ * substitution is unit-testable without spawning a real subprocess.
+ */
+export declare function resolveClaudeCmdSpec(model: string): string;
 /** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
 export declare function shutdown(): Promise<void>;
 /**

package/dist/core/agent_cc.js

@@ -8,8 +8,11 @@
  * dependencies, the same trade the pre-Flue `agent_pi.ts` made for `pi`.
  *
  * The `claude` command is resolved from `PATH` by default. To route it through
- * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD`
- * before running spf. Space-separated command chains are supported:
+ * a wrapper, proxy server, or launcher (e.g., Ollama), set `SPF_CLAUDE_CMD` —
+ * ordinarily via `env: { SPF_CLAUDE_CMD: "..." }` in `spf.config.yaml`
+ * (see `SFConfigSchema`'s doc comment), since this is a declarative launcher
+ * choice, not a secret; a real shell export still works and still wins, for
+ * a one-off local override. Space-separated command chains are supported:
  *   - `SPF_CLAUDE_CMD="claude"` (default)
  *   - `SPF_CLAUDE_CMD="ollama launch claude --model <tag>"` (Ollama launcher —
  *     the `--model` is `ollama launch`'s OWN flag, and is mandatory in
@@ -17,6 +20,17 @@
  * The command/launcher must support the full Claude Code CLI interface.
  * When unset, defaults to `claude`.
  *
+ * A literal `{model}` token anywhere in `SPF_CLAUDE_CMD` is substituted with
+ * THIS call's own `request.model` before spawning — e.g.
+ * `SPF_CLAUDE_CMD="ollama launch claude --model {model}"` with one agent's
+ * `model: kimi-k2.7-code:cloud` and another's `model: qwen3-coder:cloud`
+ * genuinely dispatches each to its own model, since `ollama launch`'s
+ * `--model` (its OWN flag, resolved BEFORE `--`, not `claude`'s) is what
+ * actually pins which model serves the whole launched process — without
+ * `{model}`, that flag would have to be one fixed value for every
+ * claude_code agent in the roster, making each agent's own `model:` field
+ * inert no matter what it said.
+ *
  * Wrapper contract for the flags this module appends (`-p`, `--json-schema`,
  * `--model`, ...): a wrapper token chain is spawned as `[...cmdTokens,
  * ...args]`, so a plain passthrough shim needs nothing special, and a
@@ -225,6 +239,16 @@ const EFFORT_MAP = {
     xhigh: "xhigh",
     max: "max",
 };
+/**
+ * Resolve `SPF_CLAUDE_CMD` for THIS call, substituting a literal `{model}`
+ * token with `model` — see the module doc comment for why a fixed tag baked
+ * into the wrapper string can't give per-agent model choice under a
+ * launcher like `ollama launch`. Exported as its own pure function so this
+ * substitution is unit-testable without spawning a real subprocess.
+ */
+export function resolveClaudeCmdSpec(model) {
+    return (process.env.SPF_CLAUDE_CMD || "claude").replaceAll("{model}", model);
+}
 // ── process lifecycle ────────────────────────────────────────────────────────
 const inFlight = new Set();
 /** Kill any still-running `claude` children — call once, at process exit. Safe if none are running. */
@@ -278,7 +302,7 @@ export async function run(request, onEvent, onSpawn, onExit) {
         toolsFlagValue(request.tools),
         "--strict-mcp-config", // see the module doc comment — required, not optional
     ];
-    const cmdSpec = process.env.SPF_CLAUDE_CMD || "claude";
+    const cmdSpec = resolveClaudeCmdSpec(request.model);
     const cmdTokens = cmdSpec.split(/\s+/).filter(Boolean);
     const [cmd, ...cmdArgs] = cmdTokens;
     // See the module doc comment for why `ollama launch ...` (and ONLY that

package/dist/core/agents.d.ts

@@ -75,6 +75,26 @@ export declare function assertRunBudget(run: RunBudgetState): void;
  * and agents.validate() reports that plainly.
  */
 export declare function loadConfig(configPaths: string[]): SFConfig;
+/**
+ * `${VAR}` substitutes from `process.env` at call time — a real secret can
+ * live in `.env` (gitignored) and be referenced from the committed
+ * `spf.config.yaml` without ever being written into it. An undefined
+ * reference throws rather than silently interpolating to `""`: a value like
+ * `SPF_CLAUDE_CMD="ollama launch claude --model ${OLLAMA_TAG}"` silently
+ * missing its tag would fail confusingly far downstream (a launcher error,
+ * or a wrong-but-plausible model), not here where the actual cause is known.
+ */
+export declare function interpolateEnvValue(key: string, raw: string): string;
+/**
+ * Apply `cfg.env` to `process.env` — called once, in `cli/index.ts`'s
+ * `main()`, right after `.env` loads and before any command runs, so every
+ * later `process.env[...]` read (provider keys, `SPF_CLAUDE_CMD`, ...) sees
+ * the result. A key already set in `process.env` (a real shell export, or
+ * `.env`, both of which load before this) is left untouched — `cfg.env`
+ * supplies a DEFAULT, never forces an override, mirroring
+ * `process.loadEnvFile()`'s own precedence for `.env` itself.
+ */
+export declare function applyConfigEnv(env: Record<string, string>): void;
 export declare function resolve(cfg: SFConfig, name: string): AgentConfig;
 /** Fail fast: every required name must resolve to a usable agent. */
 export declare function validate(cfg: SFConfig, required: string[], requiredSuites?: string[], cwd?: string): void;

package/dist/core/agents.js

@@ -146,6 +146,9 @@ function mergeAgentLists(base, override) {
  */
 function mergeRawConfig(base, override) {
     return {
+        // Key-by-key, like `defaults`/`watch` — a repo override adding ONE env
+        // var shouldn't have to repeat every built-in one.
+        env: { ...(base.env || {}), ...(override.env || {}) },
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
         observability: { ...(base.observability || {}), ...(override.observability || {}) },
         quality: { ...(base.quality || {}), ...(override.quality || {}) },
@@ -220,6 +223,41 @@ export function loadConfig(configPaths) {
         throw new Error(`invalid config (${configPaths.join(", ")}): ${describeParseError(error)}`);
     }
 }
+const ENV_VAR_REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/**
+ * `${VAR}` substitutes from `process.env` at call time — a real secret can
+ * live in `.env` (gitignored) and be referenced from the committed
+ * `spf.config.yaml` without ever being written into it. An undefined
+ * reference throws rather than silently interpolating to `""`: a value like
+ * `SPF_CLAUDE_CMD="ollama launch claude --model ${OLLAMA_TAG}"` silently
+ * missing its tag would fail confusingly far downstream (a launcher error,
+ * or a wrong-but-plausible model), not here where the actual cause is known.
+ */
+export function interpolateEnvValue(key, raw) {
+    return raw.replace(ENV_VAR_REF, (_match, name) => {
+        const value = process.env[name];
+        if (value === undefined) {
+            throw new Error(`env.${key}: references \${${name}}, which is not set (.env or the shell) — set it before running spf`);
+        }
+        return value;
+    });
+}
+/**
+ * Apply `cfg.env` to `process.env` — called once, in `cli/index.ts`'s
+ * `main()`, right after `.env` loads and before any command runs, so every
+ * later `process.env[...]` read (provider keys, `SPF_CLAUDE_CMD`, ...) sees
+ * the result. A key already set in `process.env` (a real shell export, or
+ * `.env`, both of which load before this) is left untouched — `cfg.env`
+ * supplies a DEFAULT, never forces an override, mirroring
+ * `process.loadEnvFile()`'s own precedence for `.env` itself.
+ */
+export function applyConfigEnv(env) {
+    for (const [key, rawValue] of Object.entries(env)) {
+        if (process.env[key] !== undefined)
+            continue;
+        process.env[key] = interpolateEnvValue(key, rawValue);
+    }
+}
 export function resolve(cfg, name) {
     const agent = cfg.agents.find((a) => a.name === name);
     if (!agent) {

package/dist/core/data_types.d.ts

@@ -804,6 +804,7 @@ export declare const TieringConfigSchema: v.ObjectSchema<{
 }, undefined>;
 export type TieringConfig = v.InferOutput<typeof TieringConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
+    readonly env: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, () => {}>;
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
         readonly model: v.OptionalSchema<v.StringSchema<undefined>, "google/gemini-3.6-flash">;

package/dist/core/data_types.js

@@ -647,6 +647,17 @@ export const TieringConfigSchema = v.object({
     roles: v.optional(v.record(v.string(), v.string()), () => ({})),
 });
 export const SFConfigSchema = v.object({
+    // Declarative env vars, applied to process.env before anything else reads
+    // it (see cli/index.ts's main()) — for non-secret settings that used to
+    // require an out-of-band shell export (e.g. SPF_CLAUDE_CMD) to be
+    // committable, plain text config instead of hidden process state. A value
+    // already set in process.env (the real shell, or .env, which loads first)
+    // always wins — this only supplies a DEFAULT, never forces an override.
+    // `${VAR}` inside a value interpolates from process.env at that same
+    // point, specifically so a real secret can be pulled in from `.env`
+    // without ever being written into this (committed) file — see
+    // `applyConfigEnv`/`interpolateEnvValue` in agents.ts.
+    env: v.optional(v.record(v.string(), v.string()), () => ({})),
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
     observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
     agents: v.optional(v.array(AgentConfigSchema), () => []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",