frontend-assessment-skill 1.0.8 → 1.1.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 (4) hide show
  1. package/README.md +24 -13
  2. package/bin/cli.js +104 -77
  3. package/package.json +1 -1
  4. package/skills/SKILL.md +130 -211
package/README.md CHANGED
@@ -11,9 +11,12 @@ npx frontend-assessment-skill
11
11
  ```
12
12
 
13
13
  The installer will prompt you to choose where to install the skill:
14
+
14
15
  1. **Globally** (`~/.agents/skills/frontend-assessment`) — Available across all your projects in Zed / AI agents.
15
16
  2. **Project folder** (`.agents/skills/frontend-assessment`) — Installed only in the current repository.
16
17
 
18
+ To refresh an existing installation, use `@latest` and `--update` with `--global` or `--project`. Updating replaces the installed `SKILL.md` without a confirmation prompt; it does not install the skill if it is not already present.
19
+
17
20
  ### Command-line flags (non-interactive)
18
21
 
19
22
  ```bash
@@ -22,6 +25,12 @@ npx frontend-assessment-skill --global
22
25
 
23
26
  # Install in current project directory
24
27
  npx frontend-assessment-skill --project
28
+
29
+ # Update the globally installed skill to the latest package version
30
+ npx frontend-assessment-skill@latest --update --global
31
+
32
+ # Update the skill installed in the current project
33
+ npx frontend-assessment-skill@latest --update --project
25
34
  ```
26
35
 
27
36
  ---
@@ -30,27 +39,29 @@ npx frontend-assessment-skill --project
30
39
 
31
40
  Once installed, simply ask your agent in Zed (or your agent tool of choice):
32
41
 
33
- > *"Perform a frontend health assessment of this repository"*
42
+ > _"Perform a frontend health assessment of this repository"_
34
43
 
35
44
  Or specify quarters/scopes:
36
45
 
37
- > *"Run a frontend assessment for Q3 2025 focusing on the web-app package"*
46
+ > _"Run a frontend assessment for Q3 2025 focusing on the web-app package"_
47
+
48
+ For an optional live-site performance assessment, include `FRONTEND_ASSESSMENT_URL=https://example.com`. After walking through the primary user journey, the skill uses Chrome DevTools MCP for Lighthouse Performance and Core Web Vitals when available, replaying the journey's route changes and actions during the measured session where possible. The Lighthouse category score is worth up to 20 optional points, with LCP, INP, and CLS shown as a non-additive breakdown. Unavailable Lighthouse scores are noted and excluded from scoring. If the site requires authentication, the assessment pauses for you to sign in manually and confirm before testing continues.
38
49
 
39
50
  ---
40
51
 
41
52
  ## What It Evaluates
42
53
 
43
- The skill calculates a strict, reproducible score (0–100) across 7 criteria:
44
-
45
- | Criterion | Weight | Summary |
46
- | --- | :---: | --- |
47
- | **Dependency freshness** | 20 | Share of dependencies on latest/minor version and updated within 183 days |
48
- | **Core package currency** | 20 | Currency of core runtime, framework, router, build, and test tools |
49
- | **Contributor diversity** | 10 | Unique contributors in the last 12 months (diversity signal) |
50
- | **Quarterly delivery cadence** | 10 | Commits, merges, and releases during the assessed quarter |
51
- | **Test suite maturity** | 10 | Presence of unit, integration, component, and e2e test layers |
52
- | **Coverage** | 10 | Frontend code test coverage percentage |
53
- | **UI system & component library** | 20 | Adoption of a single consistent component library, formal design tokens, and non-deprecated UI dependencies |
54
+ The skill calculates a strict, reproducible score (0–100) across 7 repository criteria. When a target URL is supplied and the Lighthouse Performance score is available through Chrome DevTools MCP, it adds up to 20 optional points based on that total Lighthouse score. LCP, INP, and CLS are listed as diagnostic score/rating breakdowns, not additional points; unavailable Lighthouse scores are noted and excluded.
55
+
56
+ | Criterion | Weight | Summary |
57
+ | --------------------------------- | :----: | ----------------------------------------------------------------------------------------------------------- |
58
+ | **Dependency freshness** | 20 | Share of dependencies on latest/minor version and updated within 183 days |
59
+ | **Core package currency** | 20 | Currency of core runtime, framework, router, build, and test tools |
60
+ | **Contributor diversity** | 10 | Unique contributors in the last 12 months (diversity signal) |
61
+ | **Quarterly delivery cadence** | 10 | Commits, merges, and releases during the assessed quarter |
62
+ | **Test suite maturity** | 10 | Presence of unit, integration, component, and e2e test layers |
63
+ | **Coverage** | 10 | Frontend code test coverage percentage |
64
+ | **UI system & component library** | 20 | Adoption of a single consistent component library, formal design tokens, and non-deprecated UI dependencies |
54
65
 
55
66
  ---
56
67
 
package/bin/cli.js CHANGED
@@ -1,19 +1,19 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- import fs from 'node:fs';
4
- import path from 'node:path';
5
- import os from 'node:os';
6
- import readline from 'node:readline/promises';
7
- import { fileURLToPath } from 'node:url';
3
+ import fs from "node:fs";
4
+ import path from "node:path";
5
+ import os from "node:os";
6
+ import readline from "node:readline/promises";
7
+ import { fileURLToPath } from "node:url";
8
8
 
9
9
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
10
- const SKILL_NAME = 'frontend-assessment';
11
- const SOURCE_SKILL_PATH = path.resolve(__dirname, '../skills/SKILL.md');
10
+ const SKILL_NAME = "frontend-assessment";
11
+ const SOURCE_SKILL_PATH = path.resolve(__dirname, "../skills/SKILL.md");
12
12
 
13
13
  const args = process.argv.slice(2);
14
14
 
15
15
  function printHelp() {
16
- console.log(`
16
+ console.log(`
17
17
  Frontend Assessment Skill Installer
18
18
 
19
19
  Usage:
@@ -22,88 +22,115 @@ Usage:
22
22
  Options:
23
23
  -g, --global Install globally to ~/.agents/skills/frontend-assessment
24
24
  -p, --project Install locally to .agents/skills/frontend-assessment
25
+ -u, --update Update the installed skill without prompting
25
26
  -h, --help Show this help message
26
27
  `);
27
28
  }
28
29
 
29
30
  async function run() {
30
- if (args.includes('-h') || args.includes('--help')) {
31
- printHelp();
32
- process.exit(0);
33
- }
34
-
35
- if (!fs.existsSync(SOURCE_SKILL_PATH)) {
36
- console.error(`\n❌ Error: Source skill file not found at ${SOURCE_SKILL_PATH}\n`);
37
- process.exit(1);
38
- }
39
-
40
- console.log('\n=========================================');
41
- console.log(' 📊 Frontend Assessment Skill Installer');
42
- console.log('=========================================\n');
43
-
44
- let targetScope = null;
45
-
46
- if (args.includes('-g') || args.includes('--global')) {
47
- targetScope = 'global';
48
- } else if (args.includes('-p') || args.includes('--project')) {
49
- targetScope = 'project';
50
- }
51
-
52
- const rl = readline.createInterface({
53
- input: process.stdin,
54
- output: process.stdout,
55
- });
56
-
57
- try {
58
- if (!targetScope) {
59
- console.log('Where would you like to install the skill?');
60
- console.log(' 1) Globally (~/.agents/skills/frontend-assessment)');
61
- console.log(' 2) In current project folder (.agents/skills/frontend-assessment)');
62
- console.log(' 3) Cancel\n');
63
-
64
- const answer = (await rl.question('Select an option (1-3) [default: 1]: ')).trim() || '1';
65
-
66
- if (answer === '1') {
67
- targetScope = 'global';
68
- } else if (answer === '2') {
69
- targetScope = 'project';
70
- } else {
71
- console.log('\nInstallation cancelled.\n');
31
+ if (args.includes("-h") || args.includes("--help")) {
32
+ printHelp();
72
33
  process.exit(0);
73
- }
74
34
  }
75
35
 
76
- const targetDir =
77
- targetScope === 'global'
78
- ? path.join(os.homedir(), '.agents', 'skills', SKILL_NAME)
79
- : path.join(process.cwd(), '.agents', 'skills', SKILL_NAME);
36
+ if (!fs.existsSync(SOURCE_SKILL_PATH)) {
37
+ console.error(
38
+ `\n❌ Error: Source skill file not found at ${SOURCE_SKILL_PATH}\n`,
39
+ );
40
+ process.exit(1);
41
+ }
80
42
 
81
- const targetFile = path.join(targetDir, 'SKILL.md');
43
+ console.log("\n=========================================");
44
+ console.log(" 📊 Frontend Assessment Skill Installer");
45
+ console.log("=========================================\n");
82
46
 
83
- if (fs.existsSync(targetFile)) {
84
- const overwrite = (
85
- await rl.question(`\n⚠️ Skill already exists at:\n ${targetFile}\n Overwrite? (y/N): `)
86
- ).trim().toLowerCase();
47
+ const updateMode = args.includes("-u") || args.includes("--update");
48
+ let targetScope = null;
87
49
 
88
- if (overwrite !== 'y' && overwrite !== 'yes') {
89
- console.log('\nInstallation cancelled. Existing file left untouched.\n');
90
- process.exit(0);
91
- }
50
+ if (args.includes("-g") || args.includes("--global")) {
51
+ targetScope = "global";
52
+ } else if (args.includes("-p") || args.includes("--project")) {
53
+ targetScope = "project";
92
54
  }
93
55
 
94
- fs.mkdirSync(targetDir, { recursive: true });
95
- fs.copyFileSync(SOURCE_SKILL_PATH, targetFile);
96
-
97
- console.log(`\n✅ Successfully installed "${SKILL_NAME}" skill!`);
98
- console.log(` Location: ${targetFile}\n`);
99
- console.log('You can now run frontend assessments in your AI agent (e.g. Zed, Claude) by prompting:');
100
- console.log(' "Give me a frontend assessment of this repository"\n');
101
- } catch (err) {
102
- console.error('\n❌ Installation failed:', err.message, '\n');
103
- process.exit(1);
104
- } finally {
105
- rl.close();
106
- }
56
+ const rl = readline.createInterface({
57
+ input: process.stdin,
58
+ output: process.stdout,
59
+ });
60
+
61
+ try {
62
+ if (!targetScope) {
63
+ console.log("Where would you like to install the skill?");
64
+ console.log(" 1) Globally (~/.agents/skills/frontend-assessment)");
65
+ console.log(
66
+ " 2) In current project folder (.agents/skills/frontend-assessment)",
67
+ );
68
+ console.log(" 3) Cancel\n");
69
+
70
+ const answer =
71
+ (
72
+ await rl.question("Select an option (1-3) [default: 1]: ")
73
+ ).trim() || "1";
74
+
75
+ if (answer === "1") {
76
+ targetScope = "global";
77
+ } else if (answer === "2") {
78
+ targetScope = "project";
79
+ } else {
80
+ console.log("\nInstallation cancelled.\n");
81
+ process.exit(0);
82
+ }
83
+ }
84
+
85
+ const targetDir =
86
+ targetScope === "global"
87
+ ? path.join(os.homedir(), ".agents", "skills", SKILL_NAME)
88
+ : path.join(process.cwd(), ".agents", "skills", SKILL_NAME);
89
+
90
+ const targetFile = path.join(targetDir, "SKILL.md");
91
+ const skillExists = fs.existsSync(targetFile);
92
+
93
+ if (updateMode && !skillExists) {
94
+ console.error(
95
+ `\n❌ No installed skill found to update at ${targetFile}`,
96
+ );
97
+ console.error(" Run without --update to install it first.\n");
98
+ process.exit(1);
99
+ }
100
+
101
+ if (skillExists && !updateMode) {
102
+ const overwrite = (
103
+ await rl.question(
104
+ `\n⚠️ Skill already exists at:\n ${targetFile}\n Overwrite? (y/N): `,
105
+ )
106
+ )
107
+ .trim()
108
+ .toLowerCase();
109
+
110
+ if (overwrite !== "y" && overwrite !== "yes") {
111
+ console.log(
112
+ "\nInstallation cancelled. Existing file left untouched.\n",
113
+ );
114
+ process.exit(0);
115
+ }
116
+ }
117
+
118
+ fs.mkdirSync(targetDir, { recursive: true });
119
+ fs.copyFileSync(SOURCE_SKILL_PATH, targetFile);
120
+
121
+ const action = updateMode ? "updated" : "installed";
122
+ console.log(`\n✅ Successfully ${action} "${SKILL_NAME}" skill!`);
123
+ console.log(` Location: ${targetFile}\n`);
124
+ console.log(
125
+ "You can now run frontend assessments in your AI agent (e.g. Zed, Claude) by prompting:",
126
+ );
127
+ console.log(' "Give me a frontend assessment of this repository"\n');
128
+ } catch (err) {
129
+ console.error("\n❌ Installation failed:", err.message, "\n");
130
+ process.exit(1);
131
+ } finally {
132
+ rl.close();
133
+ }
107
134
  }
108
135
 
109
136
  run();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "frontend-assessment-skill",
3
- "version": "1.0.8",
3
+ "version": "1.1.0",
4
4
  "description": "Installer for the frontend-assessment agent skill (Zed, Claude, and agent tools)",
5
5
  "type": "module",
6
6
  "bin": "./bin/cli.js",
package/skills/SKILL.md CHANGED
@@ -1,298 +1,217 @@
1
1
  ---
2
2
  name: frontend-assessment
3
-
4
- description: Assess frontend health and maturity. USE WHEN the user asks for a "frontend assessment", "frontend health check", "frontend review", "frontend score", or wants a reproducible 1-100 score for dependency freshness, core package currency, contributor activity, delivery cadence, testing, coverage, and UI system & component library adoption.
5
- ---
6
-
3
+ description: Assess frontend health and maturity. Use when the user asks for a frontend assessment, health check, review, or reproducible 0-100 score for dependencies, contributor activity, delivery cadence, testing, coverage, UI system adoption, and optional live-site performance.
7
4
  ---
8
5
 
9
6
  # Frontend Assessment
10
7
 
11
- Produce a reproducible **1-100 frontend assessment score** for the current repository.
8
+ Produce an evidence-based, stack-aware **0-100 frontend assessment score** for the current repository. Cite repository paths, command results, and browser measurements so another reviewer can reproduce the assessment.
12
9
 
13
- ## User Instructions
10
+ ## Inputs and Execution Order
14
11
 
15
12
  $ARGUMENTS
16
13
 
17
- Respect any explicit scope, quarter, or stack instructions from the user. If the user does not provide a quarter, assess the **most recently completed calendar quarter**.
18
-
19
- ## Goal
14
+ - Respect the user's app/package scope and stack instructions.
15
+ - Use the **last three months** for contributor activity and delivery cadence unless the user specifies a quarter or another period. Resolve exact start and end dates once and use them consistently for both criteria. Dependency status and live measurements describe the current state, not a historical snapshot.
16
+ - Accept an optional target URL directly in the request, as `FRONTEND_ASSESSMENT_URL=https://...` in the skill arguments, or from the `FRONTEND_ASSESSMENT_URL` environment variable. An explicit request/argument takes precedence over the environment variable.
20
17
 
21
- Measure frontend health in a way that is:
18
+ Execute in this order:
22
19
 
23
- - **reproducible**: use the same rubric every time
24
- - **stack-aware**: evaluate the frontend framework/runtime actually in use
25
- - **evidence-based**: do not guess; cite repo evidence and command output
26
- - **portable**: works for monorepos, single-app repos, and different frontend stacks
20
+ 1. Establish scope and detect the stack.
21
+ 2. Collect repository evidence.
22
+ 3. Map the primary user journey and, when browser access is available, walk through it.
23
+ 4. If a URL was supplied, run Lighthouse and replay the journey during performance measurement.
24
+ 5. Calculate scores and write the report.
27
25
 
28
- ## Assessment Scope
26
+ Use repository-native tooling and existing CI/test targets. Do not install tools or add instrumentation just to produce the assessment. For Nx workspaces, use the existing Nx targets through the workspace's package manager.
29
27
 
30
- 1. Identify the frontend surface being assessed.
31
- - In a monorepo, prefer the primary deployable frontend application(s).
32
- - If the repo contains multiple frontend apps and the user did not narrow scope, assess the main production-facing app(s) plus shared frontend libraries used by them.
33
- - State the scope explicitly in the report.
34
- 2. Detect the package manager from lockfiles and use the workspace-native tooling.
35
- 3. Prefer direct evidence from:
36
- - `package.json` and relevant app/library manifests
37
- - lockfiles
38
- - build/test/project configuration
39
- - git history
40
- - GitHub releases / PR metadata
41
- - UI system and design token package manifests & deprecation metadata
28
+ ## 1. Scope and Stack
42
29
 
43
- ## Stack Detection
30
+ Identify the primary deployable frontend app(s). Unless the user narrows scope, include the main production-facing apps and the shared frontend libraries they consume. State the scope explicitly.
44
31
 
45
- Detect the frontend stack first. Typical examples:
32
+ Detect the package manager from lockfiles. Inspect manifests, lockfiles, build/test configuration, source code, git history, release metadata, and UI package deprecation metadata.
46
33
 
47
- | Category | Candidate packages |
48
- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
- | UI runtime | `react`, `vue`, `angular`, `svelte` |
50
- | App framework | `next`, `remix`, `@remix-run/*`, `gatsby`, `nuxt` |
51
- | Router | `react-router`, `react-router-dom`, `@tanstack/router`, framework router |
52
- | Build tool | `vite`, `webpack`, `rspack`, `parcel` |
53
- | Test tools | `jest`, `vitest`, `cypress`, `playwright` |
54
- | UI component library | `@mui/*`, `@chakra-ui/*`, `antd`, `@mantine/*`, `@radix-ui/*`, `shadcn` (`components.json`), `@carbon/*`, `@fluentui/*`, `react-bootstrap`, `@shoelace-style/*`, in-house/custom design system |
55
- | Design tokens / Styling | `style-dictionary`, `@tokens-studio/*`, design token packages, `tailwindcss`, `@vanilla-extract/*`, `styled-components`, `@emotion/*`, CSS variables/theme tokens |
34
+ | Category | Examples |
35
+ | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
36
+ | UI runtime/framework | `react`, `vue`, `@angular/core`, `svelte`, `next`, `@remix-run/*`, `nuxt` |
37
+ | Router | Framework router, `react-router`, `react-router-dom`, `@tanstack/react-router` |
38
+ | Build tool | `vite`, `webpack`, `rspack`, `parcel` |
39
+ | Test tools | `jest`, `vitest`, `cypress`, `@playwright/test`, Storybook |
40
+ | Component library | `@mui/*`, `antd`, `@chakra-ui/*`, `@mantine/*`, `@radix-ui/*`, shadcn (`components.json`), an in-house design system |
41
+ | Tokens/theme | `style-dictionary`, `@tokens-studio/*`, dedicated token packages, formal CSS variables/theme definitions |
42
+ | Styling | CSS/Sass, utility classes, `tailwindcss`, `@vanilla-extract/*`, `styled-components`, `@emotion/*` |
56
43
 
57
- When a stack-specific package from the user's examples is not present, substitute the equivalent core package(s) for that stack.
44
+ Use equivalent core packages for the detected stack rather than requiring these examples.
58
45
 
59
- ## Data Collection
46
+ ## 2. Repository Evidence
60
47
 
61
- ### 1. Dependency freshness
48
+ ### Dependency Freshness
62
49
 
63
- Assess direct dependencies that materially affect the frontend:
50
+ Assess direct production dependencies used by the scoped frontend and shared libraries, plus frontend-critical development dependencies such as build, test, and Storybook tools.
64
51
 
65
- - production dependencies used by the frontend app(s)
66
- - shared frontend libraries they consume
67
- - dev dependencies only when they are frontend-critical (for example `vite`, `webpack`, `storybook`, `jest`, `vitest`, `playwright`, `cypress`)
52
+ Record each package's installed/resolved version, latest version, installed-version publication date, and major/minor/patch lag. Use the workspace's package manager and registry metadata; npm examples include `npm outdated --json` and `npm view <package> version time --json`.
68
53
 
69
- Use existing package manager commands and registry metadata. Prefer:
54
+ ### Core Package Currency
70
55
 
71
- - `npm outdated --json`
72
- - `npm view <package> version time --json`
73
- - lockfile/package manifest inspection
56
+ Select a short list covering the runtime/framework, router where applicable, build tool, and core test runner. For lagging packages, verify whether peer dependencies or framework compatibility block an upgrade. Use installed dependency trees, plugin peer ranges, and registry metadata such as `npm ls <package>` and `npm view <package> peerDependencies --json`.
74
57
 
75
- For each assessed package, determine:
58
+ ### Contributor Activity and Delivery Cadence
76
59
 
77
- - installed/resolved version
78
- - latest published version
79
- - publish date of installed/resolved version
80
- - whether the package is behind latest major/minor/patch
60
+ Check the oldest reachable commit and `git rev-parse --is-shallow-repository` before scoring history. If the available history does not cover the assessment window, or a shallow checkout prevents verification, mark **both history criteria `N/A`**. Do not treat missing history as zero activity.
81
61
 
82
- ### 2. Core package currency
62
+ For the same assessment window, collect:
83
63
 
84
- Build a short list of core frontend packages for the detected stack. This should usually include:
64
+ - Unique authors, using git's mailmap-aware `%aN <%aE>` format.
65
+ - Total commits and merge commits across reachable refs.
66
+ - GitHub Releases published in the window, using `gh api repos/<owner>/<repo>/releases --paginate` when available. Distinguish a verified absence of releases (`0`) from unavailable release metadata; note tag-based or other release mechanisms. If release metadata cannot be verified, mark delivery cadence `N/A` and report the available commit/merge counts without scoring them.
85
67
 
86
- - one runtime/framework package
87
- - one router package if applicable
88
- - one build tool package
89
- - one test runner if the stack depends on it for core developer workflow
68
+ Use `git --no-pager log` and `git rev-list --count` with explicit date bounds and `--all`. Record the bounds and counts. Count contributors as a diversity signal, not a popularity measure.
90
69
 
91
- If a core package is not on the latest version, determine whether it is:
70
+ ### Test Suites and Coverage
92
71
 
93
- - intentionally blocked by a peer dependency or framework compatibility constraint
94
- - simply behind with no clear blocker
72
+ Identify configured unit, integration, component, end-to-end, and visual/Storybook checks from scripts, configuration, CI, and test files. Run existing commands only when needed to confirm the test surface or obtain coverage.
95
73
 
96
- Useful evidence sources:
74
+ Prefer existing frontend coverage artifacts and coverage-enabled targets over new instrumentation. Report the most relevant frontend application percentage, its metric (for example, lines or statements), and its source; do not substitute backend-only coverage. Note additional figures separately.
97
75
 
98
- - `npm view <package> peerDependencies --json`
99
- - `npm ls <package>`
100
- - framework/plugin package peer ranges
76
+ ### UI System and Component Library
101
77
 
102
- ### 3. Contributor activity
78
+ Inspect dependencies **and source usage** to establish:
103
79
 
104
- First determine whether the available git history spans at least three months by checking the oldest reachable commit (for example, `git log --all --format=%cI | sort | sed -n '1p'`) and whether the checkout is shallow (`git rev-parse --is-shallow-repository`). If it does, count unique contributors over the last three months:
80
+ - Component libraries and in-house design systems in use.
81
+ - Formal design token packages and theme definitions.
82
+ - Styling approaches, including CSS-in-JS authored in JavaScript/JSX; distinguish runtime-generated and compiled styles where evident.
83
+ - Consistency of component, token, and styling adoption across the scoped apps.
84
+ - Installed/latest versions, maintenance status, and deprecations, using metadata such as `npm view <package> deprecated --json`.
105
85
 
106
- ```bash
107
- git log --since="3 months ago" --format='%aN <%aE>' --all | sort -u
108
- ```
86
+ Treat CSS-in-JS as an approach, not a package category or an automatic scoring benefit. Assess its consistency, maintenance, and integration with the UI system.
109
87
 
110
- Use the unique author list count as the metric. This is a diversity signal, not a popularity contest. If the repository has less than three months of available history, or a shallow clone prevents confirming the history span, mark this criterion `N/A` rather than treating missing history as zero contributors.
88
+ ## 3. Primary User Journey
111
89
 
112
- ### 4. Three-month delivery cadence
90
+ Inspect routes/pages, UI components, and interaction logic to identify a representative user's main goal, starting point, and successful outcome. Map only verified steps, including important alternate, blocked, or recovery paths. Do not infer behavior or endpoints from names alone.
113
91
 
114
- For the last three months, count:
92
+ Prepare a Mermaid `journey` diagram organized into user-facing sections, with tasks in order, actor(s), and 1-5 experience ratings. Use observed UX evidence for ratings; otherwise use a neutral `3` and label it as an estimate. These experience ratings do not affect the assessment score.
115
93
 
116
- - commits
117
- - merges
118
- - releases
94
+ Associate verified API calls with journey tasks. List HTTP methods, routes, and service/base URLs where discoverable. Show environment variable names instead of secret values and mark unresolved destinations. If there is no verifiable user-facing journey or no endpoint calls, say so instead of inventing them.
119
95
 
120
- Prefer:
96
+ When a target URL and Chrome DevTools MCP are available, follow the authentication procedure below, then walk through the journey **before auditing performance**. Record an ordered replay plan with routes, actions, and expected page states. Avoid destructive actions, real purchases, or other consequential submissions without explicit authorization; record skipped steps. If browser access is unavailable, use the source-verified journey and label it as not browser-verified.
121
97
 
122
- ```bash
123
- git rev-list --count --since="3 months ago" --all
124
- git rev-list --count --merges --since="3 months ago" --all
125
- gh api repos/<owner>/<repo>/releases --paginate
126
- ```
98
+ ## 4. Optional Live-Site Performance
127
99
 
128
- Use GitHub Releases in the same three-month window where available. If there are no GitHub releases, record `0` and note if the repo appears to release by tags or another mechanism. If the repository has less than three months of available history, or a shallow clone prevents confirming the history span, mark this criterion `N/A` rather than treating unavailable history as zero activity.
100
+ ### Availability and Authentication
129
101
 
130
- ### 5. Test suites
102
+ - No URL: skip live measurement without changing the repository-only score.
103
+ - Chrome DevTools MCP unavailable: add a report note and leave Lighthouse unscored. Do not install tooling or substitute another browser.
104
+ - Login, SSO, or another authentication challenge during the walkthrough or either measurement: pause, ask the user to sign in manually in the MCP-controlled browser, and **wait for confirmation**. Do not request, enter, or store credentials or bypass access controls.
105
+ - After confirmation, verify the intended app page is available in the same authenticated session. Preserve session storage/cookies needed for access. If a test redirects to authentication, discard that test's results and rerun after access is restored; never score the login page as the target app. If access remains blocked, report the limitation and leave affected measurements unavailable.
131
106
 
132
- Determine whether the application uses automated tests and which layers exist:
107
+ ### Journey-Based Measurement
133
108
 
134
- - unit
135
- - integration
136
- - component
137
- - e2e
138
- - visual/storybook checks
109
+ After the walkthrough:
139
110
 
140
- Use repo configuration and scripts first. Only run existing test commands when needed to discover coverage or confirm a configured test surface.
111
+ 1. Inspect the available MCP capabilities. Use a journey-capable Lighthouse workflow when supported; otherwise combine a navigation audit with a journey trace where available. Do not assume every audit tool exposes a Performance category score.
112
+ 2. Use the supplied URL as the entry point and reuse the authenticated browser session. If the Lighthouse workflow supports journey interactions, replay the verified actions in order. If it only audits a single navigation, audit the entry page and replay the journey in the separate performance trace; clearly distinguish these scopes.
113
+ 3. When using a trace, keep it running through the replayed interactions, then stop it. Record completed/skipped steps and reasons, actual URLs, measurement date, browser/tool versions where available, device/viewport, throttling, and cache settings. Use consistent settings for comparable runs.
114
+ 4. Capture the Lighthouse **Performance category score (0-100)** when exposed. Do not derive it from unrelated audit categories, trace timings, or the three diagnostics below. An unavailable category score makes the optional criterion `N/A`, even if other diagnostics were captured.
115
+ 5. Report LCP, INP, and CLS with their source and units. Keep navigation/page results distinct in multi-page traces; do not combine unrelated pages into a synthetic metric. Distinguish lab/trace results from representative field data.
141
116
 
142
- ### 6. Coverage
117
+ ### Metric Breakdown (Diagnostic Only)
143
118
 
144
- Prefer existing coverage artifacts or CI/test configuration over inventing new instrumentation:
119
+ | Metric | Good | Needs improvement | Poor |
120
+ | ------ | --------- | ---------------------- | -------- |
121
+ | LCP | <= 2.5 s | > 2.5 s and <= 4 s | > 4 s |
122
+ | INP | <= 200 ms | > 200 ms and <= 500 ms | > 500 ms |
123
+ | CLS | <= 0.1 | > 0.1 and <= 0.25 | > 0.25 |
145
124
 
146
- - `coverage/` directories
147
- - CI settings
148
- - `jest` / `vitest` / `nyc` / `cypress` coverage configuration
149
- - existing `--coverage` scripts
125
+ List each metric's value, individual score when provided by the tool, and threshold rating. Convert tool-provided 0-1 metric scores to 0-100 and label the scale. If no numeric score is provided, report the threshold rating rather than inventing a numeric score.
150
126
 
151
- If multiple coverage figures exist, report the most relevant frontend application coverage and note any additional figures.
127
+ Rate INP only from representative field data (typically the 75th percentile across visits). A lab interaction can be reported as a diagnostic but does not establish field INP; mark unavailable field INP `N/A`. Never substitute Total Blocking Time (TBT) for INP. Explain that INP is not an input to Lighthouse's navigation Performance score, and the LCP/INP/CLS breakdown alone does not reconstruct that score.
152
128
 
153
- ### 7. UI system and component library
129
+ These diagnostics add **no assessment points**. Missing individual metrics do not change an available Lighthouse category score or its weight.
154
130
 
155
- Inspect the project dependencies and source code to identify and assess:
131
+ ## 5. Scoring
156
132
 
157
- - **Detected component libraries**: Name all UI component libraries in use (e.g. `@mui/*`, `antd`, `@chakra-ui/*`, `@mantine/*`, `@radix-ui/*`, `shadcn`, `@carbon/*`, `@fluentui/*`, `react-bootstrap`, in-house component library, etc.).
158
- - **Detected design tokens / theme libraries**: Identify design token packages and formal theme tokens (e.g. `style-dictionary`, `@tokens-studio/*`, dedicated token packages, CSS variables/theme definitions).
159
- - **Detected styling approach**: Inspect the source for CSS-in-JS usage—styling authored in JavaScript or JSX, such as style objects, tagged-template styles, or styling expressions—and note whether it is runtime-generated or compiled where evident. Treat CSS-in-JS as a coding approach, not a package category.
160
- - **Consistency**: Verify whether a **single component library** is used consistently across the application and whether the styling approach is consistent, or if multiple competing UI libraries or styling systems are mixed.
161
- - **Deprecation check**: Check if any detected UI library or token package is deprecated using `npm view <package> deprecated --json` or known deprecation status.
162
- - **Adoption & version currency**: Evaluate if the component library and design system are actively used across the app and on supported versions.
133
+ The repository criteria total **100 points**. Add the optional **20-point Lighthouse criterion** only when a URL was supplied and its Performance category score was obtained through Chrome DevTools MCP. Exclude both history weights when the assessment window cannot be verified.
163
134
 
164
- ## Scoring Rubric
135
+ Calculate `applicable_maximum` as the sum of weights for scored criteria, then `normalized_score = round(100 * earned_points / applicable_maximum)`. Report both the normalized score and raw earned/applicable points. For example, the maximum is 100 (80 without history), or 120 (100 without history) when Lighthouse is scored; exclude any other criterion marked `N/A` as well. Unavailable evidence is not a measured zero, but apply explicit rubric outcomes such as no measurable coverage found. If no criterion can be scored, report the assessment as unavailable instead of dividing by zero.
165
136
 
166
- Score each applicable criterion independently. When at least three months of history are available, score all criteria and sum to **100**. If less than three months of history are available (or a shallow clone prevents verifying the span), mark both history-based criteria as `N/A`, do not score them as zero, and exclude their combined 20 points from the denominator. Normalize the earned points against the remaining applicable maximum to produce a score out of 100, and report both the raw earned/available points and normalized score.
137
+ | Criterion | Weight | Scoring |
138
+ | ----------------------------------- | -----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139
+ | Dependency freshness | 20 | `round(20 * fresh_ratio)`. A package is fresh if it is latest or at most one minor behind within the same major, and its installed version was published within 183 days. Treat latest packages with no releases in 183 days as current rather than stale. `fresh_ratio` is the share of assessed packages meeting these rules. |
140
+ | Core package currency | 20 | `20`: all latest or latest compatible, with compatibility blockers verified and documented. Otherwise: `15` for patch/minor-only lag; `8` for exactly one unblocked one-major lag and no larger lag; `0` for multiple unblocked one-major lags or any unblocked lag of more than one major. Do not count verified latest-compatible packages as unblocked lag. |
141
+ | Contributors, assessment window | 10 | `10`: >= 4 contributors; `8`: 3; `6`: 2; `3`: 1; `0`: none. `N/A` if history is insufficient. |
142
+ | Delivery cadence, assessment window | 10 | Add commits (`>=50`: 4; `20-49`: 3; `5-19`: 2; `1-4`: 1; `0`: 0), merges (`>=15`: 3; `5-14`: 2; `1-4`: 1; `0`: 0), and releases (`>=2`: 3; `1`: 2; `0`: 0). `N/A` if history is insufficient or release metadata cannot be verified. |
143
+ | Test suite maturity | 10 | `10`: unit plus integration/e2e/component tests across meaningful flows; `7`: at least two test layers; `4`: one automated layer; `0`: no automated tests found. |
144
+ | Coverage | 10 | `10`: >= 80%; `8`: >= 70% and < 80%; `6`: >= 60% and < 70%; `3`: >= 40% and < 60%; `1`: > 0% and < 40%; `0`: zero or no measurable frontend coverage found. |
145
+ | UI system & component library | 20 | `20`: one modern component library, formal tokens, and consistent maintained styling; `15`: one consistent library with tokens/theme and minor lag or isolated deviations; `10`: one library without formal tokens, or a custom design system without a token library; `5`: competing libraries/styling systems, or a deprecated library with migration underway; `0`: primary UI is deprecated/unmaintained, severely fragmented, or lacks a component library/tokens. |
146
+ | Lighthouse Performance (optional) | 20 | `round(20 * lighthouse_performance_score / 100)`. No separate points for LCP, INP, or CLS. `N/A` if no URL, MCP access, or category score. |
167
147
 
168
- | Criterion | Weight | How to score |
169
- | ---------------------------------------- | -----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
- | Dependency freshness | 20 | `score = round(20 * fresh_ratio)` where `fresh_ratio` is the share of assessed packages that are both on latest version **or** at most one minor behind **and** whose installed version is not older than 183 days. If a package has had no release in the last 183 days at all, treat it as neutral rather than stale if the installed version is latest. |
171
- | Core package currency | 20 | `20` all core packages latest or latest compatible and blockers are documented; `15` only minor lag or documented peer/framework blockers; `8` one core package is one major behind without blocker; `0` multiple core packages are one major behind or any core package is more than one major behind without blocker. |
172
- | Contributors, last 3 months | 10 | `10` >= 4 contributors; `8` 3 contributors; `6` 2 contributors; `3` 1 contributor; `0` 0 contributors. Cap at 10 so very large teams do not dominate the score. If available history is shorter than three months or cannot be verified, mark `N/A` and exclude this weight from the score denominator. |
173
- | Last 3 months: commits, merges, releases | 10 | Score three sub-parts and add them: commits `0-4` (`>=50` = 4, `20-49` = 3, `5-19` = 2, `1-4` = 1, `0` = 0), merges `0-3` (`>=15` = 3, `5-14` = 2, `1-4` = 1, `0` = 0), releases `0-3` (`>=2` = 3, `1` = 2, `0` = 0). If available history is shorter than three months or cannot be verified, mark `N/A` and exclude this weight from the score denominator. |
174
- | Test suite maturity | 10 | `10` unit plus integration/e2e/component coverage across meaningful app flows; `7` at least two test layers; `4` one automated test layer only; `0` no automated tests found. |
175
- | Coverage | 10 | `10` >= 80%; `8` 70-79%; `6` 60-69%; `3` 40-59%; `1` 1-39%; `0` no measurable coverage found. Use the most relevant frontend coverage number, not backend-only coverage. |
176
- | UI system & component library | 20 | Assess the component library, tokens/theme, and styling approach (including CSS-in-JS) together. `20` single modern component library used consistently with formal design tokens and a maintained, consistent styling approach; `15` single component library used consistently with design tokens/theme and a maintained styling approach (minor lag or isolated deviations); `10` single component library without formal tokens OR custom design system without token library; `5` mixed/competing component libraries or styling approaches (fragmented UI) OR deprecated library with migration underway; `0` deprecated/unmaintained UI library as primary UI, severe library fragmentation, or no component library/tokens. CSS-in-JS use alone does not increase the score; assess its consistency, maintenance status, and integration with the UI system. |
148
+ Keep the rubric fixed and explain any necessary deviation. Do not invent missing evidence or hide major core-package problems. Repository age, complexity, and developer counts beyond the contributor criterion must not adjust this score.
177
149
 
178
- ## Repository Context Rubric
150
+ ### Separate Repository Context Score
179
151
 
180
- Report this context score separately. **Do not add it to or subtract it from the 100-point frontend assessment score.**
152
+ Report this context score independently; do not add it to or subtract it from the frontend assessment.
181
153
 
182
- | Context factor | Points | How to score |
183
- | ------------------- | -----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
184
- | Repository age | 0-3 | `0` < 3 months old; `1` 3-11 months; `2` 1-2 years; `3` >= 3 years. Use first commit date. |
185
- | Frontend complexity | 0-4 | `0` no clear frontend app; `1` exactly one frontend app/package and no shared frontend packages; `2` one deployable frontend app plus one or more shared frontend packages; `3` two or more frontend apps or a monorepo frontend workspace; `4` two or more deployable frontend apps plus shared frontend libraries or a design system package. |
186
- | Active developers | 0-3 | `0` 0 active contributors in last 12 months; `1` 1; `2` 2-3; `3` >= 4. Use the same contributor count as the main rubric. |
154
+ | Factor | Points | Scoring |
155
+ | ------------------- | -----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156
+ | Repository age | 0-3 | From the first commit: `0`: < 3 months; `1`: 3 to < 12 months; `2`: 1 to < 3 years; `3`: >= 3 years. Note unverified age in shallow checkouts. |
157
+ | Frontend complexity | 0-4 | `0`: no clear app; `1`: one app/package, no shared frontend packages; `2`: one deployable app plus shared frontend packages; `3`: multiple frontend apps or a frontend monorepo not meeting the next tier; `4`: multiple deployable apps plus shared frontend libraries or a design system. |
158
+ | Active developers | 0-3 | Use the same assessment-window contributor count: `0`: none; `1`: one; `2`: 2-3; `3`: >= 4. Mark `N/A` if the window cannot be verified. |
187
159
 
188
- ## Important Scoring Rules
160
+ ## Required Report
189
161
 
190
- 1. **Do not make up evidence.**
191
- 2. **Do not average away major problems.** If a core package is badly outdated, reflect that sharply.
192
- 3. **Do not over-penalize stable packages** that are latest even if the ecosystem has been quiet for more than 6 months.
193
- 4. **Penalize deprecated and fragmented UI libraries.** Using deprecated UI packages or mixing multiple competing component libraries directly reduces the UI system score.
194
- 5. **Reward consistent single component library and design token usage.** Full points require a single unified component library paired with a design system and token library.
195
- 6. **Keep the rubric fixed.** If you must diverge, explain exactly why.
196
- 7. **Do not use repository age, complexity, or team size to adjust the 100-point score.** Report them only in the separate repository context rubric.
197
-
198
- ## Required Output
199
-
200
- Return the assessment in this structure:
162
+ Keep the report concise, cite evidence, and use this order. The score summary is presented first for readability even though scoring happens after measurement.
201
163
 
202
164
  ### Scope
203
165
 
204
- - repository / app(s) assessed
205
- - assessment window (last three months)
206
- - detected stack
207
- - model(s) used to run the assessment; use the agent/model name if available, otherwise `Unknown`
208
- - detected UI system & component library: `<names of detected libraries or "None">`
209
- - detected design tokens / theme library: `<names of detected token packages or "None">`
210
- - detected styling approach, including any CSS-in-JS usage in JavaScript/JSX: `<brief description, or "None detected">`
211
-
212
- ### Score summary
166
+ State the repository/apps, exact assessment window, detected stack and package manager, UI libraries, tokens/theme, styling approach (including CSS-in-JS), and model(s) used (`Unknown` if unavailable). Include the target URL/MCP status and material evidence limitations.
213
167
 
214
- `Frontend assessment score: <total>/100`
168
+ ### Score Summary and Scoring Table
215
169
 
216
- If history-based criteria are `N/A`, also report the raw score and applicable maximum, for example: `Frontend assessment score: 90/100 (72/80 applicable points)`.
170
+ `Frontend assessment score: <normalized>/100 (<earned>/<applicable maximum> applicable points)`
217
171
 
218
- ### Scoring table
172
+ Use one row per scoring criterion above, followed by a total. Mark unavailable criteria `N/A` and explain their exclusion. Do not put LCP, INP, or CLS in this scoring table.
219
173
 
220
- | Criterion | Weight | Evidence | Score | Model(s) used | Notes |
221
- | ---------------------------------------- | ------------------------------: | ----------------------------------------------------------------------------------------------------- | -------------------------: | ------------- | ----- |
222
- | Dependency freshness | 20 | ... | ... | ... | ... |
223
- | Core package currency | 20 | ... | ... | ... | ... |
224
- | Contributors, last 3 months | 10 | ... | ... | ... | ... |
225
- | Last 3 months: commits, merges, releases | 10 | ... | ... | ... | ... |
226
- | Test suite maturity | 10 | ... | ... | ... | ... |
227
- | Coverage | 10 | ... | ... | ... | ... |
228
- | UI system & component library | 20 | ... (Names of used component libraries & token libraries, consistency status, and deprecation status) | ... | ... | ... |
229
- | **Total** | **100** (or applicable maximum) | ... raw earned/applicable points | **<normalized total>/100** | | ... |
174
+ | Criterion | Weight | Evidence | Score | Model(s) used | Notes |
175
+ | --------- | -----: | -------- | ----: | ------------- | ----- |
230
176
 
231
- ### Repository context score
177
+ ### Repository Context Score
232
178
 
233
- Report this separate context rubric. It must not affect the frontend assessment score:
179
+ List each context factor's evidence and score, plus raw earned/applicable context points (normally out of 10). Note that it is excluded from the frontend assessment score.
234
180
 
235
- | Context factor | Evidence | Score |
236
- | ----------------------- | ----------------------------------------- | -------------: |
237
- | Repository age | ... | ... |
238
- | Frontend complexity | ... | ... |
239
- | Active developers | ... | ... |
240
- | **Total context score** | Not included in frontend assessment score | **<total>/10** |
181
+ ### UI System & Component Library Status
241
182
 
242
- ### UI system & component library status
183
+ | Library / Package | Role (Components / Tokens / Styling) | Installed | Latest | Deprecated? | Consistency & Notes |
184
+ | ----------------- | ------------------------------------ | --------- | ------ | ----------- | ------------------- |
243
185
 
244
- Include a breakdown of detected UI component library and design token packages. Describe styling approaches—including any CSS-in-JS usage found in JavaScript/JSX—separately; do not report CSS-in-JS itself as a package.
186
+ Describe styling approaches separately from package names; CSS-in-JS itself is not a package.
245
187
 
246
- | Library / Package | Role (Component library / Tokens / Styling) | Installed version | Latest version | Deprecated? | Consistency & Notes |
247
- | ----------------- | ------------------------------------------- | ----------------- | -------------- | ----------- | ------------------- |
188
+ ### Core Package Status
248
189
 
249
- ### Core package status
190
+ | Package | Current | Latest | Status | Upgrade blocker? |
191
+ | ------- | ------- | ------ | ------ | ---------------- |
250
192
 
251
- Include a compact table for the detected core packages:
193
+ ### Frontend User Journey Diagram
252
194
 
253
- | Package | Current | Latest | Status | Blocked by dependency? |
254
- | ------- | ------- | ------ | ------ | ---------------------- |
195
+ Include the Mermaid `journey` diagram prepared in step 3, associated verified endpoints, and walkthrough limitations. Do not replace it with an architecture or API-plumbing diagram.
255
196
 
256
- ### Top 5 pros
197
+ ### Optional Live-Site Performance Results
257
198
 
258
- List the five strongest pros in ranked order:
199
+ Place results **after the journey**. If no URL was supplied, use one short note. Otherwise include:
259
200
 
260
- 1. ...
261
- 2. ...
262
- 3. ...
263
- 4. ...
264
- 5. ...
201
+ - Lighthouse Performance category score, the calculation `round(20 * score / 100)`, and earned points out of 20, or why the criterion is `N/A`.
202
+ - Measurement settings, replayed/skipped journey steps, audited pages, and the distinction between Lighthouse and trace scopes.
203
+ - The diagnostic table below. Mark missing values/scores `N/A`; missing diagnostics do not remove an available Lighthouse score. Do not imply that these three metrics sum to the category score.
265
204
 
266
- ### Top 5 cons
205
+ | Metric | Value and units | Individual score (0-100) | Threshold rating | Source / Page / Limitations |
206
+ | ------ | --------------- | -----------------------: | ---------------- | --------------------------- |
207
+ | LCP | ... | ... | ... | ... |
208
+ | INP | ... | ... | ... | ... |
209
+ | CLS | ... | ... | ... | ... |
267
210
 
268
- List the five most significant cons in ranked order:
211
+ ### Top 5 Pros and Top 5 Cons
269
212
 
270
- 1. ...
271
- 2. ...
272
- 3. ...
273
- 4. ...
274
- 5. ...
275
-
276
- ### Frontend business logic diagram
277
-
278
- Include a low-level Mermaid `flowchart` tracing the main frontend business flows from routes/pages and user actions through relevant components, state management, domain/business logic, and API/data-access layers to their data sources and endpoints. Show meaningful request/response or state transitions where they are evident from the code.
279
-
280
- - Inspect the frontend source, routing, state/data-fetching code, API clients, and configuration; represent only verified flows and label unknowns rather than inventing behavior.
281
- - Include backend services and other dependencies that are outside the assessed frontend code. For a monorepo, distinguish services/packages found elsewhere in the repository from services hosted outside the repository. Show external API/service endpoint names or URLs when discoverable; if configured via an environment variable, show the variable name (never its secret value) and mark the destination unresolved if necessary.
282
- - Keep the diagram focused on business logic and data flow rather than a generic infrastructure overview. Use Mermaid syntax in a fenced `mermaid` block.
213
+ Provide two ranked lists of the strongest evidence-backed advantages and highest-impact problems. If fewer than five are supported, say so rather than inventing findings.
283
214
 
284
215
  ### Verdict
285
216
 
286
- End with:
287
-
288
- - one short paragraph explaining what drove the score
289
- - one short paragraph naming the highest-leverage improvements
290
-
291
- If either history-based criterion is `N/A`, do not cite the overall score as being driven by contribution or delivery-cadence factors, and do not discuss those factors in the verdict. Base the verdict only on the scored criteria and note the unavailable history outside the verdict (in the scope or scoring table).
292
-
293
- ## Behavior Notes
294
-
295
- - Prefer repository-native commands and existing CI/test scripts.
296
- - Do not install new tooling just to produce the assessment.
297
- - For Nx workspaces, use `npm nx` / `npx nx` and existing targets rather than bypassing Nx.
298
- - Keep the result concise, but include enough evidence that another reviewer can reproduce the score.
217
+ End with two short paragraphs: what drove the score, then the highest-leverage improvements. Discuss only scored criteria as score drivers. If history criteria are `N/A`, keep unavailable contributor/cadence findings in the scope or scoring table, not the verdict.