@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -15,10 +15,10 @@
             "source": {
                 "source": "npm",
                 "package": "@bovinphang/frontend-craft",
-                "version": "2.8.0"
+                "version": "3.0.0"
             },
-            "description": "Enterprise frontend team Claude Code plugin — 13 agents, 45 skills, 8 commands, shared rule templates, and production-ready hooks for code review, TypeScript review, type-safety modeling, state management, Tailwind design systems, responsive layout, dependency upgrades, security review, testing strategy, E2E, component testing, route protection, API integration, backend requirements handoff, interaction motion, performance optimization, scaffolding, design-to-code (Figma/Sketch/MasterGo/Pixso/墨刀/摹客), UI design and polish, image generation, editable draw.io drawio studio, web video presentations, Vite standards, legacy-to-modern migration, React/Vue/Next.js/Nuxt/monorepo standards, PWA, Web Workers, Canvas/Three.js, SVG animation, CI/CD, architecture planning, project absorption, and UI debugging with multi-design-tool MCP integration. All reports auto-saved as Markdown files to reports/ directory.",
-            "version": "2.8.0",
+            "description": "Enterprise frontend team Claude Code plugin — 14 agents, 74 skills, 11 commands, shared rule templates, and production-ready hooks for code review, TypeScript review, type-safety modeling, state management, Tailwind design systems, responsive layout, dependency upgrades, security review, testing strategy, E2E, component testing, route protection, API integration, backend requirements handoff, interaction motion, performance optimization, scaffolding, design-to-code (Figma/Sketch/MasterGo/Pixso/墨刀/摹客), UI design and polish, image generation, editable draw.io drawio studio, web video presentations, Vite standards, legacy-to-modern migration, React/Vue/Next.js/Nuxt/monorepo standards, PWA, Web Workers, Canvas/Three.js, SVG animation, CI/CD, architecture planning, project absorption, and UI debugging with multi-design-tool MCP integration. All reports auto-saved as Markdown files to reports/ directory.",
+            "version": "3.0.0",
             "author": {
                 "name": "Bovin Phang",
                 "email": "pengbaowen@msn.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "frontend-craft",
-    "version": "2.8.0",
+    "version": "3.0.0",
     "description": "Shared Claude Code plugin for frontend teams, including frontend skills, subagents, hooks, and MCP integration for Figma/Sketch/MasterGo/Pixso/墨刀/摹客. All reports auto-saved as Markdown files.",
     "author": {
         "name": "Bovin Phang",

package/CHANGELOG.md

@@ -9,6 +9,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Project-facing release notes are maintained in English from 2.0.0 onward. Historical entries may preserve their original language.
 
+## [3.0.0] - 2026-11-09
+
+### Shared capabilities
+
+This section describes unreleased 3.0.0; promoting common does not change the product version or imply publication. Add layered engineering guidance, an isolated real React state example and source/distribution checks. Publish and verify common 2.0.0 first.
+
+- Deliver the exact craft-common 2.0.0 dependency: 21 common and 53 frontend entries, 74 in total. Independent C/C++ foundations and Tauri/Electron specialties are shared across products.
+- Add shared ownership, exact version/language conflict checks, transactional recovery and read-only migration checks.
+- See the [migration guide](docs/common-migration.md) for legacy entries and independent uninstall behavior.
+
+
+### Breaking changes and migration
+
+- Top-level `fec update` / `upgrade` now upgrades the npm/pnpm global CLI from its original registry, then refreshes managed resources with the new CLI in the current project and user-global scope. It does not scan other projects or manage Marketplace installations.
+- Top-level `fec uninstall` / `remove` now removes only the CLI. `--purge` cleans discovered managed resources first while preserving user modifications; cleanup errors keep the CLI installed. Interactive removal requires confirmation; non-interactive removal requires `--yes`.
+- Move resource commands to `fec runtime install/update/uninstall [runtime]`, with `runtime upgrade/remove` aliases and existing resource options. `setup` remains available; top-level `install` is a deprecated compatibility alias. Old runtime arguments and resource options on top-level update/uninstall are rejected before changes with migration guidance.
+- Replace `fec update codex --global` with `fec runtime update codex --global`, and `fec uninstall --local` with `fec runtime uninstall --local`. For temporary execution, use `npx @bovinphang/frontend-craft@latest runtime update`; `runtime update` uses the running package contents without fetching a new CLI package.
+
+### Added
+
+- Verified npm/pnpm global installation ownership, original package-manager reuse, new-version entry-point continuation, phase-specific failure reporting, and read-only `--dry-run`. An already-current CLI still refreshes resources; a CLI upgrade failure stops resource updates. Partial resource failures do not roll back the upgraded CLI and can be retried with `fec runtime update`.
+- Temporary npx update checks registry `latest` and never creates a global installation; if the running version differs, it prints the latest-package runtime command. npx self-uninstall is unsupported. Source links, project dependencies, unknown sources and pnpm groups shared with other packages are refused for automatic self-management before changes.
+
+The entries below describe historical 2.x behavior. For current resource commands use the `runtime` group described above.
+
+## [2.9.0] - 2026-09-26
+
+### Added
+
+- **Technical diagram tools:** added an optional local Mermaid adapter and reproducible sequence, workflow, and architecture fixtures.
+- **Documentation:** added a bilingual review scope and technical diagram delivery guide.
+- **Behavior-preserving refactoring subsystem:** added `fec-refactoring-expert`, `/fec-smell`, `/fec-refactor-plan`, `/fec-refactor`, and 11 refactoring skills that separate diagnosis, planning, execution, validation, catalog selection, and seven technique families.
+- **Complete refactoring knowledge coverage:** normalized the supplied 24 code smells and 61 refactoring techniques from Chapters 6–12 into stable `SMELL-*` / `RF-*` identifiers, selection guidance, composition relationships, and progressive references.
+- **Frontend-specific refactoring adaptation:** added TypeScript, React, Vue, hooks/composables, state, routing, async/lifecycle, public API, SSR/hydration, and dynamic-reference guidance without forcing class-based patterns into modern frontend code.
+- **Simplified Chinese refactoring mirror:** added natural Chinese Agent, Command, Skill, catalog, smell matrix, and refactoring navigation content under `localized/zh-CN` and `docs/refactoring`.
+
+- **Content integrity tooling:** added shared YAML frontmatter schemas, source/zh-CN capability and structure checks, and automatic discovery of all `tests/**/*.test.ts` files.
+
+### Changed
+
+- **Technical diagram quality:** preserve complete Unicode labels with content-driven layout, obstacle routing, visible self calls, and extended QA.
+- **Documentation:** synchronized runtime entry points and multilingual README capability sections, including tool prerequisites and QA limits.
+- **Review scope:** code, TypeScript and security review workflows now support project review (default), specified files/directories, and incremental review for explicit change/PR/commit context. Reports record coverage, exclusions, unreviewed scope and partial completion; targeted/project reviews assess risk without requiring a Git diff. Updated multilingual READMEs, runtime guidance and example prompts.
+
+- **Refactoring safety model:** pure refactoring now uses `GREEN → REFACTOR → GREEN`, one primary transformation at a time, step-level verification, rollback-before-repair, `SAFE/CAUTION/DANGER` risk classification, diff budgets, and `PASS/PARTIAL/NOT PROVEN` proof verdicts.
+- **Workflow boundaries:** clarified that new behavior and behavior-changing defects remain in TDD, unexplained failures remain in debugging, proven dead code remains in `fec-refactor-clean`, and general merge-readiness remains in code review.
+- **Public capability counts:** documentation and Marketplace metadata now advertise 14 agents, 56 skills, and 11 commands.
+
+- **Contributor toolchain:** standardized development and CI on pnpm 12.4.1 with a frozen lockfile, ESLint, content lint, and read-only formatting checks; version synchronization no longer stages files automatically.
+- **Validation hooks:** select npm, pnpm, yarn, or bun from project declarations and lockfiles, and avoid running duplicate validation stages.
+
+### Fixed
+
+- **Technical diagram exports:** repaired self-contained SVG styles, browser-measured PNG geometry, and manifests scaled to the exported image.
+- **Content parsing and conversion:** repaired malformed agent/command YAML and stale reviewer references; converters now preserve decoded descriptions and safely escape Codex TOML instructions. Same-name source skills retain priority over converted commands.
+- **Published CLI startup:** bundled the YAML parser and its Node module bridge so isolated npm packages can install Codex and OpenClaw content without repository development dependencies.
+- **Localized content and refactoring links:** synchronized Chinese diagram workflow boundaries, capability tags, and keywords; repaired catalog links and clarified skill summaries.
+- **Managed file ownership:** strengthened manifest path validation to prevent install/update operations from claiming paths outside managed content.
+
+### Chore
+
+- **Deterministic refactoring coverage:** added install-time integrity checks for 24 smells, 61 techniques, family totals, root/zh-CN alignment, metadata/relations/eval registration, command modes, public docs, and version synchronization.
+- **Release verification:** expanded regressions for parsing, conversion, test discovery, hook package-manager selection, and isolated package installation; the full suite now contains 242 tests. Packaging checks cover OpenClaw and all 56 standalone skill packages.
+
 ## [2.8.0] - 2026-06-25
 
 ### Added

package/CHANGELOG.zh-CN.md

@@ -8,6 +8,70 @@
 
 自 **2.0.0** 起，面向发布的说明以英文 `CHANGELOG.md` 为权威来源；历史条目可能保留最初撰写语言。
 
+## [3.0.0] - 2026-11-09
+
+### 公共能力抽取
+
+本节为未发布3.0.0，不因公共版本提升而变更产品版本或表示已经发布。新增分层工程实践、独立React状态案例及真实来源/分发校验；公共2.0.0须先发布并核验。
+
+- 公共能力由精确依赖craft-common2.0.0交付：21个cc入口与53个前端入口，共74项；C/C++语言基础及Tauri/Electron专项由两产品共同复用。
+- 增加共享所有权、版本/语言冲突保护、事务恢复及只读迁移检查。
+- [迁移指南](docs/zh-CN/common-migration.md)说明旧入口处理与独立卸载规则。
+
+
+### 破坏性变更与迁移
+
+- 顶层 `fec update` / `upgrade` 改为通过原 npm/pnpm 及原 registry 升级全局 CLI，再用新版 CLI 刷新当前项目及用户全局的托管资源；不扫描其他项目，不管理 Marketplace 安装。
+- 顶层 `fec uninstall` / `remove` 默认只卸载 CLI；`--purge` 先清理已发现的托管资源并保留用户修改，清理实际失败时保留 CLI。交互终端要求确认，非交互终端必须传入 `--yes`。
+- 资源命令迁至 `fec runtime install/update/uninstall [runtime]`，保留 `runtime upgrade/remove` 别名及原资源选项。`setup` 保留，顶层 `install` 为弃用兼容入口。顶层 update/uninstall 在修改前拒绝旧 runtime 位置参数和资源选项，并输出迁移指引。
+- 将 `fec update codex --global` 改为 `fec runtime update codex --global`，将 `fec uninstall --local` 改为 `fec runtime uninstall --local`。临时运行使用 `npx @bovinphang/frontend-craft@latest runtime update`；`runtime update` 仅使用当前运行的 CLI 包资源，不联网获取新 CLI 包。
+
+### 新增
+
+- 验证 npm/pnpm 全局安装归属、复用原包管理器、新入口续跑、分阶段失败报告及只读 `--dry-run`。已是最新版仍刷新资源；CLI 升级失败停止资源操作。资源部分失败不回滚新版 CLI，可通过 `fec runtime update` 重试。
+- 临时 npx 更新检查 registry `latest`，不创建全局安装；当前版本不匹配时提示最新版 runtime 命令。npx 不支持自身卸载。源码链接、项目依赖、未知来源及含其他包的 pnpm 共享安装组均在修改前拒绝自动自身管理。
+
+以下条目记录 2.x 历史行为；当前资源命令请使用上述 `runtime` 分组。
+
+## [2.9.0] - 2026-09-26
+
+### 新增
+
+- **技术图工具**：新增可选本地 Mermaid 适配器及可复现的时序图、流程图和架构图样例。
+- **文档**：新增中英文审核范围与技术图交付指南。
+- **保持行为的重构子系统**：新增 `fec-refactoring-expert`、`/fec-smell`、`/fec-refactor-plan`、`/fec-refactor`，以及 11 个重构技能，将坏味道诊断、只读规划、受控执行、行为验证、目录选择和 7 类重构手法拆分为清晰能力。
+- **完整重构知识覆盖**：以用户提供的《重构：改善既有代码的设计（第 2 版）》JavaScript 版材料为知识基线，归一化 24 种代码坏味道和第 6～12 章 61 个标准重构手法，建立稳定的 `SMELL-*` / `RF-*` 标识、选择指南、组合关系和渐进式 Reference。
+- **前端专项适配**：补充 TypeScript、React、Vue、hooks/composables、状态管理、路由、异步/生命周期、公开 API、SSR/hydration 与动态引用场景，同时避免把现代前端机械改写为 class hierarchy。
+- **简体中文重构镜像**：在 `localized/zh-CN` 和 `docs/refactoring` 中新增自然中文的 Agent、Command、Skill、目录、坏味道矩阵与导航文档。
+
+- **内容完整性工具**：新增共享 YAML frontmatter 类型校验、中英文能力引用与结构检查，以及 `tests/**/*.test.ts` 自动发现。
+
+### 变更
+
+- **技术图质量**：通过内容驱动布局、避障连线、可见自调用和增强 QA 保留完整 Unicode 标签。
+- **文档**：同步运行时入口及多语言 README 能力章节，说明工具前提与 QA 边界。
+- **审核范围**：代码、TypeScript 和安全审核流程支持全项目（默认）、指定文件或目录、明确改动或 PR/提交上下文的增量审核。报告记录覆盖范围、排除项、未覆盖范围和部分完成状态；指定范围及全项目审核不要求 Git 差异，输出风险评估。同步多语言 README、运行时指南和提示词示例。
+
+- **重构安全模型**：纯重构统一采用 `GREEN → REFACTOR → GREEN`，一次只做一个主要结构变换，每步验证；新增“先回滚再修复”、`SAFE/CAUTION/DANGER` 风险分级、差异预算，以及 `PASS/PARTIAL/NOT PROVEN` 行为保持证明等级。
+- **工作流边界**：新增行为和行为变化型缺陷仍由 TDD 负责；原因未知的失败仍由调试框架负责；已证明的死代码仍由 `fec-refactor-clean` 负责；一般 PR 合并就绪性仍由代码评审负责。
+- **公开能力数量**：README、OpenClaw 文档与 Marketplace 元数据同步为 14 个 Agent、56 个 Skill、11 个 Command。
+
+- **贡献者工具链**：开发与 CI 统一使用 pnpm 12.4.1、冻结锁文件、ESLint、内容 lint 和只读格式检查；版本同步不再自动暂存文件。
+- **验证 Hook**：根据项目声明和锁文件选择 npm、pnpm、yarn 或 bun，避免重复执行验证阶段。
+
+### 修复
+
+- **技术图导出**：修复独立 SVG 样式、真实浏览器 PNG 几何测量及与导出图片缩放一致的 manifest。
+- **内容解析与转换**：修复 Agent/Command 的非法 YAML 和过时 reviewer 引用；转换器使用解码后的描述，并安全转义 Codex TOML 指令。同名原始技能继续优先于转换后的命令。
+- **发布 CLI 启动**：内置 YAML 解析器及其 Node 模块桥接，确保隔离 npm 包无需仓库开发依赖即可安装 Codex 和 OpenClaw 内容。
+- **中文内容与重构链接**：同步图表工作流边界、能力标签及关键词，修复目录链接并完善技能摘要。
+- **受管文件归属**：加强 manifest 路径校验，避免安装或更新操作将受管内容之外的路径纳入管理。
+
+### Chore
+
+- **确定性重构验收**：新增安装级完整性检查，覆盖 24 种坏味道、61 个手法、7 个 family 数量、root/zh-CN 对齐、metadata/relations/eval 注册、命令模式、公开文档与版本同步。
+- **发布验证**：扩充解析、转换、测试发现、Hook 包管理器选择和隔离包安装回归；完整测试共 242 项，打包检查覆盖 OpenClaw 和全部 56 个独立技能包。
+
 ## [2.8.0] - 2026-06-25
 
 ### 新增

package/CONTRIBUTING.md

@@ -8,20 +8,28 @@ Thanks for your interest in `frontend-craft`. Issues, pull requests, documentati
 
 - Node.js >= 22 for the universal installer and OpenClaw package build.
 - Git.
-- Run `npm install` before local development.
+- pnpm 12.4.1 (pinned in package.json); installing pnpm through npm requires Node.js >=22.13. The published plugin still supports Node.js >=22.0.0.
+- On Windows, install pnpm through Corepack (`corepack enable pnpm`) or npm rather than the standalone installer; a standalone pnpm 10+ blocks the lifecycle scripts that install the pinned version's native binary and leaves a shim Windows cannot execute.
+- pnpm-lock.yaml is the sole dependency lockfile. pnpm-workspace.yaml permits esbuild build scripts and explicitly skips optional SDK/native setup not used by this project.
+- Run `pnpm install --frozen-lockfile` before local development.
 
 For documentation-only changes, focus on the language and documentation policy plus the pull request checklist. For skill or OpenClaw changes, use the focused sections below before opening a pull request.
 
 Quick checks (minimum recommended):
 
+`pnpm lint` checks source code and both content languages. `pnpm format:check` checks changed source/config files without modifying them. `pnpm test` recursively discovers `tests/**/*.test.ts`, so new tests need no script-list update.
+
 ```bash
-npm test                         # General validation
-npm run pack:skills              # Skill changes
-npm run check:skills-publish     # Skill changes
-npm run typecheck:openclaw       # OpenClaw changes
+pnpm lint                         # ESLint + content validation
+pnpm typecheck                    # TypeScript + skill script types
+pnpm run check:common             # Read-only common snapshot check
+pnpm test                         # Build + all tests
+pnpm run pack:skills              # Skill changes
+pnpm run check:skills-publish     # Skill changes
+pnpm run typecheck:openclaw       # OpenClaw changes
 ```
 
-See the NPM Scripts section and Pull Request Checklist for complete scenario-specific checks.
+See the Development Scripts section and Pull Request Checklist for complete scenario-specific checks.
 
 ## Project Structure
 
@@ -48,23 +56,25 @@ See the NPM Scripts section and Pull Request Checklist for complete scenario-spe
 
 ```bash
 # 1. Install dependencies
-npm install
+pnpm install
 
 # 2. Build dist/bin and dist/hooks
-npm run build
+pnpm run build
 
 # 3. Install to a specific runtime (e.g., claude)
-node dist/bin/frontend-craft.js install claude --local --dry-run  # preview first
-node dist/bin/frontend-craft.js install claude --local            # actual install
+node dist/bin/frontend-craft.js runtime install claude --local --dry-run  # preview first
+node dist/bin/frontend-craft.js runtime install claude --local            # actual install
 
 # 4. Install to all runtimes
-node dist/bin/frontend-craft.js install --all --dry-run
+node dist/bin/frontend-craft.js runtime install --all --dry-run
 
 # 5. List all supported runtimes
 node dist/bin/frontend-craft.js list
 ```
 
-`npm run build` runs `clean`, `typecheck`, and `scripts/build-dist.ts`. Run it before using `dist/bin/frontend-craft.js` or the bundled hook scripts locally.
+`pnpm run build` runs `clean`, `typecheck`, and `scripts/build-dist.ts`. Run it before using `dist/bin/frontend-craft.js` or the bundled hook scripts locally.
+
+Local source checkouts intentionally do not support CLI self-management. Use `node dist/bin/frontend-craft.js runtime update --dry-run` to preview bundled resource updates; test top-level update/uninstall only against isolated npm/pnpm global installations with fake package managers and temporary HOME directories. Top-level `--dry-run` must remain read-only. See the README migration table for the 3.0 command split.
 
 ## Testing
 
@@ -72,7 +82,7 @@ Tests use Node.js built-in `node:test` with `assert/strict`.
 
 ```bash
 # Run all tests
-npm test
+pnpm test
 
 # Run a single test file
 node --import tsx --test tests/install/cli.test.ts
@@ -93,17 +103,17 @@ For testing the interactive installation wizard, set `FRONTEND_CRAFT_FORCE_INTER
 FRONTEND_CRAFT_FORCE_INTERACTIVE=1 node --import tsx --test tests/install/cli.test.ts
 ```
 
-`npm test` runs `npm run build` first, then executes the curated converter and installer test suite from `tests/`.
+`pnpm test` runs `pnpm run build` first, then recursively discovers every `tests/**/*.test.ts` file and executes them serially with Node.js `node:test`. `pnpm run test:only` runs that suite against an existing build.
 
 ## OpenClaw Build
 
 The OpenClaw runtime has its own build pipeline:
 
 ```bash
-npm run build:openclaw          # Bundle TypeScript to dist/openclaw/ via esbuild
-npm run typecheck:openclaw      # TypeScript type checking
-npm run check:openclaw-dist     # Verify dist integrity
-npm run pack:openclaw           # Full build + verify + package
+pnpm run build:openclaw          # Bundle TypeScript to dist/openclaw/ via esbuild
+pnpm run typecheck:openclaw      # TypeScript type checking
+pnpm run check:openclaw-dist     # Verify dist integrity
+pnpm run pack:openclaw           # Full build + verify + package
 ```
 
 Source: `src/openclaw/` (TypeScript) → `dist/openclaw/index.js` (bundled ESM).
@@ -114,12 +124,12 @@ TypeScript config: `tsconfig.openclaw.json`.
 The canonical skill sources live under `skills/<skill-id>/`. Do not edit generated files under `skill-packages/` by hand.
 
 ```bash
-npm run pack:skills            # Build one standalone package per skill
-npm run check:skills-publish   # Verify package metadata, index, and copied references
-npm run pack:all               # Build + test + OpenClaw package + standalone skill packages
+pnpm run pack:skills            # Build one standalone package per skill
+pnpm run check:skills-publish   # Verify package metadata, index, and copied references
+pnpm run pack:all               # Build + test + OpenClaw package + standalone skill packages
 ```
 
-`npm run pack:skills` writes `skill-packages/<skill-id>/` with `SKILL.md`, only the referenced `references/` files, `metadata.json`, `package.json`, `README.md`, and `LICENSE`. It also writes `skill-packages/index.json` for platform crawlers and release automation.
+`pnpm run pack:skills` writes `skill-packages/<skill-id>/` with `SKILL.md`, referenced `references/` files and required scripts, assets, data and styles, `metadata.json`, `package.json`, `README.md`, and `LICENSE`. It also writes `skill-packages/index.json` for platform crawlers and release automation.
 
 When changing a skill, keep these source files aligned:
 
@@ -128,34 +138,37 @@ When changing a skill, keep these source files aligned:
 - `skills/eval_queries.json` — positive and negative trigger examples used by routing quality checks.
 - `README.md` and localized README summaries when the public skill list or user-facing behavior changes.
 
-## NPM Scripts
+## Development Scripts
 
 Use `package.json` scripts as the public development entrypoints.
 
 | Script                         | Purpose                                                                          |
 | ------------------------------ | -------------------------------------------------------------------------------- |
-| `npm run clean`                | Remove `dist/`.                                                                  |
-| `npm run typecheck`            | Run main TypeScript checks plus checked skill support scripts.                   |
-| `npm run build`                | Run `clean`, `typecheck`, and bundle CLI/hooks via `scripts/build-dist.ts`.      |
-| `npm test`                     | Build, then run the curated `node:test` suite with `tsx`.                        |
-| `npm run build:openclaw`       | Build the main project, then bundle OpenClaw runtime output.                     |
-| `npm run audit:skills`         | Build, then report skill instruction size and description overlap signals.       |
-| `npm run typecheck:openclaw`   | Run TypeScript checking for OpenClaw with `tsconfig.openclaw.json`.              |
-| `npm run check:openclaw-dist`  | Verify the generated OpenClaw dist output.                                       |
-| `npm run pack:openclaw`        | Build, verify, and package the OpenClaw plugin.                                  |
-| `npm run pack:skills`          | Build first, then create standalone packages under `skill-packages/`.            |
-| `npm run check:skills-publish` | Build first, then verify standalone skill package metadata and copied files.     |
-| `npm run pack:all`             | Build, run tests, package OpenClaw, package skills, and verify skill output.     |
-| `npm run sync:version`         | Sync package version metadata across release manifests.                          |
-| `npm run version`              | Run `sync:version`, then stage versioned manifests for npm version workflows.    |
-| `npm run prepack`              | Build before `npm pack`.                                                         |
-| `npm run prepublishOnly`       | Sync versions and run tests before npm publish.                                  |
+| `pnpm run lint` | Check code and bilingual content declarations. |
+| `pnpm run format:check` | Check changed source formatting. |
+| `pnpm run check:content` | Validate YAML, names, references and localization structure. |
+| `pnpm run clean`                | Remove `dist/`.                                                                  |
+| `pnpm run typecheck`            | Run main TypeScript checks plus checked skill support scripts.                   |
+| `pnpm run build`                | Run `clean`, `typecheck`, and bundle CLI/hooks via `scripts/build-dist.ts`.      |
+| `pnpm test`                     | Build, then recursively discover and run all `node:test` tests.                        |
+| `pnpm run build:openclaw`       | Build the main project, then bundle OpenClaw runtime output.                     |
+| `pnpm run audit:skills`         | Build, then report skill instruction size and description overlap signals.       |
+| `pnpm run typecheck:openclaw`   | Run TypeScript checking for OpenClaw with `tsconfig.openclaw.json`.              |
+| `pnpm run check:openclaw-dist`  | Verify the generated OpenClaw dist output.                                       |
+| `pnpm run pack:openclaw`        | Build, verify, and package the OpenClaw plugin.                                  |
+| `pnpm run pack:skills`          | Build first, then create standalone packages under `skill-packages/`.            |
+| `pnpm run check:skills-publish` | Build first, then verify standalone skill package metadata and copied files.     |
+| `pnpm run pack:all`             | Build, run tests, package OpenClaw, package skills, and verify skill output.     |
+| `pnpm run sync:version`         | Sync package version metadata across release manifests.                          |
+| `pnpm run version`              | Sync versioned manifests without automatically staging files.    |
+| `pnpm run prepack`              | Build before `npm pack`.                                                         |
+| `pnpm run prepublishOnly`       | Sync versions and run tests before npm publish.                                  |
 
 For common change types:
 
-- Skill changes: run `npm test`, `npm run audit:skills`, `npm run pack:skills`, and `npm run check:skills-publish`.
-- OpenClaw changes: run `npm run typecheck:openclaw` and `npm run pack:openclaw`.
-- Release packaging: run `npm run pack:all`; `prepublishOnly` also runs version sync and tests before publish.
+- Skill changes: run `pnpm test`, `pnpm run audit:skills`, `pnpm run pack:skills`, and `pnpm run check:skills-publish`.
+- OpenClaw changes: run `pnpm run typecheck:openclaw` and `pnpm run pack:openclaw`.
+- Release packaging: CI runs `pnpm run pack:all`; `prepublishOnly` also runs version sync and tests before publish.
 
 ## Source Maintenance Files
 
@@ -181,11 +194,12 @@ Hook scripts live under `src/hooks/` and are bundled into `dist/hooks/` for publ
 
 | Source file                        | Bundled output                      | Purpose                |
 | ---------------------------------- | ----------------------------------- | ---------------------- |
-| `src/hooks/run-tests.ts`           | `dist/hooks/run-tests.js`           | Test runner helper     |
-| `src/hooks/format-changed-file.ts` | `dist/hooks/format-changed-file.js` | Format changed files   |
-| `src/hooks/security-check.ts`      | `dist/hooks/security-check.js`      | Security scanning      |
-| `src/hooks/notify.ts`              | `dist/hooks/notify.js`              | Notification script    |
-| `src/hooks/session-start.ts`       | `dist/hooks/session-start.js`       | Session initialization |
+| `src/hooks/cleanup-claude-cache.ts` | `dist/hooks/fec-cleanup-claude-cache.js` | Cache cleanup |
+| `src/hooks/run-tests.ts`           | `dist/hooks/fec-run-tests.js`           | Test runner helper     |
+| `src/hooks/format-changed-file.ts` | `dist/hooks/fec-format-changed-file.js` | Format changed files   |
+| `src/hooks/security-check.ts`      | `dist/hooks/fec-security-check.js`      | Security scanning      |
+| `src/hooks/notify.ts`              | `dist/hooks/fec-notify.js`              | Notification script    |
+| `src/hooks/session-start.ts`       | `dist/hooks/fec-session-start.js`       | Session initialization |
 
 ## Architecture Overview
 
@@ -281,7 +295,7 @@ description: Use when the user needs ...
 4. Add positive and negative trigger examples to `skills/eval_queries.json`.
 5. Add the skill to the Skills table in `README.md`.
 6. Update the repository tree in `README.md` and localized README files if the visible structure changes.
-7. Run `npm test`, `npm run pack:skills`, and `npm run check:skills-publish`.
+7. Run `pnpm test`, `pnpm run pack:skills`, and `pnpm run check:skills-publish`.
 
 ## Adding an Agent
 
@@ -328,8 +342,8 @@ skills:
 
 1. Update `hooks/hooks.json`.
 2. Put runtime hook scripts under `src/hooks/` and prefer cross-platform Node.js.
-3. Add each new hook entrypoint to `scripts/build-dist.ts` so `npm run build` bundles it into `dist/hooks/`.
-4. In `hooks/hooks.json`, use **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`** for bundled hook entrypoints (Claude Code substitutes the root at runtime; see the official [Plugins reference](https://code.claude.com/docs/en/plugins-reference)). The Claude installer in this repo also expands **`${CLAUDE_PLUGIN_ROOT}`** and legacy **`${FRONTEND_CRAFT_ROOT}`** to absolute paths when it writes `hooks.json` under `.claude/`.
+3. Add each new hook entrypoint to `scripts/build-dist.ts` so `pnpm run build` bundles it into `dist/hooks/`.
+4. In `hooks/hooks.json`, use **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`** for bundled hook entrypoints (Claude Code substitutes the root at runtime; see the official [Plugins reference](https://code.claude.com/docs/en/plugins-reference)). The Claude installer in this repo also expands **`${CLAUDE_PLUGIN_ROOT}`** and legacy **`${FRONTEND_CRAFT_ROOT}`** to absolute paths when it merges CLI-managed hook entries into `.claude/settings.json`. The source `hooks/hooks.json` remains the native plugin hook configuration.
 5. Keep repository maintenance scripts under `scripts/`; do not reference them directly from runtime hook configuration.
 6. Update the Hooks table in `README.md`.
 
@@ -338,13 +352,13 @@ skills:
 Before opening a pull request:
 
 - [ ] The change is scoped and described clearly.
-- [ ] `npm test` passes.
-- [ ] Skill changes pass `npm run audit:skills`, `npm run pack:skills`, and `npm run check:skills-publish`.
-- [ ] `npm run typecheck:openclaw` and `npm run pack:openclaw` pass when OpenClaw code or templates are affected.
+- [ ] `pnpm test` passes.
+- [ ] Skill changes pass `pnpm run audit:skills`, `pnpm run pack:skills`, and `pnpm run check:skills-publish`.
+- [ ] `pnpm run typecheck:openclaw` and `pnpm run pack:openclaw` pass when OpenClaw code or templates are affected.
 - [ ] `README.md` and `CHANGELOG.md` are updated when user-facing behavior changes (and `CHANGELOG.zh-CN.md` when you ship Chinese-facing release notes).
 - [ ] Localized README files are synced, or a follow-up translation issue is linked.
 - [ ] New runtime, agent, skill, command, hook, or template changes include relevant tests or dry-run coverage.
-- [ ] Release packaging changes pass `npm run pack:all` or are covered by the `prepublishOnly` publish gate.
+- [ ] Release packaging changes pass `pnpm run pack:all` or are covered by the `prepublishOnly` publish gate.
 - [ ] Security-sensitive changes have been reviewed against `SECURITY.md`.
 
 ## Code Style
@@ -359,3 +373,9 @@ Before opening a pull request:
 Use [GitHub Issues](https://github.com/bovinphang/frontend-craft/issues) for bugs and feature requests. Include the runtime, operating system, Node.js version, exact command, expected behavior, and actual behavior whenever possible.
 
 Do not file security-sensitive vulnerabilities as public issues. Follow [SECURITY.md](SECURITY.md) instead.
+
+When changing review or diagram capabilities, synchronize scope defaults, natural-language examples, tool prerequisites, QA limits, and coverage reporting across README translations and runtime guides. See [review scope and technical diagram delivery](docs/review-and-diagram-workflows.md).
+
+## Maintaining common content
+
+`cc-*` skills and embedded common methods are generated from the exact `@bovinphang/craft-common@2.0.0` dependency. Change the upstream common package first, prepare its corresponding package, then run `pnpm run sync:common`. Review `common-content.lock.json` and both language snapshots, then run `pnpm run check:common` and `pnpm lint`. Do not edit generated common content directly. Frontend domain skills, metadata and Chinese mirrors remain maintained here. See [project structure](docs/project-structure.md) and [common migration](docs/common-migration.md).