prizmkit 1.1.107 → 1.1.109

package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py

@@ -19,7 +19,7 @@ import os
 import re
 import sys
 
-from utils import enrich_global_context, load_json_file, read_platform_conventions, setup_logging
+from utils import enrich_global_context, helper_replacements, load_json_file, read_checkpoint_system_section, resolve_prompt_platform, setup_logging
 from continuation import add_continuation_args, append_continuation_handoff, is_continuation
 
 
@@ -134,6 +134,7 @@ def parse_args():
     parser.add_argument("--resume-phase", required=True, help='Phase to resume from, or "null" for fresh start')
     parser.add_argument("--state-dir", default=None, help="State directory (default: .prizmkit/state/refactor)")
     parser.add_argument("--output", required=True, help="Output path for the rendered prompt")
+    parser.add_argument("--project-root", default=None, help="AI-visible project root used for rendered prompt paths")
     parser.add_argument("--template", default=None, help="Custom template path. Defaults to {script_dir}/../templates/refactor-bootstrap-prompt.md")
     parser.add_argument("--mode", default=None, help="Pipeline execution mode override: lite, standard, full")
     parser.add_argument("--critic", default=None, help="Enable critic agent: true/false")
@@ -167,19 +168,6 @@ def _parse_positive_int_env(name, default):
     return parsed
 
 
-def load_log_size_section(script_dir):
-    """Load passive checkpoint guidance for normal prompt generation."""
-    section_path = os.path.join(
-        script_dir, "..", "templates", "sections", "log-size-awareness.md",
-    )
-    if not os.path.isfile(section_path):
-        return ""
-
-    content, err = read_text_file(section_path)
-    if err:
-        return ""
-    return content
-
 def find_refactor(refactors, refactor_id):
     """Find and return the refactor dict matching the given ID."""
     for refactor in refactors:
@@ -396,22 +384,39 @@ def resolve_project_root(script_dir):
     return os.path.abspath(pipeline_parent)
 
 
+def _project_root_from_prizmkit_path(path):
+    """Infer project root from a path nested under .prizmkit/."""
+    if not path:
+        return ""
+    current = os.path.abspath(path)
+    if not os.path.isdir(current):
+        current = os.path.dirname(current)
+    while current and current != os.path.dirname(current):
+        if os.path.basename(current) == ".prizmkit":
+            return os.path.abspath(os.path.dirname(current))
+        current = os.path.dirname(current)
+    return ""
+
+
+def _args_project_root(args, script_dir):
+    """Return explicit AI-visible project root, plan-path root, or script-layout default."""
+    explicit = getattr(args, "project_root", None)
+    if explicit:
+        return os.path.abspath(explicit)
+    plan_root = _project_root_from_prizmkit_path(getattr(args, "refactor_list", ""))
+    if plan_root:
+        return plan_root
+    return resolve_project_root(script_dir)
+
+
 def build_replacements(args, refactor, refactors, global_context, script_dir):
     """Build the full dict of placeholder -> replacement value."""
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
 
     # Platform-aware agent/team path resolution
-    platform = os.environ.get("PRIZMKIT_PLATFORM", "")
+    platform = resolve_prompt_platform(project_root)
     home_dir = os.path.expanduser("~")
 
-    if not platform:
-        if os.path.isdir(os.path.join(project_root, ".codex", "agents")):
-            platform = "codex"
-        elif os.path.isdir(os.path.join(project_root, ".claude", "agents")):
-            platform = "claude"
-        else:
-            platform = "codebuddy"
-
     if platform == "claude":
         agents_dir = os.path.join(project_root, ".claude", "agents")
         team_config_path = os.path.join(project_root, ".claude", "team-info.json")
@@ -428,10 +433,16 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
     dev_subagent = os.path.join(agents_dir, f"prizm-dev-team-dev{agent_ext}")
     reviewer_subagent = os.path.join(agents_dir, f"prizm-dev-team-reviewer{agent_ext}")
 
-    # Session status path
+    # Session status is controlled by the main runner state dir, even when
+    # rendered project paths are AI-visible worktree paths.
+    state_dir = (
+        os.path.abspath(args.state_dir)
+        if args.state_dir
+        else os.path.join(project_root, ".prizmkit", "state", "refactor")
+    )
     session_status_path = os.path.join(
-        project_root, ".prizmkit", "state", "refactor", args.refactor_id,
-        "sessions", args.session_id, "session-status.json"
+        state_dir, args.refactor_id, "sessions", args.session_id,
+        "session-status.json",
     )
 
     # Scope
@@ -493,7 +504,6 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
             browser_verify_steps = "   # (validate UI renders correctly and feature still works)"
 
     replacements = {
-        "{{LOG_SIZE_AWARENESS}}": load_log_size_section(script_dir),
         "{{SESSION_LOG_PATH}}": os.path.join(
             ".prizmkit", "state", "refactor", args.refactor_id,
             "sessions", args.session_id, "logs", "session.log",
@@ -527,13 +537,15 @@ def build_replacements(args, refactor, refactors, global_context, script_dir):
         "{{CHECKPOINT_PATH}}": os.path.join(
             ".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json",
         ),
+        "{{CHECKPOINT_SYSTEM}}": read_checkpoint_system_section(script_dir),
         "{{TIMESTAMP}}": "",  # Placeholder — agent fills in timestamp
-        "{{PLATFORM_CONVENTIONS}}": read_platform_conventions(project_root),
         "{{BROWSER_ENABLED}}": "true" if browser_enabled else "false",
         "{{BROWSER_TOOL}}": browser_tool,
         "{{BROWSER_VERIFY_STEPS}}": browser_verify_steps,
     }
 
+    replacements.update(helper_replacements(script_dir))
+
     return replacements
 
 
@@ -696,9 +708,6 @@ def main():
 
     # Build replacements
     replacements = build_replacements(args, refactor, refactors, global_context, script_dir)
-    if is_continuation(args):
-        replacements["{{LOG_SIZE_AWARENESS}}"] = ""
-
     # Render the template
     rendered = render_template(template_content, replacements, args.resume_phase, refactor)
 
@@ -708,7 +717,7 @@ def main():
         emit_failure(err)
 
     # Generate checkpoint file
-    project_root = resolve_project_root(script_dir)
+    project_root = _args_project_root(args, script_dir)
     checkpoint_rel = os.path.join(
         ".prizmkit", "refactor", args.refactor_id, "workflow-checkpoint.json",
     )

package/bundled/dev-pipeline/scripts/prizmkit-runtime-helper.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Thin entrypoint for the PrizmKit prompt runtime helper CLI."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def _bootstrap_import_path() -> None:
+    """Ensure direct script execution can import the runtime package."""
+    pipeline_root = Path(__file__).resolve().parents[1]
+    pipeline_root_text = str(pipeline_root)
+    if pipeline_root_text not in sys.path:
+        sys.path.insert(0, pipeline_root_text)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the runtime helper CLI and return its process exit code."""
+    _bootstrap_import_path()
+    from prizmkit_runtime.runtime_helper import main as helper_main
+
+    return helper_main(argv)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled/dev-pipeline/scripts/utils.py

@@ -9,8 +9,50 @@ import json
 import logging
 import os
 import re
+import shlex
 import sys
 
+_PIPELINE_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if _PIPELINE_ROOT not in sys.path:
+    sys.path.insert(0, _PIPELINE_ROOT)
+
+
+def shell_quote(value):
+    """Return a shell-safe token for prompt command examples."""
+    return shlex.quote(str(value))
+
+
+def runtime_python_command():
+    """Return the current Python executable for rendered prompt commands."""
+    return shell_quote(sys.executable or "python3")
+
+
+def runtime_helper_command(script_dir):
+    """Return the installed-project helper command prefix for prompt templates."""
+    helper_path = os.path.join(
+        ".prizmkit", "dev-pipeline", "scripts", "prizmkit-runtime-helper.py"
+    )
+    return "{} {}".format(runtime_python_command(), helper_path)
+
+
+def checkpoint_python_command():
+    """Return the checkpoint update Python command prefix for prompt templates."""
+    return "{} {}".format(
+        runtime_python_command(),
+        os.path.join(".prizmkit", "dev-pipeline", "scripts", "update-checkpoint.py"),
+    )
+
+
+def helper_replacements(script_dir):
+    """Return common prompt placeholders for Python runtime helpers."""
+    return {
+        "{{PYTHON_CMD}}": runtime_python_command(),
+        "{{RUNTIME_HELPER_CMD}}": runtime_helper_command(script_dir),
+        "{{CHECKPOINT_PYTHON_CMD}}": checkpoint_python_command(),
+    }
+
+
+
 
 def load_json_file(path):
     """Load and return parsed JSON from a file.
@@ -79,6 +121,46 @@ def error_out(message, code=1):
     sys.exit(code)
 
 
+def read_checkpoint_system_section(script_dir):
+    """Read the shared checkpoint prompt section for feature/bugfix/refactor prompts."""
+    path = os.path.join(
+        os.path.abspath(script_dir), "..", "templates", "sections", "checkpoint-system.md"
+    )
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    except IOError:
+        return """## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+### Checkpoint Update Helper
+
+Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
+
+```bash
+{{CHECKPOINT_PYTHON_CMD}} \\
+  --checkpoint-path {{CHECKPOINT_PATH}} \\
+  --step <step-id-or-skill-name> \\
+  --status <in_progress|completed|failed|skipped> \\
+  --note "<optional note>"
+```
+
+- Use the step `skill` value such as `prizmkit-implement`, or the step id such as `S04`.
+- Omit `--note` when there is no useful failure or handoff note.
+
+### Rules
+
+1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, complete it first before moving on.
+2. **Starting a skill**: Use the checkpoint update helper to mark the current step as `status: "in_progress"`.
+3. **After each skill completes**: Use the checkpoint update helper to mark the current step as `status: "completed"`.
+4. **On failure**: Use the checkpoint update helper to mark the step as `status: "failed"`, write `failure-log.md` with the reason, and continue only when the workflow rules allow it.
+5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to `"completed"`.
+"""
+
+
 def pad_right(text, width):
     """Pad text with spaces to fill width, accounting for ANSI escape codes."""
     i = 0
@@ -520,6 +602,18 @@ def enrich_global_context(global_context, project_root):
     return global_context
 
 
+def resolve_prompt_platform(project_root):
+    """Resolve the platform whose agent paths should appear in prompts."""
+    from prizmkit_runtime.platform_detection import resolve_platform
+
+    resolution = resolve_platform(project_root)
+    if resolution.platform:
+        return resolution.platform
+    raise RuntimeError(
+        "PrizmKit agents not found. None of .claude/agents/, .codex/agents/, or .codebuddy/agents/ exists. "
+        "Run `npx prizmkit install` first, set .prizmkit/config.json ai_cli/platform, or set PRIZMKIT_PLATFORM=claude|codex|codebuddy explicitly."
+    )
+
 def read_platform_conventions(project_root):
     """Resolve the platform-specific project conventions file.
 

package/bundled/dev-pipeline/templates/agent-prompts/critic-plan-challenge.md

@@ -1,7 +1,8 @@
 "Read {{CRITIC_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 **MODE: Plan Challenge**
 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-2. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs for affected modules.
-3. Read existing source files in the modules this plan touches.
-4. Challenge plan.md against the project's existing architecture, patterns, and style.
+2. Use context-snapshot.md as the shared source of truth. Do not create or enter AI tool-created `.claude/worktrees/...` subagent worktrees; use default/no worktree isolation and do not request worktree isolation.
+3. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are a separate runner feature controlled by `USE_WORKTREE`; do not confuse them with AI tool-created `.claude/worktrees/...`.
+4. Read additional `.prizmkit/prizm-docs/` or source excerpts only when needed to verify a specific challenge.
+5. Challenge plan.md against the project's existing architecture, patterns, and style.
 Write `.prizmkit/specs/{{FEATURE_SLUG}}/challenge-report.md` with findings (or 'No significant challenges')."

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

@@ -44,7 +44,7 @@ Infer what needs to be done from the feature context above and follow the standa
 - Do NOT push to remote — the user will push manually.
 - Write all artifacts to `.prizmkit/specs/{{FEATURE_SLUG}}/`.
 - If a step fails after 3 attempts, write a status report and stop.
-- **Anti re-read**: once you read a file into context, do NOT read it again — use `grep -n`/`sed -n` for specific lines. 3 full Reads of same file → report BLOCKED.
+- **Never re-read unmodified files**: once you read a file into context, do NOT read it again unless it was modified by an Edit/Write after your last read — use `grep -n`/`sed -n` for specific lines. Before issuing a Read, ask: "Have I read this file before, and has it changed since?" If no — do NOT read it. Subagents (Critic, Reviewer) must rely on context-snapshot.md rather than re-reading files the orchestrator already read.
 - **Read offset safety**: if Read returns "shorter than offset"/"empty" — run `wc -l` then `sed -n`, do NOT retry same offset.
 - **Hard Round Cap**: after 6 total test-fix rounds, STOP trial-and-error. Switch to read-once-then-rewrite. Do NOT exceed 7 rounds.
 - **Layered test**: debug with single-file tests, only run full suite as gate when single-file is green.

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

@@ -46,21 +46,18 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 
 1. **context-snapshot.md is your single source of truth** — After Phase 1 builds it, ALWAYS read context-snapshot.md instead of re-reading individual source files
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
-3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
+3. **Never re-read unmodified files** — Once you have read a file into context, do NOT read it again unless it was modified by an Edit/Write operation after your last read. Use `grep -n '<pattern>' <file>` or `sed -n '<start>,<end>p' <file>` for targeted line lookups instead of full-file Read. Before issuing a Read, ask yourself: "Have I read this file before, and has it changed since?" If the answer is "no, it hasn't changed" — do NOT read it. This applies to all files including those summarized in context-snapshot.md Section 4. Subagents (Critic, Reviewer) must receive context-snapshot.md and rely on it rather than independently re-reading the same files the orchestrator already read.
+4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
 5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-3. All changes are committed once at the end in Phase 4 via `/prizmkit-committer`.
 7. **Capture test output once** — When running test suites, always use `<test-command> 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
-8. **Scaffold / generated file awareness** — Files created by scaffolding tools (`npm init`, `npx create-*`, etc.) are boilerplate. Tag them, record in context-snapshot.md, and NEVER re-read them. If you need to modify one, edit directly without reading first.
 9. **Package version verification (BLOCKING)** — Before writing ANY dependency version, verify it exists via registry query (`npm view <pkg> dist-tags.latest`, `pip index versions <pkg>`, etc.). NEVER guess version numbers.
 10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`. Never commit binaries/build output.
 11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Run `wc -l <file>` to get real line count, then `sed -n` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets — `grep -n '<anchor>'` first.
 
 ---
 
-{{LOG_SIZE_AWARENESS}}
----
-
 ## PrizmKit Directory Convention
 
 ```
@@ -75,7 +72,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 {{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}}
@@ -85,16 +82,16 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 ### Phase 1: Build Context Snapshot
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md
 ```
 
 If MISSING — build it now:
 1. Read `.prizmkit/prizm-docs/root.prizm` and relevant L1 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 + acceptance criteria (copy from above)
@@ -109,12 +106,12 @@ If MISSING — build it now:
 ### Phase 2: Plan & Tasks
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}
 ```
 
 If plan.md missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate `plan.md`:
 - The plan.md should include: key components, data flow, files to create/modify, and a Tasks section with `[ ]` checkboxes (each task = one implementable unit). Keep under 80 lines.
-- Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
+- Resolve uncertain requirements from the feature description, existing code, and conservative existing-project patterns.
 
 **Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
 Before proceeding past CP-1:
@@ -160,7 +157,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.
@@ -178,7 +175,11 @@ Read `review-report.md` and check the Verdict:
 
 Run `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` after review and before commit.
 
-Before invoking the skill, create `.prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started` so stale reports are ignored.
+Before invoking the skill, create a current-run marker so stale reports are ignored:
+```bash
+{{RUNTIME_HELPER_CMD}} artifact ensure-dir .prizmkit/specs/{{FEATURE_SLUG}}
+{{RUNTIME_HELPER_CMD}} artifact touch .prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started
+```
 
 Gate requirements:
 - Generate or update tests only for this feature's changed files, changed public interfaces, and acceptance criteria.
@@ -208,13 +209,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
@@ -223,21 +224,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.
 
@@ -246,28 +235,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
 
@@ -281,8 +258,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)
@@ -295,45 +272,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 |