access-control-safety-testingUse when writing or reviewing the must-fail fixture for a gate that bans direct role or permission membership checks — an ESLint `no-restricted-syntax` selector, a dependency-cruiser rule, or a hand-rolled permission validator. Symptoms include a fixture that seeds only `.includes()`, a role check t
accessibility-auditAdversarial, authorized accessibility deep-audit loop for a React frontend you own — fans out one accessibility-auditor subagent per WCAG 2.2 principle / a11y family in parallel, each probing the RUNNING stack (axe-core on the rendered DOM, keyboard-only traversal, and accessibility-tree / accessibl
adding-ci-gatesUse when adding new CI checks or gates to a repository — batching several gate tickets onto one branch, deciding whether a gate ships now or is deferred, re-checking a gate design against the live main branch instead of a stale ticket snapshot, giving a new gate script a must-fail fixture, or handli
api-extractor-forgotten-export-resolutionUse when a library build prints `Warning: (ae-forgotten-export) The symbol "X" needs to be exported by the entry point`, when a published `.d.ts` rollup shows props as `any` or as an opaque generated alias, or when adding a component whose prop type is declared in a sibling `types.ts` and must reach
architectural-reconciliationUse when merging a long-lived feature branch whose conflicts are architectural rather than textual — the branch built a route manifest while the base adopted a route registry, reads `process.env` directly while the base adopted a typed env layer, or news up a service while the base moved to a DI com
architectureCapture the modular (bulletproof-react) frontend architecture - module/feature layering, the Component -> Hook -> Repository -> API flow, dependency-cruiser import boundaries, and path-alias conventions. Use when placing a feature, component, hook, store, or repository, deciding which layer a file b
aria-label-split-text-renderingUse when one text value is rendered across two or more elements for styling — a typed prefix in one ink and the completion in another, a highlighted search match, a two-tone label — and a getByRole query for an option by its visible name fails, an accessible name comes back with an extra or missing
auth-testing-with-seeded-tokensUse when writing browser tests for sign-in redirects, protected-route bounces or destination-preservation in a repository whose production-parity test image seeds every visitor with an auth token for Lighthouse and Playwright runs. Symptoms include an end-to-end spec that can never reach the logged-
barrel-export-validation-testingUse when writing or repairing a test that guards a public barrel — an index that re-exports components and their prop types — and the guard parses export lines with a regex, checks names with a loose "ends with Props" filter, or relies on runtime key inspection that cannot see type-only exports. Als
batch-implementation-triageUse when a list of open GitHub issues has to be filtered before automated or batch implementation — separating issues already landed on main, issues an open pull request already claims, issues whose scope is UI/UX and needs a design gate, and issues that are destructive or change live repository set
bats-fixture-full-validationUse when a Bats helper, stub or fixture in `tests/bats/` has been edited and the change is about to be staged. Symptoms include a filtered `bats -f "pattern"` run passing while the full suite fails, a helper name defined twice in one file, and a ShellCheck `SC2329` unreachable-function warning on th
bats-test-workflowUse when writing, running, or debugging Bats tests for infrastructure code — Makefile targets, shell scripts under the scripts and CI-scripts directories, jq filters, git hooks, and CI helpers. Triggers include a failing Bats suite target, a regression test that still passes on the buggy code, a stu
bmad-autonomous-planningCreates the full BMAD planning artifact chain (research, brief, PRD, architecture, epics/stories, readiness) autonomously from a short task description or GitHub issue for a React/TypeScript frontend, delegating each planning phase to a focused subagent and orchestrating the handoffs without human i
bmad-fr-nfr-review-gateRun the mandatory BMAD FR/NFR post-implementation review gate for React/TypeScript frontend work — on every pull request — that blocks completion until every requirement row scores 5/5 and the gate reports zero new findings. Use when any GitHub PR, feature, bugfix, or task needs verification — again
ci-infrastructure-failure-diagnosisUse when a CI job fails for infrastructure reasons rather than code — a sandbox or deploy check dying in a cloud pipeline-start call, "PR number extraction failed", cloud-credential configuration auth errors, a job firing on the wrong event, a fork pull request triggering a privileged job, or a Dock
ci-infrastructure-refactoringUse when refactoring how CI executes rather than what it checks — moving a gate between host and container, changing compose service orchestration, altering how a workflow invokes a make target, or adding a CI-only compose overlay. Covers the runner-only defect classes (bind mounts hiding installed
ci-single-check-validationUse when exactly one CI check on a pull request is red while the rest are green — a code-quality or code-scanning check, one Playwright shard, one lint or mutation job — and the failure looks transient (timeout, plugin crash, post-analysis upload error) rather than caused by the diff. Covers how to
ci-workflowRun the full local frontend CI suite through the profile's make target map and drive every check to green before committing. Use when the user asks to run CI, run quality checks, validate frontend code quality, or before finishing any task that touches React/TypeScript/MUI code.
code-organizationEnforce frontend code organization — bulletproof-react ownership-first placement, the allowed-folder law (a folder holds only the kind of thing its name promises), kebab-case file naming with PascalCase / UI* identifiers, type-only files, classes-only / no-static-or-free-functions outside React, pat
code-reviewSystematically retrieve, categorize, and address PR code review comments with an auditable evidence ledger — AI review loop, per-comment commits, suppression-free fixes, and pushed-head verification of required checks and approval. Use when handling code review feedback, addressing PR comments, or d
codeql-cache-corruptionUse when a CodeQL analysis step fails with "Invalid checksum for page N of the compressed relation ... The database is corrupt and should be re-created", when one branch reddens the security-testing workflow identically on every re-run while other branches stay green, or when reviewing an actions/ca
complexity-managementMaintain and improve React/TypeScript code quality with the rust-code-analysis metrics gate by refactoring code instead of relaxing configuration, keeping every metric at or under its policy ceiling (and Maintainability Index at or above its floor). Use when the metrics gate fails, a component body
compliance-drift-guardUse when governance evidence lives in markdown — a component provenance registry, a deviation ledger, a definition-of-done compliance matrix, a coverage manifest — and nothing stops it going stale, such as rows citing deleted files, unknown status tokens, roll-up counts that no longer match, or code
configuration-managementUse when adding, renaming or reading an environment variable, extending the typed config layer, or diagnosing a build that fails at boot with a schema error. Triggers include "add an env var", reading a NEXT_PUBLIC_* or REACT_APP_* value, an ESLint no-restricted-syntax error naming process.env, a Zo
deferred-di-reflect-metadata-optimizationUse when a tsyringe application loads its DI container behind a dynamic `import()` and the eager entry bundle still pulls in `reflect-metadata`, or when a mobile Lighthouse performance budget is short by a few hundredths. Symptoms include `import 'reflect-metadata';` on the first line of the client
depcruise-rule-alternative-disjointnessUse when an architecture rule is written as several alternatives that must each be provable — a dependency-cruiser rule in `.dependency-cruiser.js`, or an esquery `no-restricted-syntax` union of import shapes — and a must-fail fixture for one alternative still passes after that alternative is delete
dependency-cve-gateUse when a dependency-CVE gate fails a pull request, when adding or renewing an entry in an osv-scanner ignore policy, or when designing, reviewing or porting such a gate. Triggers include "CVE gate", "osv-scanner", "dependency vulnerability", a GHSA or CVE id reported against a lockfile, an expired
dependency-upgrade-troubleshootingUse when a dependency bump reddens CI rather than the code — Playwright reporting "Executable doesn't exist at", a Stryker shard dying with MODULE_NOT_FOUND on `testEnvironment`, dozens of visual snapshots diffing by a pixel with no UI change, baselines that pass then fail after an image-compression
docker-dev-rebuild-after-migrationUse when the dev container behaves as though it is running older code after a Dockerfile, base image, Node version or package-manager change — "command not found" or exit 127 for a tool the Dockerfile installs, "Cannot find module" or HTTP 500 from the dev server despite the module being present, a
documentation-creationCreate a comprehensive frontend project documentation suite from scratch by analyzing the React/TypeScript codebase and verifying every claim against it. Use when setting up INITIAL documentation for a project or building a complete docs/ suite where none exists. NOT for updating existing docs (use
documentation-syncKeep project documentation in sync with code changes. Use when implementing React components, modifying hooks or GraphQL operations, changing module architecture, adding configuration, updating auth flows, or making any change that affects user-facing or developer-facing documentation. Not for build
editorconfig-cyrillic-triageUse when a reviewer, bot, or editorconfig-checker reports a line over max_line_length while Prettier reports the file as formatted, and the line contains Cyrillic or other multi-byte UTF-8 text — Ukrainian labels, story args, i18n literals. Also when deciding whether to wrap such a line or to reply
eslint-config-parity-checkUse when changing ESLint configuration rather than code — dropping or replacing a shared preset, migrating to flat config, upgrading eslint or a plugin major, consolidating rules into an inline rules block, or reordering config objects — and before merging any config-only change. Triggers include "e
figma-design-checkVerify a planned or completed UI change against the Figma design via the Figma MCP before writing or editing component, layout, color, spacing, typography, sizing, or interaction-state code. Use when building or changing any visual surface and a Figma reference exists. Gated by capabilities.figma —
figma-design-review-before-codeUse when a component's Figma design must be reviewed BEFORE any code exists — a new UI component, a design handoff, a spec artifact, or a request to review a design against the existing components. Symptoms include no implementation file yet, only a Figma node id or a spec markdown, and open questio
frontend-component-developmentBuild or change React components, hooks, forms, and feature UI through the profile — reusable components carry the configured prefix, styling uses the configured UI library (MUI v7 + Emotion) and theme tokens, selectors stay semantic (no data-testid), and accessibility is non-negotiable. Use when bu
frontend-performance-accessibilityHold a React frontend to its Lighthouse performance budgets (desktop 95 / mobile 85, integer-percent floors mapped by quality.lighthouse_desktop and quality.lighthouse_mobile), keep web-vitals, bundle size, and code-splitting healthy, defend deferred-DI render paths, and meet WCAG 2.2 AA accessibili
frontend-quality-workflowRun and fix the frontend static-quality lane — formatting, ESLint, TypeScript, markdownlint, jscpd duplication, and rust-code-analysis metrics — through the profile's make target map, raise-only and with no suppressions. Use when the user asks to format code, run lint, fix ESLint/TypeScript/markdown
frontend-testing-workflowAuthor and maintain frontend tests — Jest unit suites (jsdom client + node server), Testing Library semantic queries, Playwright E2E and visual regression, seeded Faker builders, and mutation-killing assertions. Use when writing, structuring, or fixing Jest, Testing Library, Playwright, or visual te
github-actions-workflow-authoringUse when a GitHub Actions workflow carries an `on.pull_request.paths` or `on.push.paths` filter and the gate can skip itself — a required check reporting success with zero jobs executed, review feedback that the filter omits the workflow's own build inputs, a path entry left pointing at a renamed sc
github-pr-merge-readiness-auditUse when deciding whether one or several open pull requests can merge — a PR shows green checks but will not merge, an AI reviewer approval was dismissed after a merge commit, an approval sits on a stale head SHA, `mergeStateStatus` reports BLOCKED, commitlint failed on a title, or a batch of PRs ne
github-pr-workflow-approval-gateUse when a pull request will not merge although no check has failed, a workflow run sits in `action_required` or shows as waiting for approval, required checks never report at all after a push, or the checks page looks green while merge status stays pending. Also when sweeping approvals for runs acr
graphql-api-hardeningUse when editing an Apollo Server mock or any GraphQL resolver, error formatter, validation rule, or response shape, and when changing the pinned upstream API service version. Triggers include createUser or clientMutationId handling, formatError, validationRules, parseOptions, includeStacktraceInErr
host-stack-infrastructureUse when adding or changing how a browser or memory-leak suite is executed — a host-built export instead of the Docker prod stack, a new executor mode, or a Makefile switch. Triggers on "run e2e without Docker", unexplained visual-baseline diffs, an unreachable Docker daemon, or any proposal to key
husky-pre-commit-bypassUse when a Husky hook drags files the change never touched into a commit or rejects it for unrelated code — a `.husky/pre-commit` running the repository formatter followed by `git add -A`, `git status` showing modified spec, source, or config files outside the intended scope after a failed commit, a
integration-singleton-isolationUse when an integration or unit test mutates module-level state that outlives it, such as `await import('@/…')` for a side effect, a `bind*` or `set` call on an `export default new …` singleton, or an assignment to `process.env`, and the file has an ordering dependency — adding a case breaks a previ
jest-dom-aria-assertion-patternUse when a component test asserts on ARIA attributes and ESLint reports jest-dom/prefer-required or jest-dom/prefer-to-have-attribute, when toBeRequired() cannot distinguish native required from aria-required, or when mutants inside aria-describedby / aria-required computation survive DOM assertions
jsdom-mui-mutation-trapsUse when mutants in MUI component styling or controlled-value handling survive despite tests that look like they cover the behaviour, when a test reads getComputedStyle on an Emotion styled element under jsdom, or when a mutation score stalls below the gate after adding coverage.
lint-rule-pattern-verificationUse when a gate matches source with a regex or an AST selector — a check script under `scripts/ci/`, an esquery `no-restricted-syntax` entry, a drift guard that greps source for a helper call — and it may miss a spelling (bracket access, quoted or shorthand key, namespace import) or count a commente
load-testingCreate and manage K6 load tests for the key user journeys of a React frontend SPA. Use when creating load tests, writing K6 scripts, testing page-load and sign-up flow performance, debugging load-test failures, or setting up performance-under-load monitoring. Covers journey scripts, deterministic VU
make-target-maintenanceUse when a Makefile target and its coverage manifest have drifted apart — the `bats` check failing with a `diff` between the Makefile target list and the target column of `tests/bats/make-target-coverage.tsv`, a manifest row whose `evidence` file does not exist or never names the target as a whole t
mui-autocomplete-freesolo-ghost-textUse when a MUI Autocomplete in freeSolo mode needs inline typeahead and the native autoComplete or autoHighlight props do nothing, or when completed text concatenates onto what the user typed instead of replacing it. Also for search, select, or multi-select combobox fields that must show a grey inli
mutation-gate-barrel-leaf-extractionUse when a leaf helper — a style map, a predicate, or a formatting function — lives inside one component directory but is imported from other directories through that component's barrel, so the mutation runner's findRelatedTests pulls that component's whole suite set into every mutant run for the co
mutation-shard-capacity-growthUse when a Stryker mutation shard approaches or exceeds an already-calibrated CI timeout-minutes because the mutate scope grew, when shard wall clocks are badly uneven under byte-weighted packing, or when a change proposes raising that cap instead of raising MUTATION_SHARD_TOTAL and the matrix index
mutation-test-barrel-import-trapUse when one test suite re-runs for mutants in unrelated components and the mutation gate times out or drags, or when a source module imports from an aggregate barrel such as the components index (`@/components`) instead of the target component's own entry.
mutation-testing-stryker-gotchasUse when a Stryker survivor cannot be explained by a missing assertion — a mutant reported `Survived` with an empty `killedBy` or `testsCompleted` of zero, a `Stryker disable next-line` comment that never turns a mutant `Ignored`, an `ArrayDeclaration` mutant on a React hook dependency array, a merg
observability-instrumentationAdd type-safe client-side telemetry for user-impacting frontend signals — error boundaries, captured exceptions, web-vitals, and Apollo/HTTP failures — emitted to a real RUM/Sentry sink when `capabilities.observability` is true, or through a deferred structured-log sink otherwise. Use when adding fr
parser-library-preferenceUse when a CI gate, validation script, or config check reads YAML, JSON, TOML, or XML with `grep`, `sed`, or hand-written regex. Triggers on fail-open gate bugs, quoted or escaped keys, spaced colons, block scalars swallowing sibling keys, and repeated "fix the regex spelling" patches to the same sc
performance-budget-calibrationUse when a byte budget is calibrated against the wrong unit and therefore cannot fire — setting or reviewing a Lighthouse `resource-summary` script or total size assertion, a gzip entrypoint or per-chunk ceiling, or a bundler size hint; a budget that has never failed while a real regression shipped;
playwright-mobile-device-laneUse when adding or extending real mobile-device coverage to a Playwright suite — touch/tap specs, Pixel or iPhone device descriptors, `isMobile`/`hasTouch` contexts, device-pixel-ratio visual baselines — or when mobile specs re-run under every desktop project, snapshot directories fill with duplicat
playwright-visual-baseline-grep-titleUse when a Playwright run filtered with -g / --grep exits 0 but an expected visual baseline PNG was never written, when a snapshot filter has to match a title containing spaces or a separator, or when regenerating a subset of visual baselines.
pr-batch-merge-validationUse when several open pull requests are queued to land and the question is which of them can go in together. Triggers on stale branches behind `main`, "does this batch conflict?", a clean local merge that still reds the pipeline, a gate that only exists on `main`, and any plan to rebase a branch tha
qlty-eslint-runtime-mismatchUse when a Qlty check is red with "Build errored. Check the log for more information." and the cloud build log ends in linter stderr rather than findings — an ESLint version banner followed by "Error while loading rule 'react/display-name'; contextOrFilename.getFilename is not a function" — or after
qlty-local-check-ts-sandbox-false-positiveqlty-transient-build-errorquality-standardsrca-component-structuringreact-ref-callback-cleanupretriggering-ai-reviewsreview-thread-resolution-workflowrsbuild-dev-server-containerized-cishared-module-extractionshell-command-verification-robustnessstorybook-controlled-componentsstorybook-dev-host-launchstorybook-dev-server-visual-test-stalenessstorybook-figma-auditstorybook-file-pattern-syncstorybook-story-authoringstorybook-visual-state-nested-propsstryker-mutation-timeout-regression-alarmtest-discovery-contracttest-naming-and-fixture-claritytesting-workflowtwo-colour-focus-ringuri-path-validation-normalization