baldart 3.40.0 → 4.0.0

package/framework/.claude/commands/qa.md

@@ -27,7 +27,7 @@ You are the **QA Orchestrator**. When the user invokes `/qa [profile] [--card FE
 
 ## Step 1 — Gather Context (always)
 
-Run these in parallel:
+Run these in parallel (resolve `<base-branch>` from `git.trunk_branch` in `baldart.config.yml`; if absent, autodetect the integration branch):
 - `git rev-parse --abbrev-ref HEAD`
 - `git log -1 --pretty="%h %s"`
 - `git diff --name-only <base-branch>...HEAD 2>/dev/null || git diff --name-only HEAD~1`
@@ -38,7 +38,7 @@ Run these in parallel:
 - **MEDIUM**: everything else (feature modules, components, utilities)
 - **LOW**: only `.md`, `.yml`, style/CSS, test files, config — no logic changes
 
-If risk is HIGH and profile is LIGHT, warn the user: "Risk level is HIGH — consider running `/qa balanced` or `/qa deep` for better coverage."
+If risk is HIGH and profile is LIGHT, warn the user: "Risk level is HIGH — consider running `/qa balanced` or `/qa deep` for better coverage." This warning is advisory; the run proceeds, but the caveat MUST be carried into the QA Verdict block (Step 7) so a HIGH-risk LIGHT pass is never silently equivalent to a full one. (For per-card test depth in `/new`, the card's `review_profile` value governs scope — `review_profile` is computed by prd-card-writer (Rule C); see prd-card-writer.md for the criteria.)
 
 ---
 
@@ -98,14 +98,14 @@ Write the initial file:
 
 ## Step 3 — Execute Profile
 
-### LIGHT — Fast confidence (<3 min target)
+### LIGHT — Fast confidence (<3 min target [DESIGN-CHOICE: scoped to lint + type-check + related tests only; sufficient for low-risk or doc-only diffs])
 
 Run directly in this session (no sub-agents):
 
 1. Extract changed source files from the diff.
 2. Lint check on changed files — if no changed files, skip with note.
 3. Type check (e.g., `npx tsc --noEmit`)
-4. Scoped tests — if test pattern unclear, run full suite.
+4. Scoped tests — run only tests related to the changed files (related-tests / testPathPattern on touched modules). If no related tests are found, record `Tests: SKIP — no related tests` and cap confidence; do NOT fall through to the full suite.
 5. Build check.
 
 For each step: report PASS / FAIL. On FAIL, show the exact error output.
@@ -118,16 +118,16 @@ No findings file required. Present final verdict immediately.
 
 ### BALANCED — Solid validation (default)
 
-**Decide on parallelization first:**
-- If 3+ clearly independent risk tracks exist (e.g., auth + payments + UI, or unit + integration + DB) → use the parallel agent strategy below.
-- Otherwise → invoke a single `qa-sentinel` agent.
+qa-sentinel is a **mechanical gate-runner** (lint / tsc / scoped-or-full tests / build / `npm audit`):
+it returns PASS/FAIL + a gate table + confidence. It does NOT read source files, exercise flows, run
+a dev server, or do collateral-impact analysis. Behavioral / collateral / dev-server work in BALANCED
+belongs to the e2e and code-aware reviewers, not to qa-sentinel.
 
-**Single-agent path:**
-
-Invoke `qa-sentinel` via Task tool:
+Invoke `qa-sentinel` via Task tool to run the gates:
 
 ```
-Run FULL VALIDATION MODE on the current changeset.
+Run the mechanical QA gates on the current changeset at the tier dictated by the QA profile below
+(do NOT default to FULL).
 
 Context:
 - Branch: <branch>
@@ -135,22 +135,25 @@ Context:
 - Changed files: <list from git diff>
 - Risk level: <Low/Medium/High>
 - Card: <CARD-ID or "none">
+- QA profile: <the profile this /qa was invoked with: balanced | deep>
 
-After completing validation gates (lint, tsc, tests, build, audit):
-1. Start the dev server if appropriate for the change, exercise key flows, and check for server/browser console errors and unexpected 4xx/5xx responses. Focus on flows directly touched by the diff.
-2. Identify collateral impacts on adjacent features not directly in the diff.
-3. Return your full QA Report (all gates + findings).
+Tier contract: balanced → SCOPED (related tests on touched modules); deep → FULL suite. Only
+path-based risk drift (auth/permission/payment/schema/migration/API contract in the diff) may
+escalate balanced→FULL.
 
-Findings file to update: /qa/<file>.md
+Run lint, tsc, tests (per tier), build, and (deep) npm audit. Return PASS/FAIL + the gate table +
+confidence. Do NOT read source files, start a dev server, or analyze collateral impact — those are
+out of scope for this agent.
 ```
 
-After `qa-sentinel` completes:
+After `qa-sentinel` returns its PASS/FAIL + gate table:
 - Read its output.
-- Append all findings to `/qa/<file>.md` under the `## Findings` section.
-
-**Parallel-agent path (when warranted):**
+- Append the gate results to `/qa/<file>.md` under the `## Findings` section.
 
-See Step 4 below.
+**Collateral / behavioral coverage (BALANCED):** if the diff touches user-facing flows and you need
+behavioral confidence beyond the gates, use the parallel-agent path below (Step 4) — it routes
+flow-exercising and collateral-impact analysis to the appropriate code-aware / e2e agents rather than
+to qa-sentinel.
 
 ---
 
@@ -167,26 +170,31 @@ Run everything in BALANCED, plus:
 - Use MCP Playwright (if available) to open key flows related to the diff and take screenshots, checking for console errors and visual regressions.
 - Validate: login/auth flow, critical navigation, any flow directly touched by the diff.
 
-Run the e2e pass in parallel with the `qa-sentinel` FULL VALIDATION (launch both as sub-agents simultaneously).
+Run the e2e pass in parallel with the `qa-sentinel` FULL-tier gate run (launch both as sub-agents simultaneously). This inline two-agent launch is the DEEP default; escalate to the team-based strategy (Step 4) ONLY when 3+ clearly independent risk tracks exist [DESIGN-CHOICE: below this threshold, TeamCreate overhead exceeds benefit; two inline Task spawns are sufficient]. A DEEP run with fewer than 3 tracks stays on this inline path and does NOT create a team.
 
 ---
 
 ## Step 4 — Parallel Agent Strategy (Balanced/Deep when warranted)
 
-Use this when 3+ independent tracks exist.
+Use this when 3+ independent tracks exist [DESIGN-CHOICE: same threshold as DEEP inline gate — ensures consistent entry point for team-based parallelism].
 
 Create a team: `TeamCreate` with name `qa-<CARD-or-timestamp>`.
 
 Create tasks:
-- **Task A**: Unit + Lint + TypeScript — `qa-sentinel` quick subset
-- **Task B**: Integration + DB + API contract + Build — `qa-sentinel` full subset
-- **Task C** (Deep only): E2E + UI validation
-- **Task D**: Dev server log inspection + collateral impact analysis on adjacent features
+- **Task A**: Lint + TypeScript + scoped tests — `qa-sentinel` (gate run, SCOPED tier)
+- **Task B**: Full tests + build + audit — `qa-sentinel` (gate run, FULL tier)
+- **Task C** (Deep only): E2E + UI validation — `e2e-review` skill / Playwright
+- **Task D**: Collateral-impact analysis on adjacent features not in the diff — `code-reviewer` (reads source, reasons about ripple)
 
 Spawn agents in parallel (single message, multiple Task tool calls):
-- Agent A: `qa-sentinel`, tasks A + D
+- Agent A: `qa-sentinel`, task A
 - Agent B: `qa-sentinel`, task B
-- Agent C (Deep only): general-purpose agent, task C
+- Agent C (Deep only): run the `e2e-review` skill / Playwright pass for task C
+- Agent D: `code-reviewer`, task D
+
+qa-sentinel runs gates only (tasks A + B); it never receives Task D — collateral-impact analysis
+requires reading source, which qa-sentinel is forbidden from doing. If a named specialist is
+unavailable, surface `CAPABILITY_UNAVAILABLE: <agent>` and halt — never substitute a generic agent.
 
 Each agent sends findings to orchestrator via `SendMessage`. Orchestrator consolidates ALL findings into `/qa/<file>.md`.
 
@@ -215,16 +223,33 @@ After all agents/checks complete, update `/qa/<file>.md` — replace the `## Fin
 
 **Only if BLOCKER or MAJOR findings exist:**
 
-1. Invoke the **coder** agent (subagent_type: `coder`):
-   - Provide: findings file path + instruction to fix all BLOCKERs, fix MAJORs unless they require architectural change, add regression tests for all bug fixes.
-   - Do NOT ask the user — proceed directly.
-
-2. After coder completes:
-   - Re-run LIGHT profile on the fixed files to verify corrections.
-   - Invoke `doc-reviewer` and `code-reviewer` in parallel (read-only audit).
+1. Invoke the **coder** agent (subagent_type: `coder`). The coder has mandatory pre-conditions (it
+   reads a backlog card at startup, sets it IN_PROGRESS, and reads the card's `git_strategy`) and is
+   forbidden from switching branches — so it MUST be given the context it needs:
+   - **Card ID** (the resolved `<CARD-ID>` from Step 0). If Step 0 fell back to a `session-…`
+     timestamp (no card), do NOT auto-invoke the coder — there is no card for it to read. Instead,
+     surface the findings to the user and ask whether to create a card or fix manually.
+   - **Branch**: spawn the coder on the current branch (the one the diff lives on); it stays there.
+   - **Findings file path** + instruction to fix all BLOCKERs, fix MAJORs unless they require
+     architectural change, and add a regression test for every bug fix.
+   - Do NOT ask the user about whether to fix — proceed directly once a card exists.
+
+2. After coder completes, re-verify through proper subagent spawns (so results are written and
+   tracked, never run loose in this orchestrator's context):
+   - Re-invoke `qa-sentinel` (gate run, SCOPED tier) on the fixed files. It writes its
+     PASS/FAIL + gate table to `/qa/<CARD-ID>.md` and returns the structured `QA DONE` signal; the
+     orchestrator does NOT run gates in-session.
+   - Invoke `code-reviewer` (read-only audit) to confirm the fixes are correct. Invoke `doc-reviewer`
+     only if the fix touched documented behavior.
    - For DEEP: also re-run e2e smoke tests to verify UI still passes.
 
-3. Update `/qa/<file>.md` with post-fix results under a new section `## Post-Fix Verification`.
+   > **Avoid double review when embedded in `/new`**: if this `/qa` run is part of `/new`'s pipeline,
+   > `/new`'s `/codexreview` pre-merge gate already runs `code-reviewer` (and `doc-reviewer`) on the
+   > same diff. Do NOT re-run them here in that case — let the `/codexreview` gate be the single
+   > review pass and only re-run the qa-sentinel gates to confirm the fix.
+
+3. Update `/qa/<file>.md` with post-fix results under a new section `## Post-Fix Verification`,
+   including the re-run qa-sentinel verdict and any re-review findings.
 
 ---
 

package/framework/.claude/skills/context-primer/SKILL.md

@@ -15,8 +15,8 @@ Load structured, task-adaptive context about a topic into the conversation befor
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`.
-**Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
+**Reads from `baldart.config.yml`:** `paths.backlog_dir`, `paths.references_dir`, `paths.prd_dir`, `paths.wiki_dir`, `paths.adrs_dir`, `paths.wiki_log`.
+**Gated by features:** `features.has_backlog` (skip backlog grep when `false`), `features.has_wiki_overlay` (skip wiki search AND the wiki-log instrumentation tap), `features.has_adrs` (skip ADR includes), `features.has_prd_workflow` (skip PRD reads).
 **Overlay:** loads `.baldart/overlays/context-primer.md` if present — project-specific topic vocabulary, must-include canonical docs.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
 
@@ -59,7 +59,15 @@ SEARCH STRATEGY — RAG-first, verify-only-if-needed:
    Pass invoker_agent="context-primer" — this OVERRIDES your own default
    (codebase-architect) for every call you make on behalf of this skill,
    so telemetry attributes the query to the initiating skill, not the subagent.
-   Check rag_telemetry.verdict in the response:
+
+   NOTE: the search_docs MCP tool and its rag_telemetry.verdict field only
+   exist when a RAG/Obsidian doc-search layer is connected. If search_docs is
+   NOT available (no MCP tool), or it returns no rag_telemetry block, treat the
+   verdict as "empty" and go straight to the full manual search (steps 2-3) —
+   do NOT fabricate a verdict or stall waiting for a field that will never
+   appear. Emit no error; this is the normal no-RAG path.
+
+   When the field IS present, check rag_telemetry.verdict in the response:
    - "useful" → RAG is your PRIMARY source. Go to step 4.
    - "weak"/"fallback_degraded" → supplement with steps 2-3.
    - "empty" → full manual search (steps 2-3).
@@ -132,15 +140,28 @@ Return output in this EXACT XML format (30-50 lines max):
     <note acquired="YYYY-MM-DD">Note content</note>
     <note acquired="YYYY-MM-DD" stale="true">Old note [STALE — verify]</note>
   </memory_notes>
+  <!-- If no RAG layer was available, set verdict="unavailable" count="0" mode="none" -->
   <rag_quality verdict="{rag_telemetry.verdict}" count="{count}" mode="{mode}"/>
 </context_primer>
 
 WIKI LOG INSTRUMENTATION (FEAT-0805 — tap point of the auto-learning loop):
-After every search_docs call, inspect the returned rag_telemetry.verdict.
-If verdict ∈ {"weak", "empty", "fallback_degraded"}, log one entry to the
-wiki log so the nightly wiki-review can detect coverage gaps:
-
-  python3 -c "import sys; sys.path.insert(0, 'tools/doc-rag'); \
+This tap is GATED. Only attempt it when `features.has_wiki_overlay: true` AND
+`paths.wiki_log` is set in `baldart.config.yml` (it points at the project's
+wiki-log tap MODULE FILE, e.g. `tools/doc-rag/wiki_log.py` — there is no
+hardcoded `tools/doc-rag` default; that path is one consumer's layout and does
+not resolve elsewhere). If either is absent, SKIP the tap entirely and emit a
+single stderr WARNING
+"wiki_log skipped: features.has_wiki_overlay/paths.wiki_log not configured" —
+never silently no-op, and never assume a default path.
+
+When enabled: after every search_docs call, inspect the returned
+rag_telemetry.verdict. If verdict ∈ {"weak", "empty", "fallback_degraded"},
+log one entry to the wiki log so the nightly wiki-review can detect coverage
+gaps. Resolve `<wiki_log_dir>` as the PARENT DIRECTORY of `paths.wiki_log`
+(i.e. `dirname` — the importable package dir; `paths.wiki_log` itself is the
+`wiki_log.py` file):
+
+  python3 -c "import sys; sys.path.insert(0, '<wiki_log_dir>'); \
     from wiki_log import append_entry; \
     append_entry(entry_type='query', title='<query_short>', \
       agent='context-primer', \

package/framework/.claude/skills/doc-writing-for-rag/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: doc-writing-for-rag
-description: "Scrive documentazione di reference ad alta densità ottimizzata per RAG indexing. Usa template compatti, frontmatter minimal, cross-reference a schemas.md/errors.md (paths da `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Carica questa skill quando crei o riscrivi file in `${paths.references_dir}`, `${paths.prd_dir}`, o quando senti 'template endpoint', 'compattare docs', 'doc per RAG', 'dense documentation', 'signal/noise ratio'."
+description: "Writes high-density reference documentation optimized for RAG indexing. Uses compact templates, minimal frontmatter, cross-references to schemas.md/errors.md (paths from `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Load this skill when creating or rewriting files in `${paths.references_dir}`, `${paths.prd_dir}`, or when you hear 'endpoint template', 'compact docs', 'doc for RAG', 'dense documentation', 'signal/noise ratio'."
 ---
 
 # Doc Writing for RAG
 
-Protocollo di scrittura per reference docs ottimizzate per LightRAG indexing. Validato su 45 file in 3 wave di compressione (-48% linee medio, signal/noise da 45% a 80%+).
+Writing protocol for reference docs optimized for LightRAG indexing. Validated on 45 files across 3 compression waves (−48% average lines, signal/noise from 45% to 80%+).
 
 ## Project Context
 
@@ -16,35 +16,35 @@ Protocollo di scrittura per reference docs ottimizzate per LightRAG indexing. Va
 
 ## When to Use
 
-Carica questa skill quando:
+Load this skill when:
 
-- **Nuovo reference doc** da scrivere (es. nuovo dominio API, UI page, collection)
-- **Major rewrite** di file esistente >1500 linee o con S/N basso
-- **Nuovo endpoint API** da documentare in file esistente
-- **Extending** `schemas.md` o `errors.md` con nuovi schemi/codes
+- **New reference doc** to write (e.g. new API domain, UI page, collection)
+- **Major rewrite** of an existing file >1500 lines or with low signal/noise ratio
+- **New API endpoint** to document in an existing file
+- **Extending** `schemas.md` or `errors.md` with new schemas/codes
 
-NON caricare per:
-- Review incrementale di file esistenti (usa doc-reviewer-support)
-- Scrittura di ADR (diversi, già densi, vedi writing-guide)
-- PRD discovery/ideation (usa prd skill)
-- Business/marketing copy (usa copywriting skill)
+Do NOT load for:
+- Incremental review of existing files (use `doc-reviewer-support` if installed — see Related Skills)
+- Writing ADRs (different format, already dense — see writing-guide)
+- PRD discovery/ideation (use the `prd` skill)
+- Business/marketing copy (use the `copywriting` skill)
 
 ## Core Principles
 
-1. **Cross-reference over repetition**: un concetto spiegato UNA VOLTA, linkato altrove
-2. **Tables > prose** per info strutturate (endpoint params, error codes, schemas)
-3. **Frontmatter minimo**: 4 campi (doc_type, domain, canonicality, last_updated). Niente audit_notes, freshness_status, stale_*, owner, status (derivabili da git)
-4. **Central support files**: `schemas.md` per JSON schemas riusabili, `errors.md` per error codes
+1. **Cross-reference over repetition**: one concept explained ONCE, linked elsewhere
+2. **Tables > prose** for structured information (endpoint params, error codes, schemas)
+3. **Minimal frontmatter**: 4 fields (doc_type, domain, canonicality, last_updated). No audit_notes, freshness_status, stale_*, owner, status (derivable from git)
+4. **Central support files**: `schemas.md` for reusable JSON schemas, `errors.md` for error codes
 5. **Line count targets**: API ref <1500, PRD <1500, ADR <200, index <500
-6. **Descrittivo ma denso**: preserva TUTTA l'info semantica, comprimi solo verbosità
+6. **Descriptive but dense**: preserve ALL semantic information, compress only verbosity
 
-## Workflow — Nuovo endpoint API
+## Workflow — New API Endpoint
 
-1. **Check schemas.md** (`${paths.api_schemas}`): lo schema response esiste già? Se sì, riusalo. Se no, definiscilo DOPO aver scritto l'endpoint, in APPEND alla sezione di dominio appropriata. (Skip when `features.has_api_docs: false`.)
+1. **Check schemas.md** (`${paths.api_schemas}`): does the response schema already exist? If yes, reuse it. If no, define it AFTER writing the endpoint, APPENDed to the appropriate domain section. (Skip when `features.has_api_docs: false`.)
 
-2. **Check errors.md** (`${paths.api_errors}`): gli error codes esistono già nella domain section? Se sì, riusali. Se no, aggiungili APPEND in domain section. (Skip when `features.has_api_docs: false`.)
+2. **Check errors.md** (`${paths.api_errors}`): do the error codes already exist in the domain section? If yes, reuse them. If no, APPEND them in the domain section. (Skip when `features.has_api_docs: false`.)
 
-3. **Scrivi endpoint con template compatto**:
+3. **Write endpoint using compact template**:
    ```markdown
    ### POST /api/v1/domain/resource
 
@@ -60,16 +60,16 @@ NON caricare per:
    **Errors**: RESOURCE_NOT_FOUND, INVALID_NAME ([errors.md](../errors.md#domain-domain))
    ```
 
-4. **Path relativi corretti** (dipende dalla location del file):
+4. **Correct relative paths** (depends on file location):
    - `api/*.md` → `./schemas.md` + `../errors.md`
    - `api/booking/*.md` → `../schemas.md` + `../../errors.md`
    - `api/survey/*.md` → `../schemas.md` + `../../errors.md`
 
-5. **Verifica line count**: se il file supera 1500 linee → split in sub-files per dominio.
+5. **Verify line count**: if the file exceeds 1500 lines → split into sub-files per domain.
 
-## Template snippets inline
+## Template Snippets
 
-### Frontmatter minimo (mandatory)
+### Minimal frontmatter (mandatory)
 
 ```yaml
 ---
@@ -80,7 +80,7 @@ last_updated: 2026-04-05
 ---
 ```
 
-Altri campi (owner, status, audit_notes, freshness_status, stale_*) sono **derivabili** da git blame / tooling → **non scriverli**.
+Other fields (owner, status, audit_notes, freshness_status, stale_*) are **derivable** from git blame / tooling → **do not write them**.
 
 ### Compact endpoint (mandatory)
 
@@ -89,15 +89,15 @@ Altri campi (owner, status, audit_notes, freshness_status, stale_*) sono **deriv
 
 **Auth**: hook  |  **Access**: roles
 
-**Body** / **Query** / **Params**: tabella 4 colonne
+**Body** / **Query** / **Params**: 4-column table
 
 **Returns**: [Schema](schemas#anchor)
 **Errors**: CODE1, CODE2 ([errors.md](errors#domain))
 ```
 
-### Cross-reference section (per concetti ripetuti)
+### Cross-reference section (for repeated concepts)
 
-Spiegazione completa **una sola volta** nella intro del file, poi:
+Full explanation **once** in the file intro, then:
 ```markdown
 See [§Store Access Control](#store-access-control) for gating details.
 ```
@@ -106,14 +106,14 @@ See [§Store Access Control](#store-access-control) for gating details.
 
 | Reference | When to load |
 |-----------|--------------|
-| `references/compact-templates.md` | Scrittura nuovo endpoint/UI/PRD/collection |
-| `references/schemas-and-errors.md` | Estensione di schemas.md o errors.md |
-| `references/frontmatter-minimal.md` | Definire frontmatter di un nuovo file |
-| `references/line-count-targets.md` | File > soglia, decidere se splittare |
-| `references/before-after-examples.md` | Vuoi esempi concreti Wave 1+2+3 |
+| `references/compact-templates.md` | Writing new endpoint/UI/PRD/collection |
+| `references/schemas-and-errors.md` | Extending schemas.md or errors.md |
+| `references/frontmatter-minimal.md` | Defining frontmatter for a new file |
+| `references/line-count-targets.md` | File > threshold, deciding whether to split |
+| `references/before-after-examples.md` | Want concrete Wave 1+2+3 examples |
 
 ## Related Skills
 
-- `doc-reviewer-support`: review checklists, invariant tables, navigation audit
-- `prd`: PRD discovery & ideation (diverso scope)
+- `doc-reviewer-support` (OPTIONAL — not shipped with the framework): review checklists, invariant tables, navigation audit. If present, use its format; if absent, proceed without it and perform review inline.
+- `prd`: PRD discovery & ideation (different scope)
 - `copywriting`: marketing/UX copy

package/framework/.claude/skills/frontend-design/SKILL.md

@@ -196,13 +196,15 @@ These apply to every form, every project — they are not "nice to have":
 
 ---
 
-## Prototipi Standalone e Demo
+## Standalone Prototypes and Demos
 
-Quando il task richiede un prototipo HTML interattivo, demo animata, slide deck, mockup iOS/app, o design exploration **NON legato alla codebase Next.js** (nessun contesto `src/app/`), invocare la skill `huashu-design` in aggiunta o al posto di questa skill. Essa fornisce:
-- App Prototype shell (AppPhone state manager, tappabile, iPhone frame)
-- Tweaks panel per varianti in-page
-- Export animazioni → MP4/GIF (25fps base, 60fps interpolato)
-- 5 flussi × 20 filosofie di design per design exploration
-- Validazione Playwright click-test prima della consegna
+When the task calls for an interactive HTML prototype, animated demo, slide deck, iOS/app mockup, or design exploration **not tied to the project codebase**, the `huashu-design` skill can supplement or replace this skill. It provides:
+- App Prototype shell (AppPhone state manager, tappable, iPhone frame)
+- Tweaks panel for in-page variants
+- Animation export → MP4/GIF (25fps base, 60fps interpolated)
+- 5 flows × 20 design philosophies for design exploration
+- Playwright click-test validation before delivery
 
-**Regola del Filesystem (ASSOLUTA):** ogni output HTML/prototipo deve essere scritto su disco con il tool `Write` PRIMA di aprirlo in Safari o condividerlo con l'utente. Non è sufficiente outputtare blocchi di codice inline.
+**`huashu-design` is OPTIONAL** — it is a user-installed skill, not shipped with the framework. If it is not present, proceed with this skill alone and notify the user: "huashu-design not found; continuing with frontend-design only. Install huashu-design for advanced prototype tooling."
+
+**Filesystem Rule (ABSOLUTE):** every HTML output/prototype must be written to disk with the `Write` tool BEFORE opening it in a browser or sharing it with the user. Outputting inline code blocks is not sufficient.