From 7b57b2e09192c5ceffe3e4b849aeb59e6a01d05e Mon Sep 17 00:00:00 2001 From: bastien Date: Thu, 23 Apr 2026 16:06:54 +0200 Subject: [PATCH] refactor(audits): route all report writes to .claude/audits/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before: SEO.md, GEO.md, HARDEN.md, VALIDATE.md, BUGS-FOUND.md landed at project root. After: all five go to .claude/audits/. Covers both dispatcher write paths and the dispatcher bash commands that parse each report (test -s, grep score, wc) — otherwise the dispatcher would look for the file at the old location. - skills/seo,geo,harden,validate,code-clean — write paths + console summaries ("Report: .claude/audits/X.md") - skills/harden,validate — bash parsing commands (test/grep/wc) aligned - agents/seo-analyzer,validator-analyzer,code-cleaner — agent-side refs - agents/validator-analyzer frontmatter description updated Co-Authored-By: Claude Opus 4.7 (1M context) --- agents/code-cleaner.md | 6 +++--- agents/seo-analyzer.md | 2 +- agents/validator-analyzer.md | 11 +++++------ skills/code-clean/SKILL.md | 2 +- skills/geo/SKILL.md | 4 ++-- skills/harden/SKILL.md | 27 +++++++++++++-------------- skills/seo/SKILL.md | 8 ++++---- skills/validate/SKILL.md | 25 ++++++++++++------------- 8 files changed, 41 insertions(+), 44 deletions(-) diff --git a/agents/code-cleaner.md b/agents/code-cleaner.md index de35928..c6e4331 100644 --- a/agents/code-cleaner.md +++ b/agents/code-cleaner.md @@ -141,7 +141,7 @@ Do NOT call the `/refactor` skill — invoke the agent directly. If cleanup reveals actual bugs (not style issues — real defects): -- Append each bug to `BUGS-FOUND.md` at project root: +- Append each bug to `.claude/audits/BUGS-FOUND.md` (run `mkdir -p .claude/audits` first): ``` ## [date] Bug found during code-clean - **File**: @@ -178,7 +178,7 @@ REFACTORED: SKIPPED (user decision): - — -BUGS FOUND: (logged to BUGS-FOUND.md) +BUGS FOUND: (logged to .claude/audits/BUGS-FOUND.md) TESTS: passing / no test suite / ``` @@ -192,7 +192,7 @@ TESTS: passing / no test suite / - No "while we're here" scope creep. Only fix approved items. - Exported/public API symbols require explicit per-item user confirmation before deletion — even if they appear unused. -- Bugs go to BUGS-FOUND.md, not fixed in this workflow. +- Bugs go to .claude/audits/BUGS-FOUND.md, not fixed in this workflow. - If the codebase has no tests and the changes are non-trivial, warn the user about the risk before executing. - No plugin check (lightweight skill, not an orchestrator). diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index 0301413..1d8001f 100644 --- a/agents/seo-analyzer.md +++ b/agents/seo-analyzer.md @@ -877,7 +877,7 @@ SEO AGENT RESULT (depth: ) ``` **If standalone `/seo` on a project without `/geo`**: write/update -`SEO.md` at project root. Structure matches classic format, with §7 +`.claude/audits/SEO.md` (run `mkdir -p .claude/audits` first). Structure matches classic format, with §7 (GEO) marked as "Not audited — run /geo for GEO/AI optimization". ```markdown diff --git a/agents/validator-analyzer.md b/agents/validator-analyzer.md index 6d5b649..f90d446 100644 --- a/agents/validator-analyzer.md +++ b/agents/validator-analyzer.md @@ -1,6 +1,6 @@ --- name: validator-analyzer -description: Web standards audit agent — W3C HTML validity (validator.nu), W3C CSS validity (jigsaw.w3.org), WCAG 2.1 accessibility (axe-core, pa11y, WAVE). Dispatched from /validate. Produces scored VALIDATE.md report with concrete diffs for auto-fixable issues and user actions for judgment-required fixes. Complementary to /harden (security), /seo (indexability), /geo (AI extraction). +description: Web standards audit agent — W3C HTML validity (validator.nu), W3C CSS validity (jigsaw.w3.org), WCAG 2.1 accessibility (axe-core, pa11y, WAVE). Dispatched from /validate. Produces scored .claude/audits/VALIDATE.md report with concrete diffs for auto-fixable issues and user actions for judgment-required fixes. Complementary to /harden (security), /seo (indexability), /geo (AI extraction). tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch --- @@ -287,7 +287,7 @@ RGAA 4.1 (French public sector). --- -## STEP 4 — Score + VALIDATE.md +## STEP 4 — Score + .claude/audits/VALIDATE.md ### Scoring @@ -306,7 +306,7 @@ Base 100. Deductions : Clamp to [0, 100]. -### Report structure — write to `/VALIDATE.md` +### Report structure — write to `/.claude/audits/VALIDATE.md` (run `mkdir -p .claude/audits` first) ```markdown # Validation Report — @@ -455,7 +455,7 @@ READY TO APPLY — awaiting dispatcher confirmation - **Single agent, narrow scope.** W3C HTML + W3C CSS + WCAG 2.1 only. Drop anything else (meta tags, JSON-LD, perf, security, generic linting). - **Degrade gracefully.** Missing tools → fall back to static checks. - Never fail hard. Always produce VALIDATE.md, even in degraded mode. + Never fail hard. Always produce .claude/audits/VALIDATE.md, even in degraded mode. - **Framework awareness.** For SPA/JS frameworks (Next/Astro/Vite/ SvelteKit/Nuxt), validate built output (`dist/`, `_site/`, `build/`, `out/`), not JSX/TSX source. Note "Validated against built HTML at @@ -464,8 +464,7 @@ READY TO APPLY — awaiting dispatcher confirmation STOP, return control via `READY TO APPLY`. - **Cite evidence.** Every finding : `file:line` + tool output quote. Empty findings or hand-waving = bug. -- **One report.** `VALIDATE.md` at project root (or `docs/VALIDATE.md` - if convention exists). On re-run, move previous content to a +- **One report.** `.claude/audits/VALIDATE.md`. On re-run, move previous content to a `## Historique` section — do not overwrite silently. - **External validators are authoritative.** If validator.nu disagrees with `html-validate`, trust validator.nu. If jigsaw disagrees with diff --git a/skills/code-clean/SKILL.md b/skills/code-clean/SKILL.md index 3c40db1..4b36e69 100644 --- a/skills/code-clean/SKILL.md +++ b/skills/code-clean/SKILL.md @@ -7,7 +7,7 @@ description: | Trigger: "code-clean", "clean up the code", "remove dead code", "enforce code style", "cleanup", "nettoyage du code", "code hygiene". For targeted refactoring without audit → use /refactor instead. - For bug fixes discovered during cleanup → logged to BUGS-FOUND.md, not fixed here. + For bug fixes discovered during cleanup → logged to .claude/audits/BUGS-FOUND.md, not fixed here. argument-hint: disable-model-invocation: false allowed-tools: diff --git a/skills/geo/SKILL.md b/skills/geo/SKILL.md index d11fe34..b2eef2b 100644 --- a/skills/geo/SKILL.md +++ b/skills/geo/SKILL.md @@ -37,9 +37,9 @@ $ARGUMENTS ## Note on integration -If `SEO.md` already exists at project root, the geo-analyzer will +If `.claude/audits/SEO.md` already exists, the geo-analyzer will merge its findings into that file's `§7 — Optimisation GEO / IA` section (rather than writing a separate `GEO.md`). This keeps a single consolidated report when both /seo and /geo have been run. -If no `SEO.md` exists, the agent writes `GEO.md` at project root. +If no `.claude/audits/SEO.md` exists, the agent writes `.claude/audits/GEO.md` (run `mkdir -p .claude/audits` first). diff --git a/skills/harden/SKILL.md b/skills/harden/SKILL.md index 83c0e8b..0444f55 100644 --- a/skills/harden/SKILL.md +++ b/skills/harden/SKILL.md @@ -8,7 +8,7 @@ description: | (.htaccess, nginx.conf, netlify.toml, vercel.json, _headers, _redirects, wrangler.toml). Dispatches the seo-analyzer agent with a STRICT scope filter — no meta/OG/JSON-LD/sitemap/CWV/headings/alt/i18n noise. - Produces HARDEN.md at project root. + Produces .claude/audits/HARDEN.md. Trigger: "harden", "web hardening", "ssl audit", "https audit", "hsts", "csp", "security headers", "http to https", "redirect audit", "htaccess audit", "404 page", "canonical audit", "transport security", @@ -366,7 +366,7 @@ Agent( "READY TO APPLY — awaiting dispatcher confirmation" at the end. Do NOT apply any Edit/Write — the dispatcher handles STEP 3. - OUTPUT — write to /HARDEN.md : + OUTPUT — write to /.claude/audits/HARDEN.md (run `mkdir -p .claude/audits` first) : # Web Hardening Report — @@ -504,18 +504,18 @@ cached (now-READY) SSL Labs result. ## STEP 2 — Verify output ```bash -test -s HARDEN.md && wc -l HARDEN.md || echo "MISSING HARDEN.md" +test -s .claude/audits/HARDEN.md && wc -l .claude/audits/HARDEN.md || echo "MISSING .claude/audits/HARDEN.md" ``` If missing or empty : ``` -⚠️ seo-analyzer did not produce HARDEN.md. Options: +⚠️ seo-analyzer did not produce .claude/audits/HARDEN.md. Options: A) Retry with same scope B) Downgrade to LOCAL and retry (if FULL failed on network) C) Abort ``` -Extract the score and critical-alert count from HARDEN.md for the console summary. +Extract the score and critical-alert count from `.claude/audits/HARDEN.md` for the console summary. --- @@ -523,9 +523,9 @@ Extract the score and critical-alert count from HARDEN.md for the console summar Skip this step if MODE=audit. -If MODE=fix and HARDEN.md ends with `READY TO APPLY — awaiting dispatcher confirmation` : +If MODE=fix and `.claude/audits/HARDEN.md` ends with `READY TO APPLY — awaiting dispatcher confirmation` : -1. Parse the `## 8. Fix bundle` section from HARDEN.md. +1. Parse the `## 8. Fix bundle` section from `.claude/audits/HARDEN.md`. 2. Group by file. For each group, show the combined diff to the user. 3. Ask : ``` @@ -539,15 +539,15 @@ If MODE=fix and HARDEN.md ends with `READY TO APPLY — awaiting dispatcher conf A) Apply all B) Review each diff before applying C) Apply only Critique severity - D) Abort — keep HARDEN.md as audit report + D) Abort — keep .claude/audits/HARDEN.md as audit report ``` 4. On `A` : apply each bundle via Edit (targeted old_string/new_string, never full-file Write on shared templates). 5. On `B` : for each diff, show and ask yes/no/skip. 6. On `C` : filter to Critique-only, then behave as `A`. -7. On `D` : stop, leave HARDEN.md untouched. +7. On `D` : stop, leave `.claude/audits/HARDEN.md` untouched. -After applying : append a `## 10. Changes applied` section to HARDEN.md +After applying : append a `## 10. Changes applied` section to `.claude/audits/HARDEN.md` with commit-ready summary lines. Never apply fixes without explicit confirmation. Never use `--no-verify` @@ -563,8 +563,8 @@ URL : Depth : LOCAL | FULL Mode : audit | fix Score : XX / 100 ( → if fix applied) -Critical alerts : (voir HARDEN.md § 0) -Report : HARDEN.md +Critical alerts : (voir .claude/audits/HARDEN.md § 0) +Report : .claude/audits/HARDEN.md EXTERNAL VALIDATORS (FULL only) : Mozilla Observatory : (score/135) @@ -613,6 +613,5 @@ NEXT STEPS : - **SSL Labs can be slow and fail-soft.** 180s poll cap. If TIMEOUT, note it in HARDEN.md and move on. Cached result auto-hits on next run via `maxAge=24`. Never block the whole audit waiting on SSL Labs. -- **One report file.** `HARDEN.md` at project root (or `docs/HARDEN.md` - if that convention exists). On re-run, move previous content to a +- **One report file.** `.claude/audits/HARDEN.md`. On re-run, move previous content to a `## Historique` section, do not overwrite silently. diff --git a/skills/seo/SKILL.md b/skills/seo/SKILL.md index 6eea5e4..9143d49 100644 --- a/skills/seo/SKILL.md +++ b/skills/seo/SKILL.md @@ -5,7 +5,7 @@ description: | Runs the seo-analyzer (classical search — Google, Bing, DuckDuckGo) and geo-analyzer (AI search — ChatGPT, Perplexity, Claude, Gemini, Google AI Overviews, Copilot) IN PARALLEL, then consolidates their - output into a unified SEO.md report. + output into a unified .claude/audits/SEO.md report. Covers: meta, OG, JSON-LD (classical + GEO-optimised schemas), sitemap, robots.txt (including AI crawlers), llms.txt, headings, alt attrs, canonicals, hreflang, Core Web Vitals, entity SEO @@ -36,7 +36,7 @@ allowed-tools: # /seo — parallel SEO + GEO dispatcher This skill orchestrates TWO specialist agents running in parallel, then -merges their output into a single `SEO.md` report. It is the main +merges their output into a single `.claude/audits/SEO.md` report. It is the main entry point for any SEO/GEO work on a web project. ## STEP 0 — Collect shared context (ONCE) @@ -267,8 +267,8 @@ the dispatcher will merge your output with seo-analyzer's output. ## STEP 2 — Merge envelopes into SEO.md Both agents return structured envelopes keyed by SEO.md section -numbers. Consolidate them into a single `SEO.md` at project root -(or `docs/SEO.md` if that convention exists). +numbers. Consolidate them into `.claude/audits/SEO.md` +(run `mkdir -p .claude/audits` first). ### Combined score calculation diff --git a/skills/validate/SKILL.md b/skills/validate/SKILL.md index 834aca4..8492f97 100644 --- a/skills/validate/SKILL.md +++ b/skills/validate/SKILL.md @@ -4,7 +4,7 @@ description: | Web standards audit — W3C HTML validity (validator.nu), W3C CSS validity (jigsaw.w3.org/css-validator), WCAG 2.1 accessibility (axe-core, pa11y, WAVE API). Dedicated to syntactic and - accessibility conformance. Produces VALIDATE.md at project root. + accessibility conformance. Produces .claude/audits/VALIDATE.md. Dispatches the validator-analyzer agent with a STRICT scope filter — no meta/OG/JSON-LD/CWV/security-header noise. Trigger: "validate", "validation", "w3c", "html validity", @@ -220,7 +220,7 @@ Agent( "READY TO APPLY — awaiting dispatcher confirmation" at the end of §5. Do NOT apply any Edit/Write — the dispatcher handles STEP 3. - Output: write /VALIDATE.md per the structure in your + Output: write /.claude/audits/VALIDATE.md (run `mkdir -p .claude/audits` first) per the structure in your spec (sections 0-8, score XX/100). """ ) @@ -231,23 +231,23 @@ Agent( ## STEP 2 — Verify output ```bash -test -s VALIDATE.md && wc -l VALIDATE.md || echo "MISSING VALIDATE.md" +test -s .claude/audits/VALIDATE.md && wc -l .claude/audits/VALIDATE.md || echo "MISSING .claude/audits/VALIDATE.md" ``` If missing or empty : ``` -⚠️ validator-analyzer did not produce VALIDATE.md. Options : +⚠️ validator-analyzer did not produce .claude/audits/VALIDATE.md. Options : A) Retry with same scope B) Downgrade to LOCAL and retry (if FULL failed on network) C) Abort ``` -Extract the score and critical-alert count from VALIDATE.md for the +Extract the score and critical-alert count from `.claude/audits/VALIDATE.md` for the console summary : ```bash -grep -oE '\*\*Score\*\*\s+:\s+[0-9]+ / 100' VALIDATE.md | head -1 -grep -c '^### \[Critique\]' VALIDATE.md +grep -oE '\*\*Score\*\*\s+:\s+[0-9]+ / 100' .claude/audits/VALIDATE.md | head -1 +grep -c '^### \[Critique\]' .claude/audits/VALIDATE.md ``` --- @@ -256,7 +256,7 @@ grep -c '^### \[Critique\]' VALIDATE.md Skip this step if `MODE=audit`. -If VALIDATE.md ends with `READY TO APPLY — awaiting dispatcher confirmation` : +If `.claude/audits/VALIDATE.md` ends with `READY TO APPLY — awaiting dispatcher confirmation` : 1. Parse the `## 5. Fix bundle` section. 2. Group by file. For each group, show the combined diff to the user. @@ -276,7 +276,7 @@ Options : A) Apply all B) Review each diff before applying C) Apply only Critique + Haute - D) Abort — keep VALIDATE.md as audit report + D) Abort — keep .claude/audits/VALIDATE.md as audit report ``` 4. On `A` : apply each bundle via `Edit` (targeted `old_string` / @@ -284,7 +284,7 @@ Options : overwriting /seo or /geo content — meta tags, JSON-LD). 5. On `B` : for each diff, show and ask yes/no/skip. 6. On `C` : filter to Critique + Haute, then behave as `A`. -7. On `D` : stop, leave VALIDATE.md untouched. +7. On `D` : stop, leave `.claude/audits/VALIDATE.md` untouched. After applying, append a `## 8. Changes applied` section with commit-ready summary lines : @@ -322,7 +322,7 @@ URL : Depth : LOCAL | FULL Mode : audit | fix Score : XX / 100 ( → if fix applied) -Report : VALIDATE.md +Report : .claude/audits/VALIDATE.md BREAKDOWN : W3C HTML : @@ -367,8 +367,7 @@ Install for better LOCAL coverage : - **External validators are authoritative on live URLs.** validator.nu and jigsaw are the W3C backends. If a local tool disagrees with them, trust the W3C backend; flag the divergence as a finding. -- **One report file.** `VALIDATE.md` at project root (or - `docs/VALIDATE.md` if that convention exists). On re-run, move +- **One report file.** `.claude/audits/VALIDATE.md`. On re-run, move previous content to a `## Historique` section, do not overwrite silently. - **Cache dir.** `.validate-cache/` (gitignored) stores raw tool