@zmice/zc 0.1.0 → 0.2.0

package/vendor/packages/toolkit/src/content/skills/continuous-learning/body.md

@@ -0,0 +1,367 @@
+# Continuous Learning
+
+## Overview
+
+将开发会话转化为可复用知识。通过 hooks 自动观察工具使用、用户纠正和错误修复模式，提取为原子化的"本能"（instinct），并随时间演化为正式的技能和命令。
+
+**核心模式：观察（Observe）→ 提取（Extract）→ 持久化（Persist）→ 演化（Evolve）**
+
+## When to Use
+
+- 启用自动学习（配置 hooks）
+- 手动触发会话模式提取（`/learn`）
+- 审查和管理已学习的 instincts
+- 将高频 instincts 演化为正式 skills/commands
+- Sprint 回顾时自动触发学习提取（`/retro` 集成）
+
+## 架构
+
+```
+会话活动（工具调用、用户输入、错误修复）
+    │
+    │  Hooks 自动捕获（100% 可靠，确定性执行）
+    │  PostToolUse / UserPromptSubmit / Stop
+    ▼
+┌──────────────────────────────────────────────┐
+│  observations.jsonl（本地文件）                │
+│  记录：工具调用、用户纠正、错误解决路径        │
+│  项目级：projects/<project-hash>/              │
+└──────────────────────────────────────────────┘
+    │
+    │  /learn 触发模式分析（手动或 Stop hook 提醒）
+    ▼
+┌──────────────────────────────────────────────┐
+│  模式检测（Pattern Detection）                │
+│  · 用户纠正 → instinct（0.8+）               │
+│  · 错误→修复 → instinct（0.6-0.7）           │
+│  · 重复工作流 → instinct（0.5-0.6）          │
+│  · 项目约定 → instinct（0.4-0.5）            │
+└──────────────────────────────────────────────┘
+    │
+    │  双层持久化
+    ▼
+┌──────────────────────────────────────────────┐
+│  本地文件层                                    │
+│  instincts/personal/*.yaml（项目或全局）       │
+├──────────────────────────────────────────────┤
+│  Agent Memory 层                               │
+│  高置信度 instinct → learned_skill_experience  │
+│  跨会话智能检索，跨项目共享                     │
+└──────────────────────────────────────────────┘
+    │
+    │  /learn evolve — 聚类演化
+    ▼
+┌──────────────────────────────────────────────┐
+│  演化产物                                      │
+│  · skills/*.md（新技能）                      │
+│  · commands/*.md（新命令）                    │
+│  · 全局 instinct（多项目出现时自动提升）       │
+└──────────────────────────────────────────────┘
+```
+
+## Instinct 模型
+
+一个 instinct 是最小的学习单元 — 一个触发条件对应一个行动：
+
+```yaml
+---
+id: prefer-named-exports
+trigger: "when creating new TypeScript modules"
+action: "Use named exports instead of default exports"
+confidence: 0.8
+domain: code-style
+scope: project
+project_id: "a1b2c3d4e5f6"
+evidence:
+  - "User corrected default export to named export on 2026-04-10"
+  - "Observed 4 instances of named export preference in codebase"
+created: "2026-04-10T14:30:00Z"
+updated: "2026-04-12T09:15:00Z"
+---
+```
+
+### Instinct 属性
+
+| 属性 | 说明 |
+|------|------|
+| **id** | 唯一标识符，kebab-case |
+| **trigger** | 何时触发此本能 |
+| **action** | 具体要做什么 |
+| **confidence** | 置信度（0.3=试探性，0.6=中等，0.9=近乎确定） |
+| **domain** | 领域标签：code-style / testing / git / debugging / workflow / security / performance |
+| **scope** | 作用域：project（默认）/ global |
+| **project_id** | 项目 hash（scope=project 时） |
+| **evidence** | 支持此 instinct 的观察证据列表 |
+
+### 置信度规则
+
+| 来源 | 初始置信度 | 增长规则 |
+|------|-----------|---------|
+| 用户纠正 | 0.8 | 每次重复 +0.05，上限 0.95 |
+| 错误→修复路径 | 0.6 | 每次观察到 +0.05 |
+| 重复工作流 | 0.5 | 3+ 次观察后 +0.1 |
+| 项目约定推断 | 0.4 | 需 5+ 次观察确认 |
+
+**衰减规则：** 如果后续观察与 instinct 矛盾，置信度 -0.1。置信度 <0.3 的 instinct 自动归档。
+
+### 作用域决策
+
+| 模式类型 | 作用域 | 示例 |
+|---------|--------|------|
+| 语言/框架约定 | project | "使用 React Hooks"、"遵循 Django REST 模式" |
+| 文件结构偏好 | project | "测试放在 `__tests__/`"、"组件放在 `src/components/`" |
+| 代码风格 | project | "使用函数式风格"、"偏好 dataclasses" |
+| 安全实践 | global | "验证用户输入"、"清理 SQL" |
+| 通用最佳实践 | global | "先写测试"、"始终处理错误" |
+| 工具工作流 | global | "编辑前先搜索"、"写入前先读取" |
+| Git 实践 | global | "约定式提交"、"小而专注的提交" |
+
+## Hook 观察层
+
+### 工作原理
+
+Hooks 是确定性的 — 只要事件触发，脚本就一定执行，不受模型理解偏差影响。与 prompt 指令不同，hooks 提供 100% 可靠的观察能力。
+
+### 支持的 Hook 事件
+
+**核心事件（Qoder + Qwen Code 均支持）：**
+
+| Hook 事件 | 用途 | 触发频率 |
+|-----------|------|---------|
+| `PostToolUse` | 记录工具调用模式 | 每次工具调用后 |
+| `UserPromptSubmit` | 捕获用户纠正和偏好 | 每次用户输入后 |
+| `Stop` | 会话结束时触发汇总分析 | 每次 Agent 完成响应 |
+
+**扩展事件（仅 Qwen Code）：**
+
+| Hook 事件 | 用途 |
+|-----------|------|
+| `SessionStart` | 会话开始时加载已有 instincts |
+| `SessionEnd` | 会话结束时执行完整分析 |
+| `SubagentStop` | 子代理完成时记录其行为模式 |
+
+### 观察数据格式
+
+每条观察记录为一行 JSON（JSONL 格式）：
+
+```json
+{
+  "timestamp": "2026-04-14T10:30:00Z",
+  "session_id": "sess_abc123",
+  "event": "PostToolUse",
+  "project_id": "a1b2c3d4e5f6",
+  "tool_name": "Edit",
+  "tool_input_summary": "Modified src/auth/login.ts: added input validation",
+  "tool_outcome": "success",
+  "context": "User had previously corrected missing validation"
+}
+```
+
+**存储不存原始数据 — 只存摘要。** 工具输入和输出可能很大，只提取关键信息。
+
+### 文件结构
+
+```
+~/.qoder/homunculus/
+├── observations.jsonl          # 全局观察（无项目时的 fallback）
+├── instincts/
+│   ├── personal/               # 全局自动学习的 instincts
+│   └── inherited/              # 全局导入的 instincts
+├── projects/
+│   ├── a1b2c3d4e5f6/           # 项目 hash（git remote URL）
+│   │   ├── project.json        # 项目元数据
+│   │   ├── observations.jsonl  # 项目级观察
+│   │   └── instincts/
+│   │       └── personal/       # 项目级 instincts
+│   └── f6e5d4c3b2a1/           # 另一个项目
+│       └── ...
+└── projects.json               # 项目注册表：hash → name/path/remote
+```
+
+### 项目检测
+
+系统自动检测当前项目：
+
+1. `git remote get-url origin` — hash 后生成可移植项目 ID（同仓库不同机器相同 ID）
+2. `git rev-parse --show-toplevel` — 备选，使用仓库路径（机器特定）
+3. 全局 fallback — 无法检测项目时，观察存入全局作用域
+
+## Hook 安装
+
+### 快速安装
+
+运行安装脚本自动配置 hooks：
+
+**macOS / Linux:**
+```bash
+# 自动检测平台并安装
+bash skills/continuous-learning/hooks/setup.sh
+
+# 指定平台
+bash skills/continuous-learning/hooks/setup.sh --platform qoder
+bash skills/continuous-learning/hooks/setup.sh --platform qwen-code
+```
+
+**Windows (PowerShell 7+):**
+```powershell
+# 自动检测平台并安装
+.\skills\continuous-learning\hooks\setup.ps1
+
+# 指定平台
+.\skills\continuous-learning\hooks\setup.ps1 -Platform qoder
+.\skills\continuous-learning\hooks\setup.ps1 -Platform qwen-code
+
+# 卸载
+.\skills\continuous-learning\hooks\setup.ps1 -Uninstall
+```
+
+### 手动配置
+
+在 `~/.qoder/settings.json`（Qoder）或对应配置文件中添加：
+
+**macOS / Linux:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "~/.qoder/hooks/continuous-learning/observe.sh"}]}],
+    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "~/.qoder/hooks/continuous-learning/observe.sh"}]}],
+    "PostToolUseFailure": [{"matcher": "*", "hooks": [{"type": "command", "command": "~/.qoder/hooks/continuous-learning/observe.sh"}]}],
+    "Stop": [{"hooks": [{"type": "command", "command": "~/.qoder/hooks/continuous-learning/session-end.sh"}]}]
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "pwsh -NoProfile -File \"~/.qoder/hooks/continuous-learning/observe.ps1\""}]}],
+    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "pwsh -NoProfile -File \"~/.qoder/hooks/continuous-learning/observe.ps1\""}]}],
+    "PostToolUseFailure": [{"matcher": "*", "hooks": [{"type": "command", "command": "pwsh -NoProfile -File \"~/.qoder/hooks/continuous-learning/observe.ps1\""}]}],
+    "Stop": [{"hooks": [{"type": "command", "command": "pwsh -NoProfile -File \"~/.qoder/hooks/continuous-learning/session-end.ps1\""}]}]
+  }
+}
+```
+
+> **依赖要求**: macOS/Linux 版需要 `jq`，Windows 版使用 PowerShell 内置 JSON 处理，无额外依赖。
+
+## 模式检测
+
+### 检测类型
+
+| 模式类型 | 检测方法 | 置信度 |
+|---------|---------|--------|
+| **用户纠正** | UserPromptSubmit 中检测到"不要..."、"改用..."、纠正性指令 | 0.8+ |
+| **错误修复路径** | PostToolUseFailure → 后续成功的工具调用序列 | 0.6-0.7 |
+| **重复工作流** | 同一工具调用序列出现 3+ 次 | 0.5-0.6 |
+| **项目约定** | 代码风格/结构在多文件中保持一致 | 0.4-0.5 |
+| **明确教学** | 用户使用 `/learn save` 手动标记 | 0.9 |
+
+### 检测示例
+
+```
+观察：用户三次在 Agent 使用 default export 后纠正为 named export
+
+提取的 Instinct：
+  id: prefer-named-exports
+  trigger: "when creating TypeScript modules"
+  action: "Use named exports, not default exports"
+  confidence: 0.85
+  domain: code-style
+  scope: project
+  evidence:
+    - "User corrected default→named export (2026-04-10 session)"
+    - "User corrected default→named export (2026-04-11 session)"
+    - "User corrected default→named export (2026-04-12 session)"
+```
+
+## 双层持久化
+
+### 本地文件层
+
+**优势：** 高频写入、低延迟、hooks 直接操作、跨会话持久。
+
+- `observations.jsonl` — 原始观察，append-only
+- `instincts/personal/*.yaml` — 提炼后的 instincts
+
+### Agent Memory 层
+
+**优势：** 智能检索、跨项目共享、会话启动时自动加载。
+
+当 instinct 置信度 >= 0.7 时，自动同步到 Agent Memory：
+
+```
+Memory 存储格式：
+  category: learned_skill_experience
+  title: "Instinct: [trigger 摘要]"
+  content: "[action] — 置信度 [confidence] — 证据: [evidence 摘要]"
+  keywords: "[domain], instinct, [project_name]"
+  scope: project | global（对应 instinct 的 scope）
+```
+
+### 同步策略
+
+- **文件 → Memory：** `/learn` 执行时，将高置信度 instincts 写入 Memory
+- **Memory → 文件：** 会话启动时，从 Memory 恢复 instincts（如果本地文件丢失）
+- **去重：** 使用 instinct ID 作为唯一键
+
+## 演化路径
+
+### Instinct → Skill/Command
+
+当一组相关 instincts 满足以下条件时，可以演化为正式 skill 或 command：
+
+1. **聚类条件：** 3+ 个相关 instincts，同一 domain
+2. **置信度条件：** 平均置信度 >= 0.7
+3. **覆盖条件：** instincts 覆盖一个完整的工作流或决策领域
+
+### 提升规则（Project → Global）
+
+当同一 instinct 在 2+ 个项目中出现且平均置信度 >= 0.8 时，自动提升为全局：
+
+```
+项目 A: prefer-explicit-errors (0.85)
+项目 B: prefer-explicit-errors (0.80)
+                 │
+                 ▼
+全局: prefer-explicit-errors (0.83) — 自动提升
+```
+
+## 命令接口
+
+| 命令 | 说明 |
+|------|------|
+| `/learn` | 分析当前会话，提取并展示 instincts |
+| `/learn status` | 显示所有 instincts（项目级 + 全局）及置信度 |
+| `/learn evolve` | 聚类相关 instincts，建议演化为 skill/command |
+| `/learn save [描述]` | 手动创建一个高置信度 instinct |
+| `/learn promote [id]` | 将项目级 instinct 提升为全局 |
+| `/learn export` | 导出 instincts 为文件 |
+| `/learn import [file]` | 从文件导入 instincts |
+
+## 与其他技能的衔接
+
+- **sprint-retrospective** — Retro 的 Phase 7（Knowledge Capture）自动调用 `/learn` 提取本周期学习
+- **context-engineering** — 会话启动时自动加载相关 instincts 作为上下文
+- **sdd-tdd-workflow** — Phase 5 Reflect 中包含学习提取步骤
+- **verification-before-completion** — 验证过程中发现的模式（常见失败原因）自动记录
+
+## Red Flags
+
+- Hook 脚本执行时间 > 2 秒（影响 Agent 响应速度）
+- Instincts 数量 > 100 个未清理（信息过载）
+- 相互矛盾的 instincts 同时存在（应合并或归档低置信度的）
+- 全局 instincts 包含项目特定内容（作用域错误）
+- 观察数据无限增长未归档（定期清理 observations.jsonl）
+- 跳过 `/learn` 直接手动创建 Memory（绕过置信度评估）
+
+## Verification
+
+设置完成后确认：
+
+- [ ] Hook 脚本已安装且有执行权限
+- [ ] `~/.qoder/homunculus/` 目录结构已创建
+- [ ] PostToolUse hook 能正常记录观察（检查 observations.jsonl）
+- [ ] `/learn` 命令能正确分析并提取 instincts
+- [ ] 高置信度 instincts 已同步到 Agent Memory
+- [ ] 项目检测正常工作（检查 project.json）

package/vendor/packages/toolkit/src/content/skills/continuous-learning/meta.yaml

@@ -0,0 +1,18 @@
+kind: skill
+name: continuous-learning
+title: 持续学习
+description: 基于 Hook 的持续学习系统。它会观察会话行为，提炼带置信度的原子 instincts，并逐步演化为可复用的 skills 或 commands；同时利用本地文件和 Agent Memory 实现跨会话沉淀，可通过 /learn 手动触发提炼。
+tier: experimental
+audience: advanced
+stability: evolving
+suggests:
+  - skill:sprint-retrospective
+  - skill:documentation-and-adrs
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: toolkit-original
+  strategy: curated
+  notes: 本仓库围绕持续学习闭环构建的原生能力。

package/vendor/packages/toolkit/src/content/skills/debugging-and-error-recovery/body.md

@@ -0,0 +1,43 @@
+# 调试与恢复
+
+## 何时使用
+
+- 测试失败、构建报错或运行结果与预期不一致
+- 收到 bug 报告，需要先复现再修复
+- 某个问题开始反复出现，但根因不清楚
+- 你已经开始“凭感觉试错”时
+
+## 输入前提
+
+- 已保留失败证据：报错、日志、复现步骤或测试输出
+- 愿意暂停继续开发，先处理当前异常
+- 接受先定位根因，再动实现
+
+## 执行步骤
+
+1. **Stop the line**：停止继续叠加功能，先保留证据
+2. **Reproduce**：让失败稳定复现
+3. **Localize**：缩小到具体层级、文件或步骤
+4. **Reduce**：提炼最小复现用例
+5. **Fix root cause**：修根因，不修症状
+6. **Guard against recurrence**：补回归测试或监控
+7. **Verify**：重新跑验证，确认已恢复
+
+## 成功标准
+
+- 问题可稳定复现并被最小化描述
+- 修复点对应根因，而不是表面现象
+- 已有测试或验证手段防止同类问题复发
+- 修复后完整验证重新变绿
+
+## 相关原则
+
+- 停线优先于继续堆功能
+- 先复现，再修复
+- 调试过程必须保留证据链
+
+## 与其他技能的衔接
+
+- bug 修复时与 `test-driven-development` 的 Prove-It 模式配合
+- 修复完成后交给 `verification-before-completion`
+- 当问题涉及架构性缺陷时，可转给 `architect`

package/vendor/packages/toolkit/src/content/skills/debugging-and-error-recovery/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: debugging-and-error-recovery
+title: 调试与恢复
+description: 指导系统化根因调试。适用于测试失败、构建中断、行为与预期不符或出现任何异常时，用结构化方法定位并修复根因，而不是凭直觉试错。
+tier: recommended
+audience: default
+stability: stable
+suggests:
+  - skill:test-driven-development
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: debugging-and-error-recovery
+  origin_path: skills/debugging-and-error-recovery/SKILL.md
+  origin_id: skill:debugging-and-error-recovery
+  notes: 沿用上游调试流程，并对齐本仓库验证要求。

package/vendor/packages/toolkit/src/content/skills/deprecation-and-migration/body.md

@@ -0,0 +1,201 @@
+# Deprecation and Migration
+
+## Overview
+
+Code is a liability, not an asset. Every line of code has ongoing maintenance cost — bugs to fix, dependencies to update, security patches to apply, and new engineers to onboard. Deprecation is the discipline of removing code that no longer earns its keep, and migration is the process of moving users safely from the old to the new.
+
+Most engineering organizations are good at building things. Few are good at removing them. This skill addresses that gap.
+
+## When to Use
+
+- Replacing an old system, API, or library with a new one
+- Sunsetting a feature that's no longer needed
+- Consolidating duplicate implementations
+- Removing dead code that nobody owns but everybody depends on
+- Planning the lifecycle of a new system (deprecation planning starts at design time)
+- Deciding whether to maintain a legacy system or invest in migration
+
+## Core Principles
+
+### Code Is a Liability
+
+Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.
+
+### Hyrum's Law Makes Removal Hard
+
+With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.
+
+### Deprecation Planning Starts at Design Time
+
+When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.
+
+## The Deprecation Decision
+
+Before deprecating anything, answer these questions:
+
+```
+1. Does this system still provide unique value?
+   → If yes, maintain it. If no, proceed.
+
+2. How many users/consumers depend on it?
+   → Quantify the migration scope.
+
+3. Does a replacement exist?
+   → If no, build the replacement first. Don't deprecate without an alternative.
+
+4. What's the migration cost for each consumer?
+   → If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
+
+5. What's the ongoing maintenance cost of NOT deprecating?
+   → Security risk, engineer time, opportunity cost of complexity.
+```
+
+## Compulsory vs Advisory Deprecation
+
+| Type | When to Use | Mechanism |
+|------|-------------|-----------|
+| **Advisory** | Migration is optional, old system is stable | Warnings, documentation, nudges. Users migrate on their own timeline. |
+| **Compulsory** | Old system has security issues, blocks progress, or maintenance cost is unsustainable | Hard deadline. Old system will be removed by date X. Provide migration tooling. |
+
+**Default to advisory.** Use compulsory only when the maintenance cost or risk justifies forcing migration. Compulsory deprecation requires providing migration tooling, documentation, and support — you can't just announce a deadline.
+
+## The Migration Process
+
+### Step 1: Build the Replacement
+
+Don't deprecate without a working alternative. The replacement must:
+
+- Cover all critical use cases of the old system
+- Have documentation and migration guides
+- Be proven in production (not just "theoretically better")
+
+### Step 2: Announce and Document
+
+```markdown
+## Deprecation Notice: OldService
+
+**Status:** Deprecated as of 2025-03-01
+**Replacement:** NewService (see migration guide below)
+**Removal date:** Advisory — no hard deadline yet
+**Reason:** OldService requires manual scaling and lacks observability.
+            NewService handles both automatically.
+
+### Migration Guide
+1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
+2. Update configuration (see examples below)
+3. Run the migration verification script: `npx migrate-check`
+```
+
+### Step 3: Migrate Incrementally
+
+Migrate consumers one at a time, not all at once. For each consumer:
+
+```
+1. Identify all touchpoints with the deprecated system
+2. Update to use the replacement
+3. Verify behavior matches (tests, integration checks)
+4. Remove references to the old system
+5. Confirm no regressions
+```
+
+**The Churn Rule:** If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.
+
+### Step 4: Remove the Old System
+
+Only after all consumers have migrated:
+
+```
+1. Verify zero active usage (metrics, logs, dependency analysis)
+2. Remove the code
+3. Remove associated tests, documentation, and configuration
+4. Remove the deprecation notices
+5. Celebrate — removing code is an achievement
+```
+
+## Migration Patterns
+
+### Strangler Pattern
+
+Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.
+
+```
+Phase 1: New system handles 0%, old handles 100%
+Phase 2: New system handles 10% (canary)
+Phase 3: New system handles 50%
+Phase 4: New system handles 100%, old system idle
+Phase 5: Remove old system
+```
+
+### Adapter Pattern
+
+Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.
+
+```typescript
+// Adapter: old interface, new implementation
+class LegacyTaskService implements OldTaskAPI {
+  constructor(private newService: NewTaskService) {}
+
+  // Old method signature, delegates to new implementation
+  getTask(id: number): OldTask {
+    const task = this.newService.findById(String(id));
+    return this.toOldFormat(task);
+  }
+}
+```
+
+### Feature Flag Migration
+
+Use feature flags to switch consumers from old to new system one at a time:
+
+```typescript
+function getTaskService(userId: string): TaskService {
+  if (featureFlags.isEnabled('new-task-service', { userId })) {
+    return new NewTaskService();
+  }
+  return new LegacyTaskService();
+}
+```
+
+## Zombie Code
+
+Zombie code is code that nobody owns but everybody depends on. It's not actively maintained, has no clear owner, and accumulates security vulnerabilities and compatibility issues. Signs:
+
+- No commits in 6+ months but active consumers exist
+- No assigned maintainer or team
+- Failing tests that nobody fixes
+- Dependencies with known vulnerabilities that nobody updates
+- Documentation that references systems that no longer exist
+
+**Response:** Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan. Zombie code cannot stay in limbo — it either gets investment or removal.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It still works, why remove it?" | Working code that nobody maintains accumulates security debt and complexity. Maintenance cost grows silently. |
+| "Someone might need it later" | If it's needed later, it can be rebuilt. Keeping unused code "just in case" costs more than rebuilding. |
+| "The migration is too expensive" | Compare migration cost to ongoing maintenance cost over 2-3 years. Migration is usually cheaper long-term. |
+| "We'll deprecate it after we finish the new system" | Deprecation planning starts at design time. By the time the new system is done, you'll have new priorities. Plan now. |
+| "Users will migrate on their own" | They won't. Provide tooling, documentation, and incentives — or do the migration yourself (the Churn Rule). |
+| "We can maintain both systems indefinitely" | Two systems doing the same thing is double the maintenance, testing, documentation, and onboarding cost. |
+
+## Red Flags
+
+- Deprecated systems with no replacement available
+- Deprecation announcements with no migration tooling or documentation
+- "Soft" deprecation that's been advisory for years with no progress
+- Zombie code with no owner and active consumers
+- New features added to a deprecated system (invest in the replacement instead)
+- Deprecation without measuring current usage
+- Removing code without verifying zero active consumers
+
+## Verification
+
+After completing a deprecation:
+
+- [ ] Replacement is production-proven and covers all critical use cases
+- [ ] Migration guide exists with concrete steps and examples
+- [ ] All active consumers have been migrated (verified by metrics/logs)
+- [ ] Old code, tests, documentation, and configuration are fully removed
+- [ ] No references to the deprecated system remain in the codebase
+- [ ] Deprecation notices are removed (they served their purpose)

package/vendor/packages/toolkit/src/content/skills/deprecation-and-migration/meta.yaml

@@ -0,0 +1,21 @@
+kind: skill
+name: deprecation-and-migration
+title: 迁移与废弃
+description: 管理废弃与迁移。适用于移除旧系统、旧 API 或旧功能，也适用于在不同实现之间平滑迁移用户并决定是否继续维护旧路径。
+tier: recommended
+audience: advanced
+stability: stable
+suggests:
+  - skill:documentation-and-adrs
+  - skill:verification-before-completion
+platforms:
+  - qwen
+  - codex
+  - qoder
+source:
+  upstream: agent-skills
+  strategy: adapted
+  origin_name: deprecation-and-migration
+  origin_path: skills/deprecation-and-migration/SKILL.md
+  origin_id: skill:deprecation-and-migration
+  notes: 基于上游迁移废弃实践整理。