migrate
Move this project's knowledge base from the layered layout (01_adr, 02_modules, 03_features, 04_domain, 05_screens and the surface roster) to the concept layout under inspire_kb/01_spec/, where every artifact has a typed extension, and convert its [[wikilinks]] to relative Markdown links. Run once, on purpose, after /inspire:update reports the layered layout or counts wikilinks. Rebuilds nothing that is already built.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- migrate
- description
- Move this project's knowledge base from the layered layout (01_adr, 02_modules, 03_features, 04_domain, 05_screens and the surface roster) to the concept layout under inspire_kb/01_spec/, where every artifact has a typed extension, and convert its [[wikilinks]] to relative Markdown links. Run once, on purpose, after /inspire:update reports the layered layout or counts wikilinks. Rebuilds nothing that is already built.
03 SKILL.md 正文
/inspire:migrate — the KB by concept
INSPIRE 0.15.0 reads the specification only from inspire_kb/01_spec/, where every
artifact is found by its typed extension (.module.md, .feature.md, .entity.md,
.action.md, .adr.md, .bundle.md, .face.md, .screen.md, .process.md…).
This skill moves a KB written in the layered layout there, once. It is the only
step that moves anything in inspire_kb/: /inspire:update never does
(adr-kb-structure
D10).
From 0.17.0 a KB link is a relative Markdown link to the target file,
[adr-audit](../../_adr/audit.adr.md). The skill converts every [[wikilink]] in
its own step
(adr-markdown-links
D6). A KB already on the concept layout that still holds wikilinks starts at
Step 4: its links are converted and nothing moves.
What it never does: rename a module, an entity or an action; change any id but a
screen's; point a link at a different file; extract a shared screen into a pattern;
create a process, or a bundle with an artifact of its own; write to git.
Every screen id it changes goes into inspire_kb/01_spec/_migration/id-map.json,
which INSPIRE Factory 0.16.0 or later reads to rewrite the built code instead of
rebuilding it.
Preconditions
- The runtime is already on 0.15.0 or later (
/inspire:updatehas run). The validators and skills of this version read only01_spec/. jqandyq(Mike Farah v4) are onPATH.- A clean working tree. If
git status --porcelainis non-empty, stop and ask the operator to commit or stash first: the moves must be committed on their own, before any edit, so git records them as renames and the history of every file survives.
Step 1 — Dry run, and the questions it asks
"${CLAUDE_PLUGIN_ROOT}/scripts/migrate-kb.sh" --dry-run --kb inspire_kb
It prints the plan, one tab-separated line per step (move, write, idmap,
unplaced, config, note), and writes nothing. A config line names a file outside
the KB, .inspire/emanate.yml or .inspire/emanate.json, and the change to its spec
root, which moves to inspire_kb/01_spec. Step 2 also prints a seed line for each
skeleton file --skeleton adds. When it needs an answer it prints ask lines
instead and exits 3. Ask the operator each one, in their words, then run the dry run
again with the answers as flags:
ask key |
Question | Flag |
|---|---|---|
face |
No roster, but there are screens: every screen moves to one face. What is its id? Propose the project's name in kebab-case. | --face ID |
bundle |
No roster: every module is exposed by one bundle. What is its id (propose api), and which package exposes it (source_root-relative, for example apps/api)? |
--bundle ID --bundle-package PATH |
bundle-modules:{id} |
The roster has several headless surfaces: which modules does {id} serve? Read the ADR that partitions them if there is one, and propose it. |
--bundle-modules {id}=m1,m2 |
lib:{id} |
The lib surface {id}: does it become a bundle (a package with code of its own) or part of the design system (a UI kit)? |
--lib {id}=bundle or --lib {id}=design-system |
shared-face |
05_screens/shared/ holds screens two faces use. Which face keeps them? Nothing is extracted; each other face can add its own screen later. |
--shared-face ID |
Never answer a question yourself: these are specification decisions.
Relay the plan grouped: how many files move per kind, every screen id that changes
(the idmap lines, old → new), every file it cannot place (unplaced: moved under
_migration/unplaced/, never dropped), every config change and every note. Add how many wikilinks
the KB holds outside code:
"${CLAUDE_PLUGIN_ROOT}/scripts/migrate-links.sh" --count --kb inspire_kb
Ask the operator to confirm before Step 2.
Step 2 — Migrate
"${CLAUDE_PLUGIN_ROOT}/scripts/migrate-kb.sh" --kb inspire_kb {the same answer flags} \
--skeleton "${CLAUDE_PLUGIN_ROOT}/base/kb/01_spec"
--skeleton adds the READMEs, the starter patterns and the default theme the layered
layout never had, and seeds design-system.md from the theme if the project had none —
only where nothing is on disk. The plan it applied is saved to
inspire_kb/01_spec/_migration/plan.tsv.
It refuses, and moves nothing, when:
01_spec/already exists beside layered directories (a half-migrated KB) — find out what put it there before going on;- a screen id is used by more than one screen — the id map would be ambiguous. Run
.inspire/bin/screen-coherence.shon the old tree with the previous runtime, or fix the duplicate by hand, and run again.
A second run on a migrated KB is a no-op.
Step 3 — Commit the moves on their own
Tell the operator to commit now, before any edit:
git add -A && git commit -m "chore(kb): move the KB to 01_spec (/inspire:migrate)"
The tree was clean before Step 2, so every change is the run's: the KB, and the file of
each config line. git status --porcelain is empty afterwards; the Factory's remap
refuses a dirty checkout. Do not commit for them unless they ask you to. Step 4 waits
for this commit.
Step 4 — Convert the links
"${CLAUDE_PLUGIN_ROOT}/scripts/migrate-links.sh" --dry-run --kb inspire_kb
It prints one link line per link it converts (file, line, the source that resolved
it, the wikilink, the Markdown link), one draft or unlinked line per link it
settles, and writes nothing. A link resolves through, in order: its path, mapped
through the move record; its path against the current files; the id index, which
resolves a wikilink the way the validators did before 0.17.0 and reads the screen id
map, so the link names the file they read; its target as a pre-move file name, mapped
through the move record. A pre-move name two files had resolves nothing. The move
record is _migration/plan.tsv, or, when there is none, the renames git holds since
the commit before the layered directories left, read and never written; when the
history does not show that commit, ask the operator for it and pass --since REV.
A wikilink none of these resolves is settled without a person, because a wikilink left
in the KB stops the Factory. An ADR id (adr-{slug}), an entity id whose module
exists, an action id whose entity exists or a screen id whose face exists gets that
artifact's draft, from its template and in its first state, with one drafted line
per file; the link names it. Any other link becomes its text, one unlinked line each
with why: a retired file, a placeholder, an id that names no artifact type, or a name
a module and a face share.
A Markdown link already in the KB that names nothing where it stands is rebased, one
link … rebased line each: its path is read from the file's location before the move,
and a target that moved, or a directory whose files all moved to one directory, is
followed through the move record. A link to a layered directory, or to its README,
names the concept directory that took its contents (01_adr → _adr, 02_modules,
03_features and 04_domain → _modules, 05_screens → _faces), or that
directory's README, and a subdirectory follows the layout (02_modules/{m} →
_modules/{m}, 03_features/{m} → _modules/{m}/_features, 04_domain/{m} →
_modules/{m}/_domain, 05_screens/{f}/{m} → _faces/{f}/_screens, a screen index →
_faces/{f}/_index.md); when the directory a link maps to does not exist, it names
the nearest directory on that path that does. No link is converted or rebased into
_migration/. A Markdown link it can neither rebase nor resolve, hand-written ones
included, becomes its text, with an unlinked line and why (retired, placeholder,
broken), so the migrated KB holds no broken link. A template (*.template.md) is
converted like any other file, a placeholder path mapped through the layout, and its
links are never unlinked or listed as broken.
The new link's text is the wikilink's alias, else the last segment of its target,
so a link in a screen's ## Bindings keeps the screen id it named. An anchor
([[b#context]]) stays on the new path, an embed (![[b]]) keeps its !, a path
holding a space or a parenthesis is written in <…>, and a link in frontmatter is a
quoted string. Links inside code spans and fenced blocks stay as written.
Relay the count per source, the rebased count, and every drafted and unlinked
line: a draft is a file to fill in, and an unlinked one is text the operator may want
to link again. Then run it without --dry-run;
it refuses while git lists uncommitted moves, additions or deletions under the KB
(Step 3 comes first), but not for the drafts an earlier conversion wrote. The link plan
is saved to inspire_kb/01_spec/_migration/links.tsv, and a second run changes
nothing.
Tell the operator to commit the conversion:
git add -A inspire_kb && git commit -m "chore(kb): convert KB links to relative Markdown links (/inspire:migrate)"
Step 5 — Review, then narrow
.inspire/bin/review.sh inspire_kb
Expected after a migration, and fine to fix in a later commit:
face-exposurewarnings: every face lists every bundle, because the layered layout did not say which bundles a face uses. Narrow each face'sbundles:.spec-identitywarnings for a bundle with nopackage:— fill it in before the Factory plans the bundle's mount test.
Anything else the review reports was already wrong before the migration, or is a defect in it: report the second kind.
Step 6 — The INSPIRE Factory
Tell the operator what comes next for code already built: INSPIRE Factory 0.16.0 or
later reads _migration/id-map.json, rewrites the screen
ids in the built code and the claim citations that name them, and commits that as a
branch for review, without running any agent. It rewrites literals only: code that
reads a screen id's shape (its first segment was the module, it is now the face) is
not text it can fix, so its report lists those sites to review by hand. The test
suite runs on that branch before it is merged. The only new units it plans are the
grouping bundles, one mount test each. An older Factory refuses this KB and says why.
The same run rewrites the fingerprint of each built claim whose payload differs only in link syntax (adr-markdown-links D8), so the converted links rebuild nothing. That Factory reads Markdown links only and refuses a KB that still holds a wikilink; an older Factory does not read Markdown links.
04 同仓库更多 Skills
update
Update this project's INSPIRE runtime to the installed plugin's version: report drift, re-materialize unchanged files, and refuse to clobber local edits. Use after /plugin update inspire reports a newer base.
init
Install the INSPIRE runtime into this repository: materialize the skills, validators, hooks and knowledge-base skeleton, register the hooks, and freeze the runtime version. Run once per project. Use when setting up INSPIRE in a new or existing repo.
inspire-workspace
Workspace-level validation: the global pre-PR review (orchestrating module + cross-module checks) and vault-structure validation. Use for the required pre-merge gate and top-level structure checks. ADR lifecycle lives in /inspire-adr; the task tracker in /inspire-task.
inspire-task
Task tracker: create / update / close / list / show tickets in inspire_kb/99_tracker/. A plain-file kanban (one Markdown file per ticket, no external tool) for tracking work, drift, and skill-feedback. Use to open, advance, close, or query tickets.
inspire-spike
Vertical spikes: register and harvest external functional-prototype repos. A spike is a narrow, deep, throwaway build in its OWN repo that answers 'can we build it as we think?'. Use to register such a repo (name/reference it, set up its learnings hygiene) and to capture its learnings into the vault as a gap analysis against the current project.
inspire-screens
Create and validate screens (a screen is the UI spec for one view). A screen declares its own bindings — data sources, dispatches, navigation, states — and names a shared layout and shared components as dependencies. Use when designing or reviewing an application's screens.