DOCSEARCHbyAlgolia
Submit Docs

Flow-Next Documentation

repository·main·Indexed 20 days ago

https://github.com/gmickel/flow-next

An AI agent orchestration plugin and workflow layer providing structural discipline to agentic engineering via a spec-driven approach, adversarial model reviews, and verifiable receipts. Includes the guidance-eval harness for measuring agent performance across different documentation variants and models, and @gmickel/flow-next-tui, a TUI application for monitoring Ralph Mode runs.

Tokens
256.8K
Snippets
622
Records
1K
Agent score
70%

What's inside Flow-Next

  1. Overview of Flow-Next Workflows

    main

    Flow-Next provides specialized workflows for different stages of the development lifecycle:

    • flowctl CLI: The primary interface for command execution and repository mapping.
    • Orchestration (orchestration.md): Manages model routing, subagent tiers, and loop chaining (e.g., pilot+land).
    • /flow-next:chart: An adaptive loop for discovering decision-maps for large, unclear ideas before capturing them as specs.
    • /flow-next:guide: A stateless router that recommends the smallest sufficient workflow for a given task.
    • /flow-next:prime: A triage skill that classifies the repository and verifies that build/test/lint commands actually run.
    • /flow-next:qa: A live-app QA pass that derives scenarios from specs and files structured findings.
    • /flow-next:pilot: A conductor for the plan/work/make-pr loop, featuring optional backlog mode and QA stages.
    • /flow-next:land: A ship-loop babysitter that manages the transition from PR to merge and post-merge cleanup.
    • /flow-next:work: An opt-in implementation-delegation workflow for Codex.

  2. Overview of Autoresearch — repo-scout (Tier 1)

    main

    Autoresearch — repo-scout is an eval-driven optimization process for the plugins/flow-next/agents/repo-scout.md agent. Following the Karpathy/autoresearch methodology (specifically the olelehmann100kMRR/autoresearch-skill approach), the goal is to maximize both accuracy and token efficiency.

    How the Harness Works

    • Agent Execution: The prompt being tested is executed as a read-only Explore subagent.
    • Environment: The agent runs against a FROZEN snapshot of the repository (specifically the HEAD of the opt/autoresearch-tier1 branch).
    • Testing: The agent is tested against 3 fixed inputs defined in test-inputs.md.
    • Evaluation: Each output is scored against 4 binary evaluations defined in evals.md.
    • Optimization Loop: The process applies one mutation at a time. If the mutation improves the score, it is kept; otherwise, the change is reverted.

  3. Overview of Flow-Next Subsystems

    main

    Flow-Next is built on several core subsystems that manage the lifecycle of agentic engineering:

    • Architecture (architecture.md): Defines the .flow/ directory layout (specs, tasks, charts), the spec-first task model, and the fn-N ID format.
    • Skills (skills.md): A catalog of 30 skills (24 slash-commands, 6 phrase-triggers) grouped by lifecycle, autonomy, and maintenance.
    • Spec Templates (spec-template.md): Provides the canonical scaffold for specs, including R-ID rules, confidence anchors, and receipt schemas.
    • Review & Findings (review-findings.md): Defines the structured-findings contract for portable, durable reviews.
    • Memory (memory-schema.md): Manages a categorized memory tree (bug/knowledge tracks) and decision subtrees.
    • Sync & Tracking (tracker-sync.md): Provides the /flow-next:tracker-sync bridge for projecting state and managing conflict queues.
    • Artifacts (html-artifacts.md): Supports optional HTML artifact mode for spec and PR lenses.
    • Self-Improvement (self-improving.md): Describes how the system compounds through memory, glossary, and strategy loops.

  4. Overview of context-scout Autoresearch

    main

    The context-scout is a Tier 1, hot-path scout within the flow-next ecosystem. It is designed for large-scale repository exploration using a specialized prompt (plugins/flow-next/agents/context-scout.md).

    The primary goal of the context-scout is output-budget leverage: producing leaner, more efficient findings that flow into the planner context during every /flow-next:plan operation, while maintaining high coverage and grounding.

    When the primary discovery tool (RepoPrompt rp-cli) is unavailable in a headless subagent environment, context-scout automatically falls back to Standard Tools (Grep, Glob, and Read) to perform its scouting tasks.

  5. Overview of Autoresearch — docs-scout

    main

    Autoresearch — docs-scout is an eval-driven optimization tool designed to find framework or library documentation relevant to a specific change. The output from this tool is intended to flow directly into a planner.

    Its primary goal is to adhere to a "feature-preserving output budget" by following the principle: be a pointer, not a paste. Instead of providing exhaustive code blocks, long excerpts, or full configuration lists, the tool should provide:

    • The specific documentation URLs (the pointers).
    • Key API names mentioned inline.
    • Top critical gotchas.

    This approach avoids the high token costs of full code/option dumps (which can reach ~1200 tokens) by assuming the depth required is only one WebFetch away via the provided links.

  6. Overview of the flowctl CLI

    main

    flowctl is the command-line interface used for tracking tasks and specifications within the .flow/ directory. It is designed to be used by both humans and AI agents, with the strict requirement that Agents must use flowctl for all writes to ensure data integrity and task tracking.

    Key features include:

    • Multi-user safety: Supports parallel branches via merge-safe ID allocation and task assignee fields to prevent duplicate work.
    • Actor resolution: Automatically determines the user identity using the FLOW_ACTOR environment variable, falling back through Git configurations to the system $USER.
    • Validation: Provides local validation to catch issues before committing changes.

  7. Plan-sync gate corpus (fn-83.2) - ARCHIVED

    main

    ⚠️ ARCHIVED: DO NOT USE

    This corpus is archived evidence for a feature (the plan-sync-skip-gate) that was proven non-viable and removed from the shipped CLI (fn-83.4).

    Nothing in this directory constitutes a runnable ship instruction. The following components no longer exist in the shipped plugin:

    • flowctl plan-sync-probe command
    • plansync-gate.jsonl ledger
    • Gate configuration
    • CI corpus check

    Do not attempt to re-implement or run the gate. The decision to remove it is documented in .flow/memory/knowledge/decisions/plan-sync-skip-gate-not-viable-2026-07-03.md.

  8. Overview of Flow-Next commands and skills

    main

    Flow-Next provides a wide array of capabilities through two primary interfaces:

    1. Slash Commands: Invocable as /flow-next:<name>. These include the core development loop (capture → plan → work → make-pr → resolve-pr), review gates (plan-review, impl-review, etc.), and project management (setup, prime, tracker-sync).
    2. Phrase-Triggered Skills: These do not require a slash prefix and can be invoked using natural language. Examples include:
      • flow-next-deps: Analyzes dependency graphs and execution order.
      • flow-next-drive: Drives a running application like a real user (powers /flow-next:qa).
      • flow-next-export-context: Exports RepoPrompt context for external LLM review.
      • flow-next-rp-explorer: Enables token-efficient codebase exploration.
      • flow-next-worktree-kit: Manages worktrees and .env file copying.
      • flow-next: General status queries like "show me my tasks".

    For a full list of all 30 skills, refer to docs/skills.md. For a complete CLI reference, see docs/flowctl.md.

  9. What is the Cua Sandbox SDK and when to use it

    main

    The Cua Sandbox SDK is a tool for driving applications inside an isolated VM or container (any OS). It is specifically designed for headless or CI (Continuous Integration) environments where no physical display is available (e.g., cloud VMs, Linux CI runners, or unattended servers).

    Use Cases

    • Headless/CI Path: Use the Sandbox as the primary driver when there is no real display. It is the only way to drive a native surface in these environments.
    • Attended Path: On a machine with a real display and an operator, the Sandbox is available but not preferred due to higher cost and latency compared to the local Cua Driver. It should only be used if the operator explicitly requires hermetic isolation.

    Scope Limitations

    • The Sandbox is for true-native applications only.
    • Do not use it for web-based apps (like Electron or WebView2) in CI; those should use a headless agent-browser on the web ladder instead.

  10. What is /flow-next:land and how does it work?

    main

    /flow-next:land is an autonomous PR babysitter (a "cadence-tick" driver) designed to manage the lifecycle of Pull Requests authored by the build loop (the "pilot").

    Core Mental Model

    • The Pilot vs. Land: The pilot (/goal-shaped) authors specs and creates draft PRs. Land (/loop-shaped) wakes on a cadence to babysit those PRs through a gate tree (CI $\rightarrow$ patience window $\rightarrow$ review resolution $\rightarrow$ merge gates).
    • The Tick: A single invocation is called a "tick". In one tick, Land discovers open PRs, walks each through the gates, performs at most ONE action per PR, and ends with a terminal LAND_VERDICT line.
    • Non-Interactive: Land is fully autonomous and has no interactive mode. It never asks the user for input; if it encounters ambiguity, it reports NEEDS_HUMAN and exits.
    • Driver Relationship: Land is an alternative to the "Ralph" driver. Never nest them. If FLOW_RALPH or REVIEW_RECEIPT_PATH environment variables are set, Land will refuse to run.
    # Example Driver Commands

# Run every 30 minutes
/loop 30m /flow-next:land

# Run until no more work is found or human intervention is needed
/goal keep running /flow-next:land until it prints LAND_VERDICT=NO_WORK or LAND_VERDICT=NEEDS_HUMAN

  11. What is spec-scout and how does it work?

    main

    spec-scout is an autoresearch 'plan-scout' agent designed to find relationships between a new plan and existing specifications. Its output is intended to flow into /flow-next:plan.

    Its primary function is to identify three types of load-bearing relationships:

    1. Dependencies
    2. Reverse-deps
    3. Overlaps

    To prevent output bloat, the agent is optimized to collapse the 'No Relationship' enumeration (which otherwise lists every unrelated spec) into a simple count, while preserving every real relationship found. This ensures the output remains focused on actionable connections rather than noise.

  12. What is Ralph and when to use it

    main

    Ralph is an autonomous loop harness designed for production-grade, unattended scale. Unlike the standard pilot driver which runs in-session, Ralph uses an external bash loop (ralph.sh) to execute tasks in fresh sessions. This prevents context pollution and ensures a clean slate for every iteration.

    Use Ralph when:

    • You need overnight, unattended execution.
    • Your task run is expected to outlast a single session (e.g., Claude Code loops expire after 7 days).
    • You require high reliability through multi-model review gates and receipt-based proof-of-work.

    Key Differences from Pilot:

    • Scope: Ralph starts from a fully planned spec and iterates through plan-review $\rightarrow$ work $\rightarrow$ impl-review $\rightarrow$ completion review. It does not perform planning or charting. | Aspect | Ralph | Pilot | | :--- | :--- | :--- | | Loop owner | External ralph.sh | Host /loop / /goal | | Session | Fresh per iteration | In-session ticks | | Proof-of-work | Receipts in .flow/review-receipts/ | PILOT_VERDICT in transcript | | Best for | Overnight unattended scale | In-session backlog draining |