Audit

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:

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: start

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

Scan files and detect stack:

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"
6. 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

Severity Definitions

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:

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:

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