tobihagemann/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:

---
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.