feat(icp-cli): add instructions for running parallel pocket-ics in wo…

evaluations/icp-cli.json

@@ -210,6 +210,17 @@
         "Does NOT suggest killing processes manually or using dfx commands"
       ]
     },
+    {
+      "name": "Parallel local networks across git worktrees",
+      "prompt": "I'm running two agents on the same icp-cli project in separate git worktrees, and both need a local network running at the same time. Starting the second fails with a port conflict on 8000. How do I run both at once? Just the icp.yaml config and the command to find each network's port — no deploy steps.",
+      "expected_behaviors": [
+        "Sets gateway.port to 0 in the managed local network config so the OS assigns a free ephemeral port per worktree",
+        "Explains that local networks are project-local, so each worktree runs its own independent network",
+        "Uses 'icp network status --json' (reading gateway_url or api_url) to look up each network's actual assigned port",
+        "Does NOT invent a non-existent command such as 'icp network config'",
+        "Does NOT hardcode localhost:8000 or tell the user to stop one of the networks"
+      ]
+    },
     {
       "name": "Scripted project creation in CI",
       "prompt": "What is the correct icp new command to scaffold a Rust project non-interactively in CI? Just the command, no deploy steps.",

skills/icp-cli/SKILL.md

@@ -197,6 +197,7 @@ ic-wasm --version
     ```bash
     icp network stop --project-root-override /path/to/other-project
     ```
+    To run both networks at once instead of stopping one — e.g. parallel git worktrees — set `gateway.port: 0` so each gets a free port. See "Parallel local networks (git worktrees)" under How It Works.
 
     **Scenario B — a non-icp service holds the port.** Configure an alternate port in `icp.yaml` and read the actual URLs dynamically via `icp network status --json` rather than hardcoding localhost:8000:
     ```yaml
@@ -289,6 +290,32 @@ environments:
         freezing_threshold: 7776000
 ```
 
+### Parallel local networks (git worktrees)
+
+Local networks are project-local — keyed by project root (Pitfall 9). Separate git worktrees of the same repo are separate project roots, so each worktree can run its own independent local network. This lets multiple agents or branches build and deploy in parallel without interfering. The only obstacle is the gateway port: every worktree defaults to `8000`, so the second `icp network start` fails with a port conflict.
+
+Set the managed network's gateway port to `0` so the OS assigns a free ephemeral port per worktree:
+
+```yaml
+networks:
+  - name: local
+    mode: managed
+    gateway:
+      port: 0   # 0 = OS picks a free port — avoids collisions across worktrees
+```
+
+`icp network start -d` prints the chosen port (`Network started on port 58157`). To recover it afterward — for tests, scripts, or another agent — query the running network and read `gateway_url`:
+
+```bash
+icp network start -d
+icp network status --json
+# -> { "managed": true, "api_url": "http://localhost:58157/", "gateway_url": "http://localhost:58157/", ... }
+
+icp network status --json | jq -r '.gateway_url'   # http://localhost:58157/
+```
+
+Never hardcode `localhost:8000` when using `port: 0` — the port changes on every start, so read `gateway_url` (or `api_url`) from `icp network status --json` each time. To target a specific worktree's network from outside its directory, pass the global `--project-root-override <path>` flag (e.g. `icp network status --json --project-root-override /path/to/worktree`).
+
 ### Install Modes
 
 ```bash