{"id":48395160,"url":"https://github.com/gmickel/flow-next","last_synced_at":"2026-05-27T11:09:55.285Z","repository":{"id":330783212,"uuid":"1123446919","full_name":"gmickel/flow-next","owner":"gmickel","description":"Spec-driven AI workflow plugin for Claude Code, OpenAI Codex, and Factory Droid. Zero-dep task tracking, worker subagents, Ralph autonomous mode, cross-model reviews.","archived":false,"fork":false,"pushed_at":"2026-05-26T14:11:10.000Z","size":8485,"stargazers_count":615,"open_issues_count":12,"forks_count":47,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-05-26T16:14:18.766Z","etag":null,"topics":["agentic-workflow","ai-agent","ai-workflow","anthropic","autonomous-agent","claude-code","claude-code-plugin","cli","code-review","codex","execution","factory-droid","marketplace","openai-codex","planning","plugin","ralph-mode","sdlc","spec-driven-development","workflow"],"latest_commit_sha":null,"homepage":"https://flow-next.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmickel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["gmickel"]}},"created_at":"2025-12-26T22:27:07.000Z","updated_at":"2026-05-26T14:32:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gmickel/flow-next","commit_stats":null,"previous_names":["gmickel/gmickel-claude-marketplace","gmickel/flow-next"],"tags_count":122,"template":false,"template_full_name":null,"purl":"pkg:github/gmickel/flow-next","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmickel%2Fflow-next","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmickel%2Fflow-next/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmickel%2Fflow-next/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmickel%2Fflow-next/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmickel","download_url":"https://codeload.github.com/gmickel/flow-next/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmickel%2Fflow-next/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33562918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflow","ai-agent","ai-workflow","anthropic","autonomous-agent","claude-code","claude-code-plugin","cli","code-review","codex","execution","factory-droid","marketplace","openai-codex","planning","plugin","ralph-mode","sdlc","spec-driven-development","workflow"],"created_at":"2026-04-06T01:20:00.232Z","updated_at":"2026-05-27T11:09:55.279Z","avatar_url":"https://github.com/gmickel.png","language":"Python","funding_links":["https://github.com/sponsors/gmickel"],"categories":["Codex Workflow Frameworks","Python"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Flow-Next\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Flow-next](https://img.shields.io/badge/Flow--next-v1.3.3-green)](CHANGELOG.md)\n[![Docs](https://img.shields.io/badge/Docs-📖-informational)](plugins/flow-next/docs/README.md)\n\n[![Author](https://img.shields.io/badge/Author-Gordon_Mickel-orange)](https://mickel.tech)\n[![Twitter](https://img.shields.io/badge/@gmickel-black?logo=x)](https://twitter.com/gmickel)\n[![Sponsor](https://img.shields.io/badge/Sponsor-❤-ea4aaa)](https://github.com/sponsors/gmickel)\n[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/f3DYq8AAm5)\n\n**Plan-first AI workflow. Zero external dependencies.**\n\n\u003c/div\u003e\n\n\u003e 📖 **[Full doc index →](plugins/flow-next/docs/README.md)** · 🌐 **[flow-next.dev](https://flow-next.dev)** · 👥 **[Teams guide](plugins/flow-next/docs/teams.md)** · 💬 **[Discord](https://discord.gg/f3DYq8AAm5)**\n\n---\n\n## What is this?\n\nFlow-Next is an AI agent orchestration plugin. **Twenty-four 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/`.\n\n- **Spec-first.** Every unit of work belongs to a spec `fn-N`. Tasks `fn-N.M` inherit context.\n- **Fresh-context workers.** Each task runs in its own subagent. No token bleed between tasks.\n- **Cross-model reviews.** A different model (RepoPrompt / Codex / Copilot) gates every implementation.\n- **R-IDs frozen at handover.** Acceptance criteria numbered once, never renumbered.\n\nFirst-class on **Claude Code**, **OpenAI Codex** (CLI + Desktop), and **Factory Droid**. Also runs on **OpenCode** via the [community port](https://github.com/gmickel/flow-next-opencode).\n\n\u003e 🆕 **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](CHANGELOG.md) for the migration path (interactive via `/flow-next:setup` or deterministic via `flowctl migrate-rename --yes`, both transactional with rollback).\n\n---\n\n## Quick start\n\n### Install\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eOpenAI Codex\u003c/strong\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cstrong\u003eFactory Droid\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```bash\n/plugin marketplace add \\\n  https://github.com/gmickel/flow-next\n/plugin install flow-next\n/flow-next:setup\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```bash\ngit clone https://github.com/gmickel/flow-next.git\ncd flow-next\n./scripts/install-codex.sh flow-next\n# then: /flow-next:setup\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```bash\ndroid plugin marketplace add \\\n  https://github.com/gmickel/flow-next\n# /plugins → install flow-next\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**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`](plugins/flow-next/docs/platforms.md).\n\n### The 5-command happy path\n\n```bash\n/flow-next:capture                   # 1. Synthesize conversation → .flow/specs/\u003cid\u003e.md\n/flow-next:plan \u003cspec-id\u003e            # 2. Break the spec into dependency-ordered tasks\n/flow-next:work \u003cspec-id\u003e            # 3. Execute tasks in fresh-context worker subagents\n/flow-next:make-pr \u003cspec-id\u003e         # 4. Render a cognitive-aid PR body (9 input streams)\n/flow-next:resolve-pr \u003cPR#\u003e          # 5. Fetch review threads → triage → resolve\n```\n\nThat'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).\n\n---\n\n## How the flow works\n\n```mermaid\nflowchart LR\n    Idea([💡 Idea]) --\u003e P[/flow-next:prospect/]\n    Idea --\u003e C[/flow-next:capture/]\n    P --\u003e C\n    P -.-\u003e|direct via promote| L[/flow-next:plan/]\n    C --\u003e L\n    C --\u003e I[/flow-next:interview/]\n    I --\u003e L\n    L --\u003e W[/flow-next:work/]\n    W --\u003e R[/flow-next:impl-review/]\n    R --\u003e|SHIP| Done([🚀 Ship])\n    R --\u003e|NEEDS_WORK| W\n\n    Done -.maintenance.-\u003e A[/flow-next:audit/]\n    A -.-\u003e M[(.flow/memory/)]\n```\n\nThe loop is spec-driven. Each step below maps to one skill; click through to flow-next.dev for the full page.\n\n### 1. Capture or prospect a spec\n\nEither 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/\u003cid\u003e.md`.\n\n```bash\n/flow-next:capture                    # from a conversation\n/flow-next:prospect \u003cfocus-hint\u003e      # from a focus hint (concept, path, constraint, volume)\n```\n\n→ [flow-next.dev/skills/capture](https://flow-next.dev/skills/capture) · [flow-next.dev/skills/prospect](https://flow-next.dev/skills/prospect)\n\n### 2. Interview to refine\n\nDeep Q\u0026A 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.\n\n```bash\n/flow-next:interview \u003cspec-id\u003e\n```\n\n→ [flow-next.dev/skills/interview](https://flow-next.dev/skills/interview)\n\n### 3. Plan into dependency-ordered tasks\n\nResearch 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.\n\n```bash\n/flow-next:plan \u003cspec-id\u003e             # or \u003cfree-form text\u003e\n```\n\n→ [flow-next.dev/skills/plan](https://flow-next.dev/skills/plan)\n\n### 4. Work through the tasks\n\nExecute 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.\n\n```bash\n/flow-next:work \u003cspec-id\u003e             # or \u003ctask-id\u003e\n```\n\n→ [flow-next.dev/skills/work](https://flow-next.dev/skills/work)\n\n### 5. Open the PR with a cognitive-aid body\n\nRender 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`.\n\n```bash\n/flow-next:make-pr \u003cspec-id\u003e          # auto-detects from current branch\n```\n\n→ [flow-next.dev/skills/make-pr](https://flow-next.dev/skills/make-pr)\n\n### 6. Resolve PR review feedback\n\nFetch 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.\n\n```bash\n/flow-next:resolve-pr \u003cPR#\u003e\n```\n\n→ [flow-next.dev/skills/resolve-pr](https://flow-next.dev/skills/resolve-pr)\n\n---\n\n**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](https://flow-next.dev/ralph)\n\n---\n\n## Why it works\n\n| Problem | Solution |\n|---------|----------|\n| Context drift | **Re-anchoring** before every task — re-reads specs + git state |\n| Context window limits | **Fresh context per task** — worker subagent starts clean |\n| Single-model blind spots | **Cross-model reviews** — RepoPrompt, Codex, or Copilot as second opinion |\n| Forgotten requirements | **Dependency graphs** — tasks declare blockers, run in order |\n| \"It worked on my machine\" | **Evidence recording** — commits, tests, PRs tracked per task |\n| Infinite retry loops | **Auto-block stuck tasks** — fails after N attempts, moves on |\n| Duplicate implementations | **Pre-implementation search** — worker checks for similar code before writing new |\n| Hallucinated specs from \"I think we discussed…\" | **Source-tagged capture** — every acceptance criterion marked `[user]` / `[paraphrase]` / `[inferred]`, mandatory read-back loop |\n| Stale project memory polluting future work | **`/flow-next:audit` + categorized memory schema** — agent reviews each entry, flags stale (never deletes) |\n| GitHub PR review threads piling up | **`/flow-next:resolve-pr`** — fetch → triage → dispatch resolver agents → reply → resolve via GraphQL |\n\n---\n\n## Commands\n\n| Command | What it does |\n|---------|--------------|\n| `/flow-next:strategy` | Write `STRATEGY.md` — target problem, approach, users, metrics, active tracks |\n| `/flow-next:prospect` | Generate ranked candidate ideas grounded in the repo, upstream of `capture`/`interview`/`plan` |\n| `/flow-next:capture` | Synthesize conversation context into a spec (source-tagged, mandatory read-back) |\n| `/flow-next:interview` | Deep spec refinement with lead-with-recommendation + confidence tiers + codebase-first investigation; `--scope=business\\|technical\\|both` |\n| `/flow-next:plan` | Research codebase, create spec + dependency-ordered tasks |\n| `/flow-next:work` | Execute tasks with re-anchoring + worker subagents + review gates |\n| `/flow-next:impl-review` | Cross-model implementation review (RepoPrompt, Codex, or Copilot) |\n| `/flow-next:plan-review` | Cross-model plan review |\n| `/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) |\n| `/flow-next:make-pr` | Render a cognitive-aid PR body (9 input streams) and open via `gh` |\n| `/flow-next:resolve-pr` | Resolve GitHub PR review threads (fetch → triage → fix → reply → resolve via GraphQL) |\n| `/flow-next:audit` | Agent-native review of `.flow/memory/` entries against current code (Keep / Update / Consolidate / Replace / Delete) |\n| `/flow-next:memory-migrate` | Lift legacy flat memory files into the categorized schema |\n| `/flow-next:prime` | 8-pillar agent-readiness assessment with parallel scouts; remediation via consent prompts |\n| `/flow-next:ralph-init` | Scaffold autonomous loop (`scripts/ralph/`) |\n| `/flow-next:sync` | Manually trigger plan-sync to update downstream task specs after drift |\n| `/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` |\n\nFull command reference (every flag, every default) in [`docs/flowctl.md`](plugins/flow-next/docs/flowctl.md).\n\n---\n\n## Ralph (autonomous mode)\n\nRun overnight. Fresh context per iteration + multi-model review gates + auto-block stuck tasks.\n\n```bash\n/flow-next:ralph-init           # One-time setup\nscripts/ralph/ralph.sh          # Run from terminal\n```\n\n📖 **[Ralph deep dive](plugins/flow-next/docs/ralph.md)** · **[Ralph TUI](flow-next-tui/)** (`bun add -g @gmickel/flow-next-tui`)\n\n---\n\n## Where to look\n\nThe repo holds the offline-resilient reference. [flow-next.dev](https://flow-next.dev) holds the narrative, browseable guide. Pick by audience.\n\n| Looking for… | Repo file | Website |\n|---|---|---|\n| 5-minute pitch + install | `README.md` (this page) | [flow-next.dev](https://flow-next.dev) |\n| Adopting in a team, handover objects, Spec-as-PR, adoption ladder | [`docs/teams.md`](plugins/flow-next/docs/teams.md) | [Teams guide](https://flow-next.dev) |\n| Full `flowctl` CLI reference — every command, every flag | [`docs/flowctl.md`](plugins/flow-next/docs/flowctl.md) | — |\n| Ralph autonomous mode internals — hooks, receipts, DCG | [`docs/ralph.md`](plugins/flow-next/docs/ralph.md) | — |\n| `.flow/` directory layout, spec-first task model, ID format | [`docs/architecture.md`](plugins/flow-next/docs/architecture.md) | — |\n| Spec template — R-ID rules, confidence anchors, receipt schema | [`docs/spec-template.md`](plugins/flow-next/docs/spec-template.md) · canonical scaffold at [`templates/spec.md`](plugins/flow-next/templates/spec.md) | — |\n| Memory schema — bug / knowledge tracks, frontmatter, audit lifecycle | [`docs/memory-schema.md`](plugins/flow-next/docs/memory-schema.md) | — |\n| Project glossary — `GLOSSARY.md` shape, R17 forbidden-vocabulary guard | [`docs/glossary.md`](plugins/flow-next/docs/glossary.md) · [`GLOSSARY.md`](GLOSSARY.md) | — |\n| Project strategy — `STRATEGY.md` shape, downstream skill grounding | [`docs/strategy.md`](plugins/flow-next/docs/strategy.md) · [`STRATEGY.md`](STRATEGY.md) | — |\n| Cross-platform install matrix + Codex / Droid / OpenCode notes | [`docs/platforms.md`](plugins/flow-next/docs/platforms.md) | — |\n| `scripts/sync-codex.sh` pipeline, plain-text transform, validation guards | [`docs/sync-codex.md`](plugins/flow-next/docs/sync-codex.md) | — |\n| Troubleshooting — stuck tasks, Ralph debug, receipt validation, uninstall | [`docs/troubleshooting.md`](plugins/flow-next/docs/troubleshooting.md) | — |\n| Adding a new `/flow-next:\u003cname\u003e` skill | [`agent_docs/adding-skills.md`](agent_docs/adding-skills.md) | — |\n| Cutting a release | [`agent_docs/releasing.md`](agent_docs/releasing.md) | — |\n| Local plugin dev + smoke tests + Ralph e2e | [`agent_docs/local-dev.md`](agent_docs/local-dev.md) | — |\n| Repo strategic intent + active tracks | [`STRATEGY.md`](STRATEGY.md) | — |\n| Canonical vocabulary | [`GLOSSARY.md`](GLOSSARY.md) | — |\n| Visual overview, diagrams, methodology | — | [`mickel.tech/apps/flow-next`](https://mickel.tech/apps/flow-next) · [`flow-next.dev`](https://flow-next.dev) |\n\nDoc index with one-line descriptions: [`plugins/flow-next/docs/README.md`](plugins/flow-next/docs/README.md).\n\n---\n\n## Requirements\n\n- **Python 3.8+** — bundled `flowctl` CLI is pure-stdlib.\n- **`jq`** and **`gh`** — required for the review subsystem and PR plumbing.\n- **`bun`** *(optional)* — only needed for the [Ralph TUI](flow-next-tui/).\n\n## Platforms\n\n| Platform | Status |\n|---|---|\n| Claude Code | First-class (canonical surface) |\n| OpenAI Codex (CLI + Desktop) | First-class (mirror at `plugins/flow-next/codex/`, regenerated by `scripts/sync-codex.sh`) |\n| Factory Droid | First-class (regex-OR matchers handle `Execute` ↔ `Bash`) |\n| OpenCode | Community port: [`flow-next-opencode`](https://github.com/gmickel/flow-next-opencode) |\n\nDetailed install + cross-platform patterns in [`docs/platforms.md`](plugins/flow-next/docs/platforms.md).\n\n## Ecosystem\n\n| Project | Platform |\n|---|---|\n| [flow-next-opencode](https://github.com/gmickel/flow-next-opencode) | OpenCode |\n| [FlowFactory](https://github.com/Gitmaxd/flowfactory) | Factory.ai Droid |\n| [Ralph TUI](flow-next-tui/) | Cross-platform TUI for Ralph runs |\n\n## Also check out\n\n\u003e **[GNO](https://gno.sh)** — local hybrid search for your notes, docs, and code. Long-term memory over your files via MCP.\n\u003e\n\u003e ```bash\n\u003e bun install -g @gmickel/gno \u0026\u0026 gno mcp install --target claude-code\n\u003e ```\n\n---\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n\n\u003cdiv align=\"center\"\u003e\n\nMade by [Gordon Mickel](https://mickel.tech) · [@gmickel](https://twitter.com/gmickel) · [gordon@mickel.tech](mailto:gordon@mickel.tech)\n\n[![Sponsor](https://img.shields.io/badge/Sponsor_this_project-❤-ea4aaa?style=for-the-badge)](https://github.com/sponsors/gmickel)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmickel%2Fflow-next","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmickel%2Fflow-next","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmickel%2Fflow-next/lists"}