@phuthuycoding/kanban-flow 0.3.0

package/dist/harness/run.js

@@ -0,0 +1,245 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { findFeature, writeFeatureMeta } from "../workflow/features.js";
+import { buildWorkerPrompt, currentFailReport, runMarker } from "./prompt.js";
+import { captureSession, isResumeFailure, parseUsage, provisionSession } from "./session.js";
+export const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+const TAIL_BYTES = 64 * 1024;
+const KILL_GRACE_MS = 5_000;
+export function isPidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ESRCH")
+            return false;
+        if (err instanceof Error && "code" in err && err.code === "EPERM")
+            return true;
+        throw err;
+    }
+}
+function loadFeature(root, name) {
+    const feature = findFeature(root, name);
+    if (!feature || !feature.meta)
+        throw new Error(`Work item '${name}' disappeared or lost its metadata while a run was in progress.`);
+    return feature;
+}
+/** Re-read metadata right before writing so a concurrent `kf stage` or supervisor update is not clobbered. */
+async function upsertRun(root, name, record) {
+    const feature = loadFeature(root, name);
+    const runs = [...(feature.meta.runs ?? [])];
+    const index = runs.findIndex((r) => r.id === record.id);
+    if (index === -1)
+        runs.push(record);
+    else
+        runs[index] = record;
+    await writeFeatureMeta(feature.dir, { ...feature.meta, runs });
+    return feature;
+}
+/** Sessions are keyed by role, not runner: two roles on the same CLI must not share context. */
+async function saveSession(root, name, role, session) {
+    const feature = loadFeature(root, name);
+    const sessions = { ...feature.meta.sessions };
+    if (session === null)
+        delete sessions[role];
+    else
+        sessions[role] = session;
+    await writeFeatureMeta(feature.dir, { ...feature.meta, sessions: Object.keys(sessions).length > 0 ? sessions : undefined });
+}
+export function runningRun(feature) {
+    return (feature.meta?.runs ?? []).find((r) => r.status === "running" && (isPidAlive(r.pid) || isPidAlive(r.supervisorPid))) ?? null;
+}
+export function planPath(feature, id) {
+    return join(feature.dir, "runs", `${id}.json`);
+}
+export function createRunPlan(root, feature, assignment, opts) {
+    const id = randomUUID().slice(0, 8);
+    const failReport = assignment.stage === "implementation" ? currentFailReport(feature) : null;
+    const prompt = buildWorkerPrompt({ runId: id, feature, root, assignment, failReport, previous: opts.previous });
+    return {
+        id, root, feature: feature.name, role: assignment.role, runnerName: assignment.runnerName,
+        stage: assignment.stage, runner: assignment.runner, prompt, output: assignment.output,
+        fresh: opts.fresh, timeoutMs: opts.timeoutMs,
+    };
+}
+export function writeRunPlan(feature, plan) {
+    mkdirSync(join(feature.dir, "runs"), { recursive: true });
+    const path = planPath(feature, plan.id);
+    writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+    return path;
+}
+export function readRunPlan(feature, id) {
+    const path = planPath(feature, id);
+    if (!existsSync(path))
+        throw new Error(`Run plan not found: ${path}`);
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function readTail(path) {
+    if (!existsSync(path))
+        return "";
+    const size = statSync(path).size;
+    const length = Math.min(size, TAIL_BYTES);
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(path, "r");
+    try {
+        readSync(fd, buffer, 0, length, size - length);
+    }
+    finally {
+        closeSync(fd);
+    }
+    return buffer.toString("utf8");
+}
+/** Every string value inside JSON found on the output (whole output or one JSONL line). */
+function jsonStrings(output) {
+    const texts = [];
+    const visit = (value) => {
+        if (typeof value === "string")
+            texts.push(value);
+        else if (Array.isArray(value))
+            value.forEach(visit);
+        else if (value && typeof value === "object")
+            Object.values(value).forEach(visit);
+    };
+    for (const text of [output.trim(), ...output.split("\n").map((line) => line.trim())]) {
+        if (!text.startsWith("{"))
+            continue;
+        try {
+            visit(JSON.parse(text));
+        }
+        catch (err) {
+            if (!(err instanceof SyntaxError))
+                throw err;
+        }
+    }
+    return texts;
+}
+/**
+ * Last STATUS/Summary lines the worker printed. CLIs in JSON mode (claude
+ * --output-format json, codex exec --json) wrap the reply in a JSON string, so
+ * the lines are also searched inside every string value of any JSON on stdout.
+ */
+export function extractStatus(output) {
+    let statusLine = null;
+    let summary;
+    for (const source of [output, ...jsonStrings(output)]) {
+        const statuses = [...source.matchAll(/^STATUS:\s*(.+?)\s*$/gm)];
+        const summaries = [...source.matchAll(/^Summary:\s*(.+?)\s*$/gm)];
+        if (statuses.length > 0)
+            statusLine = statuses[statuses.length - 1][1];
+        if (summaries.length > 0)
+            summary = summaries[summaries.length - 1][1];
+    }
+    return { statusLine, summary };
+}
+function killGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ESRCH")
+            return;
+        throw err;
+    }
+}
+/** Spawn the worker in its own process group with stdout/stderr appended to the log; kill the group on timeout. */
+function spawnWorker(argv, opts) {
+    return new Promise((resolve, reject) => {
+        const fd = openSync(opts.logPath, "a");
+        const child = spawn(argv[0], argv.slice(1), { cwd: opts.cwd, env: opts.env, detached: true, stdio: ["ignore", fd, fd] });
+        let timedOut = false;
+        let timer;
+        let killer;
+        const finish = (result) => {
+            if (timer)
+                clearTimeout(timer);
+            if (killer)
+                clearTimeout(killer);
+            closeSync(fd);
+            resolve(result);
+        };
+        child.once("error", (err) => finish({ pid: child.pid, exitCode: null, signal: null, timedOut, spawnError: err }));
+        child.once("spawn", () => {
+            // A worker nobody recorded cannot be tracked or killed later: stop it before surfacing the error.
+            opts.onSpawn(child.pid).catch((err) => {
+                killGroup(child.pid, "SIGKILL");
+                reject(err);
+            });
+            if (opts.timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    killGroup(child.pid, "SIGTERM");
+                    killer = setTimeout(() => killGroup(child.pid, "SIGKILL"), KILL_GRACE_MS);
+                }, opts.timeoutMs);
+            }
+        });
+        child.once("exit", (code, signal) => finish({ pid: child.pid, exitCode: code, signal, timedOut }));
+    });
+}
+/**
+ * Execute one planned run to completion and record it. A resume that the runner
+ * reports as a dead session is reset exactly once: the stored session is dropped
+ * and a fresh start run follows under a new id.
+ */
+export async function executeRun(plan, env = process.env, allowReset = true) {
+    const feature = loadFeature(plan.root, plan.feature);
+    const stored = feature.meta.sessions?.[plan.role];
+    const provisioned = provisionSession(plan.runner, stored, plan.prompt, plan.fresh);
+    const logRel = join("runs", `${plan.id}.log`);
+    mkdirSync(join(feature.dir, "runs"), { recursive: true });
+    const supervisorPid = feature.meta.runs?.find((r) => r.id === plan.id)?.supervisorPid;
+    let record = {
+        id: plan.id, role: plan.role, runner: plan.runnerName, stage: plan.stage, mode: provisioned.mode, session: provisioned.session,
+        at: new Date().toISOString(), log: logRel, status: "running", supervisorPid, chain: plan.chain,
+    };
+    await upsertRun(plan.root, plan.feature, record);
+    const result = await spawnWorker(provisioned.argv, {
+        cwd: plan.root, env, logPath: join(feature.dir, logRel), timeoutMs: plan.timeoutMs,
+        onSpawn: async (pid) => {
+            record = { ...record, pid };
+            await upsertRun(plan.root, plan.feature, record);
+        },
+    });
+    const endedAt = new Date().toISOString();
+    if (result.spawnError) {
+        record = { ...record, status: "failed", endedAt, error: `${provisioned.argv[0]}: ${result.spawnError.message}` };
+        await upsertRun(plan.root, plan.feature, record);
+        return { record, ok: false };
+    }
+    const output = readTail(join(loadFeature(plan.root, plan.feature).dir, logRel));
+    const { statusLine, summary } = extractStatus(output);
+    const exitCode = result.exitCode ?? (result.signal ? 128 : 1);
+    const usage = plan.runner.usage === "json" ? parseUsage(output) : null;
+    record = { ...record, exitCode, endedAt, statusLine, summary, ...(usage ? { usage } : {}) };
+    if (result.timedOut) {
+        record = { ...record, status: "timeout", error: `Worker exceeded ${plan.timeoutMs / 60_000} min and was killed.` };
+        await upsertRun(plan.root, plan.feature, record);
+        return { record, ok: false };
+    }
+    if (provisioned.mode === "resume" && isResumeFailure(plan.runner, exitCode, output)) {
+        record = { ...record, status: "reset", error: "Resume failed: session no longer usable; stored session dropped." };
+        await upsertRun(plan.root, plan.feature, record);
+        await saveSession(plan.root, plan.feature, plan.role, null);
+        if (!allowReset)
+            return { record, ok: false };
+        const retry = await executeRun({ ...plan, id: randomUUID().slice(0, 8), fresh: true }, env, false);
+        return { ...retry, note: `Session for role ${plan.role} was reset (run ${plan.id}); re-ran as ${retry.record.id}.` };
+    }
+    if (provisioned.mode === "start") {
+        const captured = captureSession(plan.runner, provisioned.session, { stdout: output, marker: runMarker(plan.id), cwd: plan.root, env });
+        if (captured)
+            await saveSession(plan.root, plan.feature, plan.role, captured);
+        else if (plan.runner.session !== undefined)
+            record = { ...record, warning: "Session id not captured from worker output; the next run will start fresh." };
+        if (captured)
+            record = { ...record, session: captured };
+    }
+    const ok = exitCode === 0 && statusLine !== null && statusLine.startsWith("DONE");
+    record = { ...record, status: exitCode === 0 ? "done" : "failed" };
+    await upsertRun(plan.root, plan.feature, record);
+    return { record, ok };
+}

package/dist/harness/session.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+const DEFAULT_RESUME_FAILURE = /session|not found|no such|unknown|does not exist/i;
+function fill(template, prompt, session) {
+    return template.map((arg) => arg.replaceAll("{prompt}", prompt).replaceAll("{session}", session ?? ""));
+}
+/** Pick start vs resume and build argv. Sessions are never guessed: only a stored id is resumed. */
+export function provisionSession(runner, stored, prompt, fresh) {
+    if (!fresh && stored && runner.resume) {
+        return { mode: "resume", session: stored, argv: fill(runner.resume, prompt, stored) };
+    }
+    const session = runner.session === "provided" ? randomUUID() : undefined;
+    return { mode: "start", session, argv: fill(runner.start, prompt, session) };
+}
+/** Learn the session id produced by a `start` run; null when the runner gives no way to know it. */
+export function captureSession(runner, provided, input) {
+    const capture = runner.session;
+    if (capture === undefined)
+        return null;
+    if (capture === "provided")
+        return provided ?? null;
+    if ("stdout" in capture) {
+        const match = new RegExp(capture.stdout).exec(input.stdout);
+        return match?.[1] ?? null;
+    }
+    const [cmd, ...args] = capture.command;
+    const res = spawnSync(cmd, args, { cwd: input.cwd, env: input.env, encoding: "utf8", timeout: 30_000 });
+    if (res.error)
+        throw new Error(`Session lookup command failed (${capture.command.join(" ")}): ${res.error.message}`, { cause: res.error });
+    if (res.status !== 0)
+        throw new Error(`Session lookup command exited ${res.status} (${capture.command.join(" ")}): ${(res.stderr ?? "").trim()}`);
+    let list;
+    try {
+        list = JSON.parse(res.stdout);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new Error(`Session lookup command did not return JSON (${capture.command.join(" ")})`, { cause: err });
+        throw err;
+    }
+    if (!Array.isArray(list))
+        return null;
+    const hit = list.find((item) => item && typeof item === "object"
+        && String(item[capture.matchField] ?? "").includes(input.marker));
+    const id = hit ? hit[capture.idField] : undefined;
+    return typeof id === "string" ? id : null;
+}
+export function isResumeFailure(runner, exitCode, output) {
+    if (exitCode === 0)
+        return false;
+    const re = runner.resumeFailure ? new RegExp(runner.resumeFailure, "i") : DEFAULT_RESUME_FAILURE;
+    return re.test(output);
+}
+/** Usage from JSON on stdout: the last object (whole output or one JSONL line) carrying usage.input_tokens/output_tokens. */
+export function parseUsage(stdout) {
+    const candidates = [stdout.trim(), ...stdout.split("\n").map((l) => l.trim()).reverse()];
+    for (const text of candidates) {
+        if (!text.startsWith("{"))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(text);
+        }
+        catch (err) {
+            if (err instanceof SyntaxError)
+                continue;
+            throw err;
+        }
+        if (!obj || typeof obj !== "object")
+            continue;
+        const usage = obj.usage;
+        if (!usage || typeof usage.input_tokens !== "number" || typeof usage.output_tokens !== "number")
+            continue;
+        const cost = obj.total_cost_usd;
+        return { input: usage.input_tokens, output: usage.output_tokens, ...(typeof cost === "number" ? { costUsd: cost } : {}) };
+    }
+    return null;
+}

package/dist/harness/supervise.js

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { findFeature, writeFeatureMeta } from "../workflow/features.js";
+import { readProjectConfig } from "../project/config.js";
+import { PKG_ROOT } from "../shared/paths.js";
+import { executeChain, newChainId } from "./chain.js";
+import { resolveChain } from "./prompt.js";
+function chainPlanPath(dir, id) {
+    return join(dir, "runs", `chain-${id}.json`);
+}
+/**
+ * Detach a chain: the supervisor is another `kf` process, so it survives the
+ * caller's exit and can update metadata when the workers finish, on any OS.
+ */
+export async function startDetached(root, featureName, chain, opts) {
+    const feature = findFeature(root, featureName);
+    if (!feature?.meta)
+        throw new Error(`Work item '${featureName}' has no metadata.`);
+    const id = newChainId();
+    const plan = {
+        id, root, feature: featureName, stage: chain[0].stage,
+        roles: chain.map((a) => a.role), fresh: opts.fresh, timeoutMs: opts.timeoutMs,
+    };
+    mkdirSync(join(feature.dir, "runs"), { recursive: true });
+    writeFileSync(chainPlanPath(feature.dir, id), `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+    const entry = join(PKG_ROOT, "dist", "index.js");
+    const child = spawn(process.execPath, [entry, "run", featureName, "--supervise", id], { cwd: root, detached: true, stdio: "ignore" });
+    const supervisorPid = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("spawn", () => resolve(child.pid));
+    });
+    child.unref();
+    const record = {
+        id, role: chain[0].role, runner: chain[0].runnerName, stage: chain[0].stage, mode: "start",
+        at: new Date().toISOString(), log: join("runs", `${id}.log`), status: "running", supervisorPid,
+        chain: { id, index: 1, total: chain.length },
+    };
+    await writeFeatureMeta(feature.dir, { ...feature.meta, runs: [...(feature.meta.runs ?? []), record] });
+    return record;
+}
+/** Entry point of the detached process: rebuild the chain from its plan and run it. */
+export async function superviseRun(root, featureName, chainId) {
+    const feature = findFeature(root, featureName);
+    if (!feature) {
+        const orphanDir = join(root, ".works", "harness");
+        mkdirSync(orphanDir, { recursive: true });
+        const orphan = join(orphanDir, `orphan-${chainId}.json`);
+        writeFileSync(orphan, `${JSON.stringify({ chainId, feature: featureName, at: new Date().toISOString(), reason: "work item folder not found" }, null, 2)}\n`);
+        throw new Error(`Work item '${featureName}' not found; wrote ${orphan}`);
+    }
+    const path = chainPlanPath(feature.dir, chainId);
+    if (!existsSync(path))
+        throw new Error(`Chain plan not found: ${path}`);
+    const plan = JSON.parse(readFileSync(path, "utf8"));
+    const harness = readProjectConfig(root).harness;
+    const chain = [];
+    for (const role of plan.roles) {
+        const resolved = resolveChain(harness, feature, root, { stage: plan.stage, role });
+        if (!resolved.ok)
+            throw new Error(`Cannot resume chain ${chainId}: ${resolved.reason}`);
+        chain.push(...resolved.chain);
+    }
+    return executeChain(root, featureName, chain, { fresh: plan.fresh, timeoutMs: plan.timeoutMs, firstRunId: chainId });
+}

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { parseArgsCli, allCommands, commandHelp } from "./cli/args.js";
+import { cmdInit } from "./cli/commands/init.js";
+import { cmdNew } from "./cli/commands/new.js";
+import { cmdList, cmdShow, cmdView, cmdStatus, cmdValidate } from "./cli/commands/inspect.js";
+import { cmdInstruct, cmdTemplates } from "./cli/commands/artifacts.js";
+import { cmdRules } from "./cli/commands/rules.js";
+import { cmdAutoconfig } from "./cli/commands/autoconfig.js";
+import { cmdDoctor } from "./cli/commands/doctor.js";
+import { cmdRun, cmdRuns } from "./cli/commands/run.js";
+import { cmdHarness } from "./cli/commands/harness.js";
+import { cmdContexts } from "./cli/commands/contexts.js";
+import { cmdStage } from "./cli/commands/stage.js";
+import { cmdArchive } from "./cli/commands/archive.js";
+import { cmdCancel } from "./cli/commands/cancel.js";
+import { cmdApprove } from "./cli/commands/approve.js";
+import { cmdInstall, cmdUninstall } from "./integrations/install.js";
+import { cmdDashboard } from "./dashboard/dashboard.js";
+import { parseAgentIds } from "./integrations/agents.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PKG_ROOT } from "./shared/paths.js";
+const PKG_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version ?? "0.0.0";
+function portFrom(parsed) {
+    if (parsed.options.port === undefined)
+        return 8787;
+    const raw = String(parsed.options.port);
+    const n = Number(raw);
+    if (!/^\d+$/.test(raw) || !Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new Error(`Invalid port '${raw}': expected an integer from 1 to 65535.`);
+    }
+    return n;
+}
+async function help(parts) {
+    const topic = parts[0];
+    if (topic)
+        return { code: 0, stdout: commandHelp(topic) };
+    const cmds = allCommands().map((c) => `  ${c.padEnd(12)} ${commandHelp(c).split("\n")[0]}`).join("\n");
+    return {
+        code: 0,
+        stdout: `kanban-flow CLI v${PKG_VERSION}\n\nUsage: kf <command> [args]\n\nCommands:\n${cmds}\n\nRun "kf help <command>" for details.`,
+    };
+}
+async function main(argv) {
+    const cwd = process.cwd();
+    if (argv[0] === "--version" || argv[0] === "-V") {
+        return { code: 0, stdout: PKG_VERSION };
+    }
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        return help([]);
+    }
+    const parsed = parseArgsCli(argv);
+    if (parsed.options.help)
+        return help([parsed.command]);
+    switch (parsed.command) {
+        case "help":
+            return help(parsed.positionals);
+        case "version":
+            return { code: 0, stdout: PKG_VERSION };
+        case "init":
+            return cmdInit(parsed, cwd);
+        case "new":
+            return cmdNew(parsed, cwd);
+        case "list":
+            return cmdList(parsed, cwd);
+        case "show":
+            return cmdShow(parsed, cwd);
+        case "view":
+            return cmdView(parsed, cwd);
+        case "dashboard":
+            return cmdDashboard(portFrom(parsed));
+        case "status":
+            return cmdStatus(parsed, cwd);
+        case "instruct":
+            return cmdInstruct(parsed, cwd);
+        case "templates":
+            return cmdTemplates(parsed, cwd);
+        case "validate":
+            return cmdValidate(parsed, cwd);
+        case "stage":
+            return cmdStage(parsed, cwd);
+        case "archive":
+            return cmdArchive(parsed, cwd);
+        case "cancel":
+            return cmdCancel(parsed, cwd);
+        case "approve":
+            return cmdApprove(parsed, cwd);
+        case "rules":
+            return cmdRules(parsed, cwd);
+        case "autoconfig":
+            return cmdAutoconfig(parsed, cwd);
+        case "doctor":
+            return cmdDoctor(parsed, cwd);
+        case "run":
+            return cmdRun(parsed, cwd);
+        case "runs":
+            return cmdRuns(parsed, cwd);
+        case "harness":
+            return cmdHarness(parsed, cwd);
+        case "contexts":
+            return cmdContexts(parsed, cwd);
+        case "install":
+            return cmdInstall(parseAgentIds(parsed.options.agent), { cwd });
+        case "uninstall":
+            return cmdUninstall(parseAgentIds(parsed.options.agent), {
+                cwd,
+                purge: Boolean(parsed.options.purge),
+                force: Boolean(parsed.options.force),
+            });
+        default:
+            return { code: 1, stdout: commandHelp(parsed.command), stderr: `unknown command: ${parsed.command}` };
+    }
+}
+main(process.argv.slice(2)).then((r) => {
+    if (r.stdout)
+        process.stdout.write(`${r.stdout}\n`);
+    if (r.stderr)
+        process.stderr.write(`${r.stderr}\n`);
+    process.exitCode = r.code;
+}).catch((err) => {
+    process.stderr.write(`kf: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/integrations/agents.js

@@ -0,0 +1,67 @@
+import { join } from "node:path";
+export const AGENTS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        projectRel: ".claude/skills",
+        alsoReads: ["cursor", "opencode"],
+    },
+    {
+        id: "codex",
+        label: "OpenAI Codex",
+        projectRel: ".agents/skills",
+        alsoReads: ["gemini", "cursor", "opencode"],
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        projectRel: ".gemini/skills",
+        alsoReads: ["codex", "cursor", "opencode"],
+    },
+    {
+        id: "kiro",
+        label: "Kiro",
+        projectRel: ".kiro/skills",
+        alsoReads: [],
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        projectRel: ".cursor/skills",
+        alsoReads: ["codex", "gemini", "opencode"],
+    },
+    {
+        id: "opencode",
+        label: "OpenCode",
+        projectRel: ".opencode/skills",
+        alsoReads: ["codex", "gemini", "cursor"],
+    },
+];
+/** Default agent used when the user does not pick one (non-interactive). */
+export const DEFAULT_AGENT = "claude";
+export function agentById(id) {
+    return AGENTS.find((a) => a.id === id) ?? null;
+}
+export function projectSkillsDir(agent, root) {
+    return join(root, agent.projectRel);
+}
+/** Normalize raw CLI option values into a de-duped list of known agent ids. */
+export function parseAgentIds(raw) {
+    const vals = Array.isArray(raw) ? raw.map(String) : raw != null ? [String(raw)] : [];
+    const seen = new Set();
+    for (const v of vals) {
+        const a = agentById(v);
+        if (!a)
+            throw new Error(`Unknown agent '${v}'. Supported agents: ${AGENTS.map((x) => x.id).join(", ")}.`);
+        seen.add(a.id);
+    }
+    return [...seen];
+}
+/** Skills dir for any agent name: the adapter's dir when known, else the open `.agents/skills` standard. */
+export function skillsDirFor(name, root) {
+    const adapter = agentById(name);
+    return join(root, adapter ? adapter.projectRel : ".agents/skills");
+}
+export function agentLabel(id) {
+    return agentById(id)?.label ?? id;
+}

package/dist/integrations/hooks.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { findWorksRoot } from "../workflow/features.js";
+import { PKG_ROOT, USER_KABAN_DIR } from "../shared/paths.js";
+const PKG_HOOKS_DIR = join(PKG_ROOT, "kanban-flow", "hooks");
+/**
+ * Resolve a per-phase hook script. Precedence: project → user → package.
+ * Hook file layout: {kanban-dir}/hooks/{phase}.sh
+ */
+export function resolveHook(cwd, phase) {
+    const candidates = [
+        ["project", join(findWorksRoot(cwd) ?? cwd, ".kf", "hooks", `${phase}.sh`)],
+        ["user", join(USER_KABAN_DIR, "hooks", `${phase}.sh`)],
+        ["package", join(PKG_HOOKS_DIR, `${phase}.sh`)],
+    ];
+    for (const [source, path] of candidates) {
+        if (existsSync(path))
+            return { name: phase, path, source };
+    }
+    return null;
+}
+/**
+ * Run the hook for the phase the feature is about to ENTER.
+ * Returns { ok:false } when the hook script exits non-zero — the caller must
+ * then refuse the transition (or honor --skip-hooks).
+ */
+export function runHook(cwd, env) {
+    const hook = resolveHook(cwd, env.to);
+    if (!hook) {
+        return { hook: null, ran: false, ok: true, code: 0, output: "" };
+    }
+    const isSh = hook.path.endsWith(".sh");
+    const isJs = hook.path.endsWith(".js") || hook.path.endsWith(".mjs") || hook.path.endsWith(".cjs");
+    const cmd = isSh ? "bash" : isJs ? "node" : hook.path;
+    const args = isSh || isJs ? [hook.path] : [];
+    const res = spawnSync(cmd, args, {
+        encoding: "utf8",
+        cwd: env.dir,
+        env: {
+            ...process.env,
+            KFW_FEATURE: env.feature,
+            KFW_CONTEXT: env.context ?? "",
+            KFW_FEATURE_DIR: env.dir,
+            KFW_WORK_ROOT: env.root,
+            KFW_FROM_STAGE: env.from ?? "",
+            KFW_TO_STAGE: env.to,
+            KFW_APPROVAL: env.approval,
+        },
+        timeout: 120_000,
+    });
+    return {
+        hook,
+        ran: true,
+        ok: res.status === 0,
+        code: res.status ?? 1,
+        output: `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? `\n${res.error.message}` : ""}${res.signal ? `\nTerminated by ${res.signal}` : ""}`.trim(),
+    };
+}