init
Read first (if ${CLAUDE_PLUGIN_ROOT} is empty, the plugin root is two
levels above this skill's base directory): ${CLAUDE_PLUGIN_ROOT}/skills/_shared/rules.md (plugin root, engine
commands, safety, commit, last line) and
${CLAUDE_PLUGIN_ROOT}/skills/_shared/model.md (file formats). Per-stack
extraction guidance: ${CLAUDE_PLUGIN_ROOT}/skills/init/stacks.md.
If the chosen workspace already has open-erd.yaml, stop and offer
/open-erd:sync instead.
1. Sources and workspace
- Ask which source repositories go into this ERD (absolute paths; one or more). Give each a short logical name (repo folder name, kebab-case) and confirm the names: they appear in every evidence string.
- Ask where to create the workspace. There is no default. It must be outside
every source repo (check that no source path is a prefix of it and vice
versa). Suggest a sibling folder such as
<parent>/<project>-erdonly as an example. - Create it:
mkdir -p <ws>/model <ws>/extract/facts
git -C <ws> init
printf 'open-erd.local.yaml\n.DS_Store\n' > <ws>/.gitignore
- Write
open-erd.yaml(schema_version: 1,sourcesnames only) andopen-erd.local.yaml(names + absolute paths). Formats inmodel.md.
2. Extract scripts
First find every model root of every source (stacks.md, "Finding every
model root first"): path gems, submodules, engines, packages, shared
folders. Show the user the list per source. A root outside the source path
becomes its own source after the user confirms its path. If an expected root
is missing (referenced but not on disk), stop here and tell the user what is
missing and where it is referenced; do not build a partial model.
Then for each source:
- Detect the stack(s) from marker files (
stacks.md). Tell the user what you found and which files the script will read. - Write
<ws>/extract/<source>.mjsfollowingstacks.md. Read enough of the real files first that the script handles this repo's actual idioms. - Show the full script, then ask permission to run it (rules.md, "Extract scripts: approval"). Do not run before a yes.
- Run it to
extract/facts/<source>.json. Read the stderr summary. If it missed files or idioms, fix the script, show the change, ask again, rerun.
Still useful after extraction: read models, services and clients yourself
for inferred and cross_db hints the script cannot see; record what you
used as evidence.
3. Optional: database metadata
Ask once whether the user wants to add metadata from a live database (gives real foreign keys, indexes, constraints). Only on yes, and for each database separately:
- Use the user's own CLI or MCP tool and connection; never ask for or store credentials.
- Read only catalog metadata (
information_schema,pg_catalog,SHOW CREATE TABLE,db.getCollectionInfos()): FKs, indexes, unique and check constraints, column comments. Row counts andDISTINCTenum values are a separate question each. NeverSELECTdata rows. - Show the exact queries before running them.
- Save the result, without hostnames or credentials, to
<ws>/extract/db-<db>.metadata.json(sorted, no timestamps).
Facts confirmed by metadata get kind: db_fk (when a constraint exists) and
db added to evidence.
4. Write the model
From the facts files (and metadata cache), write one model/<db>.yaml per
logical database and model/cross-db.yaml when needed, following every rule in
model.md "Writing facts": table ids, direction, kind, evidence with the
source name prefix, review: pending, English notes, enum meanings (only
what code reveals; empty rather than the value restated), pii,
and each column's default, auto_increment and generated from the facts.
Write a note on every table, every column and every polymorphic entry,
not only the important ones: the Excel table sheets show it as the Comment of
each column. Read how services, controllers, jobs and operations use a table
before writing its note, and describe that business meaning rather than
restating the name; where the code shows no business meaning, say what the
value does technically, in technical terms (readers are developers). Keep
each column note short (about 15 words at most) and say only what code,
schema comments or names show; when nothing does, leave the note out rather
than write a placeholder such as Unclear from code. (model.md, "Writing
facts").
5. Domains
Group tables into domains (5–15 tables each when possible; by bounded context,
module folder, table prefix, then relation density). Present the proposal as a
list Domain: table, table, … per database and ask the user to approve or
change it. Write domain only after approval, then give every domain a
one-sentence business description under domains: in its database's model
file (model.md, "note on a domain"), learned from how the code uses its
tables. In the same message propose
collapse_join_tables and hubs: hub.columns for audit and scoping columns
first, hub.tables only for cross-cutting tables such as users or
tenants, never a business table a domain is built around, and the
polymorphic associations to turn into badges (model.md, open-erd.yaml),
each with its reason.
6. Validate, layout, render
node <plugin root>/dist/open-erd.mjs validate --workspace <ws>
node <plugin root>/dist/open-erd.mjs layout --workspace <ws>
node <plugin root>/dist/open-erd.mjs render --workspace <ws>
Fix validation errors in the model and rerun until it passes. Then, before
layout, run the missing-relation review (rules.md, "Missing-relation
review"), then the verification of the whole model (rules.md,
"Verification").
7. Commit and report
Commit in the workspace (rules.md, "Committing the workspace"):
init: ERD from <source>@<sha>[, <source>@<sha>…], with the verify: ...
line verify printed in the body (none when verify: off).
Report to the user: workspace path, output files the engine printed, counts
(databases, tables, relations, polymorphic), and how many facts are pending
review, with the next step /open-erd:review. Mention that the workspace is
not pushed anywhere. End with the feedback line.