gmickel/flow-next

Latest recorded source activity: October 25, 2026 at 19:25

SkillsMP catalog refreshed: November 2, 2026 at 18:02

skills collected: 60

GitHub stars: 713
GitHub forks: 62

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/gmickel/flow-next.

Repository README

Repository README source: README.md

Read the source README

Expand full README

<div align="center"> # Flow-Next [![GitHub stars](https://img.shields.io/github/stars/gmickel/flow-next?style=flat&logo=github&label=Stars&color=2f6f5f)](https://github.com/gmickel/flow-next/stargazers) [![CI](https://img.shields.io/github/actions/workflow/status/gmickel/flow-next/test-flow-next.yml?branch=main&label=CI%20%C2%B7%203%20OS)](https://github.com/gmickel/flow-next/actions/workflows/test-flow-next.yml) [![Latest release](https://img.shields.io/github/v/release/gmickel/flow-next?label=Release&color=green)](https://github.com/gmickel/flow-next/releases/latest) [![Mentioned in Awesome](https://awesome.re/mentioned-badge.svg)](https://github.com/ithiria894/awesome-claude-code-workflows) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) ### Faster than your agent alone. And better. **Agents generate. Flow-Next proves.** </div> Flow-Next is a workflow plugin for your coding agent. Hand it a bug, an idea, a ticket or a slow page, and it takes the work all the way to a pull request. It picks the route that kind of work needs, builds the change, gets it reviewed by another model family when the risk calls for it, and hands you something you can check instead of something you have to trust. It's also fast now. On the same model, the working change comes back in about the time your agent takes on its own, often less, and a large feature in about half the time. The result is better than the plain agent's before any review runs, and review and live QA widen that gap. | You say | What Flow-Next does | |---|---| | "This fails: `<pasted stack trace>`" | Turns the failure into a failing test, fixes the cause, and shows you the test going from red to green. | | "Add passwordless login" (or the conversation you just had about it) | Writes a spec with numbered acceptance criteria, builds it, has it reviewed, and opens a PR that maps every change to a criterion when you ask for one. | | "The /reports page takes four seconds, it should take under one" | Measures the real page before touching anything. The before-and-after numbers are the evidence. | | "Extract the pricing rules into their own module" | Pins the current behaviour with a characterization test first, so the refactor has to keep it. | | "Work ticket WOR-17" | Reads the issue with the access you already have and routes on what it says. | | "Why does the parser reject empty headers?" | Answers from git history and the project's decision memory, with citations. Writes nothing. | | `/flow-next:flow --auto` | The same thing with nobody watching. It never stops to ask, keeps fixing until the reviewer signs off, and writes every call it made on your behalf into the PR. Add `--until=merge` and it also watches CI and review threads and merges the PR when your checks allow it. | Every stage prints `ran`, `skipped(<reason>)` or `failed(<reason>)`, so you can see what happened and what didn't. The model that wrote a diff never reviews it. Specs, decisions, task state and receipts live under `.flow/` in your repository and stay readable if you stop using Flow-Next. `flow --explain <anything>` shows the route it would take, and why, without running it. It runs on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, OpenCode and Meta Muse Code. > 📖 **[Documentation: flow-next.dev](https://flow-next.dev)** · 💬 **[Discord](https://discord.gg/f3DYq8AAm5)** --- ## How much faster, and how much better I measured this over more than 170 full end-to-end runs against plain Claude Code on the same model, each case run several times. Hidden tests the agent never sees check every result, and a blind judge scores the handoff. Speed is time to the working change, before any review or QA. | Task | Speed on the work | Quality | What the quality stages did | |---|---|---|---| | Large feature | **up to 1.9x** faster | **+25%** | Plain Claude Code shipped a data-integrity bug in every run. Flow-Next's reviewers caught it every time, before the pull request. | | Held-out large feature (Rust) | **1.2x** faster | **+48%** | Four real bugs fixed, including a race condition. Flow-Next passed every hidden test; plain Claude Code failed one run in three. | | Hard bug | **about 2x** faster | **+9%** | Found the real cause and fixed it there, instead of loosening the flaky test. | | Simple bug | **1.2x** faster | **+10%** | No review needed. The gain comes from how it works: a failing test first, a fix at the cause, then a check that it works for the user. | | Small feature | **1.1-1.3x** faster | **+8%** | The reviewer caught a setup check the new option broke. Fixed before handoff. | Unattended, with `--until=merge`, a large feature went from spec to a merged pull request with nobody watching and no stops, in about half the time plain Claude Code took to build it. The [evidence page](https://flow-next.dev/project/evidence/) has the method and the rest of the numbers. --- ## Why this exists Writing the code got cheap. Everything around it didn't: pinning down what was actually asked, keeping the build aligned with it, checking the result, and explaining the diff to whoever reviews it. That work is where agent-written code quietly goes wrong, and it's the part I wanted to make repeatable. So the spec lives in `.flow/specs/<id>.md` instead of a chat that scrolls away. The build reads it before it touches code. When the risk calls for it, a model from another family checks the change, because a model reviewing its own work shares its own blind spots. And the PR shows which criterion each change satisfies and what proves it. It can't promise that the codebase stays easy to maintain. That still takes people who care about it. --- ## Install  <table> <tr> <td><strong>Claude Code</strong></td> <td><strong>OpenAI Codex</strong></td> <td><strong>Factory Droid</strong></td> </tr> <tr> <td> ```bash /plugin marketplace add \ https://github.com/gmickel/flow-next /plugin install flow-next /reload-plugins /flow-next:setup ``` </td> <td> ```bash git clone https://github.com/gmickel/flow-next.git cd flow-next ./scripts/install-codex.sh flow-next # For another Codex home (any path you like): # CODEX_HOME="$HOME/.codex-work" ./scripts/install-codex.sh # Run once per home. # then, in your project's Codex conversation: $flow-next-setup ``` </td> <td> ```bash droid plugin marketplace add \ https://github.com/gmickel/flow-next # /plugins → install flow-next ``` </td> </tr> </table> Use installation commands in your terminal or the host's plugin interface as shown above. Workflow invocations belong in the agent conversation. Codex uses `$flow-next-<name>`; OpenCode uses `/flow-next-<name>`; the other hosts accept `/flow-next:<name>` (Cursor also accepts the hyphen form). **Cursor, Grok Build, OpenCode, or Muse Code?** [Install](https://flow-next.dev/install/) has the current steps per host, including the Cursor team-marketplace import and Claude Code managed settings for an organisation. Codex installs are per home; set `CODEX_HOME` when you use more than one. ## Start one change 1. Install for your host with the block above, then run `/flow-next:setup` in a project (Codex: `$flow-next-setup`). Setup writes the agent instruction snippet and asks once which reviewer you want. 2. Tell it what you have: `/flow-next:flow <anything>`. A pasted error, an idea, a spec id, a branch or a ticket all work. Flow picks the smallest route that does the job, runs it, and stops at the next decision that's yours. For an idea too big to write down in one go, the optional `/flow-next:chart` stage comes first. 3. Read what it hands back. The stage lines say what ran and what was skipped and why. Say "open the PR" when you want one; its body maps each change to the acceptance criterion it satisfies. [Your first 30 minutes](https://flow-next.dev/first-30-minutes/) walks through the same three steps on a two-file Python example, review setup and all. You need your agent, Python 3.11+ and the project's own tools; review and PR steps also use `jq` and `gh`. ## If you're an agent If you are an agent or bot operating Flow-Next on someone's project, this repository's `AGENTS.md` and `CLAUDE.md` are not for you; they are rules for changing Flow-Next itself. What you need: - Install for your host, then run `/flow-next:setup` once in the project. - Hand everything to `/flow-next:flow <what the person gave you>`, verbatim. Don't call plan, work or review yourself unless the person names one; Flow picks the route. `--explain` previews the route without running anything. - Attended, relay `Flow stopped at` and `Next` to your person. Decisions about what to build or whether to merge are theirs. - Unattended, use `--auto`; plain `flow` refuses under an autonomy marker. The last line is always `PILOT_VERDICT=<ADVANCED|NO_WORK|DEFERRED_TO_LAND|BLOCKED|NEEDS_HUMAN>`, and `NEEDS_HUMAN` means stop and show the reason. - Only specs the person marked ready run unattended, and a merge needs their consent in this session or `--until=merge`. [For agents](https://flow-next.dev/for-agents/) has the full contract: every verdict and what to do with it, the run forms, and the safety rules. ## Land a pull request `/flow-next:land <PR>` works one named PR to the finish: it resolves review feedback and CI failures, then squash merges it once you've authorized the merge. make-pr commits the finished spec and task statuses before it opens the PR, so the merge carries them to your base branch. Land checks every spec on the PR's branch and merges only when all of them are closed. Land takes one PR at a time. To land several, pick the open PRs whose branch carries a closed spec, and run land on each one with your merge authorization. It never sweeps the repository for PRs on its own. If you want a stricter bar before merging, set it in your instruction file, in branch protection, or with `land.mergeVerdictCommand`. The [troubleshooting guide](plugins/flow-next/docs/troubleshooting.md) covers landing and manual rebases, and the [upgrade notes](plugins/flow-next/docs/flowctl.md#landing-upgrade) cover major versions. ## Where to read more The full documentation is at [flow-next.dev](https://flow-next.dev). This repository keeps this page and the reference files the skills read while they run, under [`plugins/flow-next/docs/`](plugins/flow-next/docs/README.md). - [Introduction](https://flow-next.dev/introduction/): what each stage does, and what Flow-Next refuses to claim. - [Choosing your route](https://flow-next.dev/choosing-your-route/): which stages a bug, a feature, a refactor or a performance request gets, and why the direct route is the default. - [Evidence & evals](https://flow-next.dev/project/evidence/): the benchmark against a plain agent, the research behind verification, and our own evals, including the ones that killed a feature. - [Going autonomous](https://flow-next.dev/autonomy/going-autonomous/): `flow --auto`, `--until=merge`, the Decisions list and when a run stops. - [For teams](https://flow-next.dev/guides/for-teams/): the spec as the handover between product, engineering and the agent, plus the tracker bridge to Linear, GitHub, GitLab and Jira. - [Regulated environments](https://flow-next.dev/guides/regulated-environments/): opt-in committed development evidence (`evidence.persist`), spec approval by pull request (`spec.approval`) and the `flowctl trace` matrix, which feed your team's validation rather than replace it. - [Model routing](https://flow-next.dev/guides/model-routing/): send each job to the model or harness that fits it, from one block in your instruction file. - [Review backends](https://flow-next.dev/reference/review-backends/): Codex, Copilot, Cursor, Claude and host review, and why the reviewer must come from another family. - [Configuration](https://flow-next.dev/flowctl/configuration/): every `.flow/config.json` key, generated from the schema. - [Skills](https://flow-next.dev/skills/): every skill and how to call it, and the [CLI reference](https://flow-next.dev/flowctl/cli-reference/) for `flowctl`. - [Changelog](https://flow-next.dev/releases/changelog/): release highlights. [`CHANGELOG.md`](CHANGELOG.md) here is the full record. - [Discord](https://discord.gg/f3DYq8AAm5) for questions, and [`CONTRIBUTING.md`](CONTRIBUTING.md) for local development and the docs-only rule. ## Where it already runs The engineering methodology built on Flow-Next is coached and run in engineering organisations around the world: CAD and construction software, proptech, education. That covers modern monorepos, estates of a hundred microservices and 30-year-old legacy stacks, on GitHub Enterprise, GitLab and Jira. Teams running it report a 3x speed-up on average across the whole R&D organisation, from discovery to merged code, at a higher quality of output: more than 1,000 developers across a private-equity portfolio. An hour-long discovery interview typically produces 8 to 11 specs ready to build, with numbered acceptance criteria, boundaries and task breakdowns, and the edge cases come up in the interview instead of mid-sprint. Receipts, evidence and review gates give you the approval checkpoints and the trail back from each change to its requirement. The open-source side you can check for yourself: an outside contributor's correct `flowctl` patch in [PR #95](https://github.com/gmickel/flow-next/pull/95), a listing in [awesome-claude-code-workflows](https://github.com/ithiria894/awesome-claude-code-workflows) for plan-first workflows and receipt-based gating ([#96](https://github.com/gmickel/flow-next/issues/96)), and a [test matrix on three operating systems](https://github.com/gmickel/flow-next/actions) on every push, because people run it on all three. > *"I am enjoying your version of all these cool new plugins. So far yours has worked the best."* > [@patrickmichalina](https://github.com/gmickel/flow-next/issues/5#issuecomment-3734228766) > *"really enjoying this project, thanks for making it and making it public"* > [@possibilities](https://github.com/gmickel/flow-next/pull/95), external contributor > *"it’s been really useful in my workflow."* > [@raydocs](https://github.com/gmickel/flow-next/issues/4) ## License MIT. See [`LICENSE`](LICENSE). <div align="center"> Made by [Gordon Mickel](https://mickel.tech) · [@gmickel](https://twitter.com/gmickel) · [gordon@mickel.tech](mailto:gordon@mickel.tech) [![Author](https://img.shields.io/badge/Author-Gordon_Mickel-orange)](https://mickel.tech) [![Twitter](https://img.shields.io/badge/@gmickel-black?logo=x)](https://twitter.com/gmickel) [![Sponsor](https://img.shields.io/badge/Sponsor_this_project-❤-ea4aaa?style=for-the-badge)](https://github.com/sponsors/gmickel) </div>

Loading the repository README…

Skills in this repository

Software Developers Software Quality Assurance Analysts & Testers Technical Writers Computer Occupations, All Other

5 occupation categories · 22% classified

skill

occupation

description

updated

flow-next-make-pr

unclassified

Open a PR with a cognitive-aid body rendered from flow-next spec state via gh. Use whenever asked to make or open a PR in a flow-next repo.

2026-10-25

flow-next-make-pr

unclassified

Render a briefing from the aid artifact and open or update a PR via gh. Auto-detects the spec from the branch. Supports --draft, --ready, --base, --memory, --dry-run, --update, and mode:autonomous.

2026-10-25

flow-next-audit

unclassified

Audit .flow/memory/ entries against current code and keep, update, consolidate, replace, delete, or harden each. Use when asked to audit memory or graduate a recurring lesson into a gate.

2026-10-24

flow-next-capture

unclassified

Save the current conversation as a source-tagged flow-next spec, then offer review or editing. Use when asked to capture this as a spec.

2026-10-24

flow-next-features

unclassified

Seed or maintain the committed user-POV drive map at .flow/features/ so QA and drive reuse how a user reaches each feature.

2026-10-24

flow-next-memory-migrate

unclassified

Migrate legacy flat .flow/memory files to the categorized YAML schema. One-time ceremony. Use when asked to migrate flow memory.

2026-10-24

flow-next-audit

unclassified

Audit `.flow/memory/` entries against the current codebase and decide Keep / Update / Consolidate / Replace / Delete / Harden per entry. Triggers on /flow-next:audit, "audit memory", "review memory", "refresh learnings", "sweep stale memory", "consolidate…

2026-10-24

flow-next-capture

unclassified

Synthesize the current conversation context into a flow-next spec at `.flow/specs/<spec-id>.md` via `flowctl spec create --plan-file` — agent-native, source-tagged, with a saved-spec summary and editor follow-up. Triggers on /flow-next:capture, "capture…

2026-10-24

flow-next-features

unclassified

Seed or maintain the committed user-POV feature map at `.flow/features/` so QA and drive reuse how a user reaches each feature. Two state-resolved modes: no `.flow/features/` (or explicit init intent) seeds it; a present map maintains it. Triggers on…

2026-10-24

flow-next-memory-migrate

unclassified

Migrate legacy flat memory files (`.flow/memory/pitfalls.md`, `conventions.md`, `decisions.md`) into the categorized YAML schema. Triggers on /flow-next:memory-migrate, "migrate memory", "convert legacy memory", "lift pitfalls into categorized schema",…

2026-10-24

flow-next-spec-completion-review

unclassified

Verify that a spec's completed tasks fully implement the spec requirements. Use at spec completion before close.

2026-10-18

flow-next-work

unclassified

Execute a flow-next spec or task with workers, gates and commits. Run when the work command is typed or flow-next-flow routes here; plain requests to implement fn-N go to flow-next-flow.

2026-10-18

flow-next-spec-completion-review

unclassified

Spec completion review - verifies all spec tasks implement the spec requirements. Triggers on /flow-next:spec-completion-review.

2026-10-18

flow-next-work

unclassified

Execute a Flow spec or task systematically with git setup, task tracking, quality checks, and commit workflow. Run only by /flow-next:work or when flow-next-flow routes a spec here; any other request to implement, build or work on a spec, Flow-Next named or…

2026-10-18

flow-next-qa

unclassified

Live-app QA pass derived from the spec. Drives the running app, files P0/P1/P2 findings with evidence, emits a YES or NO qa_verdict receipt.

2026-10-17

flow-next-qa

unclassified

Live-app real-user QA pass derived from the spec. Drives the running app via flow-next-drive, derives scenarios from the spec's AC / R-IDs / boundaries, files structured P0/P1/P2 findings with evidence, and ends with a YES/NO ship verdict receipt. Consumes…

2026-10-17

flow-next-flow

unclassified

Use first in a Flow-Next repo for a spec id, change, bug, issue, slow code or metric, cleanup, design fork, dump to explain, repeated mistake, prompt change, what could break, what next. No quick asks

2026-10-16

flow-next-flow

unclassified

Use first in a project that uses Flow-Next for any request to implement, build, continue or deliver its specs, whatever delivery or test steps the request adds, unless the user names another skill or asks to work directly. Also for a spec or task id, an idea…

2026-10-16

flow-next-land

unclassified

Resolve feedback and CI for one named pull request, then merge when authorized and ready. Emits LAND_VERDICT. Use when asked to land a pull request.

2026-10-15

flow-next-land

unclassified

Resolve feedback and CI for one named pull request, then squash merge when currently authorized and ready. Emits LAND_VERDICT. Use when asked to land a pull request.

2026-10-15

flow-next-prime

unclassified

Assess codebase agent and production readiness. Classifies the project, verifies commands run, leads with a verdict and ranked next actions.

2026-10-15

flow-next-prime

unclassified

Comprehensive codebase assessment for agent and production readiness. Classifies the project (lifecycle, topology, size, stack, shape), scans 8 pillars, verifies commands actually run, checks GitHub settings. Leads with a verdict + ranked next-actions; fixes…

2026-10-15

flow-next-setup

unclassified

Install or refresh flowctl and project instructions for flow-next in this repo. Use when asked to set up flow-next.

2026-10-12

flow-next-setup

unclassified

Optional local install of flowctl CLI and CLAUDE.md/AGENTS.md instructions, plus a commented model-routing example proposed into the project instruction file. Use when user runs /flow-next:setup.

2026-10-12

flow-next-resolve-pr

unclassified

Resolve PR review feedback. Fetches unresolved threads, triages, fixes, replies and resolves via GraphQL. Use when asked to address review comments.

2026-10-12

flow-next-resolve-pr

unclassified

Resolve PR review feedback — fetch unresolved threads, triage, dispatch per-thread resolver agents, validate, commit, reply + resolve via GraphQL. Triggers on /flow-next:resolve-pr.

2026-10-12

flow-next-impl-review

unclassified

Carmack-level implementation review of changes via the configured backend. Use when asked to review code or a diff in a flow-next repo.

2026-10-10

flow-next-impl-review

unclassified

John Carmack-level implementation review via Codex, Copilot, Cursor, Claude or a host reviewer. Use when reviewing code changes, PRs, or implementations. Triggers on /flow-next:impl-review.

2026-10-10

flow-next-prospect

unclassified

Generate ranked new ideas grounded in the repo. Use when asked to brainstorm what to build; picking up existing specs or work goes to flow-next-flow.

2026-10-09

flow-next-refine

unclassified

Refine a spec or task before building: one Q&A interview, optionally focused by a scope lens, or a read-only research pass over external docs. Use to refine requirements or read up on a new library.

2026-10-09

flow-next-refine

unclassified

Refine a spec, task, or spec file before building - one question pass for the decisions that would change what gets built, optionally focused by a free-text --scope lens (business, technical, qa, ...), or a read-only research pass (--scope=research) that…

2026-10-09

flow-next-plan

unclassified

Plan a feature into a flow-next spec with tasks in .flow/. Use when asked to plan, spec out, or break down work (fn-N ids).

2026-10-07

flow-next-plan

unclassified

Create structured build plans from feature requests or Flow IDs. Use when planning features or designing implementation. Triggers on /flow-next:plan with text descriptions or Flow IDs (fn-1-add-oauth, fn-1-add-oauth.2, or legacy fn-1, fn-1.2, fn-1-xxx,…

2026-10-07

flow-next-plan-review

unclassified

Carmack-level review of a flow-next spec or plan via the configured backend. Use when asked to review a plan or spec.

2026-10-05

flow-next-plan-review

unclassified

Carmack-level plan review via Codex, Copilot, Cursor, Claude or a host reviewer. Use when reviewing Flow specs or design docs. Triggers on /flow-next:plan-review.

2026-10-05

flow-next-tracker-sync

unclassified

Project a flow-next spec to a tracker issue (Linear, GitHub, GitLab, Jira) and reconcile two-way. Use when asked to sync to a tracker. NOT plan-sync.

2026-10-05

flow-next-tracker-sync

unclassified

Project a flow-next spec to Linear, GitHub, GitLab, or Jira and reconcile body, status, and comments. Use for tracker discovery, linking, create-first, push, pull, reconcile, comment, or unlink. Not /flow-next:sync, which is plan-sync.

2026-10-05

flow-next

Software Developers

Manage .flow/ tasks and specs. Use for show or list tasks, task status, what is ready, show fn-N. NOT for planning or executing (use the plan and work skills).

2026-10-05

flow-next

Software Developers

Manage .flow/ tasks and specs. Triggers: 'show me my tasks', 'list specs', 'what tasks are there', 'add a task', 'create task', 'what's ready', 'task status', 'show fn-1-add-oauth'. NOT for /flow-next:plan or /flow-next:work.

2026-10-05

flow-next-map

unclassified

Build a semantic feature index of the repo via clawpatch map (opt-in). Use when asked to map the repo.

2026-10-04

Showing 40 of 60 collected skills.