@appfire-ux/audit-agent 0.20260702.0 → 0.20260702.2

package/README.md

@@ -1,6 +1,11 @@
 # @appfire-ux/audit-agent
 
-One-command install of two Claude Code audit agents for Appfire repos. Both bootstrap/refresh `@appfire-ux/guidelines` by themselves (Phase 0):
+One-command install of two Claude Code audit agents for Appfire repos. **Every audit run refreshes both npm packages to `@latest`** (Phase 0):
+
+- **`@appfire-ux/audit-agent`** — agent/command definitions in `.claude/`
+- **`@appfire-ux/guidelines`** — rules, skills, and `guidelines/` kit
+
+Agents:
 
 - **ux-auditor** (`/ux-audit`) — guideline-compliance UX audit: design tokens, spacing/typography, accessibility, UX writing, messaging patterns, persona fit.
 - **ui-auditor** (`/ui-audit`) — UI & usability audit from a UI Designer's perspective: cross-screen consistency, layout & visual hierarchy, information architecture, navigation, interaction design, forms, data-dense views, responsiveness. Screenshot-driven (browser MCP or bundled Playwright fallback).
@@ -16,8 +21,9 @@ npm install -D @appfire-ux/audit-agent
 The postinstall script copies the agent and command into `<repo>/.claude/`. Done — open Claude Code and run:
 
 ```
-/ux-audit     # or
-/ui-audit
+/full-audit   # both audits in parallel (recommended)
+/ux-audit     # compliance only
+/ui-audit     # UI & usability only
 ```
 
 Once, for all repos on your machine:
@@ -26,11 +32,14 @@ Once, for all repos on your machine:
 npx @appfire-ux/audit-agent --global   # installs into ~/.claude/
 ```
 
-## Update
+## Update (manual, optional)
+
+Phase 0 on every `/ux-audit`, `/ui-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
 
 ```bash
-npm update @appfire-ux/audit-agent
+npm update @appfire-ux/audit-agent @appfire-ux/guidelines
 npx @appfire-ux/audit-agent
+npx @appfire-ux/guidelines
 ```
 
 ## What gets installed
@@ -41,12 +50,13 @@ npx @appfire-ux/audit-agent
 | `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>]` |
 | `.claude/agents/ui-auditor.md` | 8-phase UI & usability audit: guidelines bootstrap → screen/pattern inventory → screenshot capture → consistency/IA/interaction passes → report → self-verification |
 | `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>]` |
+| `.claude/commands/full-audit.md` | `/full-audit [scope] [--static-only] [--lang pl] [--out-dir <path>]` — runs **ux-auditor** and **ui-auditor** in parallel with shared guidelines bootstrap and one dev server |
 
-The audits complement each other: `ux-audit` checks *compliance with the guidelines*, `ui-audit` checks *the interface as designed*. Findings each agent notices outside its lane are handed off to the other's report section.
+The audits complement each other: `ux-audit` checks *compliance with the guidelines*, `ui-audit` checks *the interface as designed*. Use `/full-audit` when you want both at once; findings each agent notices outside its lane are handed off to the other's report section, and the combined summary deduplicates cross-cutting issues.
 
 ## Publishing (maintainers)
 
-**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
+**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`, `full-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
 
 **Manual:**
 

package/bin/install.js

@@ -69,8 +69,10 @@ console.log('[appfire-ux-audit-agent] Installed ' + copied.length + ' file(s) in
 for (const f of copied) console.log('  - ' + f);
 console.log('');
 console.log('Usage (in Claude Code, inside your repo):');
+console.log('  /full-audit               both audits in parallel (recommended for full coverage)');
 console.log('  /ux-audit                 guideline-compliance UX audit (tokens, a11y, content, messaging)');
 console.log('  /ui-audit                 UI & usability audit (consistency, IA, interaction design)');
-console.log('  Both accept: [scope-path] [--static-only] [--lang pl] [--out <path>]');
+console.log('  All accept: [scope-path] [--static-only] [--lang pl]');
+console.log('  /full-audit also: [--out-dir <path>]   /ux-audit|/ui-audit: [--out <path>]');
 console.log('');
 console.log('Tip: run "npx appfire-ux-audit-agent --global" to install into ~/.claude for all repos.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260702.0",
+  "version": "0.20260702.2",
   "description": "Claude Code audit agents for Appfire apps — installs ux-auditor (/ux-audit: guideline compliance) and ui-auditor (/ui-audit: UI consistency, IA, interaction design), auditing against @appfire-ux/guidelines",
   "license": "MIT",
   "publishConfig": {

package/templates/agents/ui-auditor.md

@@ -20,9 +20,17 @@ You are a senior UI Designer at Appfire doing a design critique of a shipped pro
 
 Work through the phases below IN ORDER. Do not skip Phase 0 or Phase 7.
 
-## Phase 0 — Bootstrap @appfire-ux/guidelines
+## Phase 0 — Bootstrap audit toolchain
 
-Same kit as ux-auditor (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines; postinstall copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, `guidelines/` into the project root). Assume it is NOT installed yet.
+Run **0a** then **0b** before any audit work. Record installed versions and any stale/failed steps in the report appendix.
+
+### 0a — Refresh @appfire-ux/audit-agent
+
+Same steps as ux-auditor Phase 0a: update/install `@appfire-ux/audit-agent@latest`, run `npx @appfire-ux/audit-agent`, verify `.claude/agents/` and `.claude/commands/` exist. Flag **"audit-agent possibly stale"** on npm failure when older files remain; STOP if no agent files and npm fails.
+
+### 0b — Bootstrap @appfire-ux/guidelines
+
+Same kit as ux-auditor (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines; postinstall copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, `guidelines/` into the project root).
 
 1. Locate the repo-root `package.json` (monorepo → workspace root; none anywhere → `npm init -y` and note it in the appendix).
 2. Kit present (`guidelines/` with `foundations/` + `personas/` AND at least one `.cursor/rules/ux-*.mdc`) → refresh:

package/templates/agents/ux-auditor.md

@@ -15,9 +15,38 @@ You are a principal UX auditor at Appfire. You produce the most comprehensive, e
 
 Work through the phases below IN ORDER. Do not skip Phase 0 or Phase 7.
 
-## Phase 0 — Bootstrap @appfire-ux/guidelines
+## Phase 0 — Bootstrap audit toolchain
 
-The audit is driven by the Appfire UX Guidelines kit (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines). Its postinstall script copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, and `guidelines/` into the project root. Assume it is NOT installed yet.
+Run **0a** then **0b** before any audit work. Record installed versions and any stale/failed steps in the report appendix.
+
+### 0a — Refresh @appfire-ux/audit-agent
+
+This package ships the agent/command definitions in `.claude/`. Refresh them on every audit so methodology updates are picked up automatically.
+
+1. At the repo-root `package.json` (monorepo → workspace root):
+   - **Listed in `devDependencies` or `dependencies`** → refresh:
+     ```bash
+     npm update @appfire-ux/audit-agent
+     npx @appfire-ux/audit-agent
+     ```
+     Compare `npm ls @appfire-ux/audit-agent --depth=0` with `npm view @appfire-ux/audit-agent version`. If still behind, force: `npm install @appfire-ux/audit-agent@latest`, then `npx @appfire-ux/audit-agent`.
+   - **Not listed** but `.claude/agents/ux-auditor.md` exists (e.g. global install) → refresh in place:
+     ```bash
+     npx @appfire-ux/audit-agent@latest
+     ```
+   - **Neither** → install as a dev tool, then copy agents:
+     ```bash
+     npm install -D @appfire-ux/audit-agent@latest
+     ```
+     (postinstall runs `npx` automatically; if not, run `npx @appfire-ux/audit-agent` explicitly). Note the fresh install in the appendix.
+2. Verify post-conditions — these MUST exist before continuing:
+   - `.claude/agents/ux-auditor.md`, `.claude/agents/ui-auditor.md`
+   - `.claude/commands/ux-audit.md`, `.claude/commands/ui-audit.md`, `.claude/commands/full-audit.md`
+3. Failure handling: npm fails but older `.claude/` files exist → proceed and flag **"audit-agent possibly stale"**. npm fails and no agent files → STOP and report the npm error.
+
+### 0b — Bootstrap @appfire-ux/guidelines
+
+The audit is driven by the Appfire UX Guidelines kit (npm: `@appfire-ux/guidelines`, source: github.com/fuegokit/appfire-ux-guidelines). Its postinstall script copies `.cursor/rules/ux-*.mdc`, `.cursor/skills/`, and `guidelines/` into the project root.
 
 1. Locate the correct install directory: the repo-root `package.json`. In a monorepo, use the workspace root. If there is no `package.json` anywhere, run `npm init -y` first and note this in the report appendix.
 2. Detect an existing kit: BOTH `guidelines/` (containing `foundations/` and `personas/`) AND at least one `.cursor/rules/ux-*.mdc` must exist.

package/templates/commands/full-audit.md

@@ -0,0 +1,75 @@
+---
+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>]
+---
+
+Run **both** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance) and **ui-auditor** (UI & usability).
+
+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.
+
+Derive report paths (use today's date `YYYY-MM-DD`):
+
+| 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` |
+
+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.
+
+## Step 1 — Shared setup (once, before agents)
+
+Do this yourself in the main session — **do not** delegate to either agent yet:
+
+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.
+
+## Step 2 — Launch agents in parallel
+
+Spawn **ux-auditor** and **ui-auditor** **concurrently** (two parallel agent tasks — not sequential).
+
+Pass each agent this context:
+
+```
+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.
+```
+
+Let each agent follow its full methodology from Phase 1 onward.
+
+## Step 3 — Combined summary (after both finish)
+
+Write `<out-dir>/AUDIT-SUMMARY-<date>.md`:
+
+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.
+
+## Relay to the user
+
+Report paths, combined severity counts, top 3 issues across both audits, whether parallel run succeeded, and any limitations.

package/templates/commands/ui-audit.md

@@ -13,4 +13,4 @@ Interpretation:
 - `--lang pl` — write the report in Polish (default: English).
 - `--out <path>` — report location (default: `docs/ui-audit/UI-AUDIT-<date>.md`).
 
-Launch the agent with these parameters and let it follow its full methodology, including bootstrapping/refreshing `@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.
+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.

package/templates/commands/ux-audit.md

@@ -13,4 +13,4 @@ Interpretation:
 - `--lang pl` — write the report in Polish (default: English).
 - `--out <path>` — report location (default: `docs/ux-audit/UX-AUDIT-<date>.md`).
 
-Launch the agent with these parameters and let it follow its full methodology, including bootstrapping/refreshing `@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.
+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.