@ultime/codecraft 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.4.0 - 2026-10-27
+
+- 仓库改为 `skills/codecraft` 标准集合布局，可被 `skills` CLI 直接发现。
+- 移除 `codecraft install`、agent 注册表与自定义 agent；安装改由 `npx skills add ultime-space/skills --skill codecraft` 或 `skills-npm` 负责。
+- 发布 workflow、README、适配器与评测路径同步到集合布局。
+
 ## 1.3.0 - 2026-10-27
 
 - 新增 agent 注册表：内置 generic / claude / cursor / trae / trae-cn，`--list-agents` 查看项目 / 全局路径与检测结果。

package/README.md

@@ -43,62 +43,33 @@
 
 ## 安装
 
-### 方式 A：npm + skills-npm（推荐，多项目 / 团队）
+### 方式 A：skills CLI（推荐）
 
 ```bash
-npm i -D @ultime/codecraft skills-npm
-npx skills-npm setup
+npx skills add ultime-space/skills --skill codecraft
 ```
 
-之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 Claude / Trae / Cursor 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
-
-### 方式 B：Codecraft 自带安装器（单次，无额外依赖）
-
-```bash
-npx @ultime/codecraft install
-```
+不传 `-a` 时，CLI 会检测本机 agent 并让你多选；`-g` 装到用户目录，`-a` 指定 agent。agent 支持由 `skills` CLI 维护，本 skill 不枚举。
 
-自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.cursor/skills`、`.trae/skills`、`.trae-cn/skills`）。不传 `--agent` 时只按检测结果安装，不优先任何一家。
+### 方式 B：npm + skills-npm（多项目 / 团队）
 
 ```bash
-npx @ultime/codecraft install --agent generic          # 指定 agent，可逗号分隔
-npx @ultime/codecraft install --global --agent claude  # 装到用户目录
-npx @ultime/codecraft install --global --agent trae-cn # Trae CN 的全局目录
-npx @ultime/codecraft install --global --dest .trae-cn/skills  # 自定义目录
-npx @ultime/codecraft install --dry-run                # 只看计划
-npx @ultime/codecraft install --force                  # 覆盖已有目录
-```
-
-可选内置 agent：`generic` / `claude` / `cursor` / `trae` / `trae-cn`；用 `--list-agents` 查看实际路径与检测结果。
-
-自定义 agent 放在项目级 `codecraft.agents.json` 或用户级 `~/.codecraft/agents.json`（项目级覆盖用户级）：
-
-```json
-{
-  "agents": {
-    "my-agent": {
-      "project": ".my/skills",
-      "global": ".my/skills",
-      "markers": [".my"]
-    }
-  }
-}
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
 ```
 
-- `project` / `global`：项目内与全局的目标目录；`global` 省略时复用 `project`。
-- `markers`：`auto` 检测用的目录或文件；不填则只能显式 `--agent my-agent`。
-- 未知或临时目录仍可用 `--dest`，不必先写配置。
+之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 agent 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
 
 ### 方式 C：手动指针
 
 不复制文件，只在项目规则里留一行：
 
-- Trae：`.trae/rules/codecraft.md`
+- 通用：`AGENTS.md`
 - Claude：`CLAUDE.md` 或 `~/.claude/CLAUDE.md`
-- 其他：`AGENTS.md`
+- Trae：`.trae/rules/codecraft.md`
 
 ```md
-代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
+代码任务先读 <Codecraft 仓库路径>/skills/codecraft/adapters/trae/SKILL.md
 ```
 
 平台入口：
@@ -106,8 +77,8 @@ npx @ultime/codecraft install --force                  # 覆盖已有目录
 | 平台 | 入口文件 |
 |---|---|
 | 通用（读 `AGENTS.md`） | [`adapters/generic/AGENTS.md`](./adapters/generic/AGENTS.md) |
-| Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 | Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
+| Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 
 ## 第一次使用
 
@@ -154,7 +125,6 @@ codecraft <command> [options]
 | `audit` | 内置规则 + `codecraft.config.json` 里的 gates，出只读报告 |
 | `plan` | 把 findings 转成只读升级计划；默认不跑 gates |
 | `init` | 生成 app / library 骨架；默认 dry-run |
-| `install` | 把 skill 安装到 agent skills 目录；默认写入，`--dry-run` 只看计划 |
 | `version` | 输出版本号 |
 
 ### 常用
@@ -169,9 +139,6 @@ codecraft audit --config codecraft.config.json --fail-fast
 codecraft plan --root . --with-gates
 codecraft init --root . --name demo              # dry-run
 codecraft init --root . --name demo --apply      # 写盘
-codecraft install                                # 自动检测并安装
-codecraft install --agent trae,claude --force
-codecraft install --dry-run
 ```
 
 ### 参数
@@ -189,18 +156,13 @@ codecraft install --dry-run
 | `--with-gates` | — | 关 | `plan` 执行 gates |
 | `--name <name>` | 字符串 | — | `init` 的 app / package 名称；`--apply` 时必填 |
 | `--apply` | — | 关 | `init` 写盘；已存在路径跳过，不覆盖 |
-| `--agent <list>` | `auto` / `claude` / `trae` / `cursor` / `generic` | `auto` | `install` 目标，可逗号分隔 |
-| `--global` | — | 关 | `install` 写入用户目录 |
-| `--dest <path>` | 目录 | — | `install` 的显式目标 |
-| `--force` | — | 关 | `install` 覆盖已有 codecraft 目录 |
-| `--dry-run` | — | 关 | `install` 只输出计划，不写盘 |
 
 ### 退出码
 
 | 码 | 含义 |
 |---|---|
 | `0` | 通过；warning 不阻断 |
-| `1` | 有 error findings、install 失败，或有 gate 失败 |
+| `1` | 有 error findings，或有 gate 失败 |
 | `2` | 用法错误、root 不存在、配置非法 |
 
 ### 输出
@@ -265,7 +227,7 @@ docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
 adapters/     generic / Trae / Claude 手动指针
 prompts/      输出格式
-src/ + bin/   CLI（含 install）
+src/ + bin/   CLI（check / audit / plan / init）
 tests/        node:test 用例
 templates/    init --apply 的 app / library 骨架
 evals/        golden tasks（人工回归）
@@ -281,14 +243,13 @@ ROADMAP.md    后续版本计划与交接说明
 - 不按「感觉重要」升 major；`2.0` 不设时间表。
 - 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
 - 报告始终携带版本号；跨版本对比以 JSON 为准。
-- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/codecraft/ROADMAP.md)。
+- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/skills/codecraft/ROADMAP.md)。
 
 ## FAQ
 
 - **静态检查误报怎么办？** 在 `codecraft.config.json` 的 `ignore` 里登记 `rule` + `file` + `reason`，必要时加 `expires`；不要直接删规则。
 - **`Files: 0` 是什么意思？** 没有扫到源文件，命令会输出警告并以 2 退出；用 `--pack app|library` 指定正确类型，或检查 `--root`。
-- **Trae CN 装到哪？** 用 `--agent trae-cn`（`~/.trae-cn/skills`）；未知目录用 `--dest`。
-- **怎么支持新的 agent？** 在 `codecraft.agents.json` 里加 `project` / `global` / `markers`，再跑 `--list-agents` 确认；不需要等 Codecraft 发版。
+- **怎么装到指定 agent？** `npx skills add ultime-space/skills --skill codecraft`；交互选 agent，或用 `-a <agent>` 非交互。安装路径由 `skills` CLI 维护，本 skill 不枚举。
 - **`check` / `audit` / `plan` 有什么区别？** `check` 只跑内置规则；`audit` 额外跑 config 里的 gates；`plan` 只读，把 findings 转成计划，默认不跑 gates。
 - **为什么不自动跑 typecheck / test？** 门禁由项目提供，Codecraft 只编排，避免第二套实现。
 - **monorepo 为什么被判成 app / library？** 有 `pages/`、`app/`、`manifest.json + pages.json`、Taro / uni-app 依赖或嵌套应用时按 `app`；有 `packages/` 或 `src/` 时按 `library`；仍不确定就显式传 `--pack`。

package/VERSION

@@ -1 +1 @@
-1.3.0
+1.4.0

package/adapters/README.md

@@ -9,6 +9,6 @@ Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制
 
 规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。
 
-包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills-npm` / `codecraft install` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
+包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills add` / `skills-npm` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
 
 使用者提示词（怎么对 AI 说）：[`../docs/07-ai-prompts.md`](../docs/07-ai-prompts.md)。

package/docs/07-ai-prompts.md

@@ -10,9 +10,11 @@
 最快的方式：
 
 ```bash
-npx @ultime/codecraft install
+npx skills add ultime-space/skills --skill codecraft
 ```
 
+交互选择 agent；非交互用 `-a <agent>`，全局加 `-g`。
+
 或走 npm 同步：
 
 ```bash
@@ -24,12 +26,12 @@ npx skills-npm setup
 
 也可以手动在 agent 入口里留一条指针，不要复制规则：
 
-- Trae：项目 `.trae/rules/codecraft.md`
-- Claude：`CLAUDE.md`
 - 通用：`AGENTS.md`
+- Claude：`CLAUDE.md`
+- Trae：项目 `.trae/rules/codecraft.md`
 
 ```md
-代码任务先读 <Codecraft 仓库路径>/codecraft/adapters/<平台>/...
+代码任务先读 <Codecraft 仓库路径>/skills/codecraft/adapters/<平台>/...
 ```
 
 平台对应：Trae → `adapters/trae/SKILL.md`，Claude → `adapters/claude/SKILL.md`，其他 → `adapters/generic/AGENTS.md`。
@@ -39,7 +41,7 @@ npx skills-npm setup
 任何任务都可以先用这段，再补场景：
 
 ```text
-使用 Codecraft（<Codecraft 仓库路径>/codecraft）。
+使用 Codecraft（<Codecraft 仓库路径>/skills/codecraft）。
 模式：Audit / Plan / Apply。
 范围：<目录 / 包 / 文件 / diff>。
 任务：<一句话>。

package/evals/golden-tasks.md

@@ -109,12 +109,10 @@
 - 期望：命中 A21；只报文件与行号，不回显密钥；提示轮换。
 - 失败信号：漏报；把密钥原文打印到报告；把普通变量名误报为密钥。
 
-## 16. 安装到 agent
+## 16. 安装（已移出本 skill）
 
-- 输入：空项目，无 agent 配置目录。
-- 命令：`codecraft install --root . --agent generic`；再执行一次；最后 `--force`。
-- 期望：生成 `.agents/skills/codecraft/SKILL.md`、`docs/`、`scenarios/`、`prompts/`；第二次 skip；`--force` 覆盖。
-- 失败信号：复制到错误目录；覆盖用户已有内容；`SKILL.md` 引用断链。
+- 安装由 `skills` CLI 负责：`npx skills add ultime-space/skills --skill codecraft`。
+- 不在 Codecraft 规则评估范围内；本文件不再评估安装器行为。
 
 ## 评分
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",
@@ -18,9 +18,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ultime-space/skills.git",
-    "directory": "codecraft"
+    "directory": "skills/codecraft"
   },
-  "homepage": "https://github.com/ultime-space/skills/tree/main/codecraft",
+  "homepage": "https://github.com/ultime-space/skills/tree/main/skills/codecraft",
   "bugs": {
     "url": "https://github.com/ultime-space/skills/issues"
   },

package/src/cli.mjs

@@ -5,7 +5,6 @@ import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
 import { applyInitPlan, buildInitPlan } from './init.mjs'
 import { applyIgnores } from './ignore.mjs'
-import { applyInstallPlan, buildInstallPlan, listAgents, loadAgents, parseAgents } from './install.mjs'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const VERSION = PACKAGE.version
@@ -17,19 +16,12 @@ Commands:
   audit       check + configured gates; read-only report
   plan        Read-only upgrade plan from findings
   init        Scaffold an app or package (dry-run unless --apply)
-  install     Install the skill into agent skills directories
   version     Print version
 
 Options:
   --root <path>            Project root (default: cwd)
   --pack app|library|design-system|auto  Rule pack (default: auto)
   --config <path>          Config file (default: codecraft.config.json)
-  --agent <name>[,<name>]  Install target (default: auto; see --list-agents)
-  --list-agents            List registered agents, paths and detection
-  --global                 Install into the home directory
-  --dest <path>            Explicit destination (relative to root / home), e.g. .trae-cn/skills
-  --force                  Replace an existing codecraft skill directory
-  --dry-run                Show the install plan without writing
   --no-gates               Skip gates in audit / plan
   --with-gates             Run configured gates in plan
   --fail-fast              Stop gates after the first failure
@@ -60,7 +52,7 @@ export function main(argv) {
   }
 
   const command = args.command || 'check'
-  if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
+  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
     console.error(`codecraft: unknown command "${command}"\n  next: run codecraft --help`)
     return 2
   }
@@ -71,59 +63,6 @@ export function main(argv) {
     return 2
   }
 
-  if (args.listAgents) {
-    try {
-      const agents = listAgents(root, { global: args.global })
-      if (args.format === 'json') {
-        console.log(JSON.stringify({ version: VERSION, agents }, null, 2))
-      } else {
-        console.log(formatAgents(agents))
-      }
-      return 0
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 2
-    }
-  }
-
-  if (command === 'install') {
-    let agents
-    let registry
-    try {
-      registry = loadAgents(root, { global: args.global })
-      agents = parseAgents(args.agent, [...registry.keys()])
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 2
-    }
-    try {
-      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest, registry })
-      const applied = args.dryRun ? null : applyInstallPlan(plan, { force: args.force })
-      const meta = {
-        version: VERSION,
-        mode: 'install',
-        root,
-        scope: args.global ? 'global' : 'project',
-        agent: args.agent,
-        dest: args.dest || null,
-        dryRun: args.dryRun,
-        targets: plan.length,
-        created: applied?.created.length ?? 0,
-        replaced: applied?.replaced.length ?? 0,
-        skipped: applied?.skipped.length ?? 0,
-      }
-      if (args.format === 'json') {
-        console.log(JSON.stringify({ ...meta, plan, applied }, null, 2))
-      } else {
-        console.log(formatInstall(meta, plan, applied))
-      }
-      return plan.length ? 0 : 1
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 1
-    }
-  }
-
   let config
   try {
     config = loadConfig(root, args.config)
@@ -261,12 +200,6 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
-    agent: 'auto',
-    global: false,
-    dest: '',
-    force: false,
-    dryRun: false,
-    listAgents: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -283,13 +216,7 @@ function parseArgs(argv) {
     else if (arg === '--with-gates') args.withGates = true
     else if (arg === '--fail-fast') args.failFast = true
     else if (arg === '--apply') args.apply = true
-    else if (arg === '--global') args.global = true
-    else if (arg === '--force') args.force = true
-    else if (arg === '--dry-run') args.dryRun = true
-    else if (arg === '--list-agents') args.listAgents = true
     else if (arg === '--name') args.name = argv[++i] ?? ''
-    else if (arg === '--agent') args.agent = argv[++i] ?? 'auto'
-    else if (arg === '--dest') args.dest = argv[++i] ?? ''
     else if (arg === '--root') args.root = argv[++i] ?? '.'
     else if (arg === '--pack') args.pack = argv[++i] ?? 'auto'
     else if (arg === '--config') args.config = argv[++i] ?? ''
@@ -521,67 +448,6 @@ function formatInit(meta, plan, applied) {
   return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
 }
 
-function formatAgents(agents) {
-  const lines = [
-    '# Codecraft Agents',
-    '',
-    `- Version: ${VERSION}`,
-    '',
-    '| Name | Source | Project | Global | Detected |',
-    '|---|---|---|---|---|',
-  ]
-  for (const agent of agents) {
-    const detected =
-      [agent.detected.project ? 'project' : '', agent.detected.global ? 'global' : ''].filter(Boolean).join(', ') ||
-      '—'
-    lines.push(`| ${agent.name} | ${agent.source} | ${agent.project} | ${agent.global} | ${detected} |`)
-  }
-  return lines.join('\n')
-}
-
-function formatInstall(meta, plan, applied) {
-  const lines = [
-    '# Codecraft Install',
-    '',
-    `- Version: ${meta.version}`,
-    `- Mode: install`,
-    `- Scope: ${meta.scope}`,
-    `- Agent: ${meta.agent}`,
-    `- Root: ${meta.root}`,
-    `- Dest: ${meta.dest ?? '（auto）'}`,
-    `- Dry run: ${meta.dryRun}`,
-    `- Targets: ${meta.targets}`,
-  ]
-
-  if (applied) {
-    lines.push(
-      `- Created: ${meta.created}`,
-      `- Replaced: ${meta.replaced}`,
-      `- Skipped: ${meta.skipped}`,
-    )
-  }
-
-  if (!plan.length) {
-    lines.push('', '未找到可安装的目标；请用 `--agent` 指定，或先创建 agent 配置目录。')
-  } else {
-    lines.push('', '## Plan', '', '| Agent | Target | Action |', '|---|---|---|')
-    for (const entry of plan) {
-      lines.push(`| ${entry.agent} | ${entry.target} | ${entry.action} |`)
-    }
-  }
-
-  lines.push(
-    '',
-    '## Next',
-    '',
-    meta.dryRun
-      ? '- Re-run without `--dry-run` to write the skill.'
-      : '- Restart the agent or reload skills；然后说：`用 Codecraft 审计本项目，只读，不改文件。`',
-  )
-
-  return lines.join('\n')
-}
-
 function header(meta) {
   return [
     `# Codecraft ${title(meta.mode)}`,

package/src/install.mjs

@@ -1,172 +0,0 @@
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url))
-const SKILL_FILES = ['SKILL.md']
-const SKILL_DIRS = ['docs', 'scenarios', 'prompts']
-
-const USER_AGENTS_FILE = path.join(os.homedir(), '.codecraft', 'agents.json')
-const PROJECT_AGENTS_FILE = 'codecraft.agents.json'
-
-const BUILTIN_AGENTS = {
-  generic: { project: '.agents/skills', global: '.agents/skills', markers: ['.agents'] },
-  claude: { project: '.claude/skills', global: '.claude/skills', markers: ['.claude', 'CLAUDE.md'] },
-  cursor: { project: '.cursor/skills', global: '.cursor/skills', markers: ['.cursor'] },
-  trae: { project: '.trae/skills', global: '.trae/skills', markers: ['.trae'] },
-  'trae-cn': { project: '.trae-cn/skills', global: '.trae-cn/skills', markers: ['.trae-cn'] },
-}
-
-export const AGENTS = Object.keys(BUILTIN_AGENTS)
-
-export function loadAgents(root, options = {}) {
-  const registry = new Map(
-    Object.entries(BUILTIN_AGENTS).map(([name, definition]) => [name, { ...definition, source: 'builtin' }]),
-  )
-  mergeAgentFile(registry, options.userFile ?? USER_AGENTS_FILE, 'user')
-  mergeAgentFile(registry, options.projectFile ?? path.join(root, PROJECT_AGENTS_FILE), 'project')
-  return registry
-}
-
-export function listAgents(root, options = {}) {
-  const registry = loadAgents(root, options)
-  return [...registry.entries()].map(([name, definition]) => ({
-    name,
-    project: definition.project,
-    global: definition.global,
-    source: definition.source,
-    detected: {
-      project: isDetected(root, definition.markers),
-      global: isDetected(os.homedir(), definition.markers),
-    },
-  }))
-}
-
-export function parseAgents(value, names = AGENTS) {
-  if (!value || value === 'auto') return []
-  const agents = [...new Set(value.split(',').map((item) => item.trim()).filter(Boolean))]
-  const invalid = agents.filter((agent) => !names.includes(agent))
-  if (invalid.length) {
-    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${names.join(', ')}；用 --list-agents 查看）`)
-  }
-  return agents
-}
-
-export function buildInstallPlan(root, options = {}) {
-  const registry = options.registry ?? loadAgents(root, options)
-  const base = options.global ? os.homedir() : path.resolve(root)
-  const names = [...registry.keys()]
-  const explicit = options.agents ?? []
-  const invalid = explicit.filter((agent) => !registry.has(agent))
-  if (invalid.length) {
-    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${names.join(', ')}；用 --list-agents 查看）`)
-  }
-
-  const agents = explicit.length ? explicit : detectAgents(base, registry, options.global)
-  const destinations = options.dest
-    ? [{ agent: 'custom', dir: path.resolve(base, options.dest) }]
-    : agents.map((agent) => {
-        const definition = registry.get(agent)
-        return { agent, dir: path.join(base, options.global ? definition.global : definition.project) }
-      })
-
-  assertSource()
-
-  const byTarget = new Map()
-  for (const { agent, dir } of destinations) {
-    const target = path.join(dir, 'codecraft')
-    if (!byTarget.has(target)) byTarget.set(target, { target, agents: [] })
-    byTarget.get(target).agents.push(agent)
-  }
-
-  return [...byTarget.values()].map(({ target, agents: targetAgents }) => {
-    const exists = fs.existsSync(target)
-    return {
-      agent: targetAgents.join(','),
-      agents: targetAgents,
-      target,
-      exists,
-      action: exists ? 'exists' : 'create',
-    }
-  })
-}
-
-export function applyInstallPlan(plan, options = {}) {
-  const created = []
-  const skipped = []
-  const replaced = []
-
-  for (const entry of plan) {
-    if (entry.exists && !options.force) {
-      skipped.push(entry.target)
-      continue
-    }
-    if (entry.exists) {
-      fs.rmSync(entry.target, { recursive: true, force: true })
-      replaced.push(entry.target)
-    }
-
-    fs.mkdirSync(entry.target, { recursive: true })
-    for (const file of SKILL_FILES) {
-      fs.copyFileSync(path.join(PACKAGE_ROOT, file), path.join(entry.target, file))
-    }
-    for (const dir of SKILL_DIRS) {
-      fs.cpSync(path.join(PACKAGE_ROOT, dir), path.join(entry.target, dir), { recursive: true })
-    }
-    created.push(entry.target)
-  }
-
-  return { created, skipped, replaced }
-}
-
-function mergeAgentFile(registry, file, source) {
-  if (!fs.existsSync(file)) return
-
-  let parsed
-  try {
-    parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
-  } catch (error) {
-    throw new Error(`invalid agents file ${file}: ${error.message} (fix the JSON syntax or remove the file)`)
-  }
-
-  const agents = parsed?.agents
-  if (!agents || typeof agents !== 'object' || Array.isArray(agents)) {
-    throw new Error(`invalid agents file ${file}: expected { "agents": { "<name>": { project, global, markers } } }`)
-  }
-
-  for (const [name, definition] of Object.entries(agents)) {
-    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
-      throw new Error(`invalid agents file ${file}: agent name "${name}" must be lowercase kebab-case`)
-    }
-    const project = typeof definition?.project === 'string' ? definition.project.trim() : ''
-    if (!project) {
-      throw new Error(`invalid agents file ${file}: agent "${name}" needs a non-empty "project" path`)
-    }
-    const global = typeof definition?.global === 'string' && definition.global.trim() ? definition.global.trim() : project
-    const markers = Array.isArray(definition?.markers)
-      ? definition.markers.filter((marker) => typeof marker === 'string' && marker.trim())
-      : []
-    registry.set(name, { project, global, markers, source })
-  }
-}
-
-function detectAgents(base, registry, global) {
-  const found = [...registry.entries()]
-    .filter(([, definition]) => isDetected(base, definition.markers))
-    .map(([name]) => name)
-  if (global) return found.length ? found : ['generic']
-  return [...new Set([...found, 'generic'])]
-}
-
-function isDetected(base, markers) {
-  return markers.some((marker) => fs.existsSync(path.join(base, marker)))
-}
-
-function assertSource() {
-  for (const file of SKILL_FILES) {
-    if (!fs.existsSync(path.join(PACKAGE_ROOT, file))) {
-      throw new Error(`skill source is incomplete: missing ${file}`)
-    }
-  }
-}