Kanban Flow — Orchestrator

The user describes the idea; the agent decides the rest. One command runs the whole lifecycle; each phase runs a dedicated skill.

ARGUMENTS: <context> <feature_name> — e.g. kanban auth user-login or kanban billing payment-timeout --type bug

State is enforced by the kf CLI: artifact gates, approval fingerprints, execution ids, report statuses and traceability. The agent authors and verifies the content; file presence alone cannot prove that code was tested.

Human boundary: user participates in Phase 1 (brainstorm/bug triage), Phase 2 (approval) and the explicit start-now vs backlog decision. After the user chooses start, run everything autonomously within the approved scope. Stop and ask only for a decision on backlog start, REQUIREMENT_BUG or a scope change; do not ask "continue?" between normal phases.

Preflight: if the project has no .works/, run kf init --defaults first (full bootstrap without prompts; use kf init -i when the user should answer the setup questions). Detect project stack/tooling by READING the repository — never assume.

---

Phase model & artifact contract

brainstorm → planning → implementation → testing → review ─┬→ shipping → dones
                 ↘ backlog ↗                              └──────────→ dones
                 ↘ backlog ↗

Folder name: {feature_name}_{timestamp} (created by kf new). Artifacts follow phase-{x}-{name}.md.

Phase	Skill	Gate artifacts (filled to LEAVE)	Notes
1. Brainstorm / Bug triage	kanban-brainstorm or kanban-bug	phase-1-spec-requirement.md (status: confirmed)	Human + agent refine requirement or reproduce bug
2. Planning	kanban-plan	Feature: four phase-2 files + use-cases/UC-###(-<slug>).md; bug: confirmed bug report	Human approval, then start/backlog decision
Backlog	—	Approved planning contract remains intact	Waiting for explicit user decision to start
3. Implement	kanban-implement	— (tasks.md tracks)	Autonomous
4. Testing	kanban-test	phase-4-testing-result.md (status: PASS)	FAIL/REJECT → loop to implementation
5. Review	kanban-review	phase-5-review-report.md (status: PASS)	FAIL/REJECT → loop; REQUIREMENT_BUG → STOP
5.5 Shipping	kanban-ship	— (meta.ship tracks)	Optional leg — code items only; third human gate: ship now or archive directly?
6. Closure	kanban-archive	Feature: phase-6-feature-report.md; bug: current test/review evidence	Feature canonical docs or affected bug docs, then archive — accepts review or shipping

Two gate layers on every move:

1. Artifact gate — files exist and contain no template placeholders.
2. Directional gate — report status semantics: FAIL/REJECT blocks forward motion and forces a loop back to implementation; REQUIREMENT_BUG blocks all motion (STOP FEATURE — never silently rewrite the requirement).

For features, kf validate checks each ## TC-### for FR references and matching individual UC files. Approval fingerprints the requirement, four planning artifacts and individual UC files. For bugs, approval fingerprints only the bug report; feature planning artifacts and feature report are not required. A changed contract must return to planning for human approval. Each entry to testing creates a new execution id; testing and review reports must carry that id in execution:. Read templates with kf instruct <artifact> --change <feature> to obtain the current id and exact output path.

Feature canonical docs are synced by the CLI on archive:

• Requirement: docs/requirement/{context}/{feature_name}.md
• Use cases: docs/use-cases/{context}/{feature_name}/README.md, one UC-###(-<slug>).md per use case and diagram.md
• Test plan/result: docs/testplan/{context}/{feature_name}.md and {feature_name}-result.md

Work item type is stored in .kfw.json as kind: feature|bug. Create a bug with kf new <name> --type bug; route it to kanban-bug for reproduction and triage before planning.

Bug closure updates the existing related feature docs only if needed. Do not auto-create feature docs for a bug or overwrite a feature requirement with bug-report content.

---

How to delegate phases

The pipeline is ONE run but each phase has a specialist skill. Drive it like this:

kf status --all                # which phase is each feature in?
kf status --change {feature}   # current phase + artifact checklist + Next: + Approval

Then load the skill for the feature's CURRENT phase and follow it to its endpoint (each skill ends pointing at the next one). Do not re-read old phase instructions you've already executed; go straight at the target.

If planning is already approved and its fingerprint is unchanged, ask whether to start now or keep the item in backlog. If an item is in backlog, do not start implementation without an explicit user decision. If review has a current PASS report, the item is at the ship gate — ask the human once: ship via kanban-ship (kf stage <f> shipping → kf ship) or archive directly from review (non-code items). kf archive refuses while a recorded PR is unmerged and accepts items in either review or shipping. If already in dones, validate and finish only missing closure work; never implement again. Resume existing artifacts and tasks instead of recreating the item or approved plan. kf status --all includes backlog and dones.

Multi-agent harness

If .kf/config.json has harness.stages, some stages are assigned to roles (writer, coder, tester…), each backed by a runner CLI. Before doing a stage's work yourself, read kf status --change {feature} --json: when assignedRoles is non-empty, you are the orchestrator for that stage — do not do the work, hand it off:

kf run {feature}            # blocking; runs the stage's whole role chain in order
kf run {feature} --detach   # long stages (implementation): returns a chain id
kf runs {feature}           # poll until the runs are done, then read their STATUS
kf run {feature} --role writer   # re-run one role of the chain

A stage can list several roles (brainstorm: ["researcher", "writer"]); they run one after another and each gets told where the previous one wrote. If a role does not finish DONE/DONE_WITH_CONCERNS, the chain stops there and the later roles never run — read the log of the role that stopped, do not simply re-run the chain.

When polling a detached chain, check the chain column in kf runs (1/2, 2/2): a run marked chain stopped 1/2 means the later roles never ran, so the stage is not done even though nothing is running. Treat it like a stopped chain: read that role's log before deciding.

Then act on the worker's STATUS:: DONE → kf validate --change {feature} and decide the transition as usual (gates, not the worker's word, decide); DONE_WITH_CONCERNS → read the concerns in the run log, then decide; BLOCKED / NEEDS_CONTEXT → stop and ask the user. A run without a STATUS: line or with a non-zero exit is not done. Never do an assigned stage yourself unless the user says so. Human gates stay with you.

If you are resuming mid-pipeline (the feature already exists), skip straight to the phase skill for its current phase. Never trust a folder location alone — a stage folder is not "done"; artifact + report completeness is.

---

Interaction policy

• User gives ONE command. Agent does everything else automatically.
• Brainstorm asks about material ambiguity only (missing scope, unclear behavior, conflicting acceptance criteria). Minor details → reasonable assumption + record it in the spec.
• Confirm the requirement in Phase 1, then obtain execution-contract approval in Phase 2. Present a tight summary + implementation plan and ask for approval. On approval run kf approve. Without approval, do not start autonomous execution.
• If scope must change after approval, stop implementation and explain the change. On the user's direction run kf stage <feature> planning, revise the contract and obtain fresh approval. REQUIREMENT_BUG blocks this route too; report it and await a human decision.
• Auto-fix benign blockers once. Stop + ask only when genuinely stuck.
• Never bypass a failed gate with --force unless the user explicitly approves.

---

CLI reference

kf init                        # scaffold .works/ + hooks + docs
kf doctor [--fix] [--json]     # diagnose the project; --fix applies the repairs needing no human decision
kf issues [view <n>|create|link|sync <feature>]  # GitHub issues on the configured repository, via gh
kf contexts [--json]           # declared contexts + counts, or a survey brief when none
kf new {feature} --context {ctx} [--type feature|bug]   # Phase 1: create feature/bug + seed spec
kf status --change {feature}   # artefact checklist + Next: + approval state
kf instruct {artifact} --change {feature}   # current execution id + exact output path
kf approve {feature}           # Phase 2 HITL gate
kf validate --change {feature}  # gate + traceability issues
kf stage {feature} {phase}     # move (gates + hooks run; planning → backlog/implementation)
kf run {feature} [--detach]    # run the roles assigned to the current stage (harness.stages), in order
kf runs {feature}              # worker run history (role, runner) + STATUS lines
kf stage {feature} shipping    # optional leg for code items (review+PASS only)
kf ship {feature}              # resumable: publish → merge gate → release → changelog (ship.enabled)
kf archive {feature}           # the delivery gate: merged-PR check → review/shipping → dones + docs + issue close + board + delivered stamp

Contexts: a project may declare the ones it uses in .kf/config.json, and the first entry is the default. kf new refuses a context outside that list and names the nearest declared one; a case-only variant is refused too. Run kf contexts --json before kf new and use a declared name exactly. When restricted is false nothing is declared and any valid name works. Never add a context to the config to get past a refusal — naming a business domain is the human's call.

Phase hooks: <project>/.kf/hooks/{phase}.sh run automatically before entering a phase (project → user ~/.kf/hooks → package precedence). Exit non-zero blocks the transition (--skip-hooks bypasses). The agent does NOT run hooks manually — kf stage does. Hooks also receive KFW_REPOSITORY when .kf/config.json sets repository (owner/name) — a hook that syncs work items to GitHub reads it rather than hardcoding the repo, and kf issues works off the same field. When .kf/config.json also has a project block (GitHub Projects board), hooks get KFW_PROJECT_OWNER/KFW_PROJECT_NUMBER/KFW_PROJECT_AC_GATE/KFW_PROJECT_STATUS_<STAGE>; kf init can seed the generic sync pack (issue on new, spec sync, AC gate at archive) into .kf/hooks/.

---

Hard rules

• Do NOT ask "continue to next step?" — autonomous after the user chooses start at the Phase 2 decision gate.
• Obtain requirement confirmation and planning approval; after approval continue within the approved scope.
• After planning approval, explicitly ask whether to start implementation now or move to backlog. Never infer this choice.
• Never mv feature folders manually — always kf stage / kf archive.
• Never bypass a failed gate with --force unless the user explicitly approves. Every real bypass (--force on a failing gate, --skip-hooks on an existing hook) is recorded in .kfw.json and reported by kf status/kf validate.
• Always write phase-4-testing-result.md and phase-5-review-report.md — gates enforce it.
• FAIL/REJECT loops back to implementation and re-testing before review. REQUIREMENT_BUG → STOP, never rewrite the requirement. When the item should be dropped for good (requirement wrong at the root, work superseded, user says stop), propose kf cancel {feature} --reason "<why>" and let the user decide; never cancel on your own. Reopening later is kf stage {feature} <the stage it was cancelled from>.
• No scope creep beyond the approved plan.
• Follow the project's AGENTS.md and the user's permissions. Autonomous execution does not authorize unrelated changes, database operations, deployment or messages to others.
• Never silently swallow errors. If a step can't complete and can't be auto-fixed, STOP and report.
• The user's single command IS authorization for the full pipeline — up to the Phase 2 approval gate.