npm - @bovinphang/frontend-craft - Versions diffs - 2.9.0 → 3.0.0 - Mend

@bovinphang/frontend-craft 2.9.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (579) hide show

package/README.md CHANGED Viewed

@@ -1,545 +1,605 @@
-<div align="center">
-<img src="assets/brand/frontend-craft.png" alt="frontend-craft logo" width="200" />
-# frontend-craft
-### One toolkit. Every AI coding assistant. Production-grade frontend standards.
-[![Stars](https://img.shields.io/github/stars/bovinphang/frontend-craft?style=flat)](https://github.com/bovinphang/frontend-craft/stargazers)
-[![CI](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml/badge.svg)](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@bovinphang/frontend-craft)](https://www.npmjs.com/package/@bovinphang/frontend-craft)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-![Node](https://img.shields.io/badge/Node.js-22+-5FA04E?logo=node.js&logoColor=white)
-![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
-![React](https://img.shields.io/badge/-React-61DAFB?logo=react&logoColor=black)
-![Vue](https://img.shields.io/badge/-Vue-4FC08D?logo=vue.js&logoColor=white)
-![Figma](https://img.shields.io/badge/-Figma-F24E1E?logo=figma&logoColor=white)
-**🌐 Language / 语言 / 語言 / 言語 / 언어**
-[**English**](README.md) · [简体中文](README.zh-CN.md) · [繁體中文](docs/zh-TW/README.md) · [日本語](docs/ja-JP/README.md) · [한국어](docs/ko-KR/README.md)
-</div>
-[Runtime compatibility and upgrade notes](docs/runtimes/compatibility.md)
----
-`frontend-craft` is a **universal frontend plugin** that brings the same opinionated engineering standards to all **15 AI coding assistants** listed below:
-`claude` `codex` `cursor` `windsurf` `opencode`
-`kilo` `gemini` `copilot` `antigravity` `augment`
-`trae` `codebuddy` `cline` `openclaw` `qoder`
-Per-runtime paths and caveats live in [`docs/runtimes/`](docs/runtimes/).
-It bundles **14 specialized agents**, **56 auto-activated skills**, **11 slash commands**, **5 event-driven hooks**, **MCP integrations** for 6 design-tool endpoints, and a complete **rules library** into a single installable package. Run one command, and every AI session on your team writes React, Vue, Next.js, or Nuxt the same way — typed, accessible, secure, and consistent.
----
-## Why frontend-craft?
-| Problem                                                              | What frontend-craft does                                                                       |
-| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| AI assistants write inconsistent, untyped, or insecure frontend code | **56 skills** encode team standards — auto-activated when the assistant touches matching files |
-| Each AI tool has its own plugin format                               | **One CLI** installs the same rules, agents, and hooks into 15 runtimes                        |
-| Design-to-code handoff is lossy                                      | **MCP integrations** bring in richer context from Figma, Figma Desktop, Sketch, MasterGo, Pixso, and 墨刀 |
-| Reviews are ad-hoc and shallow                                       | **14 agents** produce graded reports: code, security, a11y, performance, TS, UI fidelity       |
-| No one remembers to run lint/tests                                   | **Event-driven hooks** validate on save and session end — automatically                        |
-| New projects start from scratch every time                           | **`/fec-init`** scaffolds CLAUDE.md, rules, and settings in seconds                            |
----
-## Install
-Requires **Node.js 22+**. Works on **Windows, macOS, and Linux**.
-### Option 1 - Install the fec CLI globally (recommended)
-```bash
-# 1. Install the fec command globally
-npm install -g @bovinphang/frontend-craft@latest
-# 2. Go to your frontend project
-cd your-project
-# 3. Choose the AI runtime(s) interactively
-fec setup
-# 4. Connect the current project
-fec setup codex
-fec setup claude
-fec setup all
-# 5. Connect globally, available across all projects
-fec setup codex --global
-fec setup claude --global
-fec setup all --global
-# 6. Preview / query
-fec install --all --dry-run --global
-fec list
-```
-`npm install -g` only installs the `fec` terminal command. `fec setup` is the terminal CLI command for connecting frontend-craft to a project; it is not the in-assistant `/fec-init` slash command. In an interactive terminal, running only `fec setup` asks you to choose runtimes. `fec setup <runtime>` and `fec setup all` connect frontend-craft to the current project by default. Only pass `--global` when you want to connect frontend-craft to the selected AI tool's global config directory so it is available across projects.
-### Option 2 — Temporary npx run (no global fec command)
-```bash
-# 1. Interactive wizard
-npx @bovinphang/frontend-craft@latest
-# 2. Connect the current project
-npx @bovinphang/frontend-craft@latest install --local codex
-npx @bovinphang/frontend-craft@latest install --local claude
-npx @bovinphang/frontend-craft@latest install --all --local
-# 3. Connect globally, available across all projects
-npx @bovinphang/frontend-craft@latest install --global codex
-npx @bovinphang/frontend-craft@latest install --global claude
-npx @bovinphang/frontend-craft@latest install --all --global
-# 4. Preview / query
-npx @bovinphang/frontend-craft@latest install --all --dry-run --global
-npx @bovinphang/frontend-craft@latest list
-```
-Use `npx` when you do not want to install a global `fec` command. Without arguments, it opens the interactive wizard: choose one or more runtimes, then choose whether to connect globally or into the current project. For scripted all-runtime installs, use `install --all --local` or `install --all --global`; do not write `install all`. For CI / scripts, always pass `--global` / `-g` or `--local` / `-l`; in non-TTY environments without an explicit location, the CLI defaults to `claude --global`.
-### Option 3 — Claude Code Marketplace
-For Claude Code users, **Claude Code Marketplace** is the preferred single-source install. Use the CLI for Claude only when you need cross-runtime installs, scripted/offline file copies, or non-Marketplace environments.
-If Marketplace is already installed, the CLI will not install or update a second Claude copy, even with `--force`; update through Claude Code Marketplace instead. If a CLI-managed Claude install already exists in the other scope, interactive terminals ask whether to keep that source updated or uninstall it before switching. Non-interactive terminals stop and print the exact `update`, `uninstall`, and `install` commands to run.
-Full Claude-specific steps are in [docs/runtimes/claude.md](docs/runtimes/claude.md) · [简体中文](docs/runtimes/claude.zh-CN.md).
----
-## Quick start
-Once installed, you have a full frontend engineering toolkit available in every AI session:
-```text
-You: "Review my recent changes"
-→ The fec-code-reviewer agent is dispatched, produces reports/code-review-*.md
-You: "/fec-review"
-→ Runs a structured review across architecture, types, rendering, styles, a11y
-You: "Implement the checkout page from this Figma link"
-→ The fec-figma-implementer agent reads the design via MCP, emits components and a report
-You: "/fec-scaffold dashboard feature"
-→ Creates a page / feature / component directory tree following project conventions
-You: "/fec-refactor-clean"
-→ Classifies and safely removes dead code, unused exports, styles, and deps
-You: "/fec-refactor src/features/compose"
-→ Diagnoses structural smells, builds a small-step plan, refactors one behavior-preserving step at a time, and validates every step
-```
-All slash commands below are shown for **Claude Code**; other runtimes expose the same capabilities through their own command systems (see [`docs/runtimes/`](docs/runtimes/)).
----
-## Example prompts
-For a complete scenario-based prompt library, see [docs/example-prompts.md](docs/example-prompts.md).
-```text
-You: "Review my recent changes before merge. Focus on architecture, type safety, rendering behavior, styles, accessibility, and missing tests."
-You: "Before coding, plan the account billing feature: route structure, component boundaries, data flow, state ownership, validation flow, and rollout risks."
-You: "Build a multi-step registration form; choose the right form and schema validation approach for this project, with file upload, conditional fields, async validation, and accessible errors."
-You: "Implement the UI from Figma node 123:456. Use existing design tokens and components, match spacing and responsive states, and document assumptions."
-You: "`/fec-refactor-clean` Clean up dead code in this module."
-You: "`/fec-smell` Diagnose structural smells in this module without editing."
-You: "`/fec-refactor-plan` Build a behavior-preserving small-step refactoring plan."
-You: "`/fec-refactor` Refactor this module without changing observable behavior."
-```
----
-## What’s inside
-### Commands
-Slash commands are the primary entry points for structured workflows. Most produce a timestamped Markdown report under `reports/`.
-| Command               | Purpose                                                                | Report                                           |
-| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
-| `/fec-init`           | Initialize project templates (CLAUDE.md, rules, settings)              | —                                                |
-| `/fec-review`         | Review the full project by default; explicit file/directory or change scope | `code-review-*.md`                               |
-| `/fec-scaffold`       | Create page / feature / component boilerplate by convention            | —                                                |
-| `/fec-plan`           | Unified planning: implementation architecture or test strategy         | `architecture-proposal-*.md` or `test-plan-*.md` |
-| `/fec-tdd`            | Red → green → refactor loop for frontend TDD                           | —                                                |
-| `/fec-debug`          | Diagnose and fix frontend issues: build, runtime, UI, and API failures | `debug-*.md`                                     |
-| `/fec-refactor-clean` | Classify and safely remove dead code, unused exports, styles, and deps | `refactor-clean-*.md`                            |
-| `/fec-smell`          | Diagnose code smells with evidence; do not edit business code             | `refactoring/smell-*.md`                       |
-| `/fec-refactor-plan`  | Build an ordered behavior-preserving refactoring plan                      | `refactoring/plan-*.md`                        |
-| `/fec-refactor`       | Execute one validated behavior-preserving refactoring step at a time       | `refactoring/refactoring-*.md`                 |
-| `/fec-doc-sync`       | Sync READMEs, docs, env notes, scripts, API/route notes, and deploy docs | —                                                |
-### Review scope
-`/fec-review`, the code/TypeScript/security review agents, and their review skills use three modes:
-- **Change review:** explicitly request recent/current/staged changes, a PR or a commit, or use an established change context. With no changes, report that there is nothing to review; do not automatically review recent commits.
-- **Targeted review:** specify a file or directory to review existing code, including unchanged code, without requiring a Git diff.
-- **Project review (default):** with no scope or change context, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review by module.
-A file/directory request reviews its full contents; add "recent changes" to review only its diff. Bare `/fec-review` reviews the project even when changes exist. State mode and scope before review. Automatic review after edits must pass the current change scope explicitly.
-Examples: `/fec-review`,`/fec-review review recent changes`,  `/fec-review review src/components/Button.tsx`, `/fec-review review src/features/`, and `/fec-review review the entire project`. These are natural-language instructions, not CLI flags. Explicit scope takes precedence over the default.
-Dependency directories, build outputs, caches, generated files and third-party code are excluded by default. Reports record the mode, target scope, reviewed and unreviewed files/modules, exclusions, completion status and verification results. Limited coverage is marked partial; reading callers or running project-wide lint/typecheck does not establish manual review coverage. Change reviews retain merge recommendations; targeted/project reviews assess risk within reviewed scope. The frontend review does not replace a backend audit, and reviewers do not edit business code unless repairs are requested.
-### Skills (auto-activated)
-Skills are workflow definitions that activate automatically based on file patterns, frameworks, or task context. They encode review dimensions, output conventions, and report formats.
-The skills below are grouped by use case so you can quickly find project standards, implementation, testing, review, design, migration, project evolution, and documentation workflows.
-**Project standards** — conventions enforced whenever matching frameworks are detected:
-| Skill                           | Scope                                                                 |
-| ------------------------------- | --------------------------------------------------------------------- |
-| `fec-react-project-standard`    | React + TypeScript (structure, components, routing, state, API layer) |
-| `fec-vue3-project-standard`     | Vue 3 + TypeScript (structure, components, routing, Pinia, API layer) |
-| `fec-nextjs-project-standard`   | Next.js 14+ App Router, SSR/SSG, streaming, metadata                  |
-| `fec-nuxt-project-standard`     | Nuxt 3 SSR/SSG, composables, data fetching, middleware                |
-| `fec-vite-project-standard`     | Vite config, env safety, HMR, dev proxy, build optimization           |
-| `fec-monorepo-project-standard` | pnpm workspace, Turborepo, Nx structure and task orchestration        |
-| `fec-typescript-project-standard`   | TypeScript config, public API types, declarations, DTOs, generics             |
-**Implementation capabilities** — activated when building specific frontend behavior:
-| Skill                     | Scope                                                                     |
-| ------------------------- | ------------------------------------------------------------------------- |
-| `fec-data-fetching`       | Server-state fetching, caching, invalidation, SSR, infinite loading       |
-| `fec-api-integration`     | Typed API clients, auth refresh, uploads, realtime integration            |
-| `fec-state-management`    | State ownership, store selection, URL state, server/form/local boundaries |
-| `fec-form-handling`       | Framework-aware forms, schema validation, dynamic fields, uploads         |
-| `fec-browser-storage`     | localStorage / sessionStorage / IndexedDB / Cookies selection             |
-| `fec-route-protection`    | Auth and permission routes for React Router, Next.js, Vue Router, Nuxt    |
-| `fec-pwa-implementation`  | Manifest, service worker, offline cache, install prompts                  |
-| `fec-web-workers`         | Web Worker integration, transferables, Comlink, worker pools              |
-| `fec-canvas-threejs`      | Canvas 2D, Three.js, React Three Fiber, WebGL                             |
-| `fec-svg-animation`       | CSS / Framer Motion / GSAP SVG animation with reduced-motion              |
-| `fec-list-virtualization` | Framework-aware list virtualization, measurement, grids, infinite scroll  |
-**Testing** — activated when planning or authoring frontend test coverage:
-| Skill                   | Scope                                                                    |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `fec-testing-strategy`  | Layer selection across static, unit, component, integration, E2E, visual |
-| `fec-component-testing` | React Testing Library / Vue Test Utils with regression scenarios         |
-| `fec-e2e-testing`       | Playwright / Cypress E2E with Page Object and CI integration             |
-| `fec-tdd-workflow`      | Test-first frontend implementation with red-green-refactor               |
-**Review & quality** — activated during review, validation, or cleanup workflows:
-| Skill                          | Scope                                                                         |
-| ------------------------------ | ----------------------------------------------------------------------------- |
-| `fec-code-review`              | Correctness, maintainability, types, rendering, and verification review        |
-| `fec-debug-framework`          | Systematic diagnostics for build, runtime, UI, and API/data failures          |
-| `fec-security-review`          | Browser-side XSS, CSRF, token exposure, unsafe DOM, and third-party risks     |
-| `fec-accessibility-check`      | WCAG 2.2, keyboard, focus, touch, and screen-reader behavior                  |
-| `fec-dependency-upgrade`       | Dependency upgrades, lockfile review, CVE remediation, migration verification |
-| `fec-validation-fix`           | Run and repair lint, type-check, test, build in one pass                      |
-| `fec-performance-optimization` | Core Web Vitals, bundle, rendering, memory, network, and budget reviews       |
-| `fec-refactor-clean`           | Safe dead-code, unused export, style, route, dependency cleanup               |
-**Refactoring** — activated for evidence-based, behavior-preserving structural improvement:
-| Skill | Purpose |
-| --- | --- |
-| `fec-refactoring` | Orchestrate classification, baseline, safety, small-step execution, rollback, and proof |
-| `fec-code-smells` | Diagnose the 24 canonical code smells with evidence and false-positive checks |
-| `fec-refactoring-catalog` | Select and compose techniques from the complete 61-item catalog |
-| `fec-refactoring-functions` | Function decomposition, naming, variable, parameter-object, and phase refactorings |
-| `fec-refactoring-encapsulation` | Record, collection, primitive, class, delegate, and algorithm encapsulation refactorings |
-| `fec-refactoring-move-features` | Move functions/fields/statements, split loops, pipelines, and dead-code routing |
-| `fec-refactoring-data` | Variable/field and reference/value data refactorings |
-| `fec-refactoring-control` | Conditional decomposition, guards, polymorphic dispatch, special cases, assertions |
-| `fec-refactoring-api` | Query/modifier, parameter, flag, factory, command, and API-shape refactorings |
-| `fec-refactoring-inheritance` | Inheritance/delegation refactorings with composition-first frontend adaptations |
-| `fec-refactoring-validation` | Behavior-preservation contracts, coverage levels, verification ladder, proof verdicts |
-**Design UI** — activated for design-to-code, design systems, and visual polish:
-| Skill                         | Scope                                                                         |
-| ----------------------------- | ----------------------------------------------------------------------------- |
-| `fec-ui-design`               | Product-context UI direction, anti-generic design dials, media strategy, states, visual QA |
-| `fec-image-generation`        | System blueprints, process workflows, interactive live diagrams, HTML/SVG/PNG exports, image generation/editing, visual assets, and PNG QA |
-| `fec-drawio-studio`         | Editable draw.io / diagrams.net technical diagrams, XML/Mermaid/CSV URL handoff, shape lookup, auto-layout, code maps |
-| `fec-web-video-presentation` | Recordable 16:9 step-driven web presentations from articles, scripts, lessons, and demos |
-| `fec-tailwind-design-system`  | Tailwind tokens, theme extension, variants, class governance, dark mode       |
-| `fec-responsive-layout`       | Mobile-first layouts, container queries, data-dense responsive UI             |
-| `fec-motion-interaction`      | Context-aware motion intensity, page transitions, scroll animation, reduced motion |
-| `fec-implement-from-design`   | Build UI from design tools, screenshots, or section-level visual references   |
-| `fec-storybook-component-doc` | Storybook component docs, design-system presentation, isolated state previews |
-Technical diagram quality: `fec-image-generation` prefers local Mermaid for standard sequence/workflow diagrams and the draw.io workflow for editable architecture, with JSON/HTML fallback when tools are unavailable. Export a browser-measured manifest scaled to the PNG, run QA and inspect the final image. Preserve complete text, explicit layout and relationships; repair the source for at most two automatic rounds and report unresolved issues. Reproducible fixtures are in `skills/fec-image-generation/assets/quality-examples/`.
-[Review and technical diagram guide](docs/review-and-diagram-workflows.md).
-**Legacy migration** — activated during modernization work:
-| Skill                            | Scope                                                      |
-| -------------------------------- | ---------------------------------------------------------- |
-| `fec-legacy-web-standard`        | Standards for JS + jQuery + HTML maintenance               |
-| `fec-legacy-to-modern-migration` | Legacy frontend modernization, target-stack selection, phased workflow |
-**Project evolution** — activated when absorbing reference systems into project-native improvements:
-| Skill         | Scope                                                                  |
-| ------------- | ---------------------------------------------------------------------- |
-| `fec-alchemy` | Absorb reference system ideas through original, project-native redesign |
-**Maintenance docs** — activated during documentation upkeep:
-| Skill                           | Scope                                                                                  |
-| ------------------------------- | -------------------------------------------------------------------------------------- |
-| `fec-backend-requirements-handoff` | Frontend-to-backend handoff for UI data needs, actions, states, rules, and questions |
-| `fec-doc-sync`                  | Keep frontend docs in sync with code, config, scripts, routes, APIs, env, and deploy facts |
-| `fec-source-driven-development` | Verify version-sensitive frontend decisions against project facts and official sources |
-### Agents
-Agents are specialized sub-agents dispatched by the main assistant to handle a focused task. Each returns a structured report.
-| Agent                       | Focus                                                                      | Report                       |
-| --------------------------- | -------------------------------------------------------------------------- | ---------------------------- |
-| `fec-code-reviewer`         | React/Vue/Next/Nuxt, TS, styles, client-side security (confidence-based)   | `code-review-*.md`           |
-| `fec-typescript-reviewer`   | Type safety, async correctness, idiomatic patterns (report-only)           | `typescript-review-*.md`     |
-| `fec-security-reviewer`     | XSS, client secrets, dangerous DOM/APIs, CSP, dependency audit             | `security-review-*.md`       |
-| `fec-performance-optimizer` | Bundle size, render performance, network bottlenecks                       | `performance-review-*.md`    |
-| `fec-architect`             | Page splitting, component architecture, state flow, directory planning     | `architecture-proposal-*.md` |
-| `fec-test-planner`          | Risk-to-layer matrix: static, unit, component, E2E, visual, a11y, security | `test-plan-*.md`             |
-| `fec-debugger`              | Complex frontend diagnostics for build, runtime, UI, and API failures      | `debug-*.md`                 |
-| `fec-refactor-cleaner`      | Classify and safely remove unused code, exports, styles, routes, deps      | `refactor-clean-*.md`        |
-| `fec-refactoring-expert`   | Evidence-based behavior-preserving refactoring orchestration              | `refactoring/refactoring-*.md` |
-| `fec-e2e-runner`            | E2E authoring and runs (Playwright/Cypress), flaky quarantine, traces      | `e2e-summary-*.md`           |
-| `fec-doc-updater`           | Sync README, runtime docs, structure, capability tables, metadata          | —                            |
-| `fec-ui-checker`            | Visual issue debugging and design fidelity evaluation                      | `ui-fidelity-review-*.md`    |
-| `fec-figma-implementer`     | Precise UI implementation from Figma/Sketch/MasterGo/Pixso/墨刀 designs    | `design-implementation-*.md` |
-| `fec-design-token-mapper`   | Map design variables to project Design Tokens                              | `token-mapping-*.md`         |
-### Hooks (event-driven)
-Hooks run automatically on AI assistant events — no invocation needed.
-| Event                     | Behavior                                                       |
-| ------------------------- | -------------------------------------------------------------- |
-| `SessionStart`            | Clean Claude cache, then detect project framework and package manager |
-| `PreToolUse(Bash)`        | Block dangerous commands (`rm -rf`, force push, etc.)          |
-| `PostToolUse(Write/Edit)` | Auto-format modified files with Prettier                       |
-| `Stop`                    | Run available validation scripts once, report failures, and block only when configured |
-| `Notification`            | Cross-platform desktop notifications (macOS / Linux / Windows) |
-Stop validation is advisory by default: failures are reported without blocking the session. Set `FRONTEND_CRAFT_VALIDATION_MODE=blocking` to return a failure status. The hook uses `packageManager` from `package.json` when present, otherwise a single lockfile; conflicting lockfiles default to npm.
-### MCP integration
-Plug your AI assistant into design tools for design-to-code workflows with richer design context.
-| Service           | Capabilities                                         |
-| ----------------- | ---------------------------------------------------- |
-| **Figma**         | Read design context and variable definitions         |
-| **Figma Desktop** | Figma desktop client integration                     |
-| **Sketch**        | Read design selection screenshots                    |
-| **MasterGo**      | Read DSL structure, component hierarchy, styles      |
-| **Pixso**         | Local MCP: frame data, code snippets, image assets   |
-| **墨刀**          | Prototype data, design descriptions, HTML import     |
-| **摹客**          | Screenshot/annotation/exported-CSS workflow (no MCP) |
-### Project templates (`/fec-init`)
-Run `/fec-init` to scaffold a ready-to-use rules library and project config into `.claude/`:
-<details>
-<summary>Click to see all 20 template files</summary>
-| File                                     | Purpose                                                               |
-| ---------------------------------------- | --------------------------------------------------------------------- |
-| `CLAUDE.md`                              | Project description, commands, working principles, security           |
-| `settings.json`                          | Permission whitelist/blacklist, environment variables                 |
-| `rules/fec-vue.md`                       | Vue 3 component standards and anti-patterns                           |
-| `rules/fec-react.md`                     | React component standards and anti-patterns                           |
-| `rules/fec-design-system.md`             | Design system, tokens, accessibility                                  |
-| `rules/fec-testing.md`                   | Testing and validation rules                                          |
-| `rules/fec-git-conventions.md`           | Conventional Commits                                                  |
-| `rules/fec-i18n.md`                      | Internationalization copy standards                                   |
-| `rules/fec-performance.md`               | Frontend performance rules                                            |
-| `rules/fec-rendering-patterns.md`        | Rendering lifecycle, hydration, SSR/CSR, and update patterns          |
-| `rules/fec-responsive-design.md`         | Responsive layout, breakpoints, touch targets, and viewport behavior  |
-| `rules/fec-source-driven-development.md` | Source-driven decisions, official docs, version-sensitive assumptions |
-| `rules/fec-api-layer.md`                 | API layer typing and error handling                                   |
-| `rules/fec-state-management.md`          | State classification, strategy, anti-patterns                         |
-| `rules/fec-error-handling.md`            | Error layering, Error Boundary, fallback UI, reporting                |
-| `rules/fec-naming-conventions.md`        | Unified naming for files, components, variables, routes, API, CSS     |
-| `rules/fec-code-comments.md`             | When and how to write frontend comments                               |
-| `rules/fec-ci-cd.md`                     | CI/CD pipeline stages, GitHub Actions / GitLab CI, secrets            |
-| `rules/fec-refactoring.md`               | Refactoring constraints and feature-parity requirements               |
-| `rules/fec-agent-workflow.md`            | Agent collaboration boundaries and delegation                         |
-| `rules/fec-working-modes.md`             | Research, planning, development, review, finishing modes              |
-</details>
----
-## Configuration
-### Prerequisites
-- **Node.js 22+**
-- **npm, pnpm, or yarn**
-- **Git Bash or a compatible shell** (Windows only, when your AI runtime invokes shell-based commands)
-### MCP design-tool tokens
-Set the environment variable for whichever design tool your team uses:
-| Variable         | Tool                  | How to get                                            |
-| ---------------- | --------------------- | ----------------------------------------------------- |
-| `FIGMA_API_KEY`  | Figma / Figma Desktop | Figma account settings → Personal Access Tokens       |
-| `SKETCH_API_KEY` | Sketch                | Sketch developer settings                             |
-| `MG_MCP_TOKEN`   | MasterGo              | MasterGo account settings → Security → Generate Token |
-| `MODAO_TOKEN`    | 墨刀                  | 墨刀 AI feature page → access token                   |
-> **Pixso** uses a local MCP server — enable MCP in the Pixso client, no env var needed.
-> **摹客** has no MCP integration; works via screenshots and exported CSS.
-Add to your shell config for persistence:
-```bash
-# macOS / Linux — append to ~/.bashrc or ~/.zshrc
-export FIGMA_API_KEY="your-figma-api-key"
-export SKETCH_API_KEY="your-sketch-api-key"
-export MG_MCP_TOKEN="your-mastergo-token"
-export MODAO_TOKEN="your-modao-token"
-```
-```powershell
-# Windows — set as system environment variables, or in PowerShell:
-$env:FIGMA_API_KEY = "your-figma-api-key"
-$env:SKETCH_API_KEY = "your-sketch-api-key"
-$env:MG_MCP_TOKEN = "your-mastergo-token"
-$env:MODAO_TOKEN = "your-modao-token"
-```
----
-## Reports
-Every review, analysis, and evaluation writes a timestamped Markdown report to `reports/`. These serve as an audit trail and a handoff artifact for PRs.
-<details>
-<summary>Click to see all 19 report types</summary>
-| Report type            | Filename pattern                             | Produced by                                                         |
-| ---------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
-| Code review            | `code-review-YYYY-MM-DD-HHmmss.md`           | `/fec-review`, `fec-code-review`, `fec-code-reviewer`               |
-| Debug diagnostics      | `debug-YYYY-MM-DD-HHmmss.md`                 | `/fec-debug`, `fec-debug-framework`, `fec-debugger`                 |
-| TypeScript / JS review | `typescript-review-YYYY-MM-DD-HHmmss.md`     | `fec-typescript-reviewer`                                           |
-| Security review        | `security-review-YYYY-MM-DD-HHmmss.md`       | `fec-security-review`, `fec-security-reviewer`                      |
-| Accessibility          | `accessibility-review-YYYY-MM-DD-HHmmss.md`  | `fec-accessibility-check`                                           |
-| Performance            | `performance-review-YYYY-MM-DD-HHmmss.md`    | `fec-performance-optimizer`                                         |
-| Architecture           | `architecture-proposal-YYYY-MM-DD-HHmmss.md` | `fec-architect`                                                     |
-| Design fidelity        | `ui-fidelity-review-YYYY-MM-DD-HHmmss.md`    | `fec-ui-checker`                                                    |
-| Design implementation  | `design-implementation-YYYY-MM-DD-HHmmss.md` | `fec-figma-implementer`                                             |
-| Token mapping          | `token-mapping-YYYY-MM-DD-HHmmss.md`         | `fec-design-token-mapper`                                           |
-| Design plan            | `design-plan-YYYY-MM-DD-HHmmss.md`           | `fec-implement-from-design`                                         |
-| Test plan              | `test-plan-YYYY-MM-DD-HHmmss.md`             | `/fec-plan`, `fec-testing-strategy`, `fec-test-planner`             |
-| Validation fix         | `validation-fix-YYYY-MM-DD-HHmmss.md`        | `fec-validation-fix`                                                |
-| Refactor clean         | `refactor-clean-YYYY-MM-DD-HHmmss.md`        | `/fec-refactor-clean`, `fec-refactor-clean`, `fec-refactor-cleaner` |
-| Smell diagnosis       | `refactoring/smell-YYYY-MM-DD-HHmmss.md`     | `/fec-smell`, `fec-code-smells`                                  |
-| Refactoring plan      | `refactoring/plan-YYYY-MM-DD-HHmmss.md`      | `/fec-refactor-plan`, `fec-refactoring`                           |
-| Refactoring execution | `refactoring/refactoring-YYYY-MM-DD-HHmmss.md` | `/fec-refactor`, `fec-refactoring`, `fec-refactoring-expert`    |
-| E2E run summary        | `e2e-summary-YYYY-MM-DD-HHmmss.md`           | `fec-e2e-runner` (optional)                                         |
-| Migration plan         | `migration-plan-YYYY-MM-DD-HHmmss.md`        | `fec-legacy-to-modern-migration`                                    |
-</details>
-> **Tip:** add `reports/` to `.gitignore` to keep the auto-generated reports out of version control — or commit them to preserve a team review history.
----
-## Update and Remove
-`fec` is the short command for `frontend-craft`. If you have not installed the global `fec` command, use the same arguments with `npx @bovinphang/frontend-craft@latest`, for example `npx @bovinphang/frontend-craft@latest update`.
-### Update
-```bash
-fec update                         # Update all discovered CLI-managed installs
-fec update <runtime> --local        # Update one local CLI-managed install
-fec update <runtime> --global       # Update one global CLI-managed install
-fec upgrade <runtime> --global      # `upgrade` is an alias for `update`
-```
-### Remove
-```bash
-fec uninstall                       # Remove all discovered CLI-managed installs
-fec remove                          # `remove` is an alias for `uninstall`
-fec uninstall <runtime>             # Remove a specific runtime install
-fec remove <runtime>                # Same removal through the alias
-fec uninstall --global              # Remove discovered global installs only
-fec remove --local                  # Remove discovered local installs only
-fec uninstall <runtime> --dry-run   # Preview removals
-fec uninstall <runtime> --force     # Remove modified managed files too
-```
-The CLI writes `frontend-craft.manifest.json` into the runtime directory. `update` discovers those manifests automatically when no runtime is provided and **skips files you’ve modified locally**, so customizations survive updates.
-`uninstall`/`remove` only deletes files recorded in the manifest. It skips modified files by default; add `--force` only when you want to remove modified managed files too. `--force` does not override a Claude Code Marketplace install.
-For **Claude Code Marketplace** or **submodule** installs, see [docs/runtimes/claude.md](docs/runtimes/claude.md) · [简体中文](docs/runtimes/claude.zh-CN.md). `/fec-init` only initializes project config; it is not a second plugin install.
----
-## Legacy Skills CLI
-If your team already uses the standalone [Skills CLI](https://skills.sh/docs/cli), it can still install just the workflow skill packages from [`skills/`](skills/):
-```bash
-npx skills add bovinphang/frontend-craft   # follow prompts, or add -g for global
-npx skills update                          # update to latest
-npx skills check                           # preview available updates
-```
-| CLI                  | Installs                                                            |
-| -------------------- | ------------------------------------------------------------------- |
-| `npx @bovinphang/frontend-craft` | Skills + runtime-specific agents, commands, hooks, rules, templates |
-| `npx skills`         | Skills only (for existing Skills CLI workflows)                     |
-To disable telemetry: `DISABLE_TELEMETRY=1`. Details: [skills.sh CLI docs](https://skills.sh/docs/cli).
----
-## Community
-- [Contributing Guide](CONTRIBUTING.md) — development setup, PR checklist, localization policy ([简体中文](CONTRIBUTING.zh-CN.md))
-- [Security Policy](SECURITY.md) — private vulnerability reporting ([简体中文](SECURITY.zh-CN.md))
-- [Code of Conduct](CODE_OF_CONDUCT.md) — community standards ([简体中文](CODE_OF_CONDUCT.zh-CN.md))
-- [Changelog](CHANGELOG.md) — release notes ([简体中文](CHANGELOG.zh-CN.md))
-- [Project structure](docs/project-structure.md) — full directory layout and file responsibilities ([简体中文](docs/zh-CN/project-structure.md))
----
-## License
-[MIT](LICENSE) — use freely, modify as needed, contribute back if you can.
----
-<div align="center">
-**If frontend-craft helps your team ship better code, [give it a Star](https://github.com/bovinphang/frontend-craft).**
-</div>
+<div align="center">
+> Release status (2026-11-09): craft-common 2.0.0 is published on npm. Frontend 3.0.0 and backend 1.0.0 remain unreleased; product versions are unchanged. Earlier preparation notes describe the pre-publication state.
+<img src="assets/brand/frontend-craft.png" alt="frontend-craft logo" width="200" />
+# frontend-craft
+### One toolkit. Every AI coding assistant. Production-grade frontend standards.
+[![Stars](https://img.shields.io/github/stars/bovinphang/frontend-craft?style=flat)](https://github.com/bovinphang/frontend-craft/stargazers)
+[![CI](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml/badge.svg)](https://github.com/bovinphang/frontend-craft/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@bovinphang/frontend-craft)](https://www.npmjs.com/package/@bovinphang/frontend-craft)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Node](https://img.shields.io/badge/Node.js-22+-5FA04E?logo=node.js&logoColor=white)
+![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
+![React](https://img.shields.io/badge/-React-61DAFB?logo=react&logoColor=black)
+![Vue](https://img.shields.io/badge/-Vue-4FC08D?logo=vue.js&logoColor=white)
+![Figma](https://img.shields.io/badge/-Figma-F24E1E?logo=figma&logoColor=white)
+**🌐 Language / 语言 / 語言 / 言語 / 언어**
+[**English**](README.md) · [简体中文](README.zh-CN.md) · [繁體中文](docs/zh-TW/README.md) · [日本語](docs/ja-JP/README.md) · [한국어](docs/ko-KR/README.md)
+</div>
+[Runtime compatibility and upgrade notes](docs/runtimes/compatibility.md)
+---
+`frontend-craft` is a **universal frontend plugin** that brings the same opinionated engineering standards to all **15 AI coding assistants** listed below:
+`claude` `codex` `cursor` `windsurf` `opencode`
+`kilo` `gemini` `copilot` `antigravity` `augment`
+`trae` `codebuddy` `cline` `openclaw` `qoder`
+Per-runtime paths and caveats live in [`docs/runtimes/`](docs/runtimes/).
+It bundles **14 specialized agents**, **74 auto-activated skills**, **11 slash commands**, **5 event-driven hooks**, **MCP integrations** for 6 design-tool endpoints, and a complete **rules library** into a single installable package. Run one command, and every AI session on your team writes React, Vue, Next.js, or Nuxt the same way — typed, accessible, secure, and consistent.
+---
+## Why frontend-craft?
+| Problem                                                              | What frontend-craft does                                                                       |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| AI assistants write inconsistent, untyped, or insecure frontend code | **74 skills** encode team standards — auto-activated when the assistant touches matching files |
+| Each AI tool has its own plugin format                               | **One CLI** installs the same rules, agents, and hooks into 15 runtimes                        |
+| Design-to-code handoff is lossy                                      | **MCP integrations** bring in richer context from Figma, Figma Desktop, Sketch, MasterGo, Pixso, and 墨刀 |
+| Reviews are ad-hoc and shallow                                       | **14 agents** produce graded reports: code, security, a11y, performance, TS, UI fidelity       |
+| No one remembers to run lint/tests                                   | **Event-driven hooks** validate on save and session end — automatically                        |
+| New projects start from scratch every time                           | **`/fec-init`** scaffolds CLAUDE.md, rules, and settings in seconds                            |
+---
+## Install
+Requires **Node.js 22+**. Works on **Windows, macOS, and Linux**.
+### Option 1 - Install the fec CLI globally (recommended)
+```bash
+# 1. Install the fec command globally
+npm install -g @bovinphang/frontend-craft@latest
+# 2. Go to your frontend project
+cd your-project
+# 3. Choose the AI runtime(s) interactively
+fec setup
+# 4. Connect the current project
+fec setup codex
+fec setup claude
+fec setup all
+# 5. Connect globally, available across all projects
+fec setup codex --global
+fec setup claude --global
+fec setup all --global
+# 6. Preview / query
+fec runtime install --all --dry-run --global
+fec list
+```
+`npm install -g` only installs the `fec` terminal command. `fec setup` is the terminal CLI command for connecting frontend-craft to a project; it is not the in-assistant `/fec-init` slash command. In an interactive terminal, running only `fec setup` asks you to choose runtimes. `fec setup <runtime>` and `fec setup all` connect frontend-craft to the current project by default. Only pass `--global` when you want to connect frontend-craft to the selected AI tool's global config directory so it is available across projects.
+### Option 2 — Temporary npx run (no global fec command)
+```bash
+# 1. Interactive wizard
+npx @bovinphang/frontend-craft@latest
+# 2. Connect the current project
+npx @bovinphang/frontend-craft@latest runtime install --local codex
+npx @bovinphang/frontend-craft@latest runtime install --local claude
+npx @bovinphang/frontend-craft@latest runtime install --all --local
+# 3. Connect globally, available across all projects
+npx @bovinphang/frontend-craft@latest runtime install --global codex
+npx @bovinphang/frontend-craft@latest runtime install --global claude
+npx @bovinphang/frontend-craft@latest runtime install --all --global
+# 4. Preview / query
+npx @bovinphang/frontend-craft@latest runtime install --all --dry-run --global
+npx @bovinphang/frontend-craft@latest list
+```
+Use `npx` when you do not want to install a global `fec` command. Without arguments, it opens the interactive wizard: choose one or more runtimes, then choose whether to connect globally or into the current project. For scripted all-runtime installs, use `install --all --local` or `install --all --global`; do not write `install all`. For CI / scripts, always pass `--global` / `-g` or `--local` / `-l`; in non-TTY environments without an explicit location, the CLI defaults to `claude --global`.
+### Option 3 — Claude Code Marketplace
+For Claude Code users, **Claude Code Marketplace** is the preferred single-source install. Use the CLI for Claude only when you need cross-runtime installs, scripted/offline file copies, or non-Marketplace environments.
+If Marketplace is already installed, the CLI will not install or update a second Claude copy, even with `--force`; update through Claude Code Marketplace instead. If a CLI-managed Claude install already exists in the other scope, interactive terminals ask whether to keep that source updated or uninstall it before switching. Non-interactive terminals stop and print the exact `runtime update`, `runtime uninstall`, and `runtime install` commands to run.
+Full Claude-specific steps are in [docs/runtimes/claude.md](docs/runtimes/claude.md) · [简体中文](docs/runtimes/claude.zh-CN.md).
+---
+## Quick start
+Once installed, you have a full frontend engineering toolkit available in every AI session:
+```text
+You: "Review my recent changes"
+→ The fec-code-reviewer agent is dispatched, produces reports/code-review-*.md
+You: "/fec-review"
+→ Runs a structured review across architecture, types, rendering, styles, a11y
+You: "Implement the checkout page from this Figma link"
+→ The fec-figma-implementer agent reads the design via MCP, emits components and a report
+You: "/fec-scaffold dashboard feature"
+→ Creates a page / feature / component directory tree following project conventions
+You: "/fec-refactor-clean"
+→ Classifies and safely removes dead code, unused exports, styles, and deps
+You: "/fec-refactor src/features/compose"
+→ Diagnoses structural smells, builds a small-step plan, refactors one behavior-preserving step at a time, and validates every step
+```
+All slash commands below are shown for **Claude Code**; other runtimes expose the same capabilities through their own command systems (see [`docs/runtimes/`](docs/runtimes/)).
+---
+## Example prompts
+For a complete scenario-based prompt library, see [docs/example-prompts.md](docs/example-prompts.md).
+```text
+You: "Review my recent changes before merge. Focus on architecture, type safety, rendering behavior, styles, accessibility, and missing tests."
+You: "Before coding, plan the account billing feature: route structure, component boundaries, data flow, state ownership, validation flow, and rollout risks."
+You: "Build a multi-step registration form; choose the right form and schema validation approach for this project, with file upload, conditional fields, async validation, and accessible errors."
+You: "Implement the UI from Figma node 123:456. Use existing design tokens and components, match spacing and responsive states, and document assumptions."
+You: "`/fec-refactor-clean` Clean up dead code in this module."
+You: "`/fec-smell` Diagnose structural smells in this module without editing."
+You: "`/fec-refactor-plan` Build a behavior-preserving small-step refactoring plan."
+You: "`/fec-refactor` Refactor this module without changing observable behavior."
+```
+---
+## What’s inside
+### Commands
+Slash commands are the primary entry points for structured workflows. Most produce a timestamped Markdown report under `reports/`.
+| Command               | Purpose                                                                | Report                                           |
+| --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
+| `/fec-init`           | Initialize project templates (CLAUDE.md, rules, settings)              | —                                                |
+| `/fec-review`         | Review the full project by default; explicit file/directory or change scope | `code-review-*.md`                               |
+| `/fec-scaffold`       | Create page / feature / component boilerplate by convention            | —                                                |
+| `/fec-plan`           | Unified planning: implementation architecture or test strategy         | `architecture-proposal-*.md` or `test-plan-*.md` |
+| `/fec-tdd`            | Red → green → refactor loop for frontend TDD                           | —                                                |
+| `/fec-debug`          | Diagnose and fix frontend issues: build, runtime, UI, and API failures | `debug-*.md`                                     |
+| `/fec-refactor-clean` | Classify and safely remove dead code, unused exports, styles, and deps | `refactor-clean-*.md`                            |
+| `/fec-smell`          | Diagnose code smells with evidence; do not edit business code             | `refactoring/smell-*.md`                       |
+| `/fec-refactor-plan`  | Build an ordered behavior-preserving refactoring plan                      | `refactoring/plan-*.md`                        |
+| `/fec-refactor`       | Execute one validated behavior-preserving refactoring step at a time       | `refactoring/refactoring-*.md`                 |
+| `/fec-doc-sync`       | Sync READMEs, docs, env notes, scripts, API/route notes, and deploy docs | —                                                |
+### Review scope
+`/fec-review`, the code/TypeScript/security review agents, and their review skills use three modes:
+- **Change review:** explicitly request recent/current/staged changes, a PR or a commit, or use an established change context. With no changes, report that there is nothing to review; do not automatically review recent commits.
+- **Targeted review:** specify a file or directory to review existing code, including unchanged code, without requiring a Git diff.
+- **Project review (default):** with no scope or change context, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review by module.
+A file/directory request reviews its full contents; add "recent changes" to review only its diff. Bare `/fec-review` reviews the project even when changes exist. State mode and scope before review. Automatic review after edits must pass the current change scope explicitly.
+Examples: `/fec-review`,`/fec-review review recent changes`,  `/fec-review review src/components/Button.tsx`, `/fec-review review src/features/`, and `/fec-review review the entire project`. These are natural-language instructions, not CLI flags. Explicit scope takes precedence over the default.
+Dependency directories, build outputs, caches, generated files and third-party code are excluded by default. Reports record the mode, target scope, reviewed and unreviewed files/modules, exclusions, completion status and verification results. Limited coverage is marked partial; reading callers or running project-wide lint/typecheck does not establish manual review coverage. Change reviews retain merge recommendations; targeted/project reviews assess risk within reviewed scope. The frontend review does not replace a backend audit, and reviewers do not edit business code unless repairs are requested.
+### Skills (auto-activated)
+Skills are workflow definitions that activate automatically based on file patterns, frameworks, or task context. They encode review dimensions, output conventions, and report formats.
+The skills below are grouped by use case so you can quickly find project standards, implementation, testing, review, design, migration, project evolution, and documentation workflows.
+**Project standards** — conventions enforced whenever matching frameworks are detected:
+| Skill                           | Scope                                                                 |
+| ------------------------------- | --------------------------------------------------------------------- |
+| `fec-react-project-standard`    | React + TypeScript (structure, components, routing, state, API layer) |
+| `fec-vue3-project-standard`     | Vue 3 + TypeScript (structure, components, routing, Pinia, API layer) |
+| `fec-nextjs-project-standard`   | Next.js 14+ App Router, SSR/SSG, streaming, metadata                  |
+| `fec-nuxt-project-standard`     | Nuxt 3 SSR/SSG, composables, data fetching, middleware                |
+| `fec-vite-project-standard`     | Vite config, env safety, HMR, dev proxy, build optimization           |
+| `fec-monorepo-project-standard` | pnpm workspace, Turborepo, Nx structure and task orchestration        |
+| `cc-typescript-project-standard`   | TypeScript config, public API types, declarations, DTOs, generics             |
+**Implementation capabilities** — activated when building specific frontend behavior:
+| Skill                     | Scope                                                                     |
+| ------------------------- | ------------------------------------------------------------------------- |
+| `fec-data-fetching`       | Server-state fetching, caching, invalidation, SSR, infinite loading       |
+| `fec-api-integration`     | Typed API clients, auth refresh, uploads, realtime integration            |
+| `fec-state-management`    | State ownership, store selection, URL state, server/form/local boundaries |
+| `fec-form-handling`       | Framework-aware forms, schema validation, dynamic fields, uploads         |
+| `fec-browser-storage`     | localStorage / sessionStorage / IndexedDB / Cookies selection             |
+| `fec-route-protection`    | Auth and permission routes for React Router, Next.js, Vue Router, Nuxt    |
+| `fec-pwa-implementation`  | Manifest, service worker, offline cache, install prompts                  |
+| `fec-web-workers`         | Web Worker integration, transferables, Comlink, worker pools              |
+| `fec-canvas-threejs`      | Canvas 2D, Three.js, React Three Fiber, WebGL                             |
+| `fec-svg-animation`       | CSS / Framer Motion / GSAP SVG animation with reduced-motion              |
+| `fec-list-virtualization` | Framework-aware list virtualization, measurement, grids, infinite scroll  |
+**Testing** — activated when planning or authoring frontend test coverage:
+| Skill                   | Scope                                                                    |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `fec-testing-strategy`  | Layer selection across static, unit, component, integration, E2E, visual |
+| `fec-component-testing` | React Testing Library / Vue Test Utils with regression scenarios         |
+| `fec-e2e-testing`       | Playwright / Cypress E2E with Page Object and CI integration             |
+| `fec-tdd-workflow`      | Test-first frontend implementation with red-green-refactor               |
+**Review & quality** — activated during review, validation, or cleanup workflows:
+| Skill                          | Scope                                                                         |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| `fec-code-review`              | Correctness, maintainability, types, rendering, and verification review        |
+| `fec-debug-framework`          | Systematic diagnostics for build, runtime, UI, and API/data failures          |
+| `fec-security-review`          | Browser-side XSS, CSRF, token exposure, unsafe DOM, and third-party risks     |
+| `fec-accessibility-check`      | WCAG 2.2, keyboard, focus, touch, and screen-reader behavior                  |
+| `fec-dependency-upgrade`       | Dependency upgrades, lockfile review, CVE remediation, migration verification |
+| `fec-validation-fix`           | Run and repair lint, type-check, test, build in one pass                      |
+| `fec-performance-optimization` | Core Web Vitals, bundle, rendering, memory, network, and budget reviews       |
+| `fec-refactor-clean`           | Safe dead-code, unused export, style, route, dependency cleanup               |
+**Refactoring** — activated for evidence-based, behavior-preserving structural improvement:
+| Skill | Purpose |
+| --- | --- |
+| `fec-refactoring` | Orchestrate classification, baseline, safety, small-step execution, rollback, and proof |
+| `fec-code-smells` | Diagnose the 24 canonical code smells with evidence and false-positive checks |
+| `fec-refactoring-catalog` | Select and compose techniques from the complete 61-item catalog |
+| `fec-refactoring-functions` | Function decomposition, naming, variable, parameter-object, and phase refactorings |
+| `fec-refactoring-encapsulation` | Record, collection, primitive, class, delegate, and algorithm encapsulation refactorings |
+| `fec-refactoring-move-features` | Move functions/fields/statements, split loops, pipelines, and dead-code routing |
+| `fec-refactoring-data` | Variable/field and reference/value data refactorings |
+| `fec-refactoring-control` | Conditional decomposition, guards, polymorphic dispatch, special cases, assertions |
+| `fec-refactoring-api` | Query/modifier, parameter, flag, factory, command, and API-shape refactorings |
+| `fec-refactoring-inheritance` | Inheritance/delegation refactorings with composition-first frontend adaptations |
+| `fec-refactoring-validation` | Behavior-preservation contracts, coverage levels, verification ladder, proof verdicts |
+**Design UI** — activated for design-to-code, design systems, and visual polish:
+| Skill                         | Scope                                                                         |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| `fec-ui-design`               | Product-context UI direction, anti-generic design dials, media strategy, states, visual QA |
+| `fec-image-generation`        | UI, product and brand image generation/editing with shared PNG QA |
+| `cc-drawio-studio`         | Editable draw.io / diagrams.net technical diagrams, XML/Mermaid/CSV URL handoff, shape lookup, auto-layout, code maps |
+| `fec-web-video-presentation` | Recordable 16:9 step-driven web presentations from articles, scripts, lessons, and demos |
+| `fec-tailwind-design-system`  | Tailwind tokens, theme extension, variants, class governance, dark mode       |
+| `fec-responsive-layout`       | Mobile-first layouts, container queries, data-dense responsive UI             |
+| `fec-motion-interaction`      | Context-aware motion intensity, page transitions, scroll animation, reduced motion |
+| `fec-implement-from-design`   | Build UI from design tools, screenshots, or section-level visual references   |
+| `fec-storybook-component-doc` | Storybook component docs, design-system presentation, isolated state previews |
+Technical diagram quality: `cc-technical-diagrams` prefers local Mermaid for standard sequence/workflow diagrams and the draw.io workflow for editable architecture, with JSON/HTML fallback when tools are unavailable. Export a browser-measured manifest scaled to the PNG, run QA and inspect the final image. Preserve complete text, explicit layout and relationships; repair the source for at most two automatic rounds and report unresolved issues. Reproducible fixtures are in `skills/cc-technical-diagrams/assets/quality-examples/`.
+[Review and technical diagram guide](docs/review-and-diagram-workflows.md).
+**Legacy migration** — activated during modernization work:
+| Skill                            | Scope                                                      |
+| -------------------------------- | ---------------------------------------------------------- |
+| `fec-legacy-web-standard`        | Standards for JS + jQuery + HTML maintenance               |
+| `fec-legacy-to-modern-migration` | Legacy frontend modernization, target-stack selection, phased workflow |
+**Project evolution** — activated when absorbing reference systems into project-native improvements:
+| Skill         | Scope                                                                  |
+| ------------- | ---------------------------------------------------------------------- |
+| `fec-alchemy` | Absorb reference system ideas through original, project-native redesign |
+**Maintenance docs** — activated during documentation upkeep:
+| Skill                           | Scope                                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `fec-backend-requirements-handoff` | Frontend-to-backend handoff for UI data needs, actions, states, rules, and questions |
+| `fec-doc-sync`                  | Keep frontend docs in sync with code, config, scripts, routes, APIs, env, and deploy facts |
+| `cc-source-driven-development` | Verify version-sensitive frontend decisions against project facts and official sources |
+### Agents
+Agents are specialized sub-agents dispatched by the main assistant to handle a focused task. Each returns a structured report.
+| Agent                       | Focus                                                                      | Report                       |
+| --------------------------- | -------------------------------------------------------------------------- | ---------------------------- |
+| `fec-code-reviewer`         | React/Vue/Next/Nuxt, TS, styles, client-side security (confidence-based)   | `code-review-*.md`           |
+| `fec-typescript-reviewer`   | Type safety, async correctness, idiomatic patterns (report-only)           | `typescript-review-*.md`     |
+| `fec-security-reviewer`     | XSS, client secrets, dangerous DOM/APIs, CSP, dependency audit             | `security-review-*.md`       |
+| `fec-performance-optimizer` | Bundle size, render performance, network bottlenecks                       | `performance-review-*.md`    |
+| `fec-architect`             | Page splitting, component architecture, state flow, directory planning     | `architecture-proposal-*.md` |
+| `fec-test-planner`          | Risk-to-layer matrix: static, unit, component, E2E, visual, a11y, security | `test-plan-*.md`             |
+| `fec-debugger`              | Complex frontend diagnostics for build, runtime, UI, and API failures      | `debug-*.md`                 |
+| `fec-refactor-cleaner`      | Classify and safely remove unused code, exports, styles, routes, deps      | `refactor-clean-*.md`        |
+| `fec-refactoring-expert`   | Evidence-based behavior-preserving refactoring orchestration              | `refactoring/refactoring-*.md` |
+| `fec-e2e-runner`            | E2E authoring and runs (Playwright/Cypress), flaky quarantine, traces      | `e2e-summary-*.md`           |
+| `fec-doc-updater`           | Sync README, runtime docs, structure, capability tables, metadata          | —                            |
+| `fec-ui-checker`            | Visual issue debugging and design fidelity evaluation                      | `ui-fidelity-review-*.md`    |
+| `fec-figma-implementer`     | Precise UI implementation from Figma/Sketch/MasterGo/Pixso/墨刀 designs    | `design-implementation-*.md` |
+| `fec-design-token-mapper`   | Map design variables to project Design Tokens                              | `token-mapping-*.md`         |
+### Hooks (event-driven)
+Hooks run automatically on AI assistant events — no invocation needed.
+| Event                     | Behavior                                                       |
+| ------------------------- | -------------------------------------------------------------- |
+| `SessionStart`            | Clean Claude cache, then detect project framework and package manager |
+| `PreToolUse(Bash)`        | Block dangerous commands (`rm -rf`, force push, etc.)          |
+| `PostToolUse(Write/Edit)` | Auto-format modified files with Prettier                       |
+| `Stop`                    | Run available validation scripts once, report failures, and block only when configured |
+| `Notification`            | Cross-platform desktop notifications (macOS / Linux / Windows) |
+Stop validation is advisory by default: failures are reported without blocking the session. Set `FRONTEND_CRAFT_VALIDATION_MODE=blocking` to return a failure status. The hook uses `packageManager` from `package.json` when present, otherwise a single lockfile; conflicting lockfiles default to npm.
+### MCP integration
+Plug your AI assistant into design tools for design-to-code workflows with richer design context.
+| Service           | Capabilities                                         |
+| ----------------- | ---------------------------------------------------- |
+| **Figma**         | Read design context and variable definitions         |
+| **Figma Desktop** | Figma desktop client integration                     |
+| **Sketch**        | Read design selection screenshots                    |
+| **MasterGo**      | Read DSL structure, component hierarchy, styles      |
+| **Pixso**         | Local MCP: frame data, code snippets, image assets   |
+| **墨刀**          | Prototype data, design descriptions, HTML import     |
+| **摹客**          | Screenshot/annotation/exported-CSS workflow (no MCP) |
+### Project templates (`/fec-init`)
+Run `/fec-init` to scaffold a ready-to-use rules library and project config into `.claude/`:
+<details>
+<summary>Click to see all 20 template files</summary>
+| File                                     | Purpose                                                               |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| `CLAUDE.md`                              | Project description, commands, working principles, security           |
+| `settings.json`                          | Permission whitelist/blacklist, environment variables                 |
+| `rules/fec-vue.md`                       | Vue 3 component standards and anti-patterns                           |
+| `rules/fec-react.md`                     | React component standards and anti-patterns                           |
+| `rules/fec-design-system.md`             | Design system, tokens, accessibility                                  |
+| `rules/fec-testing.md`                   | Testing and validation rules                                          |
+| `rules/fec-git-conventions.md`           | Conventional Commits                                                  |
+| `rules/fec-i18n.md`                      | Internationalization copy standards                                   |
+| `rules/fec-performance.md`               | Frontend performance rules                                            |
+| `rules/fec-rendering-patterns.md`        | Rendering lifecycle, hydration, SSR/CSR, and update patterns          |
+| `rules/fec-responsive-design.md`         | Responsive layout, breakpoints, touch targets, and viewport behavior  |
+| `rules/fec-source-driven-development.md` | Source-driven decisions, official docs, version-sensitive assumptions |
+| `rules/fec-api-layer.md`                 | API layer typing and error handling                                   |
+| `rules/fec-state-management.md`          | State classification, strategy, anti-patterns                         |
+| `rules/fec-error-handling.md`            | Error layering, Error Boundary, fallback UI, reporting                |
+| `rules/fec-naming-conventions.md`        | Unified naming for files, components, variables, routes, API, CSS     |
+| `rules/fec-code-comments.md`             | When and how to write frontend comments                               |
+| `rules/fec-ci-cd.md`                     | CI/CD pipeline stages, GitHub Actions / GitLab CI, secrets            |
+| `rules/fec-refactoring.md`               | Refactoring constraints and feature-parity requirements               |
+| `rules/fec-agent-workflow.md`            | Agent collaboration boundaries and delegation                         |
+| `rules/fec-working-modes.md`             | Research, planning, development, review, finishing modes              |
+</details>
+---
+## Configuration
+### Prerequisites
+- **Node.js 22+**
+- **npm, pnpm, or yarn**
+- **Git Bash or a compatible shell** (Windows only, when your AI runtime invokes shell-based commands)
+### MCP design-tool tokens
+Set the environment variable for whichever design tool your team uses:
+| Variable         | Tool                  | How to get                                            |
+| ---------------- | --------------------- | ----------------------------------------------------- |
+| `FIGMA_API_KEY`  | Figma / Figma Desktop | Figma account settings → Personal Access Tokens       |
+| `SKETCH_API_KEY` | Sketch                | Sketch developer settings                             |
+| `MG_MCP_TOKEN`   | MasterGo              | MasterGo account settings → Security → Generate Token |
+| `MODAO_TOKEN`    | 墨刀                  | 墨刀 AI feature page → access token                   |
+> **Pixso** uses a local MCP server — enable MCP in the Pixso client, no env var needed.
+> **摹客** has no MCP integration; works via screenshots and exported CSS.
+Add to your shell config for persistence:
+```bash
+# macOS / Linux — append to ~/.bashrc or ~/.zshrc
+export FIGMA_API_KEY="your-figma-api-key"
+export SKETCH_API_KEY="your-sketch-api-key"
+export MG_MCP_TOKEN="your-mastergo-token"
+export MODAO_TOKEN="your-modao-token"
+```
+```powershell
+# Windows — set as system environment variables, or in PowerShell:
+$env:FIGMA_API_KEY = "your-figma-api-key"
+$env:SKETCH_API_KEY = "your-sketch-api-key"
+$env:MG_MCP_TOKEN = "your-mastergo-token"
+$env:MODAO_TOKEN = "your-modao-token"
+```
+---
+## Reports
+Every review, analysis, and evaluation writes a timestamped Markdown report to `reports/`. These serve as an audit trail and a handoff artifact for PRs.
+<details>
+<summary>Click to see all 19 report types</summary>
+| Report type            | Filename pattern                             | Produced by                                                         |
+| ---------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
+| Code review            | `code-review-YYYY-MM-DD-HHmmss.md`           | `/fec-review`, `fec-code-review`, `fec-code-reviewer`               |
+| Debug diagnostics      | `debug-YYYY-MM-DD-HHmmss.md`                 | `/fec-debug`, `fec-debug-framework`, `fec-debugger`                 |
+| TypeScript / JS review | `typescript-review-YYYY-MM-DD-HHmmss.md`     | `fec-typescript-reviewer`                                           |
+| Security review        | `security-review-YYYY-MM-DD-HHmmss.md`       | `fec-security-review`, `fec-security-reviewer`                      |
+| Accessibility          | `accessibility-review-YYYY-MM-DD-HHmmss.md`  | `fec-accessibility-check`                                           |
+| Performance            | `performance-review-YYYY-MM-DD-HHmmss.md`    | `fec-performance-optimizer`                                         |
+| Architecture           | `architecture-proposal-YYYY-MM-DD-HHmmss.md` | `fec-architect`                                                     |
+| Design fidelity        | `ui-fidelity-review-YYYY-MM-DD-HHmmss.md`    | `fec-ui-checker`                                                    |
+| Design implementation  | `design-implementation-YYYY-MM-DD-HHmmss.md` | `fec-figma-implementer`                                             |
+| Token mapping          | `token-mapping-YYYY-MM-DD-HHmmss.md`         | `fec-design-token-mapper`                                           |
+| Design plan            | `design-plan-YYYY-MM-DD-HHmmss.md`           | `fec-implement-from-design`                                         |
+| Test plan              | `test-plan-YYYY-MM-DD-HHmmss.md`             | `/fec-plan`, `fec-testing-strategy`, `fec-test-planner`             |
+| Validation fix         | `validation-fix-YYYY-MM-DD-HHmmss.md`        | `fec-validation-fix`                                                |
+| Refactor clean         | `refactor-clean-YYYY-MM-DD-HHmmss.md`        | `/fec-refactor-clean`, `fec-refactor-clean`, `fec-refactor-cleaner` |
+| Smell diagnosis       | `refactoring/smell-YYYY-MM-DD-HHmmss.md`     | `/fec-smell`, `fec-code-smells`                                  |
+| Refactoring plan      | `refactoring/plan-YYYY-MM-DD-HHmmss.md`      | `/fec-refactor-plan`, `fec-refactoring`                           |
+| Refactoring execution | `refactoring/refactoring-YYYY-MM-DD-HHmmss.md` | `/fec-refactor`, `fec-refactoring`, `fec-refactoring-expert`    |
+| E2E run summary        | `e2e-summary-YYYY-MM-DD-HHmmss.md`           | `fec-e2e-runner` (optional)                                         |
+| Migration plan         | `migration-plan-YYYY-MM-DD-HHmmss.md`        | `fec-legacy-to-modern-migration`                                    |
+</details>
+> **Tip:** add `reports/` to `.gitignore` to keep the auto-generated reports out of version control — or commit them to preserve a team review history.
+---
+## Update and Remove
+### CLI lifecycle (3.0)
+`fec update` (`upgrade`) upgrades an npm/pnpm global CLI to the original registry's `latest`, then starts the new CLI to refresh managed resources in the current project and user-global scope, even when already latest. Other projects and Marketplace installs are not scanned or managed. CLI upgrade failure stops refresh; independent resource failures are reported by phase without rolling back the CLI. Retry those resources with `fec runtime update`.
+`fec uninstall` (`remove`) removes only the global CLI by default. `--purge` first removes discovered managed resources while preserving user modifications; cleanup errors keep the CLI installed. A terminal prompts for confirmation; non-interactive runs require `--yes`. Self-management supports verified npm/pnpm global registry installs only; source links, project dependencies, unknown sources and pnpm groups shared with other packages are refused before changes. Use the original package manager manually for shared groups. `--dry-run` only previews; it never installs, deletes or starts the refresh process.
+```bash
+fec update
+fec uninstall --dry-run
+fec uninstall --purge --yes
+```
+Temporary npx runs never create a global CLI install and cannot uninstall the CLI. Top-level npx `update` refreshes resources only if its package version equals registry `latest`; otherwise use `npx @bovinphang/frontend-craft@latest runtime update`.
+| 2.x resource command | 3.0 replacement |
+| --- | --- |
+| `fec update [runtime] [options]` | `fec runtime update [runtime] [options]` |
+| `fec uninstall [runtime] [options]` | `fec runtime uninstall [runtime] [options]` |
+| `fec install [runtime] [options]` | `fec runtime install [runtime] [options]` |
+Top-level update/uninstall reject old runtime arguments and resource options such as `--global` before making changes. `setup` remains available; top-level `install` is a deprecated compatibility alias. `runtime upgrade/remove` alias `runtime update/uninstall`. Resource options remain available. `runtime update` uses only the currently running CLI package, without fetching a new package from the network.
+`fec` is the short command for `frontend-craft`. For resource operations without a global CLI, use `npx @bovinphang/frontend-craft@latest runtime update` (or `runtime install/uninstall`).
+### Resource update
+```bash
+fec runtime update                              # Update all discovered CLI-managed installs
+fec runtime update <runtime> --local            # Update one local CLI-managed install
+fec runtime update <runtime> --global           # Update one global CLI-managed install
+fec runtime upgrade <runtime> --global          # `upgrade` is an alias for `update`
+```
+### Resource removal
+```bash
+fec runtime uninstall                           # Remove all discovered CLI-managed installs
+fec runtime remove                              # `remove` is an alias for `uninstall`
+fec runtime uninstall <runtime>                 # Remove a specific runtime install
+fec runtime remove <runtime>                    # Same removal through the alias
+fec runtime uninstall --global                  # Remove discovered global installs only
+fec runtime remove --local                      # Remove discovered local installs only
+fec runtime uninstall <runtime> --dry-run       # Preview removals
+fec runtime uninstall <runtime> --force         # Remove modified managed files too
+```
+The CLI writes `frontend-craft.manifest.json` into the runtime directory. `runtime update` discovers those manifests automatically when no runtime is provided and **skips files you’ve modified locally**, so customizations survive updates.
+`runtime uninstall`/`runtime remove` only deletes files recorded in the manifest. It skips modified files by default; add `--force` only when you want to remove modified managed files too. `--force` does not override a Claude Code Marketplace install.
+For **Claude Code Marketplace** or **submodule** installs, see [docs/runtimes/claude.md](docs/runtimes/claude.md) · [简体中文](docs/runtimes/claude.zh-CN.md). `/fec-init` only initializes project config; it is not a second plugin install.
+---
+## Legacy Skills CLI
+If your team already uses the standalone [Skills CLI](https://skills.sh/docs/cli), it can still install just the workflow skill packages from [`skills/`](skills/):
+```bash
+npx skills add bovinphang/frontend-craft   # follow prompts, or add -g for global
+npx skills update                          # update to latest
+npx skills check                           # preview available updates
+```
+| CLI                  | Installs                                                            |
+| -------------------- | ------------------------------------------------------------------- |
+| `npx @bovinphang/frontend-craft` | Skills + runtime-specific agents, commands, hooks, rules, templates |
+| `npx skills`         | Skills only (for existing Skills CLI workflows)                     |
+To disable telemetry: `DISABLE_TELEMETRY=1`. Details: [skills.sh CLI docs](https://skills.sh/docs/cli).
+---
+## Community
+- [Contributing Guide](CONTRIBUTING.md) — development setup, PR checklist, localization policy ([简体中文](CONTRIBUTING.zh-CN.md))
+- [Security Policy](SECURITY.md) — private vulnerability reporting ([简体中文](SECURITY.zh-CN.md))
+- [Code of Conduct](CODE_OF_CONDUCT.md) — community standards ([简体中文](CODE_OF_CONDUCT.zh-CN.md))
+- [Changelog](CHANGELOG.md) — release notes ([简体中文](CHANGELOG.zh-CN.md))
+- [Project structure](docs/project-structure.md) — full directory layout and file responsibilities ([简体中文](docs/zh-CN/project-structure.md))
+---
+## License
+[MIT](LICENSE) — use freely, modify as needed, contribute back if you can.
+---
+<div align="center">
+**If frontend-craft helps your team ship better code, [give it a Star](https://github.com/bovinphang/frontend-craft).**
+</div>
+## Craft Common in 3.0
+Version 3.0 is unreleased. It delivers 53 frontend entries and 21 shared entries (74 skills total) from the pinned craft-common dependency, without a third manual plugin install. Common source is maintained only in craft-common.
+- `cc-drawio-studio`
+- `cc-technical-diagrams`
+- `cc-source-driven-development`
+- `cc-doc-sync-core`
+- `cc-debug-methodology`
+- `cc-refactoring-core`
+- `cc-tdd-methodology`
+Run `fec runtime check-migration codex --local --json` and read [migration guide](docs/common-migration.md).
+CLI installation manages shared ownership and uninstall references. Native channels guarantee complete single-product payloads; native dual-product deduplication is not promised.
+Pinned common source: `@bovinphang/craft-common@2.0.0`. See [project structure and maintenance boundaries](docs/project-structure.md) and [contributor checks](CONTRIBUTING.md).
+## Mixed-project inspection
+`fec project inspect . --task-path apps/desktop/src-tauri/src/lib.rs --task-kind ipc --json` reads bounded manifest evidence and recommends only delivered capabilities. Roles (UI, desktop core, native library, service, CLI), languages and frameworks are separate dimensions. It never runs build scripts or installs tools. Shared language entries include independent C and C++ standards; Tauri/Electron are common specialties. Next/React/Vue/Nuxt/Vite stay frontend specialties. No task argument means project-level candidates only.
+Common uses the final version number 2.0.0 and is prepared for publication; frontend 3.0.0 and backend 1.0.0 remain unreleased. Exit old common consumers with each old product CLI before installing matching product builds. Run `fec runtime check-migration [runtime] --local --json` first. Unknown or edited retired entries block installation. See [migration](docs/common-migration.md).
+<!-- engineering-practices-20261108 -->
+## Conditional engineering practices
+Eight existing frontend entries now connect shared principles to React/Vue lifecycle, API replay safety, query ownership, review evidence, testing, security and dependency compatibility. Read the entry's local engineering reference for conditions and exceptions. Both products still deliver all21 common entries; language capability is independent of UI, desktop, library or service role. Company guidance does not authorize a toolchain migration.
+The [React sample](skills/fec-react-project-standard/examples/engineering/README.md) uses real React/Testing Library/JSDOM to verify stale-result rejection and owned cleanup. Its locked dependencies are isolated. Repository maintenance: explicitly run `pnpm run verify:engineering -- --prepare`, then omit --prepare to reuse only matching preparation. This is a source-repository maintenance task, not a new installed CLI command. DOM simulation does not prove browser E2E, remote rollback or desktop GUI.
+Payment writes are not retried solely because of429/5xx/network errors: require a server replay contract, same intent/key and bounded budget, otherwise reconcile the uncertain result. Public clean installation still awaits common publication; [upgrade ownership rules](docs/common-migration.md) remain in force.
+Common 2.0.0 release preparation: [current unreleased changes](CHANGELOG.md#300---unreleased). Publish and verify common first; this step does not publish frontend 3.0.0.