flow-next CLAUDE.md

Claude Code Project Guide

This repo ships the flow-next Claude Code plugin — a spec-driven, zero-dependency workflow for AI-assisted SDLC, with a bundled flowctl Python CLI and autonomous Ralph mode. First-class on Claude Code, OpenAI Codex, Factory Droid, Cursor, xAI Grok Build, and OpenCode (canonical sentence lives in plugins/flow-next/docs/platforms.md — edit there, restate verbatim). The repo IS flow-next.

The repo's strategic intent and canonical vocabulary live at the repo root:

• STRATEGY.md — target problem, approach, who it's for, key metrics, active tracks
• GLOSSARY.md — vocabulary dictionary: the load-bearing terms (Spec, Task, R-ID, Receipt, Gate, plan-sync, ...) with the synonyms to avoid. Deeper concepts live in plugins/flow-next/docs/README.md; the retired long-form text is archived at agent_docs/archive/GLOSSARY-full.md

Every other detail is in a focused file you should consult when relevant — see "Where to look" below.

Stack and tooling

• Python 3.11+ (flowctl), Node ecosystem optional (TUI uses bun).
• jq and gh are required for review-subsystem and PR plumbing.
• Package manager: pick one and stay with it per project. pnpm for the TUI.
• Pre-commit / lint: biome is the source of truth for the TUI; flowctl uses pure-stdlib Python.
• Python lint: ruff, pinned. Run uvx [email protected] check . before opening a PR — CI runs the same pinned version and will fail the build otherwise. No install step; uvx fetches it. Keep the pin in step with .github/workflows/test-flow-next.yml: ruff 0.16 moved its default rule set from 59 to 413, so an unpinned upgrade is an unannounced CI break.
  • ruff.toml is correctness-only (pyflakes, bugbear, pylint errors, a few bug-pattern/security rules) and documents why each notable rule is excluded. Style rules are deliberately out of scope. Do not add a rule to make a diff pass, and do not remove one to make a diff pass — if a rule is wrong for this repo, say so in the config next to the exclusion, with the evidence.
  • Never --fix into .flow/ or plugins/flow-next/codex/; both are generated copies and are excluded for that reason. --unsafe-fixes is not used.
  • The gate is code quality only — it must never change a prompt. Never select a rule that can rewrite string contents (ISC, Q, UP032, COM, W291, D). tests/test_prompt_text_pinned.py pins every embedded prompt constant and on-disk prompt template by SHA-256; a lint or refactor pass that alters prompt text fails there. Changing a prompt on purpose is fine — update the hash in the same commit and say what changed and why. A hash update with no prompt rationale in the commit message is the thing that check exists to catch.
  • Prompt-size ratchets and evidence-ledger live-file freezes were deliberately removed (2026-08-07). Never reintroduce one. No frozen char/token ceilings, no stored-hash pins of live skill prose, no sentence-level prose assertions in tests. Prose growth is judged via .flow/criteria.md G1; test shape is governed by G2; invariants are enforced behaviorally (the fn-169 no-embed test that drives the real dispatch path is the model - text pins watched that decision get undone twice); deliberate-change detection is test_prompt_text_pinned.py only.
  • Embedded *_FALLBACK constants are not all the same kind. The four extracted review prompts are byte-identical mirrors of their templates (fn-112.3, guarded by test_review_prompt_template_parity). VALIDATOR_TEMPLATE_FALLBACK and DEEP_PASSES_FALLBACK are hand-written condensations authored that way in #118 — shorter on purpose, for installs with no template on disk. Do not "sync" them; that is not drift.