stef-openclaw-skills/docs/plans/2026-03-11-nordvpn-client.md

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:

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:

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:

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