What is run-state-management?

A file-based system for recording the state and progress of long-running development workflows. It keeps phase activity and the next action so work can resume after a session ends.

Use it to create workflow runs, record phase changes, track completion, and resume commands such as starting an issue, debugging, reviewing, or releasing.

It prevents unfinished work from being lost when a conversation or coding session stops.

run-state-management — Skill for Claude Code by synaptiai

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent

npx skills add synaptiai/synapti-marketplace --skill run-state-management

Clone the repo

git clone --depth 1 https://github.com/synaptiai/synapti-marketplace

Made for: Claude Code.

Or install flow, the plugin that ships this one along with the rest of its 32 skills, 21 commands, 9 agents.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/skills/synaptiai/synapti-marketplace/run-state-management/github.svg)](https://agentmods.dev/skills/synaptiai/synapti-marketplace/run-state-management)

Your own site

<a href="https://agentmods.dev/skills/synaptiai/synapti-marketplace/run-state-management"><img src="https://agentmods.dev/badge/skills/synaptiai/synapti-marketplace/run-state-management/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/skills/synaptiai/synapti-marketplace/run-state-management"><img src="https://agentmods.dev/badge/skills/synaptiai/synapti-marketplace/run-state-management.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 151 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.

When invoked 1,287 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00151	$0.01287
Opus 5	$0.00076	$0.00643
Sonnet 5	$0.00030	$0.00257
Haiku 4.5	$0.00015	$0.00129

Measured yesterday against content hash 9f6f162776ec, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-11, from the pricing page.

Security

Grade A, and why

run-state-management scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

plugins/flow/skills/run-state-management/SKILL.md · 57 lines

How it starts

The opening of the file, as written. The whole thing — 57 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Run State Management

Contract

Iron law: no phase transition without an activity write — state.completed_activities[] is the source of truth for /flow:resume, and a missing activity makes resume skip ahead and lose work. Invoked when FLOW_RUN_STATE=create (gated by flow.runtime.enabled) by /flow:start, /flow:debug, /flow:address, /flow:review, /flow:merge, /flow:release at command entry (create), at every phase boundary (activity), and at completion (terminal transition); /flow:pr appends activities to the active start-issue run; /flow:resume reads its output. Returns .flow/runs/<id>/run.yaml, activities/<NNN>-<name>.yaml, events.jsonl, and a workflow-run journal artifact. Permitted skips: only when flow.runtime.enabled is false — then nothing under .flow/ is written.

Inputs

The invoking command MUST pass:

Workflow id — start-issue | debug | address-pr | review-pr | merge-pr | release (matches plugins/flow/workflows/<id>.workflow.yaml).
Run id — <ISO-8601-compact-timestamp>-<target-slug>, e.g. 2026-05-20T143000Z-issue-42.
Context — repo, branch, issue/pr number, linked journal path, linked goal id (or null).
Phase — initial phase id (preflight at creation; the workflow's phase order thereafter).

Outputs

.flow/runs/<id>/run.yaml — FlowRun conforming to schemas/v1/run.schema.json.
.flow/runs/<id>/activities/<NNN>-<name>.yaml — one FlowActivity per phase boundary, schemas/v1/activity.schema.json.
.flow/runs/<id>/events.jsonl — line-per-event ledger.
workflow-run artifact in the linked decision journal (bin/journal-record.sh --type workflow-run), updated with the final status at the terminal transition.

Exact document shapes and the per-workflow phase-order table: references/run-state-templates.md.

Workflow

Create the FlowRun at command entry: write run.yaml (state.status: active, current_phase = initial phase, completed_activities: [], events: [run_started]) by direct file write — race-free because the directory does not yet exist — and emit the workflow-run journal artifact with status=active.
Record an activity at every phase boundary (and significant sub-steps): compose the FlowActivity YAML to a temp file, then bin/flow-record-activity.sh --run-id <id> --activity-file <path>. The helper assigns the sequence number, validates against the schema, writes atomically (O_NOFOLLOW + flock + tempfile+rename), and appends to events.jsonl.
Update state.current_* after each activity: advance current_phase at a boundary, set current_activity, append the recorded id to completed_activities[]. Read-merge-write through bin/_journal_atomic.py (acquire_lock(run.yaml.lock) + atomic write) — never a bare overwrite.
Terminal transition when the command ends: state.status → completed (verdict PASS / action succeeded), blocked with blocked_reason (verdict FAIL or session ended mid-workflow), failed, or cancelled; then re-emit the workflow-run artifact with the final status.
SessionEnd (hooks/scripts/session-end-state.sh, not this skill): appends a session_end event to each active run's events.jsonl and prints flow: N active FlowRun(s) persisted — it does not mutate run.yaml; status changes are the user's decision via /flow:resume.

Read the full file on GitHub · 57 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday Changed · -138 lines 9f6f162776ec
8d ago First seen · 195 lines · 151 tokens per session scan A 600a606a3c8a

Subscribe to this mod's changes

run-state-management is a skill published in the GitHub repository synaptiai/synapti-marketplace (6 stars, last pushed yesterday), licensed Apache-2.0. It adds 151 tokens to every session and 1,287 once invoked, about $0.0008 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-03.

Project management agentic-design-patterns agentic-development agentic-workflow ai-developer-tools ai-first claude-code-plugin

step4-archive-spec

Archive a completed spec — moves it to specs-archived and blocks agent access.

CaptainMe-AI/lead-dev-os · 23 tokens

plan-roadmap

Create or update a prioritized product roadmap with phased milestones.

CaptainMe-AI/lead-dev-os · 15 tokens

x-dev

A development workflow for completing tasks from a task folder. It follows the task's README and checklist, implements work in dependency order, and records verification evidence.

KtKID/x-dev-pipeline · 74 tokens

x-req

A requirements planner that turns a confirmed request into a ready-to-build task package. It assigns a risk level from Q0 to Q3, where higher levels cover changes such as permissions, public interfaces, data migrations, or concurrency.

KtKID/x-dev-pipeline · 41 tokens

pocket-closing

Terminal pocket stage. User invokes after pocket-development's phase-level pass writes verdicts. Reconciles reviews against log.json, gates on REVIEWFAIL/REVIEWBLOCKED, advances REVIEW→DONE, runs log close, and emits a closeout summary. Trigger on "pocket-closing", "close the plan", "close out", "finalize plan", or…

rfxlamia/pocketto · 92 tokens

product-manager

Use when writing user stories or acceptance criteria, defining product requirements, prioritising a feature backlog, creating a product roadmap, analysing product metrics, facilitating discovery for a new feature, evaluating trade-offs between product directions, or any task that requires deciding what to build and…

pranav8494/team-of-agents · 57 tokens