baldart 3.6.2

package/framework/.claude/skills/playwright-skill/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: playwright-skill
+description: E2E browser testing with Playwright Test CLI. Write .spec.ts files in tests/e2e/, run via `npm run test:e2e`. Supports headed mode, debug, UI mode, filtering, retries, screenshots, and trace on failure. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing.
+---
+
+# Playwright E2E Testing (CLI)
+
+All browser testing uses the **Playwright Test CLI** via `playwright.config.ts` at project root. Tests live in `${paths.e2e_tests_dir}` (default convention `tests/e2e/`).
+
+**NEVER use ad-hoc scripts to `/tmp` as a substitute.** All tests MUST be `.spec.ts` files under `${paths.e2e_tests_dir}/`.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.e2e_tests_dir`, `paths.design_system`, `stack.testing.e2e`.
+**Gated by features:** `features.has_design_system` (Design System Compliance section becomes BLOCKING when `true`), `features.multi_tenant_theming` (theming assertion rule activates when `true`).
+**Refuses to run when** `stack.testing.e2e` is set to something other than `"playwright"` or empty (warn and ask). Empty = ask user once and persist.
+**Overlay:** loads `.baldart/overlays/playwright-skill.md` if present — project-specific test URLs, auth helpers, theming pairing assertions.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Run all e2e tests | `npm run test:e2e` |
+| Run headed (visible browser) | `npm run test:e2e:headed` |
+| Run with UI mode | `npm run test:e2e:ui` |
+| Debug with Inspector | `npm run test:e2e:debug` |
+| Run single file | `npx playwright test tests/e2e/my-test.spec.ts` |
+| Run by title regex | `npx playwright test -g "login flow"` |
+| Run specific project | `npx playwright test --project=chromium` |
+| Show HTML report | `npm run test:e2e:report` |
+| Update snapshots | `npx playwright test -u` |
+
+## Writing Tests
+
+Tests go in `tests/e2e/*.spec.ts` using `@playwright/test` API:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('homepage loads correctly', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveTitle(/Fidelity/);
+  await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
+});
+
+test('login redirects to dashboard', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('input[name="email"]', 'test@example.com');
+  await page.fill('input[name="password"]', 'password123');
+  await page.click('button[type="submit"]');
+  await expect(page).toHaveURL(/dashboard/);
+});
+```
+
+### Key differences from the old approach
+
+| Old (run.js) | New (Playwright CLI) |
+|-------------|---------------------|
+| `const { chromium } = require('playwright')` | `import { test, expect } from '@playwright/test'` |
+| `chromium.launch({ headless: false })` | Configured in `playwright.config.ts`, use `--headed` flag |
+| `browser.newPage()` | `page` fixture injected automatically |
+| `browser.close()` | Automatic cleanup via fixtures |
+| `console.log('passed')` | `expect(locator).toBeVisible()` with auto-waiting |
+| Write to `/tmp/*.js` | Write to `tests/e2e/*.spec.ts` |
+| `cd $SKILL_DIR && node run.js` | `npx playwright test` |
+
+### Responsive testing with projects
+
+The config defines `chromium` (desktop) and `mobile` (iPhone 14) projects. Run both:
+
+```bash
+npx playwright test --project=chromium --project=mobile
+```
+
+Or just mobile:
+
+```bash
+npx playwright test --project=mobile
+```
+
+### Grouping with describe
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Booking flow', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/<project-specific-test-route>'); // see .baldart/overlays/playwright-skill.md for project routes
+  });
+
+  test('shows date picker on load', async ({ page }) => {
+    await expect(page.getByTestId('date-picker')).toBeVisible();
+  });
+
+  test('advances to time slot step', async ({ page }) => {
+    await page.getByTestId('date-picker').click();
+    await page.getByText('18').click();
+    await page.getByTestId('next-button').click();
+    await expect(page.getByTestId('time-slots')).toBeVisible();
+  });
+});
+```
+
+## Configuration
+
+The `playwright.config.ts` at project root manages all settings:
+
+- **baseURL**: `http://localhost:3000` (from `BASE_URL` env var)
+- **webServer**: auto-starts `npm run dev` if not already running
+- **screenshot**: only on failure
+- **trace**: on first retry
+- **projects**: `chromium` (Desktop Chrome) + `mobile` (iPhone 14)
+- **retries**: 0 locally, 2 on CI
+- **headed**: visible locally, headless on CI
+
+## Debugging
+
+```bash
+# Open Playwright Inspector (step-through, element picker)
+npm run test:e2e:debug
+
+# Interactive UI mode (run/rerun tests, time-travel, DOM inspector)
+npm run test:e2e:ui
+
+# Run headed with slowMo for visual debugging
+npx playwright test --headed -- --slow-mo=500
+```
+
+## CI Integration
+
+On CI, tests run headless with retries and produce HTML + JSON reports:
+
+```bash
+CI=true npm run test:e2e
+```
+
+Trace files and screenshots from failures are saved in `test-results/`.
+
+## Tips
+
+- Use `data-testid` attributes for reliable selectors
+- Prefer `page.getByRole()`, `page.getByText()`, `page.getByTestId()` over CSS selectors
+- Use `expect(locator)` assertions — they auto-wait (no manual `waitForSelector`)
+- Use `test.describe()` to group related tests with shared `beforeEach`
+- Use `test.skip()` or `test.fixme()` for tests that aren't ready
+- Use `--only-changed` to run only tests affected by git changes
+
+## Design System Compliance (UI validation)
+
+When `features.has_design_system: true`, E2E tests that validate UI components MUST be grounded in the Design System SSOT so that assertions reflect canonical variants and states, not ad-hoc expectations:
+
+1. Before writing a spec that asserts visual/component behavior, read `${paths.design_system}/INDEX.md` and the relevant `${paths.design_system}/components/<Name>.md` to confirm variants, states, and required props.
+2. Assert against documented variants: e.g., `expect(button).toHaveAttribute('data-variant', 'primary')` rather than matching a specific color literal.
+3. When `features.multi_tenant_theming: true`: validate token-pair presence per the project's theming pattern doc (bg class + matching text class). The exact assertion helper is listed in `.baldart/overlays/playwright-skill.md`.
+4. Motion-sensitive flows MUST include a reduced-motion run (`test.use({ reducedMotion: 'reduce' })`) per the project's motion pattern doc — reduced-motion variants are mandatory, and tests must prove they exist.
+5. Skipping this step when the spec validates UI is a protocol violation.

package/framework/.claude/skills/playwright-skill/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "playwright-skill",
+  "version": "4.1.0",
+  "description": "General-purpose browser automation with Playwright for Claude Code with auto-detection and smart test management",
+  "author": "lackeyjb",
+  "main": "run.js",
+  "scripts": {
+    "setup": "npm install && npx playwright install chromium",
+    "install-all-browsers": "npx playwright install chromium firefox webkit"
+  },
+  "keywords": [
+    "playwright",
+    "automation",
+    "browser-testing",
+    "web-automation",
+    "claude-skill",
+    "general-purpose"
+  ],
+  "dependencies": {
+    "playwright": "^1.57.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "license": "MIT"
+}

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

@@ -0,0 +1,228 @@
+---
+name: prd
+description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
+---
+
+# /prd — Structured PRD Skill
+
+Turn a feature idea into implementation-ready artifacts: PRD, UI design, and backlog
+cards. Anti-drift by design — rigid step sequence, persistent state, visible progress.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.prd_dir`, `paths.backlog_dir`, `paths.references_dir`, `paths.design_system`, `paths.ui_guidelines`, `identity.audience_segments`, `identity.language`.
+**Gated by features:** `features.has_prd_workflow` (skill REFUSES to run when `false`), `features.has_backlog` (Step 5 BLOCKING when `true`), `features.has_design_system` (Step 3 BLOCKING reads), `features.has_adrs` (architectural decisions get logged as ADRs in `paths.adrs_dir`).
+**Overlay:** loads `.baldart/overlays/prd.md` if present — project-specific terminology, card layout overrides, segment names, mandated review gates.
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+---
+
+## EXECUTION MODEL
+
+This skill is a **multi-turn conversation**. You do NOT produce all artifacts in one
+message. You ask questions, wait for answers, and iterate.
+
+**Flow overview:**
+
+| Step | Phase | Reference |
+|------|-------|-----------|
+| 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
+| 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
+| 2 | Discovery Question Loop | [discovery-phase.md](references/discovery-phase.md) |
+| 2→CR | Change Request (auto/manual) | [prd-add-phase.md](references/prd-add-phase.md) |
+| 2.5 | Research (opzionale) | [research-phase.md](references/research-phase.md) |
+| 3 | UI Design (3a-3d) | [ui-design-phase.md](references/ui-design-phase.md) |
+| 4 | Write PRD | [prd-writing-phase.md](references/prd-writing-phase.md) |
+| 4.5 | API Performance Gate | [api-perf-gate.md](references/api-perf-gate.md) |
+| 4b | Confirm Specs | [prd-writing-phase.md](references/prd-writing-phase.md) |
+| 5 | Backlog Cards | [backlog-phase.md](references/backlog-phase.md) |
+| 6 | Quality Audit | [validation-phase.md](references/validation-phase.md) |
+| 7 | Resolution & Commit | [validation-phase.md](references/validation-phase.md) |
+
+**Before starting each phase, read the corresponding reference file.**
+
+---
+
+## HARD RULES
+
+1. Follow steps in order. NEVER skip a step or jump ahead.
+2. Every step MUST update the state file before proceeding.
+3. Every gate MUST be satisfied before moving to the next step.
+4. Use TaskCreate/TaskUpdate for ALL progress tracking.
+5. When context is compressed or session resumes: run Step 0 first.
+6. **ONE question per message during discovery. Never batch questions.**
+7. No code generation. This skill produces planning artifacts only.
+8. Use exact terminology from `agents/coding-standards.md` and the project's terminology section in `.baldart/overlays/prd.md` (audience segments come from `identity.audience_segments`; domain entities are listed in the overlay).
+9. Update `${paths.references_dir}/project-status.md` Active Code Context at session start and at commit (AGENTS.md MUST). Skip when the file does not exist in the project.
+10. **STOP means STOP.** When you see `STOP`, end your message. Do not make more tool
+    calls. Do not continue to the next step. Wait for the user.
+11. **Every message MUST end with the Progress Bar.** No exceptions.
+12. **Scope Expansion Detection.** During discovery (Step 2), after every user answer,
+    check if the response introduces NEW structural entities (endpoints, collections,
+    pages, roles, flows) not in the original feature description. If detected, pause
+    and offer to run `/prd-add` for impact analysis. See discovery-phase.md for protocol.
+13. **`canonical_docs` completeness.** Every card generated from a PRD MUST have
+    `canonical_docs.ssot_registry_entry` populated (exact row name from the project's SSOT registry — typically `${paths.references_dir}/ssot-registry.md` if it exists; skip when absent). Cards with `data_fields` MUST also have `canonical_docs.data_model_refs` populated with the matching `${paths.references_dir}/collections/*.md` paths (or the project's data-model docs as defined in the overlay). The `prd-card-writer` agent enforces this during Step 5. Missing `canonical_docs` = card is not DONE.
+14. **Design System SSOT alignment (UI PRDs).** During UI Design phase (Step 3), when `features.has_design_system: true`, you MUST read `${paths.design_system}/INDEX.md` (component index + authority matrix + Quick rules MUST) before generating mockups or component specs. For each UI surface in the PRD, identify the relevant component docs under `${paths.design_system}/components/<Name>.md` and cite them in PRD Section "Canonical Sources". New UI pages/components described in the PRD MUST reuse existing components when available and MUST NOT propose hardcoded hex / shadow / border values when a token contract exists. Multi-tenant theming surfaces (when `features.multi_tenant_theming: true`) MUST reference the project's theming pattern doc; motion specs MUST reference the project's motion pattern doc. Both are listed in `.baldart/overlays/prd.md`.
+15. **Backlog structure: epic + children (MANDATORY — zero tolerance).** Every PRD that
+    produces backlog cards MUST organize them as **1 epic + N children**, regardless of N:
+    - **Epic**: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml`. Tracker only — no implementation
+      work. Contains AC-EPIC list, Definition of Done, business_rationale, scope,
+      scope_boundaries, `execution_strategy` (with parallel_groups computed from the
+      dependency graph), and `documentation_impact` map with `owner_card` per doc.
+      `group.parent` = the PRD slug string (NOT a FEAT-ID). `group.sequence: 0`.
+      `parallel_group: 0`. `depends_on: []`, `blocks: []`.
+    - **Children**: `${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M. Each has
+      `group.parent: FEAT-XXXX-00` (the epic's actual ID), `group.sequence: N`,
+      and `depends_on` / `blocks` referencing sibling child IDs.
+
+    **FORBIDDEN PATTERNS** — the `prd-card-writer` agent MUST refuse and the skill
+    MUST halt:
+    - Flat cards `FEAT-XXXX-<slug>.yml` (no `-NN-` segment, no epic parent).
+    - `group.parent` set to a placeholder string like `TIPS-EPIC` instead of the
+      actual epic FEAT-XXXX-00 id.
+    - Skipping the epic when there is only one child card.
+    - Reusing the same `FEAT-XXXX` integer for unrelated work (each epic reserves
+      the full integer space).
+
+    **Canonical examples**: `FEAT-0875-00..08` (Survey Analytics Redesign),
+    `FEAT-0876-00..11` (Menu TIPS). See `assets/epic-template.yml` for the epic
+    structure and `assets/card-template.yml` for child structure.
+
+---
+
+## TEMPLATES
+
+Use these templates when creating artifacts:
+
+| Artifact | Template |
+|----------|----------|
+| Session state file | [assets/state-template.md](assets/state-template.md) |
+| PRD document | [assets/prd-template.md](assets/prd-template.md) |
+| Backlog epic (always 1) | [assets/epic-template.yml](assets/epic-template.yml) |
+| Backlog child card (N≥1) | [assets/card-template.yml](assets/card-template.yml) |
+
+**State file location:** `${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
+**PRD location:** `${paths.prd_dir}/<slug>/PRD.md`
+**Design location:** `${paths.prd_dir}/<slug>/design.html`
+**Cards location:**
+- Epic: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml` (mandatory when `features.has_backlog: true`)
+- Children: `${paths.backlog_dir}/FEAT-XXXX-NN-<sub-slug>.yml` for N=1..M (at least 1)
+
+---
+
+## PROGRESS BAR — MANDATORY ON EVERY MESSAGE
+
+At the END of every message (after all text, before stopping), display:
+
+```
+---
+📋 **Progresso PRD: <slug>**
+
+| # | Fase | Stato |
+|---|------|-------|
+| 1 | Discovery & comprensione | ⬜/🔄/✅ |
+| 1.5 | Ricerca best practice | ⬜/🔄/✅/⏭️ |
+| 2 | Design UI & approvazione | ⬜/🔄/✅/⏭️ |
+| 3 | Conferma specifiche | ⬜/🔄/✅ |
+| 4 | Creazione backlog cards | ⬜/🔄/✅ |
+| 5 | Validazione e commit | ⬜/🔄/✅ |
+
+Comprensione: X% (N/M dimensioni coperte) — ISA: N punti identificati
+Ricerca: ⬜ non valutata / 🔍 in corso (background) / ✅ completata / ⏭️ non necessaria
+Prossimo passo: <what happens next>
+```
+
+Legend: ⬜ = da fare, 🔄 = in corso, ✅ = completato, ⏭️ = saltato (N/A)
+
+**If your message doesn't end with this table, you violated the skill rules.**
+
+---
+
+## CONTEXT LOADING — Before Discovery (MANDATORY)
+
+Before entering the discovery loop, load codebase context using the **context-primer**
+(`/cont`) skill. This centralizes all codebase exploration in one place.
+
+1. Extract 2-4 keywords from the user's feature description.
+2. Invoke the `Skill` tool with `skill: "context-primer"` passing the keywords
+   (e.g., `args: "prize scanning scratch card wheel"`).
+3. The context-primer launches `codebase-architect` which searches RAG, docs,
+   backlog, source code, and git history — returning a compact summary.
+4. Additionally, use `search_docs` MCP tool (if available) with `mode: "hybrid"` for the feature domain
+   to surface related PRDs, ADRs, and specs not covered by context-primer. The
+   active retrieval layer is Obsidian-first LightRAG; use Obsidian hits for
+   concept and decision context, then verify implementation and stateful claims
+   against repo docs/code. If MCP is unavailable, fall back to targeted
+   canonical docs plus `rg` over `${paths.references_dir}/`, `${paths.backlog_dir}/`, and `.claude/agents/`.
+5. Check `${paths.references_dir}/traceability-matrix.md` for source-to-doc mappings (if the project maintains one — skip when absent).
+
+The loaded context lives in conversation history and informs ALL subsequent
+discovery dimensions — avoiding redundant per-dimension agent launches.
+
+## QUICK REFERENCE — COMPREHENSION DIMENSIONS
+
+The 11 dimensions to cover during discovery:
+
+0. **Business rationale** — why this feature, why now? (business motivation, market signal, expected impact, strategic alignment). Can be resolved from user's initial description or by explicit question (ALWAYS first in discovery loop).
+1. **Target users** — who uses this feature?
+2. **User journey** — how does the user flow work?
+3. **Data model impact** — new collections, fields, interfaces?
+4. **API impact** — new/modified endpoints?
+5. **UI impact** — new pages, components, layouts?
+6. **Permissions/roles** — access control changes?
+7. **Edge cases** — what can go wrong?
+8. **Rollout/migration** — feature flags, data migration, backwards compat?
+9. **Integration surface** — where in the existing system must reference/link to this feature?
+10. **Test strategy** — E2E needed? scenarios? credentials?
+
+Dimension 0 is resolved first: from user's initial description (auto) or explicit question.
+Dimensions 1-8 can be resolved by: context-primer context (auto), targeted codebase-architect (if needed), user answer, or N/A.
+Dimension 9 uses automated codebase scan + user validation (see discovery-phase.md).
+Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
+
+---
+
+## COMPLETED PROGRESS BAR (for final message)
+
+```
+---
+📋 **Progresso PRD: <slug>**
+
+| # | Fase | Stato |
+|---|------|-------|
+| 1 | Discovery & comprensione | ✅ |
+| 1.5 | Ricerca best practice | ✅/⏭️ |
+| 2 | Design UI & approvazione | ✅/⏭️ |
+| 3 | Conferma specifiche | ✅ |
+| 4 | Creazione backlog cards | ✅ |
+| 5 | Validazione e commit | ✅ |
+
+Comprensione: 100%
+Ricerca: ✅ completata / ⏭️ non necessaria
+**Pronto per l'implementazione.**
+```
+
+---
+
+## Metrics Log (MANDATORY — after Phase 5 Validazione)
+
+After cards are created and committed, log this PRD run to `docs/metrics/skill-runs.jsonl`.
+
+**Steps:**
+
+1. Count from the created backlog YAML files:
+   - `cards_created`: total cards created in this PRD run
+   - `ac_coverage_ratio`: total acceptance_criteria count / total user_stories count across all cards
+   - `isa_count`: number of ISA items identified (from the progress bar "ISA: N punti")
+   - `has_test_plan_pct`: % of cards that have a `test_plan` field (even if `e2e_required: false`)
+   - `has_firestore_indexes_pct`: % of cards that have a `firestore_indexes` field
+   - `discovery_iterations`: approximate number of Q&A rounds with the user (count AskUserQuestion calls in this session, default 1 if unknown)
+
+2. Write ONE JSON line (append) to `docs/metrics/skill-runs.jsonl`:
+
+   ```json
+   {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_firestore_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
+   ```
+
+**This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar.

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -0,0 +1,232 @@
+# =============================================================================
+# {{FEAT-ID}} — {{Short title}}
+# =============================================================================
+
+id: {{FEAT-ID}}
+title: "{{Full descriptive title}}"
+status: TODO
+priority: {{HIGH|MEDIUM|LOW}}
+owner_agent: claude
+execution_mode: local
+
+group:
+  parent: {{FEAT-EPIC-ID}}
+  sequence: {{N}}
+
+git_strategy:
+  branch: "feat/{{FEAT-EPIC-ID}}-{{slug}}"
+  base: "develop"
+  target: "develop"
+
+context: |
+  {{Background and motivation. Reference PRD sections.}}
+
+  PRD: docs/prd/{{slug}}/PRD.md ({{FR/NFR refs}})
+
+business_rationale: |
+  {{2-3 righe che spiegano PERCHÉ questa feature esiste: motivazione di business +
+  impatto atteso. Estratto dalla sezione "Ratio Strategica" del PRD (Section 1b).
+  Aiuta gli agenti implementatori a comprendere l'intento strategico.}}
+
+scope:
+  summary: |
+    {{What this card delivers in 2-3 lines.}}
+  users: [{{CUSTOMER|MERCHANT|SUPER_ADMIN}}]
+  value: {{Business value in one line.}}
+
+# --- Scope Boundaries (OPTIONAL — include when card is part of a multi-card epic) ---
+# Explicitly separates what THIS card delivers vs what sibling cards handle.
+# Omit for standalone cards with no siblings.
+scope_boundaries:
+  in_scope:
+    - "{{concise deliverable of THIS card}}"
+  out_of_scope:
+    - "{{what sibling card handles — reference card ID, e.g. 'UI dropdown (FEAT-XXXX-02)'}}"
+
+requirements:
+  - >
+    {{Concrete, specific requirement.}}
+
+# --- Existing Patterns (OPTIONAL — include when card modifies existing code) ---
+# File:line references to code the agent should replicate or extend.
+# "Clear patterns to replicate" is the #1 driver of agent implementation quality (Devin 2025).
+# Omit for greenfield cards where all files are NEW.
+existing_patterns:
+  - description: "{{what pattern to replicate or extend}}"
+    file: "{{src/path/to/file.ts}}"
+    line_range: "~{{start}}-{{end}}"
+    anchor_text: "{{short unique string from the code for fuzzy location matching}}"
+    note: "{{how to adapt the pattern for this card's needs}}"
+
+# --- Anti-Patterns (OPTIONAL — include when there are known pitfalls) ---
+# Explicit DO NOTs. Agents cannot reliably extract anti-patterns from prose.
+# Include both technical (e.g. deprecated APIs) and scope (e.g. don't touch sibling card's files).
+# Omit if no known anti-patterns apply.
+anti_patterns:
+  - "DO NOT {{specific prohibited action — be concrete, not generic}}"
+
+acceptance_criteria:
+  - "[ ] [AC-1] {{Testable criterion}}"
+
+# --- Validation Commands (OPTIONAL — include for cards with testable outputs) ---
+# Executable commands the agent runs for self-verification after implementation.
+# Turns acceptance criteria into an autonomous feedback loop (PRP framework).
+# Include static checks always; runtime checks only if e2e_required: true.
+# Omit only for documentation-only or configuration-only cards.
+validation_commands:
+  - cmd: "npx tsc --noEmit"
+    expect: "exit 0"
+  - cmd: "{{verification command, e.g. grep -c 'pattern' src/file.tsx}}"
+    expect: "{{expected: 'exit 0', '>= N', 'contains X', '== N'}}"
+    note: "{{what this verifies — maps to AC-N}}"
+
+definition_of_done:
+  - "TypeScript compiles (npx tsc --noEmit)"
+  - "Lint passes (npx eslint --max-warnings=0 on changed files)"
+  - "{{Additional DoD items}}"
+
+depends_on: [{{card IDs}}]
+blocks: [{{card IDs}}]
+
+estimated_complexity: {{LOW|MEDIUM|HIGH}}
+
+# Parallelization metadata (auto-computed by /prd backlog phase)
+parallel_group: {{N}}          # Layer di esecuzione: 0 = prima, 1 = dopo layer 0, etc.
+                               # Card nello stesso gruppo possono girare in parallelo
+
+files_likely_touched:
+  - {{path}} ({{NEW|MODIFY}})
+
+links:
+  prd: "docs/prd/{{slug}}/PRD.md"
+  design: "docs/prd/{{slug}}/design.html"  # REQUIRED for UI cards, omit for API-only cards
+
+# --- Canonical Docs (REQUIRED for cards generated from a PRD) ---
+# Traces which SSOT documents informed this card's requirements.
+# ssot_registry_entry: exact row name in ${paths.references_dir}/ssot-registry.md
+# data_model_refs: collection docs consulted — REQUIRED when data_fields is present
+# additional_refs: ADRs, specs, or other SSOT docs beyond the PRD (omit if none)
+canonical_docs:
+  ssot_registry_entry: "{{Exact feature name as it appears in ssot-registry.md}}"
+  data_model_refs:
+    - "${paths.references_dir}/collections/{{collection}}.md"
+  additional_refs:
+    - "{{${paths.adrs_dir}/ADR-XXXXX.md}}"
+
+test_plan:
+  e2e_required: {{true|false}}
+  e2e_rationale: "{{reason from evaluation tree}}"
+  test_scenarios:
+    - id: TS-1
+      description: "{{scenario}}"
+      maps_to: "US-{{N}} / AC-{{N}}"
+      priority: {{HIGH|MEDIUM}}
+  test_credentials:
+    persona: {{CUSTOMER|MERCHANT|SUPER_ADMIN}}
+    auth_method: "{{OTP|password}}"
+    credentials: "{{phone: 3486417303 | username/password}}"
+    store: "{{store name if merchant}}"
+    notes: "{{e.g., OTP inserito manualmente dall'utente}}"
+  test_data_prerequisites:
+    - "{{any Firestore data needed before tests}}"
+
+integration_points:
+  - id: ISA-{{N}}
+    category: "{{NAVIGATION|PERMISSIONS|SETTINGS|SEARCH|NOTIFICATIONS|DASHBOARD|API_CONSUMERS|SHARED_STATE}}"
+    target_file: "{{existing file to modify}}"
+    action: "{{what to do}}"
+    risk: "{{HIGH|MEDIUM|LOW}}"
+
+# --- Input/Output Examples (OPTIONAL — include for API or data transformation cards) ---
+# Concrete examples disambiguate specs. SWE-bench: 38% of issues are underspecified.
+# Omit for pure UI or documentation-only cards.
+input_output_examples:
+  - scenario: "{{scenario name}}"
+    input: "{{HTTP method + path + body, or function call with args}}"
+    output: "{{expected response body or return value}}"
+
+# --- Error Handling (OPTIONAL — include for cards with failure modes) ---
+# Structured failure mode specs. Prevents agents from inventing alternative error handling.
+# Omit for type-only or documentation-only cards.
+error_handling:
+  - trigger: "{{what goes wrong — e.g. network error, 404, invalid input}}"
+    action: "{{programmatic response — e.g. set state to [], retry 3x, throw}}"
+    user_feedback: "{{what the user sees, or 'none' for silent fallback}}"
+
+# --- Reuse Analysis (OPTIONAL — include for implementation cards) ---
+# Components/utilities to reuse vs create. Agent checks this BEFORE creating new components.
+# Supports both structured format (below) and legacy free-form text for backward compatibility.
+# Omit for documentation-only or configuration-only cards.
+reuse_analysis:
+  reuse:
+    - component: "{{ComponentName or utilityName}}"
+      from: "{{src/path/to/file.ts}}"
+      note: "{{how to use or extend it}}"
+  create:
+    - component: "{{NewComponentName}}"
+      reason: "{{why no existing component fits}}"
+
+# --- Data Sources (MANDATORY — compile for EVERY card; use [] only for pure docs/config cards) ---
+# High-level overview of every data source or destination touched by this card.
+# Rules:
+#   type: firestore → collection name in `path`; field-level detail goes in data_fields below.
+#   type: file      → repo-relative path, operations (READ|WRITE|APPEND|CREATE|DELETE), format.
+#   type: api       → URL or endpoint pattern; READ=GET, WRITE=POST/PUT/PATCH, DELETE=DELETE.
+#   type: env       → env var name; operations always [READ].
+#   []              → explicit empty list for cards that read/write NO data (docs, config stubs).
+#   NEVER omit this field silently — an empty [] signals the writer verified there are no sources.
+data_sources:
+  - type: "{{firestore|file|api|env}}"
+    path: "{{collection name | repo-relative file path | API endpoint | env var name}}"
+    operations: [{{READ|WRITE|APPEND|CREATE|DELETE}}]
+    # format: "{{JSONL|YAML|JSON|markdown|binary}}"  # include for file type only
+    # note: "{{optional: data shape, why this source}}"
+
+# --- Environment Variables (MANDATORY se la card introduce/modifica env vars — altrimenti []) ---
+# Lista di variabili d'ambiente create, modificate o rimosse da questa card.
+# Il coder usa questo campo per compilare l'entry in ${paths.references_dir}/env-vars.md.
+env_vars:
+  - name: "{{VAR_NAME}}"
+    action: "{{new|modified|removed}}"
+    scope: "{{client|server|build|script}}"
+    required: "{{always|production|feature:<flag>|optional}}"
+    default: "{{valore di default, o '—' se nessuno}}"
+    feature_card: "{{nome feature / ID card, es. SPU / ADR-2026-04-24}}"
+    note: "{{a cosa serve}}"
+
+# --- Data Fields (MANDATORY for cards that read/write Firestore — omit for UI/docs/config only) ---
+# Structured field-name registry for mechanical validation (pre-commit hook + Quality Audit).
+# Field Grounding Rule: EVERY field here MUST be verified via Grep on field-registry.json
+# BEFORE ts_verified is set to true. See prd-card-writer.md Field Grounding Rule.
+# Fields id, createdAt, updatedAt are universal — do NOT include them here.
+data_fields:
+  - collection: "{{collectionName}}"          # exact key in ${paths.references_dir}/field-registry.json
+    field: "{{fieldName}}"                    # exact field name (verified via Grep)
+    type: "{{TypeScript type}}"               # e.g. "string", "OccasionType", "boolean"
+    status: "{{existing|new|modified|deprecated_removed}}"
+    ts_verified: {{true|false}}               # true = Grep confirmed field in registry
+    source: "{{src/types/booking.ts}}"        # TypeScript file where interface is defined
+    # schema_ref: "PRD.md#schema-verification"  # ONLY for status: new fields
+
+firestore_indexes:
+  - collection: "{{collection name}}"
+    fields:
+      - field: "{{field1}}"
+        order: "{{ASC|DESC}}"
+      - field: "{{field2}}"
+        order: "{{ASC|DESC}}"
+    query_location: "{{file path where the query lives}}"
+    prd_ref: "IDX-{{N}}"
+    # Omit this section entirely if the card has no compound Firestore queries.
+    # If present, the coder MUST add these indexes to firestore.indexes.json
+    # in the same commit as the query code.
+
+documentation_impact:
+  - "{{doc path}} — {{what to update}}"
+
+assumptions:
+  - "{{assumption}}"
+
+unknowns: []
+
+notes: []