@gr8ful/spf 0.2.1 → 0.4.0

package/dist/cli/commands/doctor.js

@@ -13,6 +13,7 @@ import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import * as permissions from "../../core/permissions.js";
 import * as agentCc from "../../core/agent_cc.js";
+import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
 import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
@@ -142,6 +143,23 @@ export function doctorCommand(argv) {
                 : 'not set — Bitbucket app passwords are being removed; spf watch needs an Atlassian account email plus an API token instead; see README.md\'s "spf watch" section');
         }
         check(report, "watch.chain", Boolean(findChain(cfg.watch.chain)), findChain(cfg.watch.chain) ? cfg.watch.chain : `"${cfg.watch.chain}" is not a registered chain`);
+        if (cfg.watch.refine.enabled) {
+            check(report, "watch.refine.chain", Boolean(findChain(cfg.watch.refine.chain)), findChain(cfg.watch.refine.chain) ? cfg.watch.refine.chain : `"${cfg.watch.refine.chain}" is not a registered chain`);
+            check(report, "watch.refine issue authoring", cfg.watch.issue_provider === "github", cfg.watch.issue_provider === "github"
+                ? "github supports issue authoring (createIssue/sub-issues)"
+                : `watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — the refine lane needs "github" (Jira issue authoring isn't implemented yet)`);
+        }
+    }
+    if (cfg.notifications.events !== "off") {
+        check(report, "notifications.events", true, cfg.notifications.events);
+        if (cfg.notifications.channels.length === 0) {
+            check(report, "notifications.channels", false, `notifications.events is ${JSON.stringify(cfg.notifications.events)} but no channels are configured`);
+        }
+        for (const ch of cfg.notifications.channels) {
+            const envKey = ch.webhook_url_env || DEFAULT_NOTIFY_ENV_KEY[ch.kind];
+            const label = ch.name ? `${ch.kind} (${ch.name})` : ch.kind;
+            check(report, `notifications: ${label}`, Boolean(process.env[envKey]), process.env[envKey] ? `${envKey} set` : `${envKey} is not set`);
+        }
     }
     return finish(report, flags["json"]);
 }

package/dist/cli/commands/init.js

@@ -10,6 +10,14 @@
  * `src/cli/index.ts`). Piped input, `--yes`, or `--template <name>` all
  * fall through to the original non-interactive behavior unchanged — a
  * scripted `spf init` must never hang waiting on stdin.
+ *
+ * Every path here also installs the repo-local Claude Code skill (the same
+ * work `spf install-skill` does by hand) unless `--no-skills` is passed —
+ * on every run, not just the first: `install-skill` is idempotent (a no-op
+ * once the skill is already up to date), so this never re-does work or
+ * clobbers a locally-edited skill file. `--user` (installing to
+ * `~/.claude/skills/spf` instead) stays a `spf install-skill` invocation of
+ * its own; `init` only ever writes the repo-local default.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -22,6 +30,7 @@ import { paint } from "../../core/console.js";
 import { createAsker, isInteractive, InterviewAborted } from "../ask.js";
 import { gatherContext, runInterview } from "../interview.js";
 import { readEnvFile, upsertEnvFile, writeEnvExample } from "../env_file.js";
+import { installSkillCommand } from "./install-skill.js";
 const TEMPLATE_SUFFIX = ".spf.config.yaml";
 /** Every template's short name (e.g. "ts-cc"), derived from disk rather than hand-maintained — never drifts from what's actually packaged. */
 function listTemplates() {
@@ -67,8 +76,8 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 # explicit Flue-style provider/model-id strings, and an agent's own model
 # always wins over defaults.model — so those three keep running on whatever
 # backend you just switched to, with a model id it can't resolve, unless
-# you override their model here too (builder/scout have no model of their
-# own in the packaged roster, so they need no override). See
+# you override their model here too (builder/scout/refiner have no model of
+# their own in the packaged roster, so they need no override). See
 # assets/templates/ts.spf.config.yaml (or --template ts) for the full
 # working pattern.
 
@@ -86,6 +95,27 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+#   # Optional second lane: decompose a spf:spec-ready product spec into a
+#   # feature/story-or-bug tree of real issues. Off by default; needs
+#   # issue_provider: github — issue authoring isn't implemented for Jira yet.
+#   refine:
+#     enabled: true
+#     chain: refine
+#     concurrency: 1
+
+# Uncomment to push notifications for unattended work — spf watch's daemon
+# lifecycle, and every chain run (spf <chain> / spf run, including watch's
+# own per-issue runs). Interactive commands (doctor, list, sessions, ...)
+# never notify — you're already looking at the terminal for those. events:
+# "errors" sends only failures/blocked issues; "all" adds every milestone
+# (run started, issue claimed, PR opened, ...). The URL is a secret and
+# lives only in .env — never in this file. See README.md's "Notifications"
+# section for how to get each webhook URL.
+# notifications:
+#   events: errors            # off (default) | errors | all
+#   channels:
+#     - kind: slack            # slack | teams | webhook
+#       webhook_url_env: SLACK_WEBHOOK_URL   # default for slack; TEAMS_WEBHOOK_URL / SPF_WEBHOOK_URL for the others
 `;
 // .spf/spf.config.yaml and .spf/prompt_engineering/ stay tracked — they're
 // shared project config, same as package.json. Only runtime/generated
@@ -99,10 +129,18 @@ const GENERATED_HEADER = `# .spf/spf.config.yaml — written by \`spf init\`'s i
 # (gitignored) — .env.example lists the key names only.
 `;
 export async function initCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes"]);
+    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes", "no-skills"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
     const sfDir = path.join(anchor.repo_root, ".spf");
     mkdirSync(sfDir, { recursive: true });
+    // Idempotent (a no-op once the skill is already up to date, a `.new`
+    // sibling rather than an overwrite for a locally-edited file) — safe to
+    // call on every `spf init`, not just the first.
+    const installSkill = () => {
+        if (flags["no-skills"])
+            return;
+        installSkillCommand(options["cwd"] ? ["--cwd", options["cwd"]] : []);
+    };
     const configPath = path.join(sfDir, "spf.config.yaml");
     const templateName = options["template"];
     const interactive = !templateName && !flags["yes"] && isInteractive();
@@ -115,6 +153,7 @@ export async function initCommand(argv) {
             writeFileSync(configPath, content);
             console.log(`wrote ${configPath}${templateName ? ` (from template "${templateName}")` : ""}`);
         }
+        installSkill();
     }
     else {
         const asker = createAsker();
@@ -124,6 +163,7 @@ export async function initCommand(argv) {
                 if (!overwrite) {
                     console.log("leaving the existing config alone (--force to skip this prompt)");
                     asker.close();
+                    installSkill();
                     ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
                     return 0;
                 }
@@ -141,6 +181,7 @@ export async function initCommand(argv) {
             if (Object.keys(result.env).length > 0)
                 upsertEnvFile(anchor.repo_root, result.env);
             writeEnvExample(anchor.repo_root, result.envExampleKeys);
+            installSkill();
             // The same merge-then-validate pipeline `spf doctor` runs — catches a
             // bad answer (e.g. a suite naming an unconfigured check) right after
             // writing, not at the user's first real chain run. Non-fatal: the

package/dist/cli/commands/install-skill.js

@@ -1,7 +1,10 @@
 /**
  * `spf install-skill` — copy the packaged Claude Code skill (`assets/skill/`)
- * into a target repo (or `~/.claude/skills/spf` with `--user`), on explicit
- * request only. Nothing here ever runs unless a user asks for it.
+ * into a target repo (or `~/.claude/skills/spf` with `--user`). `spf init`
+ * calls this itself, every run, unless `--no-skills` is passed — it's the
+ * command name a user (or a script) still reaches for by hand: to reinstall
+ * after an edit, to target `--user` instead of repo-local, or on a repo
+ * that never ran `spf init` at all (a pure-built-ins setup).
  *
  * Idempotent via a manifest (`.spf-skill-version`: {package, version,
  * files: {relpath: sha256}}) written at the skill root:

package/dist/cli/commands/list.js

@@ -9,5 +9,6 @@ export function listCommand() {
         console.log();
     }
     console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>]   (spf run <name> ... works identically)`);
+    console.log(`spf watch polls a tracker and runs one of these chains per issue — spf doctor shows the current config.`);
     return 0;
 }

package/dist/cli/commands/run.js

@@ -2,7 +2,7 @@
 import * as paths from "../../core/paths.js";
 import { parseCli, resolvePrompt } from "../../core/utils.js";
 import { runChain } from "../../chains/index.js";
-const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base"];
+const KNOWN_OPTIONS = ["config", "adw-id", "cwd", "agent", "base", "issue"];
 export function usageFor(chain) {
     return `usage: spf ${chain.name} "<prompt or path/to/prompt.md>" [--config <path>] [--adw-id <id>] [--cwd <dir>]`;
 }
@@ -19,6 +19,10 @@ export async function dispatchChain(chain, argv) {
         adw_id: options["adw-id"] ?? null,
         cwd: anchor.cwd,
         chain_name: chain.name,
+        // Only `refine` reads this (a "## Parent: #<id>" back-reference on
+        // every issue it creates — see ChainContext's doc comment); every
+        // other chain ignores it, so it's harmless to always pass through.
+        issue_id: options["issue"] ?? null,
     };
     const chainOptions = {};
     if (options["agent"] !== undefined)

package/dist/cli/commands/watch.js

@@ -10,6 +10,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
+import { resolveNotifier } from "../../core/notify/notifier.js";
 import { isRepoAt, makeGit } from "../../core/git_helper.js";
 import { GitHubProvider } from "../../core/issues/github_provider.js";
 import { JiraProvider } from "../../core/issues/jira_provider.js";
@@ -149,6 +150,21 @@ export async function watchCommand(argv) {
         console.error(`watch.chain ${JSON.stringify(cfg.watch.chain)} is not a registered chain — run \`spf list\` to see every chain`);
         return 1;
     }
+    if (cfg.watch.refine.enabled) {
+        if (cfg.watch.issue_provider !== "github") {
+            // Fail loudly at startup, not silently every tick: JiraProvider
+            // doesn't implement IssueAuthoringProvider yet (see its module
+            // comment) — a refine lane that can never publish would otherwise
+            // just claim every spec-ready spec and block it, forever.
+            console.error(`watch.refine.enabled is true but watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — ` +
+                `the refine lane needs "github" (issue authoring isn't implemented for Jira yet)`);
+            return 1;
+        }
+        if (!findChain(cfg.watch.refine.chain)) {
+            console.error(`watch.refine.chain ${JSON.stringify(cfg.watch.refine.chain)} is not a registered chain — run \`spf list\` to see every chain`);
+            return 1;
+        }
+    }
     const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
     const lockPath = path.join(dataPaths.data_dir, "watch.lock");
     try {
@@ -161,6 +177,9 @@ export async function watchCommand(argv) {
     const git = makeGit(anchor.repo_root);
     const worktreesDir = path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees");
     mkdirSync(worktreesDir, { recursive: true });
+    // `null` when notifications are off/unconfigured — every call below is a
+    // no-op fallback to `console.error` in that case (see notify()`s default).
+    const notifier = resolveNotifier(cfg, { dryRun: Boolean(flags["dry-run"]) });
     /**
      * Without this, a claimed issue's chain resolves its session/trace data
      * relative to `cwd` (the worktree, not the main repo — see
@@ -182,25 +201,65 @@ export async function watchCommand(argv) {
         mkdirSync(path.dirname(target), { recursive: true });
         symlinkSync(dataPaths.data_dir, target, "dir");
     }
+    /** Shared by `runChain`/`runRefine`: best-effort enrichment of a generic "didn't succeed" message with the first phase that actually failed, read back from the worktree's own (symlinked) trace db. */
+    function detailFromFailedPhase(cwd, adwId, prefix) {
+        let detail = prefix;
+        try {
+            const wtAnchor = paths.resolveAnchor(cwd);
+            const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
+            const db = new SfDb(wtDataPaths.db_path);
+            const failed = db.phases(adwId).find((p) => p.status === "fail");
+            if (failed)
+                detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
+        }
+        catch {
+            // best-effort — the generic message above still points at where to look
+        }
+        return detail;
+    }
     const runChain = async (opts) => {
         const chainDef = findChain(cfg.watch.chain); // checked above
         const ctx = { prompt: opts.prompt, config_paths: configPaths, adw_id: opts.adwId, cwd: opts.cwd, chain_name: chainDef.name };
         const code = await runChainDef(chainDef, ctx);
         if (code === 0)
             return { accepted: true, adwId: opts.adwId, detail: "" };
-        let detail = `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`;
+        const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Chain "${cfg.watch.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
+        return { accepted: false, adwId: opts.adwId, detail };
+    };
+    /**
+     * Same shape as `runChain`, for the refine lane — with one extra step on
+     * success: a chain's return value is just an exit code, so the created-
+     * issues list `steps.publishIssues()` actually produced has to come back
+     * through the side channel it wrote (`refine_publish.json`, under the
+     * SAME symlinked session dir `linkDataDir` already wires up), not through
+     * `runChainDef`'s return value.
+     */
+    const runRefine = async (opts) => {
+        const chainDef = findChain(cfg.watch.refine.chain); // checked above
+        const ctx = {
+            prompt: opts.prompt,
+            config_paths: configPaths,
+            adw_id: opts.adwId,
+            cwd: opts.cwd,
+            chain_name: chainDef.name,
+            issue_id: opts.issueId,
+        };
+        const code = await runChainDef(chainDef, ctx);
+        if (code !== 0) {
+            const detail = detailFromFailedPhase(opts.cwd, opts.adwId, `Refine chain "${cfg.watch.refine.chain}" (adw_id ${opts.adwId}) did not complete successfully. Run \`spf phases ${opts.adwId} --cwd ${opts.cwd}\` for detail.`);
+            return { accepted: false, adwId: opts.adwId, detail, created: [] };
+        }
+        let created = [];
         try {
             const wtAnchor = paths.resolveAnchor(opts.cwd);
             const wtDataPaths = paths.resolveDataPaths(wtAnchor, cfg.defaults.data_dir, cfg.observability.db);
-            const db = new SfDb(wtDataPaths.db_path);
-            const failed = db.phases(opts.adwId).find((p) => p.status === "fail");
-            if (failed)
-                detail += ` Phase "${failed.name}" failed: ${failed.error ?? "(no detail)"}`;
+            const summaryPath = path.join(wtDataPaths.data_dir, "sessions", opts.adwId, "context_handoff", "refine_publish.json");
+            created = JSON.parse(readFileSync(summaryPath, "utf-8"));
         }
         catch {
-            // best-effort — the generic message above still points at where to look
+            // best-effort — an empty list still lets runSpec finish cleanly, just with no per-issue summary
         }
-        return { accepted: false, adwId: opts.adwId, detail };
+        return { accepted: true, adwId: opts.adwId, detail: "", created };
     };
     const deps = {
         provider,
@@ -211,11 +270,16 @@ export async function watchCommand(argv) {
         chain: cfg.watch.chain,
         baseBranch: cfg.watch.base_branch,
         concurrency: cfg.watch.concurrency,
+        refineEnabled: cfg.watch.refine.enabled,
+        refineConcurrency: cfg.watch.refine.concurrency,
+        refineChain: cfg.watch.refine.chain,
+        runRefine,
         worktreesDir,
         linkDataDir,
         dryRun: Boolean(flags["dry-run"]),
         runChain,
         log: (message) => console.log(message),
+        notify: (event) => notifier?.send(event),
     };
     const state = createWatchState();
     let stopping = false;
@@ -249,7 +313,19 @@ export async function watchCommand(argv) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
-    console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}${flags["dry-run"] ? "  (dry run)" : ""}`);
+    console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}` +
+        (cfg.watch.refine.enabled ? `  refine "${cfg.watch.refine.chain}" concurrency ${cfg.watch.refine.concurrency}` : "") +
+        (flags["dry-run"] ? "  (dry run)" : ""));
+    deps.notify({
+        kind: "watch_started",
+        level: "info",
+        title: "watch started",
+        fields: [
+            ["repo", cfg.watch.repo],
+            ["label_prefix", cfg.watch.label_prefix],
+            ["chain", cfg.watch.chain],
+        ],
+    });
     try {
         for (;;) {
             await tick(deps, state);
@@ -268,6 +344,8 @@ export async function watchCommand(argv) {
         return 0;
     }
     finally {
+        deps.notify({ kind: "watch_stopped", level: "info", title: "watch stopped", fields: [["repo", cfg.watch.repo]] });
+        await notifier?.flush();
         process.off("SIGINT", stop);
         process.off("SIGTERM", stop);
         releaseLock(lockPath);

package/dist/cli/index.js

@@ -7,6 +7,7 @@
 import path from "node:path";
 import * as agentCc from "../core/agent_cc.js";
 import * as agentFlue from "../core/agent_flue.js";
+import * as notify from "../core/notify/notifier.js";
 import * as paths from "../core/paths.js";
 import { findChain } from "../chains/index.js";
 import { dispatchChain, usageFor } from "./commands/run.js";
@@ -27,8 +28,8 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
 
   spf list                                  the chain registry — names, phases, what each needs
   spf <chain> "<prompt>" [options]          run a chain (spf run <chain> ... works identically)
-  spf init [--force] [--yes] [--template <name>]  interview to seed .spf/spf.config.yaml + .env (--yes/--template skip the interview)
-  spf install-skill [--user] [--force]      install the Claude Code skill (repo-local by default)
+  spf init [--force] [--yes] [--template <name>] [--no-skills]  interview to seed .spf/spf.config.yaml + .env, and install the Claude Code skill unless --no-skills (--yes/--template skip the interview, not the skill install)
+  spf install-skill [--user] [--force]      (re)install the Claude Code skill by hand — spf init already does this
   spf migrate [--apply] [--force]           move an old stamped adws/ tree onto .spf/ (dry run by default)
   spf eject [--target <dir>] [--force]      copy the installed engine out for reference/hand-editing
   spf doctor [--json]                       check everything that fails silently otherwise
@@ -41,7 +42,7 @@ const HELP = `spf — repeatable agents-plus-code workflows (ADWs)
   spf abort <adw_id>                        signal a run's process to stop
   spf version                               print the installed version
 
-Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>]
+Chain options: [--config <path>] [--adw-id <id>] [--cwd <dir>] [--agent <name>] [--base <ref>] [--issue <id>]
 Run \`spf list\` to see every chain and what it needs.`;
 /** A raw scan for `--cwd`, ahead of any command-specific argv parsing — every command that takes it means the same thing by it. */
 function findCwdFlag(argv) {
@@ -152,5 +153,8 @@ export async function main() {
         // agent_cc.ts's shutdown() just kills any still-running claude children.
         await agentFlue.shutdown();
         await agentCc.shutdown();
+        // A no-op if notifications are off/unconfigured — awaits any in-flight
+        // webhook POST so a fast-exiting command doesn't drop it mid-flight.
+        await notify.flushAll();
     }
 }

package/dist/cli/interview.d.ts

@@ -8,6 +8,8 @@ export interface DetectedContext {
     claudeOnPath: boolean;
     /** Whatever's already in `.env` — shown masked so a re-run can offer "keep current" instead of asking blind. */
     existingEnv: Map<string, string>;
+    /** The packaged roster's agent names (planner, builder, scout, reviewer, documenter today) — read from the built-in config so a 6th agent added there needs no interview change. */
+    rosterNames: string[];
 }
 export declare function gatherContext(repoRoot: string, existingEnv?: Map<string, string>): DetectedContext;
 export interface InterviewResult {

package/dist/cli/interview.js

@@ -18,6 +18,9 @@ import { binaryOnPath } from "../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../core/providers.js";
 import { resolveModel } from "../core/agent_flue.js";
 import { ThinkingLevelSchema } from "../core/data_types.js";
+import { loadConfig } from "../core/agents.js";
+import { BUILTIN_CONFIG_PATH } from "../core/paths.js";
+import { DEFAULT_NOTIFY_ENV_KEY } from "../core/notify/notifier.js";
 import { CHAINS } from "../chains/index.js";
 function gitConfigValue(repoRoot, key) {
     const result = spawnSync("git", ["config", key], { cwd: repoRoot, encoding: "utf-8" });
@@ -40,6 +43,15 @@ function readScripts(repoRoot) {
         return {};
     }
 }
+/** Best-effort — a corrupt/missing built-in config falls back to the three names the auto-override already knows about, rather than failing the whole interview. */
+function readRosterNames() {
+    try {
+        return loadConfig([BUILTIN_CONFIG_PATH]).agents.map((a) => a.name);
+    }
+    catch {
+        return ["planner", "builder", "scout", "reviewer", "documenter"];
+    }
+}
 export function gatherContext(repoRoot, existingEnv = new Map()) {
     const remote = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: repoRoot, encoding: "utf-8" });
     const branch = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: repoRoot, encoding: "utf-8" });
@@ -51,6 +63,7 @@ export function gatherContext(repoRoot, existingEnv = new Map()) {
         scripts: readScripts(repoRoot),
         claudeOnPath: binaryOnPath("claude"),
         existingEnv,
+        rosterNames: readRosterNames(),
     };
 }
 const QUALITY_TIMEOUTS = { typecheck: 60, lint: 60, build: 120, test: 180 };
@@ -79,7 +92,7 @@ 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 (space-separated; SPF_CLAUDE_CMD)", { default: "claude" });
+        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" });
         if (launchCommand !== "claude")
             env["SPF_CLAUDE_CMD"] = launchCommand;
         const model = await asker.select("Model (Claude Code's own vocabulary — not provider/model-id)", [
@@ -142,6 +155,34 @@ export async function runInterview(asker, ctx) {
             env[envKey] = key;
         envExampleKeys.push(envKey);
     }
+    // Declined (the default): today's behavior exactly — on claude_code, the
+    // three-agent auto-pin above stands unchanged; on flue, no agents: block
+    // at all. Accepted: ask every roster agent's model, defaulting to the one
+    // chosen above, and patch/append its override — `mergeAgentLists`
+    // (agents.ts:63-71) shallow-patches by name, so re-setting `model` on an
+    // already-pinned entry (claude_code's planner/reviewer/documenter) is
+    // exactly the right shape, no `prompt_engineering` needed (interview.ts's
+    // review-section comment explains why that's fine).
+    const customizeModels = await asker.confirm("Customize models per agent?", false);
+    if (customizeModels) {
+        asker.heading("Per-agent models");
+        for (const name of ctx.rosterNames) {
+            const answer = await asker.text(`  ${name}`, { default: String(defaults.model) });
+            if (codingAgent === "flue") {
+                try {
+                    resolveModel(answer);
+                }
+                catch (error) {
+                    asker.note(`warning: ${error.message}`);
+                }
+            }
+            const existing = agentOverrides.find((a) => a.name === name);
+            if (existing)
+                existing.model = answer;
+            else
+                agentOverrides.push({ name, model: answer });
+        }
+    }
     // ── 2. quality checks ──────────────────────────────────────────────────────
     asker.heading("Quality checks");
     asker.note("a chain that gates on a suite (e.g. plan-build-test's `test`) fails loudly before anything runs if the suite is unconfigured.");
@@ -190,6 +231,18 @@ export async function runInterview(asker, ctx) {
         const chainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
         const chain = await asker.select("Chain to run per issue", chainChoices, "plan-build-test");
         watch = { issue_provider: issueProvider, code_host: codeHost, repo, label_prefix: labelPrefix, chain, base_branch: baseBranch };
+        // Issue authoring (create + link a hierarchy) is only implemented on
+        // GitHubProvider today — see jira_provider.ts's module comment — so
+        // this lane isn't offered at all on a Jira tracker rather than asking a
+        // question that would just fail at `spf watch` startup.
+        if (issueProvider === "github") {
+            const enableRefine = await asker.confirm(`Also enable the refine lane (decompose a "${labelPrefix}:spec-ready" product spec into a feature/story-or-bug tree)?`, false);
+            if (enableRefine) {
+                const refineChainChoices = CHAINS.map((c) => ({ value: c.name, label: c.name, hint: c.describe }));
+                const refineChain = await asker.select("Chain to run per spec", refineChainChoices, "refine");
+                watch.refine = { enabled: true, chain: refineChain };
+            }
+        }
         if (issueProvider === "jira") {
             const baseUrl = await asker.text("Jira base URL", {
                 default: "https://your-domain.atlassian.net",
@@ -227,7 +280,46 @@ export async function runInterview(asker, ctx) {
             asker.note("Bitbucket app passwords are being removed — this needs an Atlassian API token instead.");
         }
     }
-    // ── 4. advanced (gated) ─────────────────────────────────────────────────────
+    // ── 4. notifications ─────────────────────────────────────────────────────────
+    asker.heading("Notifications");
+    const enableNotify = await asker.confirm("Send notifications to Slack, Teams, or a webhook?", false);
+    let notifications = null;
+    if (enableNotify) {
+        const events = await asker.select("Notify on", [
+            { value: "errors", label: "errors — failed runs, blocked issues, watch errors" },
+            { value: "all", label: "all — every milestone (claimed, PR opened, done, ...) plus errors" },
+        ], "errors");
+        const channels = [];
+        for (;;) {
+            const kind = await asker.select("Channel", [
+                { value: "slack", label: "Slack — Incoming Webhook" },
+                { value: "teams", label: "Microsoft Teams — Workflows webhook" },
+                { value: "webhook", label: "generic webhook — POSTs the raw event as JSON" },
+            ], "slack");
+            const envKey = DEFAULT_NOTIFY_ENV_KEY[kind];
+            if (kind === "slack") {
+                asker.note("Slack app -> Incoming Webhooks -> Add New Webhook to Workspace.");
+                asker.note("Docs: https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks");
+            }
+            else if (kind === "teams") {
+                asker.note("In the target channel, add a Workflows webhook template (search for one like \"Post to a channel when a webhook request is received\"). The old Office 365 connector webhooks are retired — this is the only path now.");
+                asker.note("Docs: https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498");
+            }
+            else {
+                asker.note("Any endpoint that accepts a JSON POST — Discord, n8n, Zapier, your own.");
+            }
+            const url = await asker.secret(envKey, { current: ctx.existingEnv.get(envKey) });
+            if (url)
+                env[envKey] = url;
+            envExampleKeys.push(envKey);
+            channels.push({ kind, webhook_url_env: envKey });
+            const another = await asker.confirm("Add another channel?", false);
+            if (!another)
+                break;
+        }
+        notifications = { events, channels };
+    }
+    // ── 5. advanced (gated) ─────────────────────────────────────────────────────
     const wantAdvanced = await asker.confirm("\nConfigure advanced settings (thinking level, tools, protected files, data dir, poll intervals, ...)?", false);
     if (wantAdvanced) {
         asker.heading("Advanced");
@@ -254,6 +346,11 @@ export async function runInterview(asker, ctx) {
             const concurrency = await asker.text("watch.concurrency", { default: "2" });
             if (concurrency !== "2")
                 watch.concurrency = Number(concurrency);
+            if (watch.refine?.enabled) {
+                const refineConcurrency = await asker.text("watch.refine.concurrency", { default: "1" });
+                if (refineConcurrency !== "1")
+                    watch.refine.concurrency = Number(refineConcurrency);
+            }
         }
         const engineerName = await asker.text("ENGINEER_NAME (falls back to `git config user.name`)", { default: ctx.gitName ?? "" });
         if (engineerName && engineerName !== ctx.gitName)
@@ -263,8 +360,13 @@ export async function runInterview(asker, ctx) {
             if (debug)
                 env["SPF_JIRA_DEBUG"] = "1";
         }
+        if (notifications) {
+            const timeoutMs = await asker.text("notifications.timeout_ms", { default: "5000" });
+            if (timeoutMs !== "5000")
+                notifications.timeout_ms = Number(timeoutMs);
+        }
     }
-    // ── 5. review + confirm ─────────────────────────────────────────────────────
+    // ── 6. review + confirm ─────────────────────────────────────────────────────
     const observability = defaults["__observability__"];
     delete defaults["__observability__"];
     const quality = defaults["__quality__"];
@@ -278,6 +380,8 @@ export async function runInterview(asker, ctx) {
         config.watch = watch;
     if (observability)
         config.observability = observability;
+    if (notifications)
+        config.notifications = notifications;
     // No schema validation here on purpose: `config.agents` overrides are
     // intentionally PARTIAL (name + model only, no prompt_engineering) — valid
     // only once merged by name into the packaged roster (agents.ts's

package/dist/core/agents.js

@@ -57,13 +57,16 @@ function mergeAgentLists(base, override) {
     }
     return merged;
 }
-/** `defaults`/`observability`/`quality` merge key-by-key; `agents` merges by name. */
+/** `defaults`/`observability`/`quality`/`watch`/`notifications` merge key-by-key; `agents` merges by name. */
 function mergeRawConfig(base, override) {
     return {
         defaults: { ...(base.defaults || {}), ...(override.defaults || {}) },
         observability: { ...(base.observability || {}), ...(override.observability || {}) },
         quality: { ...(base.quality || {}), ...(override.quality || {}) },
         watch: { ...(base.watch || {}), ...(override.watch || {}) },
+        // channels is a whole-array replace on override, same as quality.checks —
+        // you don't want an override's channels appended to the built-in's.
+        notifications: { ...(base.notifications || {}), ...(override.notifications || {}) },
         agents: mergeAgentLists(base.agents || [], override.agents || []),
     };
 }

package/dist/core/console.d.ts

@@ -7,6 +7,10 @@
  * so a CI log reads exactly like a terminal.
  */
 import type { EnvelopeBase, EventRecord, GateReport, Phase } from "./data_types.ts";
+import type { NotifyEvent } from "./notify/channel.ts";
+interface Notifier {
+    send(event: NotifyEvent): void;
+}
 export declare function paint(style: string, text: string): string;
 interface Tracer {
     event(record: EventRecord): string;
@@ -15,11 +19,19 @@ interface Tracer {
 export declare class Console {
     private tracer;
     private adwId;
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    private notifier;
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    private chainName;
     private phaseId;
     private phaseName;
     private results;
     private finished;
-    constructor(tracer: Tracer, adwId: string);
+    constructor(tracer: Tracer, adwId: string, 
+    /** `null` when notifications are off — every call site below guards with `?.`. */
+    notifier?: Notifier | null, 
+    /** The CLI chain name (`"plan-build-test"`), for a notification's title — see session.ts. */
+    chainName?: string);
     private emit;
     sessionStarted(adwId: string, engineer: string): void;
     sessionFinished(ok: boolean, tokens: number, cost: number, dbPath: string): void;