Self-Improving

Flow-Next gets better as you use it. Four surfaces — memory, glossary, decision records, and strategy — 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 four 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/)	flowctl memory init (opt-in)	Worker auto-capture on NEEDS_WORK → SHIP; Ralph writes the same entries autonomously	memory-scout during planning; worker re-anchor before each task	/flow-next:audit — Keep / Update / Consolidate / Replace / Delete per entry
Glossary (GLOSSARY.md)	/flow-next:prime — repo scan, read-back gated	/flow-next:interview + /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; interview + review cycles	memory-scout during planning	/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), interview, capture	/flow-next:strategy (the only writer)

Memory

An opt-in, categorized store (bug and knowledge tracks) that survives context compaction. The write moment is the review loop: when an implementation review goes NEEDS_WORK → SHIP, the worker captures the problem, root cause, fix, and prevention as a structured bug-track entry — in Ralph mode this happens with nobody watching. Overlap detection merges duplicates at write time, so capture carries no dedup burden.

Reads happen where they pay: memory-scout feeds planning, and the worker re-anchor pulls module-relevant entries before touching code. /flow-next:audit is the garbage collector — it walks entries against the current codebase and keeps, updates, consolidates, replaces, or deletes each one. 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:interview 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, interview 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.

The no-ceremony principle

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

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 removes what’s stale — rather than toward staleness, where nothing has been added since the last ceremony.