How it compounds

Flow-Next gets better as you use it. Memory, glossary, decision records, strategy, and the feature map compound as side-effects of the workflow you already run. There is no manual “compound” / “refresh” / “reindex” ceremony, by design: improvement that depends on remembering an extra command doesn’t happen.

The next task starts with what this one learned

A review finds an integration mistake and the fix reaches SHIP. The workflow records the cause, correction, and prevention in project memory. When a later task touches that module, the agent can read the relevant lesson before implementing the next change.

The same continuity applies when you change sessions or coding agents. The next agent reads the spec, current task state, decisions, and relevant lessons from the repository. A team member can inspect those files too.

The compounding loops

Every self-improving surface has the same lifecycle - seeded once, grown by the skills where new knowledge actually surfaces, read back where it pays, and pruned by the audit sweep:

Surface	Seeded by	Grows through	Read by	Pruned by
Memory (.flow/memory/)	Project setup (on by default)	Worker auto-capture on NEEDS_WORK → SHIP; flow --auto writes the same entries unattended	One memory search during planning and at each task’s re-anchor; why-scout on a rationale question (bug track)	/flow-next:audit - Keep / Update / Consolidate / Replace / Delete / Harden per entry
Glossary (GLOSSARY.md)	/flow-next:prime - repo scan, read-back gated	/flow-next:refine + /flow-next:capture term adds	Plan scouts, worker re-anchor, review prompts (task-relevant terms only)	/flow-next:audit - staleness + alias creep
Decision records (.flow/memory/knowledge/decisions/)	- (accrete from work)	/flow-next:capture strategy-override prompts; refine + review cycles	The memory search during planning; why-scout on a rationale question	/flow-next:audit - supersede-not-delete
Strategy (STRATEGY.md)	/flow-next:strategy	Drift surfaced read-only by plan / capture / sync - updates stay human-confirmed	/flow-next:prospect, plan (## Strategy Alignment), refine, capture	/flow-next:strategy (the only writer)
Feature map (.flow/features/)	/flow-next:features - seeds when the directory is absent; setup and prime always recommend it	/flow-next:work updates the routes its own change altered; readers file drift notes; the maintain pass on the same command re-proves every feature	/flow-next:qa, Drive, and bug intake - navigation, preconditions, gotchas	/flow-next:features maintain when due - clean / changed / blocked, retiring the drift notes it re-proved

Memory

A categorized store, on by default (bug and knowledge tracks) that survives context compaction. The write moment is the review loop: when an implementation review goes NEEDS_WORK → SHIP, work captures the problem, root cause, fix, and prevention as a structured bug-track entry - under flow --auto this happens with nobody watching. Overlap detection merges duplicates at write time, so capture carries no dedup burden.

Reads happen where they pay: planning and each task’s re-anchor run one memory search and pick the entries that apply before touching code. With a Jev key the hits are reordered, never dropped. /flow-next:audit is the garbage collector - it walks entries against the current codebase and keeps, updates, consolidates, replaces, or deletes each one. It is also the graduation path: a lesson that keeps recurring and is mechanizable can be hardened into an enforced gate, so it stops being context the agent re-reads and starts being a check that fires on its own. A recurring lesson no gate can check gets the other repair: the audit fixes the entry’s title, tags, module, and filing so the search that should have surfaced it does. Migrating an older flat-file store: /flow-next:memory-migrate.

Glossary

Wrong-meaning-of-a-normal-word errors get built into plans and code - an agent that quietly conflates two project terms produces a correct-looking implementation of the wrong concept. The glossary loop closes that:

• Seed - /flow-next:prime bootstraps GLOSSARY.md from the repo’s load-bearing nouns, with file-reference evidence and a read-back before anything is written. On an already-populated glossary it reports coverage and never rewrites.
• Add - /flow-next:refine and /flow-next:capture offer term adds when genuinely new vocabulary surfaces in conversation, consent-gated at read-back.
• Read - plan scouts, the work worker’s re-anchor, and review prompts pull task-relevant terms (budget-capped - never the whole file).
• Prune - /flow-next:audit checks every term against the current code as part of its normal sweep.

Decision records

Load-bearing architectural choices land in .flow/memory/knowledge/decisions/ at the moment they’re made - for example, /flow-next:capture proposes a decision record when a spec deliberately overrides an active strategy track. Audit treats decisions specially: Replace is supersede-not-delete, so the historical trail of why stays intact.

Strategy

STRATEGY.md is read by the skills that need direction - /flow-next:prospect’s candidate filter, /flow-next:plan’s ## Strategy Alignment section, refine and capture conflict surfacing - and the same reads keep it honest: drift between the doc and what’s actually being built is flagged read-only, never auto-superseded. The human stays the editor via /flow-next:strategy.

Feature map

A committed user-POV drive directory (.flow/features/, beside .flow/memory/) recording how a user reaches each user-facing feature, how an agent drives it, and which traps waste a verification run. It is the layer that stops live verification re-deriving navigation every time: the spec still supplies this run’s acceptance criteria, and live captured evidence remains the only basis for a ship verdict.

• Seed - /flow-next:features when .flow/features/ is absent: interview the repo, prove every route with one live drive, write the index plus one four-H2 file per proven feature, each stamped with a **Last proven:** date and commit. Nothing undriven lands. Setup and prime recommend this step on every repository.
• Grow - /flow-next:work updates the map in the same change when that change alters how a user reaches a mapped feature: only the affected files, each new route proven with one live drive. When it cannot prove the route, it files a drift note and leaves the map alone. Besides /flow-next:features, work is the only map writer.
• Read - /flow-next:qa, Drive, and bug intake consume it by existence check, with no registration. An absent map leaves them exactly as they are today. A reader that finds a stale route files a feature-map-drift note and never edits the map.
• Prune - the maintain pass on the same command, run when the map is due: an open drift note, or a feature whose last proof is features.staleAfterCommits (default 50) product commits old. It re-proves every feature live, fixes what moved, retires the drift notes whose routes it re-proved, and ends clean (no branch, no PR), changed (one chore PR of proven corrections), or blocked (naming what blocked).

How the three mechanisms fit together, and how to run maintain from a loop: Keep the feature map current.

Unlike /flow-next:map’s local .clawpatch/ code index, this map is committed: its whole value is surviving the session and the machine. Full behavior on the Features skill page.

The no-ceremony principle

Each loop’s write moment is embedded in a step that already happens. Prime runs once per repo. Captures and refine passes happen when specs are born. Reviews happen before merge. Audits run when memory is consulted and found wanting.

The feature map’s full maintain pass is the one step that stays human-invoked, and it is scoped. Everyday upkeep is ambient: work updates the routes its own change moved, and every reader files a drift note when a route no longer matches, during work that already happens. The full pass drives the live app, so it runs when you or a host loop you start invoke it, never from a pipeline stage. You do not have to remember it: flowctl features status reports the map due from open drift notes and last-proven age, and flow’s no-argument reading recommends the pass at that moment.

Contrast with workflows that require a manual “compound” or “refresh” pass: those degrade silently the day the operator forgets. Flow-Next’s surfaces degrade toward pruning - audit and the feature-map maintain pass remove what’s stale - rather than toward staleness, where nothing has been added since the last ceremony.