migrate-turbo-files

Migrate Turbo Files

Current layouts:

• 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.
• .turbo/improvements.md entries use Type values direct, investigate, or plan. Legacy values trivial and standard map to direct and plan respectively.

This skill migrates legacy shapes to those layouts.

Task Tracking

Use update_plan to track 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. Migrate improvements.md Type values
6. 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.
• .turbo/improvements.md — read the file if it exists. Count entries whose - Type: line carries the legacy values trivial or standard. Queue these for rewriting in Step 5.

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, and improvements entries with legacy Type values. 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:

---
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:
4. Unexpanded → .turbo/shells/<filename>, frontmatter carries spec: and depends_on:
5. Expanded → .turbo/plans/<filename>, frontmatter carries status: and spec:
6. Build frontmatter:
7. spec from the index's Source field
8. For unexpanded only: depends_on mapped from the index entry's Depends on field, converting prompt numbers to shell file slugs
9. For expanded only: status mapped from the index entry's Status field (done → done, pending → ready, in-progress → ready)
10. If the target already exists with current frontmatter, skip
11. 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: Migrate improvements.md Type Values

For each entry queued in Step 1, rewrite its - Type: line in place:

• - Type: trivial → - Type: direct
• - Type: standard → - Type: plan

investigate is unchanged. Preserve all other entry content (Category, Where, Why, Noted, summary). If improvements.md does not exist or no entries carry legacy values, skip this step.

Step 6: Clean Up and Report

After all files are mig