# Audit

> Systematic website audit (stack detection, 9 phases). Use when: "audit", "website audit", "site audit", "check website".

- Skill: `claude-hangar/audit` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx skillmds@latest add claude-hangar/audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/claude-hangar/audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: claude-hangar (https://skillmd.com/u/claude-hangar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/claude-hangar/audit

---


<!-- AI-QUICK-REF
## /audit — Quick Reference
- **Modes:** start | continue | status | report | auto
- **Arguments:** `/audit $0` where $0 = mode (e.g. `/audit auto`, `/audit status`)
- **Three-layer:** phases/*.md + stacks/**/*.md + audit-context.md
- **Dual-Layer:** Source (read code) + Live (curl, Lighthouse, Playwright)
- **Check-Priorities:** MUST (mandatory) | SHOULD (standard) | COULD (nice-to-have)
- **9 Phases:** Baseline, Security, Performance, SEO, A11Y, Code, Privacy, Infra, Content
- **Finding-IDs:** IST-01, SEC-01, PERF-01, SEO-01, A11Y-01, CODE-01, GDPR-01, INFRA-01, CD-01
- **Severity:** CRITICAL > HIGH > MEDIUM > LOW
- **Context Protection:** Max 2 phases OR 5 fixes per session (except auto)
- **State:** .audit-state.json (v2.1)
- **Checkpoints:** [CHECKPOINT: verify] after each phase, [CHECKPOINT: decision] at audit scope
-->

# Skill: audit

Systematic website audit with a three-layer depth model.
Automatically detects the stack, loads relevant supplements, and performs
structured checks — for any web project.

---

## Architecture: Three-Layer Model

```
Layer 1: Base Phase (phases/*.md)           ~50 lines, universal
Layer 2: Stack Supplement (stacks/*/*.md)   ~80 lines, framework-specific
Layer 3: Project Override (audit-context.md) ~20-40 lines, project-specific
```

Per phase, only the relevant supplements are loaded.
Result: ~100-140 lines of check instructions per phase — comparable to a dedicated skill.

---

## Dual-Layer: Source + Live

Each phase has two check levels:

| Layer | Method | Example |
|-------|--------|---------|
| **Source-Layer** | Read code/config, grep, AST | Check `package.json`, read CSP in config |
| **Live-Layer** | Browser/tool-based | `curl -sI`, Lighthouse, Playwright, axe-core |

**Rule:** A check is only considered complete when BOTH layers have been verified (where applicable).
Example: "CSP configured" (Source) + "CSP header is actually sent" (Live) = complete.

Not all checks have both layers — e.g. "TypeScript strict mode" is purely source.
During phase execution, document which layer was checked per check.

---

## Check Priorities + Completeness Tracking

> See `_shared/audit-patterns.md` (MUST/SHOULD/COULD markers, completeness counting).
Phase with <100% MUST-checks can NOT be marked as `done`.

---

## 5 Modes

| Mode | Trigger | Description |
|------|---------|-------------|
| `start` | `/audit start` | Detect stack, create phase plan, execute first 2 phases |
| `continue` | `/audit continue` | Continue next phases or fix max 5 findings |
| `status` | `/audit status` | Show progress, statistics, open findings |
| `report` | `/audit report` | Generate structured Markdown report |
| `auto` | `/audit auto` | Fully autonomous run — all phases + fixes without prompts |

---

## Mode: start

### Step 1 — Auto-Detection (no user input needed)

Scan files and detect stack:

| File/Pattern | Detects | Stack-Key |
|-------------|---------|-----------|
| `package.json` > `astro` | Astro | `frontend: "astro"` |
| `package.json` > `@sveltejs/kit` | SvelteKit | `frontend: "sveltekit"` |
| `package.json` > `svelte` (without Kit) | Svelte (standalone) | `frontend: "svelte"` |
| `package.json` > `next` | Next.js | `frontend: "next"` |
| `package.json` > `nuxt` | Nuxt | `frontend: "nuxt"` |
| `hugo.toml` / `config.toml` with Hugo | Hugo | `frontend: "hugo"` |
| `package.json` > `fastify` | Fastify | `backend: "node-fastify"` |
| `package.json` > `express` | Express | `backend: "node-express"` |
| `svelte.config.js` + `@sveltejs/adapter-node` | SvelteKit Server | `backend: "node-sveltekit"` |
| `package.json` > `tailwindcss` | Tailwind CSS | `css: "tailwind"` |
| `tailwind.config.*` OR `@import "tailwindcss"` | Tailwind v4 | `css: "tailwind-v4"` |
| `Dockerfile` / `docker-compose.*` | Docker | `deployment: ["docker"]` |
| `traefik.*` / Labels with `traefik` | Traefik | `deployment: +["traefik"]` |
| `nginx.conf` / `/etc/nginx/` | nginx | `deployment: +["nginx"]` |
| `*.db` / `better-sqlite3` / `sqlite3` | SQLite | `database: "sqlite"` |
| `package.json` > `drizzle-orm` / `pg` / `postgres` | PostgreSQL + Drizzle | `database: "postgresql"` |
| `docker-compose.*` > `postgres` image | PostgreSQL (Docker) | `database: "postgresql"` |
| `package.json` > `bcryptjs` / `bcrypt` / `argon2` | Auth (Custom) | `auth: "custom"` |
| `playwright.config.*` | Playwright | `testing: ["playwright"]` |
| `.github/workflows/` | GitHub Actions | `ci: "github-actions"` |

**Version Detection:** For each detected stack, extract version from package.json or config.
Tailwind v4 detection: `@import "tailwindcss"` in CSS OR tailwindcss >= 4.0 in package.json.

### Step 2 — Context Enrichment

1. **Project CLAUDE.md** read (if available) — architecture, conventions
2. **audit-context.md** load (if in project root) — project-specific context
3. **Existing docs** scan: `AUDIT-FINDINGS*.md`, `TODO*.md`, `GO-LIVE*.md`
4. **{{REGISTRY_FILE}}** match: If project name is in project registry > identify assigned servers
5. **Existing state file** (.audit-state.json) check > auto-migrate if v1 (see State-Migration)

### Step 3 — User Query

Show detection result as table:

```
Stack Detection:
+-------------+------------------+---------+
| Category    | Detected         | Version |
+-------------+------------------+---------+
| Frontend    | Astro            | 6.x     |
| CSS         | Tailwind CSS v4  | 4.x     |
| Deployment  | Docker, Traefik  | —       |
| Testing     | Playwright       | —       |
+-------------+------------------+---------+

Detected servers: {{SERVER_NAMES}}
Project context: audit-context.md found
Existing docs: AUDIT-FINDINGS-2026-02-13.md, TODO-SEO.md
```

Then ask user (AskUserQuestion):
- **Audit scope:** Complete (all 9 phases) vs. focused (specific phases)
- **External repos:** Include related projects? (if defined in audit-context.md)
- **Server access:** Enable SSH checks? (if servers detected)
- **Phase order:** Sequential (01>08, default) vs. Smart Order (Security>Performance>Code>Rest, recommended)

**[CHECKPOINT: decision]** — User selects audit scope and phase order.

### Step 4 — Create state file and start first 2 phases

Create state file `.audit-state.json` (schema see below).
Then execute the first 2 phases according to phase execution flow.

---

## Mode: continue

1. Read `.audit-state.json`
2. Identify next pending phase(s)
3. Generate **smart recommendation** (see below)
4. User chooses: follow recommendation, different phase, or fix findings
5. Write state immediately after each phase/fix

### Smart Recommendation

> Decision logic: See `_shared/audit-patterns.md` (CRITICAL>HIGH>Phases>Remaining).
Show recommendation as **first option** in AskUserQuestion.

### Fixing Findings

- Always fix highest severity first: CRITICAL > HIGH > MEDIUM > LOW
- Per fix: Show problem > **Load fix template** (if in `fix-templates.md`) > User confirmation > Implement > Test
- Update fix status in state (`"status": "fixed"`, `"fixedIn": "Session N"`)
- **No auto-fix** — every fix requires user confirmation (except `auto` mode)

**[CHECKPOINT: verify]** — After each fix: show result, user confirms.

---

## Mode: status

Read state file and display:

```
Audit: Project Name (started YYYY-MM-DD)
Stack: Astro 6, Tailwind v4, Docker, Traefik

Phases:
  [done] 01 Baseline Analysis (Session 1, 3 Findings, MUST 100%)
  [done] 02 Security (Session 1, 5 Findings, MUST 100%)
  [wip]  03 Performance (in progress)
  [wait] 04 SEO
  [wait] 05 Accessibility
  [wait] 06 Code Quality
  [wait] 07 Privacy/GDPR
  [wait] 08 Infrastructure
  [wait] 09 Content & Design

Findings: 8 total
  CRITICAL: 1 (open: 1)
  HIGH: 3 (open: 2, fixed: 1)
  MEDIUM: 3 (open: 3)
  LOW: 1 (open: 1)

Completeness:
  MUST-Checks: 28/28 (100%)
  Total: 42/50 (84%)
  Layer: Source done, Live done (2 phases)
```

---

## Mode: report

Generate structured Markdown report based on `templates/report.md`.

1. Read state file
2. Group all findings by phase
3. Report with Executive Summary, Findings per Phase, Recommendations
4. **Include trend analysis** (if history available):
   ```
   Trend (recent audits):
     CRITICAL: 5 > 2 > 0  (resolved)
     HIGH:     8 > 6 > 4  (declining)
     MEDIUM:  12 > 10 > 7  (declining)
     Total:   25 > 18 > 11
   Assessment: Project is steadily improving.
   ```
5. Save report as `AUDIT-REPORT-{YYYY-MM-DD}.md` in project root
6. If previous reports exist: Diff section (new/resolved since last report)

---

## Mode: auto

Fully autonomous audit run without prompts. For experienced users who
want the entire audit in one go.

### Flow

1. **Check orchestrator context:** If `.audit-orchestrator-state.json` exists:
   - Read `phaseMapping.audit.delegated` > skip delegated phases
   - Read `sequencingReason` > understand context
   - **Example:** If `code-quality` delegated to `/project-audit` > skip Phase 06
2. Auto-detection as in `start`
3. **All phases** run through (no 2-phase limit, skip delegated phases)
4. Document findings with fix templates from `fix-templates.md`
5. **Context management:** When context is running low:
   - Write state immediately
   - Create task in `.tasks.json` with handoff note
   - Recommend: "New session with `/audit continue`"
5. At the end: automatically generate report

### Context Protection in Auto Mode

- Findings are collected but **not fixed immediately** (documented only)
- Per phase: If >10 findings > close phase, start next
- Write state after EVERY phase immediately
- At context limit: clean abort with complete state
- Fixes can be done in follow-up sessions with `/audit continue`

### When to Recommend Auto Mode

- User says "check everything", "fully autonomous", "full audit"
- Auditing multiple projects in sequence
- First overview of a new project

---

## Phase Execution

For each phase:

1. **Load base:** Read `phases/{NN}-{name}.md` — universal check items
2. **Load supplements:** For each detected stack, load the matching file, ONLY the section relevant to the current phase

   | Phase | Supplement Sections |
   |-------|-------------------|
   | 01-baseline-analysis | §Baseline-Analysis |
   | 02-security | §Security |
   | 03-performance | §Performance |
   | 04-seo | §SEO |
   | 05-accessibility | §Accessibility |
   | 06-code-quality | §Code-Quality |
   | 07-privacy | §Privacy |
   | 08-infrastructure | §Infrastructure |
   | 09-content-design | §Content-Design |

3. **Project override:** If `audit-context.md` exists > include relevant section
4. **Existing findings:** Check previous audit docs, do not create duplicates
5. **Execute checks:** Systematically work through all loaded checks
   - Source layer: Read and analyze code/config
   - Live layer: Execute tools (curl, Lighthouse, Playwright, axe) where applicable
6. **Document findings:** Each finding with ID, severity, description, location
7. **Count completeness:** MUST/SHOULD/COULD checks (executed vs. skipped)
   - Skipped MUST-checks: document reason
   - Phase with <100% MUST-checks: status remains `in-progress`
8. **Update state:** Set phase status to `done`, enter findings + completeness

**[CHECKPOINT: verify]** — After each phase: show findings + completeness to user, get confirmation.

### Finding-IDs

| Phase | Prefix | Example |
|-------|--------|---------|
| 01-baseline-analysis | `IST` | IST-01 |
| 02-security | `SEC` | SEC-01 |
| 03-performance | `PERF` | PERF-01 |
| 04-seo | `SEO` | SEO-01 |
| 05-accessibility | `A11Y` | A11Y-01 |
| 06-code-quality | `CODE` | CODE-01 |
| 07-privacy | `GDPR` | GDPR-01 |
| 08-infrastructure | `INFRA` | INFRA-01 |
| 09-content-design | `CD` | CD-01 |

### Severity Definitions

| Level | Criteria | Examples |
|-------|----------|----------|
| **CRITICAL** | Security vulnerability, data loss, outage | Open port, missing auth, SQL Injection |
| **HIGH** | Functional bug, performance >2s, missing validation | LCP >4s, no rate limiting, XSS |
| **MEDIUM** | Code quality, missing tests, UX issue | Missing alt texts, no error handling |
| **LOW** | Cosmetic, best practice, nice-to-have | Outdated dependency, missing docs |

**Prioritization:** CRITICAL > HIGH > MEDIUM > LOW. Security before functional before visual.

---

## State Schema v2.1 (.audit-state.json)

> Complete state schema (JSON example) + migrations v1>v2 and v2>v2.1: See **state-schema.md**

---

## Supplement Loading Logic

Per phase, the skill loads only relevant stack supplements.
Each stack file is structured by sections.

**Example Phase 02-security:**
```
> Always: phases/02-security.md (base)
> If frontend=astro: + stacks/frontend/astro.md §Security
> If css=tailwind-v4: (no Security section > load nothing)
> If deployment includes docker: + stacks/deployment/docker.md §Security
> If deployment includes traefik: + stacks/deployment/traefik.md §Security
> If backend=node-fastify: + stacks/backend/node-fastify.md §Security
> If database=sqlite: + stacks/database/sqlite.md §Security
> If testing includes playwright: + stacks/testing/playwright.md §Security
```

**Supplement file locations:**

| Stack-Key | Supplement Path |
|-----------|----------------|
| `frontend: "astro"` | `stacks/frontend/astro.md` |
| `frontend: "sveltekit"` | `stacks/frontend/sveltekit.md` |
| `frontend: "next"` | `stacks/frontend/next.md` |
| `frontend: "hugo"` | `stacks/frontend/hugo.md` |
| `backend: "node-fastify"` | `stacks/backend/node-fastify.md` |
| `backend: "node-sveltekit"` | `stacks/backend/node-sveltekit.md` |
| `css: "tailwind-v4"` | `stacks/css/tailwind-v4.md` |
| `deployment: "docker"` | `stacks/deployment/docker.md` |
| `deployment: "traefik"` | `stacks/deployment/traefik.md` |
| `deployment: "nginx"` | `stacks/deployment/nginx.md` |
| `database: "sqlite"` | `stacks/database/sqlite.md` |
| `database: "postgresql"` | `stacks/database/postgresql.md` |
| `testing: "playwright"` | `stacks/testing/playwright.md` |

If a stack is detected but no supplement exists > use base phase only, no error.

---

## Phase Order

Two modes for the order of phases:

### Sequential (Default)
`01-baseline-analysis > 02-security > 03-performance > 04-seo > 05-accessibility > 06-code-quality > 07-privacy > 08-infrastructure > 09-content-design`

### Smart Order (Recommended)
Prioritized by impact — finds critical issues first:
`02-security > 03-performance > 08-infrastructure > 01-baseline-analysis > 06-code-quality > 04-seo > 05-accessibility > 07-privacy > 09-content-design`

**Logic:** Security issues are most urgent, followed by performance (user impact),
then infrastructure (stability). SEO/A11y/Privacy are important but less time-critical.

User chooses at `start`. Store in state as `"phaseOrder": "sequential"` or `"smart"`.

---

## Fix Templates

For common findings there are ready-made fix templates in `fix-templates.md`.
Per finding type: code snippet, config change, verify step.

**Usage:** When a finding matches a template:
1. Load template from `fix-templates.md`
2. Adapt to project
3. Get user confirmation
4. Implement and verify

---

## Verification-Depth + Fix Protocol

> See `_shared/audit-patterns.md` (4-Level Verification, Stub-Detection, 5-Step Fix-Protocol).
Level 4 (Functional) is mandatory when live layer is available. READ + VERIFY never skip.

---

## Context Protection (CRITICAL)

> Base rules: See `_shared/audit-patterns.md` (Max 2 phases, state immediately, no auto-fix).

**Website audit specific:**
- **SSH readonly** during audit — write only during explicit fix with user confirmation
- **Dual-Layer:** Per phase, document whether source layer, live layer, or both were checked
- **Anti-rationalization** — Do not skip MUST-checks or reduce severity because "it looks fine". See `_shared/anti-rationalization.md`

---

## Smart Next Steps

After completing the audit (report generated or all phases done), recommend suitable follow-up skills to user. Recommendations based on findings and detected stack:

| Condition | Recommendation | Justification |
|-----------|---------------|---------------|
| Astro project detected | `/astro-audit` | Check version-specific migration/best-practices |
| SvelteKit project detected | `/sveltekit-audit` | SvelteKit/Svelte 5 version checks + best practices |
| PostgreSQL/Drizzle detected | `/db-audit` | Database schema, migrations, security, performance |
| Custom auth detected (bcryptjs etc.) | `/auth-audit` | Auth security, session management, OWASP ASVS |
| >3 HIGH/CRITICAL findings | `/adversarial-review audit` | Check report for completeness |
| Phase 09 (Content) findings >0 | `/polish scan` | Design improvements based on findings |
| Phase 09 (Content) findings >0 | `/design-system` | Check palette, typography, UX rules against curated databases |
| Claude Code project (.claude/ present) | `/security-scan` | MCP permissions, hook safety, secret detection |
| Audit completed | `/lesson-learned session` | Extract learnings from audit process |
| No /project-audit state present | `/project-audit start` | Check code/CI/CD quality |

**Output in report:** Replace `{NEXT_STEPS}` placeholder with concrete recommendation list.

**Output after last phase:** "Next steps:" + 2-3 most relevant recommendations.

---

## Files in This Skill

```
audit/
├── SKILL.md                    <- This file
├── state-schema.md             # State Schema v2.1 + Migrations
├── fix-templates.md            # Quick-Fix templates for common findings
├── phases/
│   ├── 01-baseline-analysis.md # Versions, Config, Architecture
│   ├── 02-security.md          # OWASP, Headers, Secrets, Auth
│   ├── 03-performance.md       # Lighthouse, CWV, Caching, Images
│   ├── 04-seo.md               # Meta, Structured Data, Sitemap
│   ├── 05-accessibility.md     # WCAG AA, Contrast, ARIA, Keyboard
│   ├── 06-code-quality.md      # Linting, Types, Dependencies
│   ├── 07-privacy.md           # Cookies, Fonts, Analytics
│   ├── 08-infrastructure.md    # VPS, Docker, Proxy, Backup
│   └── 09-content-design.md    # Content, Typography, Colors, Consistency
├── stacks/
│   ├── frontend/astro.md       # Astro-specific checks
│   ├── frontend/sveltekit.md   # SvelteKit-specific checks
│   ├── frontend/next.md        # Next.js-specific checks
│   ├── frontend/hugo.md        # Hugo-specific checks
│   ├── backend/node-fastify.md # Fastify-specific checks
│   ├── backend/node-sveltekit.md # SvelteKit server-side checks
│   ├── css/tailwind-v4.md      # Tailwind v4-specific checks
│   ├── deployment/docker.md    # Docker-specific checks
│   ├── deployment/traefik.md   # Traefik-specific checks
│   ├── deployment/nginx.md     # nginx-specific checks
│   ├── database/sqlite.md      # SQLite-specific checks
│   ├── database/postgresql.md  # PostgreSQL + Drizzle checks
│   └── testing/playwright.md   # Visual & E2E testing checks
└── templates/
    └── report.md               # Markdown report template
```