agenticair/flow-state

Flow State hub. Use when the user types "flow" with or without a verb (list, help, status, settings, connect, setup, size, next, run, update, or a stage name such as spec, stories, design, build, review, ship, retro), asks what to do next, how to start a feature or ticket, or which stage a project is in. Welcomes a first-time user, orients, sizes the ask and records the size in the state, and dispatches to the stage skills. Writes only configuration, and only after the user confirms.

Shared runtime for Flow State. Holds the agent role definitions, conventions, templates, deterministic scripts and the config schema that the flow-* stage skills read by relative path. Never invoke this skill directly; it does nothing on its own.

Stage review of Flow State (type "flow review"). Reviews a story's finished diff, a branch, or a pull request with the judge agent plus the host tool's native review and any project lenses, grades every finding in the parent session, and routes each to patch, defer or spec. Use after flow-build delivers, when the user says review this, or before opening a pull request.

Stage setup of Flow State (type "flow setup"). Sets a repository up once, and refreshes it later with "flow setup refresh". Discovers the repo's own rules and how it ships, asks only what it cannot discover, writes flow.config.json, .agent/STATE.md and a verified block in AGENTS.md or CLAUDE.md, registers review lenses and integrations. Never rewrites existing documentation. ("flow adopt" is accepted as an alias until 0.7.)

Stage spec of Flow State (type "flow spec"). Turns an intent, a ticket or a brief into a Flow State spec and takes it to the freeze gate. Use when the flow hub routes epic-sized work here, or the user asks to spec, define, or freeze a feature. Investigates the repository before asking questions, tags every decision with its provenance, scores the draft with a script, has a fresh reviewer check it, then presents at most fifteen lines and stops until the human says freeze.

Stage stories of Flow State (type "flow stories"). Turns a frozen Flow State spec into a slice table and one story file per slice, scored and ordered so every batch delivers something observable, then stops at the go gate where the human names the story that starts. Use after flow-spec has frozen a spec, or when the user asks to break a spec into stories or slices.