migrate-spec
Skill4 starsChanged 2 months agoMITView on GitHub
Move one existing spec onto the SpecForge component library. Use when the user asks to "migrate <spec> to the component library", "put this spec on the new components", or "adopt the design system in <spec>". Runs the deterministic renames in code, reads the callouts that carry no type and assigns one to each, and leaves a migration report in the spec's store directory.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- danielvm-git/bigpowerstheir own version, first seen Nov 6, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- danielvm-git/bigpowers★ 288same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- convert-specSkill
- create-specSkill
- export-mdSkill
- exportSkill
- generate-templateSkill
- list-specsSkill
- review-specSkill
- start-specforgeSkill
- tune-templatesSkill
- write-reviewSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 91
Write your decisions as { "assignments": { "<key>": "<type>", ...
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
migrate-spec
Migration is never automatic (design D5). It runs on one spec, because a person asked for that spec.
${CLAUDE_PLUGIN_ROOT} below denotes the installed plugin directory. Claude and
Pi export it; Codex provides the exact value in SpecForge SessionStart context.
Substitute that value in every path and shell command. Specs live at
~/.specforge/specs/<id>/spec.html; you address them by id.
Never paste what the user typed into a command. A store id is 10 hex characters. If what you were given is anything else, look the spec up first and use the id that reports:
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" listallThe CLI refuses an id outside [A-Za-z0-9_-], but that check runs after the
shell has already parsed the line, so it is the second guard and not the first.
Two passes. The codemod is code, because a class rename is mechanical. Choosing
between warning, assumption and risk for a block requires reading it, and
that is your pass.
1. See what the codemod would do
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" components migrate <id> --dryWrites nothing. codemod lists the deterministic renames with counts;
assignments shows what the classifier would fall back to if you did nothing;
conflicts names any class the spec's own stylesheet redefines under a library
name, which is the one case where migrating changes how the spec looks.
Stop and tell the user if conflicts is non-empty. The spec's own rule wins
over the library's, so the block will render in the old style under a new name.
That is theirs to decide, not yours.
2. Read the blocks that need a type
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" components migrate <id> --planReturns { id, blocks: [{ index, key, source, text }] } — every callout the
codemod could not type. source is the legacy variant: warn, good, bad, or
"" for a bare callout. key is a hash of the block's source and text, and is
how you name a block in step 3: it follows the block if the spec is edited
between the plan and the apply, and an assignment whose key matches nothing stops
the run rather than landing on the wrong block. If that happens, the spec moved
under you: re-run --plan and read the blocks again.
Assign a type to each from its text. Stay within the source's group: the tone is
part of what the original said, and moving a block from good to risk reverses
a claim its author made.
| Source | What the text says | Assign |
warn | names a trigger and a consequence | risk |
warn | states a belief that is not verified, or what would falsify it | assumption |
warn | states a limit, with a unit or a source | constraint |
warn | none of the above | warning |
"" | names a choice and an alternative | decision |
"" | gives a concrete instance of a rule stated nearby | example |
"" | none of the above | note |
good | recommends an action the reader may take or skip | tip |
good | none of the above | success |
bad | departs from a stated rule or principle | deviation |
bad | none of the above | danger |
The defaults are the weakest claim in each group on purpose. When the text does not decide it, take the default rather than guessing: an understatement is recoverable and the report names it for a later pass.
3. Apply
Write your decisions as { "assignments": { "<key>": "<type>", ... } }, keyed by
the key from the plan, and apply them:
node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" components migrate <id> --assign /tmp/<id>-assign.jsonAnything you leave out takes the classifier's default, so the spec is never left
half on each vocabulary. The run stamps the component block, sets
data-sf-components, and writes migration.json into the spec's directory
recording every rename and every assignment with by: "agent" or
by: "classifier".
4. Check it
node "${CLAUDE_PLUGIN_ROOT}/lib/lint-spec.mjs" ~/.specforge/specs/<id>/spec.htmlExpect no untyped notices and no tone class used as a type. Classes outside the library are expected and are not yours to remove: a class only this spec uses is not drift, and deleting it changes how the spec renders. The same goes for the CSS behind it, which the migration leaves in place.
Open the spec in the browser and look at it. The renames change which stylesheet paints each block, so a visual check is the only thing that catches a spec whose own rules were doing more than they appeared to.
5. Report
Say what was renamed, how many blocks you typed and on what evidence, and name
anything you took a default on. If conflicts was non-empty, say which classes
and what the user should look at.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.