prizmkit 1.1.108 → 1.1.109

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -79,7 +79,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 ## Subagent Timeout Recovery
 
 If any agent times out:
-1. `ls .prizmkit/specs/{{FEATURE_SLUG}}/` — check what exists
+1. `{{RUNTIME_HELPER_CMD}} artifact list .prizmkit/specs/{{FEATURE_SLUG}}` — check what exists
 2. If `context-snapshot.md` exists: open recovery prompt with `"Read .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md for project context and any Implementation Log/Review Notes from previous agents. Run git diff HEAD to see actual code changes already made. Do NOT re-read individual source files unless the File Manifest directs you to."` + only remaining steps + `model: "lite"`
 3. Max 2 retries per phase. After 2 failures, orchestrator completes the work directly and appends a Recovery Note to context-snapshot.md.
 
@@ -90,7 +90,7 @@ If any agent times out:
 {{IF_INIT_NEEDED}}
 ### Phase 0: Project Bootstrap
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
-- Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
+- Run `{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 - **CP-0**: Verify `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json` exist
 {{END_IF_INIT_NEEDED}}
 {{IF_INIT_DONE}}
@@ -98,14 +98,14 @@ If any agent times out:
 ### Step 1: Initialize
 
 1. Run init script:
-   `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
+   `{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 
 2. Check for existing artifacts:
-   `ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null`
+   `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}`
 
 {{IF_FRESH_START}}
 ```bash
-python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}
+{{PYTHON_CMD}} {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}
 ```
 {{END_IF_FRESH_START}}
 
@@ -113,7 +113,7 @@ python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEAT
 
 Check existing artifacts first:
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 - Both (spec.md, plan.md) exist → **SKIP to CP-1**
@@ -132,11 +132,11 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 **Step A — Build Context Snapshot** (skip if `context-snapshot.md` already exists):
 
 1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 prizm docs
-2. Detect source code directories: read KEY_FILES and STRUCTURE sections from `root.prizm` to identify where source code lives (e.g. `src/`, `app/`, `lib/`, `cmd/`, `packages/`, or project root). If `root.prizm` is missing, scan the project tree:
+2. Detect source code directories from KEY_FILES and STRUCTURE sections in `root.prizm`; if root docs are unavailable, use the helper to list likely source files:
    ```bash
-   find . -maxdepth 2 -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.rs" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/vendor/*' | head -30
+   {{RUNTIME_HELPER_CMD}} artifact source-files . --json
    ```
-   Identify the top-level source directories from the results.
+   Identify the top-level source directories from the helper output.
 3. Scan the detected source directories for files related to this feature; read each one
 4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description (2-3 lines) + acceptance criteria (copy from above)
@@ -155,14 +155,15 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 
      ### Known TRAPS (from .prizmkit/prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
-4. Confirm: `ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
+4. Confirm: `{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
 **After Step A**: Use context-snapshot.md Section 4 File Manifest to guide targeted file reads. Do NOT scan directories or read unrelated files.
 
 **Step B — Planning Artifacts** (generate only missing files):
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/spec.md .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/spec.md
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
 - spec.md missing: Run `/prizmkit-plan` → generate spec.md. Resolve uncertain requirements from the feature description, existing code, and conservative existing-project patterns.
@@ -202,7 +203,7 @@ Wait for Reviewer to return.
 
 **Guard**: Verify critic agent file exists before spawning:
 ```bash
-ls {{CRITIC_SUBAGENT_PATH}} 2>/dev/null && echo "CRITIC:READY" || echo "CRITIC:MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists {{CRITIC_SUBAGENT_PATH}} --exists-marker CRITIC:READY --missing-marker CRITIC:MISSING
 ```
 If CRITIC:MISSING — skip Phase 3.5 entirely and proceed to Phase 4. Log: "Critic agent not installed — skipping Plan Challenge."
 
@@ -308,7 +309,7 @@ The skill runs an internal review-fix loop (Reviewer Agent → filter → orches
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```bash
-grep -q "## Verdict" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.
@@ -328,8 +329,8 @@ Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLU
 
 Before invoking the skill, create a current-run marker so stale reports are ignored:
 ```bash
-mkdir -p .prizmkit/specs/{{FEATURE_SLUG}}
-touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/specs/{{FEATURE_SLUG}}
+{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
 ```
 
 Gate requirements:
@@ -360,13 +361,13 @@ You MUST execute this phase. Do NOT skip it.
 
 0a. Check if `playwright-cli` is installed:
 ```bash
-which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
 ```
 If output is `NOT_INSTALLED`, install it:
 ```bash
 npm install -g @playwright/cli@latest
 ```
-Then verify installation succeeded: `playwright-cli --version`. If installation fails, log `## Browser Verification: SKIPPED — playwright-cli installation failed` in context-snapshot.md and proceed to the next phase.
+Then verify installation succeeded: `{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version`. If installation fails, log `## Browser Verification: SKIPPED — playwright-cli installation failed` in context-snapshot.md and proceed to the next phase.
 
 0b. Learn playwright-cli usage (run once per session):
 ```bash
@@ -375,21 +376,9 @@ playwright-cli --help
 
 0c. Check if playwright-cli skill is installed for the current AI platform:
 ```bash
-CURRENT_PLATFORM=""
-if which claude >/dev/null 2>&1; then
-  CURRENT_PLATFORM="claude"; SKILL_DIR="$HOME/.claude/skills"
-elif which cbc >/dev/null 2>&1; then
-  CURRENT_PLATFORM="codebuddy"; SKILL_DIR="$HOME/.cbc/skills"
-else
-  CURRENT_PLATFORM="unknown"
-fi
-if [ -d "$SKILL_DIR/playwright-cli" ] || ls "$SKILL_DIR"/playwright* 2>/dev/null | grep -q .; then
-  echo "SKILL_EXISTS"
-else
-  echo "SKILL_MISSING"
-fi
+{{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
 ```
-If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy installed skill from `$HOME/.claude/skills/playwright-cli` to `$SKILL_DIR/playwright-cli`.
+If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy installed skill from `$HOME/.claude/skills/playwright-cli` to the path shown by the helper output for the current platform.
 
 0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
 
@@ -398,28 +387,16 @@ If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform i
 You know this project's tech stack. Detect and start the dev server yourself:
 
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
-   ```bash
-   DEV_PORT={{DEV_PORT}}
-   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
-     if [ -z "$DEV_PORT" ]; then
-       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
-     fi
-     DEV_PORT=${DEV_PORT:-3000}
-   fi
-   echo "Detected DEV_PORT=$DEV_PORT"
-   ```
+2. Determine the dev server port from the pre-detected pipeline value (`{{DEV_PORT}}`) or project config. Do NOT hardcode or guess the port. Record it as `DEV_PORT` in your notes.
 3. Verify the port is available:
    ```bash
-   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   {{RUNTIME_HELPER_CMD}} port check $DEV_PORT
    ```
 4. Start the dev server in background, capture PID:
    ```bash
-   <start-command> &
-   DEV_SERVER_PID=$!
+   {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
    ```
-5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:$DEV_PORT --timeout 30 --interval 2`
 6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
 7. If the page requires authentication, use playwright-cli to register a test user and log in first
 
@@ -433,8 +410,8 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
 1. Close the playwright-cli browser: `playwright-cli close`
-2. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. Kill the dev server process: `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
+3. Verify port is released: `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
 {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
 {{IF_BROWSER_TOOL_OPENCLI}}
 **Using: opencli** (reuses Chrome logged-in sessions)
@@ -447,45 +424,42 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
 
 0a. Check if `opencli` is installed:
 ```bash
-which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version
 ```
 If `NOT_INSTALLED`: `npm install -g @jackwener/opencli@latest`. If installation fails, log `## Browser Verification: SKIPPED — opencli installation failed` and proceed.
 
 0b. Verify Browser Bridge: `opencli doctor`. If fails, log skip and proceed.
 
-0c. Learn usage: `opencli browser --help 2>/dev/null || opencli --help`
+0c. Learn usage: `opencli browser --help`
 
-**Step 1 — Start Dev Server**: (same port detection as playwright path)
-```bash
-DEV_PORT={{DEV_PORT}}
-if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-  DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')" 2>/dev/null)
-  DEV_PORT=${DEV_PORT:-3000}
-fi
-```
-Start server, wait for ready, then: `opencli browser open http://localhost:$DEV_PORT && opencli browser state`
+**Step 1 — Start Dev Server**:
+1. Determine `DEV_PORT` from the pipeline value (`{{DEV_PORT}}`) or project config; do not guess.
+2. Verify port available: `{{RUNTIME_HELPER_CMD}} port check <DEV_PORT>`
+3. Start server: `{{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>`
+4. Wait for ready: `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:<DEV_PORT> --timeout 30 --interval 2`
+5. Open: `opencli browser open http://localhost:<DEV_PORT>`; then inspect: `opencli browser state`
 
 **Step 2 — Verification**:
 
 Use `opencli browser state` to discover elements with `[N]` indices, then verify:
    {{BROWSER_VERIFY_STEPS}}
 
-Chain commands: `opencli browser click <N> && opencli browser wait time 1 && opencli browser state`
+Run page-changing commands sequentially, then run `opencli browser state` to refresh indices.
 
 **Step 3 — Cleanup**:
 1. `opencli browser close`
-2. `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
+3. `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
 {{END_IF_BROWSER_TOOL_OPENCLI}}
 {{IF_BROWSER_TOOL_AUTO}}
 **Tool Selection**: Choose the best browser tool at runtime.
 
 **Step 0 — Detect available tools**:
 ```bash
-echo "=== playwright-cli ===" && which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "NOT_INSTALLED"
-echo "=== opencli ===" && which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
+{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version
 ```
-If opencli installed: `opencli doctor 2>/dev/null || echo "OPENCLI_BRIDGE_FAILED"`
+If opencli is installed, run `opencli doctor`. If it fails, mark OpenCLI unusable and choose playwright-cli or skip browser verification.
 
 **Decision table**:
 | Condition | Tool |

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -70,7 +70,7 @@ You are the **bug fix session agent**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}".
 ### Phase 0: Initialize
 
 ```bash
-mkdir -p .prizmkit/bugfix/{{BUG_ID}}
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/bugfix/{{BUG_ID}}
 ```
 
 {{IF_BROWSER_INTERACTION}}
@@ -186,7 +186,7 @@ Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/`:
 **Gate Check — Review Report**:
 After `/prizmkit-code-review` returns, verify the review report:
 ```bash
-grep -q "## Verdict" .prizmkit/bugfix/{{BUG_ID}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+{{RUNTIME_HELPER_CMD}} text contains .prizmkit/bugfix/{{BUG_ID}}/review-report.md --pattern "## Verdict"
 ```
 If GATE:MISSING:
 - Do not re-run `/prizmkit-code-review` in an unbounded report-repair loop.

package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md

@@ -96,7 +96,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
 
 Create refactor artifacts directory:
 ```bash
-mkdir -p .prizmkit/refactor/{{REFACTOR_ID}}
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/refactor/{{REFACTOR_ID}}
 ```
 
 ### Step 2: Pipeline Phases
@@ -208,7 +208,7 @@ Evidence must cover affected UI render, primary user interactions, behavior-sens
 - **Gate Check — Review Report**:
   After Reviewer returns, verify the review report contains a verdict:
   ```bash
-  grep -q "## Verdict" .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
+  {{RUNTIME_HELPER_CMD}} text contains .prizmkit/refactor/{{REFACTOR_ID}}/review-report.md --pattern "## Verdict"
   ```
   If GATE:MISSING:
   - Do not enter an unbounded report-repair loop and do not repeatedly re-spawn Reviewer.

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -9,7 +9,7 @@ A checkpoint file tracks your progress through this workflow:
 Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
 
 ```bash
-python3 .prizmkit/dev-pipeline/scripts/update-checkpoint.py \
+{{CHECKPOINT_PYTHON_CMD}} \
   --checkpoint-path {{CHECKPOINT_PATH}} \
   --step <step-id-or-skill-name> \
   --status <in_progress|completed|failed|skipped> \

package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md

@@ -6,10 +6,8 @@ You MUST attempt this phase. Mark it as skipped only when no usable browser tool
 
 0a. Check which browser tools are available:
 ```bash
-echo "=== playwright-cli ==="
-which playwright-cli 2>/dev/null && playwright-cli --version 2>/dev/null || echo "PLAYWRIGHT_CLI:NOT_INSTALLED"
-echo "=== opencli ==="
-which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "OPENCLI:NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
+{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version
 ```
 
 0b. Use this single decision tree:
@@ -18,19 +16,15 @@ which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "OPENCLI:NOT_
 3. Else install `playwright-cli` as the default:
    ```bash
    npm install -g @playwright/cli@latest
-   playwright-cli --version
+   {{RUNTIME_HELPER_CMD}} executable version playwright-cli --arg=--version
    ```
 4. If no browser tool is usable after these steps, append `## Browser Verification: SKIPPED — no usable browser tool` to `context-snapshot.md`, then continue to reporting/checkpoint.
 
 Use `opencli` instead of `playwright-cli` only when the scenario requires an existing Chrome login/session or third-party integration cookies.
 
-Record your choice:
-```bash
-BROWSER_TOOL="playwright-cli"   # or "opencli" or "skipped"
-echo "Selected browser tool: $BROWSER_TOOL"
-```
+Record your choice in the Browser Verification report as `Tool: playwright-cli`, `Tool: opencli`, or `Tool: skipped`.
 
-If `BROWSER_TOOL="skipped"`, do NOT start a dev server and do NOT run browser commands. Go directly to Step 4 Reporting and the checkpoint update.
+If tool is `skipped`, do NOT start a dev server and do NOT run browser commands. Go directly to Step 4 Reporting and the checkpoint update.
 
 ---
 
@@ -38,27 +32,15 @@ If `BROWSER_TOOL="skipped"`, do NOT start a dev server and do NOT run browser co
 
 0d. Check if playwright-cli skill is installed for the current AI platform:
 ```bash
-CURRENT_PLATFORM=""
-if which claude >/dev/null 2>&1; then
-  CURRENT_PLATFORM="claude"; SKILL_DIR="$HOME/.claude/skills"
-elif which cbc >/dev/null 2>&1; then
-  CURRENT_PLATFORM="codebuddy"; SKILL_DIR="$HOME/.cbc/skills"
-else
-  CURRENT_PLATFORM="unknown"
-fi
-if [ -d "$SKILL_DIR/playwright-cli" ] || ls "$SKILL_DIR"/playwright* 2>/dev/null | grep -q .; then
-  echo "SKILL_EXISTS"
-else
-  echo "SKILL_MISSING"
-fi
+{{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
 ```
-If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy installed skill from `$HOME/.claude/skills/playwright-cli` to `$SKILL_DIR/playwright-cli`.
+If `SKILL_MISSING`: run `playwright-cli install --skills`. If current platform is NOT claude, copy installed skill from `$HOME/.claude/skills/playwright-cli` to the path shown by the helper output for the current platform.
 
 0e. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Learn usage: `playwright-cli --help`.
 
 **Step 1 — Start Dev Server + Open (playwright-cli)**:
-1. Identify and start the dev server (see port detection below)
-2. Open: `playwright-cli open http://localhost:$DEV_PORT`
+1. Identify and start the dev server (see shared helper commands below)
+2. Open: `playwright-cli open http://localhost:<DEV_PORT>`
 3. If auth needed, use playwright-cli to register a test user and log in
 
 **Step 2 — Verification (playwright-cli)**:
@@ -69,18 +51,18 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
 
 **Step 3 — Cleanup (playwright-cli)**:
 1. `playwright-cli close`
-2. `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
+3. `{{RUNTIME_HELPER_CMD}} port check <DEV_PORT>`
 
 ---
 
 **If you chose `opencli`**, follow this workflow:
 
-0d. Learn usage: `opencli browser --help 2>/dev/null || opencli --help`
+0d. Learn usage: `opencli browser --help`
 
 **Step 1 — Start Dev Server + Open (opencli)**:
-1. Identify and start the dev server (see port detection below)
-2. Open and inspect: `opencli browser open http://localhost:$DEV_PORT && opencli browser state`
+1. Identify and start the dev server (see shared helper commands below)
+2. Open and inspect: `opencli browser open http://localhost:<DEV_PORT> && opencli browser state`
 3. If auth needed, opencli reuses Chrome cookies — SSO/OAuth may already be active
 
 **Step 2 — Verification (opencli)**:
@@ -95,30 +77,26 @@ Always run `state` after page-changing actions to get fresh indices.
 
 **Step 3 — Cleanup (opencli)**:
 1. `opencli browser close`
-2. `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
+3. `{{RUNTIME_HELPER_CMD}} port check <DEV_PORT>`
 
 ---
 
-**Shared: Dev Server Port Detection** (used by both tools):
-
-```bash
-DEV_PORT={{DEV_PORT}}
-if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-  DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
-  if [ -z "$DEV_PORT" ]; then
-    DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
-  fi
-  DEV_PORT=${DEV_PORT:-3000}
-fi
-echo "Detected DEV_PORT=$DEV_PORT"
-```
-
-Verify port available: `lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"`
-
-Start dev server: `<start-command> & DEV_SERVER_PID=$!`
+**Shared: Dev Server Port / Process Helpers** (used by both tools):
 
-Wait for ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until 200/302 (max 30s, 2s interval).
+1. Determine `DEV_PORT` from the pipeline value (`{{DEV_PORT}}`) or project config; do not guess.
+2. Verify port available:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} port check <DEV_PORT>
+   ```
+3. Start dev server:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
+   ```
+4. Wait for ready:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:<DEV_PORT> --timeout 30 --interval 2
+   ```
 
 ---
 
@@ -128,7 +106,7 @@ Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    Tool: <playwright-cli or opencli>
-   URL: http://localhost:$DEV_PORT
+   URL: http://localhost:<DEV_PORT>
    Dev Server Command: <actual command used>
    Tool version: <version>
    Steps executed: [list of commands used]
@@ -140,4 +118,3 @@ Append results to `context-snapshot.md`:
 
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
-

package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md

@@ -12,13 +12,13 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
 
 0a. Check if `opencli` is installed:
 ```bash
-which opencli 2>/dev/null && opencli --version 2>/dev/null || echo "NOT_INSTALLED"
+{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version
 ```
 If output is `NOT_INSTALLED`, install it:
 ```bash
 npm install -g @jackwener/opencli@latest
 ```
-Then verify installation succeeded: `opencli --version`. If installation fails, log `## Browser Verification: SKIPPED — opencli installation failed` in context-snapshot.md and proceed to the next phase.
+Then verify installation succeeded: `{{RUNTIME_HELPER_CMD}} executable version opencli --arg=--version`. If installation fails, log `## Browser Verification: SKIPPED — opencli installation failed` in context-snapshot.md and proceed to the next phase.
 
 0b. Verify Browser Bridge connectivity:
 ```bash
@@ -28,7 +28,7 @@ If `opencli doctor` fails (Chrome not running or extension not installed), log `
 
 0c. Learn opencli browser usage (run once per session):
 ```bash
-opencli browser --help 2>/dev/null || opencli --help
+opencli browser --help
 ```
 
 **Step 1 — Start Dev Server**:
@@ -36,31 +36,22 @@ opencli browser --help 2>/dev/null || opencli --help
 You know this project's tech stack. Detect and start the dev server yourself:
 
 1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
-2. **Detect the dev server port** — use the pre-detected port from pipeline if available, otherwise extract from project config. Do NOT hardcode or guess the port:
+2. Determine the dev server port from the pre-detected pipeline value (`{{DEV_PORT}}`) or project config. Do NOT hardcode or guess the port. Record it as `DEV_PORT` in your notes.
+3. Verify the port is available:
    ```bash
-   DEV_PORT={{DEV_PORT}}
-   if [ "$DEV_PORT" = "{{DEV_PORT}}" ]; then
-     DEV_PORT=$(node -e "const s=require('./package.json').scripts.dev; const m=s.match(/-p\s+(\d+)/); console.log(m?m[1]:'')")
-     if [ -z "$DEV_PORT" ]; then
-       DEV_PORT=$(echo "$NEXT_PUBLIC_SITE_URL" | sed -nE 's|.*:([0-9]+).*|\1|p')
-     fi
-     DEV_PORT=${DEV_PORT:-3000}
-   fi
-   echo "Detected DEV_PORT=$DEV_PORT"
+   {{RUNTIME_HELPER_CMD}} port check <DEV_PORT>
    ```
-3. Verify the port is available:
+4. Start the dev server with the runtime helper and capture a PID file:
    ```bash
-   lsof -ti:$DEV_PORT 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
    ```
-4. Start the dev server in background, capture PID:
+5. Wait for server to be ready:
    ```bash
-   <start-command> &
-   DEV_SERVER_PID=$!
+   {{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:<DEV_PORT> --timeout 30 --interval 2
    ```
-5. Wait for server to be ready: poll `http://localhost:$DEV_PORT` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
 6. Open the app in opencli and inspect page state:
    ```bash
-   opencli browser open http://localhost:$DEV_PORT && opencli browser state
+   opencli browser open http://localhost:<DEV_PORT> && opencli browser state
    ```
 7. If the page requires authentication, use opencli browser to interact with login forms (opencli reuses Chrome cookies, so SSO/OAuth may already be active)
 
@@ -82,13 +73,8 @@ Key opencli browser commands for verification:
 
 **Chain commands aggressively with `&&`** to minimize tool calls:
 ```bash
-# GOOD: open + inspect in one call
-opencli browser open http://localhost:$DEV_PORT && opencli browser state
-
-# GOOD: fill form in one call
+opencli browser open http://localhost:<DEV_PORT> && opencli browser state
 opencli browser type 3 "hello" && opencli browser type 4 "world" && opencli browser click 7
-
-# GOOD: click + wait + re-inspect
 opencli browser click 12 && opencli browser wait time 1 && opencli browser state
 ```
 
@@ -99,8 +85,14 @@ Construct your verification workflow based on: (1) the `opencli browser --help`
 **Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
 1. Close the opencli browser session: `opencli browser close`
-2. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
-3. Verify port is released: `lsof -ti:$DEV_PORT | xargs kill -9 2>/dev/null || true`
+2. Stop the dev server process using the PID file written in Step 1:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>
+   ```
+3. Verify port is released:
+   ```bash
+   {{RUNTIME_HELPER_CMD}} port check <DEV_PORT>
+   ```
 
 **Step 4 — Reporting**:
 
@@ -108,7 +100,7 @@ Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    Tool: opencli
-   URL: http://localhost:$DEV_PORT
+   URL: http://localhost:<DEV_PORT>
    Dev Server Command: <actual command used>
    opencli version: <version>
    Steps executed: [list of opencli browser commands used]
@@ -120,4 +112,3 @@ Append results to `context-snapshot.md`:
 
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
 
-