v0.x This is the released v0.x line — the version that ships in release tarballs and is dogfooded in this repository. The v1.0 rebuild is documented separately in the v1.x preview.

State Machines

Primitives with lifecycle (WorkItem, DecisionRecord, Scope, Discussion) are governed by state machines. processkit ships default machines that projects can override.

WorkItem default

backlog → in-progress → review → done
            ↓      ↑
          blocked ↑
            ↓      ↑
          backlog ←
(any state) → cancelled (terminal)

Source: src/context/state-machines/workitem.yaml .

DecisionRecord default

proposed → accepted → superseded (terminal)
    ↓
  rejected (terminal)

Source: src/context/state-machines/decisionrecord.yaml .

Overriding a default

Projects override a default by placing a same-named file in their own context/state-machines/ directory. The index MCP server (v0.3.0) and any validator prefer the project file over the processkit default.

Overrides must:

  • Keep the same initial state (or migrate existing data).
  • Not remove states that existing entities are currently in.
  • Add new transitions only from states that already exist.

See the state-machine-management skill for details.

Multiple machines for one kind

You can ship multiple state machines for the same primitive kind by using distinct names. Entities opt into a specific machine via spec.state_machine: <name>. Useful when the same kind has fundamentally different lifecycles (e.g. a WorkItem with bug-lifecycle vs story-lifecycle).