github.com/BrowserWorks/Waterfox (link)

# Global instructions
Limit the amount of comments you put in the code to a strict minimum. You should almost never add comments, except sometimes on non-trivial code, function definitions if the arguments aren't self-explanatory, and class definitions and their members.

Do not remove existing comments unless they are directly related to what you are changing.

If you see a good first bug that isn't directly related to your work, don't hesitate to propose it as a good first bug (see the `file-good-first-bu

# Newtab Development

## Documentation
- Newtab source docs: https://firefox-source-docs.mozilla.org/browser/extensions/newtab/docs/index.html
- Design system tokens: https://firefoxux.github.io/firefox-desktop-components/ (visual reference), or locally: `toolkit/themes/shared/design-system/dist/tokens-shared.css`

## File Locations
Most of the code should be located in `browser/extensions/newtab`
- React components: `browser/extensions/newtab/content-src/components/`
- Styles (SCSS): `browser/extensions/ne

# AGENTS.md

This directory is **SpiderMonkey**, the JavaScript engine inside the
Firefox/Gecko monorepo in the parent directly. Project-wide instructions live
in `../AGENTS.md` (referenced from `../CLAUDE.md`). Notes below cover what is
specific to `js/`.

## Test workflow

Tests are run from the `js` test shell, not the browser. There are three suites:
 - **jit-test** (`src/jit-test/`) — JIT, GC, and engine internals, run with
     `mach jit-test`.
 - **jsapi-tests** (`src/jsapi-tests/`) — C++ tests o

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Build

NSS uses GYP + Ninja as its primary build system, driven by `build.sh` (or the `mach` wrapper):

```sh
./build.sh          # debug build → ../dist/Debug/
./build.sh -o       # optimized build → ../dist/Release/
./build.sh -c       # clean + build
./mach build        # equivalent wrapper
```

Common flags:
- `--asan` / `--msan` / `--ubsan` — sanitizer builds
- `--fuzz` / `--fuz

@AGENTS.md

@AGENTS.md

@AGENTS.md

name: Claude Code Review

on:
  # zizmor: ignore[dangerous-triggers]
  # pull_request_target is required to access secrets for fork PRs.
  pull_request_target:
    branches: ["main"]
    types: [opened, synchronize, ready_for_review, reopened]

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  claude-review:
    permissions:
      contents: read
      pull-requests: write # post review comments
      issues

# General workflow

@agents/prompts/common.md

# Codebase knowledge

@./g3doc/abseil-in-webrtc.md
@./g3doc/how_to_write_documentation.md
@./g3doc/implementation_basics.md
@./g3doc/style-guide.md

{
  "mcpServers": {
    "moz": {
      "type": "http",
      "url": "https://mcp-dev.moz.tools/mcp"
    }
  }
}

{
  "mcpServers": {
    "moz": {
      "type": "http",
      "url": "https://mcp-dev.moz.tools/mcp"
    },
    "firefox-devtools": {
      "type": "stdio",
      "command": "./mach",
      "args": [
        "--quiet",
        "devtools-mcp",
        "--pref",
        "remote.prefs.recommended=false",
        "--pref",
        "browser.smartwindow.enabled=true",
        "--enable-privileged-context",
        "--enable-script"
      ]
    }
  }
}

---
name: js-perf-investigation
description: >
  Structured performance opportunity investigation for SpiderMonkey (the Firefox JavaScript engine).
  Use this skill when the user wants to investigate JS engine performance, profile SpiderMonkey,
  find optimization opportunities, write performance patches, or evaluate benchmark regressions.
  Trigger on mentions of: profiling JS, SpiderMonkey performance, JIT optimization, benchmark
  regression analysis, shell benchmarking, or any request to make JS workloa

---
name: android-new-module
description: Guide for creating new Android gradle modules in the android-components project.
---

## Overview

This skill helps you create new Android gradle modules following Mozilla's conventions and structure. Components are organized into categories: `browser`, `concept`, `feature`, `lib`, `service`, `support`, `ui`, and `compose`.

## Component Categories

- **browser** - High-level browser components (engine, menu, state, etc.)
- **compose** - Jetpack Compose components
-

---
name: jj-split
description: Steps to reliably split a commit/change using the jj (jujutsu) VCS
allowed-tools:
  - Bash(jj log:*),
  - Bash(jj show:*),
  - Bash(jj split:*),
  - Bash(jj commit:*),
  - Bash(jj new:*),
  - Bash(jj describe:*),
  - Bash(jj rebase:*),
  - Bash(jj edit:*),
  - Bash(jj restore:*),
  - Bash(jj file show:*),
  - Read,
  - Grep,
  - Glob
---

# If the commit is to be split based on path

1. Identify the commit to split - Use jj log to find the revision ID of the commit you want t

---
name: jj-split
description: Steps to reliably split a commit/change using the jj (jujutsu) VCS
allowed-tools:
  - Bash(jj log:*),
  - Bash(jj show:*),
  - Bash(jj split:*),
  - Bash(jj commit:*),
  - Bash(jj new:*),
  - Bash(jj describe:*),
  - Bash(jj rebase:*),
  - Bash(jj edit:*),
  - Bash(jj restore:*),
  - Bash(jj file show:*),
  - Read,
  - Grep,
  - Glob
---

# If the commit is to be split based on path

1. Identify the commit to split - Use jj log to find the revision ID of the commit you want t

---
description: You MUST use this skill when working with HTML, JS, CSS and other front-end code.
---


## Workflow
- Whenever you're building, if `./mach build` was previously run and you have not made any changes to C++ or Rust code (nor rebased past incoming changes to such code), you can use `./mach build faster` to skip the compilation and linking steps and only build the front-end code. This can save a lot of time when you're only working on the browser/ or toolkit/ code.
- CSS should use reusable to

---
name: android
description: Workflow guide when working with Android builds or the mobile/ directory.
---

## Workflow
- Instead of `gradlew`, use `./mach gradle` as the wrapper. Use `-p` argument of gradle if you need to run in a subdirectory

---
description: You MUST use this skill when working with Firefox's linting infrastructure (mozlint), adding new linters, modifying existing linters, running linters, or dealing with linting issues.
---


## Overview
Firefox's linting infrastructure (mozlint) provides a unified way to run various linters across the codebase. It integrates multiple linters including ESLint, Stylelint, ruff, clippy, clang-format, and many others.

## Workflow
- Run `./mach lint` without arguments to lint all modified files i

---
name: accessibility-frontend-review
description: >
  Performs an accessibility code review of a local diff or Phabricator revision in the style of the
  Firefox accessibility team. Use this skill whenever the user asks to review a Phabricator
  patch or revision for accessibility issues, mentions a D-number (like D284142) in the
  context of accessibility review, asks "does this patch have any a11y issues", or wants
  to check a diff against accessibility guidelines. Also use it when the user says thing

---
name: js-perf-investigation
description: >
  Structured performance opportunity investigation for SpiderMonkey (the Firefox JavaScript engine).
  Use this skill when the user wants to investigate JS engine performance, profile SpiderMonkey,
  find optimization opportunities, write performance patches, or evaluate benchmark regressions.
  Trigger on mentions of: profiling JS, SpiderMonkey performance, JIT optimization, benchmark
  regression analysis, shell benchmarking, or any request to make JS workloa

---
name: android
description: Workflow guide when working with Android builds or the mobile/ directory.
---

## Workflow
- Instead of `gradlew`, use `./mach gradle` as the wrapper. Use `-p` argument of gradle if you need to run in a subdirectory

---
name: specmap
description: Map relationships between a web spec section, its Firefox implementation code, and Web Platform Tests. Use when starting work on a spec feature, checking implementation coverage, or finding which WPTs to enable.
argument-hint: "[spec-url-or-fragment] [optional: specific-algorithm]"
allowed-tools:
  - Bash(searchfox-cli:*)
  - Bash(webspec-index:*)
  - Bash(curl:*)
  - Bash(jq:*)
  - Read
  - Grep
  - Glob
---

# SpecMap: Spec-Code-WPT Mapping

**Spec URL or fragment**: $0
**Sp

---
name: reorganize-patches-for-review
description: Analyze a range of local commits, and reorganize them to minimize latency and friction in the review and landing process. To achieve this, commits can be split, reordered, squashed / grouped, or even rewritten. In the final commit series / "patch stack", the codebase should build, lint, and test cleanly after every commit, and each individual commit should stand on its own.
when_to_use: Before a patch (or a patch series) is submitted for first review, if 

---
description: You MUST use this skill when working with C++, C, Rust code to implement or modify WebIDL interfaces and their native implementations.
---


## Workflow
- When implementing or reviewing new web-exposed interfaces, compare the code against the specification. The relevant link should be in the .webidl file. When reviewing, explicitly check each method's implementation against the corresponding spec algorithm and note any discrepancies. If `webspec-index` is available, use `webspec-index query

---
description: Use this skill when working with Firefox documentation,
  including building documentation with `./mach doc`,
  fixing Sphinx build errors or warnings, modifying existing
  documentation, or adding new docs.
---

## Overview

Firefox documentation is built using **Sphinx**
through the `./mach doc` command. Documentation sources are distributed
throughout the repository and can be written in **reStructuredText
(`.rst`)** or **Markdown (`.md`)**.

The documentation system integrates:

-   Sph

---
name: android-new-module
description: Guide for creating new Android gradle modules in the android-components project.
---

## Overview

This skill helps you create new Android gradle modules following Mozilla's conventions and structure. Components are organized into categories: `browser`, `concept`, `feature`, `lib`, `service`, `support`, `ui`, and `compose`.

## Component Categories

- **browser** - High-level browser components (engine, menu, state, etc.)
- **compose** - Jetpack Compose components
-

---
name: stmo
description: >
  Manage Redash queries and dashboards on Mozilla's STMO (sql.telemetry.mozilla.org)
  using stmo-cli. Use when the user wants to explore telemetry data on STMO, write,
  deploy, or execute Redash queries, manage dashboards, or discover data sources.
  Also trigger on mentions of STMO, Redash, sql.telemetry.mozilla.org, or when the
  user wants to query Mozilla telemetry data (as opposed to probe/metric discovery,
  which is mozdata territory).
allowed-tools:
  - Bash(stmo-cli:

---
description: You MUST use this skill when working with Firefox's linting infrastructure (mozlint), adding new linters, modifying existing linters, running linters, or dealing with linting issues.
---


## Overview
Firefox's linting infrastructure (mozlint) provides a unified way to run various linters across the codebase. It integrates multiple linters including ESLint, Stylelint, ruff, clippy, clang-format, and many others.

## Workflow
- Run `./mach lint` without arguments to lint all modified files i

---
name: bug-filing
description: File a Bugzilla bug for Firefox/Gecko work, or draft a bug summary and description. Use when the user asks to file a bug, wants a bug summary/description for a change, or needs to report a defect/enhancement/task. Determines the product and component with `mach file-info`, drafts the summary and description, and opens a prefilled enter_bug.cgi form in the browser for the user to submit.
allowed-tools:
  - Bash(./mach file-info:*)
  - Bash(python3 .agents/skills/bug-filing/f

---
name: webspec-index
description: Use webspec-index to query WHATWG, W3C, IETF and TC39 web specifications from the command line
---

# webspec-index

Query WHATWG, W3C, IETF and TC39 web specifications from the command line.

Use `webspec-index` whenever you need to understand what a web spec says — algorithm steps, section content, cross-references, or whether a spec anchor exists. Specs are fetched and cached locally on first use.

## Available specs

Assume that all specs from WHATWG, W3C, IETF and

---
name: git-cl
description: Provides commands for interacting with Gerrit CLs using git cl, including issue management and non-interactive uploads.
---

# git cl Skill

This skill provides instructions and best practices for using `git cl` in WebRTC
development.

## Available Workflows

- **Uploading Changes**: For non-interactive uploads, handling chained branches,
  and presubmit warnings, see [references/upload.md](references/upload.md).

## Future Extensions

This skill can be extended to cover:

- `g

---
name: accessibility-frontend-review
description: >
  Performs an accessibility code review of a local diff or Phabricator revision in the style of the
  Firefox accessibility team. Use this skill whenever the user asks to review a Phabricator
  patch or revision for accessibility issues, mentions a D-number (like D284142) in the
  context of accessibility review, asks "does this patch have any a11y issues", or wants
  to check a diff against accessibility guidelines. Also use it when the user says thing

---
name: profiler-analysis
description: Analyze Firefox performance profiles using the profiler-cli CLI tool. Trigger when given a profiler.firefox.com or share.firefox.dev link, a local profile path, or when the user wants to investigate an issue in a Firefox profile. Always use this skill instead of WebFetch for Firefox profiler URLs; WebFetch only retrieves the profiler UI's HTML shell and cannot access profile data, whereas profiler-cli downloads and parses the actual profile into a local daemon that s

---
name: bug-filing
description: File a Bugzilla bug for Firefox/Gecko work, or draft a bug summary and description. Use when the user asks to file a bug, wants a bug summary/description for a change, or needs to report a defect/enhancement/task. Determines the product and component with `mach file-info`, drafts the summary and description, and opens a prefilled enter_bug.cgi form in the browser for the user to submit.
allowed-tools:
  - Bash(./mach file-info:*)
  - Bash(python3 .agents/skills/bug-filing/f

---
name: gn-check-autofix
description: Automatically fix GN check errors in WebRTC BUILD.gn files. Use when encountering "Include not allowed", "rtc_source_set shall not contain cc files", or when needing to clean up non-absolute dependencies.
---

# GN Check Autofix

This skill provides instructions for using `tools_webrtc/gn_check_autofix.py` to
automatically resolve common GN build configuration errors in WebRTC.

## Core Workflows

### Fix Missing Dependencies

When you see "Include not allowed" errors

---
description: Use this skill when the user wants to file good-first-bugs in Bugzilla for Firefox. A good-first-bug is a narrow, self-contained, low-risk task scoped so a first-time contributor can land it without deep context. Sources include lint warnings, small typos, dead-code removal, mechanical refactors, docs conversions, or any other small task the user points at. Produces prefilled `enter_bug.cgi` URLs the user clicks to submit. Trigger on phrases like "file a good first bug", "open good first bu

---
name: include-cleaner
description: Runs the WebRTC include-cleaner tool (IWYU replacement) to fix headers in C++ files. Use when preparing a CL for upload, after modifying .cc or .h files, or when instructed to fix include regressions.
---

# WebRTC Include Cleaner

This skill provides instructions for using
`tools_webrtc/iwyu/apply-include-cleaner`, a tool that automatically manages C++
`#include` directives in the WebRTC codebase. It ensures that every header used
is explicitly included and that unuse

---
name: hta-reviewer
description: Automated code review following Harald Alvestrand's (hta@) standards for WebRTC. Use this skill to analyze CLs for thread safety, process hygiene, architectural robustness, and modern C++ adoption.
---

# HTA Reviewer Skill

This skill adopts the "Reviewer's Lens" of Harald Alvestrand, a senior WebRTC
engineer. It provides direct, technical, and process-oriented feedback on code
changes.

## Core Mandates

### 1. Process Hygiene

- **Freshness**: Ensure the CL is rebased 

---
description: You MUST use this skill when working with C++, C, Rust code to implement or modify WebIDL interfaces and their native implementations.
---


## Workflow
- When implementing or reviewing new web-exposed interfaces, compare the code against the specification. The relevant link should be in the .webidl file. When reviewing, explicitly check each method's implementation against the corresponding spec algorithm and note any discrepancies. If `webspec-index` is available, use `webspec-index query

---
description: You MUST use this skill when working with HTML, JS, CSS and other front-end code.
---


## Workflow
- Whenever you're building, if `./mach build` was previously run and you have not made any changes to C++ or Rust code (nor rebased past incoming changes to such code), you can use `./mach build faster` to skip the compilation and linking steps and only build the front-end code. This can save a lot of time when you're only working on the browser/ or toolkit/ code.
- CSS should use reusable to

---
name: specmap
description: Map relationships between a web spec section, its Firefox implementation code, and Web Platform Tests. Use when starting work on a spec feature, checking implementation coverage, or finding which WPTs to enable.
argument-hint: "[spec-url-or-fragment] [optional: specific-algorithm]"
allowed-tools:
  - Bash(searchfox-cli:*)
  - Bash(webspec-index:*)
  - Bash(curl:*)
  - Bash(jq:*)
  - Read
  - Grep
  - Glob
---

# SpecMap: Spec-Code-WPT Mapping

**Spec URL or fragment**: $0
**Sp

---
description: Use this skill when working with Firefox documentation,
  including building documentation with `./mach doc`,
  fixing Sphinx build errors or warnings, modifying existing
  documentation, or adding new docs.
---

## Overview

Firefox documentation is built using **Sphinx**
through the `./mach doc` command. Documentation sources are distributed
throughout the repository and can be written in **reStructuredText
(`.rst`)** or **Markdown (`.md`)**.

The documentation system integrates:

-   Sph

---
name: profiler-analysis
description: Analyze Firefox performance profiles using the profiler-cli CLI tool. Trigger when given a profiler.firefox.com or share.firefox.dev link, a local profile path, or when the user wants to investigate an issue in a Firefox profile. Always use this skill instead of WebFetch for Firefox profiler URLs; WebFetch only retrieves the profiler UI's HTML shell and cannot access profile data, whereas profiler-cli downloads and parses the actual profile into a local daemon that s

---
name: stmo
description: >
  Manage Redash queries and dashboards on Mozilla's STMO (sql.telemetry.mozilla.org)
  using stmo-cli. Use when the user wants to explore telemetry data on STMO, write,
  deploy, or execute Redash queries, manage dashboards, or discover data sources.
  Also trigger on mentions of STMO, Redash, sql.telemetry.mozilla.org, or when the
  user wants to query Mozilla telemetry data (as opposed to probe/metric discovery,
  which is mozdata territory).
allowed-tools:
  - Bash(stmo-cli:

---
name: gtest-parallel
description: Run Google Test binaries in parallel using the gtest-parallel script. Use when needing to speed up test execution, run flaky tests with repeat, or filter specific tests.
---

# gtest-parallel

`gtest-parallel` is a script that executes Google Test binaries in parallel,
providing speedup for single-threaded tests and tests that do not run at 100%
CPU.

## Location

The script is located at `third_party/gtest-parallel/gtest-parallel`.

## Core Flags

### Filtering Tests

---
name: webspec-index
description: Use webspec-index to query WHATWG, W3C, IETF and TC39 web specifications from the command line
---

# webspec-index

Query WHATWG, W3C, IETF and TC39 web specifications from the command line.

Use `webspec-index` whenever you need to understand what a web spec says — algorithm steps, section content, cross-references, or whether a spec anchor exists. Specs are fetched and cached locally on first use.

## Available specs

Assume that all specs from WHATWG, W3C, IETF and

---
name: reorganize-patches-for-review
description: Analyze a range of local commits, and reorganize them to minimize latency and friction in the review and landing process. To achieve this, commits can be split, reordered, squashed / grouped, or even rewritten. In the final commit series / "patch stack", the codebase should build, lint, and test cleanly after every commit, and each individual commit should stand on its own.
when_to_use: Before a patch (or a patch series) is submitted for first review, if 

---
description: Use this skill when the user wants to file good-first-bugs in Bugzilla for Firefox. A good-first-bug is a narrow, self-contained, low-risk task scoped so a first-time contributor can land it without deep context. Sources include lint warnings, small typos, dead-code removal, mechanical refactors, docs conversions, or any other small task the user points at. Produces prefilled `enter_bug.cgi` URLs the user clicks to submit. Trigger on phrases like "file a good first bug", "open good first bu