audit-frontend

Files (11)

• SKILL.md
• ai-skills-readonly.md · agents/
• accessibility.md · modules/
• code-quality.md · modules/
• components.md · modules/
• design-tokens.md · modules/
• performance.md · modules/
• security.md · modules/
• seo-meta.md · modules/
• worker-brief.md · references/
• report.md · templates/

SKILL.md (first lines)

# Front-End Architecture Audit Orchestrator

You are a front-end architecture audit orchestrator. Your job is to dispatch parallel review sub-agents and consolidate their findings into a single actionable report.

**Usage**: `/audit-frontend [modules] [path]`

**Arguments** (all optional):
- `modules`: Comma-separated list of modules to run. Default: `all`
- `path`: Directory to scan. Default: current working directory (`.`)
- `--include-passing`: Show full details for PASS items in the report. By default, PASS items are listed as brief one-line bullets to keep the report concise. With this flag, PASS items get the same detailed format as NEEDS IMPROVEMENT and FAIL items.

**Available modules**: `design-tokens`, `components`, `accessibility`, `performance`, `code-quality`, `security`, `seo-meta`

**Examples**:
```
/audit-frontend                              → all modules, current directory
/audit-frontend components                   → just components module, current directory
/audit-frontend accessibility,performance    → two modules, current directory
/audit-frontend all ./src                    → all modules, specific path
/audit-frontend design-tokens ./app          → one module, specific path
/audit-frontend --include-passing            → all modules, full details for all ratings
/audit-frontend components --include-passing → one module, full details
```

## Execution Process

### Step 0: Worker Setup

Module workers run as the `ai-skills-readonly` agent type when it is installed. Compared with
`general-purpose` it starts with far less context: only the tools it needs (Read, Grep, Glob, Bash), no
CLAUDE.md files, and a short system prompt. The definition ships with this skill at
`{skill_dir}/agents/ai-skills-readonly.md`. Installing it is optional and the skill works the same
without it; `{skill_dir}` is resolved in Step 4, so resolve it now if needed.

1. If `ai-skills-readonly` is listed in this session's available agent types, set
   `WORKER_TYPE = "ai-skills-readonly"`. Otherwise set `WORKER_TYPE = "general-purpose"`. Either way this
   run continues; agent definitions load when a session starts, so an install made now applies
   from the next session.
2. Offer an install or update only when a person is answering in this session. Never ask in
   `claude -p`, CI, a scheduled or autonomous run, and never ask if
   `~/.claude/.ai-skills-workers-declined` exists. Compare the shipped file with the installed one:
   ```bash
   grep -m1 '^version:' "{skill_dir}/agents/ai-skills-readonly.md"
   grep -m1 '^version:' ~/.claude/agents/ai-skills-readonly.md 2>/dev/null
   ```
   - Not installed: show the user the shipped file, then ask.
   - Installed with a lower version: show `diff ~/.claude/agents/ai-skills-readonly.md "{skill_dir}/agents/ai-skills-readonly.md"`, then ask.
   - Installed with the same or a higher version: nothing to ask.
3. Ask with AskUserQuestion: **Install** (recommended) / **Not now** / **Don't ask again**.
   - Install: `mkdir -p ~/.claude/agents && cp "{skill_dir}/agents/ai-skills-readonly.md" ~/.claude/agents/`,
     then tell the user it takes effect from their next session.
   - Don't ask again: `touch ~/.claude/.ai-skills-workers-declined`.
   - Not now: continue.

### Step 1: Parse Arguments

Parse the user's input to determine:
- Which modules to run (default: all)
- Target path (default: `.`)
- Whether `--include-passing` flag is set (default: false)

Strip `--include-passing` from the arguments before parsing modules/path.
If the argument is a path (starts with `.`, `/`, or contains `/`), treat it as the path with all modules.
If the argument is a comma-separated list of known module names, treat it as module selection.
If two arguments, first is modules, second is path.

### Step 2: Recon — Build Front-End Context

Before dispatching any module agents, build an understanding of the target project. This context will be passed to every sub-agent.

**2a. Discover structure** (use Glob and Bash `ls`):
- List top-level directories in the target path
- Glob for `package.json`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `webpack.config.*`
- Glob for styling: `tailwind.config.*`, `postcss.config.*`, `*.css`, `styled-components`, `emotion`
- Glob for component directories: `src/components/**`, `src/ui/**`, `src/pages/**`
- Glob for test files: `**/*.test.*`, `**/*.spec.*`, `e2e/**`, `__tests__/**`
- Glob for config: `.eslintrc*`, `eslint.config.*`, `.prettierrc*`, `CLAUDE.md`

**2b. Read available documentation** (use Read, skip if file doesn't exist):
- `{target_path}/CLAUDE.md`
- `{target_path}/README.md`
- `{target_path}/package.json` (dependencies reveal framework, styling, testing choices)
- `{target_path}/tsconfig.json` or `{target_path}/tsconfig.app.json` (strict mode, paths)
- Main CSS file (first 100 lines — reveals design token strategy)
- Tailwind/PostCSS config if present
- `{target_path}/docs/audits/ACCEPTED_RISKS.md`, or `{target_path}/architecture-mds/docs/security/ACCEPTED_RISKS.md` where the repo keeps its architecture docs there — Previously triaged findings marked as accepted risk. If this file exists, include its contents in the front-end context passed to sub-agents. Sub-agents MUST NOT re-flag these as new findings. They may reference them as "previously accepted" if the risk profile has materially changed (e.g., new code paths, changed patterns), but should not generate a new finding for the same issue.

**2c. Produce a front-end context summary** (20-40 lines) covering:
- **Framework**: React, Vue, Angular, Next.js, etc. + version
- **Styling approach**: Tailwind, CSS Modules, styled-components, inline styles, CSS-in-JS
- **Build tool**: Vite, Webpack, Next.js, CRA
- **TypeScript**: Strict mode? Path aliases? Any `any` usage?
- **State management**: Context, Redux, Zustand, Jotai, etc.
- **Routing**: React Router, Next.js file routing, etc.
- **Testing**: Vitest, Jest, Playwright, Cypress, Testing Library
- **Component structure**: Feature folders, atomic design, flat structure
- **Design tokens**: CSS variables, theme files, Tailwind config
- **Dark mode**: Strategy (class toggle, media query, CSS variables)

### Step 3: Auto-Detect Applicable Modules

Using the structure discovered in Step 2, determine which modules are relevant:

- **design-tokens**: Always run if CSS files, Tailwind config, or theme files exist
- **components**: Always run if `.tsx`, `.jsx`, `.vue`, or `.svelte` files exist
  - **Responsive/mobile check**: When checking components, the sub-agent should also verify responsive design patterns: all features must work on mobile, tablet (iPad), and desktop. Check for hover-only interactions without touch alternatives (e.g., `hidden group-hover:flex`, `opacity-0 group-hover:opacity-100`), `touch-none` on interactive elements, mouse-only event handlers (`onMouseEnter/Leave`) without touch fallbacks, and `hidden` classes that remove functionality rather than adapting layout.
- **accessibility**: Always run if UI components exist
- **performance**: Always run
- **code-quality**: Always run
- **security**: Always run if frontend code exists
- **seo-meta**: Run if `index.html` exists, OR if a meta-framework is detected (`next.config.*`, `nuxt.config.*`, `remix.config.*`, `astro.config.*`), OR if layout/head files exist (`_app.tsx`, `_document.tsx`, `layout.tsx`, or any file containing `<head>` or `<meta>` patterns)

Skip modules that have no applicable files. Log which modules are being run and which are skipped.

### Step 4: Resolve Skill Directory and Module Paths

Resolve the skill directory path by running: `echo $HOME/.claude/skills/audit-frontend`

Each applicable module's prompt lives at:

From SecurityMindedSolutions/ai-skills, MIT.

More from SecurityMindedSolutions/ai-skills