git:20260904.a723015 to git:20260905.537c567

- # 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`](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`](STRATEGY.md) — target problem, approach, who it's for, key metrics, active tracks

- - [`GLOSSARY.md`](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`](plugins/flow-next/docs/README.md); the retired long-form text is archived at [`agent_docs/archive/GLOSSARY-full.md`](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 ruff@0.16.0 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.

-

- ## Architecture: agentic vs deterministic (READ BEFORE PLANNING NEW FEATURES)

-

- flow-next is a **skill-driven plugin running inside an agentic coding environment** (host platforms: Claude Code, Codex, Factory Droid, Cursor - see the roster below). The host agent IS the intelligence. Default to skill-based architecture; reach for deterministic Python in flowctl only when there's a real reason.

-

- ### When to use a SKILL (the default)

-

- A workflow that walks files, makes per-item judgments, investigates code, composes multi-step actions where each depends on prior context, asks the user on ambiguous cases, and could reasonably be invoked via `/flow-next:<command>`.

-

- → **Build it as a skill.** The host agent reads the skill workflow file, executes via existing Read/Grep/Glob/Edit/Write tools, dispatches subagents via the platform primitive (`Agent`/`Task` in Claude, `spawn_agent` in Codex), asks via `AskUserQuestion`. Canonical files use Claude-native tool names; `sync-codex.sh` rewrites for the Codex mirror.

-

- **Do not spawn `codex`/`copilot`/other LLMs via subprocess from inside flowctl when invoked from a skill.** The host agent is already an LLM running the skill — there is no need for a second one.

-

- **Implementation offload is prose-routed, not packaged (flow-98 decision).** The `work.delegate*` subsystem is gone: bridging implementation to a second CLI (`codex exec`, `cursor-agent`, `claude -p`, `grok`) is a routing decision the host reads from the model-routing section in `CLAUDE.md` / `AGENTS.md` plus the bridge recipes in `flowctl usage`, and it is **host-orchestrated implementation-offload, never a judgment hand-off**: the bridged child writes code while the host keeps git, judgment, and the verdict. Nothing about that route licenses spawning an LLM for judgment from inside flowctl. See [`docs/orchestration.md`](plugins/flow-next/docs/orchestration.md#implementation-offload-the-bridge-route).

-

- ### When to use DETERMINISTIC flowctl Python

-

- Mechanical operations needing to work without an agent in the loop: Ralph hooks (PreToolUse / Stop / SubagentStop matchers), receipts (review / walkthrough / ralph_blocked), schema validation, atomic file writes, git plumbing, the triage-skip whitelist, the review-subsystem backend dispatch (`flowctl rp`, `flowctl review-backend`).

-

- → **Build it in flowctl Python.** Pure plumbing, no intelligence required.

-

- ### The common pattern: SKILL + thin flowctl plumbing

-

- Most features look like this. Skill drives the workflow; flowctl provides atomic helpers the skill calls. Examples: `/flow-next:prospect` skill + `flowctl prospect list/read/promote`. `/flow-next:audit` skill + `flowctl memory mark-stale`.

-

- **Split rule:** flowctl owns "set this field" / "validate this schema" / "atomic-write this file" / "list these things." Skill owns "read this and judge" / "compose multi-step decision flow" / "ask user when unsure" / "dispatch subagents."

-

- ### How to spot a mistake

-

- Symptoms suggesting deterministic when you should build skill-based:

- - Writing regex to extract "code references" from prose → host agent can read prose

- - Building a stoplist of common English words → host agent knows English

- - Spawning `codex --exec` to make judgments → host agent makes judgments

- - Parsing structured-verdict YAML from an LLM response → host agent's own structured output

- - Building a deterministic "fallback" engine for when LLM unavailable → host agent is always available

- - Weighted scoring math substituting for "is this still relevant?" → host agent answers directly

- - **Embedding content into a prompt that the agent could fetch itself** → pass an identity (a SHA range, a path), not a payload

- - **Writing a fitter / truncator / budget constant for a prompt payload** → the payload is the bug; a fitter is the symptom. Genuine *transport* limits (an argv cap) stay, and are named as transport

- - **Enumerating the ways something could be done wrong** (writer APIs, path spellings, command shapes) → an enumeration is a race against the next spelling; put the invariant where it is true by construction

-

- If three or more apply, stop and convert to a skill. The deterministic path is harder to maintain, more brittle, and produces worse output.

-

- **Sanctioned carve-out (subprocess LLM judgment):** do not "fix" these licensed cases when the symptom list matches. Review-backend dispatch and the triage-skip judge may spawn a subprocess LLM for judgment. Rationale: cross-model verdicts about pipeline-written code must not be self-issued by the host.

-

- ## Cross-platform patterns

-

- **HOST PLATFORM ROSTER (memorize - do not forget any of these when building features):**

-

- | Host | Mechanism | Consumes |

- |---|---|---|

- | Claude Code | canonical plugin (`.claude-plugin/`) | canonical files as-is |

- | Codex | pre-built mirror at `plugins/flow-next/codex/`, regenerated by `scripts/sync-codex.sh` | REWRITTEN copies (tool names, ask fallback, dispatch phrases) |

- | Factory Droid | auto-translates the Claude plugin format on install | canonical files as-is (`DROID_PLUGIN_ROOT` alias) |

- | Cursor | RECOMMENDED: team-marketplace repo import (root `.cursor-plugin/marketplace.json`); fallback: `scripts/install-cursor.sh` / `.ps1` (blanket rsync to `~/.cursor/plugins/local/`, excludes codex/ + tests/); manifest at `plugins/flow-next/.cursor-plugin/plugin.json` | canonical files AS-IS - no rewrite pass exists |

- | Grok Build | reads the Claude plugin format directly (compat, verified) | canonical files as-is |

- | OpenCode | installer scatter (`scripts/install-opencode.sh` -> `~/.config/opencode/`; skills as-is, support dirs `scripts/`+`templates/`+`references/`+`docs/` at the config root — plugin-root geometry, so relative docs links resolve; generated agents/commands; setup detects via the ownership manifest) | canonical files + support dirs + generated glue |

-

- **Architectural rule:** canonical skill files use Claude-native tool names; `sync-codex.sh` rewrites them in the Codex mirror. Skill prose stays concrete; cross-platform maintenance lives in one place — the sync script. Cursor/Droid/Grok get NO rewrite pass, so anything Claude-specific in canonical prose must either work there or carry an explicit portable-host clause.

-

- **Checklist when adding/editing skills, agents, or hooks (walk ALL of it):**

-

- 1. Run `./scripts/sync-codex.sh` TWICE (idempotency) and commit the mirror diff with the canonical change. Its validation guards must stay green; new Claude-only phrases (tool dispatches, model-name examples) may need a new transform + hard-fail guard (pattern: the fn-100 Explore-dispatch and scout-tier rules).

- 2. Claude BUILTIN references (`Explore`, `general-purpose`, `AskUserQuestion`, model names) are invisible to the Cursor/Droid/OpenCode consumers (all three read canonical prose as-is) - every such reference needs a portable-host fallback clause in the canonical prose (generic read-only dispatch with Edit/Write disallowed; plain-text numbered-prompt fallback for asks) or graceful degradation stated inline.

- 3. Plugin-root env vars: Cursor and Grok expose NONE - every bash preamble carries the three rungs in order: `${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl`, then the plugin root derived from the skill's own SKILL.md absolute path (two levels up), then the legacy `.flow/bin/flowctl` backstop. Setup copies nothing into a repo; on Claude Code bare `flowctl` also resolves via bin-PATH injection in plain Bash ONLY - never in skill prose.

- 4. No plugin-level hooks (`plugins/flow-next/hooks/` is gone): Ralph registration is agent-driven via `/flow-next:ralph-init` (merge fingerprinted entries into project settings per host). Guard matchers stay Claude-schema (`PreToolUse`/`Stop`, `Bash|Execute` shell + file-tool set); works on Claude Code + Droid, NOT Cursor (different hook events) - never assume the guard fires there.

- 5. Installers need no enumeration updates for SKILLS (Cursor installers blanket-copy; the codex mirror is a full regen; the OpenCode installer blanket-scatters) - with two exceptions: (a) the codex mirror's `phases.md` 3c is a HARDCODED heredoc in `sync-codex.sh` (`SECTION3C`), so canonical 3c edits must land in the heredoc too or the mirror goes silently stale at exit 0; (b) a new AGENT (or new agent-frontmatter key) must extend the closed allowlist in `plugins/flow-next/scripts/lib/opencode_generate.py` — it fails loudly (`GenerateError`) at OpenCode install otherwise. `plugins/flow-next/docs/platforms.md` DOES need a note when host behavior differs.

- **Validate at the CONSUMER's layout, not the producer's** (PR #363 lesson: three review rounds came from checking only the repo tree while the real consumer is the installed `$CODEX_HOME` — shallower, partial, different invocation syntax). `sync-codex.sh` now carries hard-fail guards for the whole class: mirror docs-link resolution, the installed-docs link-universe closure (resolve on disk or absolute URL), and actionable-invocation rewrites (`/flow-next:` → `$flow-next-`). A canonical edit that adds a docs link or a user-copyable command is covered by those guards — **a guard failure is load-bearing; fix the content or extend the transform, never relax the guard.**

- 6. `agents/*.md` model fields are family aliases resolved by the host; on non-Claude hosts they map to host defaults - never version-pin, and never assume a specific tier is honored off Claude Code.

-

- - **Variable references** — bash fallback: `FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"`. Droid sets `DROID_PLUGIN_ROOT` and also exposes `CLAUDE_PLUGIN_ROOT` as an alias (per Factory docs, "Alias for `${DROID_PLUGIN_ROOT}` (Claude Code compatibility)"). The fallback order is conservative but correct on both platforms. *(Last verified against Factory docs 2026-05-25 — fn-48.2.)*

- - **Hook matchers** — regex OR: `"matcher": "Bash|Execute"` (Claude `Bash`, Droid `Execute` — Factory hooks-reference 2026-05-25 still lists `Execute` as canonical and `Bash` as not recognized).

- - **Agent permissions** — `disallowedTools` blacklist (not `tools` whitelist). Tool names differ across platforms; blacklist works because both understand `Edit`, `Write`, `Task`. Read-only agents deny all three — `Task` because a spawned writing subagent is an escape hatch out of read-only; writing agents deny only the subset they must not use (plan-sync: `Write, Bash`; worker and pr-comment-resolver: none). `Task` is subagent dispatch (renamed Agent in Claude Code v2.1.63), not a planning tool.

- - **Plugin paths** — flow-next is a Claude-first plugin; use `${PLUGIN_ROOT}/.claude-plugin/plugin.json` directly. Droid auto-translates Claude Code plugin format on install (Factory docs: "Droid is compatible with plugins built for Claude Code… the plugin format is interoperable"), so a `.factory-plugin/plugin.json` fallback is **not** needed for Claude-first plugins like flow-next. Native Droid-first plugins (e.g. Factory-AI/factory-plugins marketplace) ship `.factory-plugin/plugin.json`; we don't.

- - **Blocking-question tool** — every interactive skill MUST use the platform's blocking primitive. Canonical writes `AskUserQuestion`; `sync-codex.sh` transforms canonical invocations into a plain-text numbered-prompt instruction (with `N+1. Other — type your own answer` as the final option) for the Codex mirror — the mirror never mentions `request_user_input` (Plan-mode-only per openai/codex#10384/#11536/#12694; closed without resolution as of Feb 2026). Droid (currently) sees the canonical name. Always bare `AskUserQuestion` in canonical files; an optional parenthetical breadcrumb noting the rewrite is fine.

- - **Subagent dispatch** — canonical writes `Task` with `subagent_type: Explore`; sync rewrites to `spawn_agent`. Read-only enforcement via `disallowedTools: Edit, Write, Task`.

-

- ## Editing rules

-

- - Keep prompts concise and direct.

- - Avoid feature flags or backwards-compatibility scaffolding (plugins are pre-1.0 except flow-next 1.0+).

- - Do not add extra commands / agents / skills unless explicitly requested.

- - For pure docs / agent_docs / README changes, do NOT bump the plugin version.

- - **Skill prose changes are reviewed against the skill's conduct checklist** in [`agent_docs/conduct/`](agent_docs/conduct/README.md): load it when a PR or change touches a skill's prose and use its items as the review criteria. The checklists are review rubrics, not handoff ceremony — no dogfood run or per-item pass/fail record is required to merge.

- - **Recorded decisions are settled.** A decision recorded in a spec's Decision Context, or ruled by the maintainer on the PR, is not up for re-litigation: reviewers (human or bot) may note disagreement as FYI, never as a merge-gating finding. Re-raising a recorded decision as blocking is itself a review defect. The maintainer decides when a change lands; process-compliance observations (missing ceremony, checklist records, dogfood runs) are never merge-gating.

- - **Docs-tree changes still run the FULL gate here — the classifier's tier-B verdict is not a licence to skip it.** `flowctl gate classify` calls `agent_docs/**`, `plugins/flow-next/docs/**.md`, and root `README*`/`GLOSSARY.md`/`CHANGELOG.md` docs-only (lint/format only), but this repo's unit suite pins content in every one of them — conduct checklists, prose contracts, dictionary shape — so a "docs-only" edit can break a pin. Run `python3 scripts/run_tests_parallel.py` before handing off. This is the conductor-instructions half of the documented remedy for the classifier's known fail-open (see "Known fail-open" in [`plugins/flow-next/docs/flowctl.md`](plugins/flow-next/docs/flowctl.md)); the CI half is the `paths:` filter in `.github/workflows/test-flow-next.yml`, pinned by `test_ci_trigger_coverage`.

- - **Version bumps are batched, not per-spec.** When implementing a spec, land the code + docs + an `## Unreleased` CHANGELOG entry (repo + docs-site), but do NOT run `scripts/bump.sh` or touch the version manifests / `FLOW_NEXT_VERSION`. The release + version-number decision is made separately, later, across several accumulated specs — to avoid version churn. Spec/task acceptance that says "bump to X.Y.Z" means *stage under `## Unreleased`*; the actual bump happens at the batched release.

-

- ## PR workflow

-

- - **PRs derived from a flow-next spec** → use `/flow-next:make-pr <spec-id>`. It generates a cognitive-aid PR body (R-ID coverage table, critical-changes summary, decision context, "where to look") from the spec export. Never hand-write a body when a spec exists — the skill carries discipline the manual version drifts away from.

- - **Chore PRs without a spec** (version bumps, small mechanical fixes, CHANGELOG-only changes, third-party-reported regressions) — write the body manually but match the make-pr structure: short summary + What changed + Verification + Version note (or "no version bump per CLAUDE.md docs-only rule" if applicable). Don't open bare-body PRs.

- - **Review feedback on any PR** → `/flow-next:resolve-pr` (auto-detects PR from current branch). Resolves threads via dispatched resolver agents, validates combined state, replies + resolves via GraphQL. Bounded at 2 fix-verify cycles before escalation.

- - **No direct `gh pr merge` from skills.** Merge is a human decision; do it explicitly when the PR is ready. Sole confined exception: the opt-in `/flow-next:land` ship loop merges explicitly (`--squash --match-head-commit`, never `--auto`) after its full gate tree passes — that license is bounded to land and extends to no other skill.

-

- ## Docs site

-

- - A public docs site exists at **`https://flow-next.dev`** (source repo `~/work/flow-next.dev`). User-facing changes — behavior, commands, setup, public vocabulary, README, release notes — should be reflected there in the same workstream. **The detailed update/release workflow for the docs site, and the maintainer's other downstream/narrative properties, live in the maintainer's *private* config — not this committed file** (they reference maintainer-local repos/paths that other contributors don't have).

- - **Both changelogs are user-facing release surfaces** (`CHANGELOG.md` becomes the GitHub release body; flow-next.dev is the shorter public story). Write user-outcome-first, machinery last; the full ordering rules, hard rejection test, and examples live in [`agent_docs/releasing.md`](agent_docs/releasing.md) - follow them for every entry.

-

- ## Where to look

-

- | For | Look at |

- |---|---|

- | Plugin overview + install + 5-command quick start | [`README.md`](README.md) (root) — canonical entry point |

- | Full doc index (subsystem + workflow references) | [`plugins/flow-next/docs/README.md`](plugins/flow-next/docs/README.md) |

- | Spec-driven team workflow + handover objects | [`plugins/flow-next/docs/teams.md`](plugins/flow-next/docs/teams.md) |

- | Build-loop conductor (`/flow-next:pilot` — single-tick spec-to-PR pipeline; host `/loop`/`/goal` drives) | [`plugins/flow-next/skills/flow-next-pilot/SKILL.md`](plugins/flow-next/skills/flow-next-pilot/SKILL.md) |

- | Ralph autonomous mode internals | [`plugins/flow-next/docs/ralph.md`](plugins/flow-next/docs/ralph.md) |

- | Orchestration & model routing (steering tiers, review-backend precedence, the bridge route for implementation offload, CLAUDE.md model tables, pilot+land chaining) | [`plugins/flow-next/docs/orchestration.md`](plugins/flow-next/docs/orchestration.md) |

- | Full `flowctl` CLI reference | [`plugins/flow-next/docs/flowctl.md`](plugins/flow-next/docs/flowctl.md) |

- | `.flow/` directory layout + spec-first task model | [`plugins/flow-next/docs/architecture.md`](plugins/flow-next/docs/architecture.md) |

- | Memory schema (bug/knowledge tracks, audit lifecycle) | [`plugins/flow-next/docs/memory-schema.md`](plugins/flow-next/docs/memory-schema.md) |

- | Tracker-sync bridge (projection model, hybrid ids, deterministic `flowctl tracker` transport; `/flow-next:tracker-sync` ≠ `/flow-next:sync`) | [`plugins/flow-next/docs/tracker-sync.md`](plugins/flow-next/docs/tracker-sync.md) |

- | Live-app QA (`/flow-next:qa` — opt-in; drives the running app, never passes by reading source) | [`plugins/flow-next/skills/flow-next-qa/SKILL.md`](plugins/flow-next/skills/flow-next-qa/SKILL.md) |

- | User-POV drive map (`/flow-next:features` - seed or maintain `.flow/features/` for QA and drive) | [`plugins/flow-next/skills/flow-next-features/SKILL.md`](plugins/flow-next/skills/flow-next-features/SKILL.md) |

- | Opinionated agent-readiness assessment (`/flow-next:prime` - classify, operability verdict, ranked next-actions) | [`plugins/flow-next/skills/flow-next-prime/SKILL.md`](plugins/flow-next/skills/flow-next-prime/SKILL.md) |

- | Compact markdown digest of a spec, task, diff, or the current topic (`/flow-next:visual` — the light register below the HTML lenses) | [`plugins/flow-next/skills/flow-next-visual/SKILL.md`](plugins/flow-next/skills/flow-next-visual/SKILL.md) |

- | Reply-prose discipline (`/flow-next:prose` — the agent drafts substantial chat replies under the artifact prose contract; also invocable with a draft) | [`plugins/flow-next/skills/flow-next-prose/SKILL.md`](plugins/flow-next/skills/flow-next-prose/SKILL.md) |

- | HTML artifact mode (opt-in render lenses under `.flow/artifacts/`) | [`plugins/flow-next/docs/html-artifacts.md`](plugins/flow-next/docs/html-artifacts.md) |

- | Cross-platform install matrix (Claude / Codex / Droid / OpenCode) | [`plugins/flow-next/docs/platforms.md`](plugins/flow-next/docs/platforms.md) |

- | Codebase feature map (optional) | [`plugins/flow-next/skills/flow-next-map/`](plugins/flow-next/skills/flow-next-map/) — `/flow-next:map` wraps `clawpatch map` |

- | Troubleshooting + uninstall | [`plugins/flow-next/docs/troubleshooting.md`](plugins/flow-next/docs/troubleshooting.md) |

- | Canonical spec-template scaffold (single source of truth — section list, scope-owner annotations, `## Decision Context` flat-vs-H3 conditional; a repo-root `SPEC.md` overrides it per project) | [`plugins/flow-next/templates/spec.md`](plugins/flow-next/templates/spec.md) |

- | Setup internals (copy-less install, per-artifact resolution chains, snippet/marker invariants) | [`agent_docs/setup.md`](agent_docs/setup.md) |

- | Adding a new `/flow-next:<name>` skill | [`agent_docs/adding-skills.md`](agent_docs/adding-skills.md) |

- | Cutting a release | [`agent_docs/releasing.md`](agent_docs/releasing.md) |

- | Writing docs (repo docs + flow-next.dev): capability framing, page shape, anchors as contracts | [`agent_docs/writing-docs.md`](agent_docs/writing-docs.md) |

- | Prose contract for agent-emitted artifacts (the rules every durable emission surface drafts under - PR bodies, specs and plans, tracker and PR comments, strategy and briefing sections, memory and glossary entries, done summaries, changelogs; cited by path at each emission point) | [`plugins/flow-next/docs/prose.md`](plugins/flow-next/docs/prose.md) |

- | Local plugin dev + smoke tests + Ralph e2e | [`agent_docs/local-dev.md`](agent_docs/local-dev.md) |

- | Optimizing a skill/agent prompt (token/accuracy, eval-driven) | [`agent_docs/optimizing-skills.md`](agent_docs/optimizing-skills.md) |

- | Per-skill conduct checklists (review rubric for skill-prose changes) | [`agent_docs/conduct/README.md`](agent_docs/conduct/README.md) |

- | Repo strategy + active tracks | [`STRATEGY.md`](STRATEGY.md) |

- | Vocabulary dictionary (terms + banned synonyms) | [`GLOSSARY.md`](GLOSSARY.md) · archived long-form: [`agent_docs/archive/GLOSSARY-full.md`](agent_docs/archive/GLOSSARY-full.md) |

- | Repo structure | `.claude-plugin/marketplace.json` (Claude); `.agents/plugins/marketplace.json` (Codex); `plugins/flow-next/.claude-plugin/plugin.json`, `plugins/flow-next/.codex-plugin/plugin.json`; Codex pre-built mirror at `plugins/flow-next/codex/` (regenerated by `scripts/sync-codex.sh`) |

- Optional: `/flow-next:map` wraps [openclaw/clawpatch](https://github.com/openclaw/clawpatch)'s `clawpatch map` command to build a semantic feature index under `.clawpatch/features/*.json`. When present, `repo-scout` uses it to anchor R-IDs and `Investigation targets` to concrete codebase regions. Provider-free by default; install via `pnpm add -g clawpatch` (Node 22+).

- > The legacy `flow` plugin was removed in flow-next 1.0.2 (see CHANGELOG). To browse the old code: `git show 0a45aff:plugins/flow/README.md` or `git checkout 0a45aff -- plugins/flow/`. It was never tagged as a release.

- ## Repo metadata

- - Author: Gordon Mickel (gordon@mickel.tech)

- - Homepage: https://mickel.tech

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

- <!-- flow-next:snippet:v1 -->

- This project uses Flow-Next for ALL task tracking. `flowctl` comes from the flow-next plugin install — every flow-next skill resolves it itself, and on Claude Code it is also on PATH. Do NOT create markdown TODOs or use TodoWrite. Cold session: `flowctl brief` first — one bounded call (specs, ready tasks, memory); go deeper with `show`/`cat`/`anchor <task-id>`.

-

- - Lifecycle: `flowctl list` / `show fn-N.M` / `start fn-N.M` / `done fn-N.M --summary-file s.md --evidence-json e.json` (e.json: `{"commits": ["<sha>"], "tests": ["<cmd>"], "prs": []}`)

- - BEFORE any other flowctl operation, or when unsure of a flag: run `flowctl usage` (CLI cheatsheet + orchestration recipes) or `flowctl --help`.

- - BEFORE bridging work to another model/CLI (`codex exec`, `cursor-agent`, `claude -p`, `grok`) or picking an implementation/review model: run `flowctl usage` and follow "Orchestration & model steering" exactly.

- - Creating a spec: write it directly — `/flow-next:plan` is task breakdown only. `flowctl spec create --title "Short title" --plan-file plan.md --json`, then `/flow-next:plan <spec-id>`. Scaffold cascade (first match wins): `SPEC.md` -> `spec.md` -> bundled template.

- - Substantial replies (reports, reviews, multi-section answers): invoke `/flow-next:prose` BEFORE drafting — the artifact prose contract applies to chat replies too. Short conversational turns skip it.

- - If `flowctl` is not found: your shell lacks the plugin's `scripts/` dir on PATH (only Claude Code injects it). Resolve it the way the skills do - the plugin install's `scripts/flowctl` (Claude/Droid: plugin-root env var; Codex: `${CODEX_HOME:-$HOME/.codex}/scripts/flowctl`; Cursor/Grok: two levels above any flow-next SKILL.md) - or update/reinstall the flow-next plugin. A repo with no `.flow/` yet: run `/flow-next:setup`.

-

- **This repo's own additions (maintainer notes, not part of the shipped snippet):**

-

- - **`done` writes the receipt into the TRACKED task file AFTER your commit** — stage/commit the path it reports under `modified_paths` (fn-192 / #346).

- - **Bulk task creation:** `flowctl task create --spec <spec-id> --from-json tasks.json --json` (`[{"title": ..., "description": ..., "acceptance": ..., "deps": [1], "satisfies": ["R1"]}]`); the granular verbs remain for edits.

- - **Standing criteria:** if the repo has a `.flow/criteria.md` (G-IDs), reference relevant G-IDs in spec prose — NEVER restate a standing criterion as an R-ID (a copy freezes while criteria.md evolves and gets judged twice).

- - **Spec Quick commands:** list FOCUSED suites for the feature's files (e.g. `cd plugins/flow-next/tests && python3 -m unittest test_config_snapshot test_task_create_files -q`). That is what workers baseline and verify per task. The FULL suite runs ONCE at the final gate (work Phase 4 / completion review): `python3 scripts/run_tests_parallel.py` (serial fallback `--serial`) **plus `uvx ruff@0.16.0 check .`** — both must be green before a PR. Do not put the full discover/parallel command on every task's Quick commands.

- - **When a change touches `flowctl.py` or `flowctl_tracker/`**, the final gate also needs `python3 scripts/gen_tracker_manifest.py` (the manifest pins every shipped member) and `./scripts/sync-codex.sh` twice (idempotency). Skipping either fails `test_tracker_distribution` rather than producing a useful error. There is no repo-local copy to propagate to: `plugins/flow-next/scripts/` is the single source.

- - **When a change adds, renames, or retypes a `.flow/config.json` key**, the published schema must learn it in the same change: extend the TABLE in `scripts/gen_flow_config_schema.py` (or the drift-test allowlist for machine-written keys), regenerate the committed artifact by running that script, and keep `test_flow_config_schema_drift` green (fn-138).

- - `.flow/memory/` — categorized learnings from past work (`bug/<category>/`, `knowledge/<category>/`; YAML frontmatter: track, category, module, tags, status). Search via `flowctl memory search <q>` — relevant when implementing or debugging in modules with documented prior art.

- _Scaffolded by `/flow-next:setup` as an example, then edited. This section is yours: the model ids are properties of your account and your harness, so keep them current against what your CLIs actually serve — ask a harness for its list rather than trusting this block._

- Grammar: `<tier>: <model>` or `<tier>: <model> at <effort>`. An absent tier means the session model; an unparseable line is ignored. Tier meanings: [`plugins/flow-next/docs/orchestration.md`](plugins/flow-next/docs/orchestration.md#tiers-what-kind-of-model-a-job-wants). How this harness reaches one: [`plugins/flow-next/docs/reach/`](plugins/flow-next/docs/reach/README.md).

- ```

- Resolution at every dispatch site, highest first: an explicit instruction in the moment, then this block, then the agent definition's own default, then the session model. A model this harness cannot reach falls back to the session model, says so once, and continues — routing never fails closed, and nothing here is validated.

-

- How to apply — defaults, not limits. Unless prompted otherwise, route work as you judge best; no permission needed, and an explicit user instruction always overrides this block. Standing permission to escalate: if a cheaper model misses the bar, rerun on a smarter one without asking. Judge the output, not the price tag.

- - Unset is the doctrine, not an omission: planning, capture, interview, requirement analysis, every verdict, and the worker run on the session model. Never delegate judgment.

- - The session model here is fable-5.1 (the default orchestrator in this repo since 2026-09-03): it conducts, plans, judges, and implements. Opus-5 remains a fine cheaper session choice for routine ticks; when it misses the bar, switch the session to fable-5.1 rather than raising opus-5's effort.

- - Anything user-facing (UI, copy, API design) stays on the session model even when it looks mechanical.

- - Reviews prefer a different family than the writer — uncorrelated blind spots. Advice, not enforcement: the receipt records what actually ran.

- - Autonomous loops never call a bridge CLI raw — wrap it in a thin fast-tier subagent that runs the bridge in the FOREGROUND and self-heals environment failures only, never judgment. Recipes: `flowctl usage` § Orchestration & model steering.