C3 Migration Skill

Overview

Migrate project .c3/ documentation from older versions to current skill version.

Core principle: Explicit migration triggered by user. Show plan, get confirmation, execute in batches.

Announce at start: "I'm using the c3-migrate skill to upgrade your C3 documentation."

Quick Reference

Phase	Key Activities	Output
1. Detect	Read version, compare to current	Version gap identified
2. Plan	List migrations/, scan files	Migration plan
3. Confirm	Present changes to user	User approval
4. Execute	Apply transforms in batches	Updated files
5. Finalize	Update version, suggest TOC rebuild	Migration complete

---

Phase 1: Detect Version

Read Project Version

# Check frontmatter first (v3), then VERSION file (v1/v2)
if grep -q '^c3-version:' .c3/README.md 2>/dev/null; then
    PROJECT_VERSION=$(grep '^c3-version:' .c3/README.md | sed 's/c3-version: *//')
elif [ -f ".c3/VERSION" ]; then
    PROJECT_VERSION=$(cat .c3/VERSION)
else
    PROJECT_VERSION=0
fi

Version storage:

Format	Location
v1/v2	.c3/VERSION file
v3	c3-version: 3 in .c3/README.md frontmatter
v4+ (date-based)	c3-version: YYYYMMDD-slug in .c3/README.md frontmatter

Compare Versions

Condition	Action
PROJECT == SKILL	"Already current, no migration needed." Stop.
PROJECT > SKILL	"Project newer than skill." Stop.
PROJECT < SKILL	Continue to Phase 2

Version ordering:

• Numeric versions (1, 2, 3) sort before date-based versions
• Date-based versions sort lexicographically: 20251124-foo < 20251125-bar
• Example: 1 < 2 < 3 < 20251124-adr-date-naming < 20251125-next-change

---

Phase 2: Build Migration Plan

1. List files in migrations/ directory from plugin directory
2. Sort lexicographically (numeric versions first, then YYYYMMDD-slug)
3. For each migration newer than PROJECT:
   • Extract transforms section
   • Parse patterns and file globs
4. Scan .c3/ for affected files
5. Build plan summary

Plan Format

## Migration Plan: v{FROM} → v{TO}

### Version {N} transforms:
- {PATTERN_DESC}: {FILE_COUNT} files

### Batches:
- Batch 1: file1.md, file2.md
- Batch 2: file3.md, file4.md

---

Phase 3: Confirm with User

"I'll migrate your .c3/ documentation from v{FROM} to v{TO}.

Changes:

• {CHANGE_1}
• {CHANGE_2}

Files affected: {N}

Proceed? [y/n]"

If declined, stop.

---

Phase 4: Execute Migration

Batch Processing

Process 3-5 files per batch for trackability.

For each batch:

1. Apply transforms to files
2. Report progress: Batch 1/3 complete: 3 files updated

Error Handling

Error	Action
Pattern doesn't match	Log warning, continue
File read error	Stop batch, report

---

Phase 5: Finalize

Update Version

# For numeric versions (1, 2, 3)
if [[ "$TARGET_VERSION" =~ ^[0-9]+$ ]]; then
    if [ "$TARGET_VERSION" -ge 3 ]; then
        sed -i "s/^c3-version: .*/c3-version: $TARGET_VERSION/" .c3/README.md
        rm -f .c3/VERSION
    else
        echo "$TARGET_VERSION" > .c3/VERSION
    fi
else
    # For date-based versions (YYYYMMDD-slug)
    sed -i "s/^c3-version: .*/c3-version: $TARGET_VERSION/" .c3/README.md
    rm -f .c3/VERSION
fi

Suggest TOC Rebuild

"Migration complete: v{FROM} → v{TO}

Rebuild the TOC using the plugin's build-toc.sh script to refresh the table of contents."

ADR Status Check (Post-Migration)

After migration, verify ADR status field consistency:

# Check all ADRs have status field
for f in .c3/adr/adr-*.md; do
  grep -q '^status:' "$f" || echo "Missing status: $f"
done

# List ADRs by status
grep -l '^status: proposed' .c3/adr/*.md 2>/dev/null
grep -l '^status: accepted' .c3/adr/*.md 2>/dev/null
grep -l '^status: implemented' .c3/adr/*.md 2>/dev/null

Reminder: Only status: implemented ADRs should appear in TOC. After migration, rebuild TOC to ensure filtering is correct.

---

V1 → V2 Migration

Transforms

1. Flatten components: Move from components/{container}/ to components/
2. Rename context: CTX-system-overview.md → README.md
3. Update links: Remove container subfolder from paths

Verification

# No nested component directories
[ $(find .c3/components -mindepth 1 -type d | wc -l) -eq 0 ]

# README.md has correct id
grep -q '^id: context$' .c3/README.md

---

V2 → V3 Migration

Transforms

1. Convert containers to folders: containers/C3-1-*.md → c3-1-*/README.md
2. Move components into containers: components/C3-101-*.md → c3-1-*/c3-101-*.md
3. Update context: id: context → id: c3-0, add c3-version: 3
4. Lowercase ADRs: ADR-001-*.md → adr-001-*.md

Verification

# No containers/ or components/ directories
[ ! -d ".c3/containers" ] && [ ! -d ".c3/components" ]

# Context has c3-0 and c3-version
grep -q '^id: c3-0$' .c3/README.md
grep -q '^c3-version: 3$' .c3/README.md

# All lowercase
! find .c3 -name "C3-*" -o -name "ADR-*" | grep -q .

---

20251125-layer-settings Migration

Changes

• Layer sections support structured configuration with useDefaults, include, exclude, litmus, diagrams
• Existing prose-only format still works (backward compatible)
• Skills read defaults from defaults.md files

Transforms

No automatic transforms required.

This migration is backward compatible:

• Existing context: | prose format continues to work
• Skills fall back to defaults.md when settings not customized

Optional Upgrade

Users who want layer customization can manually convert:

From:

context: |
  prose guidance here

To:

context:
  useDefaults: true
  guidance: |
    prose guidance here
  include: |
    custom items

Verification

# VERSION shows 20251125-layer-settings or later
grep 'c3-version:' .c3/README.md

# settings.yaml still valid (basic check)
if [ -f ".c3/settings.yaml" ]; then
  grep -q '^context:' .c3/settings.yaml || grep -q '^context$' .c3/settings.yaml
fi

---

Red Flags

Rationalization	Counter
"I'll migrate without asking"	Always confirm with user first
"I'll do all files at once"	Batch for trackability
"Pattern didn't match, skip silently"	Log warnings
"Version update not critical"	Always update on success

Related

• v3-structure.md
• migrations/ - Individual migration files