Webhint

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 eslint or biome
• stylesheet-only linting; route that to stylelint
• static HTML structure checks alone; route that to 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?"