create-harness-vibe-coding is a Node.js CLI that scaffolds a repo-local harness for AI-assisted software development: research, PRD, architecture, task decomposition, implementation, testing, review, recovery, and durable memory.
It is not a prompt pack and it does not generate business code. It gives Claude Code, Codex, and compatible agents a shared operating system for long-running work.
The short version
Without a framework:
Idea -> prompt -> patch -> demo -> rediscover context -> repair drift
With Harness:
Idea -> Research -> PRD -> Architecture -> Acceptance Criteria
-> Build -> Test -> Review -> Verify -> Learn -> Update
Measured status in 0.8.16
Current evidence in this repository:
- HarnessBench v0.2 local lifecycle proof: 15 runs per mode. Direct file writes completed safely in 3/15 runs; the Harness safe path completed safely in 15/15 runs.
- Protected overwrites in that proof: 21 for direct file writes, 0 for the Harness safe path.
- Claude Code L2 prompt-cache sample:
harness-thin reached 98.7% warm median cache read (+5.4 percentage points vs provider-control); /wf wf-light reached 99.1% (+5.8 percentage points).
- Startup and update chain: thin startup remains the default,
Harness/specs/guides/SETUP.md is only setup/migration reference material, and /wf-update reports agent.releaseHighlights plus validation results.
One-line install (recommended for existing repos)
Paste this into your agent:
Please install the Harness framework by following https://github.com/LiWeny16/create-harness-vibe-coding/blob/main/README.md.
Installation instructions (Agent instruction)
After reading this README, the agent selects the path that matches the project:
| Project state | Agent action |
|---|
| New project | npx create-harness-vibe-coding@latest my-project -y |
| Existing project | npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json |
Existing Harness/ with Harness/scripts/wf-update-check.mjs | node Harness/scripts/wf-update-check.mjs --json; update, do not reinstall; after apply/finalize, report agent.releaseHighlights plus validation results |
Existing Harness/ but missing Harness/scripts/wf-update-check.mjs | npx create-harness-vibe-coding@latest my-project . -y --on-conflict skip --json. Then run node Harness/scripts/wf-update-check.mjs --json |
| After install or update | node Harness/scripts/validate-harness.mjs --strict |
Install scope policy: the CLI defaults to global for a new or empty target, and to project for an existing non-empty target so older repositories keep their historical behavior. An explicit --install-scope project|global always wins. The global Harness runtime provides the command and controller surfaces; wf-ui, browser control, media download, ASR, and VLM are optional CLI extensions installed through pnpm. Use --install-scope project for a self-contained or offline/CI install; use --global-dir <dir> and --host-global-dir <dir> when the shared locations must be explicit.
Lazy extension runtime: /wf-search uses the native Rust CLI and requests optional capabilities through /wf-extension. The default runtime does not include wf-ui, browser engines, crawlers, Whisper, or VLM tooling. Install registered packages with pnpm exec wf extension install <id> --apply; project package versions are pinned by pnpm. CLI-backed commands first check pnpm exec wf --help; if the CLI is missing, they ask before installing it with pnpm add --save-dev @zingspark/[email protected].
When /wf-update finds an older project-local install, it recommends migrating to the global model and asks before changing scope. After confirmation, run npm install --global create-harness-vibe-coding@latest and create-harness-vibe-coding init . --scope global --migrate. Migration removes only safe Harness-owned prompt-engineering framework files and old local metadata; it preserves tasks, progress, memory, research, project facts, README/package files, and modified or user-authored Harness-interest files. Declining keeps the project-local update path.
After installation, hand off by phase: use CLAUDE.md as the normal session entry, use Harness/specs/guides/SETUP.md only for install/bootstrap, migration, or upgrade decisions, and use Harness/README.md as the Harness workflow router when a routed task needs it. Preserve project boundaries; research and plan before editing; run tests, validation, and review before claiming completion.
The agent handles Harness installation, conflict handling, validation, and the handoff. BrowserOS Neo is a separate user-provided prerequisite for /wf-browser: download, install, and start it yourself; Harness never downloads or installs it automatically.
Which WF command should you use?
When in doubt, use /wf-help (or $wf-help in Codex). It returns the full command table. Use /wf for complex work and /wf-max when the work can be safely parallelized.
| Command | Use it when | What it does | Example |
|---|
/wf <task> | Multi-file, architectural, risky, migration, or repeatedly failing work | Research -> plan -> implement -> test -> review -> verify -> reflect | /wf refactor the payment module and add tests |
/wf-max <task> | The task splits into independent work and needs maximum parallelism | Adds CEO -> Manager -> Worker roles and parallel waves to the full WF chain | /wf-max upgrade frontend, backend, and docs in parallel |
/wf-auto | You want continuous self-directed optimization with adaptive probe selection | Runs repeated optimization cycles with plans, evidence, and feedback | /wf-auto improve this project's stability |
/wf-auto-spark | You need external inspiration, competitive direction, or a long-term roadmap | Searches for sparks, anchors work to a North Star and milestones, and guards scope drift | /wf-auto-spark explore product growth directions |
/wf-review [focus] | You need a second opinion, peer review, or a pre-release check | Uses clean Harness-native reviewer subagents with bounded intelligent fan-out and classifies findings by severity | /wf-review focus on security and data loss |
/wf-learn | The same mistakes keep recurring or a completed task needs to become reusable knowledge | Extracts generalized methods with anti-overfitting and route-load checks | /wf-learn summarize why this task needed rework |
/wf-browser <task> | Browser smoke tests, E2E, screenshots, forms, or UI verification | Uses BrowserOS Neo and returns screenshots, traces, and evidence; you must download and start BrowserOS Neo yourself | /wf-browser verify login and checkout |
/wf-ui | Open the Harness control panel for task management, workflow graphs, agents, and settings | Directly starts the local backend and browser UI on 127.0.0.1 | /wf-ui |
/wf-readme <task> | README, install docs, architecture diagrams, or project docs need work | Preserves facts while improving structure, setup, and usage guidance |
Claude Code uses /wf-*; Codex uses the matching $wf-*; OpenCode uses the registered command or Agent instruction. Browser E2E guidance is built into wf-browser, which uses BrowserOS Neo as its default real browser and asks the user to install it manually when it is unavailable. /wf-auto and /wf-auto-spark are continuous modes, so give the agent a clear goal, scope, and acceptance criteria before starting.
Common starting points: Web/API work starts with correctness, security, reliability, and verification; CLI/SDK work starts with contracts, compatibility, error UX, and docs; AI-agent work starts with context quality, tool safety, evaluation, and recovery; data jobs start with idempotency, failure recovery, and observability. See the full WF-AUTO-ANGLES.md selection protocol.
Chinese README: README-CN.md
Harness intelligence routing
Workflow entry points create a bounded, role-scoped task context pack before
dispatch and regenerate it on resume. External research is conditional: the
local policy checks capability gaps, volatile APIs, explicit requests, repeated
failures, or benchmark gaps before an agent reads current web, GitHub, or
Hugging Face sources. Source URL, version/terms, date, and adopt/adapt/reject
rationale remain part of task evidence. Packs and structural checks improve
boundaries but do not replace semantic validation.
/wf-max uses evidence-driven WF-Max-Useful fan-out by default; a dependency
chain, absent independent acceptance, or coordination cost without benefit may
be recorded as no-spawn. WF-Max-Strict is enabled only by an explicit strict
request and remains bounded by actual runtime capacity. Direct commands such as
/wf-help, /wf-task-list, /wf-init, and /wf-update stay direct and do not
force task routing or external research.
Measured difference
Harness does not make the model smarter. It reduces uncontrolled parts of agent
work: which files may change, how conflicts are handled, how recovery works, and
what evidence counts as complete.
The current published benchmark is a deterministic local lifecycle proof, not a
full LLM feature-success A/B result. It creates 5 fixture families x 3 seeds per
mode and checks the filesystem after each run. See
HarnessBench v0.2.
Benchmark assets stay outside generated installs: users get the published
summary, not the runner, fixtures, scorer, or raw logs.
HarnessBench local lifecycle proof
Run on 2026-07-26:
node scripts/harness-bench-local.mjs --output benchmarks/results/harnessbench-local-v0.2.json
node scripts/harness-bench.mjs --input benchmarks/results/harnessbench-local-v0.2.json --markdown
| Mode | Tasks | Runs | Verified safe | Protected overwrites | Repair-triggering runs | Manual repair events | Required-file misses | Benchmark leaks | Boundary violations |
|---|
No Harness baseline (direct file writes) (direct-run) | 5 | 15 | 3/15 (20%) | 21 | 12 | 21 | 0 | 0 | 12 |
Harness safe path (harness-wf) | 5 | 15 | 15/15 (100%) | 0 | 0 | 0 | 0 | 0 | 0 |
What this proves: Harness has measurable boundary value for fresh install,
existing-project preservation, same-name user skill protection, old-Harness
updater recovery, and generated-install benchmark exclusion. It does not prove
that any model solves arbitrary frontend, backend, or embedded feature work at a
higher rate. That requires the full HarnessBench LLM A/B suite with raw run
logs.
Prompt-cache L2 sample
On 2026-07-23, this dogfood repository ran a bounded Claude Code L2 prompt-cache probe with node Harness/scripts/l2-cache-telemetry.mjs --groups provider-control,harness-thin,wf-light --turns 11 --turn-budget-usd 0.32 --total-budget-usd 1.20 --timeout-ms 240000.
Source: Claude Code JSON usage fields, especially usage.cache_read_input_tokens and usage.cache_creation_input_tokens. Read ratio is cache_read_input_tokens / (input_tokens + cache_creation_input_tokens + cache_read_input_tokens). The raw local report is outside the repo at ~/.claude/cache-telemetry/harness-l2-claim-20260723-130331.json.
| Route | Turns | Success | Warm median cache read | Warm range | Warm median latency | Uplift vs provider-control |
|---|
| provider-control | 11 | 11/11 | 93.3% | 91.1%-95.4% | 2123.5 ms | baseline |
| harness-thin | 11 | 11/11 | 98.7% | 98.1%-99.2% | 1786.5 ms | +5.4 percentage points |
/wf wf-light | 11 | 11/11 | 99.1% | 98.7%-99.7% | 2900 ms | +5.8 percentage points |
Claim boundary: this proves real cache reads and a measured improvement in this bounded Claude Code sample. It is not a universal claim for every model, repository, task, or provider.
Compared with adjacent tools
Harness is a repo-local operating contract. It can sit above Claude Code, Codex, OpenCode, or another agent instead of replacing them.
| Compared with | Primary layer | Harness advantage |
|---|
| Direct agent run | One prompt plus ad hoc context | Persistent task state, explicit write boundaries, verification gates, and recoverable handoff |
| Claude Code, Codex, OpenCode | Coding agents and runtimes | Cross-runtime repo contract with the same commands, memory shape, validator, and update policy |
| Aider | Terminal pair-programming, repo map, git/test loop | Harness focuses on install/update safety, task capsules, external benchmark evidence, and multi-runtime workflow routing |
| Superpowers | Skills-based development methodology | Harness adds an npm scaffold, machine-readable ownership/version manifests, safe merge/update scripts, and generated repo-local state |
Architecture
The architecture has three pillars:
- Goals & Constraints - PRD -> research -> architecture -> acceptance criteria.
- Quality Context - a router, context-loading protocol, and durable memory keep attention on the right evidence.
- Decomposition & Feedback -
/wf and /wf-max assign bounded work, then review, verify, learn, and update the next task.
What gets scaffolded
| Layer | Purpose |
|---|
CLAUDE.md, AGENTS.md | Agent session entry contract and compatibility pointer |
Harness/README.md, Harness/MEMORY.md | Harness workflow router and resource index |
Harness/tasks/, Harness/PROGRESS.md | Resumable task state across sessions |
.claude/, .agents/, .codex/, .opencode/ | Tool-specific discovery and configuration |
templates/common/, templates/optional/ | Declarative scaffold source and optional workflows |
Harness/scripts/validate-harness.mjs | Structural and strict readiness checks |
The generated project starts with no business stack or generated application code. You choose the stack after bootstrap.
Existing project: safe merge first
Paste this to your agent:
Read and follow https://github.com/LiWeny16/create-harness-vibe-coding exactly to configure this project with create-harness-vibe-coding.
The agent-first path previews the target before writing and preserves project-owned files. Harness/specs/guides/SETUP.md is the retained bootstrap/migration reference created by the scaffold; it is not the normal session entry.
If Harness/ already exists, first check whether Harness/scripts/wf-update-check.mjs exists. If it does, use /wf-update, $wf-update, or node Harness/scripts/wf-update-check.mjs --json instead of reinstalling blindly. If it is missing, run the safe CLI recovery command from the installation table first, then run the updater.
Optional workflows
Ask your agent to add the capability you need:
Add ui-ux-review and ts-react-frontend to this Harness project, preserve existing files, run the strict validator, and report exactly what changed.
| Workflow | Use it for |
|---|
ui-ux-review | Responsive, accessibility, and polish review |
ts-react-frontend | TypeScript, React, and Vite projects |
python-backend | FastAPI and pytest projects |
github-pr-review | PR diff review and CI evidence |
External recommendations are recorded in Harness/specs/guides/SETUP.md; they are not auto-installed.
| Recommendation | Use it for | Source |
|---|
superpowers | Community agent skills and coding workflows | Superpowers |
caveman | Terse, low-token agent behavior | Caveman |
agent-research | Literature, product, dependency, and ecosystem research | agent-research-skills |
codegraph | Repository graph and architecture mapping | CodeGraph |
grill-me | Relentless plan/design interview before implementation | Grill Me |
Verify
# This package repository
npm test
# Generated project after safe merge
node Harness/scripts/validate-harness.mjs
# Generated project after bootstrap or before release
node Harness/scripts/validate-harness.mjs --strict
# After publishing an update release
npm run check:mirrors
Ownership manifest
Harness/ownership.manifest.json is the machine-readable source of truth for file classification during install/update. It is auto-generated from templates/common/ + templates/optional/catalog.json by node scripts/build-version.mjs. Framework-owned files overwrite-upgrade; user data (tasks, memory, research, README, package, PROGRESS) is preserved; CLAUDE/AGENTS/Harness README merge; same-name user agents/commands/skills (no marker) are never overwritten.
Release gate
Iron rule: every update release must keep both update channels live:
- Canonical: npm
create-harness-vibe-coding@latest and https://github.com/LiWeny16/create-harness-vibe-coding
- Legacy compatibility mirror:
https://github.com/zingspark/create-harness-vibe-coding
Low-version installs can have updater scripts hardcoded to the legacy mirror. Do not mark a release complete until the legacy mirror exposes the same commit on main, the version tag, the generated template manifest (templates/common/.harness-version AND templates/common/Harness/ownership.manifest.json), and the tag's GitHub Release artifact, all matching canonical. Generated installs still record the canonical LiWeny16 source; the zingspark repo is kept for backward compatibility.
"Code ready" is not "users can update". Users on published npm receive the new version only AFTER npm publish completes AND the GitHub release/tag is cut AND both mirrors are synced. Do not announce the update as available to existing users until all three are done.
Footprint
| |
|---|
| Runtime | None |
| Dependencies | 6 runtime (@clack/prompts, iconv-lite, picocolors, read-excel-file, unpdf, yauzl); optional PTY (@homebridge/node-pty-prebuilt-multiarch) |
| Node.js | >=18 |
| Generated application code | None until you choose a stack |
Keywords and related concepts
AI coding agent framework; agentic workflow; context engineering; long-running coding tasks; task orchestration; durable memory; safe merge; conflict handling; acceptance criteria; Claude Code; Codex; OpenCode; Node.js CLI; developer productivity
MIT (c) LiWeny16
