migrate

migrate — Migrate Existing Docs to OKF

Reads existing project documentation and generates OKF concept files so claude-mega-brain can inject them at session start. The goal is exact fidelity — preserve real column names, actual formulas, and specific values, not generic descriptions.

Before starting

Look for existing OKF files: any .md with type: frontmatter, or index.md / log.md anywhere in the project. If none exist, run /mega-brain:init first.

If .mega-brain.json defines dir, place new files under that directory. Otherwise, put files wherever fits the project (docs/, project root, etc.) — no dedicated folder is required.

Process

1. Discover sources

Scan the project root. Priority order:

Source	Look for
API specs	openapi.yaml, swagger.json, *.openapi.yml
DB schemas	schema.sql, schema.prisma, *.dbml, migration files
Data models	models/, entities/, domain/
README sections	## API, ## Schema, ## Architecture, ## Data
Runbooks	docs/runbook*, runbooks/, playbooks/
Env/config docs	.env.example with comments, annotated config/ files
Existing wikis	docs/, wiki/, pages/

Report what you found before proceeding. If more than 10 sources, ask the user to confirm before generating all files.

2. Classify each source → OKF type

Source content	OKF type
DB table / Prisma model	Table or BigQuery Table
REST/GraphQL endpoint	API
Business metric / KPI	Metric
Microservice / module	Service
Operational procedure	Runbook
Business term / glossary	Concept
Data pipeline / ETL	Pipeline

3. Generate OKF files

One .md file per concept:

---
type: <classified type>
title: <name>
description: <one sentence, plain language>
resource: <source file path or URL>
tags: [<relevant tags>]
timestamp: <today ISO date>
---

# Schema / Definition

<exact content extracted from source — preserve all field names, types, values>

# Notes

<caveats, deprecations, gotchas found in the source>

Rules that matter:

• One concept per file — split tables from each other, endpoints from each other
• Preserve exact field names, column types, enum values, formulas — never generalize
• Add wikilinks [Name](relative-path.md) when concepts reference each other
• Place files in tables/, apis/, metrics/, services/, runbooks/ as appropriate

4. Update index.md

Add one line per new concept under the relevant section in the project's existing index.md (create one via /mega-brain:init if missing):

- [Title](subdir/file.md) — one-sentence description

5. Append to log.md

<today ISO date> — migrated <N> concepts from <source list>

6. Report

List every file created with its type and path. Flag anything ambiguous or skipped with a reason.

Tell the user to start a new Claude Code session for the injected context to activate.

What NOT to migrate

• Test fixtures and mock data
• Build artifacts and generated code
• Duplicate docs — keep the most recent or canonical version
• Files with no extractable schema, formula, or definition