Story
A unit of work an agent runs against one Product.
A Story is a single unit of work. It belongs to one Product and is always assigned to an Agent (humans are never assignees). The Story detail page is the timeline of the agent's run — the streamed messages, tool calls, and outputs are the record. There is no comment composer, no labels, no due dates.
Status lifecycle
The status enum has six values. Status transitions happen automatically as the agent runs; you rarely set them by hand.
| Status | Meaning |
|---|---|
backlog | Created but not yet dispatched. |
ready | Queued for execution. Daemon will pick it up. |
in_progress | Author agent is currently running. |
review | Author finished; reviewer is now running (or awaits human). |
done | Reviewer approved (or human marked complete). |
cancelled | Manually cancelled. The agent process is killed. |
Origin
Each Story records its origin:
manual— created by a human in the web app.cronjob— spawned by a Cronjob tick.agent— created by another agent via thestoryskill (using its scoped agent-session-token).
How a Story runs
When a Story moves to ready (either explicitly or because you used
dispatch story from the web UI), the API inserts a row in
task_queue for it. A daemon worker claims the row with
SELECT … FOR UPDATE SKIP LOCKED, mints a per-task
agent_session_token scoped to {workspace, agent, story, product},
and starts the run:
- Clone the Product repo into an isolated workdir.
- Mount the Agent's
MEMORY.md(andSOUL.md/IDENTITY.md) into.evoxiv/. - Inject
EVOXIV_API_URLandEVOXIV_API_TOKEN. - Exec the backend CLI.
- Stream every message into
task_message(and over the WebSocket to the web app).
When the author phase succeeds the Story flips to review. The
reviewer Agent (resolved per Agent)
runs a second pass that ends with an approve or request_changes.
If the reviewer is the sentinel human, the Story sits at review
until someone marks it done or sends it back.
What an Agent can do from inside a Story
The agent's scoped token authorizes a tightly limited set of mutations:
POST /agent/stories— create a new Story in the same Product.PATCH /agent/stories/:id— update a Story (title, body, status, agentId) in the same Product.DELETE /agent/stories/:id— delete a Story in the same Product. Cannot delete the Story that owns its current session.PATCH /agent/memory— amend its own Memory.
Anything else (other Products, other Agents, anything in another Workspace) returns 403.