@bleedingdev/modern-js-create 3.2.0-ultramodern.6 → 3.2.0-ultramodern.7

package/template-workspace/.agents/skills/rspack-tracing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: rspack-tracing
+description: Comprehensive guide and toolkit for diagnosing Rspack build issues. Quickly identify where crashes/errors occur, or perform detailed performance profiling to resolve bottlenecks. Use when the user encounters build failures, slow builds, or wants to optimize Rspack performance.
+---
+
+# Rspack Tracing & Performance Profiling
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+1.  Diagnose why an Rspack build is slow.
+2.  Understand which plugins or loaders are taking the most time.
+3.  Analyze a user-provided Rspack trace file.
+4.  Guide a user to capture a performance profile.
+
+## Workflow
+
+### 1. Capture a Trace
+
+First, ask the user to run their build with tracing enabled.
+
+```bash
+# Set environment variables for logging to a file
+RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json pnpm build
+```
+
+This will generate a trace file in a timestamped directory like `.rspack-profile-{timestamp}-{pid}/trace.json`.
+
+See [references/tracing-guide.md](references/tracing-guide.md) for more details on configuration.
+
+### 2. Quick Diagnosis for Crashes/Errors
+
+If the user wants to identify **which stage a crash or error occurred in**, use `tail` to quickly view the last events without running the full analysis:
+
+```bash
+# Navigate to the generated profile directory
+cd .rspack-profile-*/
+
+# View the last 20 events to see where the build failed
+tail -n 20 trace.json
+```
+
+The last events will show the span names and targets where the build stopped, helping to quickly pinpoint the problematic stage, plugin, or loader.
+
+### 3. Full Performance Analysis
+
+For detailed performance profiling (not just crash diagnosis), ask the user to run the bundled analysis script on the generated trace file.
+
+```bash
+# Navigate to the generated profile directory
+cd .rspack-profile-*/
+
+# Run the analysis script
+node ${CLAUDE_PLUGIN_ROOT}/skills/tracing/scripts/analyze_trace.js trace.json
+```
+
+### 4. Interpret Results
+
+Use the output from the script to identify bottlenecks.
+Consult [references/bottlenecks.md](references/bottlenecks.md) to map span names to actionable fixes.
+
+### 5. Locate Slow Plugins
+
+Based on the "Top Slowest Hooks" from the analysis script:
+
+1.  **Identify the Hook**: Note the hook name (e.g., `hook:CompilationOptimizeChunks`).
+2.  **Inspect Configuration**: Read `rspack.config.js` or `rsbuild.config.ts`.
+3.  **Map Hook to Plugin**: Look for plugins and their sources that tap into that specific hook.
+4.  **Output**: Output the paths, lines and columns of the suspected plugin source code.
+
+## Common Scenarios & Quick Fixes
+
+- [Bottleneck Reference](references/bottlenecks.md): Mapping spans to concepts.
+- [Tracing Guide](references/tracing-guide.md): Detailed usage of `RSPACK_PROFILE`.

package/template-workspace/.agents/skills/rspack-tracing/references/bottlenecks.md

@@ -0,0 +1,47 @@
+# Understanding Rspack Performance Bottlenecks
+
+This reference maps internal Rspack tracing spans to high-level concepts to help you identify performance issues.
+
+## Core Compilation Phases
+
+| Span Name               | Description                                                    | Potential Bottlenecks                                                             |
+| :---------------------- | :------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
+| `tracing::profiling`    | The entire build process.                                      | Overall slowness.                                                                 |
+| `compiler::make`        | **Make Phase**: Resolving, loading, and parsing modules.       | Heavy loaders (babel/swc with complex configs), too many files, slow file system. |
+| `compiler::seal`        | **Seal Phase**: Optimizing, splitting chunks, generating code. | Complex code splitting, heavy minification, many modules.                         |
+| `compiler::emit_assets` | **Emit Phase**: Writing files to disk.                         | Slow disk I/O, huge output files.                                                 |
+
+## Detailed Spans
+
+### Make Phase (Module Processing)
+
+- `resolver::resolve`: Resolving import paths.
+  - **High Time?**: Check for complex `resolve.alias` or `resolve.modules`, or too many standard fallbacks.
+- `loader::run_loaders`: Executing loaders (JavaScript/Rust).
+  - **High Time?**: Identify which loader is slow. If `sass-loader` or `babel-loader` is slow, consider caching (`cache: true` in config) or using `swc-loader`.
+- `parser::parse`: Parsing source code into AST.
+  - **High Time?**: Large files?
+
+### Seal Phase (Optimization)
+
+- `compilation::code_generation`: Generating final code from AST.
+- `compilation::optimize_chunks`: Splitting chunks (SplitChunksPlugin).
+  - `k_means_splitter`: If you see this, complex splitting logic is running.
+- `js_minimizer`: Minification (SwcJsMinimizer).
+  - **High Time?**: Disable minimization in dev (`optimization.minimize: false`) for speed.
+
+### General
+
+- `read_file`: Reading files from disk.
+- `write_file`: Writing artifacts to disk.
+
+## Common Fixes
+
+1.  **Slow `make` phase**:
+    - Use `experiments.cache` (Persistent Cache).
+    - Exclude `node_modules` from expensive loaders.
+    - Switch to lighter loaders (e.g. `swc-loader` vs `babel-loader`).
+2.  **Slow `seal` phase**:
+    - Reduce `splitChunks` complexity.
+    - Disable `sourcemap` in production if acceptable cost.
+    - Upgrade to latest Rspack (performance improvements are frequent).

package/template-workspace/.agents/skills/rspack-tracing/references/tracing-guide.md

@@ -0,0 +1,38 @@
+# Rspack Tracing Guide
+
+Tracing allows you to visualize exactly what Rspack is doing during a build.
+
+## Enabling Tracing
+
+Rspack uses several environment variables to control tracing.
+
+**Command:**
+
+```bash
+RSPACK_PROFILE=TRACE RSPACK_TRACE_LAYER=logger RSPACK_TRACE_OUTPUT=./trace.json rspack build
+```
+
+### Variables
+
+**`RSPACK_PROFILE`**: Controls the granularity of the trace.
+
+- `TRACE`: Captures all spans. (Recommended for deep analysis)
+- `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRITICAL`
+- `OFF`: Disables tracing.
+
+**`RSPACK_TRACE_LAYER`**: Controls the output format.
+
+- `logger`: Outputs standard JSON logging (required for the analysis script).
+
+## Output
+
+After running the command, Rspack will generate the file specified in `RSPACK_TRACE_OUTPUT`.
+
+## Using the Skill's Analysis Tool
+
+This skill includes a script to summarize the trace file.
+
+```bash
+# Run the included script
+node scripts/analyze_trace.js <path-to-trace-file>
+```

package/template-workspace/.agents/skills/rspack-tracing/scripts/analyze_trace.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse duration string (e.g., "1.23ms", "456.78µs", "0.12s") to milliseconds
+function parseDuration(durationStr) {
+  if (!durationStr) return 0;
+
+  const match = durationStr.match(/^([\d.]+)(ms|µs|s|ns)$/);
+  if (!match) return 0;
+
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+
+  switch (unit) {
+    case 's':
+      return value * 1000;
+    case 'ms':
+      return value;
+    case 'µs':
+      return value / 1000;
+    case 'ns':
+      return value / 1000000;
+    default:
+      return value;
+  }
+}
+
+// Get trace file path
+const tracePath = process.argv[2] || path.join(__dirname, 'trace.json');
+
+if (!fs.existsSync(tracePath)) {
+  console.error(`Error: Trace file not found at ${tracePath}`);
+  console.error('Usage: node analyze_trace.js <path-to-trace.json>');
+  process.exit(1);
+}
+
+console.log(`Analyzing trace file: ${tracePath}\n`);
+
+try {
+  const fileContent = fs.readFileSync(tracePath, 'utf8');
+
+  // Parse line-delimited JSON
+  const events = fileContent
+    .trim()
+    .split('\n')
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch (err) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  if (!events.length) {
+    console.error('No valid trace events found.');
+    process.exit(1);
+  }
+
+  console.log('=== Rspack Build Performance Analysis ===\n');
+  console.log(`Total events: ${events.length}\n`);
+
+  // Categorize events by target
+  const pluginStats = new Map();
+  const loaderStats = new Map();
+
+  events.forEach(event => {
+    const target = event.target;
+    const timeField = event.fields?.['time.busy'];
+
+    if (!timeField) return;
+
+    const duration = parseDuration(timeField);
+
+    if (target === 'Plugin Analysis') {
+      // Plugin performance
+      const pluginName = event.span?.name;
+      if (!pluginName) return;
+
+      if (!pluginStats.has(pluginName)) {
+        pluginStats.set(pluginName, {
+          count: 0,
+          total: 0,
+          max: 0,
+          min: Infinity,
+        });
+      }
+
+      const stat = pluginStats.get(pluginName);
+      stat.count++;
+      stat.total += duration;
+      stat.max = Math.max(stat.max, duration);
+      stat.min = Math.min(stat.min, duration);
+    } else if (target === 'Loader Analysis') {
+      // Loader performance
+      let loaderName = event.span?.name;
+
+      // For pitch phase (span.name is null), use resource path
+      if (!loaderName) {
+        const resource = event.fields?.resource;
+        if (resource) {
+          // Extract filename from resource path
+          const cleanResource = resource.replace(/^"|"$/g, ''); // Remove quotes
+          const filename = cleanResource.split('/').pop();
+          loaderName = `Loader pitch for ${filename}`;
+        } else {
+          loaderName = 'Loader pitch (unknown resource)';
+        }
+      }
+
+      if (!loaderStats.has(loaderName)) {
+        loaderStats.set(loaderName, {
+          count: 0,
+          total: 0,
+          max: 0,
+          min: Infinity,
+        });
+      }
+
+      const stat = loaderStats.get(loaderName);
+      stat.count++;
+      stat.total += duration;
+      stat.max = Math.max(stat.max, duration);
+      stat.min = Math.min(stat.min, duration);
+    }
+  });
+
+  // Display Plugin Analysis
+  if (pluginStats.size > 0) {
+    console.log('🔌 Plugin Analysis (by name):');
+    console.log('─'.repeat(80));
+
+    const sortedPlugins = [...pluginStats.entries()].sort(
+      (a, b) => b[1].total - a[1].total,
+    );
+
+    sortedPlugins.forEach(([name, stat]) => {
+      const avg = stat.total / stat.count;
+      console.log(`${name}`);
+      console.log(
+        `  Total: ${stat.total.toFixed(2)}ms | Count: ${stat.count} | ` +
+          `Avg: ${avg.toFixed(2)}ms | Max: ${stat.max.toFixed(2)}ms | Min: ${stat.min.toFixed(2)}ms`,
+      );
+      console.log('');
+    });
+
+    const totalPluginTime = [...pluginStats.values()].reduce(
+      (sum, stat) => sum + stat.total,
+      0,
+    );
+    console.log(`Total Plugin Time: ${totalPluginTime.toFixed(2)}ms\n`);
+  }
+
+  // Display Loader Analysis
+  if (loaderStats.size > 0) {
+    console.log('\n🔧 Loader Analysis (by name):');
+    console.log('─'.repeat(80));
+
+    const sortedLoaders = [...loaderStats.entries()].sort(
+      (a, b) => b[1].total - a[1].total,
+    );
+
+    sortedLoaders.forEach(([name, stat]) => {
+      const avg = stat.total / stat.count;
+      console.log(`${name}`);
+      console.log(
+        `  Total: ${stat.total.toFixed(2)}ms | Count: ${stat.count} | ` +
+          `Avg: ${avg.toFixed(2)}ms | Max: ${stat.max.toFixed(2)}ms | Min: ${stat.min.toFixed(2)}ms`,
+      );
+      console.log('');
+    });
+
+    const totalLoaderTime = [...loaderStats.values()].reduce(
+      (sum, stat) => sum + stat.total,
+      0,
+    );
+    console.log(`Total Loader Time: ${totalLoaderTime.toFixed(2)}ms\n`);
+  }
+} catch (err) {
+  console.error('Error processing trace file:', err);
+  process.exit(1);
+}

package/template-workspace/.agents/skills/rstest-best-practices/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: rstest-best-practices
+description: Rstest best practices for config, CLI workflow, test writing, mocking, snapshot testing, DOM testing, coverage, multi-project setup, CI integration, performance and debugging. Use when writing, reviewing, or troubleshooting Rstest test projects.
+---
+
+# Rstest Best Practices
+
+Apply these rules when writing or reviewing Rstest test projects.
+
+## Configuration
+
+- Use `rstest.config.ts` and `defineConfig` from `@rstest/core`
+- Prefer explicit imports `import { test, expect, describe } from '@rstest/core'` over `globals: true`
+- For Rsbuild projects, use `@rstest/adapter-rsbuild` with `extends: withRsbuildConfig()` to reuse build config
+- For Rslib projects, use `@rstest/adapter-rslib` with `extends: withRslibConfig()` to reuse build config
+- Use `setupFiles` for shared test setup (e.g., custom matchers, cleanup hooks)
+- When using Rsbuild plugins (e.g., `@rsbuild/plugin-react`), add them via the `plugins` field
+- For deep-level or advanced build configuration needs, use `tools.rspack` or `tools.bundlerChain`
+
+## CLI
+
+- Use `rstest` or `rstest run` to run tests (`run` disables watch mode, suitable for CI)
+- Use `rstest --watch` or `rstest watch` for local development with file watching
+- Use `rstest list` to list all test files and test names
+- Use `rstest -u` to update snapshots
+- Use `--reporter=verbose` when debugging test failures for detailed output
+- Use `--config` (`-c`) to specify a custom config file path
+
+## Test writing
+
+- Import test APIs from `@rstest/core`: `test`, `describe`, `expect`, `beforeEach`, `afterEach`, etc.
+- Use `test` or `it` for test cases; use `describe` for grouping related tests
+- Use `.only` to focus on specific tests during development, but never commit `.only` to the codebase
+- Use `.skip` or `.todo` to mark incomplete or temporarily skipped tests
+- Prefer small, focused test cases that test a single behavior
+- For async error paths, prefer `await expect(fn()).rejects.toThrow(ErrorClass)` (or `.rejects.toMatchObject({ ... })`) over `try/catch` with `expect.fail` or `.catch(e => e)` patterns — the matcher form fails clearly if the promise unexpectedly resolves, keeps the assertion in one chain, and avoids forgetting to assert the throw at all
+- For async happy paths, use `await expect(fn()).resolves.toEqual(...)` for the same reason
+- Use `includeSource` for in-source testing of small utility functions (Rust-style `import.meta.rstest`)
+- For in-source tests, wrap test code in `if (import.meta.rstest) { ... }` and define `import.meta.rstest` as `false` in production build config
+
+## Test environment
+
+- Use `testEnvironment: 'node'` (default) for Node.js / server-side code
+- Use `testEnvironment: 'jsdom'` or `testEnvironment: 'happy-dom'` for DOM / browser API testing
+- Install `jsdom` or `happy-dom` as a dev dependency when using DOM environments
+- Prefer `happy-dom` for faster DOM testing; use `jsdom` when better browser API compatibility is needed
+- For real browser testing, use `@rstest/browser` with Playwright
+- Use inline project configs to run different test environments within one project (e.g., `node` and `jsdom` projects)
+
+## React / Vue testing
+
+- For React: use `@rsbuild/plugin-react` plugin and `@testing-library/react` for component testing
+- For Vue: use `@rsbuild/plugin-vue` plugin and `@testing-library/vue` for component testing
+- Create a `rstest.setup.ts` with `expect.extend(jestDomMatchers)` and `afterEach(() => cleanup())` for Testing Library
+- Add the setup file to `setupFiles` in config
+- For SSR testing, use `testEnvironment: 'node'` and test with `react-dom/server` or framework-specific SSR APIs
+
+## Mocking
+
+- Use `rs.mock('./module')` to mock modules
+- Use `rs.fn()` to create mock functions
+- Use `rs.spyOn(object, 'method')` to spy on methods
+- Prefer `clearMocks`, `resetMocks`, or `restoreMocks` config options to automatically clean up mocks between tests
+- Use factory functions in `rs.mock('./module', () => ({ ... }))` to provide mock implementations
+
+## Snapshot testing
+
+- Use `toMatchSnapshot()` for general snapshot testing
+- Use `toMatchInlineSnapshot()` for small, readable inline snapshots
+- Use `toMatchFileSnapshot()` for large or structured outputs (e.g., HTML, generated code)
+- Keep snapshots concise — only include relevant data, avoid timestamps and session IDs
+- Use `expect.addSnapshotSerializer()` to mask paths or sensitive data in snapshots
+- Use `path-serializer` to normalize file paths across platforms
+- Review snapshot changes carefully in code review
+
+## Coverage
+
+- Enable coverage with `--coverage` CLI flag or `coverage.enabled: true` in config
+- Install `@rstest/coverage-istanbul` for the Istanbul coverage provider
+- Use `coverage.include` to specify source files for coverage (e.g., `['src/**/*.{js,ts,tsx}']`)
+- Use `coverage.thresholds` to enforce minimum coverage requirements
+- Use `coverage.reporters` to generate reports in different formats (e.g., `text`, `lcov`, `html`)
+
+## Multi-project testing
+
+- Use `projects` field in root config to define multiple test projects
+- For monorepos, use glob patterns like `'packages/*'` to auto-discover sub-projects
+- Use `defineProject` helper in sub-project configs
+- Extract shared config and use `mergeRstestConfig` to compose project configs
+- Global options (`reporters`, `pool`, `isolate`, `coverage`, `bail`) must be set at the root level, not in projects
+
+## CI integration
+
+- Use `rstest run` (not `rstest watch`) in CI
+- Use `--shard` for parallel test execution across CI machines (e.g., `--shard 1/3`)
+- Use `--reporter=blob` with `rstest merge-reports` to combine sharded results
+- Use `--reporter=junit` with `outputPath` for CI report integration
+- The `github-actions` reporter is auto-enabled in GitHub Actions for inline error annotations
+- Use `--bail` to stop early on first failure when appropriate
+
+## Performance
+
+- Disable `isolate` (`--no-isolate`) when tests have no side effects for faster execution via module cache reuse
+- Use `pool.maxWorkers` to control parallelism based on available resources
+- Keep test build fast by avoiding unnecessary Rspack plugins in test config
+- Use test filtering (`rstest <pattern>` or `-t <name>`) to run only relevant tests during development
+- Leverage watch mode's incremental re-runs for fast local feedback
+
+## Debugging
+
+- Run with `DEBUG=rstest` to enable debug mode, which writes final configs and build outputs to disk
+- Read generated files in `dist/.rstest-temp/.rsbuild/` to confirm final Rstest/Rsbuild/Rspack config
+- Use VS Code's JavaScript Debug Terminal to run `rstest` with breakpoints
+- Use `--reporter=verbose` for detailed per-test output
+- Use `--printConsoleTrace` to trace console calls to their source
+- Add VS Code launch config for debugging specific test files with `@rstest/core/bin/rstest.js`
+
+## Profiling
+
+- Use Rsdoctor with `RSDOCTOR=true rstest run` to analyze test build performance
+- Use `samply` for native profiling of both main and worker processes
+- Use Node.js `--heap-prof` for memory profiling
+
+## Toolchain integration
+
+- Use the official VS Code extension (`rstack.rstest`) for in-editor test running and debugging
+- For Rslib libraries, use `@rstest/adapter-rslib` for config reuse
+- For Rsbuild apps, use `@rstest/adapter-rsbuild` for config reuse
+- Use `process.env.RSTEST` to detect test environment and apply test-specific config
+
+## Documentation
+
+- For the latest Rstest docs, read https://rstest.rs/llms.txt

package/template-workspace/.agents/skills-lock.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "repository": "https://github.com/rstackjs/agent-skills",
+    "commit": "61c948b42512e223bad44b83af4080eba48b2677",
+    "license": "MIT",
+    "licensePath": ".agents/rstackjs-agent-skills-LICENSE"
+  },
+  "installDir": ".agents/skills",
+  "baseline": [
+    {
+      "name": "rsbuild-best-practices",
+      "path": ".agents/skills/rsbuild-best-practices",
+      "reason": "Modern.js application build configuration and Rsbuild troubleshooting"
+    },
+    {
+      "name": "rspack-best-practices",
+      "path": ".agents/skills/rspack-best-practices",
+      "reason": "Rspack bundling, CSS, asset, profiling, and production behavior"
+    },
+    {
+      "name": "rspack-tracing",
+      "path": ".agents/skills/rspack-tracing",
+      "reason": "Trace-backed Rspack failure and performance debugging"
+    },
+    {
+      "name": "rsdoctor-analysis",
+      "path": ".agents/skills/rsdoctor-analysis",
+      "reason": "Evidence-backed bundle composition, duplication, and retained-module analysis"
+    },
+    {
+      "name": "rslib-best-practices",
+      "path": ".agents/skills/rslib-best-practices",
+      "reason": "Rslib shared package and design-system library authoring"
+    },
+    {
+      "name": "rslib-modern-package",
+      "path": ".agents/skills/rslib-modern-package",
+      "reason": "Modern package contracts, exports, declarations, side effects, and release readiness"
+    },
+    {
+      "name": "rstest-best-practices",
+      "path": ".agents/skills/rstest-best-practices",
+      "reason": "Rstest configuration, test writing, mocking, snapshots, coverage, and CI behavior"
+    }
+  ],
+  "excludedByDefault": [
+    "migrate-to-rsbuild",
+    "migrate-to-rslib",
+    "migrate-to-rslint",
+    "migrate-to-rstest",
+    "rsbuild-v2-upgrade",
+    "rspack-v2-upgrade",
+    "rspress-v2-upgrade"
+  ]
+}

package/template-workspace/AGENTS.md

@@ -0,0 +1,28 @@
+# UltraModern Agent Contract
+
+This workspace is generated as an agent-ready UltraModern.js SuperApp. Agents should treat the files under `.agents/skills` as local project instructions, not optional reading.
+
+## Required Skill Baseline
+
+Use these skills when the task touches the matching subsystem:
+
+- `rsbuild-best-practices`: Modern.js app build configuration, Rsbuild options, assets, type checking, and build debugging.
+- `rspack-best-practices`: Rspack-level bundling, CSS, assets, profiling, and production build behavior.
+- `rspack-tracing`: Rspack build failures, slow builds, crash localization, and trace analysis.
+- `rsdoctor-analysis`: Evidence-based bundle analysis from `rsdoctor-data.json`, including duplicate packages, large chunks, and retained modules.
+- `rslib-best-practices`: Shared packages, generated libraries, declaration output, and Rslib configuration.
+- `rslib-modern-package`: Package contracts for shared libraries, exports, side effects, dependency placement, README, and release readiness.
+- `rstest-best-practices`: Rstest configuration, test writing, mocking, snapshots, coverage, and CI test behavior.
+
+## Project Priorities
+
+- Keep `presetUltramodern` as the single preset.
+- Prefer Effect for BFF/service code.
+- Prefer TanStack Router for app routing.
+- Keep design-system code as a normal Micro Frontend or shared package, not a special core path.
+- Keep generated packages explicit and publishable: stable `exports`, correct declarations, small public APIs, and clear ownership metadata.
+- Do not add migration tooling or codemods unless the project owner explicitly asks for migration work.
+
+## Skill Provenance
+
+The vendored Rstack skills are pinned in `.agents/skills-lock.json`. Do not update, remove, or replace them casually. If a skill needs updating, update the lock file and run `pnpm ultramodern:check`.

package/template-workspace/scripts/validate-ultramodern-workspace.mjs.handlebars

@@ -4,12 +4,23 @@ import path from 'node:path';
 const root = process.cwd();
 const packageScope = '{{packageScope}}';
 const tanstackVersion = '1.170.1';
+const rstackAgentSkillsCommit =
+  '61c948b42512e223bad44b83af4080eba48b2677';
 const modernPackages = [
   '@modern-js/app-tools',
   '@modern-js/plugin-bff',
   '@modern-js/plugin-tanstack',
   '@modern-js/runtime',
 ];
+const baselineAgentSkills = [
+  'rsbuild-best-practices',
+  'rspack-best-practices',
+  'rspack-tracing',
+  'rsdoctor-analysis',
+  'rslib-best-practices',
+  'rslib-modern-package',
+  'rstest-best-practices',
+];
 
 function readText(relativePath) {
   return fs.readFileSync(path.join(root, relativePath), 'utf-8');
@@ -30,9 +41,22 @@ function assertExists(relativePath) {
 }
 
 const requiredPaths = [
+  'AGENTS.md',
   'package.json',
   'pnpm-workspace.yaml',
   'tsconfig.base.json',
+  '.agents/skills-lock.json',
+  '.agents/rstackjs-agent-skills-LICENSE',
+  '.agents/skills/rsbuild-best-practices/SKILL.md',
+  '.agents/skills/rspack-best-practices/SKILL.md',
+  '.agents/skills/rspack-tracing/SKILL.md',
+  '.agents/skills/rspack-tracing/references/tracing-guide.md',
+  '.agents/skills/rspack-tracing/scripts/analyze_trace.js',
+  '.agents/skills/rsdoctor-analysis/SKILL.md',
+  '.agents/skills/rsdoctor-analysis/references/rsdoctor-data-types.md',
+  '.agents/skills/rslib-best-practices/SKILL.md',
+  '.agents/skills/rslib-modern-package/SKILL.md',
+  '.agents/skills/rstest-best-practices/SKILL.md',
   'topology/reference-topology.json',
   'topology/ownership.json',
   'topology/local-overlays/development.json',
@@ -65,6 +89,7 @@ for (const requiredPath of requiredPaths) {
 
 const rootPackage = readJson('package.json');
 const packageSource = readJson('.modernjs/ultramodern-package-source.json');
+const skillsLock = readJson('.agents/skills-lock.json');
 const expectedModernSpecifier =
   packageSource.strategy === 'install'
     ? packageSource.modernPackages?.specifier
@@ -83,6 +108,8 @@ function expectedModernDependency(packageName) {
 
 assert(rootPackage.private === true, 'Root package must be private');
 assert(rootPackage.modernjs?.preset === 'presetUltramodern', 'Root must declare presetUltramodern');
+assert(rootPackage.packageManager === 'pnpm@11.1.2', 'Root must pin pnpm 11.1.2');
+assert(rootPackage.engines?.pnpm === '>=11.0.0', 'Root must require pnpm >=11');
 assert(
   rootPackage.modernjs?.packageSource?.config ===
     './.modernjs/ultramodern-package-source.json',
@@ -117,6 +144,36 @@ assert(
   'Root must expose the ultramodern:check script',
 );
 
+const agentsInstructions = readText('AGENTS.md');
+assert(
+  agentsInstructions.includes('UltraModern Agent Contract') &&
+    agentsInstructions.includes('Required Skill Baseline'),
+  'Root AGENTS.md must document the UltraModern agent contract',
+);
+assert(
+  skillsLock.source?.repository === 'https://github.com/rstackjs/agent-skills',
+  'Agent skills lock must retain the Rstack skill source repository',
+);
+assert(
+  skillsLock.source?.commit === rstackAgentSkillsCommit,
+  'Agent skills lock must pin the expected Rstack skill commit',
+);
+assert(
+  skillsLock.installDir === '.agents/skills',
+  'Agent skills lock must use .agents/skills as installDir',
+);
+for (const skillName of baselineAgentSkills) {
+  assert(
+    skillsLock.baseline?.some(skill => skill.name === skillName),
+    `Agent skills lock must include ${skillName}`,
+  );
+  const skillContent = readText(`.agents/skills/${skillName}/SKILL.md`);
+  assert(
+    skillContent.includes(`name: ${skillName}`),
+    `${skillName} must contain matching skill metadata`,
+  );
+}
+
 const appPackagePaths = [
   'apps/shell-super-app/package.json',
   'apps/remotes/remote-commerce/package.json',
@@ -268,6 +325,16 @@ assert(
   manifest.packageSource?.strategy === packageSource.strategy,
   'Template manifest must retain the generated package source strategy',
 );
+assert(
+  manifest.agentSkills?.source?.commit === rstackAgentSkillsCommit,
+  'Template manifest must retain the Rstack agent skills commit',
+);
+assert(
+  baselineAgentSkills.every(skillName =>
+    manifest.agentSkills?.baseline?.includes(skillName),
+  ),
+  'Template manifest must list every baseline agent skill',
+);
 assert(
   manifest.validation?.expectedCommands?.includes('pnpm run ultramodern:check'),
   'Template manifest must document the validation command',