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
1---2name: migrate3description: Scan the project and migrate existing documentation into OKF format. Use when the user wants to populate the knowledge base from existing docs, README, schemas, API specs, runbooks, or any structured project knowledge. Trigger on "migrate to okf", "populate the knowledge base", "scan my docs", "convert docs to okf", "importar documentação", "migrar para okf", "popular o knowledge base", "lê meus docs e cria o okf", "generate okf from existing docs", or when the user points at a docs folder and asks to "put it in the knowledge base". If no OKF files exist yet, run /mega-brain:init before migrating.4---56# migrate — Migrate Existing Docs to OKF78Reads 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.910## Before starting1112Look 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.1314If `.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.1516## Process1718### 1. Discover sources1920Scan the project root. Priority order:2122| Source | Look for |23|--------|----------|24| API specs | `openapi.yaml`, `swagger.json`, `*.openapi.yml` |25| DB schemas | `schema.sql`, `schema.prisma`, `*.dbml`, migration files |26| Data models | `models/`, `entities/`, `domain/` |27| README sections | `## API`, `## Schema`, `## Architecture`, `## Data` |28| Runbooks | `docs/runbook*`, `runbooks/`, `playbooks/` |29| Env/config docs | `.env.example` with comments, annotated `config/` files |30| Existing wikis | `docs/`, `wiki/`, `pages/` |3132Report what you found before proceeding. If more than 10 sources, ask the user to confirm before generating all files.3334### 2. Classify each source → OKF type3536| Source content | OKF type |37|----------------|----------|38| DB table / Prisma model | `Table` or `BigQuery Table` |39| REST/GraphQL endpoint | `API` |40| Business metric / KPI | `Metric` |41| Microservice / module | `Service` |42| Operational procedure | `Runbook` |43| Business term / glossary | `Concept` |44| Data pipeline / ETL | `Pipeline` |4546### 3. Generate OKF files4748One `.md` file per concept:4950```markdown51---52type: <classified type>53title: <name>54description: <one sentence, plain language>55resource: <source file path or URL>56tags: [<relevant tags>]57timestamp: <today ISO date>58---5960# Schema / Definition6162<exact content extracted from source — preserve all field names, types, values>6364# Notes6566<caveats, deprecations, gotchas found in the source>67```6869**Rules that matter:**70- One concept per file — split tables from each other, endpoints from each other71- Preserve exact field names, column types, enum values, formulas — never generalize72- Add wikilinks `[Name](relative-path.md)` when concepts reference each other73- Place files in `tables/`, `apis/`, `metrics/`, `services/`, `runbooks/` as appropriate7475### 4. Update `index.md`7677Add one line per new concept under the relevant section in the project's existing `index.md` (create one via `/mega-brain:init` if missing):7879```markdown80- [Title](subdir/file.md) — one-sentence description81```8283### 5. Append to `log.md`8485```86<today ISO date> — migrated <N> concepts from <source list>87```8889### 6. Report9091List every file created with its type and path. Flag anything ambiguous or skipped with a reason.9293Tell the user to **start a new Claude Code session** for the injected context to activate.9495## What NOT to migrate9697- Test fixtures and mock data98- Build artifacts and generated code99- Duplicate docs — keep the most recent or canonical version100- Files with no extractable schema, formula, or definition
guhcostan