migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migration Skill

迁移Skill

Migrate a project from npm-installed metaswarm (

npx metaswarm init

) to the marketplace plugin. Removes redundant embedded files with a safety protocol that prevents data loss.

When to use: The SessionStart hook detects

.claude/plugins/metaswarm/.claude-plugin/plugin.json

(legacy embedded plugin) and recommends running this skill.

将项目从npm安装的metaswarm（

npx metaswarm init

）迁移到市场插件。通过防止数据丢失的安全协议移除冗余的嵌入文件。

使用时机：SessionStart钩子检测到

.claude/plugins/metaswarm/.claude-plugin/plugin.json

（旧版嵌入插件）时，会推荐运行此Skill。

IMPORTANT: Safety & Messaging Guidelines

重要提示：安全与沟通准则

The user MUST understand this before any file list is shown:

Before presenting any migration preview or file list, ALWAYS lead with this framing:

What this migration does: The marketplace plugin now provides all the skills, commands, rubrics, and guides that were previously copied into your project directory. This migration simply removes those redundant copies — the originals now live in the plugin itself.

Nothing is lost: Your project-specific files (CLAUDE.md, .coverage-thresholds.json, .beads/, bin/, scripts/) are NEVER touched. Only duplicate metaswarm framework files are removed.
Fully reversible: All removals are staged with
git rm
(not permanently deleted). Before you commit:
Undo everything:
git restore --staged . && git checkout -- .
After committing:
git revert HEAD
No commit is made automatically — you review and commit when you're satisfied.

Tone: Be reassuring, not alarming. Say "cleaning up XX redundant copies" not "deleting XX files". Say "these files now live in the plugin" not "these files will be removed". Frame the migration as housekeeping, not destruction.

When showing file counts: If there are many files (e.g., 40+), explain that the large count is because the old npm installer copied the entire plugin framework into

.claude/plugins/metaswarm/

— that one directory accounts for most of the count, and it's all framework code that's now served directly by the plugin.

在展示任何文件列表前，用户必须了解以下内容：

在展示任何迁移预览或文件列表前，务必先说明以下内容：

本次迁移的作用：市场插件现在提供了所有之前复制到你项目目录中的skills、命令、评分标准和指南。本次迁移仅会移除这些冗余副本——原版内容现在存储在插件本身中。

不会丢失任何内容：你的项目专属文件（CLAUDE.md、.coverage-thresholds.json、.beads/、bin/、scripts/）绝不会被改动。仅会移除重复的metaswarm框架文件。
完全可逆：所有移除操作都通过
git rm
暂存（不会永久删除）。在提交前：
撤销所有操作：
git restore --staged . && git checkout -- .
提交后：
git revert HEAD
不会自动提交——你可以在满意后再审核并提交。

语气：要让人安心，不要引起恐慌。要说“清理XX个冗余副本”而非“删除XX个文件”。要说“这些文件现在存储在插件中”而非“这些文件将被移除”。将迁移描述为整理工作，而非销毁操作。

展示文件数量时：如果文件数量较多（如40+），请解释数量多是因为旧版npm安装器将整个插件框架复制到了

.claude/plugins/metaswarm/

目录下——该目录占了大部分文件数量，且这些都是框架代码，现在由插件直接提供。

Step 1: Pre-flight Check

步骤1：预检检查

Confirm this skill is running from the marketplace plugin (if this skill loaded, the plugin is active)
Read
```
.metaswarm/project-profile.json
```
-- if
```
"distribution": "plugin"
```
is already set, inform the user migration was already completed and exit
Verify
```
.claude/plugins/metaswarm/.claude-plugin/plugin.json
```
exists -- if not, there is nothing to migrate; inform the user and exit

If the plugin is not loaded, the user needs to install it first:

/plugin marketplace add dsifry/metaswarm-marketplace

确认此Skill从市场插件运行（如果此Skill已加载，则插件已激活）
读取
```
.metaswarm/project-profile.json
```
——如果已设置
```
"distribution": "plugin"
```
，告知用户迁移已完成并退出
验证
```
.claude/plugins/metaswarm/.claude-plugin/plugin.json
```
是否存在——如果不存在，则无需迁移；告知用户并退出

如果插件未加载，用户需要先安装：

/plugin marketplace add dsifry/metaswarm-marketplace

Step 2: Inventory Legacy Files

步骤2：清点旧版文件

Scan for files installed by

npx metaswarm init

that are now provided by the marketplace plugin.

Candidates for removal:

Category	Path pattern
Embedded plugin	`.claude/plugins/metaswarm/` (entire directory)
Rubrics	`.claude/rubrics/*.md`
Guides	`.claude/guides/*.md`
Old commands	`.claude/commands/metaswarm-setup.md` , `.claude/commands/metaswarm-update-version.md`

NEVER removed (project-local files):

CLAUDE.md

.coverage-thresholds.json

.metaswarm/project-profile.json

.beads/

bin/

scripts/

.github/workflows/

.claude/commands/

shims.

扫描由

npx metaswarm init

安装、现在由市场插件提供的文件。

待移除候选文件：

类别	路径模式
嵌入插件	`.claude/plugins/metaswarm/` （整个目录）
评分标准	`.claude/rubrics/*.md`
指南	`.claude/guides/*.md`
旧命令	`.claude/commands/metaswarm-setup.md` 、 `.claude/commands/metaswarm-update-version.md`

绝不会移除的文件（项目本地文件）：

CLAUDE.md

、

.coverage-thresholds.json

、

.metaswarm/project-profile.json

、

.beads/

、

bin/

、

scripts/

、

.github/workflows/

、

.claude/commands/

垫片文件。

Step 3: Content Verification

步骤3：内容验证

For each removal candidate, verify it is an unmodified metaswarm file using SHA-256 hash comparison.

Hash protocol:

Read file content
Normalize line endings to LF (
```
\r\n
```
->
```
\n
```
,
```
\r
```
->
```
\n
```
)
Strip trailing whitespace from each line
Strip trailing newlines
Compute SHA-256 of normalized content
Compare against hash of the corresponding file from the marketplace plugin's own directories (rubrics/, guides/, etc.)

Computing hashes from the plugin's live files ensures the hash list stays current -- no hardcoded hashes that drift.

Classification:

Result	Action
Hash matches	Unmodified -- add to deletion list
Hash differs	User-modified -- flag for user decision, never auto-delete
Not in hash list	Unknown file -- skip entirely

对于每个待移除候选文件，通过SHA-256哈希对比验证其是否为未修改的metaswarm文件。

哈希协议：

读取文件内容
将行尾统一为LF（
```
\r\n
```
->
```
\n
```
，
```
\r
```
->
```
\n
```
）
移除每行末尾的空白字符
移除末尾的换行符
计算标准化内容的SHA-256哈希
与市场插件自身目录（rubrics/、guides/等）中对应文件的哈希进行对比

从插件的实时文件计算哈希可确保哈希列表保持最新——不会出现哈希值偏差的硬编码情况。

分类处理：

结果	操作
哈希匹配	未修改——加入删除列表
哈希不同	用户已修改——标记供用户决策，绝不自动删除
不在哈希列表中	未知文件——完全跳过

Step 4: Dry Run Preview

步骤4：试运行预览

Display the complete migration plan before any changes. Lead with the safety framing from the guidelines above, then show the preview:

undefined

在进行任何更改前展示完整的迁移计划。先按照上述准则说明安全内容，再展示预览：

undefined

Migration Preview

迁移预览

These are redundant copies of framework files that are now provided by the plugin. All removals are staged (not committed) — you can undo everything before committing.

这些是现在由插件提供的框架文件的冗余副本。所有移除操作都已暂存（未提交）——你可以在提交前撤销所有操作。

Redundant framework files to clean up (XX files)

待清理的冗余框架文件（XX个）

These are unmodified copies that the plugin now provides directly:

.claude/plugins/metaswarm/ (embedded plugin copy — XX files, now served by marketplace plugin)
.claude/rubrics/<each matching file> (now in plugin's rubrics/)
.claude/guides/<each matching file> (now in plugin's guides/)
.claude/commands/metaswarm-setup.md (replaced by plugin command)
.claude/commands/metaswarm-update-version.md (replaced by plugin command)

这些是插件现在直接提供的未修改副本：

.claude/plugins/metaswarm/（嵌入插件副本——XX个文件，现在由市场插件提供）
.claude/rubrics/<每个匹配文件>（现在位于插件的rubrics/中）
.claude/guides/<每个匹配文件>（现在位于插件的guides/中）
.claude/commands/metaswarm-setup.md（已被插件命令替代）
.claude/commands/metaswarm-update-version.md（已被插件命令替代）

Files you've customized (require your decision)

你已自定义的文件（需你决策）

.claude/rubrics/code-review-rubric.md (MODIFIED — your changes are preserved until you decide)

.claude/rubrics/code-review-rubric.md（已修改——你的更改会保留到你做出决策为止）

Your project files (NEVER touched)

你的项目文件（绝不会被改动）

CLAUDE.md, .coverage-thresholds.json, .metaswarm/, .beads/, bin/, scripts/

CLAUDE.md、.coverage-thresholds.json、.metaswarm/、.beads/、bin/、scripts/

What gets added

新增内容

6 command shims in .claude/commands/ (thin wrappers that route to plugin commands)
.metaswarm/project-profile.json updated with "distribution": "plugin"

.claude/commands/中的6个命令垫片（路由到插件命令的轻量包装器）
.metaswarm/project-profile.json更新为包含"distribution": "plugin"

How to undo (before committing)

如何撤销（提交前）

git restore --staged . && git checkout -- .

---

git restore --staged . && git checkout -- .

---

Step 5: User Confirmation

步骤5：用户确认

Use

AskUserQuestion

Remind the user: "This stages the cleanup — nothing is committed yet. You can undo with
```
git restore --staged . && git checkout -- .
```
"
Ask: "Ready to clean up the redundant framework files?" (not "Ready to delete files?")
For each user-modified file, ask individually: keep, remove, or show diff
If the user chooses "diff", display the difference between their version and the plugin's, then re-ask

使用

AskUserQuestion

：

提醒用户：“这会暂存清理操作——尚未提交任何内容。你可以使用
```
git restore --staged . && git checkout -- .
```
撤销操作。”
询问：“准备好清理冗余框架文件了吗？”（不要问“准备好删除文件了吗？”）
对于每个用户修改过的文件，单独询问：保留、移除或显示差异
如果用户选择“差异”，展示他们的版本与插件版本的区别，然后再次询问

Step 6: Git Safety

步骤6：Git安全检查

Before executing removals:

Run
```
git status
```
to check for uncommitted changes
If uncommitted changes exist, warn: "Recommended to commit or stash before migrating so changes are in their own commit. Continue anyway?"
If the user declines, exit

执行移除操作前：

运行
```
git status
```
检查是否有未提交的更改
如果存在未提交的更改，警告：“建议在迁移前提交或暂存更改，以便将更改放在单独的提交中。是否继续？”
如果用户拒绝，退出

Step 7: Cleanup

步骤7：清理操作

Announce what you're doing: Before running any commands, say:

"Staging the redundant files for removal. These are all framework copies — your project files are untouched. Nothing is committed yet."

Git-tracked files -- use

git rm

(staged, reversible via

git checkout

bash

git rm -rf .claude/plugins/metaswarm/
git rm .claude/rubrics/<each confirmed file>
git rm .claude/guides/<each confirmed file>
git rm .claude/commands/metaswarm-setup.md
git rm .claude/commands/metaswarm-update-version.md

After running: Reassure: "Done — XX files staged for removal. These are only staged, not committed. Run

git status

to see the staged changes, or

git restore --staged . && git checkout -- .

to undo."

Untracked files -- use

rm -f

(unlikely but handle gracefully).

Empty directories -- remove

.claude/rubrics/

and

.claude/guides/

if empty after cleanup. Do NOT remove

.claude/commands/

(shims remain).

说明操作内容：在运行任何命令前，告知：

“正在暂存冗余文件以进行移除。这些都是框架副本——你的项目文件未被改动。尚未提交任何内容。”

Git追踪文件——使用

git rm

（暂存状态，可通过

git checkout

撤销）：

bash

git rm -rf .claude/plugins/metaswarm/
git rm .claude/rubrics/<每个确认的文件>
git rm .claude/guides/<每个确认的文件>
git rm .claude/commands/metaswarm-setup.md
git rm .claude/commands/metaswarm-update-version.md

运行后：安抚用户：“完成——XX个文件已暂存待移除。这些仅处于暂存状态，未提交。运行

git status

查看暂存的更改，或使用

git restore --staged . && git checkout -- .

撤销。”

未追踪文件——使用

rm -f

处理（可能性低，但需优雅处理）。

空目录——清理后如果

.claude/rubrics/

和

.claude/guides/

为空，则移除它们。不要移除

.claude/commands/

（垫片文件保留）。

Step 8: Command Shim Creation

步骤8：命令垫片创建

Write 6 shims to

.claude/commands/

(same as setup skill):

Shim	Routes to
`start-task.md`	`/metaswarm:start-task`
`prime.md`	`/metaswarm:prime`
`review-design.md`	`/metaswarm:review-design`
`self-reflect.md`	`/metaswarm:self-reflect`
`pr-shepherd.md`	`/metaswarm:pr-shepherd`
`brainstorm.md`	`/metaswarm:brainstorm`

Each shim:

markdown

<!-- Created by metaswarm setup. Routes to the metaswarm plugin. Safe to delete if you uninstall metaswarm. -->
Invoke the `/metaswarm:<command-name>` skill with any arguments the user provided.

If a shim already exists with different content, ask before overwriting.

向

.claude/commands/

写入6个垫片（与安装Skill相同）：

垫片	路由到
`start-task.md`	`/metaswarm:start-task`
`prime.md`	`/metaswarm:prime`
`review-design.md`	`/metaswarm:review-design`
`self-reflect.md`	`/metaswarm:self-reflect`
`pr-shepherd.md`	`/metaswarm:pr-shepherd`
`brainstorm.md`	`/metaswarm:brainstorm`

每个垫片内容：

markdown

<!-- Created by metaswarm setup. Routes to the metaswarm plugin. Safe to delete if you uninstall metaswarm. -->
Invoke the `/metaswarm:<command-name>` skill with any arguments the user provided.

如果已有内容不同的垫片，在覆盖前需询问用户。

Step 9: Profile Update

步骤9：配置文件更新

Merge these fields into

.metaswarm/project-profile.json

(preserve existing fields):

json

{
  "distribution": "plugin",
  "migrated_at": "<ISO 8601 timestamp>",
  "migrated_from": "npm"
}

将以下字段合并到

.metaswarm/project-profile.json

中（保留现有字段）：

json

{
  "distribution": "plugin",
  "migrated_at": "<ISO 8601 timestamp>",
  "migrated_from": "npm"
}

Step 10: Post-Migration Summary

步骤10：迁移后总结

Display what was done and next steps:

undefined

展示已完成的操作和后续步骤：

undefined

Migration Complete

迁移完成

Cleaned up XX redundant framework files that are now provided by the marketplace plugin. Your project files (CLAUDE.md, .coverage-thresholds.json, .beads/, etc.) were not touched.

已清理XX个现在由市场插件提供的冗余框架文件。你的项目文件（CLAUDE.md、.coverage-thresholds.json、.beads/等）未被改动。

What changed

更改内容

Removed XX redundant framework copies (now served by plugin)
Added 6 command shims to .claude/commands/
Updated project profile to "distribution": "plugin"

移除了XX个冗余框架副本（现在由插件提供）
在.claude/commands/中添加了6个命令垫片
将项目配置更新为"distribution": "plugin"

Next steps

后续步骤

Review staged changes:
```
git diff --cached --stat
```

Commit when satisfied:

git commit -m "chore: migrate metaswarm from npm to marketplace plugin"

Verify everything works: try
```
/start-task
```

查看暂存的更改：
```
git diff --cached --stat
```

满意后提交：

git commit -m "chore: migrate metaswarm from npm to marketplace plugin"

验证所有功能正常：尝试
```
/start-task
```

If anything seems wrong

如果出现问题

Undo before committing:

git restore --staged . && git checkout -- .

Undo after committing:
```
git revert HEAD
```
Full re-install:
```
npx metaswarm install
```
(npm package still available)

---

提交前撤销：

git restore --staged . && git checkout -- .

提交后撤销：
```
git revert HEAD
```
重新安装旧版本：
```
npx metaswarm install
```
（npm包仍可用）

---

Rollback (Nothing Is Permanent)

回滚操作（所有操作均可撤销）

All removals use

git rm

, which only stages changes — files are NOT deleted from git history. The migration never auto-commits, so the user always has a chance to review and undo:

Before committing (full undo):

git restore --staged . && git checkout -- .

After committing (full undo):
```
git revert HEAD
```
Single file recovery:
```
git checkout HEAD~1 -- <path>
```
Full re-install of old approach:
```
npx metaswarm install
```
(npm package still published)

所有移除操作都使用

git rm

，仅会暂存更改——文件不会从git历史中删除。迁移绝不会自动提交，因此用户始终有机会审核并撤销：

提交前（完全撤销）：

git restore --staged . && git checkout -- .

提交后（完全撤销）：
```
git revert HEAD
```
恢复单个文件：
```
git checkout HEAD~1 -- <path>
```
重新安装旧版本：
```
npx metaswarm install
```
（npm包仍已发布）

Error Handling

错误处理

Error	Action
`.metaswarm/project-profile.json` missing	Create with minimal fields, proceed
`git rm` fails on a file	Log error, skip file, continue
Permission denied	Warn user, skip file, continue
Plugin not loaded	Exit with install instructions
`metaswarm_version < 0.8.0`	Warn manual intervention may be needed

错误	操作
`.metaswarm/project-profile.json` 缺失	使用最小字段创建该文件，继续执行
`git rm` 操作文件失败	记录错误，跳过该文件，继续执行
权限被拒绝	警告用户，跳过该文件，继续执行
插件未加载	退出并显示安装说明
`metaswarm_version < 0.8.0`	警告可能需要手动干预

Anti-Patterns

反模式

Anti-Pattern	Do Instead
Auto-deleting modified files	Flag and ask explicitly
Deleting before confirming plugin works	Pre-flight check first
Using `rm -rf` on tracked files	Use `git rm` (reversible)
Skipping dry run preview	Always show full preview
Removing project-local files	Never touch CLAUDE.md, .beads/, bin/, scripts/
Saying "deleting XX files" or "removing XX files"	Say "cleaning up XX redundant copies"
Showing file list without safety context	Always lead with the safety framing
Jumping straight to `git rm` commands	Explain what you're doing and why it's safe first

反模式	正确做法
自动删除已修改的文件	标记并明确询问用户
在确认插件可用前就删除文件	先进行预检检查
对追踪文件使用 `rm -rf`	使用 `git rm` （可撤销）
跳过试运行预览	始终展示完整预览
移除项目本地文件	绝不改动CLAUDE.md、.beads/、bin/、scripts/
说“删除XX个文件”或“移除XX个文件”	说“清理XX个冗余副本”
不说明安全背景就展示文件列表	始终先说明安全内容
直接执行 `git rm` 命令	先解释操作内容及安全性