create-harness-vibe-coding 0.8.16 → 0.8.17

package/src/generator.js

@@ -70,6 +70,9 @@ const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates', 'common');
 const OPTIONAL_DIR = path.resolve(__dirname, '..', 'templates', 'optional');
 const OPTIONAL_CATALOG = path.join(OPTIONAL_DIR, 'catalog.json');
 const VALID_CONFLICT_POLICIES = new Set(['fail', 'skip', 'backup', 'overwrite']);
+const RETIRED_OPTION_MESSAGES = new Map([
+  ['browser-e2e', 'Optional workflow "browser-e2e" has been retired; wf-browser is built in by default. Use /wf-browser, $wf-browser, or /skills wf-browser instead.'],
+]);
 const EMPTY_DIRS = [
   'tests',
 ];
@@ -154,6 +157,7 @@ function resolveOptionalSelection({
   const recommendationsById = new Map(externalRecommendations(catalog).map(item => [item.id, item]));
   const selected = [];
   const errors = [];
+  const warnings = [];
 
   if (preset) {
     if (!catalog.presets[preset]) {
@@ -168,12 +172,16 @@ function resolveOptionalSelection({
   const ids = [...new Set(selected)];
   const withoutIds = [...new Set(normalizeOptionList(withoutOptions))];
   for (const id of ids) {
-    if (!skillsById.has(id)) {
+    if (RETIRED_OPTION_MESSAGES.has(id)) {
+      warnings.push(RETIRED_OPTION_MESSAGES.get(id));
+    } else if (!skillsById.has(id)) {
       errors.push(`Unknown optional skill "${id}". Run --list-options to see available options.`);
     }
   }
   for (const id of withoutIds) {
-    if (!skillsById.has(id)) {
+    if (RETIRED_OPTION_MESSAGES.has(id)) {
+      warnings.push(`Optional workflow "${id}" is retired and built in/no-op for --without.`);
+    } else if (!skillsById.has(id)) {
       errors.push(`Unknown optional skill in --without "${id}". Run --list-options to see available options.`);
     }
   }
@@ -186,13 +194,14 @@ function resolveOptionalSelection({
   }
 
   const withoutSet = new Set(withoutIds);
-  const selectedIds = ids.filter(id => !withoutSet.has(id));
+  const selectedIds = ids.filter(id => !withoutSet.has(id) && !RETIRED_OPTION_MESSAGES.has(id));
 
   return {
     catalog,
     selectedSkills: errors.length ? [] : selectedIds.map(id => skillsById.get(id)),
     selectedRecommendations: errors.length ? [] : recommendationIds.map(id => recommendationsById.get(id)),
     errors,
+    warnings,
   };
 }
 
@@ -350,7 +359,7 @@ function readOwnershipManifest() {
  *
  * Manifest-present: candidate set = manifest.frameworkOwned paths UNION the
  * selected optional skills' manifest.optionalOwned paths. This includes optional
- * skill paths like browser-e2e (fixing the bug where same-name user files at
+ * skill paths like ui-ux-review (fixing the bug where same-name user files at
  * optional-skill paths were clobbered).
  *
  * Manifest-absent (null): candidate set = all fileSpec dests (the exact set of
@@ -493,7 +502,6 @@ function nextBackupPath(destPath) {
 
 function registerOptionalContent(file, content, selectedSkills) {
   if (!selectedSkills.length) return content;
-  const hasBrowserE2e = selectedSkills.some(skill => skill.id === 'browser-e2e');
 
   if (file === 'Harness/MEMORY.md') {
     const lines = selectedSkills.map(skill => (
@@ -509,25 +517,7 @@ function registerOptionalContent(file, content, selectedSkills) {
     const lines = selectedSkills.map(skill => (
       `- [${skill.title}](workflows/${skill.id}.md) - ${skill.description}`
     ));
-    let next = content;
-    if (hasBrowserE2e) {
-      next = next.replace(
-        '| Optional workflow installed |',
-        '| Browser E2E testing or automation | /wf-browser, $wf-browser, browser, e2e, web automation, screenshot verify, page test, browser test, Playwright, CDP | [workflows/browser-e2e.md](workflows/browser-e2e.md), [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) | UI/API contract, CLI commands, screenshots, traces, validation matrix |\n| Optional workflow installed |',
-      );
-      next = next.replace(
-        '| `/wf-readme [task]` |',
-        '| `/wf-browser [task]` | `$wf-browser [task]` | Optional browser automation/E2E workflow when `browser-e2e` is installed |\n| `/wf-readme [task]` |',
-      );
-    }
-    return `${next.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
-  }
-
-  if ((file === '.claude/commands/wf-help.md' || file === '.opencode/commands/wf-help.md') && hasBrowserE2e) {
-    return content.replace(
-      '| `/wf-readme <task>` |',
-      '| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |\n| `/wf-readme <task>` |',
-    );
+    return `${content.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
   }
 
   return content;
@@ -595,6 +585,7 @@ export function generate({
   };
 
   const optional = resolveOptionalSelection({ withOptions, withoutOptions, preset, externalOptions });
+  warnings.push(...optional.warnings);
   const fileSpecs = [
     ...createCoreFileSpecs(),
     ...createOptionalFileSpecs(optional.selectedSkills),

package/src/index.js

@@ -57,7 +57,7 @@ if (showHelp) {
   console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
   console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --dry-run');
   console.log('    npx create-harness-vibe-coding@latest legacy ./legacy -y --on-conflict skip');
-  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,browser-e2e');
+  console.log('    npx create-harness-vibe-coding@latest web ./web -y --with ts-react-frontend,ui-ux-review');
   console.log('    npx create-harness-vibe-coding@latest web ./web -y --preset web-app');
   console.log('    npx create-harness-vibe-coding@latest api ./api -y --preset fullstack --without github-pr-review');
   console.log('');

package/templates/common/.claude/commands/wf-auto-spark.md

@@ -0,0 +1,16 @@
+---
+description: Run perpetual inspiration mode via the wf-auto-spark skill
+---
+
+# /wf-auto-spark
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-auto-spark/SKILL.md` (mirror: `.agents/skills/wf-auto-spark/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF-AUTO-SPARK.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-auto-spark/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf-auto.md

@@ -0,0 +1,16 @@
+---
+description: Run perpetual adaptive auto-optimization via the wf-auto skill
+---
+
+# /wf-auto
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-auto/SKILL.md` (mirror: `.agents/skills/wf-auto/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF-AUTO.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-auto/SKILL.md` and follow it in place.

package/templates/{optional/skills/browser-e2e/.opencode → common/.claude}/commands/wf-browser.md

@@ -10,7 +10,7 @@ static help or script command.
 1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
 2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
 3. Execute per the skill adapter `.claude/skills/wf-browser/SKILL.md` (mirror: `.agents/skills/wf-browser/SKILL.md`).
-4. Do not duplicate the workflow here. The skill adapter and `Harness/workflows/browser-e2e.md` are authoritative.
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/protocols/HARNESS_BRIDGE.md` are authoritative.
 
 If this runtime cannot invoke the skill directly, read
 `.claude/skills/wf-browser/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf-help.md

@@ -3,6 +3,9 @@
 Return this help table directly. Do not invoke a skill, do not start WF mode,
 do not dispatch agents, and do not edit files.
 
+Codex compatibility: `$wf-help` or `/skills wf-help` loads the `wf-help` shim,
+which returns this same table without loading `Harness/MEMORY.md` or entering WF.
+
 | Command | Type | Usage | Purpose |
 | --- | --- | --- | --- |
 | `/wf-help` | direct command | `/wf-help` | Show this command table. |
@@ -12,14 +15,14 @@ do not dispatch agents, and do not edit files.
 | `/wf-auto-spark` | workflow skill | `/wf-auto-spark` | Perpetual inspiration mode with roadmap anchoring and external spark search. |
 | `/wf-review <focus>` | workflow skill | `/wf-review security and test coverage` | Peer CLI review through Claude/Codex/OpenCode, with reviewer subagent fallback. |
 | `/wf-learn` | workflow skill | `/wf-learn` | Force context-master -> memory-master learning cycle after repeated failures or closeout. |
-| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence when installed. |
+| `/wf-browser <task>` | workflow skill | `/wf-browser verify checkout flow` | Built-in browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |
 | `/wf-readme <task>` | workflow skill | `/wf-readme polish quickstart` | Preserve, merge, or improve README docs without trampling existing project documentation. |
 | `/wf-update` | direct command | `/wf-update` | Check/apply Harness scaffold updates with safe file classification and conflict handling. |
 | `/wf-remove` | workflow skill | `/wf-remove` | Safely remove Harness files while preserving project/user data unless explicitly purged. |
 
 Source of truth: `Harness/README.md#Skill Commands` plus installed skills under
-`.claude/skills/` (Claude Code) or `.agents/skills/` (Codex). In OpenCode the
-same skills load from `.claude/skills/`, `.agents/skills/`, and `.opencode/skills/`.
-In OpenCode, every workflow command above is also visible as a thin command
-wrapper under `.opencode/commands/` (e.g. `/wf`, `/wf-max`); each wrapper only
-routes to the matching skill adapter and does not duplicate the workflow.
+`.claude/skills/` (Claude Code and OpenCode adapters) or `.agents/skills/`
+(Codex). In OpenCode, every workflow command above is visible as a thin command
+wrapper under `.opencode/commands/` (e.g. `/wf`, `/wf-max`); each wrapper routes
+to the matching `.claude/skills/<command>/SKILL.md` adapter and does not
+duplicate the workflow.

package/templates/common/.claude/commands/wf-learn.md

@@ -0,0 +1,16 @@
+---
+description: Run the context-master -> memory-master learning cycle via the wf-learn skill
+---
+
+# /wf-learn
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-learn/SKILL.md` (mirror: `.agents/skills/wf-learn/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/protocols/MEMORY_PROTOCOL.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-learn/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf-max.md

@@ -0,0 +1,20 @@
+---
+description: Run WF-MAX with mandatory subagent fan-out and recorded degradation
+---
+
+# /wf-max
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Load and follow `.claude/skills/wf-max/SKILL.md` (mirror: `.agents/skills/wf-max/SKILL.md`) and `Harness/specs/workflows/WF-MAX.md`.
+3. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+4. MUST attempt native runtime subagent fan-out before planning is considered complete:
+   - start `task-scribe` when available for task ledger/state;
+   - start W0 exploration through manager/explorer/researcher roles with disjoint read sets;
+   - when running in OpenCode, require project `opencode.json` to have `subagent_depth >= 2` and manager agents to have `permission.task` allowlists for manager -> worker fan-out;
+   - if nested manager fan-out is unavailable, dispatch leaf workers directly from the primary agent with exact WF-MAX dispatch packets.
+5. In every runtime, MUST attempt native subagent fan-out before implementation planning is considered complete; never silently continue as a solo controller.
+6. If native fan-out fails, record `fanoutAttempted: true`, runtime, channel tried, agents requested, failure/degradation reason, and the fallback path in `Harness/tasks/<task-id>/PLAN.md` or `PROGRESS.md`.
+7. Continue with WF-Max-Useful by default or WF-Max-Strict only when the user explicitly requests strict mode.

package/templates/common/.claude/commands/wf-readme.md

@@ -0,0 +1,16 @@
+---
+description: Run the README preservation and improvement workflow via the wf-readme skill
+---
+
+# /wf-readme
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-readme/SKILL.md` (mirror: `.agents/skills/wf-readme/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and the project root \`README.md\` ownership rules are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-readme/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf-remove.md

@@ -0,0 +1,16 @@
+---
+description: Run safe harness removal via the wf-remove skill
+---
+
+# /wf-remove
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-remove/SKILL.md` (mirror: `.agents/skills/wf-remove/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/scripts/wf-remove.mjs` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-remove/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf-review.md

@@ -0,0 +1,16 @@
+---
+description: Run peer CLI or reviewer-subagent review via the wf-review skill
+---
+
+# /wf-review
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf-review/SKILL.md` (mirror: `.agents/skills/wf-review/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and the wf-review peer-review contract are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf-review/SKILL.md` and follow it in place.

package/templates/common/.claude/commands/wf.md

@@ -0,0 +1,16 @@
+---
+description: Run the tiered WF workflow (WF-Light/Standard/Full) via the wf skill
+---
+
+# /wf
+
+This is a **workflow command**, not a direct command. Do not execute it as a
+static help or script command.
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` (index only per Memory Preflight), then `Harness/README.md`.
+2. Preserve cache-first order per `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`.
+3. Execute per the skill adapter `.claude/skills/wf/SKILL.md` (mirror: `.agents/skills/wf/SKILL.md`).
+4. Do not duplicate the workflow here. The skill adapter and `Harness/specs/workflows/WF.md` are authoritative.
+
+If this runtime cannot invoke the skill directly, read
+`.claude/skills/wf/SKILL.md` and follow it in place.

package/templates/common/.claude/rules/ecc/common.md

@@ -8,7 +8,7 @@ alwaysApply: true
 ## Context
 
 - Start with `CLAUDE.md`. When `Harness/` exists, also read `Harness/memory/startup-hints.md` (L2 lightweight digest, not full router).
-- When the user explicitly invokes a `/wf-*` workflow command, excluding `/wf-help` and `/wf-update`, load `Harness/MEMORY.md` and `Harness/README.md`.
+- When the user explicitly invokes a workflow command (`/wf-*`, `$wf-*`, or `/skills wf-*`), excluding `/wf-help`, `$wf-help`, `/skills wf-help`, `/wf-update`, `$wf-update`, and `/skills wf-update`, load `Harness/MEMORY.md` and `Harness/README.md`.
 - For simple single-step tasks without `/wf-*`, operate in direct mode: skip the Harness router and execute directly.
 - Do not bulk-read `Harness/`. Load by router trigger.
 - Keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current when work has multiple steps, files, or agents.

package/templates/common/.claude/skills/wf-browser/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: wf-browser
+description: Built-in browser automation and E2E verification workflow. Use for Claude /wf-browser, Codex $wf-browser or /skills wf-browser, Browser Use, Playwright, Chrome DevTools/CDP, screenshots, forms, UI verification, and browser-visible acceptance.
+---
+
+# WF Browser
+
+This skill is the single Browser E2E entry. Do not use or create a separate
+browser E2E skill. The browser evidence contract lives here plus
+`Harness/specs/protocols/HARNESS_BRIDGE.md`.
+
+## Invocation
+
+- Claude Code: use `/wf-browser <task>` or select the `wf-browser` skill.
+- Codex CLI or IDE: use `$wf-browser <task>` or `/skills` then choose `wf-browser`.
+- OpenCode: use `/wf-browser <task>`.
+
+## Load
+
+- `CLAUDE.md`
+- `Harness/MEMORY.md` index only per Memory Preflight
+- `Harness/README.md`
+- `Harness/specs/protocols/HARNESS_BRIDGE.md`
+- Project run/build/test instructions
+- Official Browser Use skill text from `browser-use skill` when Browser Use is used
+
+## Cache Discipline
+
+Follow `Harness/specs/runtime/context-loading.md#Cache-First Context Contract`: keep stable
+workflow docs first, then append only the current URL, selectors, concise browser
+state, screenshot paths, trace paths, and failing assertions. Do not paste full
+accessibility trees, browser logs, screenshots, videos, or network dumps into
+task state.
+
+## Browser Evidence Contract
+
+Every browser-visible claim needs real browser evidence:
+
+1. URL and viewport/browser scope.
+2. Stable selector contract using `data-testid` and accessible labels/roles.
+3. Real interaction evidence from Browser Use, Playwright, Chrome DevTools/CDP,
+   or documented manual browser checks.
+4. Console and network checks for runtime exceptions, failed requests, and
+   frontend-backend side effects.
+5. Screenshot, trace, video, state snapshot, or command output path.
+6. AC-by-AC validation matrix when acceptance criteria exist.
+
+No `data-testid` or stable accessible selector, no UI acceptance. No API
+contract, no backend integration acceptance.
+
+## Controllable UI Contract
+
+UI built for browser control must expose targetable, user-meaningful controls:
+
+| Category | Required control surface |
+| --- | --- |
+| Inputs | `<label>` association or `aria-label`, `data-testid`, disabled/invalid states, deterministic placeholder only as fallback |
+| Buttons | accessible name, `data-testid`, disabled/loading state, no icon-only button without `aria-label` |
+| Filters | stable test id for input/menu/chip, selected state, clear/reset control |
+| Rows/items | stable row/item test id plus durable item key such as `data-row-id`; avoid index-only targeting |
+| Empty state | visible empty container with `data-testid="empty-state"` or feature-specific equivalent |
+| Error state | inline error/toast/banner with stable test id and accessible role when appropriate |
+| Loading state | stable spinner/skeleton/progress test id; verify duplicate submit prevention |
+
+Required coverage targets: inputs, buttons, filters, rows, empty/error/loading states.
+
+Selector priority:
+
+1. `data-testid`
+2. accessible labels/roles
+3. visible text for stable user-facing copy
+
+Do not use generated class names, brittle CSS chains, XPath, DOM index selectors,
+or raw coordinates as the primary test contract. Coordinates are acceptable only
+after locating an element through the accessibility tree or when testing canvas
+or other non-DOM UI.
+
+## Browser Use CLI
+
+Use the current script-style Browser Use CLI; old `browser-use open/state/click/screenshot/input/wait` subcommands are removed from the current CLI and must not be used in new docs or tests.
+
+Health check:
+
+```bash
+browser-use --doctor
+browser-use skill
+```
+
+PowerShell smoke:
+
+```powershell
+@'
+new_tab("https://example.com")
+wait_for_load()
+print(page_info())
+path = capture_screenshot("Harness/tasks/<task-id>/evidence/example.png")
+print(path)
+'@ | browser-use
+```
+
+Bash smoke:
+
+```bash
+browser-use <<'PY'
+new_tab("https://example.com")
+wait_for_load()
+print(page_info())
+path = capture_screenshot("Harness/tasks/<task-id>/evidence/example.png")
+print(path)
+PY
+```
+
+Useful helpers include `new_tab(url)`, `goto_url(url)`, `page_info()`,
+`capture_screenshot(path)`, `click_at_xy(x, y)`, `type_text(text)`,
+`fill_input(selector, text)`, `press_key(key)`, `scroll(x, y)`, `js(code)`,
+`cdp(method, ...)`, `wait_for_load()`, `wait_for_element(selector)`,
+`list_tabs()`, `switch_tab(target)`, and `close_tab(target)`.
+
+For local Chrome connection problems, run `browser-use --doctor`. If Chrome asks
+to allow remote debugging, stop and ask the user to approve the browser prompt.
+
+## Playwright Test Pattern
+
+Prefer Playwright for repeatable E2E tests and Browser Use/CDP for exploratory
+or interactive checks.
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test("AC-001 user can submit the form", async ({ page }) => {
+  const requests: Array<{ url: string; method: string; postData: string | null }> = [];
+  page.on("request", request => {
+    requests.push({
+      url: request.url(),
+      method: request.method(),
+      postData: request.postData(),
+    });
+  });
+
+  await page.goto("/example");
+  await page.getByTestId("email-input").fill("test@example.com");
+  await page.getByRole("button", { name: "Submit" }).click();
+
+  await expect(page.getByTestId("loading-spinner")).toBeHidden();
+  await expect(page.getByTestId("result-row")).toBeVisible();
+  expect(requests.some(request => request.url.includes("/api/example"))).toBe(true);
+});
+```
+
+## Chrome DevTools / CDP Checklist
+
+- [ ] Record URL, port, browser, and viewport.
+- [ ] Verify available Browser Use, Playwright, CDP, MCP, or manual tooling.
+- [ ] Check not just HTTP 200.
+- [ ] Verify no runtime exceptions, console errors, and failed network requests.
+- [ ] Confirm stable accessible labels/roles or `data-testid` on interactive elements.
+- [ ] Test the critical flow end-to-end with real user actions.
+- [ ] Capture screenshot, trace, video, state snapshot, or result artifact paths.
+- [ ] Produce an AC-by-AC validation matrix.
+- [ ] Clean up dev server or browser processes that the task started.
+
+## Security
+
+- Never log or screenshot real credentials, API keys, tokens, or private data.
+- Use placeholder credentials in examples.
+- Ask before using a real Chrome profile because it contains cookies and private sessions.
+- Ask before leaving a remote/cloud browser running.
+- For scraping or repeated automated visits, confirm the user owns the target or has permission.
+
+## Return
+
+- Commands or scripts run
+- Selectors used
+- Screenshot/trace/video/state paths
+- Verified flows and AC matrix
+- Failures and remaining risks

package/templates/common/.claude/skills/wf-help/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: wf-help
+description: Codex compatibility: use $wf-help or /skills wf-help in Codex to show the Harness WF command table. Claude Code and OpenCode use the direct /wf-help command.
+---
+
+# WF Help Adapter
+
+This skill is a Codex compatibility shim. It does not start WF mode, dispatch
+agents, or edit files.
+
+## Invocation
+
+- Codex CLI or IDE: use `$wf-help` or `/skills` then choose `wf-help`.
+- Claude Code: use `/wf-help` direct command from `.claude/commands/wf-help.md`.
+- OpenCode: use `/wf-help` direct command from `.opencode/commands/wf-help.md`.
+
+## Load
+
+- `.claude/commands/wf-help.md`
+
+## Rules
+
+Return the command table from `.claude/commands/wf-help.md` directly.
+Do not load `Harness/MEMORY.md`, do not enter WF, and do not invoke workflow
+skills while answering help.
+
+## Return
+
+- WF command table
+- One short note that Codex uses `$wf-*` or `/skills wf-*` for skill-backed entries

package/templates/common/.claude/skills/wf-max/SKILL.md

@@ -75,16 +75,30 @@ WF-Max-Strict (explicit override): user says `--strict`, `strict wf-max`, or
 
 ## Fan-Out Discipline
 
+- MUST attempt native subagent fan-out before implementation planning is
+  considered complete. A solo controller path is allowed only after recording
+  `fanoutAttempted: true`, the runtime, channel tried, agents requested,
+  limit/cap facts, failure reason, and fallback path in task state.
 - Use as many useful subagents as the runtime safely allows.
-- Codex capacity may be configured through official `agents.max_threads` and
-  `agents.max_depth`; generated Harness config defaults to
-  `.codex/config.toml` with `max_threads = 12` and `max_depth = 1`.
+- Claude Code documents session, concurrent, and spawn-depth subagent caps:
+  `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION`,
+  `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and
+  `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`; Harness still enforces its lower
+  WF-MAX caps unless the user explicitly approves a task-local override.
+- Codex capacity is configured through official
+  `agents.max_concurrent_threads_per_session`; `agents.max_threads` is a
+  legacy alias. Do not scaffold scalar `[agents]` caps into
+  `.codex/config.toml`; codex-cli 0.144.x can reject them during TUI
+  `skills/list`. Treat Codex capacity as a runtime probe and manage Harness
+  caps in the dispatch ledger unless the installed Codex version is verified
+  with `codex --strict-config doctor`.
+- OpenCode uses `subagent_depth` for nesting. WF-MAX manager -> worker fan-out
+  requires `subagent_depth >= 2` plus manager `permission.task` allowlists; the
+  scaffold sets `subagent_depth = 2`.
 - Close completed agents before declaring the pool exhausted.
 - If Codex remains bottlenecked, ask the user before raising
-  `agents.max_threads` above the scaffold default. Do not silently edit project
-  or global Codex config.
-- Keep `agents.max_depth = 1` unless the user explicitly approves recursive
-  delegation.
+  `agents.max_concurrent_threads_per_session`. Do not silently edit project or
+  global Codex config.
 - If the current runtime is exhausted, overflow to a peer CLI with explicit
   dispatch packets: `claude -p`, `codex exec`, or
   `opencode run --agent <role> --dir .`.

package/templates/common/.codex/config.toml

@@ -1,5 +1,3 @@
-[agents]
-# Harness WF-MAX default: higher than Codex's unset default of 6.
-# Keep depth at 1 unless the user explicitly approves recursive delegation.
-max_threads = 12
-max_depth = 1
+# Codex project config intentionally avoids WF-MAX capacity defaults.
+# codex-cli 0.144.x can reject scalar agent-capacity caps during TUI skills/list.
+# WF-MAX manages fan-out caps in Harness docs and task state instead.