code-ai-installer 1.3.1 → 1.4.0

package/locales/en/.agents/skills/pm_prd/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: pm_prd
+description: Generate a PRD — Vision, MVP, out-of-scope, user stories, acceptance criteria, NFR, risks, and open questions. The result must be verifiable.
+---
+
+# Skill: PRD (Product Requirements Document)
+
+A PRD that UX/ARCH/DEV/TEST can work from without "guessing".
+
+**Sections:**
+1. [Workflow](#1-workflow)
+2. [PRD Structure](#2-structure)
+3. [User Story Format](#3-user-story)
+4. [Quality Checklist](#4-quality)
+5. [Handoff Checklist](#5-handoff)
+6. [Example: User Story](#6-example)
+7. [Output Template](#7-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Input: Interview Summary (from $pm_interview)
+2. Draft PRD structure (section 2)
+3. Write user stories + acceptance criteria (section 3)
+4. Define NFR
+5. List risks + open questions
+6. Run quality checklist (section 4)
+7. Submit for User review
+8. After approval → handoff (section 5)
+```
+
+---
+
+## 2. PRD Structure
+
+### 1) Vision & Goals
+
+| Field | Content |
+|-------|---------|
+| Problem | What pain point are we solving? |
+| Target audience | Who are the users? |
+| Value proposition | Why would they use this over alternatives? |
+| Success metrics | How do we measure success? (KPI / OKR) |
+
+### 2) Scope
+
+| In scope (MVP) | Out of scope | Rationale |
+|----------------|-------------|-----------|
+| Feature A | Feature X | Not MVP priority |
+| Feature B | Feature Y | Technical complexity, defer to v2 |
+
+### 3) Roles & Permissions
+
+| Role | Can do | Cannot do |
+|------|--------|-----------|
+| Site Owner | CRUD settings, coupons | Access other sites |
+| End User | View popup, copy coupon | Modify settings |
+
+### 4) User Stories → section 3
+
+### 5) Acceptance Criteria → section 3
+
+### 6) Non-Functional Requirements
+
+| Category | Requirement | Priority |
+|----------|-----------|:--------:|
+| **Security** | Input validation (Zod), no secrets in logs | P0 |
+| **Security** | Server-side auth on all protected endpoints | P0 |
+| **Performance** | API response < 500ms (p95) | P1 |
+| **Performance** | Widget load < 1s (LCP) | P1 |
+| **Reliability** | Graceful error handling, no 500 to user | P0 |
+| **Observability** | Structured logging (pino), request_id correlation | P1 |
+| **Accessibility** | WCAG 2.1 AA baseline (see $a11y_baseline) | P1 |
+| **Localization** | English only (MVP) | — |
+
+### 7) Risks & Open Questions
+
+| # | Type | Description | Impact | Mitigation | Status |
+|---|------|------------|--------|-----------|:------:|
+| R-01 | Technical | Wix API rate limits | High | Caching, retry logic | Open |
+| R-02 | Product | User confusion with templates | Medium | Clear preview | Mitigated |
+
+---
+
+## 3. User Story Format
+
+### Template
+
+```markdown
+### US-XX: <Title>
+
+**As a** <role>
+**I want to** <action>
+**So that** <benefit>
+
+**Priority:** P0 / P1 / P2
+
+#### Acceptance Criteria
+
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-01 | I am on Settings page | I change title and click Save | Title updates in widget preview |
+| AC-02 | I am on Settings page | I leave title empty and click Save | Validation error "Title required" shown |
+| AC-03 | Server is unavailable | I click Save | Error toast "Failed to save" shown |
+```
+
+### Story categories
+
+| Category | Examples | Priority |
+|----------|---------|:--------:|
+| **Core CRUD** | Create coupon, update settings, delete coupon | P0 |
+| **Integration** | Install webhook, Wix auth, embed widget | P0 |
+| **UX Polish** | Loading states, empty states, toasts | P1 |
+| **Error Handling** | Network errors, validation, edge cases | P1 |
+| **Admin** | Analytics, export, bulk ops | P2 |
+
+---
+
+## 4. Quality Checklist
+
+| # | Check | Status |
+|---|-------|--------|
+| PRD-01 | MVP can be built in 1-3 iterations | ☐ |
+| PRD-02 | Every user story has acceptance criteria | ☐ |
+| PRD-03 | AC include positive + negative + edge cases | ☐ |
+| PRD-04 | Out of scope explicitly listed | ☐ |
+| PRD-05 | NFR section is filled (security, perf, a11y) | ☐ |
+| PRD-06 | Risks and open questions documented | ☐ |
+| PRD-07 | Assumptions explicitly marked | ☐ |
+| PRD-08 | PRD is understandable without verbal explanation | ☐ |
+| PRD-09 | No vague language ("should be fast" → "< 500ms p95") | ☐ |
+| PRD-10 | Dependencies between stories identified | ☐ |
+
+---
+
+## 5. Handoff Checklist
+
+What PM passes to downstream gates:
+
+| # | Deliverable | For whom | Status |
+|---|------------|:--------:|--------|
+| 1 | PRD document | UX + ARCH + DEV + TEST | ☐ |
+| 2 | User stories with AC | UX (for flows) + TEST (for test plan) | ☐ |
+| 3 | NFR table | ARCH (for system design) | ☐ |
+| 4 | Risks & open questions | All | ☐ |
+| 5 | Backlog (`$pm_backlog`) | DEV + Conductor | ☐ |
+
+---
+
+## 6. Example: User Story
+
+```markdown
+### US-03: Configure Popup Design
+
+**As a** Site Owner
+**I want to** customize popup colors, fonts, and template
+**So that** the popup matches my store's branding
+
+**Priority:** P0
+
+#### Acceptance Criteria
+| # | Given | When | Then |
+|---|-------|------|------|
+| AC-01 | On Design tab | Change background color | Preview updates in real-time |
+| AC-02 | On Design tab | Select new template | Preview switches to selected template |
+| AC-03 | On Design tab | Click Save | Settings persist, toast "Settings saved" |
+| AC-04 | On Design tab | Enter invalid color | Validation error shown inline |
+| AC-05 | Server down | Click Save | Error toast, settings not lost |
+```
+
+---
+
+## 7. Output Template
+
+```markdown
+# PRD: <Product/Feature Name>
+
+**Version:** 1.0
+**Date:** YYYY-MM-DD
+**Author:** Product Manager Agent
+**Status:** Draft / Review / Approved
+
+## 1. Vision & Goals
+<section 2, table 1>
+
+## 2. Scope
+<section 2, table 2>
+
+## 3. Roles & Permissions
+<section 2, table 3>
+
+## 4. User Stories
+<section 3 format × N stories>
+
+## 5. Non-Functional Requirements
+<section 2, table 6>
+
+## 6. Risks & Open Questions
+<section 2, table 7>
+
+## Quality Checklist
+<section 4 — all checked>
+
+## Handoff
+<section 5 — all checked>
+```
+
+---
+
+## See also
+- `$pm_interview` — interview/discovery (input)
+- `$pm_backlog` — decompose PRD into backlog
+- `$ux_discovery` → `$ux_spec` — UX design (uses PRD)

package/locales/en/.agents/skills/qa_api_contract_tests/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: qa_api_contract_tests
+description: Test API compliance against contracts — schemas, codes, errors, validation, pagination; perform smoke testing via curl/scripts.
+---
+
+# Skill: QA API Contract Tests
+
+Run API smoke tests: endpoints, status codes, error format, validation.
+
+**Sections:**
+1. [Workflow](#1-workflow)
+2. [Test Case Table](#2-test-cases)
+3. [Curl Examples](#3-curl)
+4. [Automation Script](#4-script)
+5. [Output Template](#5-output)
+
+---
+
+## 1. Workflow
+
+```
+1. Load API Contracts (from $api_contracts)
+2. For each endpoint:
+   a. Happy path → correct request → expected status + response shape
+   b. Validation → invalid request → 400 + error format
+   c. Auth → no token → 401
+   d. Not found → wrong ID → 404
+3. Fill results table
+4. For each FAIL → bug report
+```
+
+---
+
+## 2. Test Case Table
+
+### Template per endpoint
+
+| TC-ID | Endpoint | Scenario | Request | Expected Status | Expected Body | Priority |
+|-------|----------|----------|---------|:---------------:|--------------|:--------:|
+| API-TC-01 | POST /api/v1/coupons | Happy: create coupon | `{ code, discount }` | 201 | `{ data: { id, code, discount } }` | P0 |
+| API-TC-02 | POST /api/v1/coupons | Error: missing code | `{ discount: 10 }` | 400 | `{ error: { code: "VALIDATION_ERROR" } }` | P0 |
+| API-TC-03 | POST /api/v1/coupons | Error: duplicate code | `{ code: "EXISTING" }` | 409 | `{ error: { code: "ALREADY_EXISTS" } }` | P1 |
+| API-TC-04 | POST /api/v1/coupons | Auth: no token | `{ code, discount }` | 401 | `{ error: { code: "UNAUTHORIZED" } }` | P0 |
+| API-TC-05 | GET /api/v1/coupons | Happy: list | — | 200 | `{ data: [...], meta: { total } }` | P0 |
+| API-TC-06 | GET /api/v1/coupons | Empty: no data | — | 200 | `{ data: [], meta: { total: 0 } }` | P1 |
+| API-TC-07 | PUT /api/v1/settings/:id | Happy: update | `{ title, colors }` | 200 | `{ data: { ... } }` | P0 |
+| API-TC-08 | PUT /api/v1/settings/:id | Error: invalid color | `{ colors: { bg: "not-a-color" } }` | 400 | `{ error: { ... } }` | P1 |
+| API-TC-09 | PUT /api/v1/settings/:id | Error: wrong owner | Valid body, wrong appInstanceId | 403/404 | Error response | P0 |
+| API-TC-10 | DELETE /api/v1/coupons/:id | Happy: delete | — | 204 | — | P0 |
+| API-TC-11 | DELETE /api/v1/coupons/:id | Error: not found | Non-existent ID | 404 | `{ error: { code: "NOT_FOUND" } }` | P1 |
+| API-TC-12 | GET /api/v1/widget/:id | Happy: public | — | 200 | Widget config | P0 |
+| API-TC-13 | GET /api/v1/widget/:id | Error: not found | Wrong ID | 404 | Error | P1 |
+
+---
+
+## 3. Curl Examples
+
+### Happy path: Create coupon
+
+```bash
+curl -X POST https://localhost:5173/api/v1/coupons \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"code": "SAVE20", "discount": 20, "type": "percentage"}'
+
+# Expected: 201 Created
+# { "data": { "id": "...", "code": "SAVE20", "discount": 20 } }
+```
+
+### Validation error: Missing field
+
+```bash
+curl -X POST https://localhost:5173/api/v1/coupons \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{"discount": 10}'
+
+# Expected: 400 Bad Request
+# { "error": { "code": "VALIDATION_ERROR", "message": "...", "details": { "code": "Required" } } }
+```
+
+### Auth error: No token
+
+```bash
+curl -X POST https://localhost:5173/api/v1/coupons \
+  -H "Content-Type: application/json" \
+  -d '{"code": "SAVE20", "discount": 20}'
+
+# Expected: 401 Unauthorized
+# { "error": { "code": "UNAUTHORIZED", "message": "Authentication required" } }
+```
+
+### Not found
+
+```bash
+curl -X GET https://localhost:5173/api/v1/widget/nonexistent-id
+
+# Expected: 404 Not Found
+# { "error": { "code": "NOT_FOUND", "message": "App not found" } }
+```
+
+### Delete
+
+```bash
+curl -X DELETE https://localhost:5173/api/v1/coupons/<id> \
+  -H "Authorization: Bearer <token>"
+
+# Expected: 204 No Content (empty body)
+```
+
+---
+
+## 4. Automation Script
+
+### Vitest integration test pattern
+
+```javascript
+import { describe, it, expect } from 'vitest';
+
+describe('POST /api/v1/coupons', () => {
+  it('TC-01: creates coupon with valid data', async () => {
+    const res = await fetch(`${API_URL}/coupons`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ code: 'TEST20', discount: 20, type: 'percentage' }),
+    });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(body.data).toHaveProperty('id');
+    expect(body.data.code).toBe('TEST20');
+  });
+
+  it('TC-02: returns 400 for missing code', async () => {
+    const res = await fetch(`${API_URL}/coupons`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ discount: 10 }),
+    });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error.code).toBe('VALIDATION_ERROR');
+  });
+
+  it('TC-04: returns 401 without auth', async () => {
+    const res = await fetch(`${API_URL}/coupons`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ code: 'TEST', discount: 10 }),
+    });
+    expect(res.status).toBe(401);
+  });
+});
+```
+
+---
+
+## 5. Output Template
+
+```markdown
+# API Contract Test Report
+
+**Date:** YYYY-MM-DD
+**Tester:** Tester Agent
+**Base URL:** <API URL>
+**Contract reference:** <api-contracts.md>
+
+## Results
+
+| TC-ID | Endpoint | Scenario | Expected | Actual | Status |
+|-------|----------|----------|:--------:|:------:|:------:|
+| API-TC-01 | POST /coupons | Happy | 201 | 201 | ✅ |
+| API-TC-02 | POST /coupons | Validation | 400 | 400 | ✅ |
+| API-TC-04 | POST /coupons | No auth | 401 | 401 | ✅ |
+| API-TC-07 | PUT /settings/:id | Happy | 200 | 200 | ✅ |
+| API-TC-08 | PUT /settings/:id | Invalid | 400 | 500 | ❌ |
+
+## Error Format Check
+| Endpoint | Status Code | Has `error.code`? | Has `error.message`? | Status |
+|----------|:-----------:|:-----------------:|:--------------------:|:------:|
+| POST /coupons | 400 | ✅ | ✅ | Pass |
+| PUT /settings | 500 | ❌ | ❌ (raw stack) | ❌ Fail |
+
+## Summary
+| Status | Count |
+|--------|:-----:|
+| ✅ PASS | X |
+| ❌ FAIL | Y |
+| Total | Z |
+
+## Bugs Found
+| Bug ID | TC | Finding | Severity |
+|--------|-----|---------|----------|
+| BUG-XXX | API-TC-08 | PUT /settings returns 500 + stack for invalid input | 🔴 P0 |
+
+## Verdict
+- ✅ COMPLIANT — all endpoint tests pass
+- ⚠️ DEVIATIONS — minor contract mismatches
+- ❌ NON-COMPLIANT — critical contract violations
+```
+
+---
+
+## See also
+- `$api_contracts` — contract definitions (source of truth)
+- `$api_contract_compliance_review` — code review of implementation
+- `$qa_test_plan` — test plan (references this skill)
+- `$qa_security_smoke_tests` — security-focused API tests

package/locales/en/.agents/skills/qa_browser_testing/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: qa_browser_testing
+description: Visual E2E testing via the built-in Antigravity Browser — Pre-Auth Handoff, browser_subagent, screenshots, visual parity, evidence collection.
+last_verified: 2026-03-11
+version: 1.0
+---
+
+# Skill: Antigravity Browser Testing
+
+## Purpose
+
+Testing via **the built-in Google Antigravity browser** (`browser_subagent`).
+The main tool of the Tester agent for visual verification, UI parity, and DEMO gate.
+
+> [!IMPORTANT]
+> This skill is for **manual-automated** testing within Antigravity.
+> For CI/CD automation (spec files, pipeline) → `$qa_e2e_playwright`.
+
+---
+
+## When to use
+
+- Testing Wix Dashboard / Shopify Admin (closed environment)
+- Visual parity: comparing implementation with the design source (Stitch / Figma / HTML-ref)
+- DEMO gate: verifying DEV-xx slices
+- Quick UI regression check
+- Evidence collection (screenshots + video) for QA Report
+
+## When NOT to use
+
+- Automation in CI/CD pipeline is needed → `$qa_e2e_playwright`
+- Unit/integration testing → Vitest
+- API contract testing → `$qa_api_contract_tests`
+- Computational logic → unit tests
+
+---
+
+## Tools
+
+| Tool | What it does | When |
+|-----------|-----------|-------|
+| `browser_subagent` | Opens a page, clicks, enters text, checks UI | Main |
+| `capture_browser_screenshot` | Takes a screenshot of the current page | Every verification step |
+| `open_browser_url` | Navigates to a URL | Navigation |
+| `read_browser_page` | Reads the DOM/text of the page | Content verification |
+| `click_browser_element` | Clicks on an element | Interactive verification |
+
+> [!NOTE]
+> Every call to `browser_subagent` automatically records a `.webp` video.
+> Video = evidence for the QA report and walkthrough.
+
+---
+
+## Pre-Auth Handoff (Wix / Shopify)
+
+> **Trigger:** the user specifies **"Wix"** or **"Shopify"** when transitioning to the TEST gate.
+
+### Protocol
+
+**Step 1 — Request authorization:**
+```
+🌐 Pre-Auth Handoff: trigger [Wix/Shopify] detected.
+Please:
+1. Open the Antigravity browser
+2. Login to [Wix Dashboard / Shopify Admin]
+3. Navigate to the page that needs to be tested
+4. Write: "Browser is ready"
+```
+
+**Step 2 — User authorizes and opens the relevant page.**
+
+**Step 3 — Tester runs `browser_subagent` with strict rules:**
+- ❌ DO NOT open new URLs (only work with the current page)
+- ❌ DO NOT try to navigate to localhost
+- ✅ Take a screenshot at EVERY verification step
+- ✅ Click, toggle, verify UI
+- ✅ Record video (`.webp`) for evidence
+
+**Step 4 — Analyze screenshots and formulate findings.**
+
+### Constraints
+
+| Works ✅ | Doesn't work ❌ |
+|------------|---------------|
+| `manage.wix.com` | `localhost` |
+| `admin.shopify.com` | Self-signed SSL |
+| Any URL with a valid SSL | Wix sandbox iFrame API |
+| Auth state persists | Session expires (~24h) |
+
+---
+
+## Visual Parity via Antigravity Browser
+
+> [!IMPORTANT]
+> **Source of truth is determined by the UX Designer** (mandatory question #2 Clarification Protocol).
+> If not specified — request before verification.
+
+### Algorithm
+
+```
+1. Get reference screenshot (depends on Source of Truth):
+   (a) Stitch → get_screen() → download screenshot via browser_subagent
+   (b) Figma → user provides PNG export
+   (c) HTML-ref → open HTML file in browser_subagent → capture_screenshot
+
+2. Get actual screenshot:
+   → browser_subagent: open implementation → capture_screenshot
+
+3. Visually compare (Tester analyzes both screenshots):
+   → Structure: are elements in place?
+   → Typography: font, size, color?
+   → Spacing: do paddings/margins match?
+   → Colors: is the palette correct?
+   → States: are all implemented?
+
+4. Format finding:
+   → UX-PARITY-xx: PASS / FAIL + screenshot + description
+```
+
+### Example: Stitch as Source of Truth
+
+```
+Step 1: get_screen(projectId, screenId) → get screenshot URL
+Step 2: browser_subagent → open screenshot URL → capture_screenshot → save as reference
+Step 3: browser_subagent → open implementation (Wix Dashboard) → capture_screenshot → save as actual
+Step 4: Compare reference vs actual → record discrepancies
+```
+
+### Example: Figma as Source of Truth
+
+```
+Step 1: User provides PNG export from Figma
+Step 2: browser_subagent → open implementation → capture_screenshot
+Step 3: Compare Figma PNG vs actual screenshot
+Step 4: Format findings
+```
+
+### Example: HTML-ref as Source of Truth
+
+```
+Step 1: browser_subagent → open popup_templates/glassmorphism.html → capture_screenshot
+Step 2: browser_subagent → open implementation → capture_screenshot
+Step 3: Compare reference vs actual
+Step 4: Format findings
+```
+
+---
+
+## DEMO Gate via Browser
+
+### DEMO-xx Protocol
+
+```
+1. Get DEMO instructions from Dev (DEMO-xx)
+2. Pre-Auth (if Wix/Shopify) or open URL directly
+3. browser_subagent: execute steps from DEMO
+4. capture_screenshot at EVERY step
+5. Record: PASS/FAIL + screenshot + description
+6. Embed in walkthrough.md
+```
+
+### Evidence format
+
+```markdown
+### DEMO-01: Template Selection
+
+![Step 1: Open editor](path/to/screenshot_step1.png)
+Status: ✅ PASS — editor opened, templates loaded
+
+![Step 2: Select Glassmorphism](path/to/screenshot_step2.png)
+Status: ✅ PASS — preview updated correctly
+
+![Step 3: Save changes](path/to/screenshot_step3.png)
+Status: ❌ FAIL — toast did not appear after saving
+```
+
+---
+
+## browser_subagent Best Practices
+
+### Call rules
+
+```
+browser_subagent(
+  Task: "Detailed description of what to check and what to return",
+  TaskName: "Short descriptive name",
+  RecordingName: "lowercase_with_underscores"
+)
+```
+
+### What to include in Task
+
+- **Specific elements** to check (data-testid, text, CSS)
+- **Expected result** (what should be visible)
+- **Return condition** (when to consider the task complete)
+- **Screenshots** — exactly when to take them
+
+### Example of a good Task
+
+```
+Navigate to the Widget Design page. Verify that:
+1. Template selector shows at least 3 templates
+2. Click on "Glassmorphism" template
+3. Verify live preview updates with glassmorphism styling
+4. Take a screenshot after each step.
+Return: screenshot paths and PASS/FAIL status for each step.
+```
+
+### Example of a bad Task ❌
+
+```
+Check if the page works.
+```
+
+---
+
+## Anti-patterns
+
+- ❌ `browser_subagent` without specific steps — "check the page" is too vague
+- ❌ Opening new URLs after Pre-Auth — will lose auth state
+- ❌ Not taking screenshots — no evidence = no proof
+- ❌ Visual verification without a reference — need a baseline (Stitch/Figma/HTML)
+- ❌ Ignoring `.webp` recordings — that's ready-made evidence
+- ❌ Testing business logic via browser — use unit tests
+
+---
+
+## Artifacts (Deliverables)
+
+| Artifact | Format | Where |
+|----------|--------|-----|
+| Screenshots of steps | `.png` | Embed in walkthrough.md |
+| Video recordings | `.webp` | Embed in walkthrough.md |
+| DEMO Results | Table | In QA Report |
+| UX Parity Results | Table | In QA Report |
+| Findings | P0/P1/P2 blocks | In QA Report |
+
+---
+
+## Output (format)
+
+### Browser Test Summary
+| Step | Action | Expected | Actual | Screenshot | Status |
+|------|--------|----------|--------|------------|--------|
+| 1 | ... | ... | ... | 📸 link | PASS/FAIL |
+
+### UX Parity Results
+| UX-PARITY-xx | Screen | Source of Truth | Findings | Status |
+|--------------|--------|----------------|----------|--------|
+| ... | ... | Stitch / Figma / HTML-ref | ... | PASS/FAIL |
+
+### DEMO Results
+| DEMO-xx | Steps verified | Issues | Status |
+|---------|---------------|--------|--------|
+| ... | 5/5 | none | ✅ PASS |