--- slug: "flow-next" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/gmickel/flow-next@main/README.md" repo: "https://github.com/gmickel/flow-next" source_file: "README.md" branch: "main" ---
# 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) [![Docs](https://img.shields.io/badge/Docs-πŸ“–-informational)](plugins/flow-next/docs/README.md) [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/f3DYq8AAm5) [![Sponsor](https://img.shields.io/badge/Sponsor-❀-ea4aaa)](https://github.com/sponsors/gmickel) ### Agents generate. flow-next proves. **AI coding agents that ship like engineers - not slot machines.** The workflow layer for AI coding agents: durable specs, re-anchored workers, adversarial reviews, receipts. Everything lives in your repo. Zero external dependencies. Uninstall: `rm -rf .flow/`. A real pipeline run: pilot plans the spec, cross-model plan review catches a gap and ships, the worker implements with tests, impl review ships, ending on the task receipt *Proof, not adjectives: a real recorded run - plan β†’ cross-model plan review (catches a missing guard, fix, SHIP) β†’ implement + tests β†’ impl review SHIP β†’ the receipt. Nothing staged; every frame is live output.* ℹ️ The recording drives each tick with `claude -p "…"` (Claude Code's non-interactive / headless mode) so the whole run captures unattended. In normal use you just type the prompt or `/flow-next:…` command in your interactive session β€” same pipeline, same gates. /flow-next:plan output β€” dependency-ordered tasks, cross-model review passed, key decisions documented *A real `/flow-next:plan` result - dependency-ordered tasks, cross-model review iterated to SHIP, key decisions documented.*
### 🌐 [Full Documentation Site β†’ flow-next.dev](https://flow-next.dev) > πŸ“– **[Doc index](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/README.md)** Β· πŸ‘₯ **[Teams guide](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/teams.md)** Β· πŸ’¬ **[Discord](https://discord.gg/f3DYq8AAm5)** --- ## Why this exists Agentic engineering compresses implementation from weeks to hours β€” and quietly removes every safety valve pre-agentic Agile relied on. The standups, the hallway clarification, the mid-flight course correction that used to *finish* a vague ticket over a two-week cycle: gone. When an agent can ship the task in one sitting, a rough ticket plus a chat scrollback is the whole work surface. That work surface fails predictably. Agents drift mid-task, forget requirements, overfit to recent context, and hand reviewers 10K-line diffs with no focus signal. The bottleneck didn't disappear β€” it moved upstream, to requirements, review, and verification. **The spec has to carry the weight.** Flow-Next fixes the operating model, not just the prompt. It turns rough intent into durable specs, specs into context-sized task graphs, task graphs into re-anchored worker runs, and implementation into reviewed PRs with receipts. Between idea and merge it defines **six named handover objects** β€” each reviewable on its own, verified by a *different* model, and frozen at handover. The artifact chain is not bureaucracy. **It is the conversation that would otherwise be missing.** ## What you get Flow-Next is an AI agent orchestration plugin: **28 agent-native skills** covering the full lifecycle β€” idea β†’ spec β†’ tasks β†’ review β†’ ship β†’ maintain β€” layered on a bundled pure-stdlib Python CLI (`flowctl`). The host agent is the intelligence; flowctl is the deterministic plumbing. No external services, no SaaS, no global config. | Tenet | What it means | |---|---| | **Spec-driven** | Intent survives the chat. The unit of work is the spec β€” not the ticket, not the transcript, not the PR title. One durable document at `.flow/specs/.md`, evolving through layers. | | **Context-fit planning** | Right-sized task slices. Specs decompose into dependency-ordered tasks, each sized to one fresh ~100k-token context window. | | **Re-anchored work** | Fresh context per task. Every worker subagent re-reads the spec, the task, and git state before touching code β€” no token bleed, no stale assumptions. | | **Adversarial gates** | Fix until SHIP. A *different* model (RepoPrompt / Codex / Copilot / Cursor) reviews every plan and every implementation. Different models make different mistakes β€” the disagreement surface is where the gaps live. | | **Receipts** | "Done" means there is proof. Commits, tests, review verdicts, and evidence recorded per task β€” never narration. | | **Multi-harness** | One workflow everywhere. First-class on Claude Code, OpenAI Codex, and Factory Droid; runs on Grok Build and Cursor; community OpenCode port. | | **Self-improving** | Compounds as you work. Memory, glossary, decision records, and strategy grow as side-effects of the workflow you already run β€” no manual "refresh" ceremony, ever. | And one tenet about *trust*: everything lives in your repo under `.flow/`. Specs, tasks, memory, receipts β€” all of it is yours, in git, code-reviewable. Uninstall is `rm -rf .flow/`. --- ## Quick start ### Install
Claude Code OpenAI Codex Factory Droid
```bash /plugin marketplace add \ https://github.com/gmickel/flow-next /plugin install flow-next /reload-plugins /flow-next:setup ``` ```bash git clone https://github.com/gmickel/flow-next.git cd flow-next ./scripts/install-codex.sh flow-next # then: /flow-next:setup ``` ```bash droid plugin marketplace add \ https://github.com/gmickel/flow-next # /plugins β†’ install flow-next ```
**Why a script for Codex?** Codex's plugin protocol only registers `skills` from `plugin.json` β€” not custom `.toml` agents or hooks. `install-codex.sh` merges all 22 agents + hooks into `~/.codex/config.toml`. Idempotent β€” safe to re-run. Full platform matrix + community ports in [`docs/platforms.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md). **Grok Build (xAI)?** It picks up the Claude Code install automatically - skills, commands, and multi-agent flows verified. Details + caveats in [`docs/platforms.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md#grok-build-claude-code-compatibility). ### The 5-command happy path ```bash /flow-next:capture # 1. Synthesize conversation β†’ .flow/specs/.md /flow-next:plan # 2. Break the spec into dependency-ordered tasks /flow-next:work # 3. Execute tasks in fresh-context worker subagents /flow-next:make-pr # 4. Render a cognitive-aid PR body (9 input streams) /flow-next:resolve-pr # 5. Fetch review threads β†’ triage β†’ resolve ``` That's the inner loop. Branch in (`/flow-next:prospect` for ranked candidates, `/flow-next:interview` for structured discovery), branch out (`/flow-next:pilot` + `/flow-next:land` for the autonomous assembly line, `/flow-next:ralph-init` for hardened overnight runs, `/flow-next:audit` for memory garbage collection). ### After every update **Plugin mode (Claude Code, the setup default for Claude-Code-only repos): nothing to do.** Nothing is copied into your repo β€” `flowctl` rides the plugin's `bin/` PATH injection, the agent guide is pulled live via `flowctl usage`, and the spec template resolves from the bundled copy. Plugin updates land silently; you never re-run setup for an update. **Copy mode (mixed-host repos β€” Codex/Cursor/Droid teammates, CI, plain terminals): update the plugin, then re-run `/flow-next:setup` in each project.** In copy mode two things live as **snapshot copies inside your repo's `.flow/`**, not live links to the plugin: the bundled **`flowctl` CLI** (`.flow/bin/`) and **`.flow/usage.md`** (the in-repo agent guide). A plugin update does **not** touch them - re-running setup refreshes the CLI, `usage.md`, the model-routing scaffold, and the spec template. It is idempotent; nothing is lost. Plan detects a known copy/plugin version mismatch before planning; direct invocation of other skills does not run a version preflight. See [Troubleshooting](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/troubleshooting.md). Setup asks the mode question once per repo (Claude Code only; other hosts are always copy mode) and stamps the choice; switching later is a consented setup re-run. Details: [platforms.md](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md). --- ## The pipeline is a menu, not a rail The 5-command path is the opinionated default - rails for your first week, not a prohibition on anything else. Every stage is a composable primitive: skip stages, reorder them, chain them in one sentence, prompt *into* any of them - and whichever subset you run, the same execution, evidence, and review contracts hold. (Directly answers [#28](https://github.com/gmickel/flow-next/issues/28) and [#91](https://github.com/gmickel/flow-next/issues/91).) **You never have to type a slash command or a `--flag`.** Every skill runs from plain language and every argument has a plain-language equivalent - "implement fn-12 on a new branch and review it with codex" *is* `/flow-next:work fn-12 --branch=new --review=codex`. The explicit forms below are the precise, copy-pasteable version. And the skills compose beyond the pipeline: research a competitor's pricing, then "capture a spec for it"; run a load test, then "spec the fixes the numbers point to" - the exploration is the input, the spec is the durable output. **Prototype first when the question needs it.** Capture's input was never meant to be a requirements document - it can be a conversation, a half-formed briefing package, a business-language BRD, an eval result, or a working prototype. Some questions ("how should this look?", "how should this behave?", "does this state model survive the awkward cases?") cannot be settled in prose, so build the thing badly on purpose and then *"capture a spec from this prototype - ignore the code quality, I want the intent and the requirements it demonstrates."* What happens to the prototype code is a separate call made at **plan** time against your architecture and standards: throwaway evidence, keep-the-presentation-layer, or implementation seed. Prototyping is the sharpest instance of a general move - **let something real answer the question, then capture the answer** - and the route should match the question: probe or load-test a performance complaint, reproduce a bug report as a failing test that becomes R1, run an eval for a model or prompt choice, bake off candidate approaches as one task each, research the outside world. Most of those run unattended, so the finding-out happens before anyone commits to a shape. See [Prototype-Driven Specs](https://flow-next.dev/strategy/prototype-driven-specs/) and the [cookbook](https://flow-next.dev/cookbook/#compose-beyond-the-pipeline). ```text Skip stages Tiny fix? plan + work, nothing else: /flow-next:plan "rename the config key" β†’ /flow-next:work fn-N One-shot chain "Plan fn-12, run plan-review until SHIP, work every task, then make-pr." One sentence, full pipeline. Prompt into steps "/flow-next:work fn-12 - keep the UI tasks yourself; delegate the API plumbing to codex" Reorder / re-run Interview again after planning; /flow-next:sync re-aligns tasks after implementation drift. Parallelize /flow-next:plan reports execution waves. /flow-next:work inspects the ready frontier, dispatches a safe subset in isolated workspaces when useful, joins it, then continues; otherwise it serializes. Route models flowctl config set review.backend codex Β· per-task review: pins Β· delegate:codex for implementation. ``` Skills are prompts executed by the host agent, not compiled code - if the variation you want isn't a parameter, describe it and the host builds the arrangement on the spot ([orchestration guide](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/orchestration.md)). Use the smallest sufficient workflow. Full recipe catalog: [flow-next.dev/cookbook](https://flow-next.dev/cookbook). --- ## How the flow works ```mermaid flowchart LR Idea([πŸ’‘ Idea]) --> P[/flow-next:prospect/] Idea --> C[/flow-next:capture/] P --> C P -.->|direct via promote| L[/flow-next:plan/] C --> L C --> I[/flow-next:interview/] I --> L L --> W[/flow-next:work/] W --> R[/flow-next:impl-review/] R -->|SHIP| Q[/flow-next:qa/] R -->|NEEDS_WORK| W Q -->|YES| Done([πŸš€ Ship]) Q -->|NO| W Done -.maintenance.-> A[/flow-next:audit/] A -.-> M[(.flow/memory/)] ``` > `/flow-next:qa` is an **opt-in** live-app QA stage (after work, before make-pr) β€” it drives the deployed app like a real user and only runs when there's a live deploy + a driver; with neither it surfaces the limitation rather than blocking. It **augments, never replaces** CI/staging/manual QA: the cheap first live pass that catches obvious runtime breakage before a human opens the PR. Run it by hand, or wire it into the autonomous loop as the optional `pipeline.qa` pilot stage (`flowctl config set pipeline.qa on`, default off) β€” `plan β†’ plan-review β†’ work β†’ qa β†’ make-pr`. The loop is spec-driven. Each step below maps to one skill; click through to flow-next.dev for the full page.
1. Capture or prospect a spec Either synthesize an existing conversation into a structured spec, or β€” when starting from scratch β€” generate ranked candidate ideas grounded in the repo. Both land in `.flow/specs/.md`. Capture **source-tags every acceptance criterion** as `[user]` / `[paraphrase]` / `[inferred]` and runs a mandatory read-back β€” you see exactly how much of the spec the agent invented before anything is written. ```bash /flow-next:capture # from a conversation /flow-next:prospect # from a focus hint (concept, path, constraint, volume) ``` β†’ [flow-next.dev/skills/capture](https://flow-next.dev/skills/capture) Β· [flow-next.dev/skills/prospect](https://flow-next.dev/skills/prospect)
2. Interview to refine Deep Q&A pass over a spec or task: lead-with-recommendation, confidence tiers, codebase-first investigation. Use it to flesh out an ambiguous spec before breaking it down. `--scope=business|technical|both` symmetrically narrows the pass β€” the same skill serves the PO filling the business layer and the tech lead filling the technical layer, on the same spec file. ```bash /flow-next:interview ``` β†’ [flow-next.dev/skills/interview](https://flow-next.dev/skills/interview)
3. Plan into dependency-ordered tasks Research the codebase via parallel scouts, then write the spec + tasks together. Tasks `fn-N.M` declare blockers, inherit context from the parent spec, and declare which acceptance criteria they satisfy (`satisfies: [R1, R3]`). This skill does not write code β€” only the plan. ```bash /flow-next:plan # or ``` β†’ [flow-next.dev/skills/plan](https://flow-next.dev/skills/plan)
4. Work through the tasks Execute tasks systematically: each runs in a fresh-context worker subagent, re-anchors against the spec before starting, then implements + commits + records evidence. Cross-model review gates (`impl-review`, `plan-review`) wrap the loop and iterate until SHIP. ```bash /flow-next:work # or ``` β†’ [flow-next.dev/skills/work](https://flow-next.dev/skills/work)
5. Open the PR with a cognitive-aid body Don't ask a human to skim a 10K-line diff. `/flow-next:make-pr` renders a PR body from nine flow-next input streams (spec R-IDs, per-task evidence, memory hits, glossary changes, strategy alignment, deferred review findings, the diff itself) β€” with an R-ID coverage table mapping every acceptance criterion to its satisfying task and evidence commit, and a "where to look" list that tells the reviewer which lines matter. A real one, from [PR #215](https://github.com/gmickel/flow-next/pull/215):
Cognitive-aid PR body from a real merged PR: R-ID coverage table mapping acceptance criteria to tasks and evidence commits, plus the per-task verification record
```bash /flow-next:make-pr # auto-detects from current branch ``` With HTML artifact mode on (`flowctl config set artifacts.html.enabled true`), make-pr also commits a self-contained `pr.html` review instrument β€” diff-derived churn map, R-ID β†’ evidence table with flagged mismatches, where-to-look checklist β€” and links it from the PR body. Same switch gives capture/plan a spec visualizer. Opt-in; see [`docs/html-artifacts.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/html-artifacts.md). β†’ [flow-next.dev/skills/make-pr](https://flow-next.dev/skills/make-pr)
6. Resolve PR review feedback Fetch unresolved threads + top-level comments + review-submission bodies, cluster them, dispatch per-thread resolver agents (parallel on Claude Code, serial elsewhere), validate, commit, then reply + resolve via GraphQL. ```bash /flow-next:resolve-pr ``` β†’ [flow-next.dev/skills/resolve-pr](https://flow-next.dev/skills/resolve-pr)
--- ## Going autonomous Three loops, one quality bar. Multi-model review at every handover, don't-thrash reflexes (two-strike unready, auto-block, bounded CI fix budgets), evidence over narration β€” invariant across all three. That's the differentiator from "ralph-wiggum"-style loops that run open-loop without gates. The default path is the **pilot + land pipeline** β€” in-session, host-driven, zero scaffold: ```bash flowctl spec ready fn-12 # bless work (or move its issue on the tracker board) /loop 10m /flow-next:pilot # build loop: ready spec β†’ plan β†’ reviews β†’ work β†’ draft PR /loop 30m /flow-next:land # ship loop: draft PR β†’ CI green β†’ reviews converged β†’ merged β†’ released ``` Run both concurrently β€” two instances, **separate clones** β€” and you have the full assembly line: board β†’ pilot β†’ draft PR β†’ land β†’ released. The `ready` flag (or your tracker's board state) is the consent boundary: humans bless specs, loops drain them. πŸ“– **[Going autonomous](https://flow-next.dev/autonomous/overview)** **Ralph** is the hardened harness for **fully planned** specs (it never plans): an external shell loop drives a *fresh* session per iteration β€” failed attempts die with the session instead of polluting the next one β€” with hook-enforced guardrails and receipts on disk. Reach for it when a run outlasts a session or prose guardrails aren't enough. ```bash /flow-next:ralph-init # One-time setup scripts/ralph/ralph.sh # Run from terminal ```
Ralph TUI monitoring an autonomous run *Ralph mode at night, PRs in the morning. The TUI tracks task progress, streaming logs, and run state.*
πŸ“– **[Ralph deep dive](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/ralph.md)** Β· **[Ralph TUI](https://github.com/gmickel/flow-next/tree/HEAD/flow-next-tui/)** (`bun add -g @gmickel/flow-next-tui`) --- ## Why it works | Problem | Solution | |---------|----------| | Context drift | **Re-anchoring** before every task β€” re-reads specs + git state | | Context window limits | **Fresh context per task** β€” worker subagent starts clean | | Single-model blind spots | **Cross-model reviews** β€” RepoPrompt, Codex, Copilot, or Cursor as second opinion | | Forgotten requirements | **R-IDs frozen at handover** β€” numbered once, never renumbered; traced spec β†’ task β†’ commit β†’ PR coverage table | | "It worked on my machine" | **Evidence recording** β€” commits, tests, PRs tracked per task | | Infinite retry loops | **Auto-block stuck tasks** β€” fails after N attempts, moves on | | Duplicate implementations | **Pre-implementation search** β€” worker checks for similar code before writing new | | Hallucinated specs from "I think we discussed…" | **Source-tagged capture** β€” every acceptance criterion marked `[user]` / `[paraphrase]` / `[inferred]`, mandatory read-back loop | | Stale project memory polluting future work | **`/flow-next:audit` + categorized memory schema** β€” agent reviews each entry, flags stale (never deletes) | | 10K-line diffs with no focus signal | **PR-as-cognitive-aid** β€” R-ID coverage, critical changes, decisions, where-to-look | | GitHub PR review threads piling up | **`/flow-next:resolve-pr`** β€” fetch β†’ triage β†’ dispatch resolver agents β†’ reply β†’ resolve via GraphQL | | One model doing everything | **Orchestration & model routing** β€” tiered subagents, per-task reviewer routing, opt-in `codex exec` implementation offload, promptable overrides ([docs](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/orchestration.md)) | ## What adopters say > *"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, said while shipping a correct kernel patch > *"it’s been really useful in my workflow."* > β€” [@raydocs](https://github.com/gmickel/flow-next/issues/4) Featured in [awesome-claude-code-workflows](https://github.com/ithiria894/awesome-claude-code-workflows) for plan-first workflows, Ralph autonomous mode, and receipt-based gating ([#96](https://github.com/gmickel/flow-next/issues/96)). ## Field-hardened in enterprise environments flow-next's ways of working are coached and run in enterprise environments worldwide - from CAD and construction software to proptech and education, from modern monorepos and hundred-repo microservice estates to 30-year-old legacy stacks, on GitHub Enterprise, GitLab, and Jira. Discovery interviews of 2-3 hours produce 8-11 structured, buildable specs; the edge cases surface in the interview, not the sprint. Receipts, evidence JSON, and review gates are the audit trail enterprise adoption asks for - approval checkpoints and traceability are built in, not bolted on. **For teams:** six named handover objects, **Spec-as-PR** (review the 50-line spec before the 500-line diff exists), and tracker projection to Linear / GitHub / GitLab / Jira. β†’ [`docs/teams.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/teams.md) Β· [flow-next.dev](https://flow-next.dev) ## What Flow-Next is *not* Scope honesty, because the architecture depends on it: - **Not a hosted dashboard or SaaS tier.** Everything is in the repo; a hosted layer would break the uninstall promise. - **Not a Jira/Linear replacement for human-only teams.** Flow-Next is for agentic-engineering teams. If your team lives in a tracker, `/flow-next:tracker-sync` *projects* specs to it β€” **projection, not coordination**: the spec stays the source of truth; the tracker never drives flow state or spawns agents. (Contrast OpenAI Symphony, where the tracker is the control plane β€” Flow-Next is "Symphony, but with real specs, re-anchoring, and receipts.") - **Not split-file specs.** One durable spec document evolving through layers β€” vs. Kiro-style `requirements.md` / `design.md` / `tasks.md` fragmentation. - **Not a replacement for human judgment.** Humans own product decisions, risk tolerance, merge decisions, and production responsibility. Flow-Next makes those decisions easier to verify because the evidence is structured. - **Not waterfall.** Waterfall means irreversible phases, a plan frozen at minimum knowledge, and handovers that discard what the next phase learns. Flow-Next has none of them: stages are re-enterable (re-interview after planning exposes a hole, re-plan after a task proves the approach wrong), the spec is captured at the moment of *most* knowledge because exploration comes first, and evidence is written *back* into the spec as work proceeds. It does ask for more **thought** earlier than a loose ticket does; it does not ask for more **commitment** earlier. The spec is a ratchet, not a gate. Full argument: [Prototype-Driven Specs](https://flow-next.dev/strategy/prototype-driven-specs/). --- ## Commands | Command | What it does | |---------|--------------| | `/flow-next:strategy` | Write `STRATEGY.md` β€” target problem, approach, users, metrics, active tracks | | `/flow-next:prospect` | Generate ranked candidate ideas grounded in the repo, upstream of `capture`/`interview`/`plan` | | `/flow-next:capture` | Synthesize conversation context into a spec (source-tagged, mandatory read-back) | | `/flow-next:interview` | Deep spec refinement with lead-with-recommendation + confidence tiers + codebase-first investigation; `--scope=business\|technical\|both` | | `/flow-next:plan` | Research codebase, create spec + dependency-ordered tasks | | `/flow-next:work` | Execute tasks with re-anchoring + worker subagents + review gates. Opt-in: offload implementation to a local `codex exec` with `delegate:codex` (or `work.delegate=codex` config) β€” OFF by default, consent-gated, host keeps all judgment ([config keys](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/flowctl.md#config)) | | `/flow-next:impl-review` | Cross-model implementation review (RepoPrompt, Codex, Copilot, or Cursor) | | `/flow-next:plan-review` | Cross-model plan review | | `/flow-next:spec-completion-review` | Spec-completion review gate β€” verify combined implementation matches the spec (renamed from `/flow-next:epic-review` in 1.0.0) | | `/flow-next:qa` | **Live-app real-user QA** β€” derives scenarios from the spec (AC / R-IDs / boundaries), drives the running app via `flow-next-drive`, files P0/P1/P2 findings with evidence, ends with a YES/NO ship verdict receipt. Forbidden from marking PASS by reading source. Opt-in β€” needs a live deploy + a driver | | `/flow-next:make-pr` | Render a cognitive-aid PR body (9 input streams) and open via `gh`; with HTML artifact mode on, also commits a `pr.html` review instrument | | `/flow-next:resolve-pr` | Resolve GitHub PR review threads (fetch β†’ triage β†’ fix β†’ reply β†’ resolve via GraphQL) | | `/flow-next:audit` | Agent-native review of `.flow/memory/` entries against current code (Keep / Update / Consolidate / Replace / Delete / Harden β€” Harden graduates a recurring, mechanizable lesson into a lint rule, CI step, or instruction-file rule, verified live before the entry is demoted to a pointer) | | `/flow-next:memory-migrate` | Lift legacy flat memory files into the categorized schema | | `/flow-next:prime` | **Opinionated agent-readiness assessment** - classifies the project (lifecycle / topology / size / stack / delivery shape), judges substance over existence, verifies commands actually run, leads with an operability verdict + ranked next-actions; fixes agent readiness with consent. `--classify-only` gives a cheap portfolio-triage sweep across many repos | | `/flow-next:pilot` | **Single-tick build-loop conductor** β€” advances one ready spec by one pipeline stage (plan β†’ plan-review β†’ work β†’ make-pr, plus an optional `qa` stage when `pipeline.qa==on`) per tick, ends with a `PILOT_VERDICT` line; drive it with `/loop` or `/goal` | | `/flow-next:land` | **Cadence-tick ship loop** β€” babysits the build loop's draft PRs: CI tri-state fix loop, reviewer patience window, resolve-pr convergence, gated explicit merge, spec close, release-follow; ends with a `LAND_VERDICT` line; drive it with `/loop 30m /flow-next:land` | | `/flow-next:ralph-init` | Scaffold autonomous loop (`scripts/ralph/`) + register project hooks (consent-gated; nothing installed by default) | | `/flow-next:setup` | Per-project setup β€” `.flow/` init, mode question (plugin mode: zero copies, run-once on Claude Code; copy mode: local flowctl install for mixed-host repos), CLAUDE.md/AGENTS.md instructions, review-backend + config ceremony, optional model-routing scaffold | | `/flow-next:sync` | **Plan-sync** β€” update downstream *task* specs after implementation drift inside flow-next | | `/flow-next:tracker-sync` | **Tracker bridge** (distinct from `/flow-next:sync`) β€” project a spec to a Linear/GitHub/GitLab/Jira issue and reconcile body/status/comments two-way; projection, not coordination ([docs](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/tracker-sync.md)) | | `/flow-next:map` | Optional β€” wrap [openclaw/clawpatch](https://github.com/openclaw/clawpatch)'s `clawpatch map` for a semantic feature index (`.clawpatch/features/*.json`); scouts read it when present, fall back to grep/glob when absent. Requires Node 22+ + `pnpm add -g clawpatch` | **Phrase-triggered skills** (no slash command β€” just ask): `flow-next-deps` ("what's blocking what?" β€” dependency graph + execution order), `flow-next-drive` (drive a running app like a real user; powers `/flow-next:qa`), `flow-next-export-context` (export RepoPrompt context for external-LLM review), `flow-next-rp-explorer` (token-efficient codebase exploration via RepoPrompt), `flow-next-worktree-kit` (worktree create/list/switch/cleanup + `.env` copying), and base `flow-next` ("show me my tasks", "what's ready?"). Full catalog of all 28 skills with triggers: [`docs/skills.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/skills.md). Full CLI reference (every flag, every default): [`docs/flowctl.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/flowctl.md). Steering all of it β€” model routing, review backends, delegation, loop chaining: [`docs/orchestration.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/orchestration.md). --- ## Adopting in a team Flow-Next is a methodology, not just a tool. The [teams guide](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/teams.md) maps the AI-native SDLC onto concrete commands: the six handover objects, **Spec-as-PR** (review the 50-line spec before the 500-line implementation exists), parallel work from one spec, the symmetric interview (PO and tech lead run the *same* skill on the *same* file), and a week-1 β†’ month-1 β†’ quarter-1 adoption ladder. Teams that live in Linear, GitHub Issues, GitLab, or Jira keep their board: the tracker bridge projects every spec to an issue, two-way. On Linear, `make-pr` output is additionally [Linear Diffs](https://linear.app/docs/diffs)-ready β€” review the PR inside the issue. β†’ [`docs/teams.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/teams.md) Β· [`docs/tracker-sync.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/tracker-sync.md) **Rolling it out to everyone?** On Claude Code you can skip the per-developer install: deploy the marketplace + plugin org-wide via a `managed-settings.json` (MDM/GPO β€” `extraKnownMarketplaces` + `enabledPlugins`), or commit a `.claude/settings.json` to a repo for prompt-on-trust install. Each repo still needs `/flow-next:setup`. β†’ [Install: team / org-wide deployment](https://flow-next.dev/install/#team--org-wide-deployment-claude-code-managed-settings) --- ## Where to look The repo holds the offline-resilient reference. [flow-next.dev](https://flow-next.dev) holds the narrative, browseable guide. Pick by audience. | Looking for… | Repo file | Website | |---|---|---| | 5-minute pitch + install | `README.md` (this page) | [flow-next.dev](https://flow-next.dev) | | Skills catalog β€” all 28 skills, triggers, one-liners | [`docs/skills.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/skills.md) | β€” | | Adopting in a team, handover objects, Spec-as-PR, adoption ladder | [`docs/teams.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/teams.md) | [Teams guide](https://flow-next.dev) | | Full `flowctl` CLI reference β€” every command, every flag | [`docs/flowctl.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/flowctl.md) | β€” | | Ralph autonomous mode internals β€” hooks, receipts, DCG | [`docs/ralph.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/ralph.md) | β€” | | Optional HTML render lenses β€” spec visualizer + PR review instrument | [`docs/html-artifacts.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/html-artifacts.md) | β€” | | Live-app QA β€” `/flow-next:qa`, spec-derived scenarios, P0/P1/P2 findings, `qa_verdict` receipt | [`skills/flow-next-qa/SKILL.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/skills/flow-next-qa/SKILL.md) | β€” | | `.flow/` directory layout, spec-first task model, ID format | [`docs/architecture.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/architecture.md) | β€” | | Spec template β€” R-ID rules, confidence anchors, receipt schema | [`docs/spec-template.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/spec-template.md) Β· canonical scaffold at [`templates/spec.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/templates/spec.md) | β€” | | Memory schema β€” bug / knowledge tracks, frontmatter, audit lifecycle | [`docs/memory-schema.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/memory-schema.md) | β€” | | Self-improving loops β€” memory, glossary, decisions, strategy | [`docs/self-improving.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/self-improving.md) | β€” | | Tracker-sync bridge β€” projection model, hybrid id, transport ladder, `/flow-next:tracker-sync` vs `/flow-next:sync` | [`docs/tracker-sync.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/tracker-sync.md) | β€” | | Project glossary β€” `GLOSSARY.md` shape, R17 forbidden-vocabulary guard | [`docs/glossary.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/glossary.md) Β· [`GLOSSARY.md`](https://github.com/gmickel/flow-next/blob/HEAD/GLOSSARY.md) | β€” | | Project strategy β€” `STRATEGY.md` shape, downstream skill grounding | [`docs/strategy.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/strategy.md) Β· [`STRATEGY.md`](https://github.com/gmickel/flow-next/blob/HEAD/STRATEGY.md) | β€” | | Cross-platform install matrix + Codex / Droid / OpenCode notes | [`docs/platforms.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md) | β€” | | `scripts/sync-codex.sh` pipeline, plain-text transform, validation guards | [`docs/sync-codex.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/sync-codex.md) | β€” | | Troubleshooting β€” stuck tasks, Ralph debug, receipt validation, uninstall | [`docs/troubleshooting.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/troubleshooting.md) | β€” | | Contributing β€” local dev, adding skills, releasing | [`CONTRIBUTING.md`](https://github.com/gmickel/flow-next/blob/HEAD/CONTRIBUTING.md) | β€” | | Repo strategic intent + active tracks | [`STRATEGY.md`](https://github.com/gmickel/flow-next/blob/HEAD/STRATEGY.md) | β€” | | Canonical vocabulary | [`GLOSSARY.md`](https://github.com/gmickel/flow-next/blob/HEAD/GLOSSARY.md) | β€” | | Visual overview, diagrams, methodology | β€” | [`flow-next.dev`](https://flow-next.dev) | Doc index with one-line descriptions: [`plugins/flow-next/docs/README.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/README.md). --- ## Requirements - **Python 3.11+** (or the `py` launcher on Windows) β€” bundled `flowctl` CLI is pure-stdlib. Launchers skip broken aliases and working interpreters below the supported floor before loading flowctl. - **`jq`** and **`gh`** β€” required for the review subsystem and PR plumbing. - **`bun`** *(optional)* β€” only needed for the [Ralph TUI](https://github.com/gmickel/flow-next/tree/HEAD/flow-next-tui/). ## Platforms | Platform | Status | |---|---| | Claude Code | First-class (canonical surface) | | OpenAI Codex (CLI + Desktop) | First-class (mirror at `plugins/flow-next/codex/`, regenerated by `scripts/sync-codex.sh`) | | Factory Droid | First-class (regex-OR matchers handle `Execute` ↔ `Bash`) | | Grok Build (xAI) | Works via Claude Code compatibility β€” skills, `/flow-next:*` commands, hooks, and **multi-agent flows** (verified). Type **`/flow-next:`** to open the command autocomplete; `/flow-next-` filters the separate hyphen-named skill surface. Ralph intentionally not built β€” [details](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md#grok-build-claude-code-compatibility) | | Cursor | First-class. **Recommended:** team-marketplace repo import (admin imports this GitHub repo via the Cursor GitHub App; Default Off/On/Required; auto-refresh on push). **Fallback:** local plugin (`./scripts/install-cursor.sh` / `install-cursor.ps1`). Skills, commands, multi-agent, native asks, slash autocomplete verified; Ralph intentionally not built for Cursor β€” [details](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md#cursor) | | OpenCode | Community port: [`flow-next-opencode`](https://github.com/gmickel/flow-next-opencode) | Detailed install + cross-platform patterns in [`docs/platforms.md`](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/platforms.md). > **Upgrading from 0.x?** The 1.0 release renamed the `epic` surface to `spec`; the legacy aliases and automated migration commands were removed in 3.0. Re-run `/flow-next:setup` for current scaffolding, then follow the manual three-step pre-1.0 layout port in [troubleshooting](https://github.com/gmickel/flow-next/blob/HEAD/plugins/flow-next/docs/troubleshooting.md#pre-10-layout-porting). ## Ecosystem | Project | Platform | |---|---| | [flow-next-opencode](https://github.com/gmickel/flow-next-opencode) | OpenCode | | [FlowFactory](https://github.com/Gitmaxd/flowfactory) | Factory.ai Droid | | [Ralph TUI](https://github.com/gmickel/flow-next/tree/HEAD/flow-next-tui/) | Cross-platform TUI for Ralph runs | ## Contributing Bug reports and PRs welcome β€” start at [`CONTRIBUTING.md`](https://github.com/gmickel/flow-next/blob/HEAD/CONTRIBUTING.md) (local dev, adding skills, the docs-only rule) and [`SECURITY.md`](https://github.com/gmickel/flow-next/blob/HEAD/SECURITY.md) for private disclosure. Questions and show-and-tell: [GitHub Discussions](https://github.com/gmickel/flow-next/discussions). Or come say hi on [Discord](https://discord.gg/f3DYq8AAm5). Every PR runs the same gate: the full test suite on a 3-OS matrix (Ubuntu / macOS / Windows) plus an offline docs-linkcheck - green CI is the merge floor. ## Also check out > **[GNO](https://gno.sh)** β€” local hybrid search for your notes, docs, and code. Long-term memory over your files via MCP. > > ```bash > bun install -g @gmickel/gno && gno mcp install --target claude-code > ``` --- ## License MIT β€” see [`LICENSE`](https://github.com/gmickel/flow-next/tree/HEAD/LICENSE).
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)