webhint for Browser-Facing Frontends in .NET Repositories

Trigger On

• the repo ships a browser-facing site and the user asks about accessibility, performance, SEO, security headers, or page quality
• the repo has

  .hintrc

  ,

  hint

  scripts, or a served local frontend that should be audited
• the team needs more than syntax linting and wants runtime-oriented site checks

Do Not Use For

• JavaScript or TypeScript semantic linting; route that to

  dotnet-eslint

  or

  dotnet-biome

• stylesheet-only linting; route that to

  dotnet-stylelint

• static HTML structure checks alone; route that to

  dotnet-htmlhint

Inputs

• the nearest

  AGENTS.md

• package.json

• .hintrc

  if present
• the real audit target: local dev URL, preview URL, deployed URL, or built output

Workflow

1. Choose the audit surface deliberately:
   • running local URL such as

     https://localhost:3000

   • preview or deployed URL
   • local connector against built output when no browser runtime is needed
2. Prefer repo-local installation and a checked-in

   .hintrc

   .
3. Start from a documented preset such as

   web-recommended

   , then customize only for real repo requirements.
4. Add repeatable scripts to

   package.json

   , for example:

   • hint https://localhost:3000

   • hint https://example.test --config .hintrc

5. Keep runtime prerequisites explicit:
   • supported Node.js version
   • browser availability when the connector needs Chromium-based automation
6. Treat findings as categorized work:
   • headers and transport
   • accessibility and HTML issues
   • performance
   • PWA and manifest signals
7. Re-run the audit after fixes on the same URL or build output so results are comparable.

Bootstrap When Missing

1. Detect current state:

   • rg --files -g 'package.json' -g '.hintrc*'

   • rg -n '"hint"' --glob 'package.json' .

2. Prefer a repo-local install:

   • npm install --save-dev hint

3. Create or refine

   .hintrc

   with a known baseline such as

   web-recommended

   .
4. Add repeatable commands to

   AGENTS.md

   and

   package.json

   , then verify with:

   • npx hint https://localhost:3000

   • npx hint -c ./.hintrc https://example.com

5. Return

   status: configured

   if the repo now has a working site-audit gate, or

   status: improved

   if the baseline was tightened.
6. Return

   status: not_applicable

   when the repo does not expose a stable browser-facing surface that can be audited in the current task.

Handle Failures

• Missing-browser errors usually mean the environment lacks Chrome, Chromium, or Edge for the selected connector.
• WSL is a poor default for browser-backed runs; prefer a native environment or switch to a

  jsdom

  -style connector when appropriate.

• EACCES

  or install-permission failures are usually fixed by installing

  hint

  as a repo devDependency instead of relying on a global tool.
• If the audit target is unstable, authenticated, or still booting, fix the serving workflow first; otherwise the noise is not actionable.

Deliver

• a repeatable webhint audit command and config
• a stable target URL or build-output strategy
• categorized runtime-quality findings the team can act on

Validate

• the audited target matches the site that actually ships
• browser or connector prerequisites are documented
• webhint is not being used as a substitute for ESLint or Stylelint
• reruns on the same target produce consistent comparisons

Ralph Loop

1. Plan: analyze current state, target outcome, constraints, and risks.
2. Execute one step and produce a concrete delta.
3. Review the result and capture findings.
4. Apply fixes in small batches and rerun checks.
5. Update the plan after each iteration.
6. Repeat until outcomes are acceptable.
7. If a dependency is missing, bootstrap it or return

   status: not_applicable

   with a reason.

Required Result Format

• status

  :

  complete

  |

  clean

  |

  improved

  |

  configured

  |

  not_applicable

  |

  blocked

• plan

  : concise plan and current step

• actions_taken

  : concrete changes made

• verification

  : commands, checks, or review evidence

• remaining

  : unresolved items or

  none

Example Requests

• "Run webhint against the local frontend before release."
• "Add accessibility and security-header audits for this site."
• "Why does webhint fail in CI but not locally?"