@phuthuycoding/kanban-flow 0.3.0

package/dist/cli/commands/archive.js

@@ -0,0 +1,245 @@
+import { rename, rm } from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ARTIFACTS, METADATA_FILE } from "../../workflow/schema.js";
+import { findFeature, stageDir, assertPathName, writeFeatureMeta } from "../../workflow/features.js";
+import { validateFeature, checkDirectionGate, renderValidateText } from "../../workflow/validate.js";
+import { splitFrontmatter, applyFrontmatter } from "../../shared/frontmatter.js";
+import { writeFileAtomic } from "../../shared/paths.js";
+import { runHook, resolveHook } from "../../integrations/hooks.js";
+import { findRoot, recordBypasses, bypassNote } from "./helpers.js";
+function archivedDocument(raw) {
+    const { fm, body } = splitFrontmatter(raw);
+    if (Object.keys(fm).length === 0)
+        return raw;
+    fm.status = "archived";
+    return applyFrontmatter(fm, body);
+}
+/** Canonical doc paths a feature owns, whether or not they exist on disk. */
+export function canonicalDocPaths(root, feature) {
+    if (!feature.context || feature.meta?.kind === "bug")
+        return [];
+    const base = join(root, "docs");
+    const { context, name } = { context: feature.context, name: feature.name };
+    const useCaseDir = join(base, "use-cases", context, name);
+    const files = [
+        join(base, "requirement", context, `${name}.md`),
+        join(base, "testplan", context, `${name}.md`),
+        join(base, "testplan", context, `${name}-result.md`),
+    ];
+    if (existsSync(useCaseDir))
+        files.push(useCaseDir);
+    return files.filter((p) => existsSync(p));
+}
+function prepareCanonicalCopies(root, feature) {
+    if (!feature.context)
+        return [];
+    if (feature.meta?.kind === "bug")
+        return [];
+    assertPathName(feature.context, "context");
+    assertPathName(feature.name, "feature");
+    const context = feature.context;
+    const base = join(root, "docs");
+    const mappings = [
+        [ARTIFACTS["spec-requirement"].file, join(base, "requirement", context, `${feature.name}.md`), true],
+        [ARTIFACTS["use-case-specification"].file, join(base, "use-cases", context, feature.name, "README.md"), false],
+        [ARTIFACTS["use-case-diagram"].file, join(base, "use-cases", context, feature.name, "diagram.md"), false],
+        [ARTIFACTS["test-cases"].file, join(base, "testplan", context, `${feature.name}.md`), false],
+        [ARTIFACTS["testing-result"].file, join(base, "testplan", context, `${feature.name}-result.md`), false],
+    ];
+    const copies = mappings.map(([sourceFile, destination, archiveStatus]) => {
+        const source = join(feature.dir, sourceFile);
+        if (!existsSync(source))
+            throw new Error(`Cannot sync canonical docs: missing source artifact ${source}`);
+        const raw = readFileSync(source, "utf8");
+        const content = sourceFile === ARTIFACTS["use-case-specification"].file
+            ? raw.replace(/use-cases\/(UC-\d+\.md)/gi, "$1")
+            : archiveStatus ? archivedDocument(raw) : raw;
+        return {
+            destination,
+            content,
+            original: existsSync(destination) ? readFileSync(destination, "utf8") : null,
+        };
+    });
+    const useCaseSourceDir = join(feature.dir, "use-cases");
+    if (existsSync(useCaseSourceDir)) {
+        for (const file of readdirSync(useCaseSourceDir).filter((entry) => /^UC-\d+\.md$/i.test(entry))) {
+            const source = join(useCaseSourceDir, file);
+            const destination = join(base, "use-cases", context, feature.name, file);
+            copies.push({
+                destination,
+                content: readFileSync(source, "utf8"),
+                original: existsSync(destination) ? readFileSync(destination, "utf8") : null,
+            });
+        }
+    }
+    const legacy = join(base, "use-cases", context, `${feature.name}.md`);
+    // Older versions stored requirement mirrors under docs/use-cases.
+    if (existsSync(legacy) && !copies.some((copy) => copy.destination === legacy)) {
+        const raw = readFileSync(legacy, "utf8");
+        copies.push({ destination: legacy, content: archivedDocument(raw), original: raw });
+    }
+    return copies;
+}
+async function writeCanonicalCopies(copies) {
+    for (const copy of copies)
+        await writeFileAtomic(copy.destination, copy.content);
+}
+async function rollbackCanonicalCopies(copies) {
+    for (const copy of copies) {
+        if (copy.original === null)
+            await rm(copy.destination, { force: true });
+        else
+            await writeFileAtomic(copy.destination, copy.original);
+    }
+}
+export async function cmdArchive(args, cwd) {
+    const name = args.positionals[0];
+    if (!name)
+        return { code: 1, stdout: "Usage: kf archive <feature>", stderr: "missing feature" };
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const f = findFeature(root.root, name);
+    if (!f)
+        return { code: 1, stdout: `Unknown feature '${name}'. Run: kf list`, stderr: "unknown feature" };
+    if (f.stage === "cancelled") {
+        return { code: 1, stdout: `'${name}' was cancelled (${f.meta?.cancellation?.reason ?? "no reason recorded"}). Move it back to ${f.meta?.cancellation?.fromStage ?? "its stage"} first if you want to finish it.`, stderr: "cancelled" };
+    }
+    // Only review → dones transition is archive-able. If already dones, refresh canonical docs idempotently.
+    if (f.stage === "dones") {
+        const check = validateFeature(f);
+        if (!check.valid && !args.options.force)
+            return { code: 1, stdout: renderValidateText(check), stderr: "gate failed" };
+        const copies = args.options["skip-specs"] ? [] : prepareCanonicalCopies(root.root, f);
+        const changedDocs = copies.filter((copy) => copy.original !== null && copy.original !== copy.content);
+        if (changedDocs.length > 0 && !args.options.force) {
+            return {
+                code: 1,
+                stdout: `Canonical docs have changed since archive:\n${changedDocs.map((copy) => `  ${copy.destination}`).join("\n")}\nUse --skip-specs to preserve them, or --force only to intentionally restore the archived snapshot.`,
+                stderr: "canonical docs changed",
+            };
+        }
+        const metaPath = join(f.dir, METADATA_FILE);
+        const originalMeta = f.meta && existsSync(metaPath) ? readFileSync(metaPath, "utf8") : null;
+        try {
+            await writeCanonicalCopies(copies);
+            if (f.meta)
+                await writeFeatureMeta(f.dir, { ...f.meta, status: "archived" });
+        }
+        catch (err) {
+            const rollback = await Promise.allSettled([
+                rollbackCanonicalCopies(copies),
+                ...(originalMeta === null ? [] : [writeFileAtomic(metaPath, originalMeta)]),
+            ]);
+            const failures = rollback.filter((r) => r.status === "rejected").map((r) => r.reason);
+            if (failures.length > 0)
+                throw new AggregateError([err, ...failures], `Canonical docs sync failed and rollback was incomplete for '${name}'.`);
+            throw new Error(`Canonical docs sync failed for '${name}'; feature remains in dones.`, { cause: err });
+        }
+        return {
+            code: 0,
+            stdout: `Feature '${name}' is already in dones.\n${copies.length > 0 ? `Canonical docs synced:\n${copies.map((copy) => `  ${copy.destination}`).join("\n")}` : args.options["skip-specs"] ? "(--skip-specs: canonical docs not touched)" : "(no canonical docs synced)"}`,
+        };
+    }
+    if (f.stage !== "review") {
+        return {
+            code: 1,
+            stdout: `Cannot archive '${name}': feature is in stage "${f.stage}". Archive only from review (run: kf stage ${name} review first).`,
+            stderr: "wrong stage",
+        };
+    }
+    const force = Boolean(args.options.force);
+    const forcedCodes = [];
+    const check = validateFeature({ ...f, stage: "dones" });
+    if (!check.valid) {
+        if (!force) {
+            return {
+                code: 1,
+                stdout: `Gate failed for '${name}'. Fix validation before archiving:\n\n${renderValidateText(check)}\n\nOr re-run with --force.`,
+                stderr: "gate failed",
+            };
+        }
+        forcedCodes.push(...check.issues.filter((i) => i.severity === "ERROR").map((i) => i.code));
+    }
+    // Directional gate: only a PASS review-report may enter dones.
+    const direction = checkDirectionGate(f, "dones");
+    if (direction.length > 0) {
+        if (!force) {
+            const lines = direction.map((i) => `  [${i.severity}] ${i.file}: ${i.message} (${i.code})`).join("\n");
+            return {
+                code: 1,
+                stdout: `Cannot archive '${name}' — review result does not allow dones:\n\n${lines}\n\nOr re-run with --force.`,
+                stderr: "direction gate failed",
+            };
+        }
+        forcedCodes.push(...direction.map((i) => i.code));
+    }
+    const dest = stageDir(root.root, "dones");
+    const target = join(dest, f.folder);
+    if (existsSync(target)) {
+        return { code: 1, stdout: `Target already exists: ${target}`, stderr: "target exists" };
+    }
+    // Phase hook: run the 'dones' hook before archiving (unless --skip-hooks).
+    const skipHooks = Boolean(args.options["skip-hooks"]);
+    const skippedHook = skipHooks ? resolveHook(root.root, "dones") : null;
+    if (!skipHooks) {
+        const hook = runHook(root.root, {
+            feature: f.name,
+            context: f.context,
+            dir: f.dir,
+            root: root.root,
+            from: f.stage,
+            to: "dones",
+            approval: f.meta?.approval?.status ?? "pending",
+        });
+        if (hook.ran && !hook.ok) {
+            return {
+                code: 1,
+                stdout: `Hook 'dones' failed (exit ${hook.code})${hook.hook ? ` [${hook.hook.path}]` : ""}.\nArchive refused.\n\n${hook.output}\n\nRe-run with --skip-hooks to bypass.`,
+                stderr: "hook failed",
+            };
+        }
+    }
+    const afterHook = validateFeature({ ...f, stage: "dones" });
+    if (!afterHook.valid && !force)
+        return { code: 1, stdout: renderValidateText(afterHook), stderr: "gate failed" };
+    if (!f.meta)
+        return { code: 1, stdout: "Feature metadata is missing.", stderr: "metadata missing" };
+    const recorded = recordBypasses(f.stage, "dones", forcedCodes, skippedHook);
+    const bypasses = recorded.length > 0 ? [...(f.meta.bypasses ?? []), ...recorded] : f.meta.bypasses;
+    if (f.context)
+        assertPathName(f.context, "context");
+    assertPathName(f.name, "feature");
+    const copies = args.options["skip-specs"] ? [] : prepareCanonicalCopies(root.root, f);
+    const originalMeta = readFileSync(join(f.dir, METADATA_FILE), "utf8");
+    let moved = false;
+    try {
+        await rename(f.dir, target);
+        moved = true;
+        await writeCanonicalCopies(copies);
+        await writeFeatureMeta(target, { ...f.meta, bypasses, status: "archived" });
+    }
+    catch (err) {
+        if (!moved)
+            throw err;
+        const rollback = await Promise.allSettled([
+            writeFileAtomic(join(target, METADATA_FILE), originalMeta),
+            rollbackCanonicalCopies(copies),
+        ]);
+        const failures = rollback.filter((r) => r.status === "rejected").map((r) => r.reason);
+        try {
+            await rename(target, f.dir);
+        }
+        catch (rollbackError) {
+            failures.push(rollbackError);
+        }
+        if (failures.length > 0)
+            throw new AggregateError([err, ...failures], `Archive failed and rollback was incomplete for '${name}'.`);
+        throw new Error(`Archive failed for '${name}'; feature restored to review.`, { cause: err });
+    }
+    return {
+        code: 0,
+        stdout: `✓ Archived '${name}'  review → dones\n  ${target}\n${copies.length > 0 ? `  Canonical docs synced:\n${copies.map((copy) => `    ${copy.destination}`).join("\n")}` : args.options["skip-specs"] ? "  (--skip-specs: canonical docs not touched)" : "  (no canonical docs synced)"}${bypassNote(recorded)}`,
+    };
+}

package/dist/cli/commands/artifacts.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { ARTIFACTS } from "../../workflow/schema.js";
+import { findWorksRoot, findFeature } from "../../workflow/features.js";
+import { resolveTemplate, readTemplate } from "../../shared/paths.js";
+import { nowTimestamp } from "../../shared/time.js";
+export async function cmdInstruct(args, cwd) {
+    const artifact = args.positionals[0];
+    const change = typeof args.options.change === "string" ? args.options.change : null;
+    const useCase = artifact === "use-case";
+    const useCaseId = typeof args.options.id === "string" ? args.options.id.toUpperCase() : null;
+    if (!artifact) {
+        const known = Object.values(ARTIFACTS).map((a) => a.id).join(", ");
+        return { code: 1, stdout: `Missing artifact. Usage: kf instruct <artifact|use-case> --change <feature>\nArtifacts: ${known}, use-case`, stderr: "missing artifact" };
+    }
+    const def = Object.values(ARTIFACTS).find((a) => a.id === artifact);
+    if (!def && !useCase) {
+        const known = Object.values(ARTIFACTS).map((a) => a.id).join(", ");
+        return { code: 1, stdout: `Unknown artifact '${artifact}'. Artifacts: ${known}, use-case`, stderr: "unknown artifact" };
+    }
+    if (useCase && !useCaseId) {
+        return { code: 1, stdout: "Use case ID is required. Usage: kf instruct use-case --id UC-### [--change <feature>]", stderr: "missing use-case id" };
+    }
+    if (useCase && useCaseId && !/^UC-\d+$/.test(useCaseId)) {
+        return { code: 1, stdout: `Invalid use-case id '${useCaseId}'. Expected UC-###.`, stderr: "invalid use-case id" };
+    }
+    const root = findWorksRoot(cwd) ?? cwd;
+    const feature = change ? findFeature(root, change) : null;
+    if (change && !feature)
+        return { code: 1, stdout: `Unknown feature '${change}'.`, stderr: "unknown feature" };
+    const templateName = useCase ? "phase-2-use-case.md" : def.id === "spec-requirement" && feature?.meta?.kind === "bug"
+        ? "phase-1-bug-report.md"
+        : def.template;
+    const raw = await readTemplate(root, templateName);
+    const tpl = raw
+        ?.replaceAll("{feature_name}", feature?.name ?? "{feature_name}")
+        .replaceAll("{context}", feature?.context ?? "{context}")
+        .replaceAll("{timestamp}", nowTimestamp())
+        .replaceAll("{use_case_id}", useCaseId ?? "{use_case_id}")
+        .replaceAll("{execution_id}", feature?.meta?.executionId ?? "{execution_id}");
+    if (!tpl) {
+        return { code: 1, stdout: `Template '${templateName}' not found anywhere (project → ~/.kf → package).`, stderr: "no template" };
+    }
+    if (args.options.json) {
+        const file = useCase ? `${useCaseId ?? "UC-###"}.md` : def.file;
+        const outputPath = feature ? join(feature.dir, useCase ? "use-cases" : "", file) : null;
+        return {
+            code: 0,
+            stdout: JSON.stringify({
+                artifact: useCase ? "use-case" : def.id,
+                file,
+                templatePath: resolveTemplate(cwd, templateName)?.path,
+                instruction: `Write ${outputPath ?? file}. Fill all {placeholders}.`,
+                outputPath,
+                executionId: feature?.meta?.executionId ?? null,
+                unlocks: useCase ? "Planning contract — one UC-### per file" : def.unlocks,
+                template: tpl,
+            }, null, 2),
+        };
+    }
+    const lines = [];
+    lines.push(`<artifact id="${useCase ? "use-case" : def.id}" stage-phase="${useCase ? "plan" : def.phase}">`);
+    lines.push("");
+    const outputPath = useCase ? `${useCaseId ?? "UC-###"}.md` : def.file;
+    lines.push(`Write to: ${feature ? join(feature.dir, useCase ? "use-cases" : "", outputPath) : `<feature-folder>/${useCase ? "use-cases/" : ""}${outputPath}`}`);
+    lines.push(`Template (${resolveTemplate(cwd, templateName)?.source ?? "?"}): ${resolveTemplate(cwd, templateName)?.path}`);
+    lines.push("");
+    lines.push(`Unlocks: ${useCase ? "Planning contract — one UC-### per file" : def.unlocks}`);
+    if (change)
+        lines.push(`Feature: ${change}`);
+    lines.push("");
+    lines.push("--- template ---");
+    lines.push(tpl);
+    return { code: 0, stdout: lines.join("\n") };
+}
+export async function cmdTemplates(args, cwd) {
+    const rows = [
+        ...Object.values(ARTIFACTS).map((a) => ({
+            artifact: a.id,
+            template: a.template,
+            path: resolveTemplate(cwd, a.template)?.path ?? null,
+            source: resolveTemplate(cwd, a.template)?.source ?? "missing",
+        })),
+        {
+            artifact: "spec-requirement (bug)",
+            template: "phase-1-bug-report.md",
+            path: resolveTemplate(cwd, "phase-1-bug-report.md")?.path ?? null,
+            source: resolveTemplate(cwd, "phase-1-bug-report.md")?.source ?? "missing",
+        },
+        {
+            artifact: "use-case",
+            template: "phase-2-use-case.md",
+            path: resolveTemplate(cwd, "phase-2-use-case.md")?.path ?? null,
+            source: resolveTemplate(cwd, "phase-2-use-case.md")?.source ?? "missing",
+        },
+    ];
+    if (args.options.json)
+        return { code: 0, stdout: JSON.stringify(rows, null, 2) };
+    const lines = rows.map((r) => `${r.artifact.padEnd(16)} ${r.source.padEnd(8)} ${r.path}`);
+    return { code: 0, stdout: lines.join("\n") };
+}

package/dist/cli/commands/autoconfig.js

@@ -0,0 +1,180 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+import { findWorksRoot } from "../../workflow/features.js";
+import { commandHelp } from "../args.js";
+import { effectiveDefaultContext } from "../../project/contexts.js";
+import { readProjectConfig, detectStacks, configPath, projectKabanDir } from "../../project/config.js";
+import { AGENTS, DEFAULT_AGENT, projectSkillsDir } from "../../integrations/agents.js";
+import { MANAGED_SKILLS } from "../../integrations/install.js";
+import { PKG_RULES_DIR, USER_KABAN_DIR, resolveRule } from "../../shared/paths.js";
+function installedAgents(root) {
+    const has = (dir) => MANAGED_SKILLS.every((s) => existsSync(join(dir, s, "SKILL.md")));
+    return AGENTS.filter((a) => has(projectSkillsDir(a, root))).map((a) => a.id);
+}
+function checklist(root, stacks, agents, cfg) {
+    const items = [];
+    const kf = projectKabanDir(root);
+    items.push({
+        done: existsSync(configPath(root)),
+        label: "Project config (.kf/config.json)",
+        action: "kf init --defaults",
+    });
+    for (const id of agents) {
+        const a = AGENTS.find((x) => x.id === id);
+        if (!a)
+            continue;
+        items.push({
+            done: MANAGED_SKILLS.every((s) => existsSync(join(projectSkillsDir(a, root), s, "SKILL.md"))),
+            label: `Project skills for ${a.label} (${projectSkillsDir(a, root)}/)`,
+            action: `kf install --agent ${id}`,
+        });
+    }
+    const rulesDir = join(kf, "review", "rules");
+    const hasBase = ["general.md", "security.md", "performance.md"].every((f) => existsSync(join(rulesDir, f)));
+    items.push({
+        done: hasBase,
+        label: "Base review rules (.kf/review/rules/)",
+        action: "kf init --defaults (seeds templates + rules)",
+    });
+    const missingStacks = stacks.filter((s) => !existsSync(join(rulesDir, `${s}.md`)));
+    items.push({
+        done: stacks.length > 0 && missingStacks.length === 0,
+        label: stacks.length === 0 ? "Stack rule packs (no stack detected)" : `Stack rule packs: ${stacks.join(", ")}`,
+        action: stacks.length === 0 ? "kf rules --stack <id> (see: kf rules --list)" : `kf rules${missingStacks.map((s) => ` --stack ${s}`).join("")}`,
+    });
+    const hasGit = existsSync(join(root, ".git"));
+    if (hasGit) {
+        const gi = join(root, ".gitignore");
+        const ignored = existsSync(gi) && readFileSync(gi, "utf8").split("\n").some((l) => l.trim().replace(/\/$/, "") === ".works");
+        items.push({
+            done: ignored,
+            label: ".works/ ignored in .gitignore",
+            action: "echo '.works/' >> .gitignore",
+        });
+    }
+    items.push({
+        done: existsSync(join(root, "AGENTS.md")) || existsSync(join(root, "CLAUDE.md")),
+        label: "AGENTS.md (build/test/lint commands, conventions) at root",
+        action: "create AGENTS.md documenting the commands and conventions below",
+    });
+    const declared = cfg.contexts ?? [];
+    items.push({
+        done: declared.length > 0,
+        label: declared.length > 0
+            ? `Declared contexts: ${declared.join(", ")} (first is the default)`
+            : "Declared contexts (contexts in .kf/config.json) — kf new accepts any context until one is declared",
+        action: declared.length > 0 ? undefined : "kf contexts (prints a survey brief; the human confirms the list)",
+    });
+    const assigned = Object.keys(cfg.harness?.stages ?? {}).length;
+    items.push({
+        done: cfg.harness !== undefined,
+        label: cfg.harness ? `Multi-agent harness: main ${cfg.harness.main}, ${assigned} stage${assigned === 1 ? "" : "s"} assigned (kf harness)` : "Multi-agent harness (harness block in .kf/config.json)",
+        action: cfg.harness ? undefined : "kf init --defaults (seeds runner presets)",
+    });
+    const hooksDir = join(kf, "hooks");
+    const hooks = existsSync(hooksDir) ? readdirSync(hooksDir).filter((f) => f !== ".gitkeep").length : 0;
+    items.push({
+        done: hooks > 0,
+        label: "Phase hooks (.kf/hooks/) — optional",
+        action: "add shell hooks named after stages (e.g. testing) to run on kf stage",
+    });
+    return items;
+}
+function effectiveRules(cwd) {
+    const names = new Set();
+    const dirs = [PKG_RULES_DIR, join(USER_KABAN_DIR, "review", "rules"), join(projectKabanDir(findWorksRoot(cwd) ?? cwd), "review", "rules")];
+    for (const d of dirs) {
+        if (!existsSync(d))
+            continue;
+        for (const f of readdirSync(d)) {
+            if (f.endsWith(".md") && f !== "README.md")
+                names.add(f);
+        }
+    }
+    const rules = [];
+    for (const name of [...names].sort()) {
+        const resolved = resolveRule(cwd, name);
+        if (resolved)
+            rules.push({ name, path: resolved.path, source: resolved.source });
+    }
+    return rules;
+}
+/** Commands an agent drives the pipeline with, in the order they are used. */
+export const AGENT_COMMANDS = ["new", "status", "instruct", "approve", "validate", "stage", "run", "runs", "harness", "archive", "rules", "install"];
+/** The guide is generated from the registered help strings so it can never drift from the parser. */
+export function workflowGuide() {
+    const commands = AGENT_COMMANDS.map((cmd) => {
+        const [usage, description = ""] = commandHelp(cmd).replace(/^Usage:\s*/, "").split(/\s+—\s+/);
+        return `  ${usage}\n      ${description}`;
+    }).join("\n");
+    return `## Workflow guide
+
+Pipeline: brainstorm -> planning -> backlog -> implementation -> testing -> review -> dones
+
+Human gates (only places the agent must stop for the user):
+1. brainstorm: confirm the requirement before planning
+2. planning: kf approve the contract + choose start-now vs backlog
+
+Commands the agent will use (run \`kf help <command>\` for every option):
+${commands}
+
+Skills installed per agent: kanban-flow (orchestrator), kanban-brainstorm, kanban-bug,
+kanban-plan, kanban-implement, kanban-test, kanban-review, kanban-archive.
+Loop semantics: FAIL/REJECT in testing or review sends the item back to implementation
+with a new execution id; BLOCKED stops; REQUIREMENT_BUG freezes all movement.
+Never bypass a failed gate with --force or --skip-hooks unless the user explicitly approves;
+every bypass is recorded in the work item's metadata and reported by kf status/validate.`;
+}
+/**
+ * Print a self-contained briefing an agent can consume to configure this
+ * project: current context, a setup checklist with missing actions, the
+ * effective review rules to enforce, and the kanban workflow guide.
+ */
+export async function cmdAutoconfig(_parsed, cwd) {
+    const root = findWorksRoot(cwd) ?? cwd;
+    const cfg = readProjectConfig(root);
+    const stacks = cfg.stacks?.length ? cfg.stacks : detectStacks(root);
+    const known = new Set(AGENTS.map((a) => a.id));
+    const configured = (cfg.agents ?? []).filter((a) => known.has(a));
+    const agents = configured.length > 0 ? configured : [DEFAULT_AGENT];
+    const skills = installedAgents(root);
+    const ctx = [
+        "## Project context",
+        "",
+        `- Root: ${root}`,
+        `- ${cfg.stacks?.length ? "Configured" : "Detected"} stacks: ${stacks.length ? stacks.join(", ") : "none"}`,
+        `- Config: ${existsSync(configPath(root)) ? `${configPath(root)} (context: ${effectiveDefaultContext(cfg)}, reviewer: ${cfg.reviewer ?? "unset"}, agents: ${agents.join(", ")})` : "missing — run kf init"}`,
+        `- Skills installed (project scope): [${skills.join(", ") || "none"}]`,
+    ].join("\n");
+    const items = checklist(root, stacks, agents, cfg);
+    const check = [
+        "## Setup checklist",
+        "",
+        ...items.map((i) => `- [${i.done ? "x" : " "}] ${i.label}${i.done || !i.action ? "" : ` — run: \`${i.action}\``}`),
+    ].join("\n");
+    const rules = effectiveRules(cwd);
+    const rulesSection = [
+        "## Review rules to enforce",
+        "",
+        rules.length === 0
+            ? "No review rules found — run `kf init --defaults` then `kf rules`."
+            : "These rules apply at review (precedence: project -> user -> package). Apply them as coding conventions now:",
+        ...rules.flatMap((r) => ["", `### ${r.name} (${r.source}: ${r.path})`, "", readFileSync(r.path, "utf8").trim()]),
+    ].join("\n");
+    const out = [
+        "# kanban-flow agent setup briefing",
+        "",
+        `> You are configuring the project at ${basename(root)} for the kanban-flow workflow.`,
+        "> Work through the checklist, adopt the rules below as conventions, and use the",
+        "> workflow guide as your reference for driving features through the pipeline.",
+        "",
+        ctx,
+        "",
+        check,
+        "",
+        rulesSection,
+        "",
+        workflowGuide(),
+    ].join("\n");
+    return { code: 0, stdout: out };
+}

package/dist/cli/commands/cancel.js

@@ -0,0 +1,129 @@
+import { rename, rm } from "node:fs/promises";
+import { mkdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { findFeature, stageDir, writeFeatureMeta } from "../../workflow/features.js";
+import { findSecretLike } from "../../workflow/validate.js";
+import { runningRun } from "../../harness/run.js";
+import { runHook, resolveHook } from "../../integrations/hooks.js";
+import { readProjectConfig } from "../../project/config.js";
+import { selectOption } from "../../project/bootstrap.js";
+import { nowTimestamp } from "../../shared/time.js";
+import { canonicalDocPaths } from "./archive.js";
+import { findRoot, recordBypasses, bypassNote } from "./helpers.js";
+/**
+ * Stop a work item for good. The reason is mandatory: a cancelled item without
+ * one is indistinguishable from a folder someone forgot, which is the state
+ * this command exists to replace.
+ */
+export async function cmdCancel(args, cwd) {
+    const name = args.positionals[0];
+    if (!name)
+        return { code: 1, stdout: 'Usage: kf cancel <feature> --reason "<why>" [--by <name>] [--purge-docs] [--force] [--skip-hooks]', stderr: "missing feature" };
+    const reason = typeof args.options.reason === "string" ? args.options.reason.trim() : "";
+    if (!reason) {
+        return { code: 1, stdout: 'Cancelling needs a reason: kf cancel ' + name + ' --reason "<why it is being dropped>"', stderr: "missing reason" };
+    }
+    const secrets = findSecretLike(reason);
+    if (secrets.length > 0) {
+        return { code: 1, stdout: "The reason looks like it contains a credential; rewrite it without the secret.", stderr: "secret in reason" };
+    }
+    const root = await findRoot(cwd);
+    if (!root.ok)
+        return { code: 1, stdout: root.err, stderr: "no works" };
+    const f = findFeature(root.root, name);
+    if (!f)
+        return { code: 1, stdout: `Unknown feature '${name}'. Run: kf list`, stderr: "unknown feature" };
+    if (f.stage === "cancelled") {
+        return { code: 1, stdout: `'${name}' is already cancelled (${f.meta?.cancellation?.reason ?? "no reason recorded"}).`, stderr: "already cancelled" };
+    }
+    if (!f.meta)
+        return { code: 1, stdout: "Feature metadata is missing.", stderr: "metadata missing" };
+    const force = Boolean(args.options.force);
+    const forcedCodes = [];
+    const active = runningRun(f);
+    if (active) {
+        if (!force) {
+            return { code: 1, stdout: `Run ${active.id} (${active.role} @ ${active.stage}) is still running for '${name}'. Wait for it, or re-run with --force.`, stderr: "run in progress" };
+        }
+        forcedCodes.push("run_in_progress");
+    }
+    const skipHooks = Boolean(args.options["skip-hooks"]);
+    const skippedHook = skipHooks ? resolveHook(root.root, "cancelled") : null;
+    if (!skipHooks) {
+        const hook = runHook(root.root, {
+            feature: f.name, context: f.context, dir: f.dir, root: root.root,
+            from: f.stage, to: "cancelled", approval: f.meta.approval?.status ?? "pending",
+        });
+        if (hook.ran && !hook.ok) {
+            return {
+                code: 1,
+                stdout: `Hook 'cancelled' failed (exit ${hook.code})${hook.hook ? ` [${hook.hook.path}]` : ""}.\nCancel refused.\n\n${hook.output}\n\nRe-run with --skip-hooks to bypass.`,
+                stderr: "hook failed",
+            };
+        }
+    }
+    const docs = f.stage === "dones" ? canonicalDocPaths(root.root, f) : [];
+    const purge = Boolean(args.options["purge-docs"]);
+    let purgeApproved = false;
+    if (purge && docs.length > 0) {
+        if (force) {
+            purgeApproved = true;
+        }
+        else if (!process.stdin.isTTY) {
+            return {
+                code: 1,
+                stdout: `Refusing to delete canonical docs without confirmation:\n${docs.map((d) => `  ${relative(root.root, d)}`).join("\n")}\nRe-run with --force.`,
+                stderr: "purge requires interactive confirmation or --force",
+            };
+        }
+        else {
+            const pick = await selectOption(`Delete these canonical docs of '${name}'? (↑/↓ + Enter)\n${docs.map((d) => `  ${relative(root.root, d)}`).join("\n")}`, ["Keep them — only cancel the work item", "Delete them"]);
+            if (pick !== 1) {
+                return { code: 0, stdout: `Cancelled nothing. Re-run without --purge-docs to drop the work item and keep the docs.` };
+            }
+            purgeApproved = true;
+        }
+    }
+    const by = typeof args.options.by === "string" && args.options.by.trim()
+        ? args.options.by.trim()
+        : readProjectConfig(root.root).reviewer ?? "human";
+    const recorded = recordBypasses(f.stage, "cancelled", forcedCodes, skippedHook);
+    const cancellation = { at: nowTimestamp(), by, reason, fromStage: f.stage };
+    const dest = stageDir(root.root, "cancelled");
+    mkdirSync(dest, { recursive: true });
+    const target = join(dest, f.folder);
+    await writeFeatureMeta(f.dir, {
+        ...f.meta,
+        status: "cancelled",
+        cancellation,
+        ...(recorded.length > 0 ? { bypasses: [...(f.meta.bypasses ?? []), ...recorded] } : {}),
+    });
+    try {
+        await rename(f.dir, target);
+    }
+    catch (err) {
+        try {
+            await writeFeatureMeta(f.dir, f.meta);
+        }
+        catch (rollbackError) {
+            throw new AggregateError([err, rollbackError], `Cancel failed and metadata rollback was incomplete for '${name}'.`);
+        }
+        throw err;
+    }
+    // Deleting docs cannot be undone, so it happens only after the move succeeded.
+    let purged = false;
+    if (purgeApproved) {
+        for (const doc of docs)
+            await rm(doc, { recursive: true, force: true });
+        purged = true;
+    }
+    const docsNote = docs.length === 0
+        ? ""
+        : purged
+            ? `\n  Deleted canonical docs:\n${docs.map((d) => `    ${relative(root.root, d)}`).join("\n")}`
+            : `\n  Canonical docs left in place (use --purge-docs to delete them):\n${docs.map((d) => `    ${relative(root.root, d)}`).join("\n")}`;
+    return {
+        code: 0,
+        stdout: `✓ Cancelled '${name}' (was ${cancellation.fromStage}) by ${by}\n  Reason: ${reason.split("\n")[0]}\n  ${target}${docsNote}\n  Reopen with: kf stage ${name} ${cancellation.fromStage}${bypassNote(recorded)}`,
+    };
+}