Plan-first AI workflow plugin for Claude Code, OpenAI Codex, and Factory Droid. Zero-dep task tracking, worker subagents, Ralph autonomous mode, cross-model reviews.
Plan-first AI workflow. Zero external dependencies.
📖 Read the full docs → — the main documentation. All 19 commands with reference, lifecycle workflow with mermaid diagrams, install + setup on every platform, Ralph autonomous mode, Codex / Droid / OpenCode notes, complete flowctl CLI reference, project glossary + strategy + decision records, memory system. Start there if you want depth — this root page is the marketing TL;DR.
👥 Adopting in a team? Read the teams + spec-driven-development guide → — maps each SDLC stage to a Flow-Next command, names the six handover objects in the agentic lifecycle, and walks through Spec-as-PR, parallel work from one spec, R-ID frozen-at-handover, the symmetric interview pattern, and the Week 1 / Month 1 / Quarter 1 adoption ladder. Cross-links to the AI-x-SDLC-Starter-Kit methodology guide for the underlying theory.
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, multi-model reviews, decay-aware project memory, GitHub PR creation + resolution, agent-readiness audits. Everything lives in your repo — no external services, no global config. Uninstall: delete .flow/.
First-class on Claude Code, OpenAI Codex (CLI + Desktop), and Factory Droid. Also runs on OpenCode via the community port.
🆕 v1.0.0 — flowctl epic → flowctl spec. The 1.0 release renames the canonical primitive: flowctl epic becomes flowctl spec, .flow/epics/ becomes .flow/specs/, epic-scout becomes spec-scout, /flow-next:epic-review becomes /flow-next:spec-completion-review. 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; JSON read responses dual-emit spec_idandepic_id; on read, .flow/epics/ is auto-fallback when .flow/specs/ is absent. Two migration paths: interactive via /flow-next:setup (recommended) or deterministic via flowctl migrate-rename --yes (transactional backup at .flow/.backup-pre-1.0/, lockfile-guarded, sentinel-anchored). Rollback supported via flowctl migrate-rollback --yes. Suppress the auto-detect banner with FLOW_NO_AUTO_MIGRATE=1. Soft alias-removal target is 2.0.0 (telemetry-driven, not calendar-driven). Full changelog.
Why a script for Codex? Codex's plugin protocol currently only registers skills from plugin.json — not custom .toml agents or hooks. The /plugins install gives you slash commands, but no subagent isolation (worker model tier, disallowed_tools) and no Ralph hooks. install-codex.sh merges all 21 agents + hooks directly into ~/.codex/config.toml so you get the full multi-agent + Ralph experience. We'll switch to /plugins once Codex's manifest supports agents and hooks fields.
Update Codex:cd flow-next && git pull && ./scripts/install-codex.sh flow-next. The script is idempotent — safe to re-run on every update.
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/)]
Idea → spec → tasks → ship. Branch in, branch out — pick the entry point that matches your context.
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, or Copilot as second opinion |
| Forgotten requirements | Dependency graphs — tasks declare blockers, run in order |
| "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) |
| GitHub PR review threads piling up | /flow-next:resolve-pr — fetch → triage → dispatch resolver agents → reply → resolve via GraphQL |
Commands
| Command | What It Does |
|---------|--------------|
| /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 |
| /flow-next:plan | Research codebase, create spec + dependency-ordered tasks |
| /flow-next:work | Execute tasks with re-anchoring + worker subagents + review gates |
| /flow-next:impl-review | Cross-model implementation review (RepoPrompt, Codex, or Copilot) |
| /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; soft-removal target 2.0.0, telemetry-driven) |
| /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) |
| /flow-next:memory-migrate | Lift legacy flat memory files into the categorized schema; agent classifies each entry |
| /flow-next:prime | 8-pillar agent-readiness assessment with parallel scouts; remediation via consent prompts |
| /flow-next:ralph-init | Scaffold autonomous loop (scripts/ralph/) |
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
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
