# NordVPN Client Skill Implementation Plan

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

**Goal:** Build a cross-platform `nordvpn-client` skill for macOS and Linux that can install/bootstrap NordVPN, log in, connect to a target country or city, verify the VPN session, disconnect, and report status.

**Architecture:** Implement one skill with one script entrypoint and platform-specific backends. Linux uses the official NordVPN CLI. macOS uses a CLI path when present and otherwise falls back to the NordVPN app workflow. The skill manages VPN state only, leaving follow-up operations like `web-automation` to separate agent steps.

**Tech Stack:** Node.js, shell/OS commands, NordVPN CLI/app integration, OpenClaw skills, 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/nordvpn-client -b feature/nordvpn-client
```

**Step 2: Verify baseline**

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

### Task 2: Create the local skill runtime

**Files:**
- Create: `skills/nordvpn-client/SKILL.md`
- Create: `skills/nordvpn-client/scripts/nordvpn-client.js`
- Optional Create: helper files under `skills/nordvpn-client/scripts/`

**Step 1: Write the failing checks**
- Missing command/action should fail with clear usage output
- Unsupported platform should fail clearly

**Step 2: Implement platform detection and install probe**
- detect `darwin` vs `linux`
- detect whether NordVPN CLI/app is already present
- expose `status` with install/auth/connect fields

### Task 3: Implement install and auth bootstrap

**Files:**
- Modify: `skills/nordvpn-client/scripts/nordvpn-client.js`

**Step 1: Linux install/login path**
- implement official CLI probe/install path
- implement token-based login path

**Step 2: macOS install/login path**
- probe CLI first
- if absent, probe/install NordVPN app path
- implement login/bootstrap state verification for the app workflow

**Step 3: Keep secrets external**
- env vars or local credential path only
- no raw secrets in docs or skill text

### Task 4: Implement connect/disconnect/status/verification

**Files:**
- Modify: `skills/nordvpn-client/scripts/nordvpn-client.js`

**Step 1: Connect**
- support `--country` and `--city`
- normalize target handling per platform

**Step 2: Verify**
- report local connection state
- run public IP / geolocation verification
- fail if connection target cannot be reasonably verified

**Step 3: Disconnect and status**
- implement clean disconnect
- ensure `status` emits machine-readable output for agent use

### Task 5: Validate locally in OpenClaw workspace

**Files:**
- Test: local workspace copy of `nordvpn-client`

**Step 1: Direct command validation**
- usage errors are correct
- install probe works on this host
- status output is coherent before login/connect

**Step 2: One real connect flow**
- connect to a test country/city if credentials are available
- verify local state + external IP/location
- disconnect cleanly

### Task 6: Promote to repo docs and publish

**Files:**
- Modify: `README.md`
- Modify: `docs/README.md`
- Create: `docs/nordvpn-client.md`
- Create/Modify: `skills/nordvpn-client/...`

**Step 1: Document the skill**
- install/bootstrap behavior
- auth expectations
- connect/disconnect/status commands
- macOS vs Linux notes

**Step 2: Commit and push**

Run:
```bash
git add skills/nordvpn-client docs README.md
git commit -m "feat: add nordvpn client skill"
git push -u origin feature/nordvpn-client
```

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