@phuthuycoding/kanban-flow 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quyen (phuthuycoding)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# kanban-flow
+
+An AI coding agent will tell you the tests passed, the plan was followed, the
+edge cases are covered. Sometimes it is right, and you cannot tell which time
+from the transcript, because the transcript is written by the same thing you are
+checking. kanban-flow moves the proof into files on disk: the gates do not read
+the agent's summary, they read `.works/`.
+
+## How it works
+
+Every work item walks one pipeline, and only the CLI moves it between stages:
+
+```text
+brainstorm → planning → implementation → testing → review → dones
+                 ↘ backlog ↗                 ↺ FAIL loops back
+any stage → cancelled, with a reason on the record
+```
+
+```mermaid
+flowchart LR
+    B([brainstorm]) -->|requirement confirmed| P([planning])
+    P -->|contract approved + fingerprint| I([implementation])
+    P -.->|hold| BL([backlog])
+    BL -.->|start| I
+    I -->|tasks done| T([testing])
+    T -->|report PASS + current execution id| R([review])
+    R -->|report PASS + feature report| D([dones])
+    T -.->|FAIL| I
+    R -.->|FAIL| I
+    I -.->|kf cancel --reason| X([cancelled])
+    X -.->|reopen where it stopped| I
+```
+
+Solid arrows are the happy path, and every label on one is a gate the CLI checks
+before the folder moves. Dotted arrows are the ways out: hold it in backlog,
+loop back on a FAIL, or stop it for good with a reason on the record.
+
+Most stages owe an artifact. A transition is refused when that artifact is
+missing, empty, still full of template placeholders, or carrying a real secret.
+A testing report that does not say `PASS` does not reach review; a review report
+that does not say `PASS` does not archive. `--force` overrides a gate and is
+recorded in `.kfw.json` where a reviewer will find it.
+
+Three decisions belong to a human: marking the requirement `status: confirmed`,
+approving the execution contract, and choosing whether to start now or hold it
+in backlog. The approval is bound to a SHA-256 fingerprint of the contract, so
+editing the plan invalidates it, and no stage further forward accepts the item
+until it returns to planning and is approved again.
+
+## Install
+
+Needs Node 20 or newer.
+
+```bash
+npm install -g @phuthuycoding/kanban-flow
+```
+
+That puts `kf` on your PATH. To work from source instead:
+
+```bash
+git clone https://github.com/phuthuycoding/kanban-flow.git
+cd kanban-flow && npm install && npm run build && npm link
+```
+
+## A run, end to end
+
+The agent runs the commands and writes the artifacts between them, taking every
+template and path from `kf instruct`. `kf status` shows the artifact checklist;
+`kf validate` reports what is actually blocking a gate, traceability included.
+
+```bash
+cd your-project
+kf init                             # asks a few questions, seeds .kf/, installs the skills
+kf new user-login --context auth    # opens Phase 1 in brainstorm
+kf instruct spec-requirement --change user-login
+# write the requirement, set its frontmatter to status: confirmed — decision one
+kf stage user-login planning
+# write the plan, the use-case index, one file per UC, the diagram, the test plan
+kf approve user-login               # decision two; fingerprints all of it
+kf stage user-login implementation  # or backlog — decision three
+kf stage user-login testing         # mints a fresh execution id
+# write the testing report, carrying that id and real exit codes
+kf stage user-login review          # refused unless that report says PASS
+# write the review report, then the feature report
+kf archive user-login               # refused unless the review says PASS
+```
+
+## What is actually different
+
+Most of the mechanics here exist elsewhere: requirement-to-test traceability as
+a CI gate, role-to-runner configuration, hash-bound plan approval, a cancelled
+state with a mandatory reason, blocking placeholders. No claim to inventing them.
+
+One mechanic I have not found anywhere else: **every entry into testing mints a
+fresh execution id**, and a report is accepted only when its `execution:` field
+matches the current one. Fix a failure, go round again, and yesterday's green
+report is inert. Stale test evidence stops being a way to pass.
+
+```mermaid
+sequenceDiagram
+    participant A as Agent
+    participant K as kf
+    participant F as .works/
+
+    A->>K: kf stage x testing
+    K->>F: mint execution id run-1
+    A->>F: testing report, execution run-1
+    A->>K: kf stage x review
+    K-->>A: PASS and id matches, allowed
+
+    Note over A,F: review returns FAIL, the code changes
+
+    A->>K: kf stage x implementation
+    A->>K: kf stage x testing
+    K->>F: mint execution id run-2
+    A->>K: kf stage x review
+    K-->>A: refused, the report still says run-1
+```
+
+The old report is not deleted, argued with, or trusted less. It simply stops
+matching, so passing again costs exactly one honest test run. The rest of the
+case is the combination: a gate reading files instead of claims, an approval
+bound to the bytes it approved, evidence that expires.
+
+## Multi-agent harness
+
+Stages route to **roles**, roles point at **runners**. A runner is one way to
+invoke a CLI: its argv, its permission flags, how its session resumes. A role is
+a job such as researcher or tester. Pointing a role at an existing runner is one
+line; a runner nobody has declared yet is a few more.
+
+```json
+"harness": {
+  "main": "architect",
+  "roles": { "architect": "claude", "researcher": "codex", "writer": "gemini", "coder": "claude" },
+  "stages": { "brainstorm": ["researcher", "writer"], "implementation": "coder" },
+  "runners": {
+    "claude": { "start": ["claude", "-p", "{prompt}"] },
+    "codex":  { "start": ["codex", "exec", "{prompt}"] },
+    "gemini": { "start": ["gemini", "-p", "{prompt}"] }
+  }
+}
+```
+
+```mermaid
+flowchart LR
+    S1[stage: brainstorm] --> R1[role: researcher] --> N2[runner: codex]
+    S1 --> R2[role: writer] --> N3[runner: gemini]
+    S2[stage: implementation] --> R3[role: coder] --> N1[runner: claude]
+```
+
+A stage runs its roles in order, and a role that declares an `output` file hands
+it to the next one. A role reporting neither `DONE` nor `DONE_WITH_CONCERNS`
+stops the chain. Sessions are kept per work item and per role, so two roles on
+one CLI never share context.
+
+```bash
+kf harness                     # stage → role chain, role → runner, which CLIs are on PATH
+kf run user-login --detach     # run the current stage's chain; poll with kf runs
+kf runs user-login --json      # each run: role, runner, status, usage where reported
+```
+
+Presets ship for claude, codex, devin, gemini and opencode. Assign no stages and the harness stays out of the way.
+
+## Documentation
+
+The full reference lives in [docs/workflow](docs/workflow/README.md): the [state
+machine](docs/workflow/state-machine.md), every [gate](docs/workflow/gates.md), the
+[artifacts](docs/workflow/artifacts.md), the [CLI reference](docs/workflow/cli-reference.md),
+the [harness](docs/workflow/harness.md), the [dashboard](docs/workflow/dashboard.md). Release
+notes: [CHANGELOG.md](CHANGELOG.md).
+
+## License — MIT

package/dist/cli/args.js

@@ -0,0 +1,219 @@
+import { parseArgs } from "node:util";
+const COMMANDS = {
+    init: {
+        help: "Usage: kf init [path] [--defaults] [--minimal] [--context <ctx>] [--agent <id> ...]  — onboarding: asks setup questions on a TTY (defaults when non-TTY or --defaults), seeds .kf config + installs skills; --minimal skips the questions, not the scaffolding (still writes .kf config, skills and AGENTS.md; only the template/hook/rule files are left out)",
+        allowPositionals: true,
+        options: {
+            context: { type: "string", short: "c" },
+            interactive: { type: "boolean", short: "i" },
+            defaults: { type: "boolean" },
+            minimal: { type: "boolean" },
+            agent: { type: "string", multiple: true },
+        },
+    },
+    new: {
+        help: "Usage: kf new <feature> [--context <ctx>] [--type feature|bug]  — create a work item in .works/brainstorm",
+        allowPositionals: true,
+        options: {
+            context: { type: "string", short: "c" },
+            goal: { type: "string", short: "g" },
+            type: { type: "string", short: "t" },
+        },
+    },
+    list: {
+        help: "Usage: kf list [--json]",
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    show: {
+        help: "Usage: kf show <feature> [--json]",
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    view: {
+        help: "Usage: kf view [--json]  — workflow metrics by stage, kind, context and approval",
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    dashboard: {
+        help: "Usage: kf dashboard [--port <n>]  — start a local analytics dashboard with metrics and charts (default port 8787)",
+        options: {
+            port: { type: "string", short: "p" },
+        },
+    },
+    status: {
+        help: "Usage: kf status [--change <feature>] [--all] [--json]  — artifact checklist, Next step, approval state and recorded bypasses",
+        options: {
+            change: { type: "string" },
+            all: { type: "boolean", short: "a" },
+            json: { type: "boolean" },
+        },
+    },
+    instruct: {
+        help: "Usage: kf instruct <artifact|use-case> [--change <feature>] [--id UC-###]  — print the template, current execution id and exact output path",
+        allowPositionals: true,
+        options: {
+            change: { type: "string" },
+            id: { type: "string" },
+            json: { type: "boolean" },
+        },
+    },
+    templates: {
+        help: "Usage: kf templates [--json]",
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    validate: {
+        help: "Usage: kf validate [--change <feature>] [--all] [--strict] [--json]  — report gate, traceability, secret and bypass issues (exit 1 on failure)",
+        options: {
+            change: { type: "string" },
+            all: { type: "boolean", short: "a" },
+            strict: { type: "boolean" },
+            json: { type: "boolean" },
+        },
+    },
+    stage: {
+        help: "Usage: kf stage <feature> <next-stage> [--skip-hooks]  — move feature to next stage",
+        allowPositionals: true,
+        options: {
+            force: { type: "boolean", short: "f" },
+            "skip-hooks": { type: "boolean" },
+        },
+    },
+    approve: {
+        help: "Usage: kf approve <feature> [--by <name>]  — approve Phase 2 execution contract (Human gate)",
+        allowPositionals: true,
+        options: {
+            by: { type: "string" },
+        },
+    },
+    archive: {
+        help: "Usage: kf archive <feature> [--skip-hooks]  — close a work item in dones; features sync canonical docs, bugs retain related docs",
+        allowPositionals: true,
+        options: {
+            force: { type: "boolean", short: "f" },
+            "skip-specs": { type: "boolean" },
+            "skip-hooks": { type: "boolean" },
+        },
+    },
+    rules: {
+        help: "Usage: kf rules [--stack <id> ...] [--list] [--force]  — copy stack best-practice review rules into .kf/review/rules (auto-detects stack; packs: node, go, rust, python, php, ruby, java)",
+        options: {
+            stack: { type: "string", multiple: true },
+            list: { type: "boolean" },
+            force: { type: "boolean", short: "f" },
+        },
+    },
+    autoconfig: {
+        help: "Usage: kf autoconfig  — print a briefing for an agent to configure this project: context, setup checklist, effective review rules and the workflow guide",
+        options: {},
+    },
+    doctor: {
+        help: "Usage: kf doctor [--json]  — diagnose the project: stage dirs, config, work item metadata, installed skills; exits 1 when something is broken",
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    install: {
+        help: "Usage: kf install [--agent <id> ...]  — copy the 8 kanban skills into project-level agent skill dirs {root}/.<agent>/skills (default: claude). Requires a kanban project (.works/). Agents: claude, codex, gemini, kiro, cursor, opencode",
+        options: {
+            agent: { type: "string", multiple: true },
+        },
+    },
+    uninstall: {
+        help: "Usage: kf uninstall [--agent <id> ...] [--purge] [--force]  — remove the 8 kanban skills from project-level agent skill dirs {root}/.<agent>/skills (default: claude). --purge also deletes .works/, .kf/ and kanban doc dirs (asks first; --force skips the prompt)",
+        options: {
+            agent: { type: "string", multiple: true },
+            purge: { type: "boolean" },
+            force: { type: "boolean" },
+        },
+    },
+    cancel: {
+        help: 'Usage: kf cancel <feature> --reason "<why>" [--by <name>] [--purge-docs] [--force] [--skip-hooks]  — stop a work item for good, recording who dropped it and why; reopen later with kf stage <feature> <its old stage>',
+        allowPositionals: true,
+        options: {
+            reason: { type: "string" },
+            by: { type: "string" },
+            "purge-docs": { type: "boolean" },
+            force: { type: "boolean", short: "f" },
+            "skip-hooks": { type: "boolean" },
+        },
+    },
+    run: {
+        help: "Usage: kf run <feature> [--stage <s>] [--role <r>] [--fresh] [--detach] [--timeout <min>] [--dry-run]  — run the roles assigned to the work item's stage (harness.stages) as worker agents, in order, and record each run",
+        allowPositionals: true,
+        options: {
+            stage: { type: "string" },
+            role: { type: "string" },
+            agent: { type: "string" },
+            fresh: { type: "boolean" },
+            detach: { type: "boolean" },
+            timeout: { type: "string" },
+            "dry-run": { type: "boolean" },
+            supervise: { type: "string" },
+        },
+    },
+    runs: {
+        help: "Usage: kf runs [<feature>] [--json]  — list worker runs (role, runner, stage, status, STATUS line) for one or all open work items",
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    contexts: {
+        help: "Usage: kf contexts [--json]  — list the declared contexts and the ones work items actually use; prints a survey brief when none are declared",
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    harness: {
+        help: "Usage: kf harness [--json]  — show the multi-agent harness: stage to role chains, role to runner, and whether each runner CLI is on PATH",
+        options: {
+            json: { type: "boolean" },
+        },
+    },
+    help: {
+        help: "Usage: kf help [command]",
+        allowPositionals: true,
+    },
+    version: {},
+};
+export function parseArgsCli(argv) {
+    const command = argv[0] ?? "help";
+    const spec = COMMANDS[command];
+    if (!spec)
+        return { command, positionals: argv.slice(1), options: {} };
+    const opts = {};
+    for (const [k, v] of Object.entries(spec.options ?? {})) {
+        const d = { type: v.type };
+        if (v.short !== undefined)
+            d.short = v.short;
+        if (v.default !== undefined)
+            d.default = v.default;
+        if (v.multiple !== undefined)
+            d.multiple = v.multiple;
+        opts[k] = d;
+    }
+    opts.help = { type: "boolean", short: "h" };
+    const { values, positionals } = parseArgs({
+        args: argv.slice(1),
+        options: opts,
+        allowPositionals: spec.allowPositionals ?? false,
+        strict: true,
+    });
+    return { command, positionals, options: values };
+}
+export function commandHelp(command) {
+    const spec = COMMANDS[command];
+    if (!spec)
+        return `Unknown command: ${command}. Use "kf help".`;
+    return spec.help ?? `kf ${command}`;
+}
+export function allCommands() {
+    return Object.keys(COMMANDS);
+}

package/dist/cli/commands/approve.js

@@ -0,0 +1,44 @@
+import { findFeature, writeFeatureMeta, executionContractHash } from "../../workflow/features.js";
+import { validateFeature, renderValidateText } from "../../workflow/validate.js";
+import { readProjectConfig } from "../../project/config.js";
+import { nowTimestamp } from "../../shared/time.js";
+import { findRoot } from "./helpers.js";
+/**
+ * Human-in-the-Loop gate for Phase 2: the execution contract (implementation
+ * plan + use cases + test cases) must be approved before autonomous execution.
+ */
+export async function cmdApprove(args, cwd) {
+    const name = args.positionals[0];
+    if (!name)
+        return { code: 1, stdout: "Usage: kf approve <feature> [--by <name>]", 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 !== "planning") {
+        return {
+            code: 1,
+            stdout: `Cannot approve '${name}': feature is in stage "${f.stage}". Approval only applies during Phase 2 (planning).`,
+            stderr: "wrong stage",
+        };
+    }
+    const check = validateFeature(f, false, false);
+    if (!check.valid) {
+        return { code: 1, stdout: `Cannot approve an incomplete execution contract:\n${renderValidateText(check)}`, stderr: "invalid contract" };
+    }
+    const contractHash = executionContractHash(f.dir, f.meta?.kind === "bug" ? "bug" : "feature");
+    if (!contractHash || !f.meta)
+        return { code: 1, stdout: "Execution contract or metadata is missing.", stderr: "invalid contract" };
+    const cfg = readProjectConfig(root.root);
+    const by = typeof args.options.by === "string" ? args.options.by : (cfg.reviewer ?? "human");
+    if (!by.trim())
+        return { code: 1, stdout: "Approver name must not be empty.", stderr: "missing approver" };
+    const approval = { status: "approved", by, at: nowTimestamp(), contractHash };
+    await writeFeatureMeta(f.dir, { ...f.meta, approval, executionId: undefined });
+    return {
+        code: 0,
+        stdout: `✓ Approved '${name}' (by ${by} at ${approval.at})\n  Execution contract is now the binding scope for autonomous phases.`,
+    };
+}