flow-next-memory-migrate — Claude Code skill: setup and features
flow-next-memory-migrate converts legacy markdown memory records into structured YAML entries using the bundled flowctl CLI.
MIT ★ 730 updated 2026-10-29
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-nextWhat flow-next-memory-migrate does
Older versions of the framework stored project memories in three plain files: .flow/memory/pitfalls.md, conventions.md, and decisions.md. Because these files lacked structured frontmatter, search and audit utilities stopped seeing them. This skill reads every legacy record, maps it to a track and category, and writes individual categorized files via flowctl memory add.
The host agent runs the classification logic directly without external Python helper scripts or remote model calls. The flowctl executable is bundled with the plugin repository instead of being installed into the global system PATH, which means invoking it globally will fail.
You can run the migration interactively or provide the mode:autofix argument. In interactive runs, the agent asks questions to resolve ambiguous classifications. In autofix mode, it applies file-based defaults without prompting and tags questionable entries as needs-review in the final summary report.
What it helps with
- migrate flat markdown memory files into categorized YAML schemas
- restore search indexing for old project lessons and decisions
- batch-convert legacy memory entries without writing manual frontmatter
- flag ambiguous project notes for later manual review
Example prompts for the agent
- /flow-next:memory-migrate mode:autofix
- migrate legacy memory entries from
pitfalls.md - convert old memory format into the categorized schema
How to install flow-next-memory-migrate
1Plugin marketplace
/plugin marketplace add gmickel/flow-next/plugin install flow-next@flow-nextThis installs the whole flow-next plugin with all its skills
2Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-memory-migrate -a claude-code3Manually: put the files in place
~/.claude/skills/flow-next-memory-migrate/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/flow-next-memory-migrate/
1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-memory-migrate -a codex2Manually: put the files in place
.agents/skills/flow-next-memory-migrate/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-memory-migrate -a cursor2Manually: put the files in place
.cursor/skills/flow-next-memory-migrate/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gmickel/flow-next plugins/flow-next/skills/flow-next-memory-migrate2Manually: put the files in place
.github/skills/flow-next-memory-migrate/SKILL.md1Skills CLI (Vercel)
npx skills add gmickel/flow-next --skill flow-next-memory-migrate -a gemini-cli2Platform CLI
gemini skills install https://github.com/gmickel/flow-next --path plugins/flow-next/skills/flow-next-memory-migrateManually: put the files in place
.devin/skills/flow-next-memory-migrate/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about flow-next-memory-migrate
How to install flow-next-memory-migrate in Claude Code?
Run both marketplace commands in sequence: /plugin marketplace add gmickel/flow-next followed by /plugin install flow-next@flow-next.
What does flow-next-memory-migrate do?
It parses legacy markdown memory entries and converts them into categorized files with track, tag, and status metadata so flowctl search tools can index them.
What does the mode:autofix argument change?
It disables interactive questions, applies standard category defaults to every item, leaves original files intact, and marks questionable classifications as needs-review.
Source text
SKILL.md · MIT
---
name: flow-next-memory-migrate
description: Migrate legacy flat memory files (`.flow/memory/pitfalls.md`, `conventions.md`, `decisions.md`) into the categorized YAML schema. Triggers on /flow-next:memory-migrate, "migrate memory", "convert legacy memory", "lift pitfalls into categorized schema", "convert old memory format". Optional `mode:autofix` token in arguments runs without questions and accepts mechanical defaults for ambiguous classifications. Optional scope hint after the mode token narrows the migration to a specific legacy file (e.g. `pitfalls.md`).
user-invocable: false
allowed-tools: AskUserQuestion, Read, Bash, Grep, Glob, Write, Edit, Task
---
# /flow-next:memory-migrate — agent-native legacy migration
Older flow-next versions stored memory as three flat markdown files: `.flow/memory/pitfalls.md`, `conventions.md`, `decisions.md`. Each held lessons with ad-hoc headings and no schema, either separated by `---` or appended under `## <date> <source> [<type>]` headers; `memory list-legacy` returns one entry per lesson in both formats. The categorized schema (track / category / module / tags / status frontmatter, one entry per file). Existing flat files persisted but became invisible to `memory list`, `memory search`, and `flow-next-audit` because there's no frontmatter to scope or stale-flag.
This skill IS the migration. The host agent (Claude Code / Codex / Droid) reads each legacy entry, applies the mechanical default `(track, category)` from the source filename, overrides only when the entry's content warrants, and writes a categorized entry via `flowctl memory add`. Optional autofix mode accepts every mechanical default and marks ambiguous entries as `needs-review` in the report.
There is no Python classifier subprocess, no `codex`/`copilot` dispatch, no fast-model probability scoring. The host agent is already an LLM with full repo context and does the work directly. flowctl provides only thin parsing + persistence plumbing (`memory list-legacy --json`, existing `memory add`).
**Read [workflow.md](workflow.md) for the full phase-by-phase execution. Read [phases.md](phases.md) for the (track, category) decision tree with mechanical baseline + override examples.**
Read [working-rules.md](../../references/working-rules.md) first unless you already have this run; it holds for every step of this skill.
## Preamble
**CRITICAL: flowctl is BUNDLED — NOT installed globally.** `which flowctl` will fail (expected). Define once; subsequent blocks (here and in `workflow.md`) use `$FLOWCTL`:
```bash
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl" # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
```
**Inline skill (no `context: fork`)** — `AskUserQuestion` must stay reachable across phases. Subagents can't call blocking question tools (Claude Code issues #12890, #34592). Phase 1 (Classify) needs user choice on ambiguous entries in interactive mode; Phase 4 (Cleanup) needs consent before renaming originals.
## Mode Detection
Parse `$ARGUMENTS` for the literal token `mode:autofix`. If present, strip it from the arguments — the remainder is the scope hint (a legacy filename like `pitfalls.md` to narrow the run, or empty to migrate all).
```bash
RAW_ARGS="$ARGUMENTS"
MODE="interactive"
if [[ "$RAW_ARGS" == *"mode:autofix"* ]]; then
MODE="autofix"
# Strip token, collapse whitespace, trim.
SCOPE_HINT=$(printf "%s" "$RAW_ARGS" | sed 's/mode:autofix//' | tr -s ' ' | sed 's/^ //;s/ $//')
else
SCOPE_HINT="$RAW_ARGS"
fi
```
| Mode | When | Behavior |
|------|------|----------|
| **Interactive** (default) | User is at the terminal | Ask via blocking-question tool when an entry's content suggests overriding the mechanical default; confirm Phase 4 cleanup; show triage summary before writes |
| **Autofix** (`mode:autofix` in arguments) | Autonomous or batch usage | No user questions. Apply mechanical defaults for every entry. Override only when the agent has high-confidence evidence from the entry body. Mark genuinely ambiguous entries as `needs-review` in the report. Default-decline Phase 4 cleanup. Print full report |
### Autofix mode rules
- **No user questions.** Never call the blocking-question tool.
- **Process every legacy entry in scope.** No scope-narrowing question. If no scope hint was provided, migrate all three legacy files.
- **Mechanical default wins on borderline.** Override only when the entry body unambiguously points at a different `(track, category)` (e.g. an entry titled "race condition in worker pool" inside `pitfalls.md` clearly warrants `bug/runtime-errors` over the mechanical `bug/build-errors`).
- **Ambiguous → mechanical default + log as `needs-review`.** Genuine "could be A or B" cases take the mechanical default and surface in the report so the user can re-classify later.
- **Default-decline Phase 4 cleanup.** Originals stay in place. Surface the rename suggestion as a recommendation in the report.
- **Always print the full report.** The report is the sole deliverable — there is no user to ask follow-ups.
## Interaction Principles (interactive mode only)
In autofix mode, skip user questions entirely and apply the rules above.
In interactive mode, follow these principles:
- Ask via `AskUserQuestion` (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded). Fall back to numbered options in plain text only if the tool is unreachable or errors. Never silently skip the question.
- Prefer **multiple choice** when natural options exist.
- Lead with the **recommended option** (always the mechanical default unless the body warrants otherwise) and a one-sentence rationale.
- Do **not** ask the user to make decisions before the entry has been read — Phase 1 reads first, asks second.
- Group obvious mechanical-default migrations together for batched confirmation. Present overrides and ambiguous cases one at a time.
The goal is automated migration with human oversight on judgment calls — not a question for every entry.
## Subagent dispatch (mostly N/A)
This skill runs almost entirely on the main thread. Phase 1's "one entry per tool call" rule means classification iterates serially in the orchestrator — there is no investigation step independent enough to dispatch in parallel. Cross-platform tool naming (`Task` on Claude Code, `spawn_agent` on Codex, platform-equivalent on Droid) is documented here only for the rare case where the agent needs to spawn a focused investigation subagent (e.g. resolving an ambiguous override by reading a referenced file): keep such dispatches read-only (reads and searches only), do not let subagents call `flowctl memory add` directly, and merge results back on the main thread before Phase 2.
## Forbidden
- **Migrating files outside `MEMORY_LEGACY_FILES`** (`pitfalls.md`, `conventions.md`, `decisions.md` at `.flow/memory/` root). Any other `.md` at the memory root is user data — leave it alone.
- **Migrating entries inside categorized directories** (`.flow/memory/{bug,knowledge}/<category>/*.md`). Those are already migrated; re-running on them is a bug.
- **Auto-deleting legacy flat files.** Phase 4 renames originals to `.flow/memory/_migrated/<filename>.bak` for traceability — never `rm`. User can `git rm` later if they want.
- **Inventing flowctl subcommands** beyond the shipped `memory list-legacy`. Phase 2 writes via existing `flowctl memory add`. Mechanical map is documented in phases.md so the agent doesn't need to call a flowctl helper for it.
- **Batch-classifying multiple entries in a single tool call.** Phase 1 enforces one entry per tool call. Agents under context pressure batch-classify in-prompt and silently skip entries (practice-scout flagged this real failure mode).
- **Setting `context: fork`** — blocking-question tools must stay reachable.
- **Re-running on already-migrated files.** Phase 0 checks `.flow/memory/_migrated/<filename>.bak` and skips with an "already migrated" log line.
## Workflow
Execute the phases in [workflow.md](workflow.md) in order:
0. **Detect & enumerate** — run `flowctl memory list-legacy --json`, check `_migrated/` for prior runs, apply scope hint, decide interaction path.
1. **Classify (one entry per tool call)** — for each entry: read title + body + filename context, default to mechanical `(track, category)`, override only with body-driven evidence. Interactive: ask on ambiguity. Autofix: take mechanical default + log `needs-review`.
2. **Write categorized entries** — invoke `flowctl memory add --track <t> --category <c> --title "..." --body-file <tmpfile>` per classified entry. Slug uniqueness handled by existing helper.
3. **Verify + Report** — re-read newly created entries, print summary (legacy files processed, entries migrated, overrides, needs-review).
4. **Optional cleanup** — interactive: ask whether to rename originals to `.flow/memory/_migrated/<filename>.bak`. Autofix: default-decline + surface as recommendation. On first cleanup, write `.flow/memory/_migrated/.gitignore` containing `*` (self-ignoring directory pattern). **Legacy originals are renamed, never deleted** — a run that removed a legacy file has broken this.
## Output rules
The full report is the deliverable — print it as markdown to stdout. Do not summarize internally and emit a one-liner.
The report's exact shape lives in one place — [workflow.md](workflow.md) §3.2 (summary skeleton) and §3.3 (the autofix Applied / Recommended split). Render it from there; this file does not restate it.
What the report must carry either way: files processed, entries migrated, overrides, needs-review, plus per-entry detail (id, source filename, mechanical default, final classification, override rationale) and, for each `needs-review` entry, why the agent could not decide.
**Done when:** the full report reached stdout as markdown. A run that summarized internally and emitted a one-liner has broken this.
© Gordon Mickel · MIT · gmickel/flow-next