Purpose

Use pnpm-workspace.yaml as the single source of truth for shared third-party dependency versions.

This skill follows the official pnpm catalogs model and the named-catalog grouping approach described by Anthony Fu. In Citado, prefer named catalogs over the default catalog because the catalog name carries architectural meaning during reviews.

Primary references

• Official pnpm catalogs documentation: https://pnpm.io/catalogs
• Official pnpm workspace configuration docs: https://pnpm.io/pnpm-workspace_yaml
• Anthony Fu, Categorize Your Dependencies: https://antfu.me/posts/categorize-deps

Core pnpm facts

• catalog creates the default catalog.
• catalogs creates named catalogs.
• catalog: is shorthand for the default catalog only.
• catalog:<name> references a named catalog.
• Catalog references can be used in dependencies, devDependencies, peerDependencies, optionalDependencies, and pnpm overrides.
• On pnpm publish and pnpm pack, pnpm replaces catalog: references with concrete versions.

Citado repo rules

• Prefer named catalogs only. Do not introduce the singular root catalog: style in this repo unless the user explicitly asks for it.
• Keep internal workspace packages on workspace:*. Do not move internal packages into catalogs.
• Preserve the current taxonomy unless there is a clear repeated need for a new category.
• When a dependency name appears in multiple Citado frontend/viewer packages, versions should usually be aligned through one catalog entry.
• Avoid one-off catalog groups. A new catalog should represent a stable semantic class, not a temporary cleanup batch.

Current taxonomy in this repo

Read pnpm-workspace.yaml first and preserve the existing group names unless the user requests a reorganization.

• frontend: React runtime, state, and frontend runtime foundations.
• ui: component libraries, icons, motion, drag-and-drop, and CSS/runtime UI helpers.
• viewer: concrete viewer engines and viewer runtime libraries.
• build: TypeScript, Vite, Tailwind build toolchain, and build-time plugins.
• tooling: local CLIs and developer tooling used by scripts or maintenance flows.
• types: @types/* and type-only support packages.
• lint: ESLint, Prettier, and lint rule ecosystems.
• test: test runners, browser test tooling, and DOM test environments.

Classification heuristics

Choose the catalog by why the package exists, not by whether it sits in dependencies or devDependencies.

• Put React ecosystem runtime packages in frontend.
• Put UI libraries and icon/component primitives in ui.
• Put format-specific engines like PDF or image viewers in viewer.
• Put bundlers, compilers, CSS build plugins, and type compilers in build.
• Put CLIs invoked by scripts, generators, or maintenance flows in tooling.
• Put @types/* in types.
• Put ESLint/Prettier/plugins/configs in lint.
• Put Vitest, Playwright, jsdom, and similar packages in test.

If a dependency does not fit an existing catalog, check whether it is:

• truly shared across multiple packages and worth a new category, or
• package-local and better left with a direct version for now.

Workflow

1. Read the current workspace state

• Read pnpm-workspace.yaml.
• Read each affected package.json.
• Identify repeated third-party dependency names and version drift.

2. Decide whether cataloging is appropriate

Catalog a dependency when at least one of these is true:

• the same package appears in multiple workspace manifests;
• version alignment across packages matters;
• the dependency belongs to a stable semantic group already modeled in the taxonomy;
• the review benefits from seeing category intent instead of raw semver in every manifest.

Keep a direct version when the package is package-local, unlikely to be shared, or still exploratory.

3. Update pnpm-workspace.yaml

• Add or edit the version under the correct named catalog.
• Keep YAML formatting stable.
• Preserve comments if present.
• Do not reorder unrelated sections unless necessary.

4. Replace manifest versions

Update affected manifests from explicit versions to catalog:<name>.

Examples:

{
  "dependencies": {
    "react": "catalog:frontend",
    "lucide-react": "catalog:ui"
  },
  "devDependencies": {
    "vite": "catalog:build",
    "vitest": "catalog:test"
  }
}

Keep dependencies vs devDependencies semantically correct. Catalogs centralize versions; they do not replace dependency-kind decisions.

5. Refresh lockfile

Prefer one of these:

• pnpm install --lockfile-only
• pnpm i

If private registry authentication or offline metadata blocks lockfile refresh, say so explicitly and report whether the lockfile still changed.

6. Verify affected packages

Use the real package-local checks after manifest changes.

• For packages/fe: pnpm run check
• For viewer packages: run each touched package's pnpm run check
• If only skills/docs changed, skip package checks unless the user also asked for dependency edits

Review checklist

Before finishing, verify all of the following:

• No internal workspace:* dependency was replaced with a catalog entry.
• Same shared dependency names no longer have conflicting version specs across affected packages.
• New catalog names, if any, are semantic and likely to stay useful.
• package.json still uses the right dependency section even after converting to catalog references.
• Lockfile state and any auth/cache blockers are clearly reported.

Output expectations

When using this skill, report results in this order:

1. Which catalogs were added or changed.
2. Which manifests were moved to catalog:<name>.
3. Whether versions are now aligned across the touched packages.
4. Lockfile status.
5. Verification commands run and whether they passed.

Examples

Example: moving a shared build tool

Input:

"把几个前端包里的 vite 和 typescript 统一到 pnpm-workspace.yaml"

Expected approach:

• Put vite and typescript under build.
• Replace raw versions in affected package.json files with catalog:build.
• Refresh lockfile.
• Run package-local checks.

Example: deciding against a new catalog

Input:

"这个单独只在一个包里用到的小工具要不要进 catalogs？"

Expected approach:

• Check whether the dependency is shared or likely to become shared.
• If not, keep it package-local and explain why a new catalog would add noise rather than clarity.