CLI reference

The binary is kf. Every command except kf init looks for .works/ from the current directory upwards to the project root, so you can run it from the root or from any subdirectory.

kf init is the exception: it resolves its path argument against the current directory and does not search upwards. Running it inside a subdirectory of a project that is already initialised creates a second .works/, .kf/ and skills set there rather than finding the existing one.

Setting up and creating work

Driving the workflow

--force deliberately skips a gate; when re-archiving a work item in dones it also allows the archive snapshot to overwrite canonical docs that were edited. --skip-hooks skips the destination phase’s hook. --skip-specs touches no canonical doc during archive. Whenever --force or --skip-hooks actually skips something, the CLI writes a record into .kfw.json under bypasses[] and says so in its output. See gates.

Skill installation

Skills always live at project scope ({root}/.claude/skills, {root}/.agents/skills and so on). The kf CLI is the only thing installed globally, through npm link. kf init installs the skills during setup; kf install and kf uninstall work on the project root resolved from the nearest .works/ above the working directory. Neither writes anything into ~/.

Uninstall only removes skills. To take the CLI off PATH: npm rm -g @phuthuycoding/kanban-flow.

Error conventions

• Success exits 0. Bad input, a failed gate, a failed hook, a missing work item or an exception exits 1. The readable report goes to stdout; stderr carries only a short reason line. A CI step that keeps stderr and discards stdout captures the reason but none of the detail.
• The CLI never runs a migration, updates a database, deploys or publishes on its own.
• Hooks resolve in order: the project .kf/hooks, then the user’s ~/.kf/hooks, then the package hooks. The environment handed to a hook carries KFW_FEATURE, KFW_CONTEXT, KFW_FROM_STAGE, KFW_TO_STAGE, KFW_FEATURE_DIR, KFW_WORK_ROOT and KFW_APPROVAL.

Contexts

A context groups work items and their canonical docs by business domain: docs/requirement/{context}/, and the same under use-cases and testplan.

A project may declare which contexts exist, in .kf/config.json:

"contexts": ["auth", "billing", "catalog"]

Two things follow from that list, and nothing follows without it:

• The first entry is the default context for kf new without --context. There is no separate default field to keep in step with the list. defaultContext is still read for projects created before contexts existed, and is ignored once a list is declared.
• kf new refuses a context that is not on the list, naming the nearest declared spelling. A name differing only in case is refused too, because accepting Auth beside auth is how a second docs tree appears on a case-sensitive filesystem.

A project with no contexts key is unrestricted. Re-running kf init there does not add the key, and neither does a project that has work items but no config file yet: a project counts as existing if it has either. kf init writes the list only for a genuinely new project, or when you answer its question on a terminal. The one behaviour that did change for an unrestricted project: kf new now reads the config on every path, so a malformed config fails loudly instead of only when --context was omitted.

kf contexts reports each in-use context with the spelling found on disk, not a lowercased one. Where an undeclared spelling differs from a declared one only by case, it says so instead of telling you to add it, because the config reader refuses that repeat: rename the work items, or change the declared entry. It never writes anything. When no list is declared it prints a brief for an agent to survey the repo and propose one, which a human then confirms and writes.