create-harness-vibe-coding 0.8.4 → 0.8.6

package/README.md

@@ -18,7 +18,7 @@ npx create-harness-vibe-coding@latest my-project
 
 ## Your Agent Knows What to Do
 
-Already have a project? **Don't read the docs**. Paste this sentence. Your agent handles the rest.
+Already have a project? Paste this sentence. Your agent should use the script-first fast path: dry-run JSON first, read only files named in `agent.aiMergeRequired`, then run the structural validator.
 
 ```text
 Read and follow https://github.com/zingspark/create-harness-vibe-coding exactly to configure this project with create-harness-vibe-coding.
@@ -41,7 +41,7 @@ Chinese README: [README-CN.md](README-CN.md)
 | `subagent-orchestrator` | Runs parallel agents without collision |
 | `memory-master` + `context-master` | Learns from failures, compresses when full |
 | PRD + Research templates | Asks "what" and "why" before coding |
-| 11 built-in agents | Research, plan, architect, test, build, review, debug, verify |
+| 16 built-in agents | Research, plan, architecture, TDD, build, review, debug, verify, memory/context, WF-MAX managers |
 | Architecture docs | Knows where boundaries live |
 | Context-loading protocol | Loads only the docs each agent needs |
 | `.claude/` + `.agents/skills/` | Claude Code and Codex skill adapters over the same Harness docs |
@@ -125,10 +125,15 @@ npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
 
 # Add only what's missing. Never overwrite.
 npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip --json
+
+# Install-complete structural gate.
+node Harness/scripts/validate-harness.mjs
 ```
 
 The JSON output is the agent's install report: `scan` replaces hand-written root probes, `plan.create` is script-owned, and `agent.aiMergeRequired` is the only list that needs semantic AI review. Do not read package source or templates unless `agent.aiMergeRequired` names a conflicting file.
 
+For existing projects, a passing non-strict validator is the install-complete gate. `--strict` is the bootstrap/release gate and may fail until PRD, research, and architecture placeholders have been resolved from real project facts.
+
 `npx` is an install and safe-merge entry, not an update engine for an already installed Harness. Once `Harness/` exists, use `/wf-update` in Claude Code, `$wf-update` in Codex, or `node Harness/scripts/wf-update-check.mjs`; root entry conflicts such as `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, and local Harness docs need agent-mediated merge decisions.
 
 | Flag | Does |
@@ -182,6 +187,14 @@ npx create-harness-vibe-coding@latest my-app . -y --dry-run --json
 
 Use `scan.markers` instead of manual top-level probes. Ask **at most 3 blocking questions** before touching files. Files in `plan.create` are handled by the script; only files in `agent.aiMergeRequired` need AI comparison and user-supervised merge decisions.
 
+Fast path for an existing project with no installed `Harness/`:
+
+1. Run the dry-run JSON command.
+2. Run the JSON `agent.safeMergeCommand` to create only missing files.
+3. Patch only files listed in `agent.aiMergeRequired`; preserve project-owned content.
+4. Run `node Harness/scripts/validate-harness.mjs`.
+5. Stop and report install status. Defer `--strict` until bootstrap fills project-fact placeholders.
+
 Ask these only when they affect writes:
 
 - If `CLAUDE.md` or `AGENTS.md` already exists, should missing Harness guidance be merged, kept separate, or skipped?
@@ -205,7 +218,10 @@ Harness docs always live in root `Harness/`; do not route Harness files through
 # In this package repo
 npm test
 
-# In a generated project after bootstrap
+# In an existing project immediately after safe-merge install
+node Harness/scripts/validate-harness.mjs
+
+# In a generated project after bootstrap, or before release
 node Harness/scripts/validate-harness.mjs --strict
 ```
 
@@ -229,7 +245,7 @@ my-project/
 │   ├── memory/                ← Durable self-learning
 │   └── scripts/               ← Validator
 ├── .claude/
-│   ├── agents/               ← 11 common agents
+│   ├── agents/               ← 16 built-in agents
 │   ├── skills/               ← Claude Code skill commands
 │   └── rules/                ← Universal coding rules
 ├── .agents/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "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/skills/wf-remove/SKILL.md

@@ -1,14 +1,17 @@
----
-name: wf-remove
-description: Use for /wf-remove in Claude Code, $wf-remove or /skills wf-remove in Codex, or any request to uninstall Harness safely.
----
-
-# WF Remove Adapter
-
+---
+name: wf-remove
+description: Use for /wf-remove in Claude Code, $wf-remove or /skills wf-remove in Codex, or any request to uninstall Harness safely.
+---
+
+# WF Remove Adapter
+
 ## Invocation
 
 - Claude Code: use `/wf-remove` or select the `wf-remove` skill.
 - Codex CLI or IDE: use `$wf-remove` or `/skills` then choose `wf-remove`.
+- User-facing removal is the slash/skill command. The Node commands below are
+  agent-internal execution steps; do not ask the user to copy/paste them unless
+  the agent has no shell/tool access.
 
 ## Load
 
@@ -17,21 +20,31 @@ description: Use for /wf-remove in Claude Code, $wf-remove or /skills wf-remove
 
 ## Flow
 
-1. Run `node Harness/scripts/wf-remove.mjs --json` for the machine-readable
-   plan.
-2. Auto-remove only SAFE files that still match stored checksums.
+1. On plain `/wf-remove`, run `node Harness/scripts/wf-remove.mjs --json` for
+   the machine-readable plan, then run the safe default apply command yourself.
+2. Auto-remove only SAFE files that still match stored checksums or exact
+   built-in Harness discovery files recognized by the script.
 3. Ask the user before every MODIFIED or uncertain file.
 4. Preserve USER DATA by default. For an explicit thorough uninstall, use
    `--purge-user-data` (alias `--purge`); add `--keep-tasks` when the user wants task records
    retained while project-fact Harness docs are removed.
-5. Run the script, not manual deletes:
+5. Run the script yourself, not manual deletes and not user-side command copy:
    - safe default: `node Harness/scripts/wf-remove.mjs --apply --yes`
    - thorough but keep tasks: `node Harness/scripts/wf-remove.mjs --apply --yes --purge-user-data --keep-tasks`
    - exact modified decisions: add `--delete-modified <path>` for each
      user-approved MODIFIED file.
+6. After apply, verify residual discovery folders:
+   - `.claude/agents`
+   - `.claude/skills`
+   - `.claude/commands`
+   - `.claude/rules`
+   - `.agents/skills`
+   - `.codex`
+   Built-in Harness files in these locations should be gone. Custom user skills
+   or user-owned files may remain and must be reported, not blindly deleted.
 
 ## Return
 
 Report SAFE removals, MODIFIED keep/delete decisions, preserved USER DATA,
-PURGE removals, directory cleanup, CLAUDE/AGENTS status, `.harness-version`
-status, and `git status` guidance.
+PURGE removals, directory cleanup, `.claude` / `.agents` / `.codex` residual
+status, `.harness-version` status, and `git status` guidance.

package/templates/common/.harness-version

@@ -1,6 +1,6 @@
 {
-  "generator": "0.8.4",
-  "generated": "2026-07-02T09:50:07.142Z",
+  "generator": "0.8.6",
+  "generated": "2026-07-02T10:59:32.891Z",
   "options": [],
   "autoCheck": true,
   "source": "https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/",
@@ -12,7 +12,7 @@
     ".agents/skills/wf-learn/SKILL.md": "sha256-7f3e1ee0aa83cbb76707698d0c26b703ad5c74b2df95a7dc4d751939a4ba05b2",
     ".agents/skills/wf-max/SKILL.md": "sha256-9b37cc3385f6d1a285b617169e91fbf71ffec76135b7b46ec1de2fe94ca220da",
     ".agents/skills/wf-readme/SKILL.md": "sha256-4d34ee3b6b305fa2581f5d8cb31e9152759f3df8bf8fa08efbb43782f128bdcd",
-    ".agents/skills/wf-remove/SKILL.md": "sha256-f27aee81d4d6988186f468ccc5dfd02c7605967636a5aea93d92443e030dbcc2",
+    ".agents/skills/wf-remove/SKILL.md": "sha256-21ebef1a1fa8645d094c8ceeca78b33f036b6c42cda6db8be425d38d9e91af75",
     ".agents/skills/wf-review/SKILL.md": "sha256-cc6d536ec6de25546a0ba96e686f195da50ed11bc03763a76ef46d77243d3537",
     ".agents/skills/wf-update/SKILL.md": "sha256-d57cd89e271b2af63b6a1264af552a30f8d44959cf4782b42f0ab082a90be9cf",
     ".agents/skills/wf/SKILL.md": "sha256-70766bd2cb02bc489b5cc021797af62596a005d444a026abb511054a1a820a67",
@@ -42,7 +42,7 @@
     ".claude/skills/wf-learn/SKILL.md": "sha256-7f3e1ee0aa83cbb76707698d0c26b703ad5c74b2df95a7dc4d751939a4ba05b2",
     ".claude/skills/wf-max/SKILL.md": "sha256-9b37cc3385f6d1a285b617169e91fbf71ffec76135b7b46ec1de2fe94ca220da",
     ".claude/skills/wf-readme/SKILL.md": "sha256-4d34ee3b6b305fa2581f5d8cb31e9152759f3df8bf8fa08efbb43782f128bdcd",
-    ".claude/skills/wf-remove/SKILL.md": "sha256-f27aee81d4d6988186f468ccc5dfd02c7605967636a5aea93d92443e030dbcc2",
+    ".claude/skills/wf-remove/SKILL.md": "sha256-21ebef1a1fa8645d094c8ceeca78b33f036b6c42cda6db8be425d38d9e91af75",
     ".claude/skills/wf-review/SKILL.md": "sha256-cc6d536ec6de25546a0ba96e686f195da50ed11bc03763a76ef46d77243d3537",
     ".claude/skills/wf-update/SKILL.md": "sha256-d57cd89e271b2af63b6a1264af552a30f8d44959cf4782b42f0ab082a90be9cf",
     ".claude/skills/wf/SKILL.md": "sha256-70766bd2cb02bc489b5cc021797af62596a005d444a026abb511054a1a820a67",
@@ -56,8 +56,8 @@
     "Harness/HARNESS_BRIDGE.md": "sha256-681dbeca9a590bbeb3a0c01b044e40e642e6d640632d8611064eb897ada8a48d",
     "Harness/MEMORY.md": "sha256-038217c5407a526dca3bd186ec4880f266fa6a8a31d52ebcd27d55aa11f32bb0",
     "Harness/MEMORY_PROTOCOL.md": "sha256-c24c232442a50f1dc7183480fc3b51c6171e32d3ba6648c056797ccd69fea717",
-    "Harness/README.md": "sha256-f646e1b02cd3344e4b379aa150af914758376fc576f6ed6e648d00b87a837405",
-    "Harness/SETUP.md": "sha256-33e05d9bc99449b7942db3a8c70160dab1c3ecfec0510afccd459790088118e8",
+    "Harness/README.md": "sha256-95f5d0bd9e250669845c9c5e0724fdb474b1d84ec90d97588501b15f5ef183e9",
+    "Harness/SETUP.md": "sha256-490fdac08d5cff4e3b3de4c2155aac18a67f305aa659187923d8a54a4a759873",
     "Harness/TDD-GUIDE.md": "sha256-602084530fd0dea7499a023ce75738351e5d97a0c222b64d405f36da6b59a162",
     "Harness/WF-AUTO-SPARK.md": "sha256-48cc08e1a78cd4abb2ae9c2807ef1ac9a09544eb954220b9087b2032fabbd690",
     "Harness/WF-AUTO.md": "sha256-d31b545249588a69c73e5e0ad8b1286ece1a53d9cd0e93b8ba0ae6dac6fdd119",
@@ -70,8 +70,8 @@
     "Harness/lifecycle.md": "sha256-a2d025e52f3b4412d8439083aca0d2cf7a4458ad0e30de4fc6465f990379190f",
     "Harness/research/README.md": "sha256-956c154df01cb9376972eb8b88bb3be0fe4e2dda802a72457c0126e3476fa755",
     "Harness/scripts/scan-clean.mjs": "sha256-7f693faf762c9c8e7657143d651f7c8369ed4823f18babe21daec58a55025593",
-    "Harness/scripts/validate-harness.mjs": "sha256-e584959476265d53408484ec3653dd652a0f64922c785db97f0638c26f19e04c",
-    "Harness/scripts/wf-remove.mjs": "sha256-4eb136ab26a9e20a949835e8cc6ff716b4beb3496c81ae3a4c03c049db60895c",
+    "Harness/scripts/validate-harness.mjs": "sha256-31dc33729034656d24ec163ff310164e2fc77289212b2278ab4a2f3d4b9294dc",
+    "Harness/scripts/wf-remove.mjs": "sha256-944e5da9dc1abcfb8f410bca743c3f5fbee2bc74d09b97e04ceaaf53da0cb9f1",
     "Harness/scripts/wf-update-check.mjs": "sha256-d14ce08f4c05ba118362a56a4b7d5965b114bc2b15a023c08e21d57f32b2cf93",
     "Harness/subagents.md": "sha256-16255092bab9011bb67359b4399d27ab292c14a717e67123e8a76e40e8669661",
     "Harness/templates/ACCEPTANCE.template.md": "sha256-394a6c08b155b1d121f1d51da774f7988bdb891224c6d5f2ca2c131e8c95ffb3",

package/templates/common/Harness/README.md

@@ -77,7 +77,7 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 | Need subagents | subagent, role pack, context, inject, return format, orchestrator, isolation | [subagents.md](subagents.md), [context-loading.md](context-loading.md), [dispatch.md](dispatch.md), [AGENT_ISOLATION.md](AGENT_ISOLATION.md) | controller plan, role-specific context pack, isolation-aware dispatch pack |
 | Need feature work | feature, implementation, TDD, test, review, closeout | [tasks/_template/PLAN.md](tasks/_template/PLAN.md), [agent-workflow.md](agent-workflow.md), [TDD-GUIDE.md](TDD-GUIDE.md), [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) | task plan, AC-linked RED tests, implementation loop |
 | Review or release check | review, release, finding, risk, evidence, verification | [agent-workflow.md](agent-workflow.md), current feature doc | findings, verification evidence |
-| Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | missing files and unresolved project placeholders |
+| Harness readiness check | validate, readiness, placeholder, missing file, release gate | `Harness/scripts/validate-harness.mjs`, `Harness/scripts/validate-harness.mjs --strict` | structural install check; strict bootstrap/release placeholder check |
 | Need harness update | /wf-update, $wf-update, update, check for updates, harness version | `.claude/skills/wf-update/SKILL.md`, `.agents/skills/wf-update/SKILL.md`, `Harness/.harness-version`, `Harness/scripts/wf-update-check.mjs` | script-driven comparison, SAFE/CONFLICT/PRESERVE classification, user decides conflicts |
 | Need harness removal | /wf-remove, $wf-remove, wf remove, remove harness, uninstall harness | `.claude/skills/wf-remove/SKILL.md`, `.agents/skills/wf-remove/SKILL.md`, `Harness/scripts/wf-remove.mjs` | safe removal plan: auto-remove SAFE, confirm MODIFIED, never touch USER DATA |
 
@@ -103,7 +103,7 @@ Routing priority: if a request explicitly says `/wf <task>`, `$wf`, `wf mode`, `
 - Do not add stack-specific agents or skills without following `extension.md`.
 - Do not close work without tests or recorded manual verification.
 - Do not mark work `Verified` until evidence is recorded in the current task's `tasks/<id>/PROGRESS.md` and `tasks/<id>/PLAN.md` or the feature doc.
-- Run `node Harness/scripts/validate-harness.mjs` for scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap and before release.
+- Run `node Harness/scripts/validate-harness.mjs` for install-complete scaffold structure; run `node Harness/scripts/validate-harness.mjs --strict` only after bootstrap resolves project-fact placeholders and before release.
 - If a doc still has `{{...}}`, treat that section as a template, not project fact.
 
 ## Doc Map

package/templates/common/SETUP.md

@@ -31,7 +31,7 @@ First clarify the idea, then create Mini PRD, acceptance criteria, UI/API contra
 
 ## Required Bootstrap Sequence
 
-Claude must follow this order:
+Claude or Codex must follow this order during bootstrap. This sequence is broader than installation; if the user only asked to install/configure the harness in an existing project, follow the "Existing Project Fast Path" below and stop after the non-strict validator passes.
 
 0. **ECC Stack Configuration** — Detect the project's tech stack. If the repo is empty or has no stack markers (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `Gemfile`, `composer.json`, `build.gradle`, etc.), ask the user: "What's your tech stack? (language/framework)" Then install the matching ECC rule sets from `~/.claude/rules/ecc/`. See `Harness/ECC-GUIDE.md` for the stack→rules mapping. Minimum: always install `common/`. Verify with `ls .claude/rules/ecc/`.
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`, `Harness/lifecycle.md`, and `Harness/ACCEPTANCE_PROTOCOL.md`. Load `Harness/memory/*` only when the router or memory trigger applies.
@@ -45,8 +45,8 @@ Claude must follow this order:
 9. Implement only after PRD-GATE, AC-GATE, CONTRACT-GATE, and TEST-GATE pass.
 10. Independently validate with an AC-by-AC result matrix; use `Harness/HARNESS_BRIDGE.md` for browser/API/CDP flows.
 11. For `/wf-auto` or memory scenario hints, read `Harness/WF-AUTO.md` and `Harness/MEMORY_PROTOCOL.md`; do not enable a background runner by default. The only allowed runtime hook is the optional `/wf-auto` bounded tick hook.
-11. Run `node Harness/scripts/validate-harness.mjs --strict`.
-12. Record final verification and next feedback step in `Harness/tasks/<task-id>/PROGRESS.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
+12. Run `node Harness/scripts/validate-harness.mjs --strict` after project-fact placeholders are resolved.
+13. Record final verification and next feedback step in `Harness/tasks/<task-id>/PROGRESS.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
 
 ## Install or Upgrade Path
 
@@ -59,20 +59,25 @@ Before writing, identify the project state:
 | Legacy architecture or older project docs | Treat existing code/docs as source of truth, dry-run first, then fill PRD, research, architecture, and task plans from observed facts |
 | Existing `Harness/` | Do not use `npx` as an updater; ask whether to run `/wf-update`, `$wf-update`, `node Harness/scripts/wf-update-check.mjs`, keep untouched, or remove/reinstall after approval |
 
-When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
-
-1. Get the machine-readable install report first with `npx create-harness-vibe-coding@latest <project-name> <target-dir> -y --dry-run --on-conflict skip --json`. Use `scan.markers` and `agent.aiMergeRequired` instead of hand-written root probes for install decisions. Do manual project-fact reading only after the script has created missing Harness files.
-2. Record discovered facts and open questions in `Harness/tasks/<task-id>/PROGRESS.md` before changing harness docs.
-3. Fill `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md` from observed project facts plus explicit user input.
+When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
+
+### Existing Project Fast Path
+
+Use this path when the user asks only to install or configure the harness in an existing project. Do not bootstrap PRD, research, architecture, or task capsules unless the user explicitly asks for bootstrap.
+
+1. Get the machine-readable install report first with `npx create-harness-vibe-coding@latest <project-name> <target-dir> -y --dry-run --on-conflict skip --json`. Use `scan.markers` and `agent.aiMergeRequired` instead of hand-written root probes for install decisions. Do manual project-fact reading only after the script has created missing Harness files.
+2. Run the JSON `agent.safeMergeCommand` to create only missing files.
+3. Record discovered facts in the final install summary. Create or update task capsules only when bootstrap or multi-step implementation work begins.
 4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.gitignore`, settings, package files, CI, docs routers, workflow docs, or installed skills/plugins/rules unless the user explicitly approves that exact overwrite.
-5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/extension.md`.
-6. Run `node Harness/scripts/validate-harness.mjs --strict` after project-fact placeholders have been resolved or intentionally recorded as open. Use the non-strict validator only for early structural checks.
+5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/extension.md`.
+6. Run `node Harness/scripts/validate-harness.mjs` as the install-complete gate.
+7. Defer `node Harness/scripts/validate-harness.mjs --strict` until bootstrap removes project-fact placeholders. If placeholders intentionally remain, report strict validation as deferred rather than treating install as failed.
 
 `npx create-harness-vibe-coding` is an install/safe-merge entry, not an update engine for a project that already has an installed Harness. If `Harness/` already exists, use `/wf-update`, `$wf-update`, or `node Harness/scripts/wf-update-check.mjs`; root entry files and user-modified Harness docs require agent-mediated merge decisions.
 
 ### Agent-Link Install Intake
 
-When the user installs by pasting the GitHub link into an agent, get the JSON install report before editing or asking generic questions. Summarize `scan.markers`, then ask only questions that affect writes, architecture, security, or workflow. Ask at most three blocking questions up front, record safe defaults for the rest, and ask follow-ups only when that choice becomes active.
+When the user installs by pasting the GitHub link into an agent, get the JSON install report before editing or asking generic questions. Do not fetch full template files or read package source until `agent.aiMergeRequired` names a file that needs semantic comparison. Summarize `scan.markers`, then ask only questions that affect writes, architecture, security, or workflow. Ask at most three blocking questions up front, record safe defaults for the rest, and ask follow-ups only when that choice becomes active.
 
 | Topic | Ask When | Default If Unanswered |
 | --- | --- | --- |
@@ -117,9 +122,9 @@ When `--on-conflict skip` leaves existing files untouched, the script still owns
      - **[Overwrite]** — Replace with the template version. Optionally backup the original first (`--on-conflict backup`).
      - **[Keep]** — Leave the existing file as-is. Skip this file.
 
-4. For Merge: use Edit (not Write) to add missing content. Only insert sections, headings, and text that are structurally required. Do not reorder or modify existing content. Do not remove custom project-specific registrations.
-
-5. After all merges, run `node Harness/scripts/validate-harness.mjs --strict` once after project-fact placeholders are resolved. Run the non-strict validator earlier only when you need a quick structural check before bootstrap is complete.
+4. For Merge: use targeted edits, not a full-file rewrite. In Codex, use `apply_patch` or an equivalent patch operation. Only insert sections, headings, and text that are structurally required. Do not reorder or modify existing content. Do not remove custom project-specific registrations. After merging `CLAUDE.md` or `AGENTS.md`, inspect the heading outline and remove duplicate headings or repeated bullets introduced by the merge.
+
+5. After all install merges, run `node Harness/scripts/validate-harness.mjs`. Run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders are resolved during bootstrap or release preparation.
 
 **File-specific gap checklists:**
 
@@ -131,12 +136,12 @@ The harness validator checks for specific structural invariants. When comparing
 | `AGENTS.md` | Root agent entry points to `CLAUDE.md` and `Harness/README.md`; for existing projects, merge only after explicit user consent |
 | `README.md` | Existing README is project-owned. Preserve by default; ask whether to append only Development notes or run `wf-readme` for a structure pass with tables/diagrams before broad edits |
 | `Harness/MEMORY.md` | All common agents registered under `## Agents`; all common harness skills registered under `## Skills`; all 3 `Harness/memory/` files registered under `## Memory Folder`; `Harness/memory/` folder usage guidance; `Project Resource Index` in title |
-| `.claude/rules/ecc/common.md` | `## Context` section with the durable communication invariant (`project files are the only durable communication channel`); `## Memory` section with three reflection file entries; `## Security` section |
+| `.claude/rules/ecc/common.md` | Required project-local universal rules. Keep it even when global `~/.claude/rules/ecc/common/` exists; that directory and this file have different scopes. Required sections: `## Context` with the durable communication invariant (`project files are the only durable communication channel`); `## Memory` with three reflection file entries; `## Security` |
 | `Harness/README.md` | `## Keyword Routing` heading; `## Load By Task` table with at minimum the rows: "Need WF mode", "Adding harness to existing project", "Need implementation plan", "Need parallel agents", "Need subagents", "Need durable memory or reflection"; WF routing keywords include `/wf`, `wf mode`, `workflow mode`, and `wk mode`; explicit WF/WK output says subagent docs load immediately; `## Doc Map` with `memory/` and `subagents.md` entries; the durable communication invariant text; `Harness/README.md is the primary router` |
 | `Harness/WF.md` | `WF mode requires multi-subagent orchestration by default`; explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` requires at least 3 distinct role passes before second planning; `collaboration decision tree`; `Heartbeat Protocol` |
 | `Harness/extension.md` | `## Non-Invasive Extension Rules` section with the "Preserve existing" rule; `## Agent Contract` section; `## Registration` section |
-| `Harness/dispatch.md` | The durable communication invariant; common agent entries for all 9 agents; `## Handoff Format` heading |
-| `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary router`; all 10 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier) |
+| `Harness/dispatch.md` | The durable communication invariant; registered common agent entries; `## Handoff Format` heading |
+| `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary router`; all 12 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier, Memory Master, Context Master) |
 | `Harness/subagents.md` | `## Source Attribution`; `## Built-in Agent Roster`; `## WF Default Fan-Out`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; `collaboration decision tree`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
 | `Harness/architecture.md` | `## 2. Interface Decoupling`; `## 3. State Design`; `Avoid speculative abstraction`; layer constraints derived from actual project facts |
 | `Harness/PROGRESS.md` | global task index with Active Task and task history; cross-task decisions |
@@ -146,12 +151,14 @@ The harness validator checks for specific structural invariants. When comparing
 | `Harness/workflows/browser-e2e.md` (if installed as optional) | `data-testid`, `accessible labels/roles`, and `inputs, buttons, filters, rows, empty/error/loading states` requirement |
 | `Harness/workflows/ts-react-frontend.md` (if installed as optional) | Same UI selector contract as above |
 
-**Files that do NOT need manual merge when the path does not already exist (auto-created by harness):**
+**Files that do NOT need manual merge when the path does not already exist (auto-created by harness):**
+
+The generated file list is authoritative by path, not by stale count labels. Current common scaffolds include WF-MAX manager agents and `tdd-guide`; keep every file created by the scaffold unless a removal workflow explicitly classifies it as safe to remove.
 
 - `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` — these are new empty files
-- `.claude/agents/*.md` — all 9 common agents
+- `.claude/agents/*.md` - all built-in common agent files, including WF-MAX managers and `tdd-guide`
 - `.claude/skills/*.md` and mirrored `.agents/skills/*.md` — Claude Code and Codex skill adapters over the same Harness docs
-- `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
+- `.claude/rules/ecc/common.md` - required project-local universal rules. Do not delete this file as a duplicate of a global `~/.claude/rules/ecc/common/` directory; they are different scopes.
 - `.claude/settings.json` — harness settings
 - `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md` — harness runtime docs
 - `Harness/research/*.md` — research protocol and templates
@@ -314,5 +321,5 @@ After scaffolding, use the JSON output first. Files in `plan.create[]` were hand
 
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
 2. Follow the Required Bootstrap Sequence above.
-3. Run `node Harness/scripts/validate-harness.mjs --strict` when done.
+3. Run `node Harness/scripts/validate-harness.mjs` after install. Run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap resolves project-fact placeholders.
 4. Delete `Harness/SETUP.md`.

package/templates/common/scripts/validate-harness.mjs

@@ -541,6 +541,9 @@ requireText('Harness/templates/TEST_PLAN.template.md', 'syntax-only checks', 'te
 requireText('.claude/skills/tdd/SKILL.md', 'Harness/ACCEPTANCE_PROTOCOL.md', 'tdd skill loads acceptance protocol');
 requireText('.claude/skills/tdd/SKILL.md', 'Harness/HARNESS_BRIDGE.md', 'tdd skill loads harness bridge');
 requireText('.claude/skills/tdd/SKILL.md', 'No syntax-only acceptance', 'tdd skill forbids syntax-only acceptance');
+requireText('.claude/skills/wf-remove/SKILL.md', 'User-facing removal is the slash/skill command', 'wf-remove slash command is user-facing');
+requireText('.claude/skills/wf-remove/SKILL.md', 'agent-internal execution steps', 'wf-remove script commands are agent-internal');
+requireText('.claude/skills/wf-remove/SKILL.md', 'verify residual discovery folders', 'wf-remove residual discovery verification');
 requireText('.claude/agents/tdd-guide.md', 'Browser Acceptance Rules', 'tdd-guide browser acceptance rules');
 requireText('.claude/agents/tdd-guide.md', 'real user actions', 'tdd-guide real user action requirement');
 requireText('.claude/agents/test-writer.md', 'Harness/ACCEPTANCE_PROTOCOL.md', 'test-writer loads acceptance protocol');

package/templates/common/scripts/wf-remove.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
- * wf-remove.mjs — Safely remove Harness framework files.
+ * wf-remove.mjs �?Safely remove Harness framework files.
  *
  * Classifies all Harness-owned files into:
- *   SAFE     — framework files matching stored checksums → auto-remove
- *   MODIFIED — framework files edited by user → MUST confirm
- *   USER     — user data files → NEVER remove
+ *   SAFE     �?framework files matching stored checksums �?auto-remove
+ *   MODIFIED �?framework files edited by user �?MUST confirm
+ *   USER     �?user data files �?NEVER remove
  *
  * Usage:
  *   node Harness/scripts/wf-remove.mjs                    # dry-run: show plan
@@ -23,12 +23,12 @@ import { resolve, dirname, join, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { createInterface } from 'readline';
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT_FILE = fileURLToPath(import.meta.url);
+const __dirname = dirname(SCRIPT_FILE);
+const SCRIPT_ROOT = resolve(__dirname, '..', '..');
 const ROOT = process.env.WF_ROOT
   ? resolve(process.env.WF_ROOT)
-  : (existsSync(resolve(process.cwd(), 'Harness', '.harness-version'))
-    ? process.cwd()
-    : resolve(__dirname, '..', '..'));
+  : SCRIPT_ROOT;
 const VERSION_FILE = resolve(ROOT, 'Harness', '.harness-version');
 
 // ── Classification ─────────────────────────────────────────────────
@@ -45,7 +45,7 @@ const HARNESS_PREFIXES = [
   'tests/.gitkeep',
 ];
 
-/** Files the user owns — NEVER remove. Consistent with wf-update-check PRESERVE_PATTERNS. */
+/** Files the user owns �?NEVER remove. Consistent with wf-update-check PRESERVE_PATTERNS. */
 const USER_DATA_PATTERNS = [
   /^Harness\/PROGRESS\.md$/,
   /^Harness\/tasks\//,
@@ -97,14 +97,67 @@ function isPurgeableHarnessData(file, { keepTasks }) {
   if (keepTasks && /^Harness\/tasks\//.test(file) && !isFrameworkTaskFile(file)) return false;
   return PURGEABLE_HARNESS_DATA_PATTERNS.some(p => p.test(file));
 }
-
-/** Framework files that should always exist (not part of removal). */
-const KEEP_FRAMEWORK = new Set([
-  'Harness/.harness-version',
-]);
-
-/** Directories to clean up if empty after file removal. */
-const CLEANUP_DIRS = [
+
+/** Framework files that should always exist (not part of removal). */
+const KEEP_FRAMEWORK = new Set([
+  'Harness/.harness-version',
+]);
+
+const BUILT_IN_AGENT_NAMES = [
+  'architect-manager',
+  'architect',
+  'context-master',
+  'debugger',
+  'docs-researcher',
+  'explore-manager',
+  'implement-manager',
+  'implementer',
+  'memory-master',
+  'planner',
+  'researcher',
+  'review-manager',
+  'reviewer',
+  'tdd-guide',
+  'test-writer',
+  'verifier',
+];
+
+const BUILT_IN_SKILL_NAMES = [
+  'browser-e2e',
+  'github-pr-review',
+  'python-backend',
+  'subagent-orchestrator',
+  'tdd',
+  'ts-react-frontend',
+  'ui-ux-review',
+  'wf',
+  'wf-auto',
+  'wf-auto-spark',
+  'wf-browser',
+  'wf-learn',
+  'wf-max',
+  'wf-readme',
+  'wf-remove',
+  'wf-review',
+  'wf-update',
+];
+
+const KNOWN_FRAMEWORK_FILES = new Set([
+  ...BUILT_IN_AGENT_NAMES.map(name => `.claude/agents/${name}.md`),
+  ...BUILT_IN_SKILL_NAMES.flatMap(name => [
+    `.claude/skills/${name}/SKILL.md`,
+    `.agents/skills/${name}/SKILL.md`,
+  ]),
+  '.claude/commands/wf-help.md',
+  '.claude/rules/ecc/common.md',
+]);
+
+function isKnownFrameworkFile(file) {
+  return KNOWN_FRAMEWORK_FILES.has(file);
+}
+
+/** Directories to clean up if empty after file removal. */
+const CLEANUP_DIRS = [
   '.claude/agents',
   '.claude/skills/wf-auto',
   '.claude/skills/wf-browser',
@@ -251,7 +304,7 @@ function removeEmptyDirs(startDir) {
 
 async function askUser(question) {
   if (!process.stdin.isTTY) {
-    console.log('   (non-interactive — defaulting to KEEP)');
+    console.log('   (non-interactive �?defaulting to KEEP)');
     return 'k';
   }
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -300,8 +353,9 @@ async function main() {
     addFilesUnder(allFiles, dir, scanIssues);
   }
 
-  // Add framework files that might not be in checksums (newer additions)
+  // Add framework files that might not be in checksums (newer additions)
   const extraPatterns = [
+    ...KNOWN_FRAMEWORK_FILES,
     '.claude/skills/wf/SKILL.md',
     '.agents/skills/wf/SKILL.md',
     '.claude/skills/tdd/SKILL.md',
@@ -323,9 +377,9 @@ async function main() {
   }
 
   // 2. Classify every file
-  const safe = [];     // SAFE — matches checksum, auto-remove
-  const modified = []; // MODIFIED — user edited, must confirm
-  const user = [];     // USER — never remove
+  const safe = [];     // SAFE �?matches checksum, auto-remove
+  const modified = []; // MODIFIED �?user edited, must confirm
+  const user = [];     // USER �?never remove
   const skipped = [];  // File not on disk, traversal rejected, or framework-keep
   const purge = [];    // Explicitly requested Harness user-data removal
   skipped.push(...scanIssues);
@@ -347,13 +401,13 @@ async function main() {
         });
         continue;
       }
-      user.push({ file, reason: 'user data — NEVER removed' });
+      user.push({ file, reason: 'user data �?NEVER removed' });
       continue;
     }
 
     // Only allow deletion of files under harness-owned prefixes
     if (!isHarnessOwned(canonical)) {
-      user.push({ file, reason: 'outside harness prefix — NEVER removed' });
+      user.push({ file, reason: 'outside harness prefix �?NEVER removed' });
       continue;
     }
 
@@ -366,15 +420,24 @@ async function main() {
       skipped.push({ file, reason: 'not on disk' });
       continue;
     }
-
-    const currentHash = sha256File(diskPath);
-    const storedHash = storedChecksums[file];
-
-    if (!storedHash) {
-      modified.push({ file, currentHash, storedHash: 'none', reason: 'not in checksums' });
-    } else if (currentHash === storedHash) {
-      safe.push({ file, currentHash, storedHash });
-    } else {
+
+    const currentHash = sha256File(diskPath);
+    const storedHash = storedChecksums[file];
+
+    if (!storedHash) {
+      if (isKnownFrameworkFile(canonical)) {
+        safe.push({
+          file,
+          currentHash,
+          storedHash: currentHash,
+          reason: 'known framework file missing from legacy checksums',
+        });
+      } else {
+        modified.push({ file, currentHash, storedHash: 'none', reason: 'not in checksums' });
+      }
+    } else if (currentHash === storedHash) {
+      safe.push({ file, currentHash, storedHash });
+    } else {
       modified.push({ file, currentHash, storedHash, reason: 'user modified' });
     }
   }
@@ -385,7 +448,7 @@ async function main() {
     const settingsHash = sha256File(settingsFile);
     const storedSettingsHash = storedChecksums['.claude/settings.json'];
     if (storedSettingsHash && settingsHash !== storedSettingsHash) {
-      // User modified settings — move to modified
+      // User modified settings �?move to modified
       // Remove from safe if it was there
       const idx = safe.findIndex(s => s.file === '.claude/settings.json');
       if (idx >= 0) {
@@ -429,16 +492,16 @@ async function main() {
     return;
   }
 
-  console.log('\n🧹 WF-REMOVE — Harness framework removal plan\n');
+  console.log('\n🧹 WF-REMOVE �?Harness framework removal plan\n');
 
   if (safe.length > 0) {
-    console.log(`✅ SAFE (${safe.length} files — auto-remove, unmodified framework):`);
-    for (const s of safe) console.log(`   ✕ ${s.file}`);
+    console.log(`�?SAFE (${safe.length} files �?auto-remove, unmodified framework):`);
+    for (const s of safe) console.log(`   �?${s.file}`);
     console.log('');
   }
 
   if (modified.length > 0) {
-    console.log(`⚠ MODIFIED (${modified.length} files — REQUIRE CONFIRMATION):`);
+    console.log(`�?MODIFIED (${modified.length} files �?REQUIRE CONFIRMATION):`);
     for (const m of modified) {
       console.log(`   ? ${m.file}  [${m.reason}]`);
     }
@@ -446,8 +509,8 @@ async function main() {
   }
 
   if (user.length > 0) {
-    console.log(`🔒 USER DATA (${user.length} files — NEVER removed):`);
-    for (const u of user) console.log(`   ○ ${u.file}  [${u.reason}]`);
+    console.log(`🔒 USER DATA (${user.length} files �?NEVER removed):`);
+    for (const u of user) console.log(`   �?${u.file}  [${u.reason}]`);
     console.log('');
   }
 
@@ -464,17 +527,17 @@ async function main() {
     return;
   }
 
-  // 4. Apply — remove SAFE files automatically (rehash before unlink)
+  // 4. Apply �?remove SAFE files automatically (rehash before unlink)
   let safeRemoved = 0;
   let safeFailed = 0;
   for (const s of safe) {
     const diskPath = safePath(s.file);
-    if (!diskPath) { console.error(`   ✗ Traversal rejected: ${s.file}`); safeFailed++; continue; }
+    if (!diskPath) { console.error(`   �?Traversal rejected: ${s.file}`); safeFailed++; continue; }
     if (!existsSync(diskPath)) continue;
     // Re-verify hash hasn't changed since classification
     const currentHash = sha256File(diskPath);
     if (currentHash !== s.storedHash) {
-      console.log(`   ⊘ Skipped (modified since classification): ${s.file}`);
+      console.log(`   �?Skipped (modified since classification): ${s.file}`);
       safeFailed++;
       continue;
     }
@@ -482,13 +545,13 @@ async function main() {
       unlinkSync(diskPath);
       safeRemoved++;
     } catch (e) {
-      console.error(`   ✗ Failed to remove: ${s.file} — ${e.message}`);
+      console.error(`   �?Failed to remove: ${s.file} �?${e.message}`);
       safeFailed++;
     }
   }
-  console.log(`✓ Removed ${safeRemoved} safe files.`);
+  console.log(`�?Removed ${safeRemoved} safe files.`);
 
-  // 5. Handle MODIFIED files — prompt user
+  // 5. Handle MODIFIED files �?prompt user
   let modifiedRemoved = 0;
   let modifiedKept = 0;
   let modifiedFailed = 0;
@@ -508,7 +571,7 @@ async function main() {
     }
     if (yes) {
       // Non-interactive mode: skip all modified
-      console.log(`   ⊘ Skipped (modified): ${m.file}`);
+      console.log(`   �?Skipped (modified): ${m.file}`);
       modifiedKept++;
       continue;
     }
@@ -520,17 +583,17 @@ async function main() {
     const answer = await askUser('   Choose [d/k]: ');
     if (answer === 'd' || answer === 'delete') {
       const diskPath = safePath(m.file);
-      if (!diskPath) { console.error(`   ✗ Traversal rejected: ${m.file}`); modifiedFailed++; continue; }
+      if (!diskPath) { console.error(`   �?Traversal rejected: ${m.file}`); modifiedFailed++; continue; }
       try {
         unlinkSync(diskPath);
-        console.log(`   ✓ Deleted: ${m.file}`);
+        console.log(`   �?Deleted: ${m.file}`);
         modifiedRemoved++;
       } catch (e) {
-        console.error(`   ✗ Failed: ${m.file} — ${e.message}`);
+        console.error(`   �?Failed: ${m.file} �?${e.message}`);
         modifiedFailed++;
       }
     } else {
-      console.log(`   ⊘ Kept: ${m.file}`);
+      console.log(`   �?Kept: ${m.file}`);
       modifiedKept++;
     }
   }
@@ -591,7 +654,7 @@ async function main() {
       }
     } else if (!existsSync(harPath) || (existsSync(harPath) && readdirSync(harPath).filter(f => f !== '.harness-version').length === 0)) {
       unlinkSync(VERSION_FILE);
-      console.log('✓ Removed .harness-version (Harness directory empty).');
+      console.log('�?Removed .harness-version (Harness directory empty).');
     }
   }
 
@@ -610,7 +673,7 @@ async function main() {
     if (pruned > 0) {
       versionData.checksums = checksums;
       writeFileSync(VERSION_FILE, JSON.stringify(versionData, null, 2) + '\n', 'utf-8');
-      console.log(`✓ Pruned ${pruned} stale checksum(s) from .harness-version.`);
+      console.log(`�?Pruned ${pruned} stale checksum(s) from .harness-version.`);
     }
   }
 
@@ -624,7 +687,7 @@ async function main() {
         // Strip the harness section: everything from "## 1. Harness Binding" to the next "## "
         const cleaned = content.replace(/## 1\. Harness Binding[\s\S]*?(?=## 2\.)/, '');
         writeFileSync(claudePath, cleaned, 'utf-8');
-        console.log('✓ Stripped Harness binding section from CLAUDE.md.');
+        console.log('�?Stripped Harness binding section from CLAUDE.md.');
       }
     }
   }