@bovinphang/craft-common 0.0.0-stage → 1.0.0

package/localized/zh-CN/skills/eval_queries.json

@@ -0,0 +1,160 @@
+{
+  "cc-debug-methodology": {
+    "should_trigger": [
+      "Vite 构建报错 Module not found，帮我排查",
+      "页面白屏了，控制台有 TypeError",
+      "这个组件渲染结果和预期不一致，帮我 debug",
+      "接口返回 500 但前端没展示错误信息",
+      "打包后样式丢失，开发环境正常",
+      "React 组件 hydration mismatch 怎么定位",
+      "HMR 更新后页面状态丢失",
+      "排查生产环境偶发性 JS 异常"
+    ],
+    "should_not_trigger": [
+      "给这个模块写单元测试",
+      "设计一个新的 React 组件",
+      "优化首屏加载性能",
+      "做前端安全审查",
+      "升级 TypeScript 到最新版本",
+      "重构这个 hooks 的逻辑",
+      "写一个 Playwright E2E 测试",
+      "给这个 API 设计类型定义"
+    ]
+  },
+  "cc-doc-sync-core": {
+    "should_trigger": [
+      "同步 README 中的 skill 和 agent 数量",
+      "新增命令后更新多语言文档",
+      "根据 package.json 生成命令清单",
+      "同步 runtime 文档",
+      "更新 marketplace 描述里的能力数量",
+      "检查 README 和 skills metadata 是否一致",
+      "把报告输出表同步到文档",
+      "更新项目结构文档中的 commands 列表"
+    ],
+    "should_not_trigger": [
+      "给组件写 Storybook stories",
+      "修复 TypeScript 构建失败",
+      "写登录 E2E 测试",
+      "审查 XSS 风险",
+      "规划 React 组件边界",
+      "清理未使用导出",
+      "实现 PWA manifest",
+      "优化虚拟列表滚动"
+    ]
+  },
+  "cc-drawio-studio": {
+    "should_trigger": [
+      "生成一个可编辑的 draw.io 架构图并导出 PNG",
+      "把这个微服务系统画成 .drawio 文件",
+      "用 diagrams.net 做 ER 图，要求后续能编辑",
+      "查一下 AWS Lambda 在 draw.io 里的官方 shape style",
+      "给这个 TypeScript 项目生成模块依赖图并自动布局",
+      "生成 UML 类图并用 draw.io CLI 导出 SVG",
+      "draw.io 自动布局一个超过 20 个节点的服务拓扑",
+      "用 Graphviz 布局后生成 diagrams.net 编辑链接",
+      "制作可编辑序列图并检查 .drawio 是否有断边",
+      "用官方云形状创建可编辑 draw.io 架构图"
+    ],
+    "should_not_trigger": [
+      "生成一张产品宣传海报图片",
+      "编辑这张照片并替换背景",
+      "实现 Three.js 交互式 3D 拓扑图",
+      "给 SVG logo 加路径描边动画",
+      "只写 Mermaid 到 README 中",
+      "按 Figma 设计稿实现页面",
+      "检查 dashboard 的按钮 hover 状态",
+      "用 Playwright 截图做视觉回归",
+      "优化 Canvas 粒子动画性能",
+      "生成漫画头像和品牌板"
+    ]
+  },
+  "cc-refactoring-core": {
+    "should_trigger": [
+      "保持行为不变，重构这个前端模块。",
+      "这个函数只做结构调整，每一步都验证，不改输出和副作用。",
+      "给这个 React 功能做保持行为重构，并设置差异预算。",
+      "这个 Vue composable 只优化结构，不增加新功能。",
+      "按 SAFE/CAUTION/DANGER 给这次重构分级并小步执行。",
+      "先建立绿色基线，再重构这个 TypeScript service，最后回到绿色。",
+      "为这次保持行为重构设置回滚边界。",
+      "按一次一个重构手法执行并给出最终证明。"
+    ],
+    "should_not_trigger": [
+      "删除没用的 React 组件和 npm 依赖。",
+      "修复这个会发两次请求的 bug。",
+      "把 Redux 迁移到 Zustand。",
+      "审查这个 PR 是否可以合并。",
+      "排查为什么这个页面白屏。",
+      "用 TDD 新增支付功能。",
+      "把 Vite 升级并处理 breaking changes。",
+      "按 Figma 新增一个响应式页面。"
+    ]
+  },
+  "cc-source-driven-development": {
+    "should_trigger": [
+      "这个 Next.js 新版本 API 先查官方文档再决定",
+      "帮我确认 Vite 配置项当前版本是否还推荐",
+      "这个浏览器 API 兼容性要以规范和 MDN 为准",
+      "为前端库迁移做事实源驱动决策",
+      "React Router 版本差异需要查文档",
+      "这个包的 ESM/CJS 行为不要凭记忆判断",
+      "按项目源码和官方 docs 设计公共接口",
+      "验证 Nuxt useFetch 最新推荐用法"
+    ],
+    "should_not_trigger": [
+      "给表单写 Zod 校验",
+      "优化大列表虚拟滚动",
+      "运行 npm test 并修复失败",
+      "检查按钮 aria-label",
+      "写 Playwright 登录流程",
+      "清理未使用依赖",
+      "设计 UI 视觉方向",
+      "审查 token 存储安全"
+    ]
+  },
+  "cc-tdd-methodology": {
+    "should_trigger": [
+      "用 TDD 实现这个 hook",
+      "先写失败测试再修这个 bug",
+      "为新组件走红绿重构流程",
+      "补一个回归测试再改逻辑",
+      "用测试驱动开发这个前端功能",
+      "这个工具函数先写单测再实现",
+      "修复表单校验 bug 前先复现测试",
+      "用测试驱动方式重构状态逻辑"
+    ],
+    "should_not_trigger": [
+      "只运行现有测试并修复失败",
+      "制定测试分层策略",
+      "写完整 Playwright E2E 流程",
+      "同步文档能力表",
+      "清理未使用依赖",
+      "做 XSS 安全审查",
+      "设计 Vue 项目结构",
+      "配置 PWA 离线缓存"
+    ]
+  },
+  "cc-technical-diagrams": {
+    "should_trigger": [
+      "绘制后台任务生命周期并保留可编辑源",
+      "把架构 JSON 渲染为自包含 HTML",
+      "绘制 API 和数据库事务序列图",
+      "展示 Agent 记忆检索流程并标注箭头语义",
+      "检查技术图 PNG 中的文本裁切",
+      "渲染含决策和回退边的工作流",
+      "创建服务依赖的本地交互预览",
+      "导出 SVG 时保留所有数据流标签"
+    ],
+    "should_not_trigger": [
+      "生成产品摄影图",
+      "编辑头像背景",
+      "构建 React 组件",
+      "优化数据库查询",
+      "修复 Rust 编译错误",
+      "审查权限逻辑",
+      "编写 CLI 单元测试",
+      "润色营销文案"
+    ]
+  }
+}

package/localized/zh-CN/skills/metadata.json

@@ -0,0 +1,223 @@
+[
+  {
+    "id": "cc-debug-methodology",
+    "name": "证据驱动诊断",
+    "category": "review-quality",
+    "tags": [
+      "debug",
+      "evidence",
+      "root-cause"
+    ],
+    "summary": "证据驱动诊断",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "review-quality",
+      "debug",
+      "evidence",
+      "root-cause"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  },
+  {
+    "id": "cc-doc-sync-core",
+    "name": "文档事实同步",
+    "category": "maintenance-docs",
+    "tags": [
+      "documentation",
+      "source-of-truth",
+      "i18n"
+    ],
+    "summary": "文档事实同步",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "maintenance-docs",
+      "documentation",
+      "source-of-truth",
+      "i18n"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  },
+  {
+    "id": "cc-drawio-studio",
+    "name": "可编辑技术图",
+    "category": "implementation-capability",
+    "tags": [
+      "drawio",
+      "uml",
+      "erd",
+      "architecture"
+    ],
+    "summary": "可编辑技术图",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "implementation-capability",
+      "drawio",
+      "uml",
+      "erd",
+      "architecture"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  },
+  {
+    "id": "cc-refactoring-core",
+    "name": "保持行为的重构",
+    "category": "project-evolution",
+    "tags": [
+      "refactoring",
+      "behavior-preservation",
+      "baseline"
+    ],
+    "summary": "保持行为的重构",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "project-evolution",
+      "refactoring",
+      "behavior-preservation",
+      "baseline"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  },
+  {
+    "id": "cc-source-driven-development",
+    "name": "以事实来源驱动开发",
+    "category": "project-standard",
+    "tags": [
+      "official-docs",
+      "versioning",
+      "local-knowledge"
+    ],
+    "summary": "以事实来源驱动开发",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "project-standard",
+      "official-docs",
+      "versioning",
+      "local-knowledge"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  },
+  {
+    "id": "cc-tdd-methodology",
+    "name": "测试驱动开发",
+    "category": "testing",
+    "tags": [
+      "tdd",
+      "regression",
+      "red-green-refactor"
+    ],
+    "summary": "测试驱动开发",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "testing",
+      "tdd",
+      "regression",
+      "red-green-refactor"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  },
+  {
+    "id": "cc-technical-diagrams",
+    "name": "结构化技术图表",
+    "category": "implementation-capability",
+    "tags": [
+      "architecture",
+      "sequence",
+      "workflow",
+      "png-qa"
+    ],
+    "summary": "结构化技术图表",
+    "version": "1.0.0",
+    "license": "MIT",
+    "homepage": "https://github.com/bovinphang/craft-common",
+    "repository": "https://github.com/bovinphang/craft-common",
+    "keywords": [
+      "implementation-capability",
+      "architecture",
+      "sequence",
+      "workflow",
+      "png-qa"
+    ],
+    "platforms": [
+      "skills-cli",
+      "skillreg",
+      "claude-code",
+      "codex",
+      "cursor",
+      "opencode",
+      "openclaw",
+      "generic-skill-runtime"
+    ]
+  }
+]

package/localized/zh-CN/skills/relations.json

@@ -0,0 +1,53 @@
+{
+  "cc-debug-methodology": {
+    "capabilityTags": [
+      "debug",
+      "evidence",
+      "root-cause"
+    ]
+  },
+  "cc-doc-sync-core": {
+    "capabilityTags": [
+      "documentation",
+      "source-of-truth",
+      "i18n"
+    ]
+  },
+  "cc-drawio-studio": {
+    "capabilityTags": [
+      "drawio",
+      "uml",
+      "erd",
+      "architecture"
+    ]
+  },
+  "cc-refactoring-core": {
+    "capabilityTags": [
+      "refactoring",
+      "behavior-preservation",
+      "baseline"
+    ]
+  },
+  "cc-source-driven-development": {
+    "capabilityTags": [
+      "official-docs",
+      "versioning",
+      "local-knowledge"
+    ]
+  },
+  "cc-tdd-methodology": {
+    "capabilityTags": [
+      "tdd",
+      "regression",
+      "red-green-refactor"
+    ]
+  },
+  "cc-technical-diagrams": {
+    "capabilityTags": [
+      "architecture",
+      "sequence",
+      "workflow",
+      "png-qa"
+    ]
+  }
+}

package/methods/debug.md

@@ -0,0 +1,13 @@
+# Evidence-driven diagnosis
+
+Use five steps to establish a root cause before applying a fix.
+
+1. **Classify:** describe the observable failure, impact, version, environment and minimal reproduction. Identify the relevant subsystem using project evidence. Cross-layer failures start from the visible symptom and trace across boundaries.
+2. **Collect:** reproduce with the smallest failing command or operation; collect necessary logs, traces, state, configuration and recent changes. Redact credentials and sensitive payloads. A domain adapter supplies stack-specific probes.
+3. **Hypothesize:** keep at most three hypotheses ranked by evidence. Each states "X causes Y; Z can confirm or falsify it." Do not substitute a symptom or speculative repair for a cause.
+4. **Verify:** vary one factor at a time, start with the strongest hypothesis and record confirmed/falsified/pending. If all are falsified, collect more evidence. Three consecutive failed verifications of the same hypothesis require reporting the block rather than repeating it.
+5. **Fix and validate:** apply the smallest confirmed repair, preserve a regression reproduction and run affected then broader existing checks. Report baseline failures separately; do not disable tests or weaken validation to claim success.
+
+For dependency or environment failures, compare exact toolchain/dependency versions, lockfile and CI/local differences before upgrading packages. Keep migrations separate from ordinary defect repairs. Avoid adding retries, changing timeouts or suppressing errors without proving the cause and the intended semantics.
+
+Deliver `reports/debug-YYYY-MM-DD-HHmmss.md` with symptom and reproduction, evidence, hypothesis/result table, root cause, modified files/behavior, executed verification, residual risk and the next useful action. Do not claim a fix or a green suite without observed results.

package/methods/doc-sync.md

@@ -0,0 +1,12 @@
+# Documentation synchronization
+
+Synchronize public documentation from implementation facts, not from the desired design.
+
+1. Identify the repository stack, document entry points and requested scope. Include root READMEs, nested package/application/runtime READMEs and deployment guides; exclude dependencies, generated outputs and third-party directories.
+2. Collect authoritative project sources: manifests/lockfiles, configuration, env examples, commands, schemas, public APIs, tests, CI, build and deployment files. Use sources for the actual stack rather than require a particular language's manifest.
+3. Compare commands, environment variable names, paths, versions, API behavior, capabilities, setup and deployment instructions. Keep only stable public facts; do not present proposals or experimental designs as supported behavior.
+4. Check every existing language entry. Public identifiers, commands, version constraints, support matrices, report paths and examples must agree. Translate prose according to the existing convention; explicitly report translations requiring human review.
+5. Update affected README/docs/ADR/changelog and user-facing metadata together. An ADR records context, decision, alternatives, impact, verification and rollback clues; it is not a full review report.
+6. Run the project's existing consistency checks, relevant type/tests/build or packaging checks and legacy-reference search. Record each checked document, source of truth, updated language, unchanged entry and unresolved uncertainty.
+
+Do not invent commands or environment variables, overwrite private documents outside the requested scope, or replace a README with internal implementation details. A successful prose edit alone does not prove factual consistency.

package/methods/refactoring.md

@@ -0,0 +1,16 @@
+# Behavior-preserving refactoring
+
+Refactoring changes internal organization while preserving the observable contract. Use GREEN → REFACTOR → GREEN; do not manufacture a failing behavioral requirement for a structural change.
+
+1. Classify whether this is structural work, a new behavior, a defect fix, or a dependency migration. Keep behavior changes in a separate workflow.
+2. Read affected implementation, callers, exports, registration, persistence and tests. Define observable results, errors, side effects and ordering, state transitions, public names and protocols before editing.
+3. Establish the green baseline or record existing failures. If a relevant behavior lacks coverage, add characterization tests that describe current behavior; these may start green.
+4. Diagnose structural evidence and check false positives. Line count and complexity metrics alone do not justify a rewrite. Prefer the smallest safe, reversible transformation.
+5. Plan prerequisite steps. Each records target, structural intent, technique, risk, expected files/functions, expected public API/behavior changes (zero for pure refactoring), verification and rollback boundary.
+6. Change one primary structural concern, then run the nearest meaningful check and inspect the diff. Stop and reassess if the actual scope exceeds the planned diff budget.
+7. A new regression invalidates the current step: restore only that step, verify the previous baseline and shrink or reorder the transformation before retrying. Do not revert unrelated user edits or spread repairs across unrelated modules.
+8. Broaden verification as the changed contract requires: local/static checks, unit/integration, full lint/types/tests, build and relevant specialty checks. Use existing project tools rather than impose a framework.
+
+Risk is contextual: SAFE for local/private changes with strong evidence; CAUTION for cross-module/shared-state/lifecycle changes; DANGER for public APIs, schemas, persistence, authentication, permission, protocols or architecture-wide changes. A technique name alone never makes a change safe.
+
+Deliver a proof verdict: PASS when the relevant behavior is adequately covered and checks pass; PARTIAL when checks pass but coverage has important gaps; NOT PROVEN when evidence or environment prevents a credible preservation claim. Include executed commands, rollback decisions and remaining risks.

package/methods/source-driven-development.md

@@ -0,0 +1,19 @@
+# Source-driven development
+
+Use project facts, authoritative sources and version-specific evidence to make engineering decisions.
+
+1. Establish the question, affected version and local contract. Read the project's manifests, configuration, implementation, callers and tests before proposing changes. Stable local transformations can rely on those facts; changing runtime, package or public API assumptions need authoritative verification.
+2. Collect official documentation, source, type definitions, release notes, specifications and migration guides for the actual version. Third-party discussions provide clues, not the final basis. Record source paths/URLs, versions, dates and relevant conclusions.
+3. Compare recommendations with the running project. State compatibility, maintenance cost, migration scope and rollback. Isolate unstable external assumptions behind a small boundary; do not overturn stable conventions just to use a newer pattern.
+4. Prove key assumptions using the project's existing checks or a minimal reproduction. Select checks for the actual stack. Record commands and observed outcomes; if verification is unavailable, report the uncertainty rather than claim support.
+5. Update a lightweight ADR, migration record or factual documentation when public interfaces, dependencies or team conventions change. Do not copy long external documents.
+
+## Local knowledge requests
+
+When a user restricts evidence to a local repository or knowledge directory, search that source first and do not fill gaps with online guesses. Use the explicit path, otherwise check whether `knowledge/` exists. If absent, identify the missing source instead of inventing one.
+
+Read `data_structure.md` navigation where available, choose relevant branches, and search progressively instead of loading the entire corpus. Default to at most five keyword refinement rounds. Record file paths, sections/pages/sheets, version range and evidence gaps. For PDF or spreadsheets choose an appropriate extraction tool before reading large content. Use external sources only when the user's scope permits them.
+
+## Evidence priority and delivery
+
+Project implementation/configuration/tests establish the local contract; official versioned documentation/source establishes external behavior; specifications establish platform constraints; issues and articles only supplement these. Deliver the decision, sources, implementation impact, verification results and remaining uncertainty. "Checked the docs" without traceable evidence is insufficient.

package/methods/tdd.md

@@ -0,0 +1,13 @@
+# Test-driven development
+
+For new behavior and behavior-changing defect fixes use RED → GREEN → REFACTOR. The test describes an observable contract, not private implementation structure.
+
+1. Identify one behavior: inputs, output/error, state transition or externally observable side effect. Choose the closest meaningful test level using existing project tooling.
+2. Write the smallest test that distinguishes the missing or wrong behavior. Run it first and observe failure for the expected behavior, not a syntax, import or environment problem. For a defect, the test must fail against the original defect.
+3. Implement only enough to pass that test. Do not refactor during the red phase or add unrelated features.
+4. Run the test and relevant surrounding tests, then improve naming and structure while preserving green. New requirements enter the next cycle.
+5. Report the observed red/green commands, covered behavior and untested boundaries. Do not infer success from a diff or unexecuted tests.
+
+Pure structural refactoring has a different contract: establish current behavior through existing or characterization coverage and keep GREEN → REFACTOR → GREEN. Do not invent a failure merely to satisfy a ritual.
+
+Test logic close to the risk; use integration tests for real boundaries and end-to-end tests for journeys that need them. Do not make E2E the default or assert fragile private state. Do not introduce a new testing framework merely for TDD. If infrastructure is absent, explain the minimum test setup and obtain a decision before introducing it; use the actual stack rather than require frontend tools.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@bovinphang/craft-common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Craft AI Coding 的公共技能、研发方法与共享安装协议",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bovinphang/craft-common"
+  },
+  "homepage": "https://github.com/bovinphang/craft-common",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "packageManager": "pnpm@12.4.1",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "docs/consuming-common.md",
+    "dist",
+    "skills",
+    "localized",
+    "methods",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync:methods": "tsx scripts/sync-methods.ts",
+    "pack:skills": "tsx scripts/pack-skills.ts",
+    "lint": "eslint src scripts tests eslint.config.mjs --max-warnings=0",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx scripts/run-tests.ts",
+    "build": "pnpm typecheck && tsx scripts/build.ts && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "@types/node": "^22.19.15",
+    "esbuild": "^0.28.0",
+    "eslint": "9.39.4",
+    "globals": "17.12.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "8.70.1"
+  }
+}

package/skills/cc-debug-methodology/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-debug-methodology
+description: Use when diagnosing unexplained engineering failures, build errors, service exceptions, inconsistent data, or cross-layer faults before selecting a repair.
+---
+
+# Evidence-driven diagnosis
+
+Read and follow the [shared method](references/method.md). Select project-specific tools and domain checks from the actual repository; this workflow does not require a frontend stack.

package/skills/cc-debug-methodology/references/method.md

@@ -0,0 +1,13 @@
+# Evidence-driven diagnosis
+
+Use five steps to establish a root cause before applying a fix.
+
+1. **Classify:** describe the observable failure, impact, version, environment and minimal reproduction. Identify the relevant subsystem using project evidence. Cross-layer failures start from the visible symptom and trace across boundaries.
+2. **Collect:** reproduce with the smallest failing command or operation; collect necessary logs, traces, state, configuration and recent changes. Redact credentials and sensitive payloads. A domain adapter supplies stack-specific probes.
+3. **Hypothesize:** keep at most three hypotheses ranked by evidence. Each states "X causes Y; Z can confirm or falsify it." Do not substitute a symptom or speculative repair for a cause.
+4. **Verify:** vary one factor at a time, start with the strongest hypothesis and record confirmed/falsified/pending. If all are falsified, collect more evidence. Three consecutive failed verifications of the same hypothesis require reporting the block rather than repeating it.
+5. **Fix and validate:** apply the smallest confirmed repair, preserve a regression reproduction and run affected then broader existing checks. Report baseline failures separately; do not disable tests or weaken validation to claim success.
+
+For dependency or environment failures, compare exact toolchain/dependency versions, lockfile and CI/local differences before upgrading packages. Keep migrations separate from ordinary defect repairs. Avoid adding retries, changing timeouts or suppressing errors without proving the cause and the intended semantics.
+
+Deliver `reports/debug-YYYY-MM-DD-HHmmss.md` with symptom and reproduction, evidence, hypothesis/result table, root cause, modified files/behavior, executed verification, residual risk and the next useful action. Do not claim a fix or a green suite without observed results.

package/skills/cc-doc-sync-core/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: cc-doc-sync-core
+description: Use when project documentation, multilingual READMEs, setup instructions, CLI usage, or public capability descriptions drift from implementation, configuration, tests, or release metadata.
+---
+
+# Documentation synchronization
+
+Read and follow the [shared method](references/method.md). Select project-specific tools and domain checks from the actual repository; this workflow does not require a frontend stack.

package/skills/cc-doc-sync-core/references/method.md

@@ -0,0 +1,12 @@
+# Documentation synchronization
+
+Synchronize public documentation from implementation facts, not from the desired design.
+
+1. Identify the repository stack, document entry points and requested scope. Include root READMEs, nested package/application/runtime READMEs and deployment guides; exclude dependencies, generated outputs and third-party directories.
+2. Collect authoritative project sources: manifests/lockfiles, configuration, env examples, commands, schemas, public APIs, tests, CI, build and deployment files. Use sources for the actual stack rather than require a particular language's manifest.
+3. Compare commands, environment variable names, paths, versions, API behavior, capabilities, setup and deployment instructions. Keep only stable public facts; do not present proposals or experimental designs as supported behavior.
+4. Check every existing language entry. Public identifiers, commands, version constraints, support matrices, report paths and examples must agree. Translate prose according to the existing convention; explicitly report translations requiring human review.
+5. Update affected README/docs/ADR/changelog and user-facing metadata together. An ADR records context, decision, alternatives, impact, verification and rollback clues; it is not a full review report.
+6. Run the project's existing consistency checks, relevant type/tests/build or packaging checks and legacy-reference search. Record each checked document, source of truth, updated language, unchanged entry and unresolved uncertainty.
+
+Do not invent commands or environment variables, overwrite private documents outside the requested scope, or replace a README with internal implementation details. A successful prose edit alone does not prove factual consistency.