Workflow

Every Joy item moves through one small, fixed set of statuses. There is exactly one workflow per project: it is not templated, selectable, or importable. You scale strictness by tightening individual transitions with gates, not by adding statuses.

The states

• new: the item exists or was proposed, but is not yet approved for work.
• open: approved and triaged into the backlog, ready to pick up.
• in-progress: being worked on.
• review: work done, awaiting acceptance.
• closed: accepted and finished.
• deferred: deliberately set aside; reachable from any active state, because there can always be a reason to put something on hold.

blocked is not a manual state; it is computed automatically from dependencies.

The verbs

Each transition has a one-word shortcut:

joy approve IT-0001   # new -> open
joy start   IT-0001   # new or open -> in-progress
joy submit  IT-0001   # in-progress -> review
joy close   IT-0001   # review -> closed
joy rework  IT-0001   # review -> in-progress
joy defer   IT-0001   # any active state -> deferred
joy reopen  IT-0001   # closed or deferred -> open

Gates

By default every transition is open and Joy only warns, never blocks. When you need more control, you tighten individual transitions with gates. The workflow itself stays the same.

start works directly from new, so the open status is optional in everyday use. It comes into play with a triage gate on new -> open: items are then approved into the backlog with joy approve before work starts. A gate with allow_ai: false on new -> open is a handy way to keep AI-created items in new until a human approves them.

Solo: no gates

Every transition is open; start goes straight from new.

Team: triage and acceptance gates

A triage gate on new -> open (with allow_ai: false for AI-created items) routes proposals through human approval; an acceptance gate on review -> closed lets only leads close work, optionally requiring green CI.

Same workflow, more strictness: nothing was added to the state model, two transitions were tightened. See Capabilities and gates for how gates are configured.