AGENT SKILL

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
所属仓库
Genomcore/inspire
最近更新
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

  1. The runtime is already on 0.15.0 or later (/inspire:update has run). The validators and skills of this version read only 01_spec/.
  2. jq and yq (Mike Farah v4) are on PATH.
  3. A clean working tree. If git status --porcelain is 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.sh on 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-exposure warnings: every face lists every bundle, because the layered layout did not say which bundles a face uses. Narrow each face's bundles:.
  • spec-identity warnings for a bundle with no package: — 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

Genomcore
Genomcore/inspire

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.

★ 0
Genomcore
Genomcore/inspire

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.

★ 0
Genomcore
Genomcore/inspire

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.

★ 0
Genomcore
Genomcore/inspire

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.

★ 0
Genomcore
Genomcore/inspire

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.

★ 0
Genomcore
Genomcore/inspire

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.

★ 0