stackmapstackmap
Install

DocsDiagram kinds

Lifecycle

The states of one thing and the moves between them: a job, an order, a deployment.

States are nodes with state types, not component types. A start state gets the initial marker, a success or failure with no way out is drawn as an end state, and a retry is a return edge back to the state it retries.

An example

The skill’s own example, job.lifecycle.json, laid out by stackmap.

file:///…/.stackmap/job/diagram.html
job.lifecycle.json75 lines
{  "kind": "lifecycle",  "title": "Export job lifecycle",  "subtitle": "States of one export job",  "lanes": [    { "id": "main", "label": "Job phases" },    { "id": "waiting", "label": "Interruptions" },    { "id": "ends", "label": "Terminal exits" }  ],  "nodes": [    {      "id": "queued",      "type": "start",      "lane": "main",      "card": { "title": "Queued", "subtitle": "Request accepted" }    },    {      "id": "running",      "type": "active",      "lane": "main",      "card": { "title": "Running", "subtitle": "Rendering rows" }    },    {      "id": "done",      "type": "success",      "lane": "main",      "card": { "title": "Done", "subtitle": "File ready" }    },    {      "id": "throttled",      "type": "waiting",      "lane": "waiting",      "card": {        "title": "Throttled",        "subtitle": "Rate limit",        "tag": "backoff"      }    },    {      "id": "failed",      "type": "failure",      "lane": "ends",      "card": { "title": "Failed", "subtitle": "Retries exhausted" }    }  ],  "edges": [    {      "id": "start",      "from": "queued",      "to": "running",      "tone": "main"    },    { "id": "finish", "from": "running", "to": "done", "tone": "main" },    {      "id": "limit",      "from": "running",      "to": "throttled",      "label": "429"    },    {      "id": "resume",      "from": "throttled",      "to": "running",      "label": "retry",      "kind": "return"    },    {      "id": "give-up",      "from": "throttled",      "to": "failed",      "label": "5 attempts",      "tone": "error"    }  ]}
Point at a node in the JSON, or at its card, to find the other.

Its parts

  • Seven state types

    Start, active, waiting, decision, success, failure, neutral.

  • Start marker

    Where the thing begins.

  • End states

    A double outline when nothing leaves.

  • Retries

    Return edges, dotted.

Rules

From the authoring contract the skill gives your agent. stackmap validate enforces the hard ones and names the fix.

  • States are nodes with the seven state types, not component types.
  • A start state gets the initial marker; a success or failure with no way out is drawn as an end state.
  • A retry is a return edge back to the state it retries.
  • Lanes are phases of attention (lifecycle phases, interruptions, terminal exits), and every node needs a lane.
  • Cards are compact: title, subtitle, brand and a short tag.

State types

TypeUse it for
StartWhere the thing begins (drawn with an initial marker)
ActiveWork in progress: building, executing, rolling back
WaitingPaused on something outside: approval, input, a timer
DecisionA check that sends the thing one way or another
SuccessA good end, or a good stop along the way
FailureAn error or a bad end
NeutralAnything else

Ask for one

Draw the lifecycle of an agent run: every state it can be in, and what moves it between them.

Your agent picks the kind that answers the question; naming it is the surest way to get it.

Examples

See lifecycle examples in the gallery