baldart 3.16.0 → 3.17.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.17.0] - 2026-05-23
+
+The `/prd` skill gains a third option in the design phase. Until v3.16.0, when a user reached Step 3 without having provided mockups (`mockups.status: none`), the only path forward was internal generation via the `ui-design` skill (3 HTML options → iteration → save). With Claude Design now offering a design-system-sync'd visual generator, users who prefer iterating in that surface had to abandon the PRD flow halfway, work externally, and then re-enter as if they'd had mockups from the start. This release adds **Step 3.0 — Mockup Source Decision**: when `mockups.status: none` AND UI impact ≠ N/A, the skill explicitly asks "internal generation or handoff to Claude Design?". The handoff branch generates a context-rich prompt (discovery + brand voice + design-system tokens + screens in scope + stack target) ready to paste, then STOPs. On user re-entry with local paths, it re-uses the existing Step 1.6 Mockup Intake verbatim — copy → analyze → populate state — and Step 3 falls naturally into Hybrid mode. Zero code paths downstream of the bivio are new; the entire feature is a decision point + a prompt generator on top of pre-existing infrastructure.
+
+### Added — PRD Step 3.0 Mockup Source Decision
+
+- **§ Step 3.0 in [framework/.claude/skills/prd/references/ui-design-phase.md](framework/.claude/skills/prd/references/ui-design-phase.md)** before the precondition decision tree. Activates only when `mockups.status: none` AND UI impact ≠ N/A. Poses the binary question (Internal `ui-design` vs Handoff Claude Design) with explicit STOP gate — silence or ambiguity re-asks rather than defaulting silently. Branch A sets `mockups.source: internal` and falls through unchanged. Branch B collects context from state file + `baldart.config.yml` + `.baldart/overlays/prd.md` + `${paths.design_system}/INDEX.md` + `tokens-reference.md` (when `features.has_design_system: true`), renders the handoff prompt template, presents it inside a fenced code-block with copy-paste instructions, persists `mockups.status: pending_external` + `mockups.source: claude-design` + `mockups.handoff_prompt_path` in the state file (prompt saved to `${paths.prd_dir}/<slug>/handoff/claude-design-prompt.md` for session-restart survival), and STOPs.
+- **Re-entry handler in same file**. When the user returns with local paths after handoff, the skill invokes the existing Step 1.6 Mockup Intake procedure verbatim (no code duplication) — copy into `mockups/` with collision-safe rename, run Mockup analysis schema, populate `## UI Design`. Then flips `mockups.status` from `pending_external` to `provided` or `partial` based on coverage of `screens_in_scope[]`, keeps `mockups.source: claude-design` as audit trail, and falls through to the precondition decision tree which routes to Hybrid mode unchanged.
+- **Precondition decision tree extended** with two new rows: `mockups.status: pending_external` ⇒ STOP (handoff in flight); `mockups.status: none` AND user picked Branch A ⇒ Full (preserves backwards-compatible default). The existing `provided` / `partial` ⇒ Hybrid and UI = N/A ⇒ Skip rows are unchanged.
+- **New template asset [framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md](framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md)**. Seven-section structure populated at runtime: (1) feature objective, (2) user flow + personas, (3) screens in scope with required states + primary actions + data shown, (4) brand & voice (conditional on overlay), (5) design system constraints with tokens excerpt + registered primitives + numeric tables from `framework/agents/design-system-protocol.md` (conditional on `features.has_design_system: true`), (6) stack target + output format preference derived from `stack.framework`, (7) deliverable spec (PNG exports per state + code/Figma + inline notes on new components / token deviations / layout decisions). Generic and project-agnostic — all project-specific content is injected as placeholders.
+- **Hard Rule 16 note in [framework/.claude/skills/prd/SKILL.md](framework/.claude/skills/prd/SKILL.md)** added to the existing Mockup Intake rule. Codifies that a NO answer at intake routes through Step 3.0 (not directly to Full mode), with cross-reference to the ui-design-phase section. The rule itself remains unchanged for backwards compatibility — Step 3.0 is purely additive.
+
+### Notes
+
+- **No new `baldart.config.yml` keys** — the schema-change propagation rule does not apply to this release. The bivio is runtime-only per the user's preference (zero persistent flag); no template/configure/update/doctor updates needed. All context for the handoff prompt is read from existing config keys (`paths.*`, `stack.*`, `features.has_design_system`).
+- **Backwards compatibility.** PRDs in flight on v3.16.x finish on v3.16.x semantics. New PRD sessions started on v3.17.0+ see Step 3.0 only when they actually reach Step 3 with `mockups.status: none` — the default (Branch A) preserves the v3.16.x behavior exactly. Existing PRDs that already provided mockups never enter Step 3.0.
+- **`ui-design` skill is unchanged** — Step 3.0 sits in front of it, doesn't modify it. The Full pipeline (3a → 3d) is reached identically when the user picks Branch A or when no mockup-related state exists at all. The `ui-expert` agent and `huashu-design`/`frontend-design` skills are equally untouched.
+- **`mockup_analysis` schema is unchanged** — the new `pending_external` value of `mockups.status` is purely transitional and is overwritten by `provided` / `partial` on user re-entry, so existing PRD templates and state files keep validating without migration.
+- **Files modified outside the Step 3.0 scope** (`card-template.yml`, `backlog-phase.md`, `validation-phase.md`, `prd-card-writer.md`, `framework/.claude/skills/new/SKILL.md`) are the v3.16.0 in-flight release (agent routing + UI specialist briefing — see entry below) and are NOT part of v3.17.0. v3.16.0 should be tagged and pushed before v3.17.0 in the release sequence.
+- **Verification is manual** (no test suite). Dogfood scenarios: (1) `/prd` with mockups provided at intake → never enters Step 3.0, Hybrid mode as today (regression check); (2) `/prd` without mockups, answer "A" at Step 3.0 → Full mode runs identically to v3.16.x; (3) `/prd` without mockups, answer "B" → prompt rendered with discovery + tokens + screens + stack, saved to `handoff/`, state shows `pending_external`, skill STOPs; (4) simulate re-entry with a PNG path → file copied to `mockups/`, status flips to `provided`, Step 3 enters Hybrid mode invoking `ui-design` only for uncovered screens; (5) `features.has_design_system: false` → § 5 of the rendered prompt is omitted entirely; (6) no overlay present → § 4 brand voice omitted.
+
 ## [3.16.0] - 2026-05-23
 
 The `/new` orchestrator becomes specialist-aware: it now reads `owner_agent` from each card YAML and dispatches the right implementation agent — `coder` for backend/logic, `ui-expert` for UI cards, with `plan`/`visual-designer`/`motion-expert` reserved as stubs that fall back to `coder` with a WARN. UI cards (`owner_agent: ui-expert`) receive a dedicated mission briefing that enforces the registry-first BLOCKING cascade (read `${paths.design_system}/INDEX.md` + `tokens-reference.md` + per-component specs BEFORE coding), the implementation-only constraint (no mockup redesign — STOP and ask on registry conflicts), and the Post-Intervention Coherence Check (reconcile INDEX + components + tokens in the same commit). The PRD side enforces the contract end-to-end: `owner_agent` is now a mandatory enum on every child card, UI cards have UI-only scope (logic moves to a sibling `coder` card), and the validation phase blocks commit on enum violations + warns on mixed-scope UI cards.

package/VERSION

@@ -1 +1 @@
-3.16.0
+3.17.0

package/framework/.claude/skills/prd/SKILL.md

@@ -101,6 +101,13 @@ message. You ask questions, wait for answers, and iterate.
     (`mockup_analysis.screens[].gaps[]`) DEVONO diventare domande mirate in Discovery o
     essere esplicitamente waivate.
 
+    **Nota — handoff esterno post-intake.** Se l'utente risponde NO al mockup intake, lo
+    Step 3.0 in UI Design gli chiederà se vuole generare i mockup internamente (workflow
+    `ui-design`) o fare handoff a **Claude Design**. Nel ramo handoff la skill genera un
+    prompt context-rich pronto da incollare, fa STOP, e al rientro con i path locali
+    riusa esattamente questa stessa procedura di Step 1.6 → Step 3 entra in Hybrid mode.
+    Vedi [ui-design-phase.md](references/ui-design-phase.md) § "Step 3.0 — Mockup Source Decision".
+
 ---
 
 ## TEMPLATES

package/framework/.claude/skills/prd/assets/claude-design-handoff-prompt.template.md

@@ -0,0 +1,116 @@
+# Claude Design Handoff Prompt — Template
+
+> Template populated at runtime by **Step 3.0 (Mockup Source Decision)** in
+> [../references/ui-design-phase.md](../references/ui-design-phase.md) when the
+> user picks the **handoff** branch. All `{{placeholders}}` are resolved from the
+> PRD state file (`${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`),
+> `baldart.config.yml`, and optional overlays.
+>
+> Render rules:
+> - Conditional sections (marked `{{#if …}} … {{/if}}`) are emitted only when the
+>   condition is true. Skip the entire section (including its heading) when false.
+> - Lists (marked `{{#each …}}`) render one bullet per item; emit "—" if empty.
+> - The rendered output is presented to the user inside a fenced markdown
+>   code-block so they can copy-paste verbatim into Claude Design.
+
+---
+
+# Feature: {{feature_title}}
+
+## 1. Obiettivo
+
+{{feature_objective_one_sentence}}
+
+## 2. User flow
+
+{{user_flow_summary}}
+
+{{#if primary_personas}}
+**Personas target**:
+{{#each primary_personas}}
+- {{this.name}} — {{this.context}}
+{{/each}}
+{{/if}}
+
+## 3. Schermate in scope
+
+{{#each screens_in_scope}}
+### {{this.name}}
+
+- **Scopo**: {{this.purpose}}
+- **Stati richiesti**: {{this.states_required}}  <!-- empty, loading, populated, error, success, ecc. -->
+- **Azioni primarie**: {{this.primary_actions}}
+- **Dati visualizzati**: {{this.data_shown}}
+{{#if this.notes}}
+- **Note**: {{this.notes}}
+{{/if}}
+
+{{/each}}
+
+{{#if brand_voice}}
+## 4. Brand & voice
+
+- **Tono**: {{brand_voice.tone}}
+- **Personalità**: {{brand_voice.personality}}
+- **Do**: {{brand_voice.do}}
+- **Don't**: {{brand_voice.dont}}
+{{#if brand_voice.references}}
+- **Riferimenti visivi**: {{brand_voice.references}}
+{{/if}}
+{{/if}}
+
+{{#if has_design_system}}
+## 5. Design system constraints
+
+> Riusa SOLO i token e le primitive elencate. Se devi proporre qualcosa di nuovo,
+> segnalalo esplicitamente nella consegna così posso aggiornare il registro.
+
+### Token chiave
+
+```
+{{design_tokens_excerpt}}
+```
+
+### Primitive da riusare
+
+{{#each registered_primitives}}
+- **{{this.name}}** — {{this.purpose}} ({{this.path}})
+{{/each}}
+
+### Vincoli numerici (da `design-system-protocol.md`)
+
+- Type scale: {{tokens.type_scale}}
+- Spacing scale: {{tokens.spacing_scale}}
+- Radius: {{tokens.radius_scale}}
+- Contrast minimo: {{tokens.contrast_target}} (WCAG AA + APCA Lc ≥ {{tokens.apca_target}})
+- Motion durations: {{tokens.motion_durations}}
+{{/if}}
+
+## 6. Stack target
+
+- **Framework**: {{stack.framework}}
+- **Output preferito**: {{output_format_preference}}  <!-- "HTML/CSS standalone" | "React component (Tailwind)" | "Figma frame" -->
+{{#if stack.charting}}
+- **Charting library**: {{stack.charting}}
+{{/if}}
+{{#if stack.animation}}
+- **Animation library**: {{stack.animation}}
+{{/if}}
+
+## 7. Cosa restituirmi
+
+Per ogni schermata elencata in § 3:
+
+1. **PNG export** ad alta risoluzione (≥ 2x) di OGNI stato richiesto (es. `lista-ordini__empty.png`, `lista-ordini__populated.png`).
+2. {{output_format_preference_block}}  <!-- "Codice HTML/CSS in un file unico" | "Codice React (.tsx) con import Tailwind" | "Link Figma alla frame" -->
+3. **Note inline** su:
+   - Componenti nuovi (non presenti nel registry sopra) che hai introdotto e perché.
+   - Token deviation: qualunque colore/spacing/radius fuori dalla palette sopra, con motivazione.
+   - Decisioni di layout non ovvie (es. priority sort, hierarchy visiva, density).
+
+Quando hai pronto, dimmi i **path locali** dei file (PNG/HTML/TSX) — li importerò in questa sessione PRD per analisi e validazione contro il design system.
+
+---
+
+<!-- baldart-handoff: do-not-edit-manually -->
+<!-- Generated from claude-design-handoff-prompt.template.md by /prd Step 3.0 -->

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

@@ -1,15 +1,97 @@
 # UI Design Phase (Step 3)
 
+## Step 3.0 — Mockup Source Decision (only when `mockups.status: none`)
+
+When the state file shows `mockups.status: none` AND UI impact ≠ N/A, the user
+has not provided any mockup at intake. Before falling into the **Full** pipeline,
+offer them an explicit choice — generate internally or hand off to **Claude
+Design** (Anthropic's design product, design-system-sync'd) — so they don't have
+to abandon the PRD flow halfway.
+
+Skip this step entirely when `mockups.status` ∈ {`provided`, `partial`,
+`pending_external`} (already decided) or when UI impact = N/A (no design work).
+
+### The question (single STOP)
+
+Ask the user, verbatim:
+
+> Non hai fornito mockup all'intake. Come preferisci produrli per questa feature?
+> **(A) Internamente** — genero io 3 opzioni HTML (workflow `ui-design`), iteriamo qui.
+> **(B) Handoff a Claude Design** — ti preparo un prompt context-rich da incollare in Claude Design; quando hai i mockup tornami con i path locali.
+
+**STOP.** Wait for an explicit `A` / `B` answer. Silence or ambiguity ⇒ ask
+again (do NOT default silently).
+
+### Branch A — Internal generation
+
+Set `mockups.source: internal` in the state file, then fall through to the
+**Precondition decision tree** below — the `none` row routes to Full mode
+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):
+
+   > 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:
+   - `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).
+   - `step_3_mode: pending_external_handoff` (transitional — overwritten when user returns).
+
+5. **STOP.** Wait for the user to return with local paths.
+
+### Re-entry from handoff (user returns with paths)
+
+When the user comes back with one or more local paths after the handoff:
+
+1. Invoke **Step 1.6 — Mockup Intake** verbatim
+   ([SKILL.md](../SKILL.md) § Hard Rule 16,
+   [discovery-phase.md](discovery-phase.md) § "Mockup analysis schema"):
+   - Copy local files into `${paths.prd_dir}/<slug>/mockups/` with collision-safe
+     rename.
+   - Run the full Mockup analysis schema (screens, user_flow, components,
+     states_visible, copy_excerpts, gaps, design_system_alignment).
+   - Populate `## UI Design` in the state file.
+2. Flip `mockups.status` from `pending_external` to `provided` or `partial`
+   based on coverage of `screens_in_scope[]`. Keep `mockups.source: claude-design`
+   as audit trail.
+3. Fall through to the **Precondition decision tree** below — the `provided` /
+   `partial` row routes to **Hybrid mode** unchanged.
+
+---
+
 ## Precondition decision tree
 
 Read `mockups.status` and `screens_in_scope[]` from the state file `## UI Design`
-section (populated by Step 1.6) plus the UI impact dimension from the discovery
-checklist. Pick exactly one branch:
+section (populated by Step 1.6 and/or Step 3.0 re-entry) plus the UI impact
+dimension from the discovery checklist. Pick exactly one branch:
 
 | Condition | Branch | Action |
 |-----------|--------|--------|
 | UI impact = N/A | **Skip totale** | Mark task 2 `completed` ("Skipped — no UI"). `step_3_mode: skipped`. Proceed to PRD Writing Phase. |
-| `mockups.status: none` AND UI impact ≠ N/A | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
+| `mockups.status: none` AND UI impact ≠ N/A | **3.0 Decision** | Run Step 3.0 above first. Branch A ⇒ fall through to **Full**; Branch B ⇒ STOP, then re-enter. |
+| `mockups.status: pending_external` | **STOP** | User is in handoff with Claude Design. Do not advance until paths arrive (see § "Re-entry from handoff"). |
+| `mockups.status: none` AND user picked Branch A in Step 3.0 | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
 | `mockups.status` ∈ {`provided`, `partial`} AND UI impact ≠ N/A | **Hybrid** | Per-screen routing (see § Hybrid mode below). `step_3_mode: hybrid` (or `skipped` if every screen is covered AND no `mockup_analysis.design_system_alignment.violations`). |
 
 Mark task 2 as `in_progress` for the Full and Hybrid branches.

package/package.json

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