@gr8ful/spf 0.1.0

package/dist/chains/index.js

@@ -0,0 +1,116 @@
+import * as adwPrompt from "./adw_prompt.js";
+import * as adwScout from "./adw_scout.js";
+import * as adwPlan from "./adw_plan.js";
+import * as adwBuild from "./adw_build.js";
+import * as adwPlanBuild from "./adw_plan_build.js";
+import * as adwBuildTest from "./adw_build_test.js";
+import * as adwPlanBuildTest from "./adw_plan_build_test.js";
+import * as adwPlanBuildTestQuality from "./adw_plan_build_test_quality.js";
+import * as adwBuildReview from "./adw_build_review.js";
+import * as adwQuality from "./adw_quality.js";
+import * as adwDocument from "./adw_document.js";
+import * as adwSimpleSdlc from "./adw_simple_sdlc.js";
+export const CHAINS = [
+    {
+        name: "prompt",
+        describe: "one agent, one prompt, traced end to end — --agent <name> picks who (default: builder)",
+        phases: "engineer(request) -> <agent>",
+        requiredAgents: (options) => [options["agent"] ?? "builder"],
+        requiredSuites: [],
+        run: adwPrompt.main,
+    },
+    {
+        name: "scout",
+        describe: "read-only recon; nothing changes",
+        phases: "engineer(request) -> scout",
+        requiredAgents: adwScout.REQUIRED_AGENTS,
+        requiredSuites: adwScout.REQUIRED_SUITES,
+        run: adwScout.main,
+    },
+    {
+        name: "plan",
+        describe: "turn a request into an implementable plan",
+        phases: "engineer(request) -> planner",
+        requiredAgents: adwPlan.REQUIRED_AGENTS,
+        requiredSuites: adwPlan.REQUIRED_SUITES,
+        run: adwPlan.main,
+    },
+    {
+        name: "build",
+        describe: "implement an existing plan",
+        phases: "engineer(request) -> builder",
+        requiredAgents: adwBuild.REQUIRED_AGENTS,
+        requiredSuites: adwBuild.REQUIRED_SUITES,
+        run: adwBuild.main,
+    },
+    {
+        name: "plan-build",
+        describe: "small, well-understood work — plan, build, commit",
+        phases: "engineer(request) -> planner -> builder -> git(commit)",
+        requiredAgents: adwPlanBuild.REQUIRED_AGENTS,
+        requiredSuites: adwPlanBuild.REQUIRED_SUITES,
+        run: adwPlanBuild.main,
+    },
+    {
+        name: "build-test",
+        describe: "there is a suite to satisfy — build, test, bounded fix loop",
+        phases: "engineer(request) -> builder -> code(test) [-> builder(fix) -> code(test) ...]",
+        requiredAgents: adwBuildTest.REQUIRED_AGENTS,
+        requiredSuites: adwBuildTest.REQUIRED_SUITES,
+        run: adwBuildTest.main,
+    },
+    {
+        name: "plan-build-test",
+        describe: "the standard chain — plan, build, test, commit",
+        phases: "engineer(request) -> planner -> builder -> code(test) [-> fix loop] -> git(commit)",
+        requiredAgents: adwPlanBuildTest.REQUIRED_AGENTS,
+        requiredSuites: adwPlanBuildTest.REQUIRED_SUITES,
+        run: adwPlanBuildTest.main,
+    },
+    {
+        name: "plan-build-test-quality",
+        describe: "the repo has quality commands worth enforcing beyond tests — same, plus lint/typecheck/build gates",
+        phases: "engineer(request) -> planner -> builder -> code(quality:all) [-> fix loop] -> git(commit)",
+        requiredAgents: adwPlanBuildTestQuality.REQUIRED_AGENTS,
+        requiredSuites: adwPlanBuildTestQuality.REQUIRED_SUITES,
+        run: adwPlanBuildTestQuality.main,
+    },
+    {
+        name: "build-review",
+        describe: "\"is this what was asked for\" matters more than \"does it run\"",
+        phases: "engineer(request) -> builder -> reviewer [-> revise loop]",
+        requiredAgents: adwBuildReview.REQUIRED_AGENTS,
+        requiredSuites: adwBuildReview.REQUIRED_SUITES,
+        run: adwBuildReview.main,
+    },
+    {
+        name: "quality",
+        describe: "lint, typecheck, build — no agents at all",
+        phases: "engineer(request) -> code(quality:all)",
+        requiredAgents: adwQuality.REQUIRED_AGENTS,
+        requiredSuites: adwQuality.REQUIRED_SUITES,
+        run: adwQuality.main,
+    },
+    {
+        name: "document",
+        describe: "write up the work that was just done, from the diff",
+        phases: "engineer(request) -> code(changes) -> documenter",
+        requiredAgents: adwDocument.REQUIRED_AGENTS,
+        requiredSuites: adwDocument.REQUIRED_SUITES,
+        run: adwDocument.main,
+    },
+    {
+        name: "simple-sdlc",
+        describe: "the work is real and its shape is not obvious — plan, build, test, review, document; 3 commits",
+        phases: "engineer(request) -> planner -> builder -> code(test) -> reviewer -> code(changes) -> documenter",
+        requiredAgents: adwSimpleSdlc.REQUIRED_AGENTS,
+        requiredSuites: adwSimpleSdlc.REQUIRED_SUITES,
+        run: adwSimpleSdlc.main,
+    },
+];
+export function findChain(name) {
+    return CHAINS.find((c) => c.name === name);
+}
+export function resolveRequiredAgents(chain, options) {
+    return typeof chain.requiredAgents === "function" ? chain.requiredAgents(options) : chain.requiredAgents;
+}

package/dist/cli/bin.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * The process entry point. This file must have NO static imports of anything
+ * that transitively touches node:sqlite (that means core/tracer.ts and
+ * everything downstream of it) — ESM hoists static imports, so a static
+ * import here would evaluate node:sqlite, and emit its ExperimentalWarning,
+ * before the patch below ever runs. Dynamic import() is not hoisted, which
+ * is the whole reason this file is split from index.ts.
+ *
+ * NOTE: this is a Phase 1 stub — just enough to run one chain end-to-end for
+ * the golden-master verification. list/sessions/doctor/ui/etc. land in the
+ * CLI-surface phase; this file's dispatch logic will be replaced, not
+ * layered on top of.
+ */
+export {};

package/dist/cli/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * The process entry point. This file must have NO static imports of anything
+ * that transitively touches node:sqlite (that means core/tracer.ts and
+ * everything downstream of it) — ESM hoists static imports, so a static
+ * import here would evaluate node:sqlite, and emit its ExperimentalWarning,
+ * before the patch below ever runs. Dynamic import() is not hoisted, which
+ * is the whole reason this file is split from index.ts.
+ *
+ * NOTE: this is a Phase 1 stub — just enough to run one chain end-to-end for
+ * the golden-master verification. list/sessions/doctor/ui/etc. land in the
+ * CLI-surface phase; this file's dispatch logic will be replaced, not
+ * layered on top of.
+ */
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...rest) => {
+    const message = typeof warning === "string" ? warning : warning.message;
+    const type = typeof rest[0] === "string" ? rest[0] : rest[0]?.type;
+    if (type === "ExperimentalWarning" && message.includes("SQLite"))
+        return;
+    return originalEmitWarning(warning, ...rest);
+});
+await (await import("./index.js")).main();
+export {};

package/dist/cli/commands/abort.d.ts

@@ -0,0 +1 @@
+export declare function abortCommand(argv: string[]): number;

package/dist/cli/commands/abort.js

@@ -0,0 +1,42 @@
+/**
+ * `spf abort <adw_id>` — there is no in-process Flue handle to call .abort()
+ * on from a separate CLI invocation, so this is OS-level: find the pid(s)
+ * recorded as still running for this adw_id and SIGTERM them. Since Flue
+ * runs in-process, that pid is the whole `spf` invocation driving the chain
+ * — this stops the run, not just the current model call.
+ */
+import { Database } from "../../core/sqlite.js";
+import { parseCli } from "../../core/utils.js";
+import { openTrace } from "./trace.js";
+export function abortCommand(argv) {
+    const { positionals, options } = parseCli(argv, ["cwd", "config"]);
+    if (positionals.length < 1) {
+        console.error("usage: spf abort <adw_id> [--cwd <dir>] [--config <path>]");
+        return 1;
+    }
+    const adwId = positionals[0];
+    const { db, dataDir } = openTrace(options);
+    // SfDb opens read-only; a live process row needs a separate writable
+    // handle only to read it here (no write happens) — reuse the same file.
+    const raw = new Database(db.path, { readonly: true });
+    const rows = raw
+        .query("SELECT pid, kind, name, command FROM processes WHERE adw_id = ? AND ended_at IS NULL")
+        .all(adwId);
+    raw.close();
+    if (rows.length === 0) {
+        console.log(`no live process recorded for ${adwId} (data_dir: ${dataDir}) — it may have already finished, or crashed without closing its trace`);
+        return 1;
+    }
+    let ok = true;
+    for (const row of rows) {
+        try {
+            process.kill(row.pid, "SIGTERM");
+            console.log(`sent SIGTERM to pid ${row.pid} (${row.kind}${row.name ? `:${row.name}` : ""} — ${row.command})`);
+        }
+        catch (error) {
+            ok = false;
+            console.error(`could not signal pid ${row.pid}: ${error.message} — it may already be dead; the trace will still show it as running until finalizeWhenKilled's handler runs in that process`);
+        }
+    }
+    return ok ? 0 : 1;
+}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1 @@
+export declare function doctorCommand(argv: string[]): number;

package/dist/cli/commands/doctor.js

@@ -0,0 +1,165 @@
+/**
+ * `spf doctor` — the answer to every "why did nothing happen". Resolves and
+ * prints every anchor, validates the whole roster (not just what one chain
+ * needs), and checks the things that fail silently otherwise: a missing
+ * provider key, a quality check whose binary isn't on PATH, a
+ * protected_files pattern that matches nothing (how a stale path convention
+ * announces itself), an env-file that didn't load.
+ */
+import { existsSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+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 { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
+import { parseCli } from "../../core/utils.js";
+import { isRepoAt } from "../../core/git_helper.js";
+import { findChain } from "../../chains/index.js";
+// Common providers' env var conventions — public knowledge (pi-ai's own
+// resolution table is internal, unexported, and not something to reach into
+// for this). Missing from this table just means "unknown provider, skipped
+// the key check" — never a false failure.
+const PROVIDER_ENV_KEYS = {
+    anthropic: ["ANTHROPIC_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    google: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+    openrouter: ["OPENROUTER_API_KEY"],
+    fireworks: ["FIREWORKS_API_KEY"],
+    groq: ["GROQ_API_KEY"],
+    mistral: ["MISTRAL_API_KEY"],
+    xai: ["XAI_API_KEY"],
+    deepseek: ["DEEPSEEK_API_KEY"],
+    together: ["TOGETHER_API_KEY"],
+    cerebras: ["CEREBRAS_API_KEY"],
+};
+function check(report, name, ok, detail) {
+    report.checks.push({ name, ok, detail });
+    if (!ok)
+        report.ok = false;
+}
+function binaryOnPath(bin) {
+    if (path.isAbsolute(bin) || bin.includes("/"))
+        return existsSync(bin);
+    const result = spawnSync(process.platform === "win32" ? "where" : "which", [bin], { encoding: "utf-8" });
+    return result.status === 0;
+}
+export function doctorCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "config"], ["json"]);
+    const report = { ok: true, checks: [] };
+    check(report, "node version", true, process.version);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    check(report, "cwd", true, anchor.cwd);
+    check(report, "repo_root", true, anchor.repo_root);
+    // Informational only — no .spf/ is a fully valid, supported state (pure
+    // built-ins), never a failure on its own.
+    check(report, ".spf directory", true, anchor.spf_dir ?? "(none — running off packaged built-ins; run `spf init` to override)");
+    const isRepo = isRepoAt(anchor.repo_root);
+    check(report, "git repository", isRepo, isRepo ? "yes" : "no — commit phases and change capture will fail");
+    const resolution = paths.resolveConfigPaths(anchor, options["config"]);
+    check(report, "config resolution", true, `${resolution.source}: ${resolution.paths.join(" -> ")}`);
+    let cfg;
+    try {
+        cfg = agents.loadConfig(resolution.paths);
+        check(report, "config parses", true, `${cfg.agents.length} agent(s), ${Object.keys(cfg.quality.suites).length} quality suite(s)`);
+    }
+    catch (error) {
+        check(report, "config parses", false, error.message);
+        return finish(report, flags["json"]);
+    }
+    const dataPaths = paths.resolveDataPaths(anchor, cfg.defaults.data_dir, cfg.observability.db);
+    check(report, "data_dir", true, dataPaths.data_dir);
+    check(report, "db_path", true, `${dataPaths.db_path}${existsSync(dataPaths.db_path) ? "" : " (not created yet — fine before the first run)"}`);
+    check(report, "flue_db_path", true, path.join(dataPaths.data_dir, "flue.db"));
+    // Validate the WHOLE roster and EVERY declared suite — doctor's job is "is
+    // everything defined here healthy", not "can one specific chain run".
+    try {
+        agents.validate(cfg, cfg.agents.map((a) => a.name), Object.keys(cfg.quality.suites), anchor.cwd);
+        check(report, "roster + suites validate", true, "clean");
+    }
+    catch (error) {
+        check(report, "roster + suites validate", false, error.message);
+    }
+    const usesClaudeCode = cfg.agents.some((a) => a.coding_agent === "claude_code");
+    if (usesClaudeCode) {
+        const claudeOnPath = binaryOnPath("claude");
+        let version = "";
+        if (claudeOnPath) {
+            const result = spawnSync("claude", ["--version"], { encoding: "utf-8" });
+            version = result.status === 0 ? result.stdout.trim() : "";
+        }
+        check(report, "claude CLI", claudeOnPath, claudeOnPath ? version || "on PATH, but --version failed" : "not found on PATH — required by any coding_agent: claude_code agent");
+    }
+    for (const agent of cfg.agents) {
+        const label = `agent "${agent.name}"`;
+        if (agent.coding_agent === "claude_code") {
+            // No provider-key hard-fail here, unlike Flue: Claude Code also
+            // supports its own `claude login`/OAuth flow, so a missing
+            // ANTHROPIC_API_KEY doesn't necessarily mean broken.
+            check(report, `${label} provider key`, true, process.env["ANTHROPIC_API_KEY"] ? "ANTHROPIC_API_KEY is set" : "ANTHROPIC_API_KEY not set — fine if authenticated via `claude login` instead");
+        }
+        else {
+            try {
+                const [provider] = resolveModel(agent.model);
+                const envKeys = PROVIDER_ENV_KEYS[provider];
+                if (!envKeys) {
+                    check(report, `${label} provider key`, true, `provider "${provider}" not in doctor's known list — skipped, not a failure`);
+                }
+                else {
+                    const set = envKeys.find((k) => process.env[k]);
+                    check(report, `${label} provider key`, Boolean(set), set ? `${set} is set` : `none of ${envKeys.join(", ")} is set`);
+                }
+            }
+            catch (error) {
+                check(report, `${label} model`, false, error.message);
+            }
+        }
+        const isKnownToolName = agent.coding_agent === "claude_code" ? agentCc.isKnownToolName : isKnownFlueToolName;
+        for (const toolName of agent.tools ?? []) {
+            if (!isKnownToolName(toolName))
+                check(report, `${label} tool "${toolName}"`, false, "not a known tool name");
+        }
+    }
+    for (const spec of cfg.quality.checks) {
+        check(report, `quality check "${spec.name}"`, binaryOnPath(spec.argv[0]), `${spec.argv[0]} ${binaryOnPath(spec.argv[0]) ? "found on PATH" : "NOT found on PATH"}`);
+    }
+    for (const [suiteName, names] of Object.entries(cfg.quality.suites)) {
+        const missing = names.filter((n) => !cfg.quality.checks.some((c) => c.name === n));
+        check(report, `quality suite "${suiteName}"`, missing.length === 0, missing.length === 0 ? names.join(", ") : `names unknown check(s): ${missing.join(", ")}`);
+    }
+    // A protected_files pattern matching nothing anywhere in the trace is
+    // usually a stale convention (e.g. an old adws/... pattern) that silently
+    // stopped protecting anything.
+    if (isRepo) {
+        const tree = permissions.snapshot({ repo_root: anchor.repo_root, cfg });
+        for (const pattern of cfg.defaults.protected_files) {
+            const matchesSomething = Object.keys(tree).some((p) => p.startsWith(pattern.replace(/\/+$/, "") + "/") || p === pattern);
+            check(report, `protected_files pattern ${JSON.stringify(pattern)}`, true, matchesSomething ? "matches tracked/dirty paths" : "matches nothing in the current diff (fine if the tree is clean; suspicious if this is a stale convention)");
+        }
+    }
+    for (const envFile of [".env"]) {
+        const p = path.join(anchor.repo_root, envFile);
+        check(report, `${envFile}`, true, existsSync(p) ? `present (${statSync(p).size} bytes)` : "absent — fine if no provider needs a key from it");
+    }
+    if (cfg.watch.repo.trim()) {
+        check(report, "watch.provider", cfg.watch.provider === "github", cfg.watch.provider);
+        check(report, "GITHUB_TOKEN", Boolean(process.env["GITHUB_TOKEN"]), process.env["GITHUB_TOKEN"]
+            ? "set"
+            : 'not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo); see README.md\'s "GITHUB_TOKEN scope" 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`);
+    }
+    return finish(report, flags["json"]);
+}
+function finish(report, json) {
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        for (const c of report.checks) {
+            console.log(`${c.ok ? "✓" : "✗"} ${c.name}: ${c.detail}`);
+        }
+        console.log(report.ok ? "\nspf doctor: clean" : "\nspf doctor: problems found above");
+    }
+    return report.ok ? 0 : 1;
+}

package/dist/cli/commands/eject.d.ts

@@ -0,0 +1 @@
+export declare function ejectCommand(argv: string[]): number;

package/dist/cli/commands/eject.js

@@ -0,0 +1,55 @@
+/**
+ * `spf eject` — copy the installed CLI's own compiled engine (`dist/core/`,
+ * `dist/chains/`) out to disk for reference or hand-editing. There is no
+ * wiring back in: `.spf/` config can override the roster and prompts, but an
+ * engine-level change (a new gate, a new envelope type, a modified phase
+ * primitive) has no config surface, by design — see
+ * `authoring_chains.md`. This exists so `spf migrate`'s report has something
+ * concrete to point at for repos with hand-edited `adw_modules/*.ts` from
+ * the old stamped design, and for anyone who wants to read the engine
+ * without cloning the package's source repo.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from "node:fs";
+import path from "node:path";
+import * as paths from "../../core/paths.js";
+import { ensureGitignore } from "../gitignore.js";
+import { parseCli } from "../../core/utils.js";
+function copyDirRecursive(from, to) {
+    mkdirSync(to, { recursive: true });
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+        const srcPath = path.join(from, entry.name);
+        const destPath = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyDirRecursive(srcPath, destPath);
+        else if (entry.isFile())
+            copyFileSync(srcPath, destPath);
+    }
+}
+export function ejectCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd", "target"], ["force"]);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const destRoot = options["target"] ? path.resolve(options["target"]) : path.join(anchor.repo_root, ".spf", "engine");
+    if (existsSync(destRoot) && !flags["force"]) {
+        console.error(`${destRoot} already exists — pass --force to overwrite, or --target to eject somewhere else.`);
+        return 1;
+    }
+    const pkg = JSON.parse(readFileSync(path.join(paths.PACKAGE_ROOT, "package.json"), "utf-8"));
+    const distDir = path.join(paths.PACKAGE_ROOT, "dist");
+    mkdirSync(destRoot, { recursive: true });
+    copyDirRecursive(path.join(distDir, "core"), path.join(destRoot, "core"));
+    copyDirRecursive(path.join(distDir, "chains"), path.join(destRoot, "chains"));
+    writeFileSync(path.join(destRoot, "NOTES.md"), `# Ejected engine — @gr8ful/spf v${pkg.version}\n\n` +
+        `A reference copy of this install's compiled engine (\`core/\`, \`chains/\`), for reading or for\n` +
+        `reapplying hand-edited logic from an old stamped \`adws/adw_modules/\` tree.\n\n` +
+        `**This is JS, not TypeScript** — the published package ships compiled output only. It is **not\n` +
+        `wired into any \`spf\` command**: editing these files changes nothing about how \`spf\` itself runs.\n` +
+        `Engine-level changes (a new gate, envelope type, or phase primitive) have no config surface by\n` +
+        `design — see \`authoring_chains.md\` in the installed skill for where each kind of change belongs\n` +
+        `and why it isn't a \`.spf/\` override.\n`);
+    console.log(`ejected v${pkg.version}'s core/ and chains/ into ${destRoot}`);
+    // Only for the default in-repo location — an explicit --target elsewhere
+    // is the caller's own directory to manage, not necessarily this repo's.
+    if (!options["target"])
+        ensureGitignore(anchor.repo_root, [".spf/engine/"]);
+    return 0;
+}

package/dist/cli/commands/events.d.ts

@@ -0,0 +1 @@
+export declare function eventsCommand(argv: string[]): Promise<number>;

package/dist/cli/commands/events.js

@@ -0,0 +1,49 @@
+import { parseCli } from "../../core/utils.js";
+import { openTrace } from "./trace.js";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function printEvent(e) {
+    let payload = "";
+    try {
+        payload = JSON.stringify(JSON.parse(e.payload_json ?? "{}"));
+    }
+    catch {
+        payload = e.payload_json ?? "";
+    }
+    console.log(`${e.rowid}  ${(e.type ?? "").padEnd(12)} ${(e.name ?? "").padEnd(24)} ${payload}`);
+}
+export async function eventsCommand(argv) {
+    const { positionals, options, flags } = parseCli(argv, ["cwd", "config", "after", "limit"], ["json", "follow"]);
+    if (positionals.length < 1) {
+        console.error("usage: spf events <adw_id> [--after <rowid>] [--follow] [--cwd <dir>] [--config <path>] [--json]");
+        return 1;
+    }
+    const adwId = positionals[0];
+    const { db } = openTrace(options);
+    let after = options["after"] ? Number.parseInt(options["after"], 10) : 0;
+    const page = db.events(adwId, after, options["limit"] ? Number.parseInt(options["limit"], 10) : 500);
+    if (flags["json"] && !flags["follow"]) {
+        console.log(JSON.stringify(page.events, null, 2));
+        return 0;
+    }
+    for (const e of page.events)
+        printEvent(e);
+    after = page.cursor;
+    if (!flags["follow"])
+        return 0;
+    console.error(`-- following ${adwId}; ^C to stop --`);
+    for (;;) {
+        await sleep(500);
+        const session = db.session(adwId);
+        const next = db.events(adwId, after, 500);
+        for (const e of next.events)
+            printEvent(e);
+        if (next.events.length > 0)
+            after = next.cursor;
+        if (session && session.status !== "running" && next.events.length === 0) {
+            console.error(`-- ${adwId} is ${session.status}, stopping --`);
+            return session.status === "success" ? 0 : 1;
+        }
+    }
+}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function initCommand(argv: string[]): number;

package/dist/cli/commands/init.js

@@ -0,0 +1,62 @@
+/** `spf init` — seed a `.spf/` override directory. Everything else is inherited from the packaged defaults. */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import * as paths from "../../core/paths.js";
+import { ensureGitignore } from "../gitignore.js";
+import { parseCli } from "../../core/utils.js";
+const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packaged built-in defaults.
+# List only what you want to CHANGE; everything else (the roster, prompts,
+# models) is inherited. Run \`spf doctor\` any time to see what's actually in
+# effect for this repo, and where each value came from.
+
+# Uncomment to enable a quality-gated chain (build-test, plan-build-test,
+# plan-build-test-quality, quality, simple-sdlc) — an unconfigured suite
+# fails loudly before anything runs, on purpose, rather than reporting a
+# placeholder green.
+# quality:
+#   checks:
+#     - {name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 600}
+#   suites:
+#     test: [test]
+#     all: [test]
+
+# agents:
+#   - name: builder
+#     model: anthropic/claude-sonnet-4-6
+#     coding_agent: claude_code   # run this agent on Claude Code instead of Flue
+#     model: sonnet               # claude_code's own alias, NOT provider/model-id
+
+# Uncomment to enable \`spf watch\` — polls GitHub issues labeled
+# <label_prefix>:ready and runs \`chain\` against each in its own worktree.
+# Needs a GITHUB_TOKEN env var: a classic PAT with repo scope (or public_repo
+# for a public-only repo) — never the project scope, which is unrelated and
+# unused here. See README.md's "GITHUB_TOKEN scope" section. \`spf doctor\`
+# checks it's set.
+# watch:
+#   repo: owner/name
+#   label_prefix: spf
+#   chain: plan-build-test
+#   base_branch: main
+`;
+// .spf/spf.config.yaml and .spf/prompt_engineering/ stay tracked — they're
+// shared project config, same as package.json. Only runtime/generated
+// content is ignored: session traces (data/), a hand-editable engine copy
+// (engine/, from `spf eject`), and secrets (.env).
+const GITIGNORE_ENTRIES = [".spf/data/", ".spf/engine/", ".env"];
+export function initCommand(argv) {
+    const { options, flags } = parseCli(argv, ["cwd"], ["force"]);
+    const anchor = paths.resolveAnchor(options["cwd"]);
+    const sfDir = path.join(anchor.repo_root, ".spf");
+    mkdirSync(sfDir, { recursive: true });
+    const configPath = path.join(sfDir, "spf.config.yaml");
+    if (existsSync(configPath) && !flags["force"]) {
+        console.log(`${configPath} already exists — leaving it alone (--force to overwrite)`);
+    }
+    else {
+        writeFileSync(configPath, STARTER_CONFIG);
+        console.log(`wrote ${configPath}`);
+    }
+    ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
+    console.log(`\nnext: spf doctor   (confirm everything resolves), then spf scout "describe this repo"`);
+    return 0;
+}

package/dist/cli/commands/install-skill.d.ts

@@ -0,0 +1 @@
+export declare function installSkillCommand(argv: string[]): number;