STRATEGY.md

name	flow-next
last_updated	2026-10-15
generator	flow-next-strategy

flow-next Strategy

Target problem

AI agent workflows drift, lose context, and produce uneven quality at scale. Existing task trackers (Jira, Linear) optimize for human cadence — 2-3 week implementations with daily standups, mid-flight refinement, and design reviews carrying the weight. Agentic engineering compresses implementation to hours, not weeks; the touchpoints that pre-agentic Agile relied on collapse, and the spec has to carry the full weight upstream. Without structured handovers between idea and merge, agents drift mid-task, reviewers face 10K-line diffs with no focus signal, and quality is uneven across runs.

Our approach

Spec-driven development with re-anchoring, cross-model review, and zero external dependencies. Six named handover objects between idea and merge — each reviewable on its own and frozen at handover, with cross-model verification where configured. Specs are single durable documents that evolve through layers — .flow/specs/<id>.md is the source of truth for goal, architecture, R-IDs, and acceptance, vs alternative split-file approaches (e.g., Kiro's requirements.md / design.md / tasks.md). Skill-driven plugin layered on flowctl Python plumbing; the host agent IS the intelligence (first-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, OpenCode, and Meta Muse Code - canonical sentence in plugins/flow-next/docs/platforms.md), and flowctl provides only thin atomic helpers. Everything lives in the repo under .flow/ — no external services, no global config, no SaaS. Uninstall: delete the directory.

Opt-in convenience skills (e.g. /flow-next:map wrapping clawpatch) may carry their own runtime prerequisites, but flowctl core never imports or requires them — the zero-dep contract holds for the base install; opt-in skills add nothing to the uninstall path beyond a single self-contained directory.

A ready cohesive spec should run through /flow-next:work <id> --no-plan with a capable coding agent when decomposition adds no coordination value. Planning remains useful for dependencies, separate ownership, staged delivery and execution constraints. Material product or authority choices need refinement; implementation details can remain with the owner. Risk and file count determine relevant verification, not whether tasks must be decomposed. Explicit spec/design review works before tasks exist; configured implementation review, acceptance coverage, completion-review policy and opt-in QA remain unchanged. /flow-next:flow is the one dial on this opinionated default path. Attended, it reads whatever the user has, routes from one shared routing reference, runs the route, and stops at the next decision that is the user's; flow --auto runs the same reference unattended, hop after hop to a draft PR, stopping only where a human is needed. One judgment, two entry shapes; /flow-next:pilot is the one-release alias for flow --auto --tick.

Design principles

Standing rules that decide day-to-day build questions. Each earned its place through a shipped decision; the anchors are the receipts.

• The artifact is the contract. Nothing between the plan and an executor restates content that lives in a file - prompts carry pointers and rails; every executor (native worker, bridged CLI, scout, runner) reads the spec/task files as its brief. Quality budget therefore concentrates in the spec and its acceptance contract, whether captured directly or refined during planning; a thin artifact is refused downstream (the worker's thin-task valve), never compensated for. (Anchor: fn-103 / decision record composed-brief-deleted-path-handoff-2026-07-19 - an 8-run eval deleted the composed delegation brief.)
  • The reviewer is an executor too - identities, not payloads. A review prompt carries the rubric, a <base-sha>..<head-sha> range, resolvable paths, and the reply grammar; it never carries the diff body, the spec body, or re-rendered prior findings. The reviewer has a shell and a checkout and already fetches. Two consequences that are not negotiable: a prompt-payload fitter or truncator is evidence the payload is wrong (a genuine transport cap is a separate thing and is named as transport), and prior findings come from session continuity or a receipt path, never a re-render. This was decided once in fn-74, re-accreted twice by fn-90 and fn-159, and cost a false-SHIP hole plus reviewers seeing ~10% of a 495 KB diff - so it is enforced by a test, not by prose. (Anchor: fn-169; the re-accretion history is the argument.)
• flowctl grows only under burden of proof. flowctl is thin atomic plumbing - hashes, path membership, schema validation, receipts, git mechanics. A subcommand is added only when the operation involves zero judgment and must work with no agent in the loop; anything that reads, weighs, or decides belongs to the host agent. Deterministic proxies for judgment questions are banned outright (anchor: plan-sync-skip-gate-not-viable-2026-07-03); the periodic audit that keeps this honest is the fn-101 pattern - classify every subcommand keep / leakage / vestigial, burden of proof on keeping, and on adding.
• Agent first. The agent decides; flow-next records what it decided. A spec or skill never makes the agent fill a form before it may act: no required fields, fixed labels, enums, validator rules, new judge kinds, template sections, flowctl verbs, checks or gating stops that stand between the agent and the work. A routing-matrix row that describes a new starting state is not on that list: it is guidance the agent reads while routing, adds no field, check or stop, and is judged by whether requests route correctly. The agent chooses, writes its choice where a human reviews it (a ledger, the PR, a spec section written after acting), and stops only for what is genuinely the human's: a target, an authority, a product call. A new mechanism names the unattended-trust failure it prevents; "the agent might not think of it" is a sentence of guidance, not a mechanism. Every added stage, field and check costs every run, so the default answer to "should this be a mechanism?" is no, and machinery a model no longer needs is deleted. (Anchors: fn-265's nine-field pre-registration stopped unattended runs for values the agent could choose, and fn-273 replaced it with the agent setting up the experiment, 139 lines to 33; fn-267 and fn-269 were trimmed from a schema field with a proof enum and a new judge kind with mandatory labels to a few sentences of guidance before they were built, 2026-09-28. Routing rows were split out of this list on 2026-10-15: what made the first fn-269 draft machinery was its judge kind and mandatory labels, not its row.)
• Remember the bitter lesson. Do not build scaffolding around a model's current weaknesses - capability grows and the scaffolding rots into cost (the composed brief was exactly this). Before adding a compensating mechanism, try stating the bar in one general sentence; before keeping one, eval it against its absence with pre-registered bars and delete on evidence. Deterministic machinery is reserved for what models should never own regardless of capability: unattended-trust rails (receipts, rollback, guard shapes, schemas), not quality compensation.
• The owner holds the license. Whoever implements owns delegation: the in-host worker on the standard path, the bridged child when the implementer tier reaches a model over a CLI bridge. Wrappers, scouts, and conductors never fan out on the implementer's behalf, because delegation by someone with no stake in the result is not ownership. Safety rules bound push, history rewrite, scope, verdict, and nested bridges, never the owner's own delegation; a never-list that grows past those five has narrowed the owner without a requirement and is a review finding. (Anchors: #436, where "never spawns a bridge of its own" widened to "never spawn another agent or bridge" through three checks; the September 2026 no-plan owner screens, which tied the direct route's quality to one owner seeing the whole task end to end.)
• Consent comes from a person. An unattended run acts only on an explicit act of a person, such as a ready flag, a board move, or a merge destination passed on the current invocation. It never infers consent from a score, a transcript, an environment variable or a receipt. Each mode's skill text enforces what that mode may author, promote and merge; a new mode or flag names which explicit act it rests on rather than carving an exception into another mode's rules. (Anchors: fn-68 backlog mode moved where the loop asks a person without moving who promotes; --until=merge consent is read from the current invocation and never recovered.)
• Receipts are the portable product boundary. Downstream tools consume versioned, additive receipt fields with explicit identity, snapshot binding, lineage, bounds, and labeled fallback. They never depend on Flow-Next's parser or skill internals, and they never turn stale or ambiguous evidence into current state. (Anchors: fn-136 structured findings 3.9.0; fn-137 criteria compliance receipts 3.10.0; fn-138 published config schema 3.12.0 - the principle graduated from aspiration to receipted rule.)

Who it's for

Solo developers running multi-agent loops who need re-anchoring + receipts to keep agents on track overnight. Engineering teams adopting spec-driven development who need an artefact chain that replaces standups / refinement / design-review touchpoints. Platform owners building autonomous agent harnesses who need cross-model review gates and proof-of-work receipts. Also flow-swarm operators (in-progress companion product reading .flow/specs/ natively).

Key metrics

Counts and versions below are dated observations, not current inventory. Read the manifests and CI workflow for live counts. Track descriptions preserve product intent; historical rollout detail is labeled separately from current mechanics. This clarification does not set a new roadmap.

• Smoke-test surface and parity. Number of smoke suites × OS matrix (historical snapshot: 10 × Linux/macOS/Windows, plus Cursor-install, python-probe, and Windows-launcher jobs). Cross-platform parity across Codex / Droid / Cursor / Grok Build (and the OpenCode install path) is non-negotiable.
• Slash-command count and density. Each command is a discrete handover. 23 commands / 28 skills / 21 subagents at 3.12.0; 28 commands / 32 skills / 20 subagents at the flow release (flow replaced guide, so the command count stayed flat); 27 commands / 31 skills / 21 subagents at the flow --auto release (pilot folded into flow as --auto, the why-scout joined; the registry inventory also carries the one-release interview and pilot alias stubs, so it reads 27 commands / 33 skills until the stubs are removed; their command shims are gone); 26 commands / 30 skills / 21 subagents at 7.0.0; additions must justify a new handover, not a convenience alias (the retired epic-review alias was removed entirely in 3.3.1).
• OpenCode-path adoption. The in-repo install-opencode.sh is the OpenCode adoption signal (the flow-next-opencode port is superseded and archived as a pointer); FlowFactory predates native first-class Droid support and is historical evidence, not the current Droid story.
• Spec-driven adoption signal. Inbound traffic to docs/teams.md and the AI-x-SDLC-Starter-Kit cross-link as proxy for team adoption.
• Idea-to-merge wall-clock. Time from /flow-next:capture to /flow-next:make-pr body landing on a draft PR. Worth measuring as the system matures.

Tracks

v1.0 vocabulary stability (SHIPPED)

Complete. fn-43 (epic→spec rename) shipped in 1.0.0 (2026-05-09) with the full alias layer; the aliases outlived the original "until 2.0" plan and were removed telemetry-driven in 3.0.0 (fn-111) along with the pre-1.0 migration machinery. Kept as history because the contract it established - canonical vocabulary, never-silent migration - still governs renames.

Spec-driven team patterns

docs/teams.md (handover objects, Spec-as-PR, parallel work from one spec, R-ID frozen-at-handover, symmetric interview, adoption ladder, and since 3.10.0 standing project-wide criteria: a user-owned .flow/criteria.md of G-IDs judged by the completion review on every spec). Cross-linked from the AI-x-SDLC-Starter-Kit methodology guide. Establishes flow-next's identity as a methodology, not just a tool.

Autonomous mode

Current direction: flow --auto and land (pilot is the one-release alias for flow --auto --tick). Shipped follow-ups include parallel-draw review (fn-215, 4.12.0) and rolling work scheduling (fn-218). The paragraph below records the earlier rollout and rationale; consult current orchestration docs for execution details.

The autonomy track — a loop suite (pilot 1.13.0, land 1.14.0; land gained the structural authorship marker and the FLOW_PR_CREATE_CMD identity seam in 3.11.0; pilot's judgment moved onto the flow routing reference as flow --auto in the release after 5.0, with pilot kept one release as the flow --auto --tick alias). flow --auto + land are the default path: flow --auto builds (ready spec → [optional plan/design review] → work → configured reviews → [opt-in qa] → make-pr closes completed specs → draft PR, hop after hop in one invocation; --tick runs one hop where a host /loop//goal drives repetition), land ships (draft PR → CI-fixed → review-converged → gated merge); releases follow the repository's release instructions separately; run concurrently in separate clones they form the full assembly line, with the readiness gate / tracker board as the consent boundary. An optional live-app QA stage (pipeline.qa, off | on | auto, default off, fn-72) sits between work and make-pr; auto runs it only for specs whose acceptance describes a drivable UI surface, and pilot activates the stage only on on. With it on, pilot drives the running build like a real user at all-tasks-done and surfaces runtime/UI breakage into the draft PR — autonomy-safe (never prompts, never hard-blocks; NEEDS_WORK still advances), and it augments, never replaces CI/staging/manual QA. An opt-in backlog mode (pilot.autonomy=backlog, default off, fn-68) widens pilot from "one already-ready spec" to standing management of the whole open backlog — per tick it enumerates flow specs + tracker issues, triages the top dep-ordered item, and either advances it or surfaces a precise async question; this moves where the loop asks a person, from before the loop to inside the loop, on block, without moving who consents: promotion stays the person's board act and land stays human-gated (Consent comes from a person). The per-tick decision log (flowctl pilot-log) is the factory-efficiency readout and the self-improvement substrate. Packaged codex delegation (work.delegate*, fn-55) was deprecated in favor of the agentic route — the setup CLAUDE.md routing scaffold plus the flowctl usage bridge recipes — and flow-98 then removed it outright. docs/running-lean.md names the human-driven and autonomous operating profiles and prices every optional layer so running lean is a deliberate choice rather than a missing setup. Quality discipline is invariant across all: multi-model review at every handover, convergence-aware review terminals (explicit prior-finding resolution, bounded rounds, and reviewer-emitted NEEDS_HUMAN), don't-thrash reflexes (two-strike unready / auto-block / bounded CI fixes), evidence over narration, surface-don't-force. Differentiator from autonomous loops that run open-loop without quality gates. The cloud-orchestration role (scheduler, hosted environments, multi-agent-at-scale, the production monitor→triage loop) is mergefoundry's, not flow-next's — fn-68 is the governed, in-repo per-tick conductor such a control plane invokes.

flow-swarm preparation (contract pillars SHIPPED)

The portable-contract surface flow-swarm consumes without importing Flow-Next internals is now shipped: structured review findings with durable IDs, snapshot-bound anchors, and explicit currentness (fn-136, 3.9.0); per-criterion compliance in ordinary receipts (fn-137, 3.10.0); and a published JSON Schema for the full config surface at flow-next.dev/schema/ (fn-138, 3.12.0). Legacy prose remains a safe labeled fallback throughout. Historical coordination gap recorded at 3.0.0 (verify downstream status before acting): flow-swarm read the pre-1.0 epics JSON key and forwards --epic flags (flagged at 3.0.0) and must migrate to the canonical spec surface. Coordination timing remains downstream product work; Flow-Next owns the stable handover objects.

Tracker determinism

The fn-139-141 batch (3.5.2-3.6.1): the four-provider tracker bridge's repeatable machinery - auth boundaries, provider selection, pagination, create-if-unlinked, status transitions, relations, PR links, comment-marker dedup, locks, one aggregate receipt - moved from skill prose into the deterministic flowctl_tracker/ package, deleting four growing per-provider API recipes and cutting reached-path prose ~70%. Every semantic judgment (discovery, three-way body conflicts, lifecycle-comment content, structured recovery) stays in the host; the facade supersedes fn-57 R3's prohibition on tracker mutations in flowctl because the mutations carry zero judgment. The template for future "prose that grew into plumbing" extractions.

Cross-platform parity

First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor (3.3.0), xAI Grok Build (3.4.0), OpenCode (4.3.0, installer-delivered), and Meta Muse Code (installer-delivered); (canonical roster sentence: plugins/flow-next/docs/platforms.md). Canonical skill files use Claude-native tool names; sync-codex.sh rewrites for the Codex mirror; Cursor/Droid/Grok consume canonical files as-is, so Claude-only references need portable fallbacks. What parity means mechanically: the fn-121 plugin-vs-copy setup modes and the fn-139 tracker-manifest install-integrity contract. Single source of truth.

Self-improving through normal work

The system compounds as a side-effect of normal use — memory accretes from review fix-cycles, the glossary is seeded by prime and grows through refine/capture while plan/work/review read it back, decision records land when judgment calls happen, and strategy drift is surfaced by the skills that consume the doc. Never a manual compound/refresh ceremony: improvement that depends on remembering an extra command doesn't happen. Audit is the garbage collector, not the growth mechanism.

Milestones

Historical roadmap snapshot through August 2026; the open items below are not revalidated commitments or a new priority ordering. Check current specs and downstream state before scheduling them.

• DONE 2026-05-09 — flow-next 1.0.0 (shipped early, Q2). fn-43 + alias layer; the stable .flow/ contract flow-swarm needed. Since then: 2.0.0 (2026-06-12, render lenses), 3.0.0 (2026-07-21, alias removal + Ralph opt-in + dead-surface sweep), 3.12.0 (2026-07-31, the fn-136/137/138 portable-contract series complete).
• Next — flow-swarm contract consumption. flow-swarm migrates off the epics key and renders structured findings + criteria compliance from receipts; first end-to-end swarm-driven pipeline run against a published-schema config.
• TBD — flow-swarm v1. Reads .flow/specs/ directly; coordinates parallel agents across worktrees; consumes the PR-as-cognitive-aid walkthrough (the portable contract for it shipped in fn-136).
• TBD — Spec-driven team adoption case study. First public team writeup using the methodology guide. Validates the framing externally.

Not working on

• Hosted dashboards or SaaS tier. The whole architecture is "everything in the repo"; a hosted layer breaks the uninstall promise (rm -rf .flow/).
• Built-in CI runners. CI is the user's; flowctl provides validate --all for pipeline integration but does not run the pipeline.
• A graphical builder. The host agent IS the UI — adding a separate GUI splits the maintenance surface for negative product value.
• Replacing Jira / Linear for human-only teams. flow-next is for agentic-engineering teams; teams without agents should keep their existing tracker.
• Localization of CLI strings or skill workflow text. English-only; the original through-1.x wording was a historical horizon, not a new localization commitment.