edercnj/x-migrate-frontmatter

Skill: x-migrate-frontmatter

Migrates one file or a directory of markdown artifacts from frontmatter v2 to schema v3.0, adding requires-capabilities via a 4-stage hybrid pipeline.

Triggers

/x-migrate-frontmatter <file>                    — migrate single file
/x-migrate-frontmatter <dir>                     — migrate all .md under dir
/x-migrate-frontmatter <file> --dry-run          — show diff without writing
/x-migrate-frontmatter <file> --force-ai         — skip heuristics, go straight to AI inference

Parameters

| Flag | Type | Default | Description | |------|------|---------|-------------| | target | Path | — | Positional. File or directory to migrate. | | --dry-run | Boolean | false | Show diff; do not write or commit. | | --force-ai | Boolean | false | Skip heuristic stages; use AI inference directly. | | --commit | Boolean | true | Commit via x-commit-planning after writing. | | --catalog-root | Path | capabilities/ | Catalog root for capability ID lookup. |

Pipeline (4 stages per file)

Stage 1 — Path Heuristic

Map file path segments to known capability IDs using the path-to-capability table:

| Path pattern | Inferred capabilities | |-------------|----------------------| | skills/core/dev/x-spring-* | [framework.spring-boot.*] | | skills/core/data/*postgres* | [data.database.postgres] | | skills/core/dev/*jpa* | [data.persistence.jpa] | | skills/core/security/* | [security.*] | | rules/conditional/db-* | [data.database.*] | | knowledge/testing* | [testing.framework.*] | | Path has no match | → Stage 2 |

Stage 2 — Keyword Scan

Scan the file body for technology keywords and map to capabilities:

| Keyword(s) | Capability added | |-----------|-----------------| | postgres, PostgreSQL, JPA, Hibernate | data.database.postgres, data.persistence.jpa | | MongoDB, mongo | data.database.mongo | | Redis, Lettuce | data.cache.redis | | OAuth2, JWT, OIDC | security.authn.oauth2 | | Docker, Dockerfile | deployment.container.docker | | Kafka, KafkaListener | messaging.kafka.consumer | | No keywords match | → Stage 3 |

Stage 3 — AI Fallback (when stages 1+2 produce no results)

Invoke a general-purpose subagent with the file content to propose requires-capabilities.

Agent(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Infer requires-capabilities for {file}",
  prompt: "Read this skill/rule/agent file and infer which capability IDs from the catalog it requires. Return ONLY a YAML list of capability IDs. If none apply, return []. File path: {path}"
)

After AI inference: emit WARNING: AI inference used for {file} — manual review recommended.

Stage 4 — Write + Validate

1. Parse existing frontmatter (preserve all existing fields).

2. Add requires-capabilities: [<inferred IDs>] (or [] if none inferred).

3. Preserve visibility: internal and user-invocable: false when present (Rule 22).

4. Validate output against governance/schemas/frontmatter-3.0.json via FrontmatterValidator.

5. Write back to file.

6. When --commit=true, commit via:

   Skill(skill: "x-commit-planning", args: "--files <file> --message 'migrate(frontmatter): {file} → v3.0'")

Output Contract

| Field | Description | |-------|-------------| | filesProcessed | Count of .md files examined | | filesMigrated | Count successfully migrated | | filesFailed | Count failed (validator rejected output) | | warnings | List of AI-inference warnings | | dryRun | Boolean — whether writes were performed |

Error Codes

| Code | Condition | |------|-----------| | MIGRATION_FAILED | Validator rejects output after migration | | CATALOG_MISSING | --catalog-root path does not exist | | ARGS_INVALID | Unknown flag or missing target |

Recovery

If a file fails validation after migration, the original is preserved (backed up to <file>.v2.bak). Re-run with --force-ai to use AI inference instead of heuristics.

Integration Notes

Consumed by stories 0203-0214 (batch migration of 182 artifacts). FrontmatterValidator (story-0064-0201) validates every output before writing. x-commit-planning handles commit if --commit=true.