@phuthuycoding/kanban-flow 0.3.0

package/docs/workflow/harness.md

@@ -0,0 +1,144 @@
+# Multi-agent harness
+
+A **role** does one job in the pipeline, and each role points at a **runner**: a CLI, a model and its permission flags. Stages are assigned to roles, never to vendors. Assign no stages and nothing changes: the main agent does everything itself.
+
+## Why three layers
+
+```
+stage  →  role       →  runner
+testing   tester        gemini (CLI + model + permission flags)
+```
+
+- **Stage to role almost never changes.** Testing always wants a tester, review always wants a reviewer. Write it once.
+- **Role to runner is where you change your mind about a model.** Find one that writes better and `writer` becomes a one-line edit, with no stage touched.
+- **Runner to CLI and flags** is what breaks when a vendor changes its interface. One broken runner does not take the rest down with it.
+
+Every model is strong at something different: breadth of research, prose, code, review. A role is how you say "this job needs that strength" without hard-wiring a vendor's name into the pipeline.
+
+## Why "resume the latest session" is never needed
+
+kanban-flow keeps its state in files: `.works/`, the artifacts and `.kfw.json`. It never relies on what a conversation remembers. A worker for a stage is a fresh headless session whose context is that stage's skill plus the artifacts on disk. A session is kept **per work item and per role**, so the repair loop from FAIL back to implement continues in the session that did the work, and that id is either minted by kf or fetched deterministically, never guessed as "the latest". Two roles sharing one runner still get two separate sessions, so `coder` and `reviewer` on the same CLI never see each other's context.
+
+## Config
+
+The `harness` block in `.kf/config.json`, which `kf harness` displays. This example is a **hand-tuned** one, spreading roles across several runners. What `kf init` seeds is deliberately plainer: all six roles on the single agent you chose, and `"stages": {}` — so nothing is routed to a worker until you assign it:
+
+```json
+"harness": {
+  "main": "architect",
+  "roles": {
+    "architect":  "claude-opus",
+    "researcher": { "runner": "codex",  "brief": "Explores breadth: prior art, libraries, comparable features.", "output": "research.md" },
+    "writer":     { "runner": "gemini", "brief": "Turns agreed decisions into precise prose." },
+    "coder":      "claude-opus",
+    "tester":     { "runner": "devin",  "brief": "Runs the real suite and records exact commands and exit codes." },
+    "reviewer":   "codex"
+  },
+  "stages": {
+    "brainstorm":     ["researcher", "writer"],
+    "implementation": "coder",
+    "testing":        "tester",
+    "review":         "reviewer"
+  },
+  "runners": {
+    "claude-opus": {
+      "start":  ["claude", "-p", "{prompt}", "--session-id", "{session}", "--permission-mode", "acceptEdits", "--output-format", "json"],
+      "resume": ["claude", "-p", "{prompt}", "-r", "{session}", "--permission-mode", "acceptEdits", "--output-format", "json"],
+      "session": "provided",
+      "usage": "json"
+    },
+    "codex": {
+      "start":  ["codex", "exec", "--json", "{prompt}"],
+      "resume": ["codex", "exec", "resume", "{session}", "{prompt}"],
+      "session": { "stdout": "\"thread_id\":\"([^\"]+)\"" },
+      "usage": "json"
+    },
+    "devin": {
+      "start":  ["devin", "-p", "{prompt}", "--permission-mode", "accept-edits"],
+      "resume": ["devin", "-p", "{prompt}", "-r", "{session}", "--permission-mode", "accept-edits"],
+      "session": { "command": ["devin", "list", "--format", "json"], "idField": "id", "matchField": "title" }
+    },
+    "gemini":   { "start": ["gemini", "-p", "{prompt}", "--approval-mode", "auto_edit"] },
+    "opencode": { "start": ["opencode", "run", "{prompt}"] }
+  }
+}
+```
+
+- `main`: the role the orchestrating agent plays. It must be a role, not a runner.
+- `roles.<role>`: a runner name in short form, or `{ runner, brief?, output? }`.
+  - `brief`: a sentence or two describing the role, injected into the prompt so the worker knows what it was called for.
+  - `output`: an extra file the role must write inside the work item folder, such as `research.md`, for the next role to read. The path has to stay inside the work item folder.
+- `stages.<stage>`: one role, or **an array of roles run in order**. The `backlog` stage cannot be assigned. Any stage left undeclared is handled by the main agent.
+- `runners.<runner>`: see the table below. Permissions (`--permission-mode`, `--approval-mode`, `--sandbox`) live in the template; kf injects no flags of its own.
+
+Adding a model means adding a runner and pointing a role at it. Two models on one CLI, such as `claude-opus` and `claude-haiku`, are two runners, assigned to the expensive role and the cheap one.
+
+### Runner fields
+
+| Field | What it means |
+|---|---|
+| `start` | The argv for a fresh session. `{prompt}` is mandatory. `{session}` is allowed only under `session: "provided"`, where kf mints a UUID before running |
+| `resume` | The argv to continue a stored session; it must contain `{session}`. Without it the role always starts fresh |
+| `session` | `"provided"`, `{ "stdout": "<regex, group 1>" }`, or `{ "command", "idField", "matchField" }`, which runs a command returning a JSON array and picks the entry whose `matchField` contains the `kf-run:<id>` marker kf puts at the head of the prompt |
+| `usage` | `"json"` parses `usage.input_tokens` and `usage.output_tokens`, plus `total_cost_usd` when present, from JSON on stdout |
+| `skillsDir` | The runner's skills directory. Defaults follow `kf install`: `.claude/skills`, `.agents/skills` (codex), `.gemini/skills`, `.kiro/skills`, `.cursor/skills`, `.opencode/skills`, and any unfamiliar name falls back to `.agents/skills` |
+| `resumeFailure` | A regex that recognises a failed resume; the default is `session\|not found\|no such\|unknown\|does not exist` |
+
+### Presets, as verified on 2026-09-19
+
+| Runner | Session | What was verified |
+|---|---|---|
+| claude | kf mints the UUID via `--session-id`, resumes with `-r`; usage and cost come from the JSON | Run for real: start and resume both work |
+| codex | `thread_id` from the JSONL of `exec --json`, resumes with `exec resume <id>`; usage from `turn.completed` | Run for real: start and resume both work |
+| devin | `devin list --format json` matched on `title` against the marker; resumes with `-r <id>` | Run for real: start, list and resume all work. Devin refuses an untrusted directory, so open `devin` interactively once inside the repo |
+| gemini | no resume | Could not log in on the verification machine. `-r` accepts `latest` or an index; whether it accepts a UUID is unknown |
+| opencode | no resume | How to obtain the id is unverified; `run -s <id>` does exist |
+
+## Flow
+
+1. Before each stage, the main agent, running the `kanban-flow` skill, reads `kf status --change <f> --json`. When `assignedRoles` is present it runs `kf run <f>`, adding `--detach` for a long stage such as implementation and then polling `kf runs <f>`.
+2. `kf run` resolves the stage's role chain and runs it **in order**. Each role's prompt carries: the role and its `brief`, the work item, the stage, the folder, the path to that runner's phase `SKILL.md`, pointers to `kf status` and `kf instruct`, the requirement to write `output` when the role has one, a "Previous step" section naming the previous role, its output file and its log from the second step onward, and the contract: do only this stage's work, never run `kf stage`, `kf approve`, `kf archive` or `kf run`, never edit an approved contract, never commit, and finish with `STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT` followed by `Summary:`.
+3. Each role is its own run: its own process group, its own `runs/<id>.log`, and one entry in `.kfw.json.runs[]` carrying both `role` and `runner`.
+4. A role that does not end in `DONE` or `DONE_WITH_CONCERNS` **stops the chain**. The roles after it do not run, `kf run` exits 1, and it names which role stopped and which were skipped.
+5. The main agent reads `STATUS` and `Summary` from the tail of the log, without swallowing the transcript, runs `kf validate` and decides on the transition. The gate does not take the worker's word for anything.
+6. On the repair loop, the next `kf run` resumes that role's session for that work item, and the prompt gains the path to the current FAIL report. `--fresh` forces a new session.
+
+`kf run --role <name>` runs exactly one role from the chain. `--dry-run` prints the plan for the whole chain, one argv and prompt block per role. The timeout is 30 minutes by default (`--timeout <minutes>`, `0` for none); on expiry the whole process group is killed and the run is marked `timeout`. There is no automatic retry: a failed resume resets the session exactly once and starts fresh. A work item has at most one `running` run at a time.
+
+With `--detach`, kf writes the chain plan, spawns a detached `kf run --supervise <id>` as the supervisor and returns immediately. The supervisor runs the whole chain and finds the folder again by work item name before writing results; when the folder is gone it writes `.works/harness/orphan-<id>.json`. `kf runs` reports `failed (supervisor lost)` when a record is still `running` but its pid is dead, and it never repairs the metadata on its own.
+
+## Observability
+
+- `kf harness [--json]`: the main role, stage to role chain, role to runner with brief and output, and runner to CLI, PATH, resume and session.
+- `kf status --change <f>`: `Assigned: researcher (codex) → writer (gemini) (kf run)` and `Runs: N (role×n, …)`; the JSON carries `assignedRoles` and `runs[]`.
+- `kf runs [<f>] [--json]`: every run with its role, its runner and its place in the chain, such as `2/2`, newest first. A run that ends a chain before the last role while nothing else is running shows `chain stopped 1/2` with a warning underneath, and the JSON carries `chainBroken`. This is how you spot a broken chain, from a dead supervisor or a Ctrl+C, instead of assuming the stage finished.
+
+Typing a runner name into `stages` gets a message that says so, rather than "unknown role":
+
+```
+Invalid project config: .kf/config.json — harness.stages.testing "gemini" is a runner,
+not a role; declare a role in harness.roles that points at it
+```
+- `kf view [--json]`: `metrics.runs.byRole` as `{ runs, done, failed }`, and `metrics.runs.usage` broken down by role.
+
+## Token cost
+
+- The real work of reading code, changing it and running tests does not grow. It simply moves onto the assigned runner's quota.
+- What does grow: every handover makes a worker re-read the skill, the artifacts and the relevant code, roughly 10 to 30 thousand tokens. **A role chain multiplies that by its length**: a two-role brainstorm pays for two handovers. Chain roles only when the two jobs are genuinely different.
+- The repair loop costs another handover when the runner cannot resume.
+- The main agent gets cheaper: it spends nothing while a worker runs, and only reads the tail of the log.
+- Waste is held down: prompts carry paths rather than content, the chain stops the moment a role fails, a worker that prints no `STATUS` counts as unfinished, and nothing retries.
+- Measurement: a runner with `usage: "json"` records tokens and cost into `runs[]`, and `kf view` totals them **by role**, so you can see which role is the expensive one.
+
+## Limits
+
+- The "do not move the stage" rule is a contract in the prompt, not something kf can enforce, because the worker has `kf` on its PATH. `runs[]` and `bypasses[]` are there to check against.
+- Chains are always sequential, never parallel. Stopping midway leaves a half-done state: the first role wrote its file, the next never ran. `kf run` says so, `kf runs` marks it `chain stopped i/n`, and the stage's artifact gate is still what decides.
+- Killing a process group uses `process.kill(-pid)`, which is POSIX. On Windows, kf cannot clean up a worker's children.
+- `.kfw.json` is written both by the supervisor and by the main agent's `kf stage`. kf re-reads before writing and writes atomically, but there is no lock.
+- A worker log can contain whatever sensitive content the CLI printed. `.works/` is usually gitignored; keep it that way.
+- There is no async bridge yet, meaning nothing wakes the main agent once it is gone, and no `kf run --task` for ad-hoc work outside a stage.
+
+## Terms of use
+
+kf only spawns each vendor's official CLI using the headless flags that vendor documents (`claude -p`, `codex exec`, `gemini -p`, `devin -p`, `opencode run`), under the account already logged in on the machine running it. kf **never** reads, stores or forwards any CLI's credentials or tokens, never calls a vendor API directly and never retries in bursts. Each user remains responsible for the terms of the plan they are on, covering commercial use, account sharing and rate limits. This document is not legal advice.

package/docs/workflow/lifecycle.md

@@ -0,0 +1,107 @@
+# Workflow Lifecycle
+
+## The whole flow
+
+```mermaid
+flowchart TD
+    A([User describes a feature or a bug]) --> B{Does the project have .works?}
+    B -- No --> C[kf init]
+    B -- Yes --> D[Read the repo and pick the current phase]
+    C --> D
+    D --> E{Is the work item a bug?}
+    E -- No --> F[Brainstorm: pin down scope and acceptance]
+    E -- Yes --> G[Bug triage: reproduce, actual vs expected, severity]
+    F --> H[kf new + phase-1-spec-requirement.md]
+    G --> H
+    H --> I{Requirement confirmed?}
+    I -- Not yet --> E
+    I -- Yes --> J[kf stage item planning]
+    J --> K{Work item kind?}
+    K -- Feature --> KP[Planning: implementation plan + one file per UC + diagram + test plan]
+    K -- Bug --> KB[Planning: triage report + fix scope + regression strategy]
+    KP --> L{Human approves the execution contract?}
+    KB --> L
+    L -- Not yet --> K
+    L -- Yes --> M[kf approve: store the contract fingerprint]
+    M --> N{Start implementation now?}
+    N -- Yes --> O[Implementation: tasks.md + code]
+    N -- Not yet --> P[Backlog: hold the approved contract]
+    P --> Q{User chooses to start?}
+    Q -- Not yet --> P
+    Q -- Yes --> O
+    O --> R{Build green and tasks done?}
+    R -- Not yet --> O
+    R -- Yes --> S[kf stage item testing]
+    S --> T[Mint a new execution id]
+    T --> U[Run the tests from the Test Strategy]
+    U --> V[Write testing-result carrying the execution id]
+    V --> W{Testing PASS?}
+    W -- FAIL/REJECT --> O
+    W -- BLOCKED --> X([Stop and report the blocker])
+    W -- PASS --> Y[kf stage item review]
+    Y --> Z[Review changed files against rules: project, then user, then package]
+    Z --> AA[Write review-report carrying the execution id]
+    AA --> AB{Review result?}
+    AB -- FAIL/REJECT --> O
+    AB -- REQUIREMENT_BUG --> AC([Stop and ask the user to decide])
+    AB -- PASS --> AD{Work item kind?}
+    AD -- Feature --> FC[Write feature-report]
+    FC --> AE[kf archive: copy requirement, use-case and testplan docs]
+    AD -- Bug --> BC[Update the related feature docs if needed]
+    BC --> BA[kf archive: keep the bug record with its test and review]
+    BA --> AF
+    AE --> AF([dones: archive complete])
+```
+
+There is a second way out of this flow: `kf cancel <feature> --reason "<why>"` stops a work item for good at any stage, `dones` included when something supersedes it. The reason is mandatory and is stored in `.kfw.json` together with the stage it stopped in, so reopening it is `kf stage <feature> <that stage>`. This is the user's decision; the agent only suggests it on a `REQUIREMENT_BUG` or a dead scope.
+
+Phase 1, the Phase 2 approval and the start-or-backlog decision are the points where the user decides. A feature produces all four planning artifacts; a bug uses its bug report as the triage contract and produces no feature use cases or test plan. If behaviour appears beyond the scope of the fix, tell the user and let them decide before opening a separate feature. Once start is chosen the agent runs on its own inside the execution contract. Two exceptions still need the user: `REQUIREMENT_BUG`, and any change of scope.
+
+## Starting a feature, step by step
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Orchestrator as kanban-flow
+    participant CLI as kf
+    participant FS as .works/.kf/docs
+
+    User->>Orchestrator: Describes the context and the feature
+    Orchestrator->>CLI: kf init when .works is missing
+    Orchestrator->>CLI: kf new item --context context [--type bug]
+    CLI->>FS: Create the brainstorm folder, the metadata and the spec or bug template
+    Orchestrator->>User: Summarise the requirement or the triage, plus the open questions
+    User-->>Orchestrator: Confirms, or adjusts the scope
+    Orchestrator->>FS: Write status: confirmed into the requirement or bug report
+    Orchestrator->>CLI: kf stage feature planning
+    Orchestrator->>User: Summarise the execution contract
+    User-->>Orchestrator: approve
+    Orchestrator->>CLI: kf approve item
+    CLI->>FS: Store the approval contractHash
+    Orchestrator->>User: Start now, or send to backlog?
+    User-->>Orchestrator: start now / defer
+    Orchestrator->>CLI: kf stage item implementation or backlog
+```
+
+## Fixing a failure, step by step
+
+```mermaid
+sequenceDiagram
+    participant Test as kanban-test
+    participant CLI as kf
+    participant Impl as kanban-implement
+    participant FS as Work item folder
+
+    Test->>CLI: kf stage feature review
+    CLI-->>Test: Refused when the testing report is not PASS on the current execution
+    Test->>FS: Write testing-result with status FAIL or REJECT
+    Test->>CLI: kf stage feature implementation
+    CLI->>FS: Retire the current execution id
+    Impl->>FS: Fix the code and tick the tasks
+    Impl->>CLI: kf stage feature testing
+    CLI->>FS: Mint a new execution id
+    Test->>FS: Write testing-result for the new execution
+    Test->>CLI: kf stage feature review
+```
+
+An old report is kept as evidence, but it can never stand in as the result of a new execution.

package/docs/workflow/skills.md

@@ -0,0 +1,52 @@
+# Skill routing
+
+`kanban-flow` is the orchestrator. Each phase skill owns only that phase's work; the real state stays with the CLI and the filesystem.
+
+The orchestrator also owns the harness: when `.kf/config.json` assigns roles to a stage, `kf run` hands that stage to worker sessions instead of the orchestrator doing the work itself. The routing below still decides *which skill* loads; the harness decides *who runs it*. See [the harness guide](harness.md).
+
+```mermaid
+flowchart TD
+    O[kanban-flow orchestrator] --> B[kanban-brainstorm]
+    O --> BUG[kanban-bug: kind=bug]
+    B --> P[kanban-plan]
+    BUG --> P
+    P --> H{Human approve}
+    H --> D{Start now?}
+    D -->|Yes| I[kanban-implement]
+    D -->|No| BL[backlog]
+    BL -->|User starts| I
+    I --> T[kanban-test]
+    T -->|PASS| R[kanban-review]
+    T -->|FAIL/REJECT| I
+    T -->|scope change| P
+    R -->|PASS| A[kanban-archive]
+    R -->|FAIL/REJECT| I
+    R -->|scope change| P
+    A --> DONE[feature canonical docs or bug docs update + dones]
+```
+
+## Responsibilities
+
+| Skill | What it owns | What it must not decide alone |
+| --- | --- | --- |
+| `kanban-flow` | Read the state, route to the phase, name the gate, resume at the right point | Never treat a requirement as confirmed on its own, never bypass a human gate |
+| `kanban-brainstorm` | Ask about and pin down the problem, the goal, the scope and the acceptance criteria; write Phase 1 | Never move to planning before the user has confirmed |
+| `kanban-plan` | For a feature, produce the execution plan, each UC file, the diagram, the test plan and the traceability; for a simple bug, keep the triage contract and write a full plan only when the behaviour contract changes | Never approve the contract, never choose start or backlog |
+| `kanban-bug` | Triage the bug: reproduce it, record actual against expected, severity, root cause and the regression requirement | Never settle on a root cause alone, never start implementation alone |
+| `kanban-implement` | Execute the tasks in the contract, hold the scope, update code and tests; subagents run under a prompt contract of task, files, acceptance and constraints, plus the status protocol | Never widen the scope or skip the plan without returning to planning |
+| `kanban-test` | Run the tests, record the execution id and the evidence, classify as PASS, FAIL, REJECT or BLOCKED | Never turn a BLOCKED into a PASS |
+| `kanban-review` | Review the implementation, the tests, the architecture, the security and the scope, including the AI-risk lens: phantom tests, catch-and-swallow, scope drift | Never archive when the report is not PASS |
+| `kanban-archive` | For a feature, write the feature report and then call `kf archive`, which is what copies the canonical docs; for a bug, settle the docs impact and update only the related docs when needed | Never copy the canonical docs by hand — that skips the link rewrite and the `status: archived` stamp, and the next archive refuses. Never delete data, never deploy or publish on its own |
+
+## Resuming and handing off
+
+When starting or resuming a feature:
+
+1. Read `kf status --change <feature> --json` and `kf validate --change <feature> --json`.
+2. Read the artifacts of the current state and the one before it. Do not guess from the folder name.
+3. In `planning` with a stale approval, finish the contract again and ask for a fresh `kf approve`.
+4. In `testing` or `review`, use the `executionId` the metadata holds. A report from another execution is not valid.
+5. On a `FAIL` or a `REJECT`, fix it in implementation and return to testing. On a `REQUIREMENT_BUG`, stop and tell the user. On a `BLOCKED`, stop and report the blocker.
+6. Call archive only after a PASS review. A feature needs its full feature report; a bug needs a settled docs impact.
+
+The phase 6 artifact is the handover document. It states what actually changed, which tests ran, which docs were updated, what limits remain and which follow-ups were accepted.

package/docs/workflow/source-layout.md

@@ -0,0 +1,47 @@
+# Source layout
+
+CLI runtime code lives under `src/` and is grouped by responsibility. File moves do not change the public `kf` commands or the generated entrypoint `dist/index.js`.
+
+```text
+src/
+├── index.ts              # CLI entrypoint and command dispatch
+├── cli/
+│   ├── args.ts           # argument parsing and help metadata
+│   ├── result.ts         # command result contract
+│   └── commands/         # command handlers, split by use
+│       ├── init.ts       # project initialization
+│       ├── new.ts        # feature/bug creation
+│       ├── inspect.ts    # list, show, view, status, validate
+│       ├── artifacts.ts  # instruct and templates
+│       ├── stage.ts      # state transitions
+│       ├── approve.ts    # planning approval
+│       ├── rules.ts      # stack review-rule pack installation
+│       ├── autoconfig.ts # agent-facing setup briefing (context, checklist, rules, workflow)
+│       ├── run.ts        # kf run / kf runs (hand a stage to a worker agent)
+│       ├── harness.ts    # kf harness (effective harness config)
+│       └── archive.ts    # closure and canonical docs sync
+├── workflow/             # domain state, artifacts and validation
+│   ├── schema.ts         # stages, artifacts, transitions
+│   ├── features.ts       # .kfw.json metadata (approval, execution id, bypasses), feature listing
+│   ├── status.ts         # artifact checklist rendering
+│   ├── findings.ts       # Finding/ValidationResult types
+│   ├── secrets.ts        # secret-like content scan
+│   ├── validate-artifacts.ts     # due artifacts, stage gate, requirement confirmed
+│   ├── validate-approval.ts      # approval fingerprint, recorded bypasses
+│   ├── validate-reports.ts       # tasks.md, testing/review report semantics, exit codes
+│   ├── validate-traceability.ts  # FR → UC → TC references
+│   ├── direction.ts      # directional gate (PASS/FAIL/REQUIREMENT_BUG)
+│   └── validate.ts       # facade: composes the checks, renders results, re-exports
+├── harness/              # multi-agent harness: role/runner config, worker prompt, session, run executor, role chain, detached supervisor
+├── project/              # project config, declared contexts and bootstrap prompts
+├── integrations/         # agents, skill installation and hooks
+├── dashboard/            # analytics HTTP server and HTML view
+├── shared/               # filesystem paths, frontmatter and time helpers
+└── tests/                # all Vitest tests, grouped separately from runtime
+    ├── helpers/          # fake agent CLIs and harness project fixture
+    └── setup/            # vitest globalSetup (builds dist for detached-run tests)
+```
+
+Dependency direction is intentionally one-way: command handlers call workflow/project/integration services; workflow code does not import CLI handlers. Shared utilities contain no command dispatch. This keeps changes to the CLI surface isolated from state and artifact rules.
+
+When adding code, place it beside the responsibility it serves. Add a command handler under `src/cli/commands/`, a state or gate rule under `src/workflow/`, and its test under `src/tests/`. Keep the public dispatch in `src/index.ts` limited to wiring.

package/docs/workflow/state-machine.md

@@ -0,0 +1,83 @@
+# State machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> brainstorm: kf new
+    brainstorm --> planning: requirement/bug report filled + confirmed
+    planning --> backlog: approved + defer
+    planning --> implementation: approved + start now
+    backlog --> implementation: user chooses start
+    backlog --> planning: revise scope/plan
+    implementation --> testing: implementation complete
+    implementation --> planning: scope/plan needs change
+    testing --> review: testing result PASS
+    testing --> implementation: testing FAIL/REJECT
+    testing --> planning: scope change
+    review --> dones: review PASS + closure for kind
+    review --> implementation: review FAIL/REJECT
+    review --> planning: scope change
+    dones --> [*]
+    brainstorm --> cancelled: kf cancel --reason
+    planning --> cancelled: kf cancel --reason
+    backlog --> cancelled: kf cancel --reason
+    implementation --> cancelled: kf cancel --reason
+    testing --> cancelled: kf cancel --reason
+    review --> cancelled: kf cancel --reason
+    dones --> cancelled: kf cancel --reason
+    cancelled --> brainstorm: reopen at cancellation.fromStage
+    cancelled --> [*]
+
+    state testing {
+        [*] --> execution
+        execution: executionId is required
+    }
+    state review {
+        [*] --> review_execution
+        review_execution: report must use current executionId
+    }
+```
+
+## States and transitions
+
+| State | What it means | Allowed transitions |
+| --- | --- | --- |
+| `brainstorm` | Working the requirement out with the user | `planning` |
+| `planning` | A feature settles its execution contract, a bug confirms its triage contract; then approval, then the start or backlog decision | `backlog`, `implementation` |
+| `backlog` | The contract is approved but work has not started | `implementation`, `planning` |
+| `implementation` | The agent executes against the approved contract | `testing`, `planning` |
+| `testing` | Run the tests from the test plan and record the outcome | `review`, `implementation`, `planning` |
+| `review` | Review the code, the scope and the architecture, and write the report | `dones`, `implementation`, `planning` |
+| `dones` | Archived; a terminal state | `cancelled`, via `kf cancel` |
+| `cancelled` | Stopped for good; it sits off the linear track, so no artifact is ever demanded of it | Back to `cancellation.fromStage` only |
+
+The CLI allows only the edges above. Never move a `.works/` folder by hand.
+
+## The guards that matter
+
+- The requirement or bug report must be filled in and marked confirmed before it leaves `brainstorm`.
+- Leaving `planning` needs all four planning artifacts and the UC files for a feature; a bug needs only a filled bug report and a real human's approval. The approval stores a fingerprint of the matching contract, so editing the contents afterwards makes it stale.
+- Every entry into `testing` mints a new `executionId`. Both `phase-4-testing-result.md` and `phase-5-review-report.md` must carry the current one.
+- `FAIL` and `REJECT` return to `implementation`. `BLOCKED` stops the flow. `REQUIREMENT_BUG` is a stop condition in review: never rewrite the requirement or move the state on your own.
+- Only a `PASS` review whose testing and review match the current execution reaches `dones`. A feature also needs `phase-6-feature-report.md`; a bug does not.
+- The only way into `cancelled` is `kf cancel`, and `--reason` is mandatory. The only way out is back to the stage it stopped in (`cancellation.fromStage`), at which point `cancellation` and `status` are cleared from the metadata. `kf archive` refuses a cancelled item.
+
+The minimum metadata looks like this:
+
+```json
+{
+  "schema": "kanban-flow",
+  "kind": "feature",
+  "feature": "payment-retry",
+  "context": "billing",
+  "created": "20260917_1405",
+  "approval": {
+    "status": "approved",
+    "by": "human",
+    "at": "20260917_1430",
+    "contractHash": "sha256:..."
+  },
+  "executionId": "uuid-of-the-current-testing-run"
+}
+```
+
+The `executionId` is cleared on a return to planning **and on every entry into implementation**, then reissued when a new testing execution begins. The implementation reset is the one that matters in a FAIL loop: it is what stops the old testing evidence from counting for the repaired code. A bug report lives in `phase-1-spec-requirement.md` using the bug template; it needs none of the feature planning artifacts. If new behaviour appears beyond the scope of the fix, tell the user and let them decide before opening a separate feature.

package/kanban-flow/review/rules/README.md

@@ -0,0 +1,30 @@
+# Kanban Flow Review Rules
+
+## Structure
+- `general.md` — Rules applied to every review
+- `security.md` — Security-specific checks
+- `performance.md` — Performance-specific checks
+- `{stack}.md` — Stack-specific rules. Packs ship in the package at `kanban-flow/review/stacks/{stack}.md` (7 packs: `node`, `go`, `rust`, `python`, `php`, `ruby`, `java`) and are installed into this directory via `kf rules`.
+
+## How to Use
+Skill `kanban-review` loads all rules in this directory at review time.
+Project-specific rules override global rules when same filename exists.
+
+## Installing Stack Rules
+```bash
+kf rules                                  # auto-detect stacks from manifests (monorepo: installs every detected pack)
+kf rules --stack go --stack python        # install specific packs
+kf rules --list                           # list available packs and detected stacks
+kf rules --force                          # overwrite a project rule file that differs from the pack
+```
+Without `--force`, an existing `.kf/review/rules/{stack}.md` that differs from the pack is skipped with a warning — project rules are user-owned. Re-running on an identical file reports "already installed". Works before `kf init`.
+
+## Adding Rules
+Create a new `.md` file in this directory. Each rule should be:
+- A short imperative sentence
+- Specific enough to verify (not "write good code")
+
+## Severity Levels
+- **HIGH** — Must fix before merge (security risk, data loss, crash)
+- **MEDIUM** — Should fix before merge (performance, maintainability)
+- **LOW** — Suggestion, can defer

package/kanban-flow/review/rules/general.md

@@ -0,0 +1,41 @@
+# General Code Review Rules
+
+## Error Handling
+- Never swallow errors (empty catch/try)
+- Catch only specific exception types
+- Every catch must handle or rethrow with context
+- App must not panic on exception
+- Log with stack trace, request id, input, and correct level
+
+## Code Quality
+- One file max 500 lines (if longer, re-evaluate responsibilities)
+- Split by responsibility, not by line count
+- One file = one clear responsibility
+- Separate UI logic from display logic when file grows
+
+## Naming & Changes
+- Do not rename functions/files for style preference only
+- Rename only when name causes semantic confusion
+- No reformatting existing code (no import reorder, no quote changes)
+- Each edit = one purpose, no refactoring during bug fix
+
+## Comments
+- No unnecessary comments describing what code does
+- Comment only "why" (decisions, constraints, gotchas)
+- No TODO comments, no "changed by AI", no "removed old logic"
+
+## Review Discipline
+- Scout first: read the actual repo/code before asking the user or flagging — no findings based on guesses
+- Review only files that actually changed; verify claims against the real diff
+- Preserve verified decisions: do not reopen a decision already verified earlier without new evidence
+- Preserve user decisions: never silently undo user-chosen scope, libraries, or thresholds
+- Threat-model before applying a finding: state what the code stores, protects, and exposes; fix the real failure mode, not the abstract one
+
+## Stable Artifacts
+- Do not embed plan IDs, phase numbers, or finding codes (FR-001, TC-002, HIGH-1) in code comments, test names, or commit messages — they rot when the plan changes
+- Reference artifacts by stable names in docs; keep mutable anchors out of the codebase
+
+## Security
+- Never commit secrets or keys
+- Never expose secrets in logs
+- Validate and sanitize input at boundaries

package/kanban-flow/review/rules/performance.md

@@ -0,0 +1,29 @@
+# Performance Review Rules
+
+## Queries & Data Access
+- No N+1 queries (check for loops with DB calls inside)
+- Use pagination for list endpoints
+- Add indexes for frequently queried fields
+- Prefer batch operations over individual operations
+
+## Caching
+- Identify cacheable data (read-heavy, slow-compute)
+- Set appropriate TTL
+- Invalidate cache on data mutation
+
+## Network & I/O
+- Prefer async/parallel for independent I/O
+- Set timeouts on external calls
+- Handle connection pooling properly
+- Avoid unnecessary data transfer
+
+## Memory
+- Stream large data instead of loading into memory
+- Watch for memory leaks in event listeners
+- Clean up resources (close files, connections)
+
+## Frontend (if applicable)
+- Lazy load non-critical resources
+- Optimize bundle size
+- Minimize re-renders (React memoization)
+- Compress images and assets

package/kanban-flow/review/rules/security.md

@@ -0,0 +1,32 @@
+# Security Review Rules
+
+## Secrets Management
+- No hardcoded credentials, API keys, or tokens
+- No secrets in workflow artifacts (specs, plans, reports) — `kf validate` rejects secret-like content
+- Use environment variables or secret managers
+- Never log sensitive data
+
+## Threat Model First
+- Before applying a security finding, state what the code stores, protects, and exposes
+- Fix the real failure mode, not the abstract pattern — a finding without a reachable attack path is LOW
+- Do not add auth/crypto/validation where the data is not sensitive and not externally reachable
+
+## Input Validation
+- Validate all external input at system boundary
+- Sanitize before using in queries, commands, templates
+- Use parameterized queries (no string concatenation for SQL)
+
+## Authentication & Authorization
+- Check auth before business logic
+- Use established auth patterns (not custom crypto)
+- Enforce least-privilege access
+
+## Dependencies
+- No known vulnerable dependencies
+- Review new dependencies before adding
+- Lock dependency versions
+
+## Data Protection
+- Encrypt sensitive data at rest and in transit
+- Mask sensitive data in logs
+- Apply rate limiting on public endpoints

package/kanban-flow/review/stacks/go.md

@@ -0,0 +1,33 @@
+# Go Review Rules
+
+## Error Handling
+- No ignored errors — every `err` is checked, wrapped with `%w` context, or explicitly documented why safe
+- No `panic` in library code; reserve for truly unrecoverable startup failures
+- Error return is the last return value; sentinel errors via `errors.Is`/`errors.As`, not `==` on messages
+- No empty `if err != nil {}` blocks and no `_ =` discarding of meaningful errors
+
+## Concurrency
+- Every goroutine has a defined lifecycle — no fire-and-forget without a stop/join path
+- Shared state guarded by mutex/channel, never by convention; run `go test -race` clean
+- Channels closed by the sender only; no send on possibly-closed channel
+- `context.Context` is the first parameter and propagates cancellation — no `context.Background()` deep in call chains
+
+## Resources
+- `defer x.Close()` immediately after successful open/conn/resp — before the error return path
+- HTTP response bodies always drained and closed
+- No goroutine leaks via unbounded blocking writes — use buffered channels or select+ctx
+
+## Code Quality
+- Exported symbols have doc comments starting with the symbol name
+- Interfaces defined at the consumer, small (1-3 methods); no giant interface up front
+- No init() side effects beyond registration; wiring happens in main/composition root
+- Table-driven tests for branching logic; `t.Helper()` in test helpers
+
+## Dependencies & Config
+- `go.mod`/`go.sum` committed; no replace directives left without a comment why
+- No global mutable state — config passed explicitly or via struct fields
+
+## Performance
+- No string concatenation in hot loops — `strings.Builder`
+- Slice/map capacity preallocated when size is known
+- No N+1 DB calls — batch or join at the repository layer