prizmkit 1.1.108 → 1.1.110

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

@@ -52,15 +52,15 @@ 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. **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.
+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 platform file/search tools for targeted lookup; when shell-free helper lookup is needed, run `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<pattern>" --json`, then read only the smallest bounded range with the platform file-reading tool 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 4 (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.
+5. **Minimize tool output** — Never load full command output into context. First capture command output to a temp file using the command/tool output option or the host-appropriate redirection, then inspect only the final relevant lines and use targeted search helpers to extract 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-5. All changes are committed once at the end in Phase 6 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.
+7. **Capture test output once** — When running test suites, capture output once to `/tmp/test-out.txt` using the command/tool output option or the host-appropriate redirection, surface only the final relevant lines, then search `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
 9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
 10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
-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.
+11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Use the platform file-reading tool to refresh bounded line information, or locate an anchor with `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<anchor>" --json` before reading a small bounded range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets or prescribe POSIX-only lookup commands.
 
 ---
 
@@ -78,7 +78,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.
 
@@ -89,7 +89,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}}
@@ -101,30 +101,30 @@ If any agent times out:
 
 **Check for previous failure log:**
 ```bash
-cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md --exists-marker PREVIOUS_FAILURE --missing-marker NO_PREVIOUS_FAILURE
 ```
-If failure-log.md exists:
-- Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
+If the helper prints `PREVIOUS_FAILURE`:
+- Read `failure-log.md` ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
 - Read DISCOVERED_TRAPS — if any are genuine, inject into .prizmkit/prizm-docs/ during Phase 6 retrospective
 - Do NOT delete failure-log.md until this session completes all phases and commits successfully
 
 ```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/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 + acceptance criteria (copy from above)
-   - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
+   - **Section 2 — Project Structure**: run the helper to get a visual directory tree, then paste output:
      ```bash
-     find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+     {{RUNTIME_HELPER_CMD}} artifact tree . --max-depth 2
      ```
    - **Section 3 — Key TRAPS & RULES**: relevant TRAPS/RULES from prizm-docs (not full copies)
    - **Section 4 — File Manifest**: For each file relevant to this feature, list: file path, why it's needed (modify/reference/test), key interface signatures (function names + params + return types). Do NOT include full file content — agents read files on-demand. Format:
@@ -144,7 +144,7 @@ If MISSING — build it now:
 ### Phase 2: Plan & Tasks (you, the orchestrator)
 
 ```bash
-ls .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
+{{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/plan.md
 ```
 
 If either missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate missing files:
@@ -183,7 +183,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."
 
@@ -264,7 +264,7 @@ After all critics return, read all 3 reports:
 
 Before starting, check plan.md Tasks:
 ```bash
-grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || true
+{{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
 ```
 - If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
 - If non-zero → implement directly below.
@@ -314,7 +314,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.
@@ -334,8 +334,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:
@@ -366,13 +366,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
@@ -381,21 +381,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 the installed skill from the Claude user skills directory 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.
 
@@ -404,29 +392,17 @@ 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)
-6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+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
 
 **Step 2 — Verification**:
@@ -439,8 +415,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}} port check {{DEV_PORT}}`
 {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
 {{IF_BROWSER_TOOL_OPENCLI}}
 **Using: opencli** (reuses Chrome logged-in sessions)
@@ -453,45 +429,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}} port check {{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 |
@@ -512,7 +485,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]
@@ -550,7 +523,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
 ```bash
 git status --short
 ```
-Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+Working tree MUST be clean after this step. If any feature-related files remain, stage them explicitly and amend the SAME commit with `git commit --amend --no-edit`; do NOT create a separate commit.
 
 **Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
 

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

@@ -52,15 +52,15 @@ 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-2 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. **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.
+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 platform file/search tools for targeted lookup; when shell-free helper lookup is needed, run `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<pattern>" --json`, then read only the smallest bounded range with the platform file-reading tool 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 4 (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.
+5. **Minimize tool output** — Never load full command output into context. First capture command output to a temp file using the command/tool output option or the host-appropriate redirection, then inspect only the final relevant lines and use targeted search helpers to extract 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-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Batch independent operations** — Issue multiple independent `Write`/`Read` calls in a single message turn when they have no dependencies. Combine multiple `mkdir -p` into one command. Never run `npm test` twice just to apply a different grep filter — capture output to `/tmp/test-out.txt` once and grep the file.
 9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
 10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
-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.
+11. **Read offset safety (BLOCKING)** — If Read returns "shorter than offset"/"File is empty"/"Wasted call" — do NOT retry same offset. Use the platform file-reading tool to refresh bounded line information, or locate an anchor with `{{RUNTIME_HELPER_CMD}} text search <file> --pattern "<anchor>" --json` before reading a small bounded range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets or prescribe POSIX-only lookup commands.
 
 ---
 
@@ -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,30 +113,30 @@ 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**
 - `context-snapshot.md` exists → use it directly, skip Phase 1
 - Some missing → generate only missing files
 
-Before planning, check whether feature code already exists in the project (search in source directories identified from `root.prizm` or the project tree scan):
+Before planning, check whether feature code already exists in the project (use the helper to search source directories identified from `root.prizm` or the project tree scan):
 ```bash
-grep -r "{{FEATURE_SLUG}}" . --include="*.js" --include="*.ts" --include="*.py" --include="*.go" --include="*.java" --include="*.rb" --include="*.rs" -l --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor --exclude-dir=.prizmkit 2>/dev/null | head -20
+{{RUNTIME_HELPER_CMD}} text search . --pattern "{{FEATURE_SLUG}}" --json
 ```
 
-Record result as `EXISTING_CODE` (list of files, or empty).
+Record result as `EXISTING_CODE` (helper `match` entries for source files, or empty; ignore `.prizmkit/` artifact matches).
 
 If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing implementation — document what exists, identify gaps, do NOT re-implement what is already done.
 
 **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."
 
@@ -258,7 +259,7 @@ After all critics return, read all 3 reports:
 
 Before starting, check plan.md Tasks:
 ```bash
-grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || true
+{{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
 ```
 - If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
 - If non-zero → implement directly below.
@@ -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 the installed skill from the Claude user skills directory 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,29 +387,17 @@ 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)
-6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
+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
 
 **Step 2 — Verification**:
@@ -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}} port check {{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}} port check {{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 |
@@ -506,7 +480,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]
@@ -528,9 +502,9 @@ If verification fails, log the failure details but continue to commit. Failures
 - Complex bugs (multi-module, cascading): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`.
 - Commit prefix: `fix(<scope>):` (not `feat:`).
 
-**6a.** Check if feature already committed:
+**6a.** Check if feature already committed by inspecting recent git history for `{{FEATURE_ID}}`:
 ```bash
-git log --oneline | grep "{{FEATURE_ID}}" | head -3
+git log --oneline
 ```
 - If a commit for `{{FEATURE_ID}}` already exists → **skip 6d** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to 6e Final verification.
 - If no existing commit → proceed normally with 6b–6d.
@@ -559,7 +533,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
 ```bash
 git status --short
 ```
-Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+Working tree MUST be clean after this step. If any feature-related files remain, stage them explicitly and amend the SAME commit with `git commit --amend --no-edit`; do NOT create a separate commit.
 
 **Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.