# Migrate Turboplans

> Migrate legacy plan and shell files in .turbo/ to the current layout. Splits legacy artifacts between .turbo/shells/ (unexpanded shells, needs /expand-shell) and .turbo/plans/ (expanded plans and standalone plans), backfills minimal frontmatter, and deletes legacy prompt-plan indexes. Use when the user asks to "migrate turboplans", "migrate turbo plans", "upgrade plan format", "add frontmatter to plans", or "convert old plans".

- Skill: `majiayu000/migrate-turboplans` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/migrate-turboplans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/migrate-turboplans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/migrate-turboplans

---


# Migrate Plans

Current layout: unexpanded shells live in `.turbo/shells/` with `spec:` and `depends_on:` frontmatter. Plans live in `.turbo/plans/` with `status:` (required) and optional `spec:` for provenance. This skill migrates legacy shapes to that layout.

## Task Tracking

Use `TaskCreate` to create a task for each step:

1. Scan and classify existing files
2. Migrate prompt plan indexes
3. Process remaining files in `.turbo/plans/`
4. Normalize frontmatter on remaining plans
5. Clean up and report

## Step 1: Scan and Classify Existing Files

Scan for all legacy shapes:

- **Prompt plan indexes** — Glob `.turbo/prompt-plans/*.md`. Also check for `.turbo/prompts.md` (oldest legacy format). Parse each index to determine whether prompts are inline (contain `### Prompt` sections with code blocks) or reference separate shell files (contain `**Shell:**` fields). Record the set of shell files each index references — Step 3 will skip these.
- **Files in `.turbo/plans/*.md`** — Read each file's first 20 lines and classify:
  - **Unexpanded shell** — has legacy `type: shell` frontmatter AND does not contain `## Pattern Survey`, OR has no frontmatter but contains `## Produces`, `## Consumes`, and `## Covers Spec Requirements` without `## Pattern Survey`. Target: `.turbo/shells/<filename>`.
  - **Expanded plan** — contains `## Pattern Survey` (with or without `<!-- Expanded from:` marker, with or without legacy `type: shell`). Target: stays in `.turbo/plans/`, frontmatter normalized.
  - **Regular plan** — no frontmatter or legacy `type: plan` frontmatter, not shell-shaped, no `## Pattern Survey`. Target: stays in `.turbo/plans/`, frontmatter normalized.
  - **Already-current plan** — has frontmatter with `status:` and no `type:`. Skip.
- **Files in `.turbo/shells/*.md`** — if they already have current frontmatter (no `type:`, no `status:`, just `spec:` and `depends_on:`), they're migrated. Otherwise, queue for normalization in Step 3.

Report what was found: number of indexes, unexpanded shells in `.turbo/plans/`, expanded plans in `.turbo/plans/`, regular plans, already-current plans, already-current shells. If nothing needs migration, report and stop.

## Step 2: Migrate Prompt Plan Indexes

For each prompt plan index (including `.turbo/prompts.md` if present), parse:

- **Source** — spec path from the `Source:` field
- **Prompts** — each `## Prompt N:` entry with its Status, Depends on, and content

### Inline Prompts (Old Format)

Indexes where each prompt contains a `### Prompt` section with a code block of concrete instructions. These are equivalent to expanded plans, so migrate them to `.turbo/plans/`.

For each prompt entry:

1. Generate a slug: `<spec-slug>-NN-<title-slug>` from the spec filename and prompt number/title
2. If `.turbo/plans/<slug>.md` already exists with current frontmatter, skip this entry (collision)
3. Map the legacy status to a plan `status`: `done` → `done`, `pending` → `ready`, `in-progress` → `ready`
4. Write a plan at `.turbo/plans/<slug>.md`:

````markdown
---
status: <mapped status>
spec: <source spec path>
---

# Plan: <Prompt Title>

## Context

<The prompt's **Context** field content. If absent, use "Migrated from legacy prompt plan.">

## Implementation Steps

1. **Execute prompt instructions**
   - <The prompt's code block content, converted from a monolithic block into numbered sub-steps where natural boundaries exist. Preserve the concrete file references and instructions.>

## Verification

- Verify the implementation matches the prompt's requirements
- Run any test commands mentioned in the prompt
````

### Shell-Based Prompt Plans (Newer Format)

Indexes where each prompt references a separate shell file via a `**Shell:**` field. The referenced files may live in `.turbo/plans/` under the old layout. For each prompt entry:

1. Read the referenced file at its original path. If missing, report the mismatch and skip
2. Classify as unexpanded (no `## Pattern Survey`) or expanded (has `## Pattern Survey`)
3. Determine target:
   - **Unexpanded** → `.turbo/shells/<filename>`, frontmatter carries `spec:` and `depends_on:`
   - **Expanded** → `.turbo/plans/<filename>`, frontmatter carries `status:` and `spec:`
4. Build frontmatter:
   - `spec` from the index's Source field
   - For unexpanded only: `depends_on` mapped from the index entry's Depends on field, converting prompt numbers to shell file slugs
   - For expanded only: `status` mapped from the index entry's Status field (`done` → `done`, `pending` → `ready`, `in-progress` → `ready`)
5. If the target already exists with current frontmatter, skip
6. Write the file to the target path with the new frontmatter prepended before the existing `# Plan:` heading (replacing any legacy frontmatter). Delete the original at `.turbo/plans/<filename>`.

## Step 3: Process Remaining Files in `.turbo/plans/`

Handles files in `.turbo/plans/` that were not recorded in Step 1 as referenced by a prompt-plan index. Skip index-referenced files even if Step 2 couldn't process them (missing source, collision, target-already-current) — they belong to Step 2's accounting and should not be reprocessed here as unexpanded shells.

For each unexpanded shell:

1. Build frontmatter: `spec:` inferred from the spec slug embedded in the filename (`<spec-slug>-NN-<title>.md`) when a matching `.turbo/specs/<spec-slug>.md` exists (otherwise omit), `depends_on: []`
2. Write to `.turbo/shells/<filename>` with the new frontmatter prepended before the `# Plan:` heading (replacing any legacy frontmatter)
3. Delete the original at `.turbo/plans/<filename>`

For each expanded plan:

1. Build frontmatter: `status: ready` (default), or `status: done` if legacy frontmatter had `status: done`, plus `spec:` inferred from the filename when a matching spec exists
2. Rewrite the file in place with the normalized frontmatter (dropping legacy `type:`, `depends_on:`, and any other fields)

For each file in `.turbo/shells/*.md` that needs normalization (queued from Step 1):

1. Keep `spec:` and `depends_on:` if present, synthesize defaults if not (`depends_on: []`)
2. Drop any legacy `type:` or `status:` fields
3. Rewrite the file in place with the normalized frontmatter

Create `.turbo/shells/` if it does not exist. If a file at a shell target path already exists, report the collision and skip.

## Step 4: Normalize Frontmatter on Remaining Plans

For regular plans in `.turbo/plans/` that were not handled by Steps 2 or 3:

- If the file has no frontmatter, prepend `status: done` (plans without frontmatter predate the convention and have already been implemented)
- If the file has legacy `type: plan` frontmatter, drop `type:` and normalize `status:` to `done` if already `done`, otherwise `ready`. If no `status:` is present, set `status: done`.

The `status: done` default here differs from Step 3's `ready` default for expanded plans. Reasoning: regular plans without frontmatter are old enough that they're assumed implemented; expanded plans may have been expanded but never implemented, so `ready` is the safer default.

## Step 5: Clean Up and Report

After all files are migrated:

1. Delete `.turbo/prompt-plans/` (the index files are no longer needed)
2. Delete `.turbo/prompts.md` if it exists (oldest legacy format)

Report a summary:

- Number of inline prompts converted to plans under `.turbo/plans/`
- Number of shells migrated from prompt-plan indexes to `.turbo/shells/`
- Number of expanded plans migrated from prompt-plan indexes to `.turbo/plans/`
- Number of unexpanded shells relocated from `.turbo/plans/` to `.turbo/shells/`
- Number of expanded plans normalized in place in `.turbo/plans/`
- Number of shells normalized in place in `.turbo/shells/`
- Number of regular plans that received frontmatter
- Number of files already migrated (skipped)
- Files deleted (indexes and relocated source files)

## Rules

- Never modify the spec files in `.turbo/specs/`.
- Never overwrite a file that already exists at the target path with valid current frontmatter.
- Preserve all existing body content when adding or normalizing frontmatter. The migration is additive, structural (directory moves), and subtractive (legacy index deletion), never content-destructive.
- If a shell file referenced by an index does not exist, report the mismatch and skip that entry.
- If the source spec path in an index does not resolve, still migrate the files but note the missing spec in the report.
- Never write `type:` into any migrated file. The directory is the type signal.
- Never write `depends_on:` into a plan. The dependency graph lives on shells only.
- The migration never produces `status: draft` because legacy artifacts predate the draft concept and cannot retroactively go through refinement; `ready` is the baseline for migrated expanded plans.