npm - create-harness-vibe-coding - Versions diffs - 0.6.1 → 0.6.3 - Mend

create-harness-vibe-coding 0.6.1 → 0.6.3

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 (10) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {

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

@@ -20,7 +20,7 @@ Cross-model peer review. Invokes the OTHER agent CLI to review changes from a fr
 - Check `which codex && echo CODEX || echo NO_CODEX` to detect Codex
 - Check `which claude && echo CLAUDE || echo NO_CLAUDE` to detect Claude
 - Use the OTHER CLI — the one NOT running this session. Never self-review.
-- If only one CLI is available: warn, then use it (single-model review is better than none).
+- If only one CLI is available: warn the user, suggest installing the other CLI. Do NOT proceed with self-review.
 ## Flow

package/templates/common/.claude/settings.json CHANGED Viewed

@@ -18,6 +18,7 @@
       "WebSearch"
     ],
     "deny": [
+      "EnterPlanMode",
       "Bash(rm -rf *)",
       "Bash(sudo *)",
       "Bash(curl *)",

package/templates/common/.claude/skills/wf-review/SKILL.md CHANGED Viewed

@@ -14,7 +14,7 @@ Cross-model peer review via the OTHER agent CLI. Fresh eyes on your changes.
 ## How It Works
-1. **Detect runtime**: Check `which codex` and `which claude`
+1. **Detect available CLIs**: Check `which codex` and `which claude`. Use the OTHER CLI — never the one running this session.
 2. **Prepare context**: Gather diff (`git diff`), relevant architecture docs, the specific question
 3. **Invoke the OTHER CLI** — the one we're NOT currently running under
 4. **Read and synthesize**: Present the raw output, then add analysis
@@ -25,7 +25,7 @@ Cross-model peer review via the OTHER agent CLI. Fresh eyes on your changes.
 |---|---|
 | Claude → Codex | `git diff \| codex exec "..."` (include full diff, not just commit message) |
 | Codex → Claude | `git diff \| claude -p "..."` |
-| Either (fallback) | try the other CLI; if only one installed, use it (still better than self-review) |
+| Either (fallback) | warn user, suggest installing the other CLI. Do NOT proceed with same-model review. |
 **Anti-self-review rule**: Detect which runtime we're in, then use the OTHER one. Never invoke the same CLI that's running the session.

package/templates/common/docs/README.md CHANGED Viewed

@@ -103,7 +103,7 @@ Routing priority: if a request explicitly says `/wf <task>`, `/wf-max [task]`, `
 ```text
 Harness/README.md                  router only
 Harness/MEMORY.md                  resource index
-Harness/PLAN.md                    active project plan
+Harness/PLAN.md                    project-level plan (redirects to tasks/<id>/PLAN.md)
 Harness/SETUP.md                   install/bootstrap contract
 Harness/PROGRESS.md                global task index and cross-task decisions
 Harness/tasks/<id>/PROGRESS.md     per-task progress, phase, heartbeat

package/templates/common/docs/harness/architecture.md CHANGED Viewed

@@ -1,114 +1,126 @@
-# Harness Architecture — {{projectName}}
+# Harness Architecture - create-harness-vibe-coding
-> **Responsibility**: Defines the system layering structure, component overview, and key design decisions.
-> **Does NOT cover**: Code details (AI can read code), API documentation (placed in docstrings).
->
-> Philosophical sources: arc42 Chapter 5 (Building Block View) + C4 Model Level 3 (Component) + matklad's lightweight ARCHITECTURE.md.
+> **Responsibility**: Define the repository structure and scaffold generation boundaries.
+> **Does NOT cover**: Generated target-project business architecture.
 ---
 ## 1. Layering Rules
-<!-- This is the hardest constraint in the entire architecture. Each layer's "allowed dependencies" must be explicit. -->
+```text
+bin/
+  CLI executable shim. Calls src/index.js.
-```
-┌──────────────────────────┐
-│     interfaces/          │  ← User entry (CLI / API / UI)
-│     May depend on: harness│
-├──────────────────────────┤
-│     harness/             │  ← Generic runtime shell: orchestration,
-│     May depend on:        │     security, auditing, scheduling
-│       application         │     Contains no business rules
-├──────────────────────────┤
-│     application/         │  ← Business use-case orchestration
-│     May depend on: domain │
-├──────────────────────────┤
-│     domain/              │  ← Pure business objects + port protocols
-│     Only depends on:      │     Depends on no external implementations
-│       standard library    │
-├──────────────────────────┤
-│     infrastructure/      │  ← Adapter implementations (data sources,
-│     Implements domain     │     external services)
-│       ports               │
-└──────────────────────────┘
+src/
+  CLI orchestration and scaffold generation logic.
+  May read templates/ and write the chosen target directory.
+templates/
+  Source of generated scaffold assets.
+  Must stay declarative: markdown, skill files, agent files, scripts, and optional workflow docs.
+Harness/ and .claude/
+  Dogfood runtime for this repository's own agent work.
+  Must not be treated as package source unless intentionally copied into templates/.
+tests/
+  Node test suite for CLI behavior, generator behavior, package contents, and generated harness validation.
 ```
-**Hard Constraints**:
-- domain must never import infrastructure/ or interfaces/
-- application only depends on domain
-- harness coordinates workflows but contains no domain business rules
-- All cross-layer communication goes through port protocols defined in domain
+Hard constraints:
----
+- `templates/common/**` and `templates/optional/**` are the source of generated output.
+- Root `Harness/**` is this repository's operating harness; changing it does not change generated projects.
+- Generated output paths are normalized by `harnessDest()` in `src/generator.js`.
+- Existing-project safety is owned by conflict planning in `src/generator.js`, not by template prose alone.
+- Package publication is constrained by `package.json#files`; root dogfood files are not package contents.
 ## 2. Interface Decoupling
-Use interfaces or ports to protect real boundaries, not to create abstraction for its own sake.
-- Define a port when code crosses a layer, process, network, storage, SDK, browser, or permission boundary.
-- Keep domain and application logic independent from infrastructure adapters.
-- Pass data through explicit contracts instead of reaching into another feature's internals.
-- Prefer direct calls inside the same cohesive module when there is only one caller, one implementation, and no boundary to protect.
-- Avoid speculative abstraction: do not add factories, plugin systems, service locators, generic repositories, or config layers until the feature has a concrete second use or a real testability/replacement need.
+Use interfaces and module boundaries to protect real seams in the generator, not to decorate straightforward code.
----
+- `src/index.js` owns CLI/user interaction; `src/generator.js` owns planning and file writes.
+- Template files are declarative inputs; source code should not depend on root dogfood `Harness/**`.
+- Optional catalog structure is the extension contract for presets and optional skills.
+- Avoid speculative abstraction: do not add plugin systems, generic runners, extra config layers, or service containers until a real second use or testability boundary exists.
+- When a boundary is real, express it with a small data contract and test it through generated output behavior.
 ## 3. State Design
-State must have one owner, legal transitions, and observable recovery behavior.
+State in this repo should be explicit, serializable, and owned by one layer.
-- Identify durable state, runtime cache, derived UI state, external system state, and audit/event history separately.
-- Name the owner of each state slice; do not let UI, application services, and infrastructure all mutate the same state directly.
-- Model long-running workflows with explicit states, guards, and failure transitions in `Harness/state-machines.md`.
-- Store resumable progress and recovery decisions in `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` or project-owned durable storage, not only in chat.
-- Keep state minimal: derive values when cheap, persist only what must survive reload, retry, or handoff.
+- Generator plan state is computed in memory and returned as `plan`/`summary`; file writes consume that plan instead of re-deciding conflicts.
+- Filesystem state is authoritative only through existence/type checks and write results.
+- Optional selection state comes from CLI flags plus `templates/optional/catalog.json`; do not duplicate it in template prose.
+- Release state lives in `package.json`, npm, git tags, and GitHub; document commands in `README.md`, not `CLAUDE.md`.
+- Long-running agent work records resumable status in `Harness/tasks/<task-id>/PLAN.md#Heartbeat`.
----
+## 4. Core Components
-## 4. Harness Core Components
+### 4.1 CLI Entry
-### 4.1 Runner / Loop
+- **Location**: `bin/create-harness-vibe-coding.js`, `src/index.js`
+- **Responsibility**: Parse flags, handle interactive/non-interactive modes, print plans/results, and call the generator.
+- **Does NOT handle**: Template walking, conflict classification, or file writing internals.
-- **Responsibility**: Drives a task from input to completion: loading context, calling application use-cases, handling stop conditions.
-- **Design Decision**:
-  - Runner only orchestrates, does not interpret domain meaning — Rationale: keeps harness reusable across different business domains
-  - Stop conditions are explicitly modeled — Rationale: prevents agent loops from running indefinitely or silently half-completing
-- **Does NOT handle**: Business rules, domain object creation details, external service implementations
+### 4.2 Prompt Layer
-### 4.2 Permission Policy
+- **Location**: `src/prompts.js`
+- **Responsibility**: Ask basic interactive npx questions: project name and target directory.
+- **Does NOT handle**: Agent-link install intake. That matrix is read by coding agents from `README.md` and `Harness/SETUP.md`.
-- **Responsibility**: Decides whether a given tool, file, network, or external action is allowed to execute.
-- **Design Decision**:
-  - High-risk actions are denied by default, allow rules are explicitly declared — Rationale: the platform must first guarantee security boundaries
-- **Does NOT handle**: Judging whether a business action is correct
+### 4.3 Generator Core
-### 4.3 Event Bus / Audit Trail
+- **Location**: `src/generator.js`
+- **Responsibility**: Resolve optional selections, map template paths to destination paths, detect conflicts, render templates, register optional workflows, and write files.
+- **Critical functions**:
+  - `harnessDest()` maps legacy template source paths such as `docs/harness/*` into generated root `Harness/*`.
+  - `createPlan()` and `addFileActions()` classify directories and file actions before writes.
+  - `registerOptionalContent()` updates generated router/memory docs when optional workflows are selected.
-- **Responsibility**: Records task lifecycle, tool invocations, failures, human approvals, and final results.
-- **Design Decision**:
-  - Events are append-only, audit records cannot be overwritten in place — Rationale: facilitates replay, debugging, and post-mortem analysis
-- **Does NOT handle**: Saving final data on behalf of business systems
+### 4.4 Template Assets
-### 4.4 State / Checkpoint Store
+- **Location**: `templates/common/**`, `templates/optional/**`
+- **Responsibility**: Define generated `CLAUDE.md`, `AGENTS.md`, `README.md`, `Harness/**`, `.claude/**`, optional skills, and optional workflows.
+- **Does NOT handle**: Existing-project decisions. Templates state contracts; generator and agents apply them safely.
-- **Responsibility**: Saves recoverable state, context summaries, task progress, and interrupt points.
-- **Design Decision**:
-  - State format must be serializable — Rationale: enables replay, resume, testing, and migration
-- **Does NOT handle**: Long-term business database modeling
+### 4.5 Validator
-### 4.5 Tool Registry
+- **Source template**: `templates/common/scripts/validate-harness.mjs`
+- **Generated location**: `Harness/scripts/validate-harness.mjs`
+- **Responsibility**: Validate required scaffold files, skill/agent registrations, router invariants, optional workflow registrations, and strict project-fact placeholders.
-- **Responsibility**: Registers callable tools along with their input/output contracts, permission labels, and error semantics.
-- **Design Decision**:
-  - Tool contracts explicitly specify input, output, errors, and side effects — Rationale: reduces the probability of agent tool misuse
-- **Does NOT handle**: Internal business implementation of tools
+### 4.6 Dogfood Runtime
----
+- **Location**: root `Harness/**`, `.claude/**`, `CLAUDE.md`, `AGENTS.md`, `MEMORY.md`
+- **Responsibility**: Govern future AI-agent work in this repository.
+- **Does NOT handle**: Changing package output unless edits are made to `templates/**` or source code.
+## 5. Data Flow
+```text
+CLI args / prompts
+-> src/index.js parse and display
+-> src/generator.js resolve optional catalog
+-> walk templates/common and selected templates/optional
+-> harnessDest maps source paths to generated destinations
+-> createPlan/addFileActions classify create/skip/backup/overwrite/conflict
+-> renderTemplate substitutes projectName
+-> registerOptionalContent updates generated Harness router/memory
+-> write files or return dry-run/json plan
+-> tests and generated validator verify behavior
+```
+## 6. Architectural Constraints
+- Do not add generated-output behavior by editing only root `Harness/`; edit `templates/common/**` or `templates/optional/**`.
+- Do not add user-facing CLI behavior without tests in `tests/cli-smoke.test.js` or `tests/generator.test.js`.
+- Do not add required generated files without updating `templates/common/scripts/validate-harness.mjs` and relevant tests.
+- Do not write Harness docs into generated `docs/`; `Harness/` is the generated root for harness-owned docs.
+- Do not make root `CLAUDE.md` a dumping ground for build commands, architecture, or release process.
-## 5. Architectural Constraints (Non-Negotiable)
+## 7. Known Follow-Up Risks
-- `domain/` only defines business models, business invariants, and port protocols; does not import `harness/`, `infrastructure/`, or `interfaces/`.
-- `harness/` may orchestrate workflows, security gates, auditing, and stop conditions, but must not determine business meaning.
-- All cross-layer external capabilities are expressed through `domain` ports; adapter implementations live in `infrastructure/`.
-- Rejections and failures must be testable or documented with manual verification steps in the feature doc.
-- Audit events are append-only, never overwritten in place.
+- Interactive confirmation currently happens before full conflict-plan display in interactive mode.
+- Some README tests assert exact prose and can be made more structural.
+- `wf-mode` and `subagent-orchestrator` routing priority should continue to be tightened in templates.

package/templates/common/docs/research/README.md CHANGED Viewed

@@ -6,7 +6,7 @@ Purpose: guide agent research. Record conclusions in [research-results.md](resea
 Use this before PRD, stack choice, external API use, public dependency choice, pricing/legal/security assumptions, or any fact likely to change.
-Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/tasks/<task-id>/PROGRESS.md`.
+Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/tasks/<task-id>/PLAN.md`.
 ## Research Agent
@@ -104,7 +104,7 @@ Use these patterns when turning research into PRD or feature docs:
 ## Write Target
-- Research process, queries, and limitations: this file or `Harness/tasks/<task-id>/PROGRESS.md`.
+- Research process, queries, and limitations: this file or `Harness/tasks/<task-id>/PLAN.md`.
 - Final research decisions: [research-results.md](research-results.md).
 - Product scope: [PRD.md](PRD.md).
 - Architecture consequences: `Harness/architecture.md` and `Harness/domain/ports.md`.

package/templates/optional/skills/browser-e2e/.claude/commands/wf-browser.md ADDED Viewed

@@ -0,0 +1,25 @@
+# /wf-browser [task]
+AI-driven browser automation via Browser Use (89.1% WebVoyager benchmark). Dual mode: CLI (~50ms per call, no LLM needed) + Python Agent API (multi-step AI reasoning).
+## Required
+- Load `wf-browser` skill.
+- Load `Harness/workflows/browser-e2e.md` for evidence contract and fallback paths.
+- Real-browser evidence required for every browser/UI claim (screenshot, state snapshot, or console output).
+## Modes
+**CLI (fast iteration):** `browser-use open/state/click/screenshot/close` — Claude Code reasons, CLI executes.
+**Agent (complex flows):** Python API with LLM observation→decision→action loop.
+## Flow
+```text
+open page → state (inspect elements)
+→ click/input (interact)
+→ state/screenshot (verify)
+→ close (cleanup)
+```
+Keep browser evidence in `Harness/tasks/<task-id>/evidence/*.png`.

package/templates/optional/skills/browser-e2e/.claude/skills/wf-browser/SKILL.md ADDED Viewed

@@ -0,0 +1,164 @@
+---
+name: wf-browser
+description: AI-driven browser automation for E2E testing, web scraping, form filling, and UI verification. Powered by Browser Use (89.1% WebVoyager benchmark). Use for /wf-browser, browser testing, web automation, page interaction, form filling, screenshot verification, or any task requiring real browser control. Dual mode: CLI (fast iteration, no LLM needed) + Python Agent API (complex multi-step workflows with AI reasoning).
+---
+# WF Browser — AI Browser Automation
+Load:
+- `Harness/workflows/browser-e2e.md`
+- Official `browser-use` skill at `~/.claude/skills/browser-use/SKILL.md` (auto-installed if missing)
+- `Harness/PROGRESS.md` when work is active
+## Modes
+Choose based on task complexity:
+### Mode 1: CLI (fast iteration, ~50ms per call)
+Best for: single-page checks, quick screenshots, form fills, element inspection. No LLM needed — Claude Code reasons and issues CLI commands.
+```bash
+browser-use --headed open https://example.com   # Open page (headed = visible browser)
+browser-use state                                # Get page title, text, interactive elements with indices
+browser-use screenshot evidence.png              # Capture screenshot as evidence
+browser-use click 5                              # Click element by index from state output
+browser-use input 3 "user@example.com"           # Fill input field by index
+browser-use eval "document.title"                # Run JavaScript in page
+browser-use close                                # Close browser when done
+```
+Daemon keeps the browser open between commands — no cold-start per action.
+### Mode 2: Python Agent API (multi-step AI reasoning)
+Best for: complex multi-page workflows, dynamic navigation, data extraction across pages. Needs LLM API key.
+```python
+from browser_use.beta import Agent, BrowserProfile
+from browser_use.llm import ChatAnthropic
+agent = Agent(
+    task="Go to github.com, search for 'browser-use', click the first result, and report the star count",
+    llm=ChatAnthropic(model="claude-haiku-4-5-20251001"),
+    browser_profile=BrowserProfile(headless=False),
+)
+history = await agent.run()
+print(history.final_result())
+```
+## Environment Setup
+Run once per machine:
+```bash
+# 1. Install browser-use with CLI extras
+pip install "browser-use[cli]"
+# 2. Install Chromium browser
+browser-use install
+# 3. Verify installation
+browser-use doctor
+# 4. (Optional) Set LLM API key for Agent mode
+# Create .env file with: ANTHROPIC_API_KEY=sk-ant-...
+# Or: OPENAI_API_KEY=sk-...
+# Or: BROWSER_USE_API_KEY=bu-...
+```
+### Windows GBK Encoding Fix
+If you see `UnicodeEncodeError: 'gbk' codec can't encode character`, the install is auto-patched. If not, set env var before commands:
+```bash
+set PYTHONIOENCODING=utf-8
+```
+### Requirements
+| Requirement | Version | Check |
+|-------------|---------|-------|
+| Python | >= 3.11 | `python --version` |
+| pip | any | `pip --version` |
+| Chromium | auto-installed | `browser-use doctor` |
+| LLM API key | for Agent mode only | check `.env` |
+## Common Patterns
+### Login Persistence
+```bash
+# Use real Chrome profile (preserves cookies/logins)
+browser-use --profile "Default" open https://app.target.com
+# Or connect to running Chrome with remote debugging
+browser-use connect
+```
+### E2E Test Flow
+```bash
+browser-use --headed open https://yourapp.local
+browser-use state                          # Verify page loaded
+browser-use screenshot step1-landing.png   # Evidence
+browser-use input 3 "test@email.com"       # Fill email
+browser-use input 5 "password123"          # Fill password
+browser-use click 8                        # Click login button
+browser-use wait text "Dashboard"           # Wait for navigation text
+browser-use state                          # Verify logged in
+browser-use screenshot step2-dashboard.png # Evidence
+browser-use close
+```
+### Console & Network Log Capture
+```bash
+browser-use eval "console.log('checkpoint');"   # Inject log marker
+browser-use eval "document.title"                # Read page state via JS
+browser-use get text 5                           # Get text of element index 5
+browser-use get value 3                          # Get value of input element index 3
+# For full console/network: use Python Agent mode with Playwright's page.on('console') and page.on('request')
+```
+### Error Recovery
+```bash
+# If daemon crashes or gets stuck:
+browser-use close          # Clean shutdown
+# Then restart:
+browser-use open <url>     # Fresh daemon starts automatically
+```
+## Verification Contract
+Every browser task must produce:
+1. **State evidence**: `browser-use state` output or screenshot
+2. **Action log**: sequence of commands issued
+3. **Result assertion**: explicit before/after state comparison
+No browser/UI claim without real-browser evidence.
+## Architecture Note
+Browser Use wraps Playwright with AI reasoning. The daemon keeps Chromium running between CLI commands (~50ms latency). The Agent mode adds an LLM observation→decision→action loop on top. This replaces fragile CSS-selector scripts with semantic element targeting via accessibility tree snapshots.
+Benchmarks: 89.1% WebVoyager (SOTA), 78k+ GitHub stars, MIT license.
+## Security
+- **Never log or screenshot credentials** — redact password fields, API keys, tokens before capturing evidence
+- **Chrome profiles contain sensitive data** — only use `--profile` with explicit user approval; never share profile data
+- **Screenshots may capture PII** — review before saving to task evidence directory
+- **Scraping targets need approval** — confirm the target site's ToS allow automated access before scraping
+- **`browser-use input` commands with passwords** — use placeholder values in documentation; never hardcode real credentials
+- **Agent mode sandbox** — run Agent API with `allowed_domains` restriction when possible
+## Return
+- CLI commands issued and their output
+- screenshot paths
+- agent history (if Agent mode used)
+- verification pass/fail with evidence
+- remaining risks (flaky selectors, auth issues, CAPTCHAs)

package/templates/optional/skills/browser-e2e/docs/workflows/browser-e2e.md CHANGED Viewed

@@ -1,42 +1,63 @@
 # Browser E2E Workflow
-## Required Evidence
-- App start command and URL.
-- Real-browser load of the changed app before any web/UI acceptance claim.
-- Console, runtime, and network check result, including whether React/Vite/client startup errors or failed requests appeared.
-- Stable accessible labels/roles and stable test hooks such as `data-testid` are required for critical UI controls and states: inputs, buttons, filters, rows, empty/error/loading states.
-- CDP, Playwright, and manual verification must target those selectors for the critical interaction path instead of brittle DOM paths.
-- Viewports and browsers checked.
-- Screenshot, trace, video, or documented manual screenshot artifact for each critical UI flow.
-- Final pass/fail result with exact command output summary.
-## Chrome DevTools / CDP / MCP Checklist
-- Start the app with the project command and record the URL and port.
-- Open a real browser target through available CDP, MCP, browser automation, or manual tooling.
-- Wait for a stable app selector, route, or page-ready state, not just HTTP 200.
-- Capture runtime exceptions, console errors, and failed network requests before and after the flow.
-- Interact through stable accessible labels/roles or `data-testid`, not brittle DOM paths.
-- Verify at least one critical flow end-to-end in the real browser target.
-- Save screenshot, trace, video, or result artifact paths and record them in `Harness/PLAN.md` or the feature doc.
-- Clean up any dev server or browser processes started for verification.
-## Common Commands
-```powershell
-npm run dev
-npx playwright test
-npx playwright test --headed
-npx playwright show-report
-```
+Optional workflow for browser-visible testing and automation. Installed when `browser-use` CLI is available.
+## When Active
+This workflow is active when:
+1. `browser-use` CLI is installed and `browser-use doctor` passes
+2. `Harness/workflows/browser-e2e.md` exists (this file)
+3. A task explicitly references `/wf-browser` or browser E2E testing
+## Contract
+Browser evidence in this project follows the contract:
+1. **Every browser claim needs real-browser evidence** — screenshot, state snapshot, or console output
+2. **CLI mode is preferred for deterministic steps** — use `browser-use open/state/click/screenshot` for predictable flows
+3. **Agent mode is for dynamic exploration** — use Browser Use Agent API when the page structure is unknown or changing
+4. **Evidence goes to the task directory** — `Harness/tasks/<task-id>/evidence/*.png`
+## Quick Install
-If Playwright is not installed, prefer an existing browser test command from `package.json`. Chrome DevTools/CDP, manual screenshot evidence, or framework-specific tools are acceptable when the method, URL, flow, console/runtime/network result, and artifacts are documented.
+```bash
+# One-time setup
+pip install "browser-use[cli]"
+browser-use install
+browser-use doctor
+# Windows: if you see GBK encoding errors, set:
+set PYTHONIOENCODING=utf-8
+# Verify
+browser-use open https://example.com
+browser-use state
+browser-use screenshot test.png
+browser-use close
+```
 ## Fallback
-When no browser automation is available, run the app locally in a real browser, inspect critical flows manually, capture screenshots, and report console or network errors. Do not claim web/UI acceptance from typecheck, build, or unit tests alone. Do not install new dependencies unless the user approves.
+If `browser-use` is not installed, fall back to:
+1. Playwright/Puppeteer MCP server (if configured)
+2. Chrome DevTools Protocol (CDP) manual inspection
+3. `Harness/WF.md#Browser And API Evidence` manual check contract
+## Integration Points
+- **wf-mode**: references this file at line 16 and 42 of `.claude/skills/wf-mode/SKILL.md`
+- **wf-browser**: the `/wf-browser` slash command loads this workflow + the skill via `.claude/commands/wf-browser.md`
+- **MEMORY.md**: registered as optional workflow skill
+- **README.md**: routing table row "Browser E2E testing or automation" → browser-e2e
-## Windows Notes
+## File Locations
-Use PowerShell syntax for environment variables, for example `$env:PORT='3000'; npm run dev`. Quote paths that contain spaces.
+| File | Purpose |
+|------|---------|
+| `.claude/skills/wf-browser/SKILL.md` | Skill definition |
+| `.claude/commands/wf-browser.md` | Slash command bridge |
+| `Harness/workflows/browser-e2e.md` | This file — workflow contract and install guide |
+| `~/.claude/skills/browser-use/SKILL.md` | Official Browser Use skill (user-level, auto-downloaded) |
+| `pip show browser-use \| findstr Location` | Python package install location (run to find) |
+| `~/.browser-use/` | Daemon state and browser profiles |