flow-state-dev

Create a new persistence store adapter package implementing all StoreRegistry interfaces. Produces a complete package with factory, individual stores, schema initialization, and tests.

Add a new page to the flow-state-dev documentation site (Docusaurus). Handles frontmatter, sidebar placement, content structure, and cross-linking.

Create a new flow definition with actions, scopes, resources, and capabilities. Produces the flow file, action blocks, and server registration.

Create a new block (handler, generator, utility, or router) following project conventions. Produces the block file, exports, and a matching test file.

Create a Linear issue for work already done (or in progress), check out a fix/ branch, commit the changes, and open a PR. For quick logging and shipping of on-the-fly work.

Create a new composable pattern — a multi-block sequencer composition that solves a recurring agentic architecture problem. Produces the pattern factory, internal blocks, tests, and documentation.

Pull a Linear issue, deeply research implementation approaches using web sources and codebase patterns, validate with multiple agents, then publish the spec as a versioned doc at docs/specs/<ISSUE-ID>.md opened as a spec PR for automated review and mirrored to the Linear issue (repo and Linear kept in sync).

Debug flow execution by running flows via the CLI, analyzing NDJSON traces and stderr logs, isolating failing blocks, and diagnosing root causes.

Disciplined diagnosis loop for hard bugs and performance regressions in the @flow-state-dev repo. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression. For flow execution failures specifically, prefer `fsd:debug-flow`.

Use when the user asks to dispatch, kick off, run remotely, or orchestrate work on one or more Linear issues — routes each issue to the right cloud Claude task (`fsd:create-spec` or `fsd:implement-issue`) based on its Linear state. Trigger phrases include "dispatch FIX-123", "kick off work on", "run create-spec remotely for", "orchestrate these issues".

Reflect on a completed, reviewed, or reworked change, extract the transferable lessons (not project trivia), and propose best-practice updates. Use after a PR was reworked or heavily reviewed, after a hard bug, or after a design you reversed — especially to learn from your OWN work being changed. Part of the self-testing-and-improving loop. Gates hard against best-practice bloat; writes to docs/contributing/best-practices.md only after user review.

Use when implementing a Linear issue. Fetches the issue and spec, creates a fix branch, auto-routes by Linear category (Bug vs Feature/Enhancement) to the right implementation discipline, dispatches sub-agents for complex work, runs a comprehensive review, opens a PR, and then stays on the PR — acknowledging new review comments with an eyes reaction and responding to every code-related comment with either a fix or a justification. Handles "Fix bug for FIX-N" and "Implement FEAT-N" the same way — the routing happens inside.

Find deepening opportunities in the @flow-state-dev repo, informed by FSD's existing domain vocabulary (block, generator, sequencer, router, pattern, capability, scope, item) and authority hierarchy (docs/architecture > docs/contributing/best-practices.md > AGENTS.md). Use when the user wants to improve architecture, find refactoring opportunities, consolidate shallow blocks or thin handlers, or make a package more testable and AI-navigable. Respects existing best practices (BP-001–BP-039) — suggestions that would contradict a BP should explicitly justify revisiting it.

Review Linear issues and propose prioritization changes, surface missing or stale tasks, and sequence work for parallel agent execution with human review gates.

Identify unblocked Linear tasks based on what's on main and in open PRs, prioritize up to 8 for today, clean stale todos, and generate a work plan for each as a file in agents/todos/.

Use when the user wants to figure out which Linear issues to dispatch right now — picks spec-ready and implement-ready issues respecting open-PR capacity, overlap, and priority. Trigger phrases include "what should we dispatch", "plan the next batch", "what's ready to go", "kick off some work", "pick today's dispatches". User-provided focus arguments (e.g. "focus on streaming") override priority order.

Build a throwaway prototype to flesh out an FSD design — either a runnable flow harness in apps/kitchen-sink for block/pattern/capability/state-machine questions, or several radically different UI variants on a single route for devtool or renderer questions. Use when the user wants to prototype, sanity-check a block shape, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".

Log an issue to Linear and immediately start fixing it. Handles duplicate detection, ticket creation, implementation, quality review via sub-agents, and Linear status updates — only pausing for user review before committing.

Use when you want a retrospective re-examination of a branch, PR, a Linear issue's attached spec, or a named feature in the @flow-state-dev repo — to question whether the solution was (or will be) the right approach, whether it's overbuilt or carries YAGNI/speculative surface, what the 80/20 version would be, and whether building it revealed a simpler path. Read-only; produces a scannable findings table, no edits or tickets. Keywords: bloat, overbuilt, over-engineered, too much code, premature abstraction, YAGNI, 80/20, was this the best approach, cut scope, review spec before building, FIX-.

Test-driven development for FSD blocks, patterns, capabilities, and flows using a strict red-green-refactor loop with vertical (tracer-bullet) slices. Use when building a new block / pattern / capability / flow, fixing a bug, or any time the user mentions "red-green-refactor", "TDD", "tracer bullet", or "test-first".

Verify a trading-desk analysis change by running the real analyze pipeline headlessly and reading a machine-readable RunSummary — no browser, no custom harness. Use after changing desk analysis logic (a block, generator, orchestration step, scoring math, prompt, capability) when you need to confirm the real path produced a decision, not just that unit tests pass. Drives raw `fsdev run` for analyze + the zero-model runSummary read action.

Write or update tests for blocks and patterns following project vitest conventions. Covers mock context setup, generator mocking, state testing, and sequencer composition verification.

Tell the agent to zoom out and give a higher-level map of an unfamiliar area of the @flow-state-dev codebase, named in FSD vocabulary. Use when you've just landed in an area and want the lay of the land before touching anything.