Flow-Next Engineering Pipeline
A repository-native workflow for turning AI coding work into reviewed specs, tasks, and evidence-backed delivery.
What does this agent do, and when should you use it?
Flow-Next is a repository-native engineering workflow plugin that keeps specs, tasks, memory, and receipts under `.flow/`. It pairs host-agent reasoning with `flowctl`, a bundled pure-standard-library Python CLI, rather than a hosted control plane. Its main path captures a durable spec, plans dependency-ordered tasks, runs implementation, and produces a PR-oriented review artifact. Workers can start each task with fresh context and re-read the spec, task, and Git state before making changes; plan and implementation reviews can use a different model. The repository documents first-class support for Claude Code, OpenAI Codex, Factory Droid, Cursor, and Grok Build, with project artifacts remaining in Git.
/flow-next:capture writes a conversation or briefing into .flow/specs/<id>.md and source-tags acceptance criteria as [user], [paraphrase], or [inferred]. /flow-next:plan <spec-id> investigates the codebase and creates dependency-ordered fn-N.M tasks that declare the R-IDs they satisfy. /flow-next:work <spec-id> or a task ID launches fresh-context workers that re-anchor on the spec, task, and Git state, then implement, test, commit, and record evidence; plan-review and impl-review can iterate with another model until SHIP. /flow-next:make-pr renders a PR body from R-IDs, task evidence, memory, glossary and strategy changes, deferred findings, and the diff. /flow-next:resolve-pr <PR#> fetches review material, dispatches resolution work, validates commits, and replies to and resolves threads through GraphQL. flowctl also manages configuration, readiness state, and disk-backed receipts used by autonomous Ralph runs.
- A Claude Code tech lead who wants to convert a requirements conversation into a reviewable specification before implementation begins.
- An engineering team breaking a broad change into context-sized tasks while preserving the commit and test evidence for every task.
- A GitHub-based team that wants a second model to review both the implementation plan and completed implementation before human PR review.
- A mixed Codex and Claude Code team that needs workflow state and specifications to travel with the repository rather than live in one vendor workspace.
- A team running fully planned work overnight with Ralph shell loops, hooks, and on-disk receipts.
What are this agent's strengths and limitations?
- Uses a single durable repository spec and traces acceptance R-IDs through tasks, commits, tests, and PR coverage.
- Fresh-context workers re-anchor before every task, while cross-model plan and implementation reviews provide an explicit second opinion.
- `make-pr` produces an R-ID coverage table and a focused review guide instead of leaving reviewers with an unexplained large diff.
- Supports several coding hosts while keeping workflow state, receipts, and documentation reviewable in Git.
- Requires Python 3.11+, `jq`, and GitHub CLI; PR and review-resolution functions depend on GitHub tooling.
- The workflow adds explicit specs, tasks, gates, and receipts; the documentation notes that experienced developers may initially perceive this as friction.
- Codex requires an installation script because its plugin protocol does not directly register the custom `.toml` agents or hooks.
- Ralph requires an external shell loop and only handles fully planned specs; it is intentionally not built for Cursor or Grok Build.
How do you install or deploy this agent?
Claude Code:
/plugin marketplace add https://github.com/gmickel/flow-next
/plugin install flow-next
/reload-plugins
/flow-next:setup
OpenAI Codex:
git clone https://github.com/gmickel/flow-next.git
cd flow-next
./scripts/install-codex.sh flow-next
Then run /flow-next:setup. The Codex installer merges bundled agents and hooks into the active Codex home’s config.toml and is documented as idempotent. Requirements are Python 3.11+, jq, and gh; Bun is optional for the Ralph TUI.
How do you use this agent?
After setup, run /flow-next:capture to create a spec from the current requirement, then /flow-next:plan <spec-id> and /flow-next:work <spec-id>. Use /flow-next:make-pr <spec-id> to create the PR review body, and /flow-next:resolve-pr <PR#> to process review feedback. For autonomous operation, mark approved work with flowctl spec ready fn-12, then run /flow-next:pilot and /flow-next:land loops in separate clones. Ralph is intended only for fully planned specs.
How does this agent compare with similar options?
It is not positioned as a Jira or Linear replacement: tracker-sync projects specs to a tracker while the spec remains the source of truth. The documentation also contrasts its one evolving spec document with Kiro-style split requirements.md, design.md, and tasks.md files.