create-harness-vibe-coding 0.8.13 → 0.8.17

package/templates/common/Harness/TASK_ARCHIVE.md

@@ -1,56 +0,0 @@
-# TASK_ARCHIVE — Task Archive Mechanism
-
-Purpose: keep `Harness/tasks/` lean by archiving completed/abandoned tasks while preserving all evidence.
-
-## Archive Location
-
-Active tasks stay in `Harness/tasks/<task-id>/`.
-Archived tasks move to `Harness/tasks/_archive/YYYY/<task-id>/`.
-
-## What Is Never Archived
-
-- `Harness/tasks/_template/` — scaffold template, never moved.
-- `Harness/tasks/auto/` — WF-AUTO permanent state capsule, never moved unless explicitly allowed by WF-AUTO docs.
-- `Harness/tasks/_archive/` — the archive directory itself.
-- Active, blocked, in-progress, or needs-user-decision tasks.
-- Tasks whose STATE.json status is `active`, `blocked`, `in_progress`, `running`, `pending`, or `needs-user-decision`.
-
-## What May Be Archived
-
-Tasks whose STATE.json or PROGRESS.md status is: `complete`, `verified`, `archived`, `abandoned`, `obsolete`, `done`, `closed`, or `closeout`.
-
-The script reads STATE.json `status`/`phase` first, then falls back to the first `- Phase:`, `Phase:`, or `Current:` marker in the task's PROGRESS.md (first word wins). Ambiguous phases are never auto-archived.
-
-## Archive Process
-
-1. Verify the task is not active/blocked.
-2. Ensure `Harness/tasks/_archive/YYYY/` exists.
-3. Move `Harness/tasks/<task-id>/` → `Harness/tasks/_archive/YYYY/<task-id>/`.
-4. Update the moved STATE.json: `status` → `archived`, `phase` → `archived`.
-5. Update `Harness/tasks/_archive/INDEX.md`.
-6. Update `Harness/PROGRESS.md` Task Index — remove or annotate `(archived)`.
-
-## Retention
-
-- Archived tasks retain: PLAN, PROGRESS, STATE, ARTIFACTS, NOTES.
-- Do NOT delete historical evidence.
-- `Harness/PROGRESS.md` keeps the last 5 non-archived task entries in the Task Index.
-- When outer task capsules exceed 5 completed/abandoned/obsolete, archive the oldest.
-- The validator (`Harness/scripts/validate-harness.mjs`) warns when `Harness/tasks/` holds more than 5 outer task capsules (excluding `_archive`, `_template`, `auto`) and fails in `--strict` mode.
-
-## Script
-
-Use `Harness/scripts/archive-tasks.mjs`:
-- Default: dry-run
-- `--apply` to execute
-- `--keep 5` to set the non-archived task threshold
-- `--task <task-id>` to archive a specific task
-- `--json` for machine-readable output
-- `node Harness/scripts/archive-tasks.mjs --dry-run --json` must always run
-
-## Safety Rules
-
-- Windows path safe. Use `path.resolve()` before moving.
-- Confirm target is within `Harness/tasks/` before any move.
-- Do NOT recursively delete.
-- Tasks with `needs-user-decision` status are never auto-archived.

package/templates/common/Harness/WF-STATE.md

@@ -1,83 +0,0 @@
-# WF-STATE — Lightweight Resumable State Machine
-
-Purpose: persist resumable workflow state across compaction, new Claude Code windows, new terminals, and project reopen. It is NOT a scheduler, daemon, lock manager, async runtime, or graph framework.
-
-## State Files
-
-| File | Role |
-|------|------|
-| `Harness/PROGRESS.md` | Global active pointer — which task is current |
-| `Harness/tasks/<task-id>/STATE.json` | Machine-readable resume truth |
-| `Harness/tasks/<task-id>/PROGRESS.md` | Human-readable summary |
-| `Harness/tasks/<task-id>/PLAN.md` | Plan, decisions, scope context |
-
-## Enums
-
-### phase
-`intake`, `clarify`, `requirements`, `prd`, `acceptance`, `plan`, `explore`, `implement`, `verify`, `review`, `fix`, `reflect`, `closeout`, `blocked`, `archived`
-
-### item status (queues)
-`pending`, `ready`, `running`, `done`, `blocked`, `skipped`, `failed`
-
-### mode
-`direct`, `wf`, `wf-max`, `wf-auto`, `wf-auto-spark`, `wf-review`, `wf-browser`
-
-### tier
-`none`, `light`, `standard`, `full`, `max-useful`, `max-strict`
-
-## Rules
-
-1. **STATE.json is machine-readable resume truth.** On session start, the agent reads it to know where it left off.
-2. **PROGRESS.md is human-readable summary.** It mirrors key state but is secondary for machine reasoning.
-3. **PLAN.md is plan/decision context.** Load only when decisions or scope need review.
-4. **On every phase transition, dispatch return, blocker, verification result, review finding, or closeout, update STATE.json.** task-scribe or controller writes; production agents never write task state.
-5. **Long logs/transcripts never go into STATE.json.** Store paths only.
-6. **task-scribe may update STATE.json and task summaries; production agents may not.**
-7. **If STATE.json conflicts with PLAN/PROGRESS, controller stops and reconciles before continuing.**
-
-## Resume Protocol
-
-New window / session start:
-1. Read `CLAUDE.md`.
-2. If user says "continue", "resume", "last task", "current task", "status", or the work is not a simple direct task:
-   - Read `Harness/PROGRESS.md` → find Active Task
-   - If Active Task exists, read `Harness/tasks/<active-task>/STATE.json`
-   - Read `Harness/tasks/<active-task>/PROGRESS.md`
-   - Read `Harness/tasks/<active-task>/PLAN.md` only if decisions/scope need review
-3. From STATE.json, determine:
-   - Current phase, gate, tier
-   - activeQuestion (needs user answer before proceeding)
-   - Queues: ready (can dispatch immediately), running (awaiting results), blocked (needs resolution), done
-   - nextAction (what to do next)
-4. Do NOT bulk-read `Harness/tasks/` to find context. Use the active pointer.
-5. Direct simple tasks may skip STATE/PLAN/PROGRESS unless the user says "continue"/"resume".
-
-## State Transitions
-
-```
-intake → clarify → requirements → prd → acceptance → plan
-→ explore → implement → verify → review
-→ (fix → verify → review loop)
-→ reflect → closeout
-```
-
-Any phase may transition to `blocked` if a dependency, user decision, or external input is required.
-
-## Dispatch Ledger
-
-Every dispatch packet MUST have an `id`. On return, controller or task-scribe updates the ledger item:
-- `id`, `agent`, `role`, `phase`, `status` (pending/ready/running/done/blocked/skipped/failed), `evidence`
-
-See [WF-KERNEL.md](WF-KERNEL.md) for the dispatch packet format.
-
-## Integration with /wf and /wf-max
-
-- `/wf` uses the STATE ready queue for dynamic orchestration.
-- `/wf-max` uses the SAME STATE ready queue for maximum safe fan-out.
-- When a subagent returns or goes idle, controller immediately dispatches the next ready item.
-- task-scribe is the exception for task-state writes.
-- Production source agents do not write STATE/PLAN/PROGRESS unless explicitly dispatched as task-scribe.
-
-## Template
-
-See `Harness/tasks/_template/STATE.json` for the canonical template. On task creation, copy and populate from the template.

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

@@ -1,42 +0,0 @@
----
-name: browser-e2e
-description: Mandatory real-browser smoke and end-to-end verification using Playwright, Chrome DevTools/CDP, or documented manual browser evidence.
----
-
-# Browser E2E
-
-## When To Use
-
-Use this skill when a change affects browser-visible behavior, navigation, forms, routing, layout, or client-side integration. Web/UI acceptance requires loading the app in a real browser before claiming the UI is done.
-
-## Docs To Load
-
-- `Harness/workflows/browser-e2e.md`
-- `Harness/PROGRESS.md` and current task `tasks/<id>/PLAN.md`
-- Existing project test, build, and run instructions.
-
-## Required Inputs
-
-- Target URL or command to start the app.
-- User flows or pages to verify.
-- Expected behavior and supported viewport/browser scope.
-- Selector contract: stable accessible labels/roles and `data-testid` hooks for critical inputs, buttons, filters, rows, empty/error/loading states, and other targetable UI states.
-
-## Allowed Writes
-
-- Browser test files in the project's existing test locations.
-- Evidence artifacts such as screenshots, traces, or reports in existing artifact folders.
-- Notes in current task plan when the active task asks for plan tracking.
-
-## Output Format
-
-Return changed files, commands run, browser evidence paths, verified flows, failures, and follow-up risks.
-Include the selectors used for CDP/Playwright/manual verification.
-
-## PROGRESS.md & Task PLAN.md Updates
-
-Update `Harness/tasks/<task-id>/PLAN.md` only when executing a tracked plan item or recording evidence requested by the current task.
-
-## dispatch.md Usage
-
-Use `Harness/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.

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

@@ -1,194 +0,0 @@
----
-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 Claude /wf-browser, Codex $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
-```
-
-### Windows Daemon Patches
-
-Browser Use v0.13.1 has two known issues on Windows that are auto-patched on install. If `browser-use open` fails with "Failed to start daemon" or socket timeout, re-apply:
-
-```bash
-python -c "
-import browser_use.skill_cli.main as m
-p = m.__file__
-c = open(p, encoding='utf-8').read()
-# Patch 1: auto-clean stale state on dead PID
-c = c.replace(
-    'probe = _probe_session(session)\n\n\t# Socket reachable',
-    'probe = _probe_session(session)\n\n\t# Auto-clean stale state\n\tif not probe.socket_reachable and not probe.pid_alive and probe.phase:\n\t\t_clean_session_files(session)\n\t\tprobe = _probe_session(session)\n\n\t# Socket reachable'
-)
-# Patch 2: auto-recover from stale session instead of erroring
-c = c.replace(
-    \"f'Error: Session {session!r} is alive (phase={probe.phase}) but socket unreachable.\",\"
-    \"f'Warning: Session {session!r} has stale state (phase={probe.phase}), auto-cleaning...\",\"
-)
-c = c.replace(
-    \"sys.exit(1)\n\n\t\telif probe.phase == 'shutting_down'\",
-    \"_terminate_pid(probe.pid)\n\t\t\t_clean_session_files(session)\n\n\t\telif probe.phase == 'shutting_down'\"
-)
-# Patch 3: extend daemon startup timeout (15s -> 30s)
-c = c.replace('deadline = time.time() + 15', 'deadline = time.time() + 30')
-open(p, 'w', encoding='utf-8').write(c)
-print('Patches applied')
-"
-```
-
-### 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/Harness/workflows/browser-e2e.md

@@ -1,119 +0,0 @@
-# Browser E2E Workflow
-
-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`, `$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`
-
-### Harness Bridge
-
-For frontend-backend flows, use `Harness/HARNESS_BRIDGE.md` to validate UI
-selectors, API payloads, seeded data, runtime state probes, and CDP/network
-traces. Browser validation must produce an AC-by-AC result matrix when the task
-has acceptance criteria.
-
-### Stable UI Selector Contract
-
-All browser automation and E2E tests in this project use a stable selector contract. Selectors must be written against **public, stable attributes** that survive refactors, not against ephemeral class names or DOM indices.
-
-**Required selector priority (most stable first):**
-
-1. **`data-testid`** - the primary stable anchor for automated tests
-2. **accessible labels/roles** - `getByRole`, `getByLabelText`, `getByPlaceholderText` (ARIA roles, `<label>` associations, placeholder text)
-3. **Text content** - `getByText` for visible user-facing strings
-
-**Required coverage targets.** Every interactive page tested by browser automation must cover: inputs, buttons, filters, rows, empty/error/loading states.
-
-| Category | Examples |
-|---|---|
-| **Inputs** | text fields, textareas, selects, checkboxes, radios, file uploads |
-| **Buttons** | submit buttons, icon-only buttons, toggle buttons, CTA buttons |
-| **Filters** | search inputs, dropdown filters, date range pickers, filter chips/tags |
-| **Rows** | table rows, list items, card containers - the repeating data unit |
-| **Empty state** | "no results" message, empty illustration, zero-state CTA |
-| **Error state** | inline validation errors, toast notifications, server error banners |
-| **Loading state** | spinners, skeletons, progress bars, "Loading..." text |
-
-**Selector format examples:**
-
-```
-data-testid="search-input"
-data-testid="submit-btn"
-data-testid="filter-status"
-data-testid="result-row"
-data-testid="empty-state"
-data-testid="error-banner"
-data-testid="loading-spinner"
-```
-
-**Rationale:** `data-testid` attributes are decoupled from styling and layout - they survive CSS refactors, component renames, and DOM restructuring. Accessible labels and roles are the fallback when `data-testid` is not available, and they double as a11y coverage. Class-name and XPath selectors are not accepted in test automation because they break on cosmetic changes.
-
-## Chrome DevTools / CDP / MCP Checklist
-
-- [ ] record the URL and port
-- [ ] Verify available CDP, MCP, browser automation, 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 critical flow end-to-end
-- [ ] Capture screenshot, trace, video, or result artifact paths
-- [ ] Produce an AC-by-AC validation matrix
-- [ ] Clean up any dev server or browser processes
-
-## Quick Install
-
-```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
-
-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**: when browser-visible changes are made, follow the evidence contract in `Harness/WF.md#Browser And API Evidence`
-- **Harness Bridge**: use `Harness/HARNESS_BRIDGE.md` for UI contract, API contract, seeded test data, runtime state probes, and network trace collection.
-- **wf-browser**: Claude Code uses `.claude/skills/wf-browser/SKILL.md`; Codex uses `.agents/skills/wf-browser/SKILL.md`. Both load this workflow.
-- **MEMORY.md**: registered as optional workflow skill
-- **README.md**: routing table row "Browser E2E testing or automation" -> browser-e2e
-
-## File Locations
-
-| File | Purpose |
-|------|---------|
-| `.claude/skills/wf-browser/SKILL.md` | Claude Code skill adapter |
-| `.agents/skills/wf-browser/SKILL.md` | Codex repo skill adapter |
-| `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 |