@appfire-ux/audit-agent 0.20260702.2 → 0.20260706.0

package/templates/commands/full-audit.md

@@ -1,75 +1,111 @@
 ---
-description: Run ux-auditor and ui-auditor in parallel — full guideline compliance + UI/usability audit
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out-dir <path>]
+description: Run ux-auditor, ui-auditor and a11y-auditor in parallel — guideline compliance + UI/usability + accessibility/VPAT audit
+argument-hint: [scope-path] [--agents ux,ui,a11y] [--static-only] [--lang pl|en] [--out-dir <path>] [--prod]
 ---
 
-Run **both** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance) and **ui-auditor** (UI & usability).
+Run **all three** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance), **ui-auditor** (UI & usability) and **a11y-auditor** (accessibility / VPAT readiness).
 
 Arguments passed by the user: `$ARGUMENTS`
 
 ## Parse arguments
 
 - **Scope path** — optional directory (default: whole repo).
-- `--static-only` — skip runtime/screenshots for both agents; warn the user that the UI audit will be much weaker.
-- `--lang pl|en` — report language for both agents (default: English).
-- `--out-dir <path>` — parent folder for outputs (default: `docs/audits`). Individual reports go in subfolders; do not use `--out` here.
+- `--agents ux,ui,a11y` — subset of agents to run (default: all three).
+- `--static-only` — skip runtime/screenshots/scans for all agents; warn the user that the UI audit will be much weaker and most a11y criteria become NEEDS_MANUAL_REVIEW.
+- `--lang pl|en` — report language for all agents (default: English; a11y JSON/criterion map stays English).
+- `--out-dir <path>` — parent folder for outputs (default: `docs/audits`).
+- `--prod` — append `-prod` to report filenames (auditing production/staging URL).
 
-Derive report paths (use today's date `YYYY-MM-DD`):
+Date slug: `YYYY-MM-DD` + optional `-prod` suffix.
 
-| Agent | Report |
-|-------|--------|
-| ux-auditor | `<out-dir>/ux-audit/UX-AUDIT-<date>.md` |
-| ui-auditor | `<out-dir>/ui-audit/UI-AUDIT-<date>.md` |
-| summary | `<out-dir>/AUDIT-SUMMARY-<date>.md` |
+## Required output layout
 
-Screenshot assets: `docs/ui-audit/assets/` and `docs/ux-audit/assets/` (per each agent's defaults) unless you consolidate under `<out-dir>/` — if so, tell both agents the same asset dir to avoid duplicate captures.
+```
+<out-dir>/
+├── AUDIT-SUMMARY-<date>[-prod].md
+├── AUDIT-SUMMARY-<date>[-prod].html
+├── prod-assets/              # only when orchestrator shares PNG captures across agents
+├── ux-audit/
+│   ├── UX-AUDIT-<date>[-prod].md
+│   ├── UX-AUDIT-<date>[-prod].html
+│   └── assets/*.png
+├── ui-audit/
+│   ├── UI-AUDIT-<date>[-prod].md
+│   ├── UI-AUDIT-<date>[-prod].html
+│   └── assets/*.png
+└── a11y-audit/
+    ├── A11Y-AUDIT-<date>[-prod].{md,html,json}
+    ├── assets/*.png
+    └── axe-results/*.json
+```
 
-## Step 1 — Shared setup (once, before agents)
+Relative image paths in MD/HTML: `assets/<file>.png` — never base64, never `../prod-assets/`.
 
-Do this yourself in the main session — **do not** delegate to either agent yet:
+## Role division (/full-audit)
 
-1. **Refresh audit toolchain (Phase 0 from ux-auditor):**
-   - **0a** — `@appfire-ux/audit-agent@latest`: `npm update` / `npm install @latest` as needed, then `npx @appfire-ux/audit-agent`. Verify `.claude/agents/` and `.claude/commands/` are current.
-   - **0b** — `@appfire-ux/guidelines@latest`: `npm update` / `npm install @latest` as needed, then `npx @appfire-ux/guidelines`. Verify `.cursor/rules/ux-*.mdc` and `guidelines/` exist.
-   - Record both package versions and any stale/failed steps for the summary appendix.
-2. Unless `--static-only`: detect dev command (`npm run dev`, etc.), start **one** dev server, note the base URL. Both agents will reuse it — do not start a second server.
+| Agent | Owns | Same protocol |
+|-------|------|----------------|
+| **ux-auditor** | Guideline compliance: tokens, a11y, copy, messaging, personas | STOP & ASK, MD+HTML+PNG, Definition of done |
+| **ui-auditor** | IA, consistency, layout, interaction, responsiveness | STOP & ASK, MD+HTML+PNG, Definition of done |
+| **a11y-auditor** | Deep accessibility: WCAG 2.2 A/AA, axe-core scan, VPAT/ACR datapoints | STOP & ASK, MD+HTML+PNG+JSON, no over-claiming |
 
-## Step 2 — Launch agents in parallel
+- Each agent writes to its own `ux-audit/`, `ui-audit/` or `a11y-audit/` subfolder with its own `assets/`.
+- Use `prod-assets/` **only** when orchestrator captures once and agents reuse identical PNGs — each agent copies into local `assets/` for Confluence-relative paths.
+- Do **not** duplicate capture work unless one agent needs extra viewports/states the other missed.
 
-Spawn **ux-auditor** and **ui-auditor** **concurrently** (two parallel agent tasks — not sequential).
+## Step 1 — Shared setup (once, before agents)
 
-Pass each agent this context:
+Do this in the main session — **do not** delegate yet:
 
-```
-Phase 0 (audit toolchain bootstrap) is ALREADY COMPLETE in the main session.
-- audit-agent version: [npm ls / npm view]
-- guidelines version: [npm ls / npm view]
-- Kit verified at: [list key paths]
-- Dev server: [running at URL | not started — static-only]
-- Scope: [path or whole repo]
-- Language: [en|pl]
-- Report path: [agent-specific path above]
-- Asset dir: [shared or per-agent path]
-
-Skip Phase 0 npm install. Begin at your Phase 1.
-For runtime/screenshot phases: reuse the dev server URL above; do not start another server.
-When done: complete through Phase 7 and return report path, severity counts, top 3 issues, limitations.
-```
+1. **Refresh audit toolchain (Phase 0):**
+   - **0a** — `@appfire-ux/audit-agent@latest` + `npx @appfire-ux/audit-agent`
+   - **0b** — `@appfire-ux/guidelines@latest` + `npx @appfire-ux/guidelines`
+   - **0c** (when a11y-auditor runs) — `npm ls playwright axe-core --depth=0 || npm install -D playwright axe-core`; `npx playwright install chromium`
+   - Record versions for the summary appendix.
+2. **Resolve base URL** — do not assume localhost. If blind-alley signals (OAuth redirect, auth wall, wrong UI) → **STOP & ASK** user with the template from ux-auditor before launching agents.
+3. Unless `--static-only`: start **one** dev server OR use user-provided logged-in URL. Note base URL for all agents.
+4. Optional shared capture: if Browser MCP or Playwright script runs here, save to `<out-dir>/prod-assets/` and tell agents to copy into their `assets/` folders.
 
-Let each agent follow its full methodology from Phase 1 onward.
+## Step 2 — Launch agents in parallel
 
-## Step 3 — Combined summary (after both finish)
+Spawn **ux-auditor**, **ui-auditor** and **a11y-auditor** **concurrently** (honor `--agents`).
 
-Write `<out-dir>/AUDIT-SUMMARY-<date>.md`:
+```
+Phase 0 COMPLETE. Orchestrator context:
+- audit-agent version: …
+- guidelines version: …
+- Base URL: [url | static-only]
+- Scope: …
+- Language: …
+- ux report: <out-dir>/ux-audit/UX-AUDIT-<date>[-prod].md
+- ui report: <out-dir>/ui-audit/UI-AUDIT-<date>[-prod].md
+- a11y report: <out-dir>/a11y-audit/A11Y-AUDIT-<date>[-prod].md (+ .json datapoints, axe-results/)
+- Shared prod-assets: [path or none — copy to local assets/ if used]
+- STOP & ASK already resolved: [yes/no — what user provided]
+
+Skip Phase 0 npm. Begin Phase 1.
+Reuse base URL; do not start another server.
+Follow Shared deliverables: MD+HTML+PNG, Definition of done.
+If STOP & ASK triggers mid-run, pause and ask user — do not fake verified-runtime.
+```
 
-1. **Executive overview** — 5–8 sentences, both lenses combined.
-2. **Reports** — links to both markdown files.
-3. **Combined scorecard** — ux-auditor categories + ui-auditor categories, total findings by severity.
-4. **Top 5 cross-cutting issues** — deduplicated; note if ux and ui flagged the same surface differently.
-5. **Handoffs merged** — items each agent deferred to the other.
-6. **Shared limitations** — static-only, capture gaps, bootstrap notes.
-7. **Suggested order of work** — quick wins that satisfy both audits first.
+## Step 3 — Combined summary + HTML (after all agents finish)
+
+1. Write `<out-dir>/AUDIT-SUMMARY-<date>[-prod].md`:
+   - Executive overview (all lenses)
+   - Links to all MD reports
+   - Combined scorecard + severity totals
+   - Top 5 cross-cutting issues (deduplicated)
+   - Merged handoffs
+   - Shared Limitations (URL, viewports, roles, capture gaps)
+   - Suggested remediation order
+2. Generate HTML for **all** reports:
+   ```bash
+   node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir <out-dir>
+   ```
+   (or repo-local `docs/audits/build-html-reports.mjs` if present)
+3. Optionally serve preview: `npx --yes serve <out-dir> -p 4173` and give user links to `*.html`.
 
 ## Relay to the user
 
-Report paths, combined severity counts, top 3 issues across both audits, whether parallel run succeeded, and any limitations.
+MD + HTML paths (all reports), combined severity counts, Baseline Accessibility Score + safe conclusion (a11y), top 3 issues, capture coverage, Limitations, local preview URLs, whether parallel run and STOP & ASK occurred. Remind the user the a11y `.json` feeds "AI Agent: VPAT Document" (Confluence, CRUX) for the ACR draft.

package/templates/commands/ui-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Run a UI & usability audit of this repo (consistency, IA, interaction design)
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>]
+argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod]
 ---
 
 Use the **ui-auditor** agent to run a full UI & usability audit of this repository.
@@ -9,8 +9,11 @@ Arguments passed by the user: `$ARGUMENTS`
 
 Interpretation:
 - A path argument limits the audit scope to that directory (default: whole repo, primary-persona surfaces prioritized).
-- `--static-only` — skip Phase 3 (runtime capture); do not start the dev server. Note: this significantly weakens a UI audit — warn the user before proceeding.
+- `--static-only` — skip Phase 3 (runtime capture); warn the user this significantly weakens the audit.
 - `--lang pl` — write the report in Polish (default: English).
-- `--out <path>` — report location (default: `docs/ui-audit/UI-AUDIT-<date>.md`).
+- `--out <path>` — report MD path (default: `docs/audits/ui-audit/UI-AUDIT-<date>[-prod].md`).
+- `--prod` — append `-prod` to the report filename.
 
-Launch the agent with these parameters and let it follow its full methodology, including bootstrapping/refreshing `@appfire-ux/audit-agent` and `@appfire-ux/guidelines` (Phase 0), early screenshot capture (Phase 3), and mandatory self-verification (Phase 7). When it finishes, relay: the report path, finding counts by severity, top 3 issues, capture coverage, and any limitations it reported.
+Deliverables: **MD + HTML + PNG in `assets/`** (Confluence-ready). STOP & ASK on auth/login walls before faking visual evidence. Generate HTML via `build-html-reports.mjs` after the MD report.
+
+Launch the agent with these parameters and let it follow its full methodology, including Phase 0 toolchain refresh and Phase 7 Definition of done. Relay: MD + HTML paths, preview URL if served, finding counts, top 3 issues, capture coverage, Limitations.

package/templates/commands/ux-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Run a comprehensive UX audit of this repo against @appfire-ux/guidelines
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>]
+argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod]
 ---
 
 Use the **ux-auditor** agent to run a full UX audit of this repository.
@@ -11,6 +11,9 @@ Interpretation:
 - A path argument limits the audit scope to that directory (default: whole repo, UI code prioritized).
 - `--static-only` — skip Phase 4 (runtime verification); do not start the dev server.
 - `--lang pl` — write the report in Polish (default: English).
-- `--out <path>` — report location (default: `docs/ux-audit/UX-AUDIT-<date>.md`).
+- `--out <path>` — report MD path (default: `docs/audits/ux-audit/UX-AUDIT-<date>[-prod].md`).
+- `--prod` — append `-prod` to the report filename (production/staging URL audit).
 
-Launch the agent with these parameters and let it follow its full methodology, including bootstrapping/refreshing `@appfire-ux/audit-agent` and `@appfire-ux/guidelines` (Phase 0) and mandatory self-verification (Phase 7). When it finishes, relay: the report path, finding counts by severity, top 3 issues, and any limitations it reported.
+Deliverables: **MD + HTML + PNG in `assets/`** (Confluence-ready). Follow STOP & ASK if runtime capture hits auth walls. Generate HTML via `build-html-reports.mjs` after the MD report.
+
+Launch the agent with these parameters and let it follow its full methodology, including Phase 0 toolchain refresh and Phase 7 Definition of done. Relay: MD + HTML paths, preview URL if served, finding counts, top 3 issues, Limitations.