Turbo 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\".

install

source · Clone the upstream repo

git clone https://github.com/tobihagemann/turbo

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/tobihagemann/turbo "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/migrate-turboplans" ~/.claude/skills/tobihagemann-turbo-migrate-turboplans && rm -rf "$T"

manifest: skills/migrate-turboplans/SKILL.md

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:

Scan and classify existing files
Migrate prompt plan indexes
Process remaining files in
```
.turbo/plans/
```
Normalize frontmatter on remaining plans
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:

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

Read the referenced file at its original path. If missing, report the mismatch and skip
Classify as unexpanded (no
```
## Pattern Survey
```
) or expanded (has
```
## Pattern Survey
```
)
Determine target:
- Unexpanded →
```
.turbo/shells/<filename>
```
  , frontmatter carries
```
spec:
```
  and
```
depends_on:
```
- Expanded →
```
.turbo/plans/<filename>
```
  , frontmatter carries
```
status:
```
  and
```
spec:
```
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
```
  )
If the target already exists with current frontmatter, skip
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:

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: []
```
Write to
```
.turbo/shells/<filename>
```
with the new frontmatter prepended before the
```
# Plan:
```
heading (replacing any legacy frontmatter)
Delete the original at
```
.turbo/plans/<filename>
```

For each expanded plan:

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
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):

Keep
```
spec:
```
and
```
depends_on:
```
if present, synthesize defaults if not (
```
depends_on: []
```
)
Drop any legacy
```
type:
```
or
```
status:
```
fields
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:

Delete
```
.turbo/prompt-plans/
```
(the index files are no longer needed)
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.