@appfire-ux/audit-agent 0.20260702.1 → 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).
@@ -27,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260702.1",
+  "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

@@ -28,7 +28,10 @@ Screenshot assets: `docs/ui-audit/assets/` and `docs/ux-audit/assets/` (per each
 
 Do this yourself in the main session — **do not** delegate to either agent yet:
 
-1. Bootstrap `@appfire-ux/guidelines` (Phase 0 from ux-auditor): install/update, run `npx @appfire-ux/guidelines`, verify `.cursor/rules/ux-*.mdc` and `guidelines/` exist. Record bootstrap notes for the summary appendix.
+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
@@ -38,7 +41,9 @@ Spawn **ux-auditor** and **ui-auditor** **concurrently** (two parallel agent tas
 Pass each agent this context:
 
 ```
-Phase 0 (guidelines bootstrap) is ALREADY COMPLETE in the main session.
+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]

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.