feat(specify): surface Claude Artifacts in specs for UX/UI projects (#431)

[kevinkod]

Closes #431.

Why

For front-end / UX-UI features, a static markdown spec under-serves the user. Claude Artifacts can render mockups, interactive prototypes, and flow diagrams that make a feature tangible and easy to validate before any code is written. The CLI already gates behaviour on FE-surface detection (the accessibility audit), so a "project has a UX/UI surface" signal is an established pattern to reuse.

What

When a spec is authored for a project with a front-end surface, the generated spec now carries an optional ## Visual Prototyping with Claude Artifacts section that points the reader at the public artifacts docs.

• spec-template.md — new optional, clearly-marked conditional section. Carries the detail + two public docs links (support.claude.com "what are artifacts", code.claude.com "artifacts in Claude Code").
• specify.md phase doc — terse reinforcement of the gate. Kept lean on purpose: specnaut-specify.md is the largest Windsurf Cascade workflow and sits near the 12k-char cap, so the bulk of the guidance lives in the template (not a Windsurf workflow).
• Gate reuses the accessibility mechanism — the SAME front-end-surface signal list the a11y-auditor uses (.html/.jsx/.tsx/.vue/.svelte/.astro, an app/pages/routes markup dir, or a package.json FE-framework dep). No new heuristic.
• No FE surface → section removed entirely. A back-end / CLI-only spec stays artifact-free (mirrors the "remove inapplicable sections" rule).

Boundary (§ I)

Only the public Claude Artifacts product and its public docs are referenced — nothing from the private Cloud half. The user's original "artefacts côté cloud" means Claude's hosted Artifacts (claude.ai), not specnaut-cloud.

Tests

• tests/templates/artifacts_in_specs_test.ts (new) — locks the bundled spec-template + specify content: the section ships, both docs links are present, the gate defers to a11y-auditor, and the remove-if-no-FE instruction is present.
• Plugin copy + local golden kept byte-identical; deno task bundle regenerated.
• Full suite: 1137 passed. deno fmt --check + deno lint clean.

Agent adoption

/specnaut specify now adds an optional Visual Prototyping with Claude Artifacts section to generated specs when your project has a front-end / UX-UI surface (detected via the same signals the accessibility gate uses). Specs authored before this upgrade won't have it retroactively — run the prompt below to backfill any in-flight UX/UI specs, and to update any project-local spec-template override you maintain.

Check whether this project has a front-end surface (any of: .html/.htm,
.jsx/.tsx, .vue/.svelte/.astro files; a public/, src/app/, src/pages/,
src/routes/, or pages/ markup dir; or a package.json listing react, vue,
svelte, solid-js, preact, lit, astro, @angular/core, or qwik).

If it does:
  1. For each in-flight spec under .specnaut/specs/*/spec.md that lacks a
     "## Visual Prototyping with Claude Artifacts" section, add one after
     Assumptions that points the reader at Claude Artifacts for visualising
     the UX, with links to the public artifacts docs.
  2. If you keep a customised .specnaut/templates/spec-template.md override,
     mirror the same optional, FE-gated section into it.

If this project has NO front-end surface, do nothing — a back-end/CLI-only
spec must stay artifact-free.

🤖 Generated with Claude Code