StateMachine

Legacy v1 state/transition graph entity. In the SmoothTiger/SmoothRiver v2 direction, processkit no longer presents StateMachine as a first-class shipped entity surface. State machines still exist as validation machinery used by MCP servers, but users should not model new workflow records as StateMachine entities.

ID prefix	SM (legacy v1)
State machine	none (meta-primitive)
MCP server	none
Skill	state-machine-management (legacy authoring guidance)

v2 replacement

Use the owning MCP server for lifecycle transitions. It loads the appropriate implementation contract and returns structured errors for invalid transitions. Project workflows should be expressed with WorkItems, Artifacts, Gates, and Bindings rather than new StateMachine records.

Fields

Required

Field	Type	Description
description	string	What this state machine governs
initial	string	Starting state for new entities
states	object	Map of state name → {description, transitions[]}

Optional

Field	Type	Description
terminal	string[]	States with no outgoing transitions

Transition fields (within each state)

Field	Type	Description
to	string	Target state
guard	string	Prose description of when this transition is allowed
on_enter	string	Side effect description when entering target state
required_role	string	Role required to make this transition

Default state machines shipped by processkit

Primitive	States
WorkItem	backlog → in-progress → review → done (+ blocked, cancelled)
DecisionRecord	proposed → accepted / rejected → superseded
Migration	pending → in-progress → applied / rejected
Scope	planned → active → completed / cancelled
Discussion	active → resolved / closed
Note	fleeting → insight / promoted / archived

Example — custom state machine

---
apiVersion: processkit.projectious.work/v1
kind: StateMachine
metadata:
  id: SM-20260411_0919-ClearRidge-rfc-lifecycle
  created: '2026-04-11T09:19:00Z'
spec:
  description: RFC lifecycle for architecture proposals.
  initial: draft
  terminal: [accepted, withdrawn]
  states:
    draft:
      description: Being written — not ready for review.
      transitions:
        - to: in-review
          guard: Author marks RFC ready.
    in-review:
      description: Open for comments from stakeholders.
      transitions:
        - to: accepted
          required_role: tech-lead
        - to: draft
          guard: Major revision needed.
        - to: withdrawn
          guard: Author withdraws.
    accepted:
      description: Accepted — implementation may proceed.
    withdrawn:
      description: RFC withdrawn by author.
---

Notes

• Legacy state machine definitions may exist in context/state-machines/ during v1 migration, but they are not first-class v2 entities.
• MCP servers load the state machine for a given kind and enforce valid transitions — invalid transition attempts return a structured error.
• For v2, change lifecycle behavior in the owning MCP server or a reviewed implementation contract, then migrate affected records explicitly. Do not create new StateMachine records.