Quick Start

Start a bugfix workflow and your agent loses the ability to edit files. It can only read. When it proves it understands the bug, editing unlocks.

/statewright start bugfix

Planning Phase

Only read-only tools are available: Read, Grep, Glob. The agent reads code, identifies the bug, builds understanding. If it tries to call Edit, the MCP gateway blocks the call:

Tool 'Edit' is not available in the 'planning' phase.
Allowed tools: Read, Grep, Glob.

No ambiguity. The agent adjusts and reads more. When ready, it transitions by calling the MCP tool:

// Agent calls: statewright_transition
{ "event": "READY", "data": { "rationale": "Bug identified in get_db_url()" } }

Implementing Phase

Now Edit and Write unlock. The agent applies the fix. Edit size is capped at 20 lines per operation and the workflow limits this state to 3 files (as defined in the workflow, not system defaults). When done:

{ "event": "DONE", "data": { "rationale": "Applied os.environ.get() pattern" } }

Testing Phase

Bash becomes available, restricted to test commands. The agent runs tests.

If tests pass:

{ "event": "PASS", "data": { "rationale": "All 4 tests pass" } }

Workflow completes. Enforcement deactivates. All tools available again.

If tests fail, the agent transitions back to implementing — it doesn't get to skip ahead:

{ "event": "FAIL", "data": { "rationale": "test_db_url_from_env failed — still reading hardcoded value" } }

Back to implementing. Fix the bug properly, then test again. The loop is the point.

View the Run

Go to statewright.ai/runs to see every transition with timestamps, rationale, and tool calls per phase. The entire run is an audit trail. And yes, you can see what the agent was thinking at each transition... the rationale strings are stored, not just the event names.

For the theory behind all this, see Core Concepts. To build your own workflow, Create Your Own.