📖 Full doc index → · 🌐 flow-next.dev · 👥 Teams guide · 💬 Discord

What is this?

Flow-Next is an AI agent orchestration plugin. Twenty-three agent-native skills for the full lifecycle: idea → spec → tasks → review → ship → maintain. Bundled task tracking, dependency graphs, re-anchoring before every task, multi-model reviews, decay-aware project memory, GitHub PR creation and resolution, agent-readiness audits. Everything lives in your repo — no external services, no global config. Uninstall: delete .flow/.

• Spec-first. Every unit of work belongs to a spec fn-N. Tasks fn-N.M inherit context.
• Fresh-context workers. Each task runs in its own subagent. No token bleed between tasks.
• Cross-model reviews. A different model (RepoPrompt / Codex / Copilot) gates every implementation.
• R-IDs frozen at handover. Acceptance criteria numbered once, never renumbered.

First-class on Claude Code, OpenAI Codex (CLI + Desktop), and Factory Droid. Also runs on OpenCode via the community port.

🆕 v1.0+ — flowctl epic → flowctl spec. The 1.0 release renames the canonical primitive across the entire flow-next surface. All 0.x scripts and CLAUDE.md examples keep working — the legacy CLI is preserved as a deprecation alias layer through all of 1.x. See the CHANGELOG for the migration path (interactive via /flow-next:setup or deterministic via flowctl migrate-rename --yes, both transactional with rollback).

Quick start

Install

/plugin marketplace add \
  https://github.com/gmickel/flow-next
/plugin install flow-next
/flow-next:setup

git clone https://github.com/gmickel/flow-next.git
cd flow-next
./scripts/install-codex.sh flow-next
# then: /flow-next:setup

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 21 agents + hooks into ~/.codex/config.toml. Idempotent — safe to re-run. Full platform matrix + community ports in docs/platforms.md.

The 5-command happy path

/flow-next:capture                   # 1. Synthesize conversation → .flow/specs/<id>.md
/flow-next:plan <spec-id>            # 2. Break the spec into dependency-ordered tasks
/flow-next:work <spec-id>            # 3. Execute tasks in fresh-context worker subagents
/flow-next:make-pr <spec-id>         # 4. Render a cognitive-aid PR body (9 input streams)
/flow-next:resolve-pr <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:ralph-init for autonomous overnight runs, /flow-next:audit for memory garbage collection).

How the flow works

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| Done([🚀 Ship])
    R -->|NEEDS_WORK| W

    Done -.maintenance.-> A[/flow-next:audit/]
    A -.-> M[(.flow/memory/)]

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 (source-tagged, mandatory read-back), or — when starting from scratch — generate ranked candidate ideas grounded in the repo. Both land in .flow/specs/<id>.md.

/flow-next:capture                    # from a conversation
/flow-next:prospect <focus-hint>      # from a focus hint (concept, path, constraint, volume)

→ flow-next.dev/skills/capture · 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 to flesh out an ambiguous spec before breaking it down. --scope=business|technical|both symmetrically narrows the pass.

/flow-next:interview <spec-id>

→ flow-next.dev/skills/interview

3. Plan into dependency-ordered tasks

Research the codebase, then write the spec + tasks together. Tasks fn-N.M declare blockers, inherit context from the parent spec, and stay dependency-ordered. This skill does not write code — only the plan.

/flow-next:plan <spec-id>             # or <free-form text>

→ 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.

/flow-next:work <spec-id>             # or <task-id>

→ flow-next.dev/skills/work

5. Open the PR with a cognitive-aid body

Render 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). Optional mermaid diagrams on module-boundary changes. Pushes via gh.

/flow-next:make-pr <spec-id>          # auto-detects from current branch

→ 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.

/flow-next:resolve-pr <PR#>

→ flow-next.dev/skills/resolve-pr

Going autonomous? /flow-next:ralph-init scaffolds a repo-local Ralph harness under scripts/ralph/. Ralph loops the same steps overnight with fresh context per iteration, multi-model review gates, and auto-block on stuck tasks. → flow-next.dev/ralph

Why it works

Commands

Full command reference (every flag, every default) in docs/flowctl.md.

Ralph (autonomous mode)

Run overnight. Fresh context per iteration + multi-model review gates + auto-block stuck tasks.

/flow-next:ralph-init           # One-time setup
scripts/ralph/ralph.sh          # Run from terminal

📖 Ralph deep dive · Ralph TUI (bun add -g @gmickel/flow-next-tui)

Where to look

The repo holds the offline-resilient reference. flow-next.dev holds the narrative, browseable guide. Pick by audience.

Doc index with one-line descriptions: plugins/flow-next/docs/README.md.

Requirements

• Python 3.8+ — bundled flowctl CLI is pure-stdlib.
• jq and gh — required for the review subsystem and PR plumbing.
• bun (optional) — only needed for the Ralph TUI.

Platforms

Detailed install + cross-platform patterns in docs/platforms.md.

Ecosystem

Also check out

GNO — local hybrid search for your notes, docs, and code. Long-term memory over your files via MCP.

bun install -g @gmickel/gno && gno mcp install --target claude-code

License

MIT — see LICENSE.