# Web Automation CloakBrowser Migration Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Replace Camoufox and direct Chromium launches in `web-automation` with CloakBrowser and publish the updated repo/docs.

**Architecture:** Use a single CloakBrowser-backed launch path in `skills/web-automation/scripts/browse.ts`, migrate `extract.js` to the same backend, update dependent scripts and tests, then update docs and publish the repo changes.

**Tech Stack:** Node.js, TypeScript, JavaScript, Playwright-compatible browser automation, CloakBrowser, git

---

### Task 1: Create isolated worktree

**Files:**
- Modify: repo git metadata only

**Step 1: Create worktree**

Run:
```bash
git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills worktree add /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser -b feature/web-automation-cloakbrowser
```

**Step 2: Verify baseline**

Run:
```bash
git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser status --short --branch
```
Expected: clean feature branch

### Task 2: Migrate the browser launcher

**Files:**
- Modify: `skills/web-automation/scripts/browse.ts`
- Modify: `skills/web-automation/scripts/package.json`
- Modify: `skills/web-automation/scripts/pnpm-lock.yaml`
- Optional Modify: test helper scripts under `skills/web-automation/scripts/`

**Step 1: Write the failing verification**

Run:
```bash
cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser/skills/web-automation/scripts && node -e "require.resolve('cloakbrowser/package.json')"
```
Expected: fail before dependency migration

**Step 2: Replace backend dependency**
- remove `camoufox-js`
- add `cloakbrowser`
- update `browse.ts` to launch CloakBrowser contexts
- preserve persistent profile support

**Step 3: Verify launcher wiring**

Run a direct browse smoke test after install/update.

### Task 3: Migrate dependent scripts

**Files:**
- Modify: `skills/web-automation/scripts/extract.js`
- Modify: `skills/web-automation/scripts/auth.ts`
- Modify: `skills/web-automation/scripts/flow.ts`
- Modify: `skills/web-automation/scripts/scrape.ts`
- Modify: `skills/web-automation/scripts/test-minimal.ts`
- Modify: `skills/web-automation/scripts/test-full.ts`
- Modify: `skills/web-automation/scripts/test-profile.ts`

**Step 1: Keep interfaces stable**
- preserve CLI usage where possible
- use CloakBrowser through shared launcher code
- keep one-shot extraction JSON output unchanged except for backend wording if needed

**Step 2: Add compatibility aliases**
- support old `CAMOUFOX_*` env vars where practical
- document new canonical naming

### Task 4: Verify behavior

**Files:**
- Test: `skills/web-automation/scripts/*`

**Step 1: Extractor error checks**

Run:
```bash
cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser && node skills/web-automation/scripts/extract.js
```
Expected: JSON error for missing URL

Run:
```bash
cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser && node skills/web-automation/scripts/extract.js ftp://example.com
```
Expected: JSON error for invalid scheme

**Step 2: Extractor smoke test**

Run:
```bash
cd /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/web-automation-cloakbrowser && node skills/web-automation/scripts/extract.js https://example.com
```
Expected: JSON result with title `Example Domain` and status `200`

**Step 3: Stateful path verification**
- run one direct `browse.ts`, `scrape.ts`, or `flow.ts` command using the CloakBrowser backend
- confirm persistent-context code still initializes successfully

### Task 5: Update docs and publish

**Files:**
- Modify: `skills/web-automation/SKILL.md`
- Modify: `docs/web-automation.md`
- Modify: `README.md`
- Modify: `docs/README.md`

**Step 1: Update docs**
- replace Camoufox wording with CloakBrowser wording
- replace old setup/install steps
- document any compatibility env vars and new canonical names

**Step 2: Commit and push**

Run:
```bash
git add skills/web-automation docs README.md
git commit -m "refactor: migrate web-automation to cloakbrowser"
git push -u origin feature/web-automation-cloakbrowser
```

**Step 3: Merge and cleanup**
- fast-forward or merge to `main`
- push `main`
- remove the worktree
- delete the feature branch