@hiver/skills 1.0.1 → 1.0.2

package/collections/extension/skills/modify-extension/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: modify-extension
+description: Full command over Chrome extension top-level code in hiver-extension-v3/. Use when adding new features, modifying the script injection pipeline, fixing load sequence bugs, adding service worker commands, new iframes, new context menus, or any other change scoped to the extension layer.
+---
+
+# Build Extension V3
+
+**Scope:** All code inside `hiver-extension-v3/` — manifest, service worker, content scripts, iframes, context menus, env config, and `src/` files.
+
+**Out of scope:** The React app bundles (`gx_combined.js`, `gx_react_combined.js`, `index.js`) that get injected into Gmail. Those are built from a separate part of the codebase. This skill only owns the extension layer that loads and injects those bundles.
+
+**Never touch `chrome_extension_dev/`** — it is auto-generated from `hiver-extension-v3/` during local dev builds. All changes go into `hiver-extension-v3/` only.
+
+---
+
+## Step 1 — Understand the Task
+
+Read the task and classify it:
+
+| Task type | Primary files involved |
+|---|---|
+| New service worker message command | `service_worker.js` |
+| New context menu item | `ContextMenu.js`, `service_worker.js` |
+| New iframe | `content_scripts/iframes.js`, `manifest.json`, new `src/iframe_*.html` |
+| New content script | `manifest.json`, new file in `content_scripts/` |
+| Modify script injection pipeline | `service_worker.js`, `grexit.js` |
+| Fix load sequence bug | `grexit.js`, `content_scripts/gmail.js`, `content_scripts/utils.js` |
+| New manifest permission or resource | `manifest.json` |
+| Env-specific behavior | `env.js`, `service_worker.js` |
+
+---
+
+## Step 2 — Write Plain English Test Cases (TDD)
+
+Before writing any code, write explicit test cases:
+
+```
+TEST: [short name]
+GIVEN: [precondition / starting state]
+WHEN: [event or action that occurs]
+THEN: [expected outcome]
+```
+
+Then trace through the existing code and confirm each test currently fails. Implement. Then trace through updated code and confirm each test now passes.
+
+---
+
+## Step 3 — Read the Relevant Files
+
+Always read the files you will touch before editing.
+
+## 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 |
+|-------|------|--------------|
+| Architecture (file roles, injection pipeline, env behavior) | [references/architecture.md](references/architecture.md) | When you need to understand file relationships or the boot sequence |
+| Implementation patterns (service worker, context menu, iframe, content script, manifest, env-gating, logging) | [references/implementation-patterns.md](references/implementation-patterns.md) | When writing code for a specific task type |
+
+---
+
+## Step 4 — Check if Chrome APIs or Patterns Are Unfamiliar
+
+If the task requires a Chrome extension API that does not already exist in the codebase, **do not guess**. Use WebSearch:
+
+```
+search: "chrome extension manifest v3 <topic> site:developer.chrome.com"
+```
+
+Always prefer the Chrome Developers documentation over general web search results. Reconcile with how the existing codebase handles similar things.
+
+---
+
+## Step 5 — Implement
+
+Load the relevant reference file for the task type and follow the pattern.
+
+---
+
+## Step 6 — Verify Test Cases
+
+After implementing, trace through each test case from Step 2:
+- Identify the exact code path that satisfies the `THEN` condition
+- If any test still fails, fix before closing the task
+
+---
+
+## Hard Rules — Never Violate
+
+1. **Script load order in manifest is fixed** — `hiver-logger.js` → (performanceLogger, utils, gmail, iframes) → `grexit.js`. Wrong order = silent runtime failure.
+2. **No import/export in content scripts** — Only `service_worker.js` and files it imports are ES modules.
+3. **Always return true for async message handlers** — If `sendResponse` is called inside `.then()` or after `await`, the `case` block must `return true`.
+4. **New DOM manipulation needs trusted types** — Route through `src/trusted-type-policy.js`.
+5. **Use reloadUntil for critical boot failures** — Add entry to `reloadKeys` with unique key and `maxCount: 5`.
+6. **Log all significant pipeline stages** — New boot steps must call `postMessageToLogger` on both success and failure.
+
+---
+
+## Checklist
+
+- [ ] Relevant files read before editing
+- [ ] Plain English test cases written before implementation
+- [ ] Implementation follows the correct pattern for the task type
+- [ ] Script load order in `manifest.json` is correct (if manifest was changed)
+- [ ] `return true` present for any new async message handler
+- [ ] New files under `src/` are covered by `web_accessible_resources`
+- [ ] New chrome API usage has corresponding permission in manifest
+- [ ] Env-gating done correctly (not using `import` in content scripts)
+- [ ] Each test case traced through updated code and confirmed passing

package/collections/extension/skills/modify-extension/references/architecture.md

@@ -0,0 +1,55 @@
+# Extension Architecture Reference
+
+## File Roles and Module Types
+
+| File | Role | Module type |
+|---|---|---|
+| `manifest.json` | Permissions, content script order, web_accessible_resources | — |
+| `service_worker.js` | Message hub, script/CSS injection, update lifecycle | **ES module** |
+| `grexit.js` | Gmail boot orchestrator — runs the full load sequence | **NOT a module** (uses globals) |
+| `hiver-logger.js` | Constants + `HiverLogger` class — must load before `grexit.js` | **NOT a module** |
+| `customClasses.js` | `CustomFetchError` | ES module (imported by `service_worker.js`) |
+| `ContextMenu.js` | Context menu creation + click handling | ES module (imported by `service_worker.js`) |
+| `env.js` | Production env: `HIVER_V2_HOST`, `HIVER_SELECTORS_API_URL`, `APP_ENV = 'production'` | ES module |
+| `env.dev.js` | Dev env overrides (same exports, different values) | ES module |
+| `content_scripts/utils.js` | `autoRetry`, `waitUntil`, `reloadUntil`, `getDebugEnabled` | Global |
+| `content_scripts/gmail.js` | `waitForGmailToLoadNew`, `waitForGmailInitialization` | Global |
+| `content_scripts/iframes.js` | `injectExtensionIframes` — injects 7 iframes | Global |
+| `content_scripts/flowTracer.js` | Flow tracing (runs in MAIN world at document_start) | Global |
+| `content_scripts/performanceLogger.js` | Performance logging helpers | Global |
+| `src/selectors.js` | Resolves Gmail DOM selectors from `localStorage('selectors')` | Injected via `chrome.scripting` |
+| `src/trusted-type-policy.js` | CSP Trusted Types policy setup | Injected via `chrome.scripting` |
+| `src/iframe_*.html` | Individual iframe pages (editor, chat, analytics, gainsight, video, loggly) | Standalone |
+| `src/iframe_*_handler.js` | Handlers loaded inside each iframe | Global (in iframe context) |
+
+## Script Injection Pipeline
+
+```
+grexit.js boots in Gmail tab
+  │
+  ├─ [1] injectTrustedTypePolicy()
+  │       → sends "injectTrustedTypePolicy" → service_worker executes src/trusted-type-policy.js
+  │
+  ├─ [2] autoRetry(setupExtensionMetaDataGlobals)
+  │       → sends "setupExtensionMetaDataGlobals" → service_worker injects version/id globals
+  │
+  ├─ [3] initializeHiverExtension() [IIFE]
+  │       → sends "fetchSelectorsAndApplicationVersions"
+  │       → service_worker fetches in parallel:
+  │             gmailSelectors API → stored in localStorage('selectors')
+  │             runtimeBundleVersion API → extensionUiVersion, channelsUiVersion, featureFlags
+  │
+  ├─ [4] → sends "injectHiverSelectorScript" → service_worker executes src/selectors.js
+  │
+  ├─ [5] → sends "injectAppScripts" → service_worker executes:
+  │             gx_combined.js + gx_react_combined.js + index.js
+  │
+  └─ [6] injectExtensionIframes() → 7 hidden iframes injected into Gmail DOM
+```
+
+## Environment Behavior
+
+| `APP_ENV` | Script paths | CSS injection | Update checks |
+|---|---|---|---|
+| `'production'` | Fetched from `runtimeBundleVersion` API | No | Yes |
+| anything else | `build/latest/*.js` (local) | Yes (`insertAppCSSOnBuddyEnvironment`) | No |

package/collections/extension/skills/modify-extension/references/implementation-patterns.md

@@ -0,0 +1,180 @@
+# Extension Implementation Patterns
+
+## Adding a new service worker message command
+
+Add a case inside the `onMessage` switch in `service_worker.js`:
+
+```js
+// async command — must return true
+case 'myNewCommand_1':
+    myAsyncOperation(request.someArg).then(sendResponse);
+    return true; // required — keeps the message port open until sendResponse fires
+
+// sync command
+case 'myNewCommand_2':
+    sendResponse(someValue);
+    break;
+```
+
+Send from a content script:
+```js
+chrome.runtime.sendMessage({ command: 'myNewCommand_1', someArg: value }, ({ success, data, error }) => {
+    if (!success) { /* handle error */ }
+    // use data
+});
+```
+
+---
+
+## Adding a new context menu item
+
+In `ContextMenu.js`, add inside `createContextMenu()`:
+```js
+chrome.contextMenus.create({
+    id: 'myNewItem',
+    title: 'My New Action',
+    contexts: ['page'],
+    documentUrlPatterns: ['*://mail.google.com/*']
+});
+```
+
+Add a handler function:
+```js
+const handleMyNewItem = async (tabId) => {
+    try {
+        chrome.tabs.sendMessage(tabId, {
+            type: 'CONTEXT_MENU_WORKER_EVENT',
+            payload: { type: 'MY_NEW_ACTION' }
+        });
+    } catch (err) {
+        console.log('== FAILED TO HANDLE MY_NEW_ACTION ==', err);
+    }
+};
+```
+
+Wire it in `handleContextMenuClick`:
+```js
+if (info.menuItemId === 'myNewItem') {
+    await handleMyNewItem(tab.id);
+}
+```
+
+---
+
+## Adding a new iframe
+
+In `content_scripts/iframes.js`, add inside `injectExtensionIframes()` following the existing pattern:
+```js
+const iframe_myfeature_id = 'Hiver_iframe_myfeature';
+let iframe_myfeature = doc.getElementById(iframe_myfeature_id);
+if (!iframe_myfeature) {
+    injectIframe({
+        id: iframe_myfeature_id,
+        src: chrome.runtime.getURL('src/iframe_myfeature.html'),
+        style: 'display:none;border:none;',
+        body
+    });
+}
+```
+
+Then create `src/iframe_myfeature.html`. The existing `"src/*"` wildcard in `web_accessible_resources` already covers it — verify it does before adding a new entry.
+
+---
+
+## Adding a new content script (shared globals)
+
+Create the file in `content_scripts/`. Add it to `manifest.json` at the **correct position** in the `js` array:
+
+```json
+"js": [
+    "hiver-logger.js",
+    "src/trusted-type-policy.js",
+    "content_scripts/performanceLogger.js",
+    "content_scripts/utils.js",
+    "content_scripts/gmail.js",
+    "content_scripts/iframes.js",
+    "content_scripts/myNewScript.js",
+    "grexit.js"
+]
+```
+
+Rules:
+- If your script defines globals that other scripts consume → place it **before** those scripts
+- If your script uses globals from `hiver-logger.js` → place it **after** `hiver-logger.js`
+- `grexit.js` is always **last**
+- Do **not** use `import`/`export` — content scripts are not ES modules
+
+---
+
+## Adding a file injected via chrome.scripting
+
+Create the file in `src/`. Inject it from `service_worker.js`:
+```js
+function executeScripts(tabId, files, executionWorld = 'MAIN') {
+    return chrome.scripting.executeScript({ target: { tabId }, files, world: executionWorld });
+}
+
+// usage
+executeScripts(tabId, ['src/myfile.js']); // runs in MAIN world by default
+```
+
+Check `web_accessible_resources` in `manifest.json`. The existing wildcard `"src/*"` covers any new file under `src/`.
+
+---
+
+## Adding a new manifest permission
+
+```json
+"permissions": ["scripting", "contextMenus", "myNewPermission"]
+```
+
+For host permissions:
+```json
+"host_permissions": ["*://mail.google.com/*", "*://mynewhost.com/*"]
+```
+
+---
+
+## Env-gating new behavior
+
+In `service_worker.js` (ES module — `APP_ENV` is importable):
+```js
+import { APP_ENV } from './env.js';
+
+if (APP_ENV !== 'production') {
+    // dev-only behavior
+}
+```
+
+In content scripts (`APP_ENV` is not importable). Pass it through a service worker message response or inject it as a global via `executeFunction`:
+```js
+function setMyEnvGlobal(appEnv) {
+    window.MY_APP_ENV = appEnv;
+}
+// in service_worker.js handler:
+executeFunction({ tabId, functionToExecute: setMyEnvGlobal, args: [APP_ENV] });
+```
+
+---
+
+## Adding a new log stage in the boot sequence
+
+```js
+const currentStage = 'myNewStage';
+const { duration, stageDuration } = getStageDetails(currentStage);
+postMessageToLogger({
+    message: 'Description of what happened',
+    stage: currentStage,
+    duration,
+    stageDuration,
+    level: LOG_LEVELS.DEBUG, // or LOG_LEVELS.ERROR
+});
+```
+
+For failures, add a `LOG_MESSAGES` constant in `hiver-logger.js`:
+```js
+const LOG_MESSAGES = {
+    // existing...
+    MY_NEW_FAILURE: 'My new thing failed to initialize',
+};
+```

package/collections/extension/skills/scaffold-react-feature/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: scaffold-react-feature
+description: Generate standard feature folder structure, wiring, and feature flag boilerplate for new features. Internal skill — used by build-milestone agent, not invoked directly by users.
+---
+
+# Scaffold Feature
+
+**Trigger:** Only when building a **new feature or new component**. Do NOT use for bug fixes or issue fixes.
+
+**Used by:** `build-milestone` agent internally. Not invoked directly by users.
+
+---
+
+## Step 1 — Determine Mount Type
+
+Ask (or infer from agent context / milestone doc):
+
+> **Is this feature mounted via Backbone or pure React?**
+
+- **Backbone mount** → the feature is rendered inside a Backbone view using `ReactBackboneModules`
+- **React-only** → the feature is lazy-imported and rendered directly in `react-extn/src/index.js`
+
+---
+
+## Step 2 — Create Folder Structure
+
+Create the following under `react-extn/src/<FeatureName>/`:
+
+```
+<FeatureName>/
+  index.js          ← main React component export
+  hooks/            ← custom hooks (data, state, business logic)
+  constants/
+    queries.js      ← React Query query/mutation keys
+    index.js        ← other constants (strings, enums, config)
+  components/       ← sub-components
+  utils.js          ← pure utility functions
+  mounter.js        ← ONLY if Backbone-mounted (see Step 3a)
+```
+
+---
+
+## Step 3a — Backbone Mount Wiring
+
+### Create `mounter.js`
+
+```js
+import ReactDOM from 'react-dom/client';
+import { HiverProvider } from '@hiver/hiver-ui-kit';
+import { Provider } from 'react-redux';
+import HiverQueryClientProvider from '../reactQueryClient.js';
+import MyFeature from './index.js';
+
+export const mountMyFeature = (store) => (container, props) => {
+    const root = ReactDOM.createRoot(container);
+    root.render(
+        <HiverProvider custom>
+            <HiverQueryClientProvider>
+                <Provider store={store}>
+                    <MyFeature {...props} />
+                </Provider>
+            </HiverQueryClientProvider>
+        </HiverProvider>
+    );
+    return root.unmount.bind(root);
+};
+```
+
+Replace `MyFeature` / `mountMyFeature` with the actual feature name.
+
+### Register in `ReactBackboneModules/index.js`
+
+1. Add the import at the top:
+   ```js
+   import { mountMyFeature } from '../MyFeature/mounter';
+   ```
+2. Inside `appendReactBackboneModules()`, add:
+   ```js
+   myFeature: createModule(mountMyFeature(store)),
+   ```
+
+Use camelCase for the module key (e.g., `myFeature`).
+
+---
+
+## Step 3b — React-only Wiring
+
+### Add lazy import in the file where the component is consumed
+
+Do **not** default to `react-extn/src/index.js`. Add the lazy import in whichever file actually renders this component (e.g., a parent page, a layout component, or a route file).
+
+```js
+const LazyMyFeature = React.lazy(() => import('./MyFeature' /* webpackChunkName: "my_feature" */))
+```
+
+- Use `PascalCase` for the variable name prefixed with `Lazy`
+- Use `snake_case` for `webpackChunkName`
+- Render `<LazyMyFeature />` at the correct place in that file, wrapped in `<React.Suspense>` if not already present
+
+---
+
+## Step 4 — Feature Flag Boilerplate (if needed)
+
+If the milestone requires a feature flag:
+
+### Naming convention
+Use the `rls-` prefix: e.g., `rls-my-feature-name`
+
+### Add key to `react-extn/src/utils/constants.js`
+
+Find the `featureKeys` object and add:
+```js
+myFeatureName: 'rls-my-feature-name',
+```
+
+### Add checker function to `react-extn/src/utils/features.js`
+
+```js
+export const isMyFeatureEnabled = (availableFeatures) =>
+    isFeatureActive(availableFeatures, featureKeys.myFeatureName);
+```
+
+### Gate the feature render
+
+Use `availableFeatures` from Redux and the checker function to conditionally render:
+```js
+const availableFeatures = useSelector(state => state.availableFeatures);
+if (!isMyFeatureEnabled(availableFeatures)) return null;
+```
+
+---
+
+## Checklist (confirm before handing off to build-component)
+
+- [ ] Folder structure created under `react-extn/src/<FeatureName>/`
+- [ ] Mount type determined: Backbone / React-only
+- [ ] `mounter.js` created and registered in `ReactBackboneModules/index.js` (Backbone only)
+- [ ] Lazy import added in the correct consumer file (React-only, not necessarily the root `index.js`)
+- [ ] Feature flag key added to `constants.js` (if needed)
+- [ ] Feature flag checker added to `features.js` (if needed)
+- [ ] Feature is gated behind the flag in the component (if needed)

package/collections/extension/skills/write-test-cases/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: write-test-cases
+description: Writes structured behavioural test cases for a milestone into a progress-sheet markdown file. Invoked by build-milestone before any implementation begins (Normal Mode) or once per feedback round (Fix Mode). Never writes source code.
+---
+
+# Write Test Cases
+
+Generates a complete set of structured behavioural test cases for a milestone and saves them as a progress sheet that `build-milestone` uses to drive its TDD loop.
+
+## When to Use
+
+- Invoked by `build-milestone` at the start of **Normal Mode** — before any implementation begins
+- Invoked by `build-milestone` at the start of **Fix Mode** — once per feedback round, scoped to the feedback
+
+## Inputs
+
+- Path to the milestone document (always required)
+- Mode: `normal` or `feedback`
+- If `feedback` mode: path to the feedback file
+
+## Instructions
+
+### Normal Mode
+
+1. Read the milestone document thoroughly. Extract:
+   - Goal
+   - Acceptance criteria (2–3 product-level "done" conditions)
+   - Architectural approach and high-level areas affected
+
+2. Explore the codebase **scoped strictly to the "High-level areas affected" section of the milestone doc**. Read only the files and directories explicitly named there. Do NOT fan out to unrelated modules. Limit reads to what is minimally needed to understand current state — what exists, what doesn't, what will change.
+
+3. If the milestone doc contains Figma design links, load them using the Figma MCP tool. Analyze the designs to identify UI-specific behaviours and edge cases. Load only the specific nodes linked — do not traverse the full Figma file.
+
+4. Derive test cases from the acceptance criteria and your codebase exploration. For each observable behaviour the milestone introduces or changes, write one test case. Aim for full coverage across:
+   - Happy path (primary user flows)
+   - Edge cases (boundary conditions, empty states, large data)
+   - Error states (API failures, invalid input, permission issues)
+   - Regressions (existing behaviours that must not break)
+
+5. Write ALL test cases to `milestone-tests/<milestone-name>-tests.md` — create the file if it doesn't exist. All test cases start with `⬜ Pending` status.
+
+6. Use this format for every test case:
+
+```markdown
+## TC-001 | Category: happy-path | ⬜ Pending
+Given: <system or state precondition>
+When:  <user action or system trigger>
+Then:  <observable outcome — what the user sees or what changes in state>
+```
+
+7. After writing all test cases, exit. Do not write any source code.
+
+---
+
+### Feedback Mode
+
+1. Read the milestone document to understand the original scope.
+
+2. Read the feedback file. Identify the **active** (non-stale) feedback entry.
+
+3. Explore the codebase to understand the current state of the implementation for this milestone.
+
+4. Derive test cases scoped **only** to what the feedback describes. Write as many as needed to fully cover the feedback — happy path, edge cases, and regressions relevant to the fix.
+
+5. Append the new test cases to the existing `milestone-tests/<milestone-name>-tests.md` under a new section:
+
+```markdown
+## Feedback Round N
+
+### FTC-001 | Category: regression | ⬜ Pending
+Given: <precondition>
+When:  <action>
+Then:  <expected outcome>
+```
+
+Where `N` is incremented from the last existing Feedback Round number in the file.
+
+6. After appending, exit. Do not write any source code.
+
+---
+
+## Output
+
+A `milestone-tests/<milestone-name>-tests.md` file (created or appended) with all new test cases set to `⬜ Pending`.
+
+The `milestone-tests/` directory lives alongside the `milestones/` directory under the same parent.
+
+## Rules
+
+- NEVER write source code
+- NEVER mark any test case as passing — all new TCs start as `⬜ Pending`
+- NEVER modify existing test case entries — only append new ones
+- In Feedback Mode, only write TCs scoped to the active feedback — do not add unrelated cases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hiver/skills",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Shared Claude Code skills & agents for Hiver teams",
   "type": "module",
   "bin": {