prizmkit 1.1.109 → 1.1.111

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/agents/prizm-dev-team-reviewer.md +4 -0
  3. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +36 -3
  4. package/bundled/dev-pipeline/templates/bootstrap-tier1.md +16 -16
  5. package/bundled/dev-pipeline/templates/bootstrap-tier2.md +18 -18
  6. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +17 -17
  7. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  8. package/bundled/dev-pipeline/templates/sections/context-budget-rules.md +8 -8
  9. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +4 -3
  10. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +9 -5
  11. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +1 -1
  12. package/bundled/dev-pipeline/templates/sections/phase-commit-full.md +2 -2
  13. package/bundled/dev-pipeline/templates/sections/phase-commit.md +1 -1
  14. package/bundled/dev-pipeline/templates/sections/phase-implement-agent.md +1 -1
  15. package/bundled/dev-pipeline/templates/sections/phase-implement-full.md +1 -1
  16. package/bundled/dev-pipeline/templates/sections/test-failure-recovery-agent.md +1 -1
  17. package/bundled/dev-pipeline/templates/sections/test-failure-recovery-lite.md +1 -1
  18. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +212 -0
  19. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +122 -0
  20. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +124 -0
  21. package/bundled/dev-pipeline/tests/test_unified_cli.py +1 -1
  22. package/bundled/skills/_metadata.json +1 -1
  23. package/bundled/skills/prizmkit/SKILL.md +9 -9
  24. package/bundled/skills/prizmkit-code-review/SKILL.md +24 -2
  25. package/bundled/skills/prizmkit-code-review/references/reviewer-agent-prompt.md +2 -1
  26. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.109",
3
- "bundledAt": "2026-07-08T05:29:47.417Z",
4
- "bundledFrom": "814bf2f"
2
+ "frameworkVersion": "1.1.111",
3
+ "bundledAt": "2026-07-08T07:06:52.766Z",
4
+ "bundledFrom": "1db214b"
5
5
  }
@@ -25,6 +25,8 @@ You are the team's "senior engineer doing code review" — you diagnose problems
25
25
  2. If no `context-snapshot.md`: read `spec.md`, `plan.md` from the artifact directory, then `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
26
26
  3. Identify changed files from `## Implementation Log` or completed tasks in plan.md
27
27
 
28
+ **Worktree constraint**: You are spawned with default/no worktree isolation by the orchestrator. You review the active checkout's changes — the orchestrator provides workspace context (git status, diff summary, new-file paths). Do NOT request or create `.claude/worktrees/...` tool worktrees. Do NOT re-discover or re-index the whole repository; use the orchestrator-provided context as your review scope and request only targeted file reads.
29
+
28
30
  **File Reading Rule**: Read ONLY files listed in the Implementation Log for diagnosis — do not explore unrelated files. Exception: during Fix Strategy Formulation, you MAY read additional files to trace impact (callers, dependents, shared patterns).
29
31
 
30
32
  ### Review Workflow
@@ -74,6 +76,8 @@ When Dev has applied fixes and returns for re-review:
74
76
  - Do not modify source files to fix issues — produce Fix Instructions for Dev instead
75
77
  - **Do NOT run test suites** — the Orchestrator handles testing. You review code, not execute tests.
76
78
  - Do NOT re-read source files already listed in context-snapshot.md Section 4 File Manifest unless you need a specific code detail for a finding
79
+ - **Do NOT request or create worktrees** (`.claude/worktrees/...` or similar) — you review the active checkout's changes using the orchestrator-provided workspace context
80
+ - **Do NOT re-discover or broadly re-index the repository** — the orchestrator has already captured the diff scope; request only targeted file reads for lines you need
77
81
 
78
82
  ### Behavioral Rules
79
83
 
@@ -190,9 +190,42 @@ def detect_test_commands(project_root):
190
190
  """
191
191
  test_commands = []
192
192
 
193
- # Check for npm/package.json
194
- if os.path.exists(os.path.join(project_root, "package.json")):
195
- test_commands.append("npm test")
193
+ # Check for npm/package.json — use content-aware detection
194
+ pkg_json_path = os.path.join(project_root, "package.json")
195
+ if os.path.exists(pkg_json_path):
196
+ try:
197
+ with open(pkg_json_path, "r", encoding="utf-8") as f:
198
+ pkg_data = json.load(f)
199
+ scripts = pkg_data.get("scripts", {}) if isinstance(pkg_data, dict) else {}
200
+
201
+ # Detect package manager from lockfiles
202
+ if os.path.exists(os.path.join(project_root, "pnpm-lock.yaml")):
203
+ pm_cmd = "pnpm"
204
+ elif os.path.exists(os.path.join(project_root, "yarn.lock")):
205
+ pm_cmd = "yarn"
206
+ else:
207
+ pm_cmd = "npm"
208
+
209
+ # Find best test script: prefer "test", then "test:unit",
210
+ # then first script matching test-related patterns
211
+ if "test" in scripts:
212
+ test_commands.append("{} test".format(pm_cmd))
213
+ elif "test:unit" in scripts:
214
+ test_commands.append("{} run test:unit".format(pm_cmd))
215
+ else:
216
+ # Search for any test-like script name
217
+ test_like = None
218
+ for script_name in sorted(scripts.keys()):
219
+ if "test" in script_name.lower():
220
+ test_like = script_name
221
+ break
222
+ if test_like:
223
+ test_commands.append(
224
+ "{} run {}".format(pm_cmd, test_like)
225
+ )
226
+ except Exception:
227
+ # Corrupt/unreadable package.json → skip JS detection
228
+ pass
196
229
 
197
230
  # Check for Go
198
231
  if os.path.exists(os.path.join(project_root, "go.mod")):
@@ -46,15 +46,15 @@ You are running in **headless non-interactive mode** with a FINITE context windo
46
46
 
47
47
  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
48
48
  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.
49
- 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.
49
+ 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.
50
50
  4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
51
51
  4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
52
- 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.
52
+ 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.
53
53
  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`.
54
- 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.
54
+ 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.
55
55
  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.
56
56
  10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`. Never commit binaries/build output.
57
- 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.
57
+ 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.
58
58
 
59
59
  ---
60
60
 
@@ -95,9 +95,9 @@ If MISSING — build it now:
95
95
  3. Scan the detected source directories for files related to this feature; read each one
96
96
  4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
97
97
  - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
98
- - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
98
+ - **Section 2 — Project Structure**: run the helper to get a visual directory tree, then paste output:
99
99
  ```bash
100
- 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'
100
+ {{RUNTIME_HELPER_CMD}} artifact tree . --max-depth 2
101
101
  ```
102
102
  - **Section 3 — Prizm Context**: content of root.prizm and relevant L1/L2 docs
103
103
  - **Section 4 — Existing Source Files**: **full verbatim content** of each related file in fenced code blocks (with `### path/to/file` heading and line count). Include ALL files needed for implementation and review — downstream phases read this section instead of re-reading individual source files
@@ -126,9 +126,9 @@ Before proceeding past CP-1:
126
126
  **Build artifacts**: After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary or build directory is in `.gitignore`:
127
127
  ```bash
128
128
  # Example for Go
129
- grep -q '^/binary-name$' .gitignore || echo '/binary-name' >> .gitignore
129
+ {{RUNTIME_HELPER_CMD}} text contains .gitignore --pattern "/binary-name" --found-marker IGNORED --missing-marker NEEDS_IGNORE_ENTRY
130
130
  ```
131
- Never commit compiled binaries, build output, or generated artifacts.
131
+ If the helper prints `NEEDS_IGNORE_ENTRY`, edit `.gitignore` and add `/binary-name` as a single line. Never commit compiled binaries, build output, or generated artifacts.
132
132
 
133
133
  **3a.** Run `/prizmkit-implement` — this handles the implementation cycle:
134
134
  - Reads plan.md Tasks section from `.prizmkit/specs/{{FEATURE_SLUG}}/`
@@ -226,7 +226,7 @@ playwright-cli --help
226
226
  ```bash
227
227
  {{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
228
228
  ```
229
- 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.
229
+ 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.
230
230
 
231
231
  0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
232
232
 
@@ -238,14 +238,14 @@ You know this project's tech stack. Detect and start the dev server yourself:
238
238
  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.
239
239
  3. Verify the port is available:
240
240
  ```bash
241
- {{RUNTIME_HELPER_CMD}} port check $DEV_PORT
241
+ {{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}
242
242
  ```
243
243
  4. Start the dev server in background, capture PID:
244
244
  ```bash
245
245
  {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
246
246
  ```
247
- 5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:$DEV_PORT --timeout 30 --interval 2`
248
- 6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
247
+ 5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:{{DEV_PORT}} --timeout 30 --interval 2`
248
+ 6. Open the app in playwright-cli: `playwright-cli open http://localhost:{{DEV_PORT}}`
249
249
  7. If the page requires authentication, use playwright-cli to register a test user and log in first
250
250
 
251
251
  **Step 2 — Verification**:
@@ -259,7 +259,7 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
259
259
 
260
260
  1. Close the playwright-cli browser: `playwright-cli close`
261
261
  2. Kill the dev server process: `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
262
- 3. Verify port is released: `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
262
+ 3. Verify port is released: `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
263
263
  {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
264
264
  {{IF_BROWSER_TOOL_OPENCLI}}
265
265
  **Using: opencli** (reuses Chrome logged-in sessions)
@@ -297,7 +297,7 @@ Run page-changing commands sequentially, then run `opencli browser state` to ref
297
297
  **Step 3 — Cleanup**:
298
298
  1. `opencli browser close`
299
299
  2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
300
- 3. `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
300
+ 3. `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
301
301
  {{END_IF_BROWSER_TOOL_OPENCLI}}
302
302
  {{IF_BROWSER_TOOL_AUTO}}
303
303
  **Tool Selection**: Choose the best browser tool at runtime.
@@ -328,7 +328,7 @@ Append results to `context-snapshot.md`:
328
328
  ```
329
329
  ## Browser Verification
330
330
  Tool: <playwright-cli or opencli>
331
- URL: http://localhost:$DEV_PORT
331
+ URL: http://localhost:{{DEV_PORT}}
332
332
  Dev Server Command: <actual command used>
333
333
  Tool version: <version>
334
334
  Steps executed: [list of commands used]
@@ -366,7 +366,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
366
366
  ```bash
367
367
  git status --short
368
368
  ```
369
- 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.
369
+ 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.
370
370
 
371
371
  **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.
372
372
 
@@ -52,15 +52,15 @@ You are running in **headless non-interactive mode** with a FINITE context windo
52
52
 
53
53
  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
54
54
  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.
55
- 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.
55
+ 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.
56
56
  4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
57
57
  4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
58
- 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.
58
+ 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.
59
59
  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`.
60
- 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.
60
+ 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.
61
61
  9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
62
62
  10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
63
- 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.
63
+ 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.
64
64
 
65
65
  ---
66
66
 
@@ -101,10 +101,10 @@ If any agent times out:
101
101
 
102
102
  **Check for previous failure log:**
103
103
  ```bash
104
- cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
104
+ {{RUNTIME_HELPER_CMD}} artifact exists .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md --exists-marker PREVIOUS_FAILURE --missing-marker NO_PREVIOUS_FAILURE
105
105
  ```
106
- If failure-log.md exists:
107
- - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
106
+ If the helper prints `PREVIOUS_FAILURE`:
107
+ - Read `failure-log.md` ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
108
108
  - Read DISCOVERED_TRAPS — if any are genuine, inject into .prizmkit/prizm-docs/ during Phase 6 retrospective
109
109
  - Do NOT delete failure-log.md until this session completes all phases and commits successfully
110
110
 
@@ -122,9 +122,9 @@ If MISSING — build it now:
122
122
  3. Scan the detected source directories for files related to this feature; read each one
123
123
  4. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
124
124
  - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
125
- - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
125
+ - **Section 2 — Project Structure**: run the helper to get a visual directory tree, then paste output:
126
126
  ```bash
127
- 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'
127
+ {{RUNTIME_HELPER_CMD}} artifact tree . --max-depth 2
128
128
  ```
129
129
  - **Section 3 — Key TRAPS & RULES**: relevant TRAPS/RULES from prizm-docs (not full copies)
130
130
  - **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:
@@ -264,7 +264,7 @@ After all critics return, read all 3 reports:
264
264
 
265
265
  Before starting, check plan.md Tasks:
266
266
  ```bash
267
- grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || true
267
+ {{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
268
268
  ```
269
269
  - If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
270
270
  - If non-zero → implement directly below.
@@ -383,7 +383,7 @@ playwright-cli --help
383
383
  ```bash
384
384
  {{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
385
385
  ```
386
- 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.
386
+ 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.
387
387
 
388
388
  0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
389
389
 
@@ -395,14 +395,14 @@ You know this project's tech stack. Detect and start the dev server yourself:
395
395
  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.
396
396
  3. Verify the port is available:
397
397
  ```bash
398
- {{RUNTIME_HELPER_CMD}} port check $DEV_PORT
398
+ {{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}
399
399
  ```
400
400
  4. Start the dev server in background, capture PID:
401
401
  ```bash
402
402
  {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
403
403
  ```
404
- 5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:$DEV_PORT --timeout 30 --interval 2`
405
- 6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
404
+ 5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:{{DEV_PORT}} --timeout 30 --interval 2`
405
+ 6. Open the app in playwright-cli: `playwright-cli open http://localhost:{{DEV_PORT}}`
406
406
  7. If the page requires authentication, use playwright-cli to register a test user and log in first
407
407
 
408
408
  **Step 2 — Verification**:
@@ -416,7 +416,7 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
416
416
 
417
417
  1. Close the playwright-cli browser: `playwright-cli close`
418
418
  2. Kill the dev server process: `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
419
- 3. Verify port is released: `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
419
+ 3. Verify port is released: `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
420
420
  {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
421
421
  {{IF_BROWSER_TOOL_OPENCLI}}
422
422
  **Using: opencli** (reuses Chrome logged-in sessions)
@@ -454,7 +454,7 @@ Run page-changing commands sequentially, then run `opencli browser state` to ref
454
454
  **Step 3 — Cleanup**:
455
455
  1. `opencli browser close`
456
456
  2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
457
- 3. `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
457
+ 3. `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
458
458
  {{END_IF_BROWSER_TOOL_OPENCLI}}
459
459
  {{IF_BROWSER_TOOL_AUTO}}
460
460
  **Tool Selection**: Choose the best browser tool at runtime.
@@ -485,7 +485,7 @@ Append results to `context-snapshot.md`:
485
485
  ```
486
486
  ## Browser Verification
487
487
  Tool: <playwright-cli or opencli>
488
- URL: http://localhost:$DEV_PORT
488
+ URL: http://localhost:{{DEV_PORT}}
489
489
  Dev Server Command: <actual command used>
490
490
  Tool version: <version>
491
491
  Steps executed: [list of commands used]
@@ -523,7 +523,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
523
523
  ```bash
524
524
  git status --short
525
525
  ```
526
- 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.
526
+ 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.
527
527
 
528
528
  **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.
529
529
 
@@ -52,15 +52,15 @@ You are running in **headless non-interactive mode** with a FINITE context windo
52
52
 
53
53
  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
54
54
  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.
55
- 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.
55
+ 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.
56
56
  4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
57
57
  4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
58
- 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.
58
+ 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.
59
59
  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`.
60
60
  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.
61
61
  9. **Package version verification (BLOCKING)** — Verify dependency versions via registry query before writing them. NEVER guess.
62
62
  10. **Build artifact hygiene** — After build/compile, ensure output is in `.gitignore`.
63
- 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.
63
+ 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.
64
64
 
65
65
  ---
66
66
 
@@ -120,12 +120,12 @@ Check existing artifacts first:
120
120
  - `context-snapshot.md` exists → use it directly, skip Phase 1
121
121
  - Some missing → generate only missing files
122
122
 
123
- Before planning, check whether feature code already exists in the project (search in source directories identified from `root.prizm` or the project tree scan):
123
+ 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):
124
124
  ```bash
125
- 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
125
+ {{RUNTIME_HELPER_CMD}} text search . --pattern "{{FEATURE_SLUG}}" --json
126
126
  ```
127
127
 
128
- Record result as `EXISTING_CODE` (list of files, or empty).
128
+ Record result as `EXISTING_CODE` (helper `match` entries for source files, or empty; ignore `.prizmkit/` artifact matches).
129
129
 
130
130
  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.
131
131
 
@@ -259,7 +259,7 @@ After all critics return, read all 3 reports:
259
259
 
260
260
  Before starting, check plan.md Tasks:
261
261
  ```bash
262
- grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || true
262
+ {{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
263
263
  ```
264
264
  - If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
265
265
  - If non-zero → implement directly below.
@@ -378,7 +378,7 @@ playwright-cli --help
378
378
  ```bash
379
379
  {{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
380
380
  ```
381
- 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.
381
+ 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.
382
382
 
383
383
  0d. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Use its recommended patterns to construct your verification flow.
384
384
 
@@ -390,14 +390,14 @@ You know this project's tech stack. Detect and start the dev server yourself:
390
390
  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.
391
391
  3. Verify the port is available:
392
392
  ```bash
393
- {{RUNTIME_HELPER_CMD}} port check $DEV_PORT
393
+ {{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}
394
394
  ```
395
395
  4. Start the dev server in background, capture PID:
396
396
  ```bash
397
397
  {{RUNTIME_HELPER_CMD}} process start --pid-file .prizmkit/state/browser-dev-server.pid -- <start-command tokens>
398
398
  ```
399
- 5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:$DEV_PORT --timeout 30 --interval 2`
400
- 6. Open the app in playwright-cli: `playwright-cli open http://localhost:$DEV_PORT`
399
+ 5. Wait for server to be ready: run `{{RUNTIME_HELPER_CMD}} web wait-ready --url http://localhost:{{DEV_PORT}} --timeout 30 --interval 2`
400
+ 6. Open the app in playwright-cli: `playwright-cli open http://localhost:{{DEV_PORT}}`
401
401
  7. If the page requires authentication, use playwright-cli to register a test user and log in first
402
402
 
403
403
  **Step 2 — Verification**:
@@ -411,7 +411,7 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
411
411
 
412
412
  1. Close the playwright-cli browser: `playwright-cli close`
413
413
  2. Kill the dev server process: `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
414
- 3. Verify port is released: `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
414
+ 3. Verify port is released: `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
415
415
  {{END_IF_BROWSER_TOOL_PLAYWRIGHT}}
416
416
  {{IF_BROWSER_TOOL_OPENCLI}}
417
417
  **Using: opencli** (reuses Chrome logged-in sessions)
@@ -449,7 +449,7 @@ Run page-changing commands sequentially, then run `opencli browser state` to ref
449
449
  **Step 3 — Cleanup**:
450
450
  1. `opencli browser close`
451
451
  2. `{{RUNTIME_HELPER_CMD}} process cleanup-pid <pid-from-.prizmkit/state/browser-dev-server.pid>`
452
- 3. `{{RUNTIME_HELPER_CMD}} process cleanup-port $DEV_PORT`
452
+ 3. `{{RUNTIME_HELPER_CMD}} port check {{DEV_PORT}}`
453
453
  {{END_IF_BROWSER_TOOL_OPENCLI}}
454
454
  {{IF_BROWSER_TOOL_AUTO}}
455
455
  **Tool Selection**: Choose the best browser tool at runtime.
@@ -480,7 +480,7 @@ Append results to `context-snapshot.md`:
480
480
  ```
481
481
  ## Browser Verification
482
482
  Tool: <playwright-cli or opencli>
483
- URL: http://localhost:$DEV_PORT
483
+ URL: http://localhost:{{DEV_PORT}}
484
484
  Dev Server Command: <actual command used>
485
485
  Tool version: <version>
486
486
  Steps executed: [list of commands used]
@@ -502,9 +502,9 @@ If verification fails, log the failure details but continue to commit. Failures
502
502
  - Complex bugs (multi-module, cascading): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`.
503
503
  - Commit prefix: `fix(<scope>):` (not `feat:`).
504
504
 
505
- **6a.** Check if feature already committed:
505
+ **6a.** Check if feature already committed by inspecting recent git history for `{{FEATURE_ID}}`:
506
506
  ```bash
507
- git log --oneline | grep "{{FEATURE_ID}}" | head -3
507
+ git log --oneline
508
508
  ```
509
509
  - 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.
510
510
  - If no existing commit → proceed normally with 6b–6d.
@@ -533,7 +533,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
533
533
  ```bash
534
534
  git status --short
535
535
  ```
536
- 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.
536
+ 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.
537
537
 
538
538
  **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.
539
539
 
@@ -8,7 +8,7 @@ A checkpoint file tracks your progress through this workflow:
8
8
 
9
9
  Use this helper to update checkpoint status. Do not hand-edit `workflow-checkpoint.json` directly.
10
10
 
11
- ```bash
11
+ ```text
12
12
  {{CHECKPOINT_PYTHON_CMD}} \
13
13
  --checkpoint-path {{CHECKPOINT_PATH}} \
14
14
  --step <step-id-or-skill-name> \
@@ -6,18 +6,18 @@ You are running in **headless non-interactive mode** with a FINITE context windo
6
6
 
7
7
  1. **context-snapshot.md is your single source of truth** — After it is built, ALWAYS read context-snapshot.md instead of re-reading individual source files
8
8
  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.
9
- 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.
9
+ 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.
10
10
  4. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
11
11
  5. **One task at a time** — Complete and test one task before starting the next.
12
- 6. **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.
12
+ 6. **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.
13
13
  7. **No intermediate commits** — Do NOT run `git add`/`git commit` during implementation phases. All changes are committed once at the end via `/prizmkit-committer`.
14
- 8. **Capture test output once** — When running test suites during the post-review gate, capture with `<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.
14
+ 8. **Capture test output once** — When running test suites during the post-review gate, 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.
15
15
  9. **Package version verification (HARD CONSTRAINT — BLOCKING)** — Before writing ANY dependency version in `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `pyproject.toml`, or any other dependency manifest:
16
16
  - You MUST verify the real version exists by querying the package registry first:
17
- - npm/Node.js: `npm view <package> dist-tags.latest 2>/dev/null`
18
- - Python/pip: `pip index versions <package> 2>/dev/null | head -1`
19
- - Go: `go list -m -versions <module>@latest 2>/dev/null`
20
- - Rust: `cargo search <crate> --limit 1 2>/dev/null`
17
+ - npm/Node.js: `npm view <package> dist-tags.latest`
18
+ - Python/pip: `pip index versions <package>` and use the first result line
19
+ - Go: `go list -m -versions <module>@latest`
20
+ - Rust: `cargo search <crate> --limit 1`
21
21
  - **NEVER guess or hallucinate version numbers**. If you cannot verify a version, use `"latest"` or `"*"` as a placeholder, or omit the version constraint entirely and let the package manager resolve it
22
22
  - If the registry query fails (network issue, package not found), you MUST either:
23
23
  (a) Use a known-safe version you have high confidence in, OR
@@ -26,4 +26,4 @@ You are running in **headless non-interactive mode** with a FINITE context windo
26
26
  - **This is a BLOCKING gate**: do NOT run `npm install` / `pip install` / `cargo build` / `go mod tidy` until ALL versions in the manifest have been verified or use open constraints
27
27
  - Batch version lookups: query multiple packages in parallel to save time (e.g., run multiple `npm view` commands concurrently)
28
28
  10. **Build artifact hygiene** — After any build/compile command (`go build`, `npm run build`, `tsc`, etc.), ensure the output binary, build directory, generated bundle, or cache directory is ignored by git before the commit phase. Never commit compiled binaries, build output, or generated artifacts.
29
- 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 '<start>,<end>p' <file>` for exact range. 2 consecutive offset errors → STOP Reading that file. Never guess offsets `grep -n '<anchor>'` first.
29
+ 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.
@@ -34,7 +34,7 @@ If tool is `skipped`, do NOT start a dev server and do NOT run browser commands.
34
34
  ```bash
35
35
  {{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
36
36
  ```
37
- 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.
37
+ 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.
38
38
 
39
39
  0e. Read the installed playwright-cli skill (SKILL.md) for workflow guidance. Learn usage: `playwright-cli --help`.
40
40
 
@@ -62,7 +62,8 @@ Construct your verification workflow based on: (1) the playwright-cli skill docu
62
62
 
63
63
  **Step 1 — Start Dev Server + Open (opencli)**:
64
64
  1. Identify and start the dev server (see shared helper commands below)
65
- 2. Open and inspect: `opencli browser open http://localhost:<DEV_PORT> && opencli browser state`
65
+ 2. Open: `opencli browser open http://localhost:<DEV_PORT>`
66
+ 3. Inspect: `opencli browser state`
66
67
  3. If auth needed, opencli reuses Chrome cookies — SSO/OAuth may already be active
67
68
 
68
69
  **Step 2 — Verification (opencli)**:
@@ -71,7 +72,7 @@ Use `opencli browser state` to discover elements with `[N]` indices, then verify
71
72
 
72
73
  Key commands: `state`, `click <N>`, `type <N> "text"`, `get text <N>`, `get value <N>`, `wait text "..."`, `wait selector "..."`, `scroll down`, `eval "(function(){ ... })()"`.
73
74
 
74
- **Chain commands with `&&`**: `opencli browser type 3 "hello" && opencli browser click 7`
75
+ Run page-changing commands sequentially; for example, run `opencli browser type 3 "hello"`, then run `opencli browser click 7`.
75
76
 
76
77
  Always run `state` after page-changing actions to get fresh indices.
77
78
 
@@ -51,7 +51,8 @@ You know this project's tech stack. Detect and start the dev server yourself:
51
51
  ```
52
52
  6. Open the app in opencli and inspect page state:
53
53
  ```bash
54
- opencli browser open http://localhost:<DEV_PORT> && opencli browser state
54
+ opencli browser open http://localhost:<DEV_PORT>
55
+ opencli browser state
55
56
  ```
56
57
  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)
57
58
 
@@ -71,11 +72,14 @@ Key opencli browser commands for verification:
71
72
  - `opencli browser scroll down` — scroll page
72
73
  - `opencli browser eval "(function(){ ... })()"` — read-only JS evaluation for data extraction
73
74
 
74
- **Chain commands aggressively with `&&`** to minimize tool calls:
75
+ **Run commands sequentially and refresh state after page-changing actions**:
75
76
  ```bash
76
- opencli browser open http://localhost:<DEV_PORT> && opencli browser state
77
- opencli browser type 3 "hello" && opencli browser type 4 "world" && opencli browser click 7
78
- opencli browser click 12 && opencli browser wait time 1 && opencli browser state
77
+ opencli browser open http://localhost:<DEV_PORT>
78
+ opencli browser state
79
+ opencli browser type 3 "hello"
80
+ opencli browser type 4 "world"
81
+ opencli browser click 7
82
+ opencli browser state
79
83
  ```
80
84
 
81
85
  **IMPORTANT**: Always run `opencli browser state` after page-changing actions (open, click on links, scroll) to get fresh element indices. Never guess indices.
@@ -34,7 +34,7 @@ Use this output to determine the correct commands for your verification steps. D
34
34
  ```bash
35
35
  {{RUNTIME_HELPER_CMD}} platform skill playwright-cli --prefix
36
36
  ```
37
- 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.
37
+ 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.
38
38
 
39
39
  0d. Read the installed playwright-cli skill for workflow guidance:
40
40
  After skill installation, read the skill's SKILL.md to understand recommended workflows and patterns. Use these patterns to construct your verification flow — do NOT invent your own patterns if the skill provides them.
@@ -2,7 +2,7 @@
2
2
 
3
3
  **a.** Check if feature already committed:
4
4
  ```bash
5
- git log --oneline | grep "{{FEATURE_ID}}" | head -3
5
+ git log --oneline
6
6
  ```
7
7
  - If a commit for `{{FEATURE_ID}}` already exists → **skip d** (do NOT run /prizmkit-committer, do NOT run git reset, do NOT stage or unstage anything). Proceed directly to e Final verification.
8
8
  - If no existing commit → proceed normally with b–d.
@@ -30,7 +30,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
30
30
  ```bash
31
31
  git status --short
32
32
  ```
33
- 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.
33
+ 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.
34
34
 
35
35
  **f.** Write completion summary for downstream dependency context:
36
36
 
@@ -23,7 +23,7 @@ This single commit includes: feature code + tests + .prizmkit/prizm-docs/ update
23
23
  ```bash
24
24
  git status --short
25
25
  ```
26
- 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.
26
+ 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.
27
27
 
28
28
  **e.** Write completion summary for downstream dependency context:
29
29
 
@@ -4,7 +4,7 @@
4
4
 
5
5
  Before starting, check plan.md Tasks:
6
6
  ```bash
7
- grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || true
7
+ {{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
8
8
  ```
9
9
  - If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
10
10
  - If non-zero → implement directly below.
@@ -4,7 +4,7 @@
4
4
 
5
5
  Before starting, check plan.md Tasks:
6
6
  ```bash
7
- grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || true
7
+ {{RUNTIME_HELPER_CMD}} text count .prizmkit/specs/{{FEATURE_SLUG}}/plan.md --pattern "- [ ]"
8
8
  ```
9
9
  - If result is `0` (all tasks already `[x]`) → **SKIP to Review**.
10
10
  - If non-zero → implement directly below.