| name | flow-memory-keeper |
| description | Use at task, phase, flow, sync, archive, finish, revise, or failure checkpoints to keep Flow specs clean, capture learnings and failures, elevate durable patterns, and refine this skill with project-specific nuances |
Flow Memory Keeper
Purpose
This project-local skill prevents Flow work from drifting into stale specs, missing learnings, or half-archived folders.
Use it whenever work is completed, paused, blocked, revised, synced, or archived.
Mandatory Outcomes
Before claiming a task, phase, or flow is complete:
- Ensure
spec.md is readable and current through the normal Flow sync process.
- Capture concrete learnings in the flow's
learnings.md.
- Capture failures, false starts, blockers, and recovery notes when they would help a future session.
- If the user had to repeat a correction or showed frustration that something was forgotten, flag that as a workflow gap and capture it explicitly.
- Elevate durable patterns to
.agents/patterns.md.
- Update
.agents/knowledge/ chapters when the current-state knowledge base changed.
- If the flow is complete, archive it cleanly and leave the active spec area uncluttered.
- Capture validated repo-native commands and verification workflows in
.agents/workflow.md when they were discovered or corrected during the work.
Completion Protocol
Task or Phase Completion
- Append a concise entry to
.agents/specs/<flow_id>/learnings.md:
- what changed
- why it changed
- files touched
- commands or checks that mattered
- canonical repo commands that future agents should reuse
- gotchas, failures, and recoveries worth remembering
- any repeated user correction or frustration that revealed a missing default, checklist item, or workflow rule
- Move reusable guidance into
.agents/patterns.md.
- If the work changed architecture, conventions, tooling, operational behavior, or canonical project commands, update the relevant
.agents/knowledge/*.md chapter and .agents/workflow.md.
- Promote repeated user corrections or frustration into an obvious durable rule instead of leaving it as a one-off note.
- Run the normal Flow sync step so
spec.md reflects the latest state.
Failure Capture
Capture failure notes whenever one of these happened:
- a hypothesis was wrong
- a command or tool failed in a non-obvious way
- a harness integration behaved differently than expected
- a backend migration exposed a hidden assumption
- a repeated reminder from the user revealed a workflow gap
- the user seemed frustrated that something obvious was forgotten again
Failure notes belong in learnings.md, but keep them short and reusable. Focus on what future agents should avoid or check earlier.
Flow Archive
When a flow is finished:
- Confirm the final sync/export step ran.
- Ensure
learnings.md is not missing critical discoveries.
- Elevate the stable patterns and current-state knowledge before archiving.
- Move the flow folder into
.agents/archive/ according to the Flow archive workflow.
- Remove or avoid leaving stale scratch files in the active specs area.
Skill Refinement Loop
This skill should improve over time.
When you discover a repeated project nuance, add or revise a short rule below instead of keeping the lesson only in session memory.
Only keep:
- durable project-specific rules
- recurring harness quirks
- recurring workflow misses
- validated project-native command wrappers that should become defaults
- user corrections or frustration that clearly indicate a missing default or checklist item
- archive/sync/learnings habits that proved necessary
Do not keep:
- one-off narrative history
- temporary debugging logs
- duplicate rules already captured elsewhere
Before claiming a task, phase, or flow is complete, verify:
Project Nuances
- Add short, durable project-specific reminders here as they are discovered.
