# Architecture & harnesses Source: https://flow-next.dev/understand/architecture/ How Flow-Next runs inside your coding agent and stores specs, tasks, and evidence in your repository, with a bundled CLI for state changes. Flow-Next is deliberately split between **agent-native skills** and **deterministic flowctl plumbing**. ## Skills own judgment Skills perform work that needs the **host agent’s** judgment - codebase reading, weighing tradeoffs, sequencing, and user clarification (an intelligent LLM, not deterministic code; this is *agent* judgment, not a human approval gate): * `/flow-next:flow` * `/flow-next:capture` * `/flow-next:refine` * `/flow-next:plan` * `/flow-next:work` * `/flow-next:impl-review` * `/flow-next:qa` * `/flow-next:make-pr` The host agent is the intelligence. Flow-Next does not spawn a second LLM from `flowctl` just to make a judgment the current agent can make directly. The one exception is the optional [Jev judge](https://flow-next.dev/guides/jev-judge/): with a key set, `flowctl judge` answers a few narrow hints (fork kind, memory reorder, task tier). ## flowctl owns mechanics `flowctl` is pure Python plumbing for operations that need determinism: * Atomic writes to `.flow/` * Schema validation * Task and spec state transitions * Review receipt validation * Git plumbing * Migration helpers * Backend dispatch wrappers ## Repo-local state ```txt .flow/ ├── specs/ ├── tasks/ ├── memory/ └── review-receipts/ ``` This keeps the install non-invasive and the failure mode obvious. ## Control plane ```mermaid flowchart TB Human["Human intent"] --> Skill["/flow-next skill"] Skill --> Agent["Host agent judgment"] Skill --> Flowctl["flowctl deterministic writes"] Agent --> Repo["Codebase"] Flowctl --> State[".flow state"] Repo --> Review["Review backend"] State --> Review Review --> Receipt["Receipt"] ``` The host agent reads code, asks clarifying questions, judges tradeoffs, and edits files. `flowctl` creates IDs, validates state, writes JSON and markdown atomically, and records transitions. The review backend supplies independent pressure so the same model that wrote the change is not the only reviewer. ## Why this split matters Anything that requires judgment stays in a skill: * Does this spec satisfy the product request? * Which code paths are relevant? * Is a finding introduced by this diff or pre-existing? * What should the PR reviewer read first? Anything that should be deterministic stays in `flowctl`: * Allocate the next spec ID. * Mark a task started or done. * Validate dependencies. * Emit machine-readable receipt JSON. * Migrate repo-local `.flow/` state. This keeps Flow-Next portable across harnesses. Claude Code, Codex, Droid, Grok Build, Cursor, OpenCode, and Muse Code all run the same workflow, because the intelligence is whichever host agent is already in the session. ## Multi-harness model | Harness | Primary role | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Code | Canonical plugin surface and slash-command workflow | | OpenAI Codex | Codex mirror with equivalent skills and subagent dispatch | | Factory Droid | Cross-platform agent runtime support | | xAI Grok Build | First-class. Detected via `GROK_AGENT=1`; canonical Claude files as-is; slash commands; `flowctl` resolved from the plugin install via the skill’s absolute path; both CLAUDE.md and AGENTS.md; `review.backend host` with single-family fail-closed (`grok-4.5`); multi-agent verified | | Cursor | First-class. Team-marketplace repo import recommended; local `install-cursor.sh` / `.ps1` fallback - skills, multi-agent, native asks, `review.backend host` verified | | OpenCode | First-class. Installer-delivered: `install-opencode.sh` scatters canonical skills plus generated agents and flat `/flow-next-` commands into `~/.config/opencode/`, and setup detects the host from the installer’s ownership manifest; multi-agent fan-out, codex-backend review, and host-backend review verified | | Meta Muse Code | First-class. Installer-delivered: `install-muse.sh` builds a Muse bundle with the agents’ tool names translated and their dispatch spelled `flow-next/`, installs and approves it, and setup detects the host from the bundle’s marker file; `/flow-next:` commands; `AGENTS.md`; review through a CLI backend with Muse’s sandbox disabled (`host` is single-family fail-closed); setup through land verified live | The docs use slash commands because that is the user-facing workflow. The CLI reference exists for lower-level automation and debugging. ## Interactive questions on Codex Canonical Flow-Next skills use Claude Code’s `AskUserQuestion` primitive for blocking decisions. The Codex mirror does not call `request_user_input`, because that tool is unavailable outside Codex Plan mode. As of Flow-Next 1.1.2, `sync-codex.sh` rewrites canonical `AskUserQuestion` invocations into plain-text numbered prompts for Codex: ```txt 1. Recommended option 2. Alternative option 3. Other — type your own answer ``` That gives Codex Desktop Default mode, Codex Plan mode, and Codex CLI the same behavior without runtime mode detection. Claude Code and Factory Droid keep their native blocking-question surfaces.