Flow-Next
Zero-Dep Agent Orchestration
One task at a time with full review cycles, or throw the whole epic at it and walk away. Either way: re-anchoring, evidence, cross-model review.
Planning ensures every task fits the context window. Re-anchoring after each task—and after compaction—means zero drift.
/flow-next:work fn-1.1single task/flow-next:work fn-1entire epicSignal Intercepts
What people are saying
Claire Novotny
@clairernovotny
“I've found it generating production-quality code. Far far better than any of the other tools I've tried so far.”
David P
@Lat3ntG3nius
“Cross-model review is genius because it exploits model diversity as a feature, not a bug. Different models make different mistakes, so using them as mutual reviewers creates a safety net that single-model workflows can't match.”
Baran Güneysel
@chnoblist
“As a designer, I always felt a gap between prototyping and delivering production-ready code, but flow-next bridges that gap and empowers me to ship with confidence.”
Tiago Freitas
@tiagoefreitas
“Flow-next is simply the best coding flow not even close, and still a side project!”
Ben
@BuildItWithBen
“RepoPrompt + flow-next combo has been a force multiplier for me. Keep the updates flowing!”
Mark Feighery
@MarkFeighery1
“Ok never mind I used it all and it's brilliant.”
dailyreader
@010110O0
“Been running flow-next for the last week and boy am I happy!”
Ecosystem
One workflow, four platforms
Same .flow/ directory, same flowctl, same workflow — regardless of which AI coding tool you use.
- +Native plugin marketplace
- +Full commands, hooks, 17 subagents
- +Ralph autonomous mode
# add marketplace
/plugin marketplace add
github.com/gmickel/
gmickel-claude-marketplace
# install
/plugin install flow-next- +Cross-platform compatibility
- +Same marketplace install flow
- +Bash|Execute hook matchers
# add marketplace
droid plugin marketplace add
github.com/gmickel/
gmickel-claude-marketplace
# install
/plugin install flow-next- +20 multi-agent roles
- +3-tier model mapping (GPT 5.3)
- +Linux, macOS, Windows
# clone + install
git clone gmickel/
gmickel-claude-marketplace
./scripts/install-codex.sh
flow-next- +Community port
- +Separate repository
- +Same .flow/ format
Zero vendor lock-in
File-based state in .flow/ — works everywhere, move between platforms freely
The secret: you control the granularity
Work task-by-task with full review cycles for maximum control. Or throw the whole epic at it and let Flow-Next handle everything. Same guarantees either way.
Flexible Execution
Same workflow, different scopes. Both get re-anchoring, reviews, and evidence.
/flow-next:work fn-1.1/flow-next:work fn-1→ Pick your level of supervision. The workflow stays the same.
No Context Worries
Planning ensures tasks fit context. Re-anchoring handles the rest.
Tasks sized at planning
Every task fits one work iteration
Re-anchor every task
Fresh context from .flow/ specs
Survives compaction
Re-anchor after summarization too
→ Never worry about 200K token limits again.
Two Models > One
If drift happens despite re-anchoring, a different model catches it.
SHIP→ Two models catch what one misses.
The result: agents that actually finish what they start
Pre-sized tasks + re-anchoring + cross-model review = minimal drift, maximum reliability
Plan→Work→Review→DoneThe Problem
Process failures,
not model failures
Flow-Next gives agents structured task graphs, forces re-anchoring before every task, records evidence of completion, and runs cross-model reviews.
→ Agents that finish what they start.
Key Features
Built for reliability
Re-anchoring
Before EVERY task, re-reads epic + task specs + git state. Per Anthropic guidance: agents must re-anchor to prevent drift.
Multi-user Safe
Scan-based IDs (no counters). Soft claims via assignee. Auto-detects actor from git email. Teams work parallel branches.
Zero Dependencies
Bundled flowctl.py. No external CLI to install. No npm packages. Just Python 3.
Non-invasive
No hooks. No daemons. No CLAUDE.md edits. Delete .flow/ to uninstall completely. No traces.
CI-ready
flowctl validate --all exits 1 on errors. Drop into pre-commit hooks or GitHub Actions.
Dependency Graphs
Tasks declare blockers. Epic-scout auto-detects cross-epic dependencies during planning.
Plan-Sync
Opt-in sync keeps downstream task specs updated when implementation drifts. Cross-epic mode available.
Memory System
Persistent learnings survive context compaction. Auto-captures pitfalls from NEEDS_WORK reviews.
Commands
Eight commands, complete workflow
/flow-next:planResearch + produce epic with dependency-ordered tasks
/flow-next:workExecute epic task by task with re-anchoring
/flow-next:interviewDeep interview to flesh out spec (optional)
/flow-next:plan-reviewCarmack-level plan review (Codex or RepoPrompt)
/flow-next:impl-reviewCarmack-level impl review (Codex or RepoPrompt)
/flow-next:epic-reviewEpic completion review before epic closes
/flow-next:primeAssess codebase agent-readiness, propose fixes
/flow-next:syncUpdate downstream tasks after implementation drift
/flow-next:ralph-initScaffold autonomous operation loop (Ralph mode)
Core Workflow
Plan → Work → Ship
/flow-next:planCreates .flow/specs/fn-N.md
- 01Run 7 research scouts in parallel
- 02Gap analysis for edge cases
- 03Create epic + set epic dependencies
- 04Break into tasks + add doc update criteria
- 05Auto-review (Codex or RepoPrompt)
/flow-next:workRe-reads specs before each task
- 01Re-anchor: read epic + task + git state
- 02Implement following existing patterns
- 03Test + verify acceptance criteria
- 04Record summary + evidence via flowctl
- 05Loop to next ready task
/flow-next:epic-reviewCatches gaps per-task review misses
- 01All tasks done, review not shipped
- 02Extract requirements from spec
- 03Verify each requirement vs code
- 04Fix gaps inline (loops until SHIP)
- 05Set status=ship, epic closes
Planning Intelligence
Seven research scouts run in parallel during planning, gathering context from multiple sources before a single line of code is written.
repo-scoutFinds existing patterns and conventions
practice-scoutGathers modern best practices
docs-scoutFinds relevant framework docs
github-scoutCross-repo code search
epic-scoutDetects epic dependencies
docs-gap-scoutIdentifies docs needing updates
memory-scoutRetrieves project learnings
gap-analystFinds missing requirements
9 scouts use Haiku for speed, 4 use Opus for depth
Plus: worker, plan-sync, quality-auditor, context-scout = 17 total subagents
Agent Readiness
Assessment
Agents waste cycles when codebases lack pre-commit hooks, documented env vars, or clear conventions. These are environment problems, not agent problems. /flow-next:prime scans your codebase and proposes fixes.
Six Assessment Pillars
Style & Validation
Linters, formatters, type checking, pre-commit
Build System
Build commands, CI, lock files
Testing
Test framework, coverage, E2E
Documentation
README, CLAUDE.md, ADRs
Dev Environment
.env.example, Docker, devcontainer
Code Quality
CONTRIBUTING, PR templates, CODEOWNERS
Maturity Levels
# Full assessment + interactive fixes
/flow-next:prime
# Report only
/flow-next:prime --report-only6
Haiku scouts
36
Criteria checked
~15s
Assessment time
∞
Templates included
Ralph Mode
Agents that run overnight
Opt-in autonomous operation built on top of the flow-next plan/work loop. Orchestrates complete cycles while you sleep—fresh context windows every iteration prevent drift. Attempt backstops block stuck tasks automatically.
Smart Selector
flowctl next chooses plan gate vs work gate
Fresh Context
New session per iteration prevents 200K token drift
Auto Backstop
Blocks tasks after N failed attempts
Repo-Local
Everything in scripts/ralph/ - no external services
Deterministic enforcement prevents agents from skipping steps or drifting from the workflow.
Receipt-Based Gating
Every review must produce a receipt proving it ran. No receipt = no progress.
Review Until SHIP
Reviews don't just flag issues—they block until the reviewer returns SHIP.
Workflow Enforcement
Guard rails ensure the agent follows the prescribed flow exactly.
# Scaffold autonomous harness
/flow-next:ralph-init
# Run one iteration (interactive)
./scripts/ralph/ralph_once.sh
# Run overnight loop
./scripts/ralph/ralph.sh
flowctl next selects unit
plan gate or work gate
plan: runs /flow-next:plan + review loop until SHIP
work: runs /flow-next:work for one task until pass
none: COMPLETE — all epics done
Fresh Claude session
clean context window
Record attempt + loop
auto-block if stuck
⚙️Configuration
Edit scripts/ralph/config.env to customize
🛡️Safety & Uninstall
YOLO Mode Warning
YOLO=1 skips permission prompts. Use in sandbox/container only. No secrets in env.
Uninstall Ralph
rm -rf scripts/ralph/Removes harness + vendored flowctl. .flow/ remains.
Terminal UI
for Ralph Runs
Watch your autonomous runs in real-time. Task progress, streaming logs, and run state—all in a beautiful terminal interface.
Task Progress
Visual status tracking
Live Logs
Streaming output
Themes
Dark & light modes
Vim Keys
j/k navigation
# Requires Bun runtime
bun add -g @gmickel/flow-next-tui
# Start monitoring
flow-next-tui # or: fntuiAuto-selects latest run. Detach with q—Ralph keeps running.
How It Works
Plan
epic-firstWork
loopedStorage
Everything in .flow/
No external databases. No config elsewhere. One directory you can delete to fully uninstall.
.flow/
├── meta.json # schema version
├── config.json # opt-in features
├── epics/
│ └── fn-1.json
├── specs/
│ └── fn-1.md # epic plan
├── tasks/
│ ├── fn-1.1.json # metadata + deps
│ ├── fn-1.1.md # spec + done
│ └── ...
└── memory/ # opt-in
├── pitfalls.md
├── conventions.md
└── decisions.mdMulti-user Safety
without coordination servers
Scan-based IDs
Scans existing files to allocate next ID. No shared counters.
Soft claims
Tasks track assignee. Prevents accidental duplicate work.
Actor resolution
Auto-detects from git email, FLOW_ACTOR env, or $USER.
# Actor A starts task
flowctl start fn-1.1 # sets assignee
# Actor B tries same task
flowctl start fn-1.1
error: claimed by actor-a@example.com
flowctl start fn-1.1 --force # overrideBundled CLI
flowctl.py manages all state
Skills call this automatically. Use it directly if you want.
# Setup
flowctl init # create .flow/
flowctl detect # check exists
# Workflow
flowctl ready --epic fn-1 # ready/blocked
flowctl start fn-1.1 # claim task
flowctl done fn-1.1 --summary-file s.md
# Validation
flowctl validate --all # CI gatePower features when you need them
Off by default. Enable via /flow-next:setup or flowctl config set.
Syncs downstream task specs when implementation drifts from the plan. Keeps future tasks accurate.
Same-epic sync
Updates downstream tasks in current epic
Cross-epic sync
Also checks other open epics (opt-in, off by default)
flowctl config set planSync.enabled true
flowctl config set planSync.crossEpic truePersistent learnings survive context compaction. Retrieves relevant entries during planning and work.
pitfalls.md
Auto-captured from NEEDS_WORK reviews
conventions.md
Project patterns not in CLAUDE.md
decisions.md
Architectural choices with rationale
flowctl config set memory.enabled true
flowctl memory initTwo models catch what one misses
Send your plans and implementations to a different AI model for review. Choose Codex CLI (cross-platform, GPT 5.2 High) or RepoPrompt (macOS). Both use identical Carmack-level review criteria.
Fresh Perspective
A second model catches blind spots that self-review misses
Blocks Until SHIP
No "LGTM with nits" that get ignored—reviews enforce resolution
Cross-Platform
Codex CLI works on Linux, macOS, Windows. RepoPrompt for macOS power users
- ✓Cross-platform (Linux, macOS, Windows)
- ✓GPT 5.2 High reasoning by default
- ✓Context hints: symbols + references
- ✓Session continuity across fix cycles
npm i -g @openai/codex && codex auth- ✓Visual context builder UI
- ✓Any model via RepoPrompt interface
- ✓Full file context, not patches
- ✓Token-efficient codebase exploration
/flow-next:plan-reviewReview the plan before any code is written. Catches architectural issues early.
/flow-next:impl-reviewReview the implementation. Loops fix → re-review until SHIP verdict.
Auto-detection: Flow-Next checks for available backends automatically. Configure preference via flowctl config set review.backend codex or FLOW_REVIEW_BACKEND env var.
Get Started
Pick your platform
/plugin marketplace add https://github.com/gmickel/gmickel-claude-marketplace/plugin install flow-nextdroid plugin marketplace add https://github.com/gmickel/gmickel-claude-marketplace/plugins → Marketplace → install flow-nextgit clone gmickel/gmickel-claude-marketplace
./scripts/install-codex.sh flow-nextInstalls 20 multi-agent roles to ~/.codex/
Community port — see repo README for setup
rm -rf .flow/If Ralph Mode enabled
rm -rf scripts/ralph/No hooks. No config. No traces.
Requirements
- +Python 3.8+ and git
- +Codex CLI (cross-platform) or RepoPrompt (macOS) for cross-model reviews
Flow vs Flow-Next
Flow
- Storage:plans/*.md or Beads epics
- Install:Plugin + optionally Beads
- Config:CLAUDE.md for Beads
Flow-Next
- Storage:.flow/ directory
- Install:Plugin only
- Config:None
Choose Flow-Next for zero deps and clean uninstall. Choose Flow if you use Beads.
View Flow →