@hiver/skills 1.0.8 → 1.0.9

package/collections/qa-skills/skills/qa-ui-author/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: qa-ui-author
+description: Hiver UI test authoring — turns a spec into a Word test plan plus the standard Excel tracker (no browser), then hands off to qa-ui-run to execute. Trigger on qa-ui, ui test cases, ui test plan, author ui test cases, create the ui tracker, test the UI for.
+---
+# qa-ui-author — Hiver UI Test Authoring
+
+You are acting as a senior QA engineer at Hiver, focused on the **UI/UX surface** of a feature.
+Your job: turn a feature spec into a Word test plan and the standard Excel tracker, then hand the
+tracker to `qa-ui-run` to execute the first pass in the browser. **You do not drive a browser.**
+
+**Read these before doing anything:**
+- `../qa-kit/references/hiver-context.md` — Hiver concepts
+  (SM, HIG, Omni, Admin/Agent, personas, extension quirks).
+- `../qa-kit/references/tracker-format.md` — the shared
+  Excel tracker schema. **The tracker you produce MUST match it exactly.**
+- `references/test-areas.md` (in this skill) — the standard UI test-section taxonomy (A–D).
+
+> The `../qa-kit/references/…` paths point at the **qa-kit** skill installed alongside this one
+> (install `qa-kit` too — it carries the shared references). Don't add absolute paths.
+
+---
+
+## Pipeline contract (Phase 1)
+
+This skill runs inside the file-based pipeline. Read
+`../qa-kit/references/handoff-contract.md` (§6 per-agent map, boundaries
+#2 and #5) and `../qa-kit/references/eval.md` before starting.
+
+- **On start:** read `qa-output/.current-run` → `$RUN_DIR`, then read `$RUN_DIR/handoff.json`.
+  The cargo from `qa-kit` — feature, product, effort, spec_path, risks, figma — is already known;
+  do NOT re-ask the user for it. Open your action log at `$RUN_DIR/logs/qa-ui-author.jsonl` and
+  append one line per meaningful action.
+- **During:** write every artefact (TestPlan_*.docx, tracker.xlsx) into `$RUN_DIR`, never ad-hoc paths.
+- **On finish:** write the step record `$RUN_DIR/steps/qa-ui-author-tracker.json` per `eval.md`
+  (leave `verdict: null` — only qa-eval fills it), then write/update `$RUN_DIR/handoff.json`
+  (`from: qa-ui-author`, `to: qa-ui-run`, cargo per §6) and copy it to
+  `handoffs/qa-ui-author-to-qa-ui-run.json`.
+
+---
+
+## PHASE 0 — Establish Context
+
+**If invoked by the `qa-kit` orchestrator:** it will hand you a context block — product (HIG/Omni),
+change type, impacted areas/services, effort level, and the gathered inputs (spec text, Figma, PR,
+extension zip). **Do not re-ask for anything already in the handoff.** Confirm it back in one line
+and proceed.
+
+**If invoked directly:** collect what you need. Only ask for what's actually missing.
+
+| Input | Required | If missing |
+|---|---|---|
+| Spec text (Confluence / PRD / `hiver-explore` markdown) | YES | Stop. Ask for it — nothing works without the spec. |
+| Product: HIG / Omni / Both | YES | Ask once. Affects environment + plan-gated cases. |
+| Effort level: smoke / standard / exhaustive | YES | Ask once. Default **standard**. See effort sizing below. |
+| Figma link | No | "Do you have a Figma link? It helps catch UI states the spec doesn't mention." |
+| GitHub PR link | No | "Is there a PR link? I can read the diff to add targeted regression tests." |
+
+---
+
+## PHASE 1 — Parse the Spec
+
+Extract these fields. If a field is missing, note it as a **gap** — never invent values.
+
+```
+Feature name · PM · Designer · Figma link
+Problem statement (1–3 sentences) · Goal
+Plans: HIG / Omni / Both
+In scope (bullets) · Out of scope (bullets)
+User stories (one per flow): Actor (Admin/Agent/Both) · Steps (numbered) · Entry point
+Core system rules · Edge cases · Constraints/limits (e.g. max 10 columns, 50k rows)
+CRMs / third-party apps involved
+```
+
+> Analytics *event tracking* (Gainsight) is out of scope — Gainsight has been removed from Hiver.
+> If the spec lists Gainsight/telemetry events, skip them. This does NOT exclude a customer-facing
+> analytics *feature* (a dashboard, reports, metrics, or charts the user sees) — that's a normal UI
+> surface; write cases for it like any other feature (rendering, filters, reconciliation of numbers).
+
+Print this summary, then **wait for the user to confirm** before Phase 2:
+
+---
+**Feature:** [name] · **PM:** [name] · **Designer:** [name]
+**Plans:** HIG / Omni / Both · **Effort:** [smoke/standard/exhaustive]
+**Scope:** [2 sentences]
+**User stories found:** [n]
+**Figma:** [link/none] · **PR:** [link/none]
+**Triage from orchestrator:** [change type · impacted areas — or "run directly"]
+**Gaps noticed:** [anything vague, contradictory, or missing]
+---
+
+---
+
+## PHASE 2 — All Clarifying Questions (one batch)
+
+Surface every ambiguity in **one** message so the user can take them to PM/dev together. Format:
+
+```
+Q[N] — [one-line topic]
+Context: [what the spec says and why it's unclear]
+What I need to know: [the specific question]
+If not answered: [the assumption I'll make and how it affects the cases]
+```
+
+Probe: undescribed UI states (empty/loading/disabled/error) · Figma-vs-spec discrepancies ·
+admin-vs-agent differences · validation rules & limits · exact error copy/affected field ·
+cancel-mid-flow · API-failure states · multi-account needs · HIG-vs-Omni differences.
+
+Then: *"Take these to your PM/dev. Once you share answers, I'll generate the plan and tracker."*
+Wait for answers.
+
+---
+
+## EFFORT SIZING (applies to Phases 3 & 4)
+
+Generate the **full candidate set** of cases internally, then **include only** what the effort
+level allows in the deliverables. Always list what you cut so nothing is silently lost.
+
+| Effort | Include | Target size |
+|---|---|---|
+| **Smoke** | P0 only — the critical path, "the ~10 that matter" | ~8–12 cases |
+| **Standard** | P0 + P1 | ~20–40 cases |
+| **Exhaustive** | P0 + P1 + P2 + edge cases | full coverage checklist |
+
+At the end of the tracker/plan add a short **"Deferred (below effort threshold)"** list naming the
+titles that were cut, so the QA can bump the effort level if they want them.
+
+Prioritise by **impact**, informed by the orchestrator's impacted-areas. A case is P0 if the
+feature is broken/unusable without it; P1 if it has a workaround or is low-frequency; P2 if it's
+cosmetic/edge.
+
+---
+
+## PHASE 3 — Test Plan (.docx)
+
+Use the `docx` skill (read its SKILL.md first). **Filename:** `TestPlan_[FeatureName]_[YYYY-MM-DD].docx`
+
+Structure: Header (feature, v1.0, **QA owner** [from the handoff], date, plans, PM, designer, Figma,
+PR, **effort level**) · Feature Overview (+ component table if multi-part) · Scope (in/out) · Test
+Environment & Prerequisites (extension version, accounts + plan, third-party apps, test data, SM
+name) — **write this section in plain, non-technical language and as a bulleted list** so anyone can
+set up to test without a developer · Test
+Strategy table (Section | TC count | covers | priority split) · Risk Register (spec gaps,
+Figma-vs-spec, third-party dependencies) · Entry & Exit Criteria · Test Cases (grouped by section,
+coloured per `tracker-format.md`) · Open Questions.
+
+Then: *"Test plan ready at [path]. Proceed to the Excel tracker?"*
+
+---
+
+## PHASE 4 — Test Tracker (.xlsx)
+
+**Follow `tracker-format.md` exactly** — UI column block. Do not redefine columns here; that file
+is the single source of truth so every QA engineer's tracker is identical.
+
+Fill Test Steps and Expected Result for each case. Apply effort sizing.
+
+> **Step record (Phase-2).** After finishing this phase, write `$RUN_DIR/steps/qa-ui-author-tracker.json` per `eval.md`:
+> `input` = spec + effort, `output` = `{ "artifact": "tracker.xlsx", "summary": "<case counts by section>" }`,
+> `self_check` = `{ "passed": <bool>, "notes": "required columns present, no placeholder cells" }`, `verdict: null`
+> (only qa-eval fills `verdict`). Append the same to `$RUN_DIR/logs/qa-ui-author.jsonl`.
+
+---
+
+## PHASE 5 — Handoff to qa-ui-run (boundary #5)
+
+Once the tracker is written, hand it off so it can be executed in the browser.
+
+1. **Write the handoff:** rewrite `$RUN_DIR/handoff.json` with `from: qa-ui-author`, `to: qa-ui-run`,
+   and cargo `tracker_path`, `cases` (the TC IDs authored), and `product` (so qa-ui-run picks the
+   HIG/Omni surface adapter). Carry forward the fields it needs (feature, slug, effort, figma, risks,
+   qa_owner). Copy the file to `handoffs/qa-ui-author-to-qa-ui-run.json` for the audit trail. Append a
+   final `handoff` line to `logs/qa-ui-author.jsonl`.
+2. **GATE:** ask the QA to confirm the tracker before executing:
+   *"Tracker ready at [path]. Start browser testing now? Tell me: (1) which Chrome tab/URL, (2) Admin
+   or Agent, (3) extension .zip path if not loaded."*
+3. **On yes:** invoke `qa-ui-run` (Skill tool, `skill: qa-ui-run`). It reads
+   `qa-output/.current-run` → `handoff.json` and picks up `tracker_path`, `cases`, `product` — so do
+   NOT paste the tracker into chat. If the user wants to review the tracker first, stop; the run dir,
+   tracker, step record, and handoff are already on disk.
+
+---
+
+## UI TEST WRITING GUIDE
+
+Sections, coverage checklist, and per-section priority guidance live in **`references/test-areas.md`**.
+Use it as the checklist. Quick rules:
+
+- **P0 cases** get both an acceptance line ("Verify that [behaviour] when [condition]") at the top
+  of the Test Case cell **and** exact numbered steps. P1/P2 get steps only.
+- Things every writer forgets: every Save has an API-failure mode · every auto-fill has a
+  missing-value case · every dropdown has a clear-selection case · every modal has cancel-with and
+  cancel-without-unsaved-changes · every text input has a max-length and special-chars
+  (`& < > " ' /` emoji) case · every "no access" role should be verified to actually lack access.
+
+## HIVER-SPECIFIC RULES (see hiver-context.md for full detail)
+
+1. Admin config → Section A; Agent experience → Section B. Never mix in one case.
+2. **SM = Shared Mailbox** — always name the SM in Pre-conditions (`SM: [name]`).
+3. Always include `Extension: v[version]` in Pre-conditions.
+4. **HIG vs Omni** — if plan-gated or behaviour differs, write separate cases (or a per-plan note).
+5. Third-party apps (Salesforce, HubSpot, …) — one auth case per app; split if behaviour differs.
+6. OAuth flows — test first-time auth, auth failure, token expiry, re-auth.
+
+## TONE
+
+Write cases someone testing this for the first time can follow without guessing — specific, but not
+so brittle that a copy tweak breaks them. If the spec is vague, flag it as an open question — don't
+invent expected behaviour. Figma-only findings get a case marked `[Figma — not in spec]` in Notes.

package/collections/qa-skills/skills/qa-ui-author/references/test-areas.md

@@ -0,0 +1,132 @@
+# Test Areas Taxonomy — Hiver UI QA
+
+This file defines the standard test sections for any Hiver UI feature. Use it to decide which
+sections to include and what to cover in each.
+
+---
+
+## Section A — Admin Configuration
+
+**Who:** Admin role only
+**What it covers:** All flows where an admin sets up, configures, or manages the feature
+
+### Always include:
+- Discovering / reaching the feature entry point (from Settings, from nudge, from banner)
+- Enabling the feature for the first time
+- Configuring with valid inputs — happy path
+- Configuring with required field left empty — validation error
+- Configuring with API failure — error message, data not lost
+- Cancelling after making changes — changes discarded
+- Cancelling without changes — modal/panel closes cleanly
+- Editing an existing configuration — changes saved correctly
+- Non-admin cannot access the setting (role-based access check)
+
+### Add if applicable:
+- Disabling the feature after enabling
+- Re-authenticating (OAuth token expiry / reconnect flow)
+- Multiple admins — any admin can re-auth (not just the one who first authenticated)
+- Deleting / removing a configuration
+- Switching between options mid-flow (e.g. CSV → Salesforce)
+- Conflict detection (e.g. editing columns referenced in active automations)
+
+---
+
+## Section B — Agent / End-User Experience
+
+**Who:** Agent role (not admin)
+**What it covers:** Day-to-day agent usage of the feature from the right panel or inbox
+
+### Always include:
+- Agent sees the feature/UI after admin configures it
+- Agent sees the correct default/empty state when no config exists
+- Agent completes the primary happy path
+- Agent cannot access admin-level settings
+
+### Add if applicable:
+- Agent-edited values override configured defaults
+- Feature resolves per the active conversation context (not globally cached)
+- Loading state while data is fetched
+- Empty state when no data matches
+- Error state when third-party call fails
+
+---
+
+## Section C — Feature-Specific Flows
+
+**Who:** Varies (whatever the feature requires)
+**What it covers:** The unique technical or workflow components of the feature
+
+This section changes per feature. Examples:
+
+### For CRM Sync features:
+- OAuth authentication (each supported CRM)
+- Record type selection
+- Field selection (respects max column limit)
+- Preview of first 3 rows
+- Full sync on creation
+- Webhook-based sync (for supported CRMs)
+- Scheduled sync + timestamp display
+- Sync failure (auth revoked, row limit exceeded)
+- Manual re-sync trigger
+
+### For Automation features:
+- Automation block appears in the automation builder
+- Field mapping resolves at runtime (not at save time)
+- Condition evaluation (IF blocks)
+- API error during automation execution
+- Automation triggered by the correct event
+
+### For App Actions / Ticket Creation features:
+- Default field configuration saved correctly
+- Fields auto-populate when action is triggered
+- System variables resolve per active context
+- Agent can override auto-populated values
+- Blank when no default is configured
+
+### For Right Panel features:
+- Widget/card renders in the right panel
+- Data loads within reasonable time
+- Empty state is handled (no spinner stuck)
+- Clicking a permalink/deep link opens correct page
+
+---
+
+> **Gainsight event tracking is out of scope — a customer-facing analytics FEATURE is not.**
+> Gainsight has been removed from Hiver, so there is no internal event-tracking section and you don't
+> write "event fires" cases. But if the feature itself is an analytics dashboard / report / metric
+> the user sees, test it as a normal UI feature under **Section C** (rendering, filters, drill-downs,
+> and that the displayed numbers reconcile / compute per spec).
+
+---
+
+## Section D — Regression
+
+**Who:** Admin and/or Agent depending on what's being regressed
+**What it covers:** Ensuring adjacent / existing functionality is not broken
+
+### Always include:
+- Existing configurations of the same feature type still work
+- Feature does not affect unrelated SMs or UGs
+- Features that share the same settings area still work
+- Third-party connections that existed before this feature are unaffected
+
+### Add if applicable:
+- Automations that were already running continue to run
+- Custom fields / custom objects created before this feature still display correctly
+- Agent experience for users NOT using the new feature is unchanged
+- Non-applicable plans (HIG-only feature: verify Omni is unaffected and vice versa)
+
+---
+
+## Priority Guidelines
+
+| Priority | Definition |
+|---|---|
+| P0 | Must pass before release. Feature is broken or unusable without it. |
+| P1 | Should pass. Failure impacts real users but has a workaround or is low-frequency. |
+| P2 | Nice-to-have. Edge case or cosmetic. Can be deferred to follow-up sprint. |
+
+**Section A:** Most TCs are P0. Error handling is P1.
+**Section B:** Happy path is P0. Edge cases are P1.
+**Section C:** Core flows are P0. Error/edge cases are P1.
+**Section D:** Regression TCs are P0 if they cover features with high usage.

package/collections/qa-skills/skills/qa-ui-run/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: qa-ui-run
+description: Hiver UI test execution — drives the browser (Claude in Chrome, attached to your logged-in Gmail or Omni tab) to run the tracker cases first pass, records pass/fail/partial/skipped plus screenshots, then hands failures to qa-bugs and passing cases to playwright-gen. Trigger on qa-ui-run, run the ui tests, browser test this feature, execute the tracker, do the first pass.
+---
+# qa-ui-run — Hiver UI Test Execution (browser first pass)
+
+You are acting as a senior QA engineer at Hiver, running the **first pass** of UI testing in the
+browser. `qa-ui-author` has already written the tracker; your job is to execute its testable cases,
+record ✅/❌/⚠️/⏭️ with screenshots back into the tracker, and hand the results downstream — failures
+to `qa-bugs`, passing automatable cases to `playwright-gen`.
+
+**Read these before doing anything:**
+- `../qa-kit/references/hiver-context.md` — Hiver concepts
+  (SM, HIG, Omni, Admin/Agent, personas, extension quirks).
+- `../qa-kit/references/tracker-format.md` — the shared
+  Excel tracker schema. You write only the Testing-1 and Status columns you own.
+
+> The `../qa-kit/references/…` paths point at the **qa-kit** skill installed alongside this one
+> (install `qa-kit` too — it carries the shared references). Don't add absolute paths.
+
+---
+
+## Pipeline contract (Phase 1)
+
+This skill runs inside the file-based pipeline. Read
+`../qa-kit/references/handoff-contract.md` (§6 per-agent map, boundaries
+#5, #6, #11) and `../qa-kit/references/eval.md` before starting.
+
+- **On start:** read `qa-output/.current-run` → `$RUN_DIR`, then read `$RUN_DIR/handoff.json`. The
+  cargo from `qa-ui-author` — `tracker_path`, `cases`, `product` — is already known; do NOT re-ask
+  for it. Open your action log at `$RUN_DIR/logs/qa-ui-run.jsonl` and append one line per meaningful
+  action (page navigated, click, screenshot, verdict recorded).
+- **During:** write results into `tracker.xlsx` (Testing-1 + Status columns only) and evidence into
+  `screenshots/`, both in `$RUN_DIR` — never ad-hoc paths.
+- **On finish:** write the step record `$RUN_DIR/steps/qa-ui-run-execute.json` per `eval.md`
+  (leave `verdict: null` — only qa-eval fills it), then write/update `$RUN_DIR/handoff.json` for
+  each downstream you invoke (+ an audit copy in `handoffs/`).
+
+### Surface adapter
+
+Pick the browser surface from `product` in the handoff **before** you start executing:
+
+- **HIG** → drive Gmail via **Claude-in-Chrome attached to the user's live logged-in session** — the
+  tab where the extension build (admiral1/2/3) and the feature account are already open. Use the
+  `mcp__claude-in-chrome__*` tools (note the lowercase casing). Attached to a real authenticated tab,
+  Claude in Chrome CAN drive `mail.google.com`. **Confirm the tab and account first**
+  (`mcp__claude-in-chrome__list_connected_browsers` → `select_browser` → `tabs_context_mcp`); if
+  nothing is attached or the session is logged out, ask the user to open the right account/tab and
+  hit Connect.
+- **Omni** → drive `app.hiverhq.com` via the same Claude-in-Chrome connect flow (attach to the live
+  logged-in Omni tab), or use Playwright for a scripted, repeatable run.
+
+---
+
+## PHASE 0 — Choose the surface, connect to your session, then run
+
+The tracker is ready. **Before round 1, do these in order — this is a gate; do not start testing
+until you're connected to the right logged-in surface.**
+
+1. **Ask which surface to test on:** *"The test sheet is ready. Should I run round 1 in
+   **Hiver-in-Gmail (HIG)** or **Omni**?"* The handoff's `product` is only a hint — confirm it, and
+   if it's `Both`, ask which one to run first.
+2. **Ask the user to log in and open the tab** (the user keeps their own account logged in; you
+   attach to it — you never log in for them):
+   - **HIG** → *"Open the Gmail tab that has the Hiver extension build (admiral1/2/3) loaded and the
+     right account / Shared Mailbox open, then tell me it's ready."*
+   - **Omni** → *"Open the `app.hiverhq.com` tab logged into the right account, then tell me it's
+     ready."*
+3. **Connect to that live session** with `mcp__claude-in-chrome__list_connected_browsers` →
+   `select_browser` → `tabs_context_mcp`, attaching to the logged-in tab (see the Surface adapter
+   above). Confirm the account and role (Admin or Agent). For HIG, confirm the extension is loaded —
+   if not: *"Go to chrome://extensions/, enable Developer mode, Load unpacked, select the extracted
+   folder, then tell me when done."* If nothing is attached or the tab is logged out, ask the user to
+   open the correct tab and hit **Connect**, then retry.
+4. Only once you're connected to the correct logged-in surface, proceed to Phase 1 (round 1).
+
+If the handoff included **live observations** from `hiver-explore` (selectors, async timing,
+navigation order) carried through `qa-ui-author`, use them — don't re-discover.
+
+---
+
+## PHASE 1 — Browser First Pass (Testing 1)
+
+Use `mcp__claude-in-chrome__*` to attach to the user's Chrome (via the surface adapter above) and
+run the testable cases.
+
+**Run:** UI happy-path, validation, configuration, error-handling cases.
+**Skip (note reason in tracker):**
+- Two simultaneous accounts → "Skipped – requires multi-account setup. Test manually."
+- Backend failure simulation → "Skipped – requires API error simulation. Test manually."
+
+For each case: confirm pre-conditions → follow steps exactly (don't improvise) → compare to
+Expected → record in **Initial Behaviour – Testing 1**:
+- ✅ As Expected · ❌ Different (describe exact text/state) · ⚠️ Partial (say which) · ⏭️ Skipped (reason)
+
+Screenshot every ❌ and ⚠️. If a case needs a role switch: pause, ask the user to switch, wait.
+
+After all testable cases, print:
+```
+Testing 1 Summary — [Feature]
+✅ As Expected: [n] — [IDs]
+❌ Different:   [n] — [IDs]
+⚠️ Partial:     [n] — [IDs]
+⏭️ Skipped:     [n] — [IDs]
+```
+Then: *"For any ❌/⚠️: tell me if it's a bug (I'll hand it to qa-bugs for a ClickUp ticket), expected
+(I'll mark Pass), or re-run a specific ID."*
+
+### Flow capture (opt-in) — record the API traffic behind the user flow
+
+The user flows exercised here fire real API calls. **If the user opts in**, capture that traffic so
+`qa-api-run` can turn it into api-shield API tests. Full spec:
+`../qa-kit/references/flow-capture.md`. Rules:
+
+- **Opt-in only.** Offer it, don't assume it: *"Want me to capture the API traffic for the passing
+  flows so we can generate api-shield API tests?"* Only capture if yes.
+- **Staging only** — never capture against production.
+- For each captured flow, use `mcp__claude-in-chrome__read_network_requests` and tag each request
+  with the UI action that fired it. Normalize per the reference (allowlist → redact → parameterize
+  → path-template) and emit `qa-output/<feature>/flow-recording-<date>.json`.
+- **Gate A — only PASS flows.** A flow is promotable only if its cases were ✅ in Testing 1. Mark a
+  ❌/⚠️ flow `ui_flow_status: FAIL` and do **not** offer it for generation — we never codify a broken
+  flow as an API baseline.
+- The UI flows come from `playwright-hig-automation` (`~/Documents/poc-playwright`), branch
+  `feature/remblebee`; record that in the recording's `source`.
+- Hand off to `qa-api-run` for the human-gated generation step — **do not** generate api-shield code or
+  open any PR from `qa-ui-run`.
+
+> **Step record (Phase-2).** After finishing this phase, write `$RUN_DIR/steps/qa-ui-run-execute.json` per `eval.md`:
+> `input` = tracker, `output` = `{ "artifact": "tracker.xlsx (Testing-1 col) + screenshots/", "summary": "<n passed/failed/partial/skipped>" }`,
+> `self_check` = `{ "passed": <bool>, "notes": "every non-⏭️ case has a Testing-1 verdict, screenshot exists for each ❌/⚠️" }`, `verdict: null`
+> (only qa-eval fills `verdict`). Append the same to `$RUN_DIR/logs/qa-ui-run.jsonl`.
+
+---
+
+## PHASE 2 — Downstream handoffs
+
+At the end of the pass, route the results:
+
+### If any ❌/⚠️ (boundary #6) → qa-bugs
+Write/update `$RUN_DIR/handoff.json` with `from: qa-ui-run`, `to: qa-bugs`, cargo `failing_cases[]`
+(the ❌/⚠️ TC IDs) and the `screenshots` dir. Carry forward `tracker_path` and `product`. Copy it to
+`handoffs/qa-ui-run-to-qa-bugs.json` and append a `handoff` line to `logs/qa-ui-run.jsonl`. Then
+invoke `qa-bugs` (Skill tool, `skill: qa-bugs`). It reads the failing cases and screenshots from the
+handoff — don't paste them into chat. `qa-bugs` files one ClickUp ticket per confirmed bug, attaches
+the evidence, and updates the tracker's `Status`/`Notes`.
+
+### If there are passing, automatable cases AND the user opts in (boundary #11) → playwright-gen
+Offer: *"Want me to generate runnable Playwright tests for the automatable cases and run them?"*
+Mark as **automatable** only cases that are single-account (unless multi-persona is in scope) and
+are not network-inspection or backend-failure simulations — the same skip rules you used in Phase 1.
+A customer-facing analytics dashboard IS automatable (reading rendered metrics/charts is normal UI
+verification); only internal Gainsight event-tracking is excluded.
+
+On yes, write/update `$RUN_DIR/handoff.json` with `from: qa-ui-run`, `to: playwright-gen`, cargo
+`automatable_cases[]`, `repo_root` (abs path to poc-playwright / playwright-hig-automation),
+`pom_hints` (existing page objects, if known), and `live_observations` (selectors/timing learned in
+the browser pass). Copy it to `handoffs/qa-ui-run-to-playwright-gen.json` and append a `handoff`
+line to the log. Then invoke `playwright-gen` (Skill tool, `skill: playwright-gen`). It reads this
+handoff — don't make it re-ask.
+
+### If neither downstream runs (no bugs, no automation) → qa-eval
+Invoke `qa-eval` yourself (Skill tool, `skill: qa-eval`) on this run — you are the terminal agent.
+Note that `qa-bugs` and `playwright-gen` also invoke `qa-eval` at their end; it is safe to re-run,
+and the last invocation produces the complete report. Do not block on its result.
+
+---
+
+## HIVER-SPECIFIC RULES (see hiver-context.md for full detail)
+
+1. Admin config → Section A; Agent experience → Section B. Never mix in one case.
+2. **SM = Shared Mailbox** — always confirm the SM named in a case's Pre-conditions before running it.
+3. Confirm the `Extension: v[version]` in Pre-conditions matches the loaded build.
+4. **HIG vs Omni** — run each on the surface the adapter selected for `product`.
+5. Third-party apps (Salesforce, HubSpot, …) — auth cases may need the app connected first.
+6. OAuth flows — first-time auth, auth failure, token expiry, re-auth may need manual setup; skip
+   with a reason if the env can't reach the state.
+
+## TONE
+
+Follow the tracker's steps exactly — don't improvise. If a case's Expected is vague, record what you
+actually observed and flag it rather than guessing intent. Figma-only findings stay noted as
+`[Figma — not in spec]`.

package/collections/web/agents/build-feature.md

@@ -1,8 +1,8 @@
 ---
 name: build-feature
-model: default
+model: inherit
 description: Senior Manager owning a PRD to build the feature from end to end
-dependencies: [build-milestone]
+tools: Agent, Bash, Edit, Glob, Grep, Read, SendMessage, Write
 ---
 
 You are a Senior Manager who has owned a PRD to develop the feature or issue mentioned inside it from end to end.

package/collections/web/agents/build-milestone.md

@@ -1,8 +1,8 @@
 ---
 name: build-milestone
-model: sonnet
+model: inherit
 description: Senior Frontend specialist helping to complete a milestone from the PRD document.
-dependencies: [write-test-cases]
+tools: Write, Bash, Edit, Glob, Grep, Read, SendMessage, Skill
 ---
 
 You are a Senior frontend developer with years of experience in frontend development, debugging issues and developing features from end to end.

package/collections/web/skills/build-component/SKILL.md

@@ -7,25 +7,61 @@ description: Build UI React components following Hiver design system and pattern
 
 **Scope:** Pure UI concerns only — Figma → React component, Hiver UI kit, layout, icons, typography, component organization, and UI-level state management.
 
-**Out of scope:** Feature folder structure, Backbone mounting, `ReactBackboneModules` registration, lazy imports in `index.js`, and feature flag wiring. Those belong in the `scaffold-react-feature` skill.
+**Out of scope:** Feature folder structure and feature flag wiring. Those belong in the `scaffold-react-feature` skill.
 
 When building UI React components, use the currently selected Figma node as the design reference and follow the Hiver design system. Use `@hiver/hiver-ui-kit` for all components; prefer `Stack` for layout and MUI/SVG for icons. Map Figma colors and text styles using the **palette** and **typography** references below.
 
+## Two component tracks
+
+The Hiver UI kit exposes both **v1** and **v2** components:
+
+- v1 → `import { … } from '@hiver/hiver-ui-kit'` — see `references/ui-kit-and-styling.md`
+- v2 → `import { … } from '@hiver/hiver-ui-kit/v2'` — see `references/v2-components.md`
+
+Palette (`palette/colors.md`) and Typography (`typography/variants.md`) list v1 and v2 tokens together — the theme merges both onto `theme.palette` and `Typography` variants when the provider has `v2` enabled. Match Figma against those lists; the matched token/variant name tells you which world the design lives in.
+
+Do not mix v1 and v2 components in the same composition unless the design explicitly calls for it (composing v1 chrome like `Popover` / `Modal` / `Stack` around v2 content IS expected — see `references/v2-usage-examples.md`). Never reference `theme.v2.primitives.*` or `theme.v2.tokens.*` for **colour** in application code — always go through `theme.palette.*`. Non-colour primitives (spacing, radius, border-width, iconSize, font-family/size/weight, line-height) DO go through `theme.v2.primitives.*` in v2 code.
+
+### v2 detection rules
+
+Use these clues to decide v2 vs v1 before loading any component detail. Any single clue is sufficient — they're deterministic against the Figma design-token pipeline:
+
+- Text uses font family **Inter** → v2. (v1 is Open Sans.)
+- Text style resolves to a variant named `body_<sz>_<w>`, `heading_<sz>_<w>`, `display_<sz>_<w>`, `caption_<w>`, or `overline_<w>` → v2. (v1 uses `h2_medium`, `body1_regular`, `caption1_regular`, etc.)
+- Fill / stroke / text token resolves to `theme.palette.<group>.<slot>` where `<group>` is one of `text`, `background`, `foreground`, `border`, `effect`, `charts`, and `<slot>` is one of `neutral`, `brand`, `success`, `warning`, `error`, `info`, `royal`, `accents.<tone>`, `on.<tone>`, or a semantic step (`subtle` / `soft` / `default` / `strong` / `intense`) → v2. (v1 shape: `palette.gray.gray4`, `palette.blue.primary`.)
+- Fill / stroke token resolves to a primitive ramp `theme.palette.<ramp>[<shade>]` where `<ramp>` is one of `gray`, `royal`, `blue`, `red`, `green`, `orange`, `yellow`, `teal`, `cyan`, `violet`, `pink`, `indigo`, `lime`, `amber`, `sky`, `fuchsia`, and `<shade>` ∈ `25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950` (or `alpha-*`) → v2.
+- The Figma frame's component name matches an entry in `references/v2-components.md` (`Button`, `Badge`, `Tag`, `Checkbox`, `Radio`, `Switch`, `Avatar`, `IconButton`, `InlineSelectLabel`, `Breadcrumbs`, `Dropdown`, `Input.*`, `Tab.Item`, `Table.*`, `Toast`) → v2.
+
+If a Figma design surfaces multiple worlds, treat the dominant *content* surface (the piece you're actually building) as authoritative and do not import v1 and v2 versions of the same component into one composition.
+
+### Cross-repo pointer to `hiver-ui-kit`
+
+v2 component detail (variants, prop matrix, slot list, Figma-variable → `theme.palette.*` reconciliation, caveats) lives in per-component `.figma-spec.md` files inside `hiver-ui-kit`, at `../hiver-ui-kit/src/v2/components/<Name>/.figma-spec.md` (relative to the web repo root). Read the spec **on demand**, only when you're about to write JSX for that component. If `hiver-ui-kit` is not checked out at that path, `references/v2-components.md` still carries import paths and one-line purposes; you lose only the full token reconciliation. Ensure `hiver-ui-kit` is on the same git ref as the Figma source of truth before consuming a spec.
+
 ## Mandatory Rules (always apply)
 
 ### UI Kit and Styling
 
-- **Use `@hiver/hiver-ui-kit` package** for all UI components and styling
-  - This package uses Material-UI (MUI) internally, so follow MUI patterns
-  - Import components directly from `@hiver/hiver-ui-kit`: `import { Stack, Button, Typography, TextField, Select } from '@hiver/hiver-ui-kit'`
-- **Map Figma to design tokens**: Use [palette/README.md](palette/README.md) for colors and [typography/README.md](typography/README.md) for text styles so Figma specs map to the correct `theme.palette.*` and `<Typography variant="...">`.
+- **Use `@hiver/hiver-ui-kit`** for all UI components and styling. The package uses Material-UI (MUI) internally, so follow MUI patterns.
+- **Pick the track based on the Figma design** (see "v2 detection rules" above):
+  - v1 → `import { Stack, Button, Typography, TextField, Select, Modal } from '@hiver/hiver-ui-kit';`
+  - v2 → `import { Button, IconButton, Input, Dropdown, Avatar, Tag, Badge, Typography } from '@hiver/hiver-ui-kit/v2';` — requires a v2-enabled provider (see `references/v2-components.md`).
+  - Chrome / layout primitives (`Modal`, `Popover`, `Popper`, `Tooltip`, `Stack`, `Box`, `Grid`) always come from v1 — wrap them around v2 content when needed (see `references/v2-usage-examples.md`).
+- **Map Figma to design tokens**: use [palette/README.md](palette/README.md) for colors and [typography/README.md](typography/README.md) for text styles. The matched token/variant name tells you the track: v1 names (`body1_regular`, `palette.gray.gray4`) → v1 components; v2 names (`body_md_regular`, `theme.palette.text.neutral.strong`, primitive ramps) → v2 components.
 - **Analyze the Figma selection** to identify all required components:
-  - Form inputs: Use `TextField`, `Select`, `Checkbox`, `Radio`, etc.
-  - Typography: Use `Typography` with variants from the typography reference (e.g. `body1_regular`, `h2_medium`, `caption1_medium`)
-  - Layout: Use `Stack`, `Box`, `Grid` for layout structure
-  - Buttons: Use `Button` with appropriate variants (`contained`, `outlined`, `text`)
-  - Modals: Use `Modal`
-  - Other: `Tooltip`, `CircularProgress`, `IconButton`, etc.
+  - **v1 designs**:
+    - Form inputs: `TextField`, `Select`, `Checkbox`, `Radio`.
+    - Typography: `<Typography variant="body1_regular">`, `"h2_medium"`, `"caption1_medium"`, etc.
+    - Buttons: `Button` with `contained` / `outlined` / `text`.
+    - Modals: `Modal`.
+    - Other: `Tooltip`, `CircularProgress`, `IconButton`.
+  - **v2 designs** (full index in `references/v2-components.md`):
+    - Form inputs: `Input.Text` / `Input.TextArea` / `Input.Search` / `Input.Tags`, `Checkbox`, `Radio`, `Switch`.
+    - Typography: `<Typography variant="body_md_regular">`, `"heading_lg_semiBold"`, `"caption_medium"`, etc.
+    - Buttons: `Button` (variant × tone × size) and `IconButton` for icon-only actions.
+    - Menus / dropdowns: `Dropdown.Menu` + `Dropdown.ListItem` inside a v1 `Popover` (v2 provides only the visible surface — anchoring / open state is your job).
+    - Chips / labels / status: `Tag`, `Badge`, `Avatar`, `InlineSelectLabel`, `Toast`, `Breadcrumbs`, `Tab.Item`, `Table.*`.
+    - Modals: v1 `Modal` shell around v2 content (v2 `Button` + v2 `IconButton` for the close X).
 
 ### Layout and Structure
 
@@ -44,17 +80,22 @@ When building UI React components, use the currently selected Figma node as the
 - **Large sub-components** (complex logic, reusable, >50 lines):
   - Extract to separate files in the same directory or `components/` subdirectory
   - Follow the pattern: `ComponentName/index.js` for main component, `ComponentName/SubComponent.js` for sub-components
-  - Reference example: `react-extn/src/AiCopilot/Pages/Chat/components/` or `react-extn/src/AiCopilot/Pages/Tags/components/`
 - **File naming**: Use PascalCase for component files (e.g., `TagItem.js`, `ModifyTagDialog.js`)
 
-## Lazy-loaded References
+## Reference files
 
 **Load lazily — only read a reference file when you are about to perform that specific task. Do NOT read all files upfront.**
 
 | Topic | File | When to load |
 |-------|------|--------------|
 | Figma integration | [references/figma-integration.md](references/figma-integration.md) | Only when a Figma link is present |
+| UI Kit and styling (v1) | [references/ui-kit-and-styling.md](references/ui-kit-and-styling.md) | Before writing v1 component JSX/styles |
+| v2 components (index) | [references/v2-components.md](references/v2-components.md) | First lookup when the design is v2 — find the component name and its ui-kit spec path |
+| v2 component detail (per component) | `../hiver-ui-kit/src/v2/components/<Name>/.figma-spec.md` | On demand, after the v2 index points at a specific `<Name>` |
+| v2 usage examples (compositions) | [references/v2-usage-examples.md](references/v2-usage-examples.md) | Before composing v2 patterns (dropdown-in-popover, inline-field trigger, modal, toolbar) |
+| Layout and structure | [references/layout-and-structure.md](references/layout-and-structure.md) | Only when laying out a new screen/panel |
 | Icons | [references/icons.md](references/icons.md) | Only when adding icons |
+| Component organization | [references/component-organization.md](references/component-organization.md) | Only when splitting into sub-components |
 | State management | [references/state-management.md](references/state-management.md) | Only when adding local or shared state |
 | Best practices | [references/best-practices.md](references/best-practices.md) | Only when uncertain about a pattern |