baldart 4.78.1 → 4.79.0

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -30,35 +30,50 @@ unchanged. No other side-effect of Step 3.0.
 
 ### Branch B — Claude Design handoff
 
-1. **Collect context from the state file + config + overlays:**
-   - `feature_title`, `feature_objective_one_sentence` from `## Feature Description`.
-   - `user_flow_summary`, `primary_personas` from `## Discovery Log` (dimensions 1 + 2).
-   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA touchpoints if not yet populated — same logic as Hybrid mode § "Build the per-screen routing table").
-   - `brand_voice` from `.baldart/overlays/prd.md` if present (skip section otherwise).
-   - When `features.has_design_system: true`: read `${paths.design_system}/INDEX.md` (primitive list) + `${paths.design_system}/tokens-reference.md` (tokens excerpt). When `false`: omit § 5 of the prompt entirely.
-   - `stack.framework`, `stack.charting`, `stack.animation` from `baldart.config.yml`.
-   - `output_format_preference` derived from `stack.framework` (Next/Remix → React+Tailwind; vanilla → HTML/CSS; otherwise ask the user).
-   - Numeric token tables (type scale, spacing, radius, contrast, motion durations) from `framework/agents/design-system-protocol.md` — cite verbatim.
-
-2. **Render the prompt** by populating
-   [../assets/claude-design-handoff-prompt.template.md](../assets/claude-design-handoff-prompt.template.md)
-   with the collected context. Strip empty conditional sections.
-
-3. **Present the rendered prompt** to the user inside a fenced markdown
-   code-block, prefixed with this instruction (verbatim):
+The handoff prompt is owned by the **`ds-handoff` skill** (the single SSOT). `/prd`
+decides to hand off; `/ds-handoff` builds the field-level, 1:1 brief — it grounds
+every screen's fields in the real data schemas and runs a coverage gate **before**
+emitting, so Claude Design does not have to imagine the fields. (This is the same
+delegate-or-else-inline contract as `/prd` → `/ds-new`.)
+
+1. **Delegate to `/ds-handoff`.** Invoke it in *delegated* mode, passing the
+   resolved context so it skips its own screen-resolution prompt:
+   - the state-file path;
+   - `feature_title`, `feature_objective_one_sentence` (from `## Feature Description`);
+   - `user_flow_summary`, `primary_personas` (from `## Discovery Log` dimensions 1 + 2);
+   - `screens_in_scope[]` from `## UI Design` (derive from User Stories + ISA
+     touchpoints if not yet populated — same logic as Hybrid mode § "Build the
+     per-screen routing table");
+   - `mockup_analysis` from `## UI Design` if present (the skill reads its
+     `layout / component_props / states / responsive` as input);
+   - the `features.has_design_system` flag (the skill omits § 5 when `false`).
+
+   `/ds-handoff` runs field extraction + the coverage gate + the mandatory template
+   and returns the **rendered prompt** plus the **`field-inventory.md` path**.
+
+   **Graceful fallback** — if `/ds-handoff` is unavailable (Codex without it linked,
+   or an older install): render a **coarse** brief inline from `screens_in_scope[]`
+   (per-screen: scopo / stati / azioni primarie / dati visualizzati) and the same
+   top-level sections (obiettivo, user flow, brand, design system, stack, cosa
+   restituirmi). State explicitly to the user: *"field-level brief non disponibile →
+   brief coarse"*, so the lost fidelity is visible, not silent.
+
+2. **Present the returned prompt** to the user inside a fenced markdown code-block,
+   prefixed with this instruction (verbatim):
 
    > Incolla il prompt qui sotto in Claude Design. Quando hai i mockup pronti,
    > tornami con i **path locali** dei file (PNG, HTML, TSX, o link Figma) e
    > riprendo da qui — copio i file nella cartella del PRD, li analizzo come
    > al solito (Step 1.6 Mockup Intake), e Step 3 entra in Hybrid mode.
 
-4. **Update state file** before stopping:
+3. **Update state file** before stopping:
    - `mockups.status: pending_external`
    - `mockups.source: claude-design`
    - `mockups.handoff_prompt_path: ${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` (save the rendered prompt to disk so it survives session restarts).
+   - `mockups.field_inventory_path: ${paths.prd_dir}/<slug>/mockups/field-inventory.md` (the path `/ds-handoff` returned; omit on the coarse fallback).
    - `step_3_mode: pending_external_handoff` (transitional — overwritten when user returns).
 
-5. **STOP.** Wait for the user to return with local paths.
+4. **STOP.** Wait for the user to return with local paths.
 
 ### Re-entry from handoff (user returns with paths)
 

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

@@ -246,6 +246,14 @@ prevent**: catching a duplicate primitive at the mockup stage costs minutes,
 catching it after implementation costs a refactor. The weekly `ds-drift`
 routine is a safety net, not a substitute for this check.
 
+**Downstream visual verification (nudge, not a gate).** The chosen design is
+verified visually **at the mockup stage** here (Step D evaluator). The fidelity
+of the *implemented* result against this design is verified **downstream**, when
+the design lands in a live route: that is `/e2e-review` Phase 4 — auto-run by
+`/new`, or invoke `/e2e-review CARD-ID` manually if you implement this design
+outside the `/new` pipeline. This is where route-level fidelity lives; it is a
+pointer, never a blocking obligation on this skill.
+
 ---
 
 ## Design Principles (quick reference)

package/framework/agents/skills-mapping.md

@@ -24,6 +24,10 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > This map references **only skills shipped under `framework/.claude/skills/`**.
 > Confirm a skill exists (its directory is present) before routing to it; never
 > route to a skill name that has no directory.
+>
+> **Gating.** Many skills are gated on a `features.*` flag in `baldart.config.yml`
+> (noted per entry). When the flag is `false` the skill REFUSES — do not route to
+> it; resolve the gate first (e.g. `/design-system-init` for `has_design_system`).
 
 ## Core Development Skills
 
@@ -43,6 +47,19 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Nuova funzionalità"
 - "How should I scope..."
 
+### prd-add
+
+**When to use**:
+
+- A new requirement lands on an ACTIVE `/prd` session (change request)
+- "serve anche…", a missing endpoint/sub-feature surfaces mid-discovery
+- Runs ICIAS impact analysis to decide which PRD phases SKIP / PATCH / REDO
+
+**Triggers**:
+
+- "/prd-add"
+- "Aggiungi requisito" / "Serve anche" / "Manca un endpoint"
+
 ### context-primer
 
 **When to use**:
@@ -68,6 +85,20 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Implementa le card"
 - "Esegui le card"
 
+### new2
+
+**When to use**:
+
+- EXPERIMENTAL workflow-hosted variant of `/new` (A/B testing context economy)
+- The whole card batch runs in a background dynamic workflow (subagent output never
+  enters the main context); every `/new` gate becomes a deterministic policy
+- **Claude-only** (needs the `Workflow` tool)
+
+**Triggers**:
+
+- "/new2 CARD-IDS"
+- "Implementa le card con workflow"
+
 ### bug
 
 **When to use**:
@@ -82,6 +113,30 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Fix [bug]"
 - "Non funziona" / "Why is [X] not working?"
 
+### worktree-manager
+
+**When to use**:
+
+- Parallel coding agents needing fully independent git worktrees
+- Create / merge (→ PR) / list / cleanup isolated workspaces
+- Used programmatically by `/new` for per-card worktree ops
+
+**Triggers**:
+
+- "/nw" (new) · "/mw" (merge) · "/lw" (list) · "/cw" (cleanup)
+- "New worktree" / "Merge worktree"
+
+### issue-review
+
+**When to use**:
+
+- Triage / planning a GitHub issue (summary + priority + plan + tests)
+
+**Triggers**:
+
+- "/issue-review"
+- "Triage this issue" / "Review issue [N]"
+
 ## Code Quality Skills
 
 ### simplify
@@ -136,7 +191,129 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 > standalone invocable BALDART skill. Route UI work through `ui-design` /
 > `ui-expert`, not to `ui-ux-pro-max` directly.
 
-## Testing Skills
+### motion-design
+
+**When to use**:
+
+- Animations, transitions, micro-interactions, loading/page transitions
+- Scroll-triggered effects, choreography, timing/easing decisions
+- Works with CSS / Framer Motion / GSAP / Lottie / Spring
+
+**Triggers**:
+
+- "/motion-design"
+- "Anima…" / "transition" / "micro-interaction"
+
+### gamification-design
+
+**When to use**:
+
+- Points systems, reward loops, progression mechanics, loyalty/retention
+- B2C customer-facing engagement features
+
+**Triggers**:
+
+- "/gamification-design"
+- "Punti / reward / progression / battle pass / loyalty"
+
+## Design System Skills
+
+> All gated on `features.has_design_system: true`. Without a registry, bootstrap
+> first with `/design-system-init`.
+
+### design-system-init
+
+**When to use**:
+
+- GREENFIELD: bootstrap a component registry (INDEX.md + DTCG tokens + per-component specs) and flip `has_design_system`
+- UPGRADE: regenerate machine-readable HEADs / DTCG tokens on an existing prose-only registry
+- SEED: a registry born in Claude Design (design-led)
+
+**Triggers**:
+
+- "/design-system-init"
+- "Crea design system" / "inizializza registro componenti" / "aggiorna le spec"
+- `baldart doctor` nudges (specs missing / prose-only)
+
+### ds-new
+
+**When to use**:
+
+- Create ONE canonical element (a component OR a token) end-to-end: reuse-first → optional scaffold → document + register + govern + verify
+- The on-the-fly twin of the bulk `design-system-init`; callable by `/prd` when reconciliation confirms a NEW component
+
+**Triggers**:
+
+- "/ds-new" · "/ds-new token [id]"
+- "Nuovo componente design system" / "registra una primitive" / "aggiungi un token"
+
+### ds-edit
+
+**When to use**:
+
+- Deliberately edit ONE existing element: resync / extend-variant / breaking / re-govern
+- Regenerates the spec preserving agentic fields + prose
+- NOT for the automatic mechanical doc-resync after a code change (that's already automatic via the `DS_COMPONENT_STALE` gate)
+
+**Triggers**:
+
+- "/ds-edit"
+- "Aggiungi una variante" / "modifica un componente" / "breaking change su un componente"
+
+### ds-render
+
+**When to use**:
+
+- Render design-system primitives in ISOLATION (one component × variant) to a PNG each
+- Feeds isolated QUALITY verification (`/e2e-review` Phase 4b/4c) — never a fidelity diff
+- Rides on a detected Storybook (clean no-op otherwise)
+
+**Triggers**:
+
+- "/ds-render"
+- "Render i componenti" / "screenshot dei primitivi"
+
+### ds-handoff
+
+**When to use**:
+
+- Produce the FIELD-LEVEL, 1:1 Claude Design handoff prompt — every screen's real fields (label / control / required / validation / default / enum / helper / readonly), grounded in the project's data schemas, coverage-gated before emission
+- The single SSOT for the Claude Design prompt; `/prd` Step 3.0 Branch B delegates here
+- Standalone for an ad-hoc orchestrator + `ui-expert` run
+
+**Triggers**:
+
+- "/ds-handoff [screens-or-feature]"
+- "Handoff a Claude Design" / "prompt per Claude Design" / "brief field-level"
+
+### design-sync
+
+**When to use**:
+
+- Mirror the in-repo registry (SSOT) UP to its Claude Design satellite (the code→design half of the closed loop)
+- `publish` / `bootstrap` / `drift` modes; delegates every write to the DesignSync MCP; refuse-on-divergence
+- Claude-only; interactive-auth (`/design-login`); no-op without a bound satellite
+
+**Triggers**:
+
+- "/design-sync"
+- "Pubblica il design system" / "mirror su Claude Design" / "il designer ha cambiato qualcosa"
+
+## Testing & Review Skills
+
+### e2e-review
+
+**When to use**:
+
+- Deterministic BLOCKING end-to-end review after a feature is implemented
+- Functional E2E (Playwright) + visual fidelity diff + design-quality critic, under a severity gate + bounded self-heal
+- Auto-called by `/new` Phase 2.6; invocable manually
+- Gated on `features.has_e2e_review`
+
+**Triggers**:
+
+- "/e2e-review CARD-ID"
+- "Verifica end-to-end" / "review schermate" / "controlla i mockup"
 
 ### playwright-skill
 
@@ -166,7 +343,7 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - Integration testing
 - Server management needed
 
-## Documentation Skills
+## Documentation & Knowledge Skills
 
 ### doc-writing-for-rag
 
@@ -180,6 +357,64 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "doc per RAG" / "dense documentation"
 - "template endpoint" / "compattare docs"
 
+### capture
+
+**When to use**:
+
+- Distill a cross-document synthesis of the recent conversation into a reusable wiki synthesis page
+- Implements Karpathy's query→wiki file-back loop
+- Gated on `features.has_wiki_overlay`
+
+**Triggers**:
+
+- "/capture"
+- "Salva sintesi" / "distilla conversazione" / "questa conversazione in wiki"
+
+### graph-align
+
+**When to use**:
+
+- On-demand documentation alignment via the Graphify code knowledge graph
+- Surface core code with no doc coverage, stale docs, drift vs the SSOT registry
+- The interactive twin of the nightly `doc-graph-align` routine
+- Gated on `features.has_code_graph`
+
+**Triggers**:
+
+- "/graph-align"
+- "Allinea la documentazione" / "check doc coverage"
+
+## Internationalization Skills
+
+> Gated on `features.has_i18n: true`.
+
+### i18n
+
+**When to use**:
+
+- Audit the i18n context registry against `t()` calls + native locale files (drift codes)
+- Context-aware translation of missing/stale labels via the `i18n-translator` agent
+- The interactive twin of the weekly `i18n-align` routine
+
+**Triggers**:
+
+- "/i18n"
+- "Traduci le label" / "audit i18n" / "allinea le traduzioni"
+
+### i18n-adopt
+
+**When to use**:
+
+- One-shot migration that externalizes ALL hardcoded user-facing strings on an existing codebase (the i18n analogue of `/design-system-init`)
+- Full-auto on a dedicated branch, idempotent + resumable; never auto-merges
+
+**Triggers**:
+
+- "/i18n-adopt"
+- "Migra a i18n" / "adotta i18n" / "externalize all strings"
+
+## Product & Content Skills
+
 ### copywriting
 
 **When to use**:
@@ -193,6 +428,152 @@ Map Claude Code skills to project domains and provide guidance on when to use ea
 - "Migliora il testo"
 - Landing/marketing content
 
+### seo-audit
+
+**When to use**:
+
+- Audit / diagnose technical + on-page SEO issues on a site
+
+**Triggers**:
+
+- "/seo-audit"
+- "SEO audit" / "why am I not ranking" / "meta tags review"
+
+### api-design-principles
+
+**When to use**:
+
+- Designing a new API, reviewing an API spec, establishing API design standards (REST / GraphQL)
+
+**Triggers**:
+
+- "/api-design-principles"
+- "Design this API" / "review API spec"
+
+## Integration Skills
+
+### kie-ai
+
+**When to use**:
+
+- Generate images / videos / audio via Kie.ai (80+ models), upscaling, background removal, TTS/SFX
+
+**Triggers**:
+
+- "/kie" / "/generate-image" / "/generate-video"
+- "Genera immagine / video", model names ("nano banana", "veo", "kling", "suno"…)
+
+### remotion-best-practices
+
+**When to use**:
+
+- Building video in React with Remotion (best practices guidance)
+
+**Triggers**:
+
+- "Remotion" / "video in React"
+
+## Retrieval & Toolchain Bootstrap Skills
+
+> Install/verify opt-in layers. Each is gated on its `features.*` flag and is
+> idempotent (re-running re-verifies + reports drift).
+
+### lsp-bootstrap
+
+**When to use**:
+
+- Install + verify the LSP symbol-search layer (language servers, `lsp.installed_servers`)
+- After enabling `features.has_lsp_layer`
+
+**Triggers**:
+
+- "/lsp-bootstrap"
+- "Install LSP" / "set up symbol search"
+
+### graphify-bootstrap
+
+**When to use**:
+
+- Install + verify + wire the Graphify code-knowledge-graph layer (CLI, offline graph build, auto-rebuild hook, MCP)
+- After enabling `features.has_code_graph`
+
+**Triggers**:
+
+- "/graphify-bootstrap"
+- "Install graphify" / "set up the code graph"
+
+### toolchain-bootstrap
+
+**When to use**:
+
+- Install + verify + wire the curated dev toolchain (Biome / Vitest / tsc / Lefthook) as devDeps
+- After enabling `features.has_toolchain`
+
+**Triggers**:
+
+- "/toolchain-bootstrap"
+- "Install the toolchain" / "set up biome"
+
+## Framework Maintenance & Meta Skills
+
+### baldart-update
+
+**When to use**:
+
+- Bring the BALDART framework up-to-date in a consumer repo (seamless `npx baldart update --yes`)
+- The skill narrates the CLI; it never re-implements it
+
+**Triggers**:
+
+- "/baldart-update"
+- "Aggiorna baldart" / "update del framework"
+
+### baldart-push
+
+**When to use**:
+
+- Contribute local framework improvements upstream to the BALDART repo
+- Hands off to `npx baldart push` (interactive); never pushes project-specific customizations
+
+**Triggers**:
+
+- "/baldart-push"
+- "Contribuisci al framework" / "push del framework"
+
+### overlay
+
+**When to use**:
+
+- Author `.baldart/overlays/` — the per-project customisation layer for skills / agents / commands
+- Scaffolds + validates + surfaces drift via the CLI; often the answer when the `framework-edit-gate` hook blocked a direct edit
+
+**Triggers**:
+
+- "/overlay"
+- "Customizza skill" / "override agent" / "personalizza comando"
+
+### skill-creator
+
+**When to use**:
+
+- Create a new skill, or modify/optimize/measure an existing one
+
+**Triggers**:
+
+- "/skill-creator"
+- "Crea una skill" / "improve this skill"
+
+### find-skills
+
+**When to use**:
+
+- Discover/install agent skills when a needed capability might already exist as a skill
+
+**Triggers**:
+
+- "/find-skills"
+- "Is there a skill that…" / "how do I do X"
+
 ## Project-Specific Skills
 
 Add your project-specific skills here:
@@ -214,7 +595,8 @@ START: User gives a task
   |
   v
 Is it a new feature needing scope/plan?
-  |-- YES --> /prd (scopes + plans + writes cards)
+  |-- YES --> /prd (scopes + plans + writes cards; UI phase delegates the
+  |           Claude Design prompt to /ds-handoff)
   |           Then /new (implements the cards end-to-end)
   |
   v
@@ -223,11 +605,22 @@ Is it a bug fix?
   |
   v
 Is it UI/visual work?
-  |-- YES --> /ui-design (mockups/options) or frontend-design
+  |-- YES --> /ui-design (mockups/options) or frontend-design;
+  |           motion → /motion-design
   |
   v
-Is it browser testing?
-  |-- YES --> playwright-skill or webapp-testing (E2E via /e2e-review)
+Is it design-system work (a component / token / handoff)?
+  |-- YES --> /ds-new (create) · /ds-edit (change) · /ds-render (isolate) ·
+  |           /ds-handoff (Claude Design prompt) · /design-sync (mirror)
+  |           (bootstrap the registry first with /design-system-init)
+  |
+  v
+Is it internationalization?
+  |-- YES --> /i18n (audit + translate) or /i18n-adopt (one-shot migration)
+  |
+  v
+Is it browser/E2E testing or review?
+  |-- YES --> playwright-skill / webapp-testing / /e2e-review (blocking)
   |
   v
 Is it cleanup/complexity reduction?
@@ -250,7 +643,15 @@ Common skill chains (all skills below are shipped under `.claude/skills/`):
 3. **UI Feature**:
    - /prd → /ui-design → /new → playwright-skill (or /e2e-review for blocking E2E)
 
-4. **Refactoring**:
+4. **UI Feature via Claude Design handoff**:
+   - /prd (Branch B) → /ds-handoff (field-level prompt) → [design in Claude Design]
+     → /prd re-entry (mockup intake) → /new → /e2e-review
+
+5. **Design System**:
+   - /design-system-init (bootstrap) → /ds-new / /ds-edit (evolve) → /ds-render
+     (verify isolated) → /design-sync (mirror to the satellite)
+
+6. **Refactoring**:
    - /simplify (identify + apply cleanups) → /new gates re-run lint/tsc/tests
 
 ## Anti-Patterns
@@ -263,6 +664,7 @@ Common skill chains (all skills below are shipped under `.claude/skills/`):
 - Claim completion before the `/new` review + gate cycle passes
 - Use wrong skill for the task
 - Route to a skill name that has no directory under `.claude/skills/`
+- Route to a feature-gated skill when its `features.*` flag is `false`
 
 **Do**:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.78.1",
+  "version": "4.79.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"