@phuthuycoding/kanban-flow 0.3.0

package/dist/integrations/install.js

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { findWorksRoot } from "../workflow/features.js";
+import { selectOption } from "../project/bootstrap.js";
+import { PKG_ROOT } from "../shared/paths.js";
+import { AGENTS, DEFAULT_AGENT, projectSkillsDir, } from "./agents.js";
+export const MANAGED_SKILLS = [
+    "kanban-flow",
+    "kanban-bug",
+    "kanban-brainstorm",
+    "kanban-plan",
+    "kanban-implement",
+    "kanban-test",
+    "kanban-review",
+    "kanban-archive",
+];
+const PKG_SKILLS_DIR = join(PKG_ROOT, "skills");
+/** Copy the managed skills from the package into the given skill dir. */
+export async function copySkillsTo(skillsDir) {
+    if (!existsSync(PKG_SKILLS_DIR)) {
+        return {
+            code: 1,
+            stdout: `Package skills dir not found: ${PKG_SKILLS_DIR}`,
+            stderr: "skills dir missing",
+        };
+    }
+    for (const name of MANAGED_SKILLS) {
+        const from = join(PKG_SKILLS_DIR, name);
+        if (!existsSync(join(from, "SKILL.md"))) {
+            return {
+                code: 1,
+                stdout: `Package skill missing: ${from}`,
+                stderr: "skill missing",
+            };
+        }
+    }
+    await mkdir(skillsDir, { recursive: true });
+    const copied = [];
+    for (const name of MANAGED_SKILLS) {
+        const from = join(PKG_SKILLS_DIR, name);
+        await cp(from, join(skillsDir, name), { recursive: true, force: true });
+        copied.push(name);
+    }
+    return { code: 0, stdout: `${copied.join(", ")} → ${skillsDir}/` };
+}
+/** Remove the managed skills from the given skill dir (leaves others intact). */
+export async function removeSkillsFrom(skillsDir) {
+    const removed = [];
+    for (const name of MANAGED_SKILLS) {
+        const target = join(skillsDir, name);
+        if (existsSync(target)) {
+            await rm(target, { recursive: true, force: true });
+            removed.push(name);
+        }
+    }
+    return { removed };
+}
+const PURGE_DIRS = [".works", ".kf", join("docs", "requirement"), join("docs", "use-cases"), join("docs", "testplan")];
+/**
+ * Install skills into each agent's project-level dir ({root}/.claude/skills, ...).
+ * Requires a kanban project (.works/) — run `kf init` first.
+ * Empty/missing agents fall back to the default agent (claude).
+ */
+export async function cmdInstall(agents = [DEFAULT_AGENT], opts = {}) {
+    const ids = agents.length > 0 ? agents : [DEFAULT_AGENT];
+    const base = opts.cwd ?? process.cwd();
+    const root = findWorksRoot(base);
+    if (!root) {
+        return {
+            code: 1,
+            stdout: `No kanban project found at ${base} (missing .works/) — run: kf init`,
+            stderr: "not a kanban project",
+        };
+    }
+    const lines = [];
+    let failed = false;
+    for (const id of ids) {
+        const a = AGENTS.find((x) => x.id === id);
+        if (!a)
+            continue;
+        const dir = projectSkillsDir(a, root);
+        const res = await copySkillsTo(dir);
+        failed ||= res.code !== 0;
+        lines.push(res.code === 0 ? `✓ ${a.label}: ${res.stdout}` : `⚠ ${a.label}: ${res.stdout}`);
+    }
+    if (lines.length === 0) {
+        return { code: 1, stdout: "No valid agents given for install.", stderr: "no agent" };
+    }
+    const alsoReads = ids.length === 1 ? AGENTS.find((x) => x.id === ids[0])?.alsoReads.join(", ") ?? "" : "";
+    const note = alsoReads ? `\nAlso picked up by: ${alsoReads}` : "";
+    return {
+        code: failed ? 1 : 0,
+        stdout: `Installed kanban skills:\n${lines.join("\n")}${note}\n\nRestart your AI assistant to detect them.`,
+        stderr: failed ? "skill installation failed" : undefined,
+    };
+}
+/**
+ * Remove skills from each agent's project-level skill dir.
+ * Resolves the .works root; falls back to cwd so cleanup still works when
+ * .works/ was deleted manually. Empty/missing agents fall back to the
+ * default agent (claude).
+ */
+export async function cmdUninstall(agents = [DEFAULT_AGENT], opts = {}) {
+    const ids = agents.length > 0 ? agents : [DEFAULT_AGENT];
+    const base = opts.cwd ?? process.cwd();
+    const root = findWorksRoot(base) ?? base;
+    const purgeTargets = opts.purge ? PURGE_DIRS.filter((d) => existsSync(join(root, d))) : [];
+    if (opts.purge && purgeTargets.length > 0 && !opts.force) {
+        if (!process.stdin.isTTY) {
+            return {
+                code: 1,
+                stdout: `Refusing to purge project data (${purgeTargets.join(", ")}) in ${root} without confirmation — re-run with --force.`,
+                stderr: "purge requires interactive confirmation or --force",
+            };
+        }
+        const pick = await selectOption(`Purge permanently deletes in ${root}:\n${purgeTargets.map((d) => `  ${d}/`).join("\n")}\nProceed? (↑/↓ + Enter)`, ["Cancel — keep everything", `Purge — delete ${purgeTargets.map((d) => `${d}/`).join(" ")} and project skills`]);
+        if (pick !== 1) {
+            return { code: 0, stdout: "Purge cancelled — nothing removed.\nRun without --purge to remove only skills." };
+        }
+    }
+    const lines = [];
+    for (const id of ids) {
+        const a = AGENTS.find((x) => x.id === id);
+        if (!a)
+            continue;
+        const dir = projectSkillsDir(a, root);
+        const { removed } = await removeSkillsFrom(dir);
+        lines.push(removed.length > 0 ? `✗ ${a.label}: removed ${removed.length} skills from ${dir}/` : `· ${a.label}: already clean in ${dir}/`);
+    }
+    if (lines.length === 0) {
+        return { code: 1, stdout: "No valid agents given for uninstall.", stderr: "no agent" };
+    }
+    let purged = "";
+    if (opts.purge) {
+        if (purgeTargets.length > 0) {
+            for (const d of purgeTargets) {
+                await rm(join(root, d), { recursive: true, force: true });
+            }
+            purged = `\nPurged project data: ${purgeTargets.map((d) => `${d}/`).join(" ")}`;
+        }
+        else {
+            purged = "\nNo project data (.works/, .kf/) found to purge.";
+        }
+        purged += leftoverIgnoreNote(root);
+    }
+    return {
+        code: 0,
+        stdout: `${lines.join("\n")}${purged}\n\nCLI still on PATH — unlink with: npm rm -g @phuthuycoding/kanban-flow`,
+    };
+}
+/**
+ * `kf init` can add `.works/` to .gitignore. Purge deliberately leaves it: .gitignore belongs to
+ * the user and may have been edited by hand. But a command that says it purged the project data
+ * has to say what it left behind, or the line only surfaces later, when some unrelated `.works/`
+ * is quietly ignored and nobody remembers why.
+ */
+function leftoverIgnoreNote(root) {
+    const gitignore = join(root, ".gitignore");
+    if (!existsSync(gitignore))
+        return "";
+    let body;
+    try {
+        body = readFileSync(gitignore, "utf8");
+    }
+    catch {
+        // An unreadable .gitignore is not a reason to fail an uninstall that already succeeded.
+        return "";
+    }
+    if (!body.split("\n").some((line) => line.trim() === ".works/"))
+        return "";
+    return `\nLeft alone: .gitignore still ignores .works/ — it is your file, so remove that line yourself if you want it gone.`;
+}
+/** Install the managed kanban skills into each agent's project-level dir (e.g. ./.claude/skills). */
+export async function installProjectSkills(root, agents = [DEFAULT_AGENT]) {
+    const ids = agents.length > 0 ? agents : [DEFAULT_AGENT];
+    const lines = [];
+    let failed = false;
+    for (const id of ids) {
+        const a = AGENTS.find((x) => x.id === id);
+        if (!a)
+            continue;
+        const dir = projectSkillsDir(a, root);
+        const res = await copySkillsTo(dir);
+        failed ||= res.code !== 0;
+        lines.push(res.code === 0 ? `✓ ${a.label}: ${res.stdout}` : `⚠ ${a.label}: ${res.stdout}`);
+    }
+    return {
+        code: failed ? 1 : 0,
+        stderr: failed ? "skill installation failed" : undefined,
+        stdout: `Installed kanban skills:\n${lines.join("\n")}\n\nRestart your AI assistant to detect them.`,
+    };
+}

package/dist/project/bootstrap.js

@@ -0,0 +1,358 @@
+import { existsSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { mkdir, copyFile, readdir } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
+import { stdin as input, stdout as output } from "node:process";
+import { execFileSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { nowTimestamp } from "../shared/time.js";
+import { detectStacks, writeProjectConfig, configPath } from "./config.js";
+import { effectiveDefaultContext, normalizeContext } from "./contexts.js";
+import { STAGES } from "../workflow/schema.js";
+import { assertPathName } from "../workflow/features.js";
+import { seedHarness } from "../harness/config.js";
+import { AGENTS, DEFAULT_AGENT, parseAgentIds } from "../integrations/agents.js";
+import { readProjectConfig } from "./config.js";
+/** git user.name, else $USER, else "human". */
+export function detectReviewer(root = process.cwd()) {
+    try {
+        const name = execFileSync("git", ["-C", root, "config", "user.name"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (name)
+            return name;
+    }
+    catch (err) {
+        if (!(err instanceof Error && (("status" in err && err.status === 1) || ("code" in err && err.code === "ENOENT"))))
+            throw err;
+    }
+    return process.env.USER || process.env.USERNAME || "human";
+}
+/** True when .git exists and .works/ is not already ignored. */
+export function shouldSuggestIgnoreWorks(root) {
+    if (!existsSync(join(root, ".git")))
+        return false;
+    const gi = join(root, ".gitignore");
+    if (!existsSync(gi))
+        return true;
+    const content = readFileSync(gi, "utf8");
+    return !/^\s*\.works\/?\s*$/m.test(content) && !content.split("\n").some((l) => l.includes(".works"));
+}
+export function appendIgnoreWorks(root) {
+    const gi = join(root, ".gitignore");
+    const add = "\n# kanban-flow\n.works/\n";
+    if (!existsSync(gi))
+        writeFileSync(gi, add, "utf8");
+    else
+        writeFileSync(gi, readFileSync(gi, "utf8") + add, "utf8");
+}
+async function confirm(rl, q, def) {
+    const hint = def ? "Y/n" : "y/N";
+    const ans = (await rl.question(`${q} (${hint}) `)).trim().toLowerCase();
+    if (ans === "")
+        return def;
+    return ans === "y" || ans === "yes";
+}
+/** Drop case-insensitive repeats, keeping the first spelling: the config reader refuses them. */
+function dedupeContexts(names) {
+    const seen = new Set();
+    const out = [];
+    for (const name of names) {
+        const key = normalizeContext(name);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(name);
+    }
+    return out;
+}
+/**
+ * Does `.works/` hold any work item folder? Deliberately only reads directory entries: reading
+ * work item metadata would make `kf init` die on a half-broken project, which is the one moment
+ * someone reaches for it. An empty `.works/` is not an existing project.
+ */
+export function hasWorkItems(root) {
+    for (const stage of STAGES) {
+        let entries;
+        try {
+            entries = readdirSync(join(root, ".works", stage));
+        }
+        catch (err) {
+            // Missing means nothing to count. Anything else — unreadable, not a directory — means we
+            // cannot tell, and the safe answer is "existing": declaring a list would be the change
+            // that locks someone out, while declining to declare one changes nothing.
+            if (err.code === "ENOENT")
+                continue;
+            return true;
+        }
+        // A work item is a folder named `<feature>_<timestamp>`. A .gitkeep or a .DS_Store is not one,
+        // and counting it would silently suppress the list — the very failure this check exists for.
+        if (entries.some((name) => /_\d{8}_\d{4}$/.test(name)))
+            return true;
+    }
+    return false;
+}
+export function bootstrapDefaults(root, explicitContext) {
+    const cfg = readProjectConfig(root);
+    const defaultContext = explicitContext || effectiveDefaultContext(cfg);
+    // Declaring a list is a decision, and `--defaults` means nobody made one, so only an explicit
+    // --context declares. Even then, not on a project that already exists: declaring one name there
+    // would lock out every context its work items already use, which is what FR-007 forbids. An
+    // existing project declares by answering on a TTY, or by hand.
+    const isNewProject = !existsSync(configPath(root)) && !hasWorkItems(root);
+    const declared = cfg.contexts?.length ? cfg.contexts
+        : explicitContext && isNewProject ? [explicitContext]
+            : [];
+    return {
+        contexts: declared,
+        defaultContext,
+        defaultContextStated: Boolean(explicitContext) || cfg.contexts !== undefined || cfg.defaultContext !== undefined,
+        stacks: cfg.stacks?.length ? cfg.stacks : detectStacks(root),
+        reviewer: cfg.reviewer ?? detectReviewer(root),
+        ignoreWorks: shouldSuggestIgnoreWorks(root),
+        seedFeature: false,
+        agents: cfg.agents?.length ? parseAgentIds(cfg.agents) : [DEFAULT_AGENT],
+    };
+}
+/** Arrow-key radio select on a TTY; digit keys also work. Returns the chosen index. */
+export async function selectOption(question, options) {
+    return new Promise((resolveP, reject) => {
+        let idx = 0;
+        let drawn = 0;
+        const draw = () => {
+            if (drawn > 0)
+                output.write(`\x1b[${drawn}A\x1b[J`);
+            const text = `${question}\n${options.map((o, i) => ` ${i === idx ? "❯" : " "} ${o}`).join("\n")}`;
+            output.write(`${text}\n`);
+            drawn = text.split("\n").length;
+        };
+        const cleanup = () => {
+            input.setRawMode(false);
+            input.off("keypress", onKey);
+            input.pause();
+        };
+        const onKey = (_s, key) => {
+            if (key.name === "up")
+                idx = (idx - 1 + options.length) % options.length;
+            else if (key.name === "down")
+                idx = (idx + 1) % options.length;
+            else if (/^[1-9]$/.test(key.name) && Number(key.name) <= options.length)
+                idx = Number(key.name) - 1;
+            else if (key.name === "return") {
+                cleanup();
+                resolveP(idx);
+                return;
+            }
+            else if (key.name === "c" && key.ctrl) {
+                cleanup();
+                reject(new Error("Setup aborted (Ctrl+C). Re-run with --defaults to skip prompts."));
+                return;
+            }
+            else
+                return;
+            draw();
+        };
+        emitKeypressEvents(input);
+        input.setRawMode(true);
+        input.resume();
+        input.on("keypress", onKey);
+        draw();
+    });
+}
+/**
+ * Onboarding entry: let the user pick quick setup (defaults) or customize,
+ * then collect answers accordingly.
+ */
+export async function onboardAnswers(root, explicitContext) {
+    const d = bootstrapDefaults(root, explicitContext);
+    const mode = await selectOption("Setup mode (↑/↓ + Enter):", [
+        `Quick setup — defaults (context: ${d.defaultContext}, stacks: ${d.stacks.join(", ") || "unset"}, reviewer: ${d.reviewer}, agents: ${d.agents.join(", ")})`,
+        "Customize — answer each question",
+    ]);
+    if (mode === 0)
+        return d;
+    return promptAnswers(root, explicitContext);
+}
+/**
+ * Ask the bootstrap questions interactively. Every question has a sensible
+ * default — Enter accepts it. Returns the collected answers.
+ */
+export async function promptAnswers(root, explicitContext) {
+    const rl = createInterface({ input, output });
+    try {
+        return await askAll(rl, root, explicitContext);
+    }
+    catch (err) {
+        if (err instanceof Error && (err.name === "AbortError" || err.name === "ERR_ABORT")) {
+            throw new Error("Setup aborted (EOF/Ctrl+C). Re-run with --defaults to skip prompts.");
+        }
+        throw err;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Exported for tests: the interactive branch is otherwise unreachable without a TTY, and it owns
+ * the context-list dedupe and the empty-answer fallback, both of which must not regress silently.
+ */
+export async function askAll(rl, root, explicitContext) {
+    const d = bootstrapDefaults(root, explicitContext);
+    // One question, not two: the list declares the default by position, so there is no second
+    // field to keep in step with it.
+    //
+    // On a project that is already unrestricted, `d.contexts` is empty and the prompt says so:
+    // pressing Enter there must leave it unrestricted. Enter is not a decision, and declaring a
+    // list on someone's behalf would lock out every context their work items already use.
+    const hint = d.contexts.length > 0 ? d.contexts.join(",") : "leave empty to keep this project unrestricted";
+    const ctxRaw = (await rl.question(`Contexts, comma separated, first is the default [${hint}]: `)).trim();
+    const typed = ctxRaw.split(/[\s,]+/).map((c) => c.trim()).filter(Boolean);
+    const contexts = typed.length > 0 ? dedupeContexts(typed) : d.contexts;
+    const defaultContext = contexts[0] ?? d.defaultContext;
+    let stacks = d.stacks;
+    const parseStacks = (raw) => raw.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+    if (stacks.length > 0) {
+        const ok = await confirm(rl, `Detected stacks: ${stacks.join(", ")}. Use them?`, true);
+        if (!ok) {
+            const s = (await rl.question("Stacks (comma-separated, e.g. node,go — or skip): ")).trim();
+            stacks = parseStacks(s);
+        }
+    }
+    else {
+        const s = (await rl.question("Stacks (comma-separated, e.g. node,go — or skip): ")).trim();
+        stacks = parseStacks(s);
+    }
+    const rev = (await rl.question(`Default reviewer for kf approve [${d.reviewer}]: `)).trim();
+    const reviewer = rev || d.reviewer;
+    const agents = (await promptAgents(rl, d.agents)).agents;
+    let ignoreWorks = d.ignoreWorks;
+    if (d.ignoreWorks) {
+        ignoreWorks = await confirm(rl, "Add .works/ to .gitignore?", true);
+    }
+    const seedFeature = await confirm(rl, "Seed a demo feature to show the structure?", false);
+    // Typing a list is a decision; pressing Enter is not. Recording Enter as one would repoint
+    // every future context-less `kf new` at the invented fallback, on the one path where the
+    // prompt has just promised "leave empty to keep this project unrestricted".
+    return { contexts, defaultContext, defaultContextStated: typed.length > 0 || d.defaultContextStated, stacks, reviewer, ignoreWorks, seedFeature, agents };
+}
+/** Multi-select agent prompt (comma-separated ids; Enter = default agent). */
+async function promptAgents(rl, defaults) {
+    const list = AGENTS.map((a) => a.id).join(", ");
+    const ans = (await rl.question(`Install skills for which agents? (comma-separated, default: ${defaults.join(", ")}) [${list}]: `)).trim();
+    if (ans === "")
+        return { agents: defaults };
+    return { agents: parseAgentIds(ans.toLowerCase().split(/[\s,]+/)) };
+}
+/** Copy package templates/rules (+ empty hooks dir) into the new project override dirs. */
+export async function seedOverrides(root) {
+    const dirs = [
+        join(root, ".kf", "templates"),
+        join(root, ".kf", "hooks"),
+        join(root, ".kf", "review", "rules"),
+    ];
+    await Promise.all(dirs.map((d) => mkdir(d, { recursive: true })));
+    const { PKG_TEMPLATES_DIR, PKG_RULES_DIR } = await import("../shared/paths.js");
+    await copyDirInto(PKG_TEMPLATES_DIR, join(root, ".kf", "templates"));
+    await copyDirInto(PKG_RULES_DIR, join(root, ".kf", "review", "rules"));
+}
+async function copyDirInto(src, dest) {
+    if (!existsSync(src))
+        return;
+    const files = await readdir(src);
+    for (const f of files) {
+        const from = resolve(src, f);
+        const to = resolve(dest, f);
+        if (!existsSync(from) || existsSync(to))
+            continue;
+        await mkdir(dest, { recursive: true });
+        await copyFile(from, to);
+    }
+}
+/** Write .kf/config.json for this project. */
+export function saveConfig(root, a) {
+    const existing = readProjectConfig(root);
+    // Both halves of the rule live here, not at a caller: this is the one point every set of
+    // answers passes through, so no producer — present or future — can write a contexts list that
+    // readProjectConfig then refuses. Dedupe covers the repeat rule; assertPathName covers names.
+    const contexts = dedupeContexts(a.contexts);
+    for (const c of contexts)
+        assertPathName(c, "context");
+    // `contexts[0]` is the default once a list exists, so a second field would only drift. With no
+    // list, keep whatever the project already stated and invent nothing: a default the tool made up
+    // would make `kf new`'s guess-from-work-items arm unreachable.
+    // Four cases, and each one matters:
+    //   named by a person      → write it, or `--context X` would seed docs/X and then send every
+    //                            new item somewhere else
+    //   already in the config  → counts as named: `defaultContextStated` is true whenever the
+    //                            config already carried context information, so this is the same
+    //                            branch. A separate `existing.defaultContext ??` fallback here
+    //                            would be unreachable, since both read the same file.
+    //   nothing, no work items → write the fallback; on a fresh project there is nothing to
+    //                            override, and the field is how someone discovers it exists
+    //   nothing, but work items exist → write nothing, or the invented default would make
+    //                            `kf new`'s guess-from-work-items arm unreachable
+    const keepDefault = a.defaultContextStated ? a.defaultContext : hasWorkItems(root) ? undefined : a.defaultContext;
+    const legacyDefault = contexts.length === 0 && keepDefault ? { defaultContext: keepDefault } : {};
+    const cfg = {
+        schema: "kanban-flow",
+        ...(contexts.length > 0 ? { contexts } : {}),
+        ...legacyDefault,
+        stacks: a.stacks,
+        reviewer: a.reviewer,
+        agents: a.agents,
+        harness: existing.harness ?? seedHarness(a.agents),
+        created: existing.created ?? nowTimestamp(),
+    };
+    writeProjectConfig(root, cfg);
+}
+const AGENT_SCRIPTS = [["Install", "ci"], ["Build", "build"], ["Typecheck", "typecheck"], ["Lint", "lint"], ["Test", "test"]];
+function nodeCommandRows(root) {
+    const manifest = join(root, "package.json");
+    if (!existsSync(manifest))
+        return [];
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(manifest, "utf8"));
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new Error(`Invalid JSON in ${manifest}`, { cause: err });
+        throw err;
+    }
+    const scripts = pkg.scripts ?? {};
+    return AGENT_SCRIPTS
+        .filter(([, script]) => script === "ci" || script in scripts)
+        .map(([label, script]) => `| ${label} | \`${script === "ci" ? (existsSync(join(root, "package-lock.json")) ? "npm ci" : "npm install") : script === "test" ? "npm test" : `npm run ${script}`}\` |`);
+}
+/**
+ * Seed AGENTS.md at the project root so agents know the commands and the
+ * kanban-flow conventions. Never overwrites an existing AGENTS.md or CLAUDE.md.
+ */
+export function seedAgentsFile(root, stacks) {
+    if (existsSync(join(root, "AGENTS.md")) || existsSync(join(root, "CLAUDE.md")))
+        return "kept";
+    const rows = stacks.includes("node") ? nodeCommandRows(root) : [];
+    const commands = rows.length > 0
+        ? rows.join("\n")
+        : "| Build | `TODO: fill in` |\n| Test | `TODO: fill in` |\n| Lint | `TODO: fill in` |";
+    const content = `# AGENTS.md
+
+Conventions for AI coding agents working in this repository. Seeded by \`kf init\`; edit freely.
+
+## Commands
+
+| Task | Command |
+|---|---|
+${commands}
+
+Detect anything else by reading the repository, never by guessing.
+
+## Workflow (kanban-flow)
+
+- Start a feature with one command: \`kanban <context> <feature>\` (bug: \`kanban <context> <name> --type bug\`).
+- Only two human gates: confirm the requirement (Phase 1) and approve the plan + choose start-now vs backlog (Phase 2). Do not ask "continue?" between other phases.
+- Work item state lives in \`.works/\`; move items only with \`kf stage\` / \`kf archive\`, never by moving folders.
+- Never use \`--force\` or \`--skip-hooks\` without explicit user approval; every bypass is recorded in the work item's metadata.
+- Run \`kf autoconfig\` for the setup checklist and the review rules to apply as coding conventions.
+`;
+    writeFileSync(join(root, "AGENTS.md"), content, "utf8");
+    return "created";
+}

package/dist/project/config.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { assertPathName } from "../workflow/features.js";
+import { parseAgentIds } from "../integrations/agents.js";
+import { validateHarness } from "../harness/config.js";
+import { normalizeContext } from "./contexts.js";
+export const CONFIG_FILE = "config.json";
+/** Stack ids that have a shipped review rule pack (kanban-flow/review/stacks/{id}.md). */
+export const STACK_IDS = ["node", "go", "rust", "python", "php", "ruby", "java"];
+export function projectKabanDir(root) {
+    return join(root, ".kf");
+}
+export function configPath(root) {
+    return join(projectKabanDir(root), CONFIG_FILE);
+}
+/** Read the project config; missing config uses defaults, invalid config is an error. */
+export function readProjectConfig(root) {
+    const f = configPath(root);
+    if (!existsSync(f))
+        return {};
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(f, "utf8"));
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            throw new Error(`Invalid JSON in project config: ${f}`, { cause: err });
+        throw err;
+    }
+    if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)
+        || (cfg.defaultContext !== undefined && typeof cfg.defaultContext !== "string")
+        || (cfg.reviewer !== undefined && typeof cfg.reviewer !== "string")
+        || (cfg.created !== undefined && typeof cfg.created !== "string")
+        || (cfg.schema !== undefined && cfg.schema !== "kanban-flow")
+        || (cfg.stack !== undefined && cfg.stack !== null && typeof cfg.stack !== "string")
+        || (cfg.stacks !== undefined && (!Array.isArray(cfg.stacks) || !cfg.stacks.every((s) => typeof s === "string")))
+        || (cfg.agents !== undefined && (!Array.isArray(cfg.agents) || !cfg.agents.every((a) => typeof a === "string")))) {
+        throw new Error(`Invalid project config: ${f}`);
+    }
+    if (cfg.contexts !== undefined) {
+        if (!Array.isArray(cfg.contexts) || cfg.contexts.length === 0 || !cfg.contexts.every((c) => typeof c === "string")) {
+            throw new Error(`Invalid project config: ${f} — contexts must be a non-empty array of strings`);
+        }
+        for (const c of cfg.contexts)
+            assertPathName(c, "context");
+        const seen = new Set();
+        for (const c of cfg.contexts) {
+            const key = normalizeContext(c);
+            if (seen.has(key))
+                throw new Error(`Invalid project config: ${f} — contexts lists "${c}" twice (names are compared case-insensitively)`);
+            seen.add(key);
+        }
+    }
+    if (cfg.stacks === undefined && typeof cfg.stack === "string")
+        cfg.stacks = [cfg.stack];
+    if (cfg.defaultContext !== undefined)
+        assertPathName(cfg.defaultContext, "context");
+    if (cfg.agents)
+        parseAgentIds(cfg.agents);
+    if (cfg.harness !== undefined)
+        cfg.harness = validateHarness(cfg.harness, f);
+    return cfg;
+}
+export function writeProjectConfig(root, cfg) {
+    writeFileSync(configPath(root), `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+}
+const STACK_PROBES = [
+    ["package.json", "node"],
+    ["go.mod", "go"],
+    ["Cargo.toml", "rust"],
+    ["pyproject.toml", "python"],
+    ["requirements.txt", "python"],
+    ["composer.json", "php"],
+    ["Gemfile", "ruby"],
+    ["pom.xml", "java"],
+];
+/** Dirs never worth scanning for manifests (deps, VCS, build output). */
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "out", "target", "vendor",
+    "coverage", ".works", ".kf", "bin", "pkg", "__pycache__",
+]);
+/** Detect all tech stacks from manifest files at the root and subdirectories (monorepo-aware). */
+export function detectStacks(root, maxDepth = 2) {
+    const found = [];
+    const visit = (dir, depth) => {
+        for (const [file, stack] of STACK_PROBES) {
+            if (existsSync(join(dir, file)) && !found.includes(stack))
+                found.push(stack);
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !e.name.startsWith(".") && !SKIP_DIRS.has(e.name)) {
+                visit(join(dir, e.name), depth + 1);
+            }
+        }
+    };
+    visit(root, 0);
+    return found;
+}
+/** Detect the primary tech stack — first probe match at the project root only. */
+export function detectStack(cwd) {
+    return detectStacks(cwd, 0)[0] ?? null;
+}