create-harness-vibe-coding 0.8.0 → 0.8.2

package/templates/common/SETUP.md

@@ -13,15 +13,15 @@ This scaffold is a 0-1 product harness:
 - `Harness/MEMORY.md` plus a `Harness/memory/` folder for durable self-learning, user corrections, and tool reflections
 - built-in common agents
 - subagent orchestration and context-loading protocol
-- skill-style dynamic loaders in `.claude/skills/` for Claude Code and `.agents/skills/` for Codex
+- skill-style dynamic loaders in `.claude/skills/` for Claude Code and `.agents/skills/` for Codex
 - lightweight harness validator
 - test/review/feedback loop
 
-It does not guess your stack or business domain. Claude Code or Codex should fill those through the lifecycle.
+It does not guess your stack or business domain. The agent MUST detect or ask, then install the right ECC rules for the project.
 
 ## Bootstrap Prompt
 
-Start Claude Code or Codex, then say:
+Start Claude Code or Codex, then say:
 
 ```text
 Read Harness/SETUP.md. Bootstrap this project as a 0-1 product harness.
@@ -33,6 +33,7 @@ First clarify the idea, then create PRD, research, architecture, Harness/PROGRES
 
 Claude must follow this order:
 
+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`, and `Harness/lifecycle.md`. Load `Harness/memory/*` only when the router or memory trigger applies.
 2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `Harness/tasks/<task-id>/PLAN.md`.
 3. Fill `Harness/research/PRD.md` with MVP, non-goals, and acceptance criteria.
@@ -44,33 +45,42 @@ Claude must follow this order:
 10. Run `node Harness/scripts/validate-harness.mjs --strict`.
 11. 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.
 
-## Existing Project Bootstrap Sequence
+## Install or Upgrade Path
 
-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. Scan existing project facts first: top-level files, `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `Harness/`, `README.md`, package files (`package.json`, `pyproject.toml`, `go.mod`, etc.), test commands, app entry points, CI files, existing docs, and current run/build scripts.
-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.
-4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.gitignore`, settings, hooks, package files, CI, docs routers, or workflow docs 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` after registration, then run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders have been resolved or intentionally recorded as open.
-
-`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` or `node Harness/scripts/wf-update-check.mjs`; root entry files and user-modified Harness docs require agent-mediated merge decisions.
+Before writing, identify the project state:
+
+| Project state | Required action |
+| --- | --- |
+| Empty or new project | Run the scaffold, then follow this file for 0-1 bootstrap |
+| Existing project, no `Harness/` | Scan project facts first, run `--dry-run`, preserve existing files, merge only missing Harness guidance |
+| 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.
+4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.gitignore`, settings, hooks, 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.
+
+`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, scan the project root before editing or asking generic questions. Summarize what exists, 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 |
-| --- | --- | --- |
-| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
-| Existing Harness | `Harness/` already exists | Stop and ask whether to run `/wf-update`, dry-run merge missing files, keep it untouched, or remove/reinstall after approval |
-| Harness location | Always | Use root `Harness/`; do not write harness docs into `docs/` |
-| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
-| README optimization | existing README is stale, sparse, missing command tables, or the user asks for diagrams/polished docs | Offer `wf-readme`; default to append-only Development notes until the user approves a structure pass or full rewrite |
-| Extensions | ECC, Superpowers, custom rules, or stack-specific skills may be useful | Recommend first; install only after user approval |
-| Optional capabilities | stack is known or the user wants setup guidance | Offer local workflows plus recommendation-only external options: Superpowers, Caveman, agent research, and code graph |
-| Skills | stack is known and optional skills could improve testing, frontend, backend, review, or browser evidence | Install 1-2 relevant local workflows only after user approval |
+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.
+
+| Topic | Ask When | Default If Unanswered |
+| --- | --- | --- |
+| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
+| Existing Harness | `Harness/` already exists | Stop and ask whether to run `/wf-update`, dry-run merge missing files, keep it untouched, or remove/reinstall after approval |
+| Harness location | Always | Use root `Harness/`; do not write harness docs into `docs/` |
+| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
+| README optimization | existing README is stale, sparse, missing command tables, or the user asks for diagrams/polished docs | Offer `wf-readme`; default to append-only Development notes until the user approves a structure pass or full rewrite |
+| Extensions | ECC, custom rules, or stack-specific skills may be useful | Scan installed skills/plugins/rules first; recommend only missing capabilities; install only after user approval |
+| Optional capabilities | stack is known or the user wants setup guidance | Offer local workflows plus recommendation-only GitHub links: Superpowers, Caveman, agent research, and code graph; do not duplicate already-installed capabilities |
+| Skills | stack is known and optional skills could improve testing, frontend, backend, review, or browser evidence | Install 1-2 relevant local workflows only after user approval |
 | CI/CD | CI config exists or the project lacks a test/build gate | Document existing commands first; add CI/CD only after user approval |
 | Verification depth | browser-visible, API, database, auth, payment, or deployment behavior is affected | Require real command evidence; require browser/API evidence when relevant |
 | Memory/privacy | repo contains sensitive domain data, customer data, secrets, or private workflows | Enable memory index only; never record secrets or private data |
@@ -79,23 +89,23 @@ When the user installs by pasting the GitHub link into an agent, scan the projec
 
 ### Agent Conflict Resolution Protocol
 
-When `--on-conflict skip` leaves existing files untouched, the agent resolves each conflict with user supervision.
+When `--on-conflict skip` leaves existing files untouched, the script still owns file creation and the agent resolves only the files named in `agent.aiMergeRequired`.
 
 **Workflow:**
 
 1. Run the harness tool in planning mode to get the conflict list:
    ```
-   npx create-harness-vibe-coding@latest . . -y --dry-run --json
+   npx create-harness-vibe-coding@latest . . -y --dry-run --on-conflict skip --json
    ```
-   Parse the JSON output. Files in `plan.skip[]` need attention. Files in `plan.create[]` are handled automatically.
+   Parse the JSON output. Files in `plan.create[]` are handled automatically by the script. If `agent.aiMergeRequired[]` is empty, do not read package source or templates; run the safe merge command from `agent.safeMergeCommand`.
 
-2. For each skipped file, locate the harness template counterpart:
-   - From npm: `node_modules/create-harness-vibe-coding/templates/common/<path>`
-   - From GitHub: `https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/<path>`
+2. For each file in `agent.aiMergeRequired[]`, use its `templateHint` to locate the harness template counterpart only when semantic comparison is needed:
+   - From npm: `node_modules/create-harness-vibe-coding/<templateHint>`
+   - From GitHub: `https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/<templateHint>`
 
 3. For each skipped file:
    - Read the existing project file.
-   - Read the harness template counterpart.
+   - Read the harness template counterpart only for that file.
    - Compare sections and headings. Identify structural sections, registration entries, and required text patterns that exist in the template but are missing from the existing file.
    - If the skipped file is `CLAUDE.md`, tell the user that it is the root agent entry contract. Ask whether they consent to refactor or merge it before editing. Preserve project-specific rules while adding the Harness startup, memory, router, workflow, and subagent orchestration contract.
    - If the skipped file is `AGENTS.md`, tell the user that it is part of the root agent entry contract and ask whether they consent to merge or replace it before editing.
@@ -106,7 +116,7 @@ When `--on-conflict skip` leaves existing files untouched, the agent resolves ea
 
 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`. Fix any remaining validation errors, then run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders are resolved.
+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.
 
 **File-specific gap checklists:**
 
@@ -117,10 +127,10 @@ The harness validator checks for specific structural invariants. When comparing
 | `CLAUDE.md` | Must be merged only after user confirmation when it already exists. Required contract: `## 1. Harness Binding & Startup` with the `Harness/SETUP.md` bootstrap contract line; `## 6. Memory & Self-Learning` section; the tool reflection trigger text (`same tool/use pattern fails 3+ times`); the user correction trigger text (`user corrects the same assumption/pattern 2+ times`); `Never bulk-read Harness/` in Startup |
 | `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 |
+| `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 |
 | `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/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) |
@@ -129,7 +139,7 @@ The harness validator checks for specific structural invariants. When comparing
 | `Harness/PROGRESS.md` | global task index with Active Task and task history; cross-task decisions |
 | `Harness/tasks/<id>/PROGRESS.md` | `## Current Goal`, `## Phase`, `## Heartbeat`, `## Loaded Context` headings |
 | `Harness/tasks/<id>/PLAN.md` | `## Tasks`, `## Parallel Dispatch`, `## Subagent Synthesis`, `## Verification` headings |
-| `Harness/SETUP.md` | Only meaningful for fresh projects. If the project has its own onboarding docs, skip this file entirely (it is temporary). If kept, ensure the "Existing Project Bootstrap Sequence" is present. |
+| `Harness/SETUP.md` | Temporary install/bootstrap guide for new projects, existing projects, legacy upgrades, and Harness update decisions. If kept, ensure "Install or Upgrade Path" is present. |
 | `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 |
 
@@ -137,7 +147,7 @@ The harness validator checks for specific structural invariants. When comparing
 
 - `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/skills/*.md` and mirrored `.agents/skills/*.md` — Claude Code and Codex skill adapters over the same Harness docs
+- `.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/settings.json` — harness settings
 - `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md` — harness runtime docs
@@ -145,15 +155,15 @@ The harness validator checks for specific structural invariants. When comparing
 - `AGENTS.md` — agent registry; if it already exists, ask for user consent before merging or replacing it
 - `Harness/scripts/validate-harness.mjs` and `tests/.gitkeep` — tooling
 
-Optional workflow examples:
-
-```bash
-npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
-npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
-npx create-harness-vibe-coding@latest my-app ./my-app -y --recommend superpowers,codegraph
-```
-
-`--recommend` records recommendation-only external capabilities in this file. It does not install third-party skills or plugins.
+Optional workflow examples:
+
+```bash
+npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
+npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
+npx create-harness-vibe-coding@latest my-app ./my-app -y --recommend superpowers,codegraph
+```
+
+`--recommend` records recommendation-only external capability links in this file. It does not install third-party skills or plugins.
 
 ### Template Fill Guide
 
@@ -200,7 +210,7 @@ False confidence is worse than a question. If you catch yourself thinking "this
 
 ## How to Find Proper Skills
 
-After the architecture stage reveals your stack, install matching agent skills. Skills teach Claude Code and Codex domain-specific patterns, testing conventions, and design rules.
+After the architecture stage reveals your stack, inspect existing `.claude/skills/`, `.agents/skills/`, plugins, hooks, and custom rules before recommending anything. Skills teach Claude Code and Codex domain-specific patterns, testing conventions, and design rules, but duplicate skills create routing noise.
 
 **Built-in route**: invoke the `/find-skills` skill (or say "help me find skills for X"). Examples:
 
@@ -211,28 +221,53 @@ After the architecture stage reveals your stack, install matching agent skills.
 "I need a skill for PostgreSQL schema design."
 ```
 
-**Superpowers**: [Superpowers](https://github.com/obra/superpowers) is a community skill registry. Search it:
+**External recommendation links**:
 
-```bash
-# If superpowers CLI or MCP is configured
-npx skills search "react testing"
-npx skills search "python api"
-```
+| Recommendation | Source | Purpose |
+| --- | --- | --- |
+| Superpowers | <https://github.com/obra/Superpowers> | **[RECOMMENDED]** community skill registry for agent workflows. Installed alongside ECC — Superpowers teaches *how to execute*, ECC defines *what standards to meet*. |
+| Caveman | <https://github.com/JuliusBrussee/caveman> | terse, low-token agent behavior and memory compression |
+| Agent Research | <https://github.com/lingzhi227/agent-research-skills> | research-agent skills for literature, product, dependency, and ecosystem investigation |
+| CodeGraph | <https://github.com/colbymchenry/codegraph> | code graph or repository-map tooling |
+
+These are links for the user's agent to evaluate. This scaffold does not maintain third-party install steps. If a user selects one, first check whether an equivalent capability is already installed; then present the GitHub link and ask for approval before the user's agent follows that project's own README.
+
+### ECC (Rules) vs Superpowers (Skills) — Complementary, Not Redundant
+
+ECC and Superpowers overlap ~80% in topic coverage but serve different purposes:
+
+| | ECC Rules | Superpowers Skills |
+|---|------|------|
+| **Role** | Coding STANDARD (what to enforce) | Coding GUIDE (how to execute) |
+| **Enforcement** | Hooks (PreToolUse/PostToolUse), validator | Agent self-discipline |
+| **Scope** | Universal + per-language (TS/Python/Go/...) | Universal (no language specifics) |
+| **TDD** | `testing.md`: coverage ≥80%, AAA pattern | `test-driven-development`: red-green-refactor workflow |
+| **Code Review** | `code-review.md`: severity levels, checklist | `requesting-code-review`: dispatch reviewer subagent |
+| **Subagents** | `subagents.md` + `dispatch.md`: role packs, write sets | `subagent-driven-development`: two-stage review after each task |
+| **Verification** | `testing.md` + `agent-workflow.md`: evidence before claims | `verification-before-completion`: verification before claiming done |
+| **Unique** | Design quality, performance budgets, security CSP, per-language idioms, hooks | Brainstorming, git worktrees |
+
+**Installation rule:**
+1. **ECC is mandatory.** Install `common/` + stack-specific rules during bootstrap step 0. See `Harness/ECC-GUIDE.md`.
+2. **Superpowers is recommended.** Install after ECC. It adds ~14 workflow skills that teach agents *how* to execute ECC standards.
+3. **No duplicates from other sources.** If a Superpowers skill has an ECC equivalent, keep both — they don't conflict. ECC sets the bar, Superpowers shows the path.
+4. **Priority**: ECC rules take precedence when there's a conflict. ECC is the contract; Superpowers is the training manual.
 
 **Manual discovery**: search GitHub and npm directly using patterns from `Harness/research/README.md#Architecture Decision References`.
 
 **Priority order**:
-1. `/find-skills` first — fastest discovery, respects your tool environment.
-2. Superpowers registry — broad community coverage.
-3. GitHub search — when the first two miss niche domains.
+1. Existing project skills/plugins/rules first - do not recommend duplicates.
+2. `/find-skills` or the runtime's local skill discovery - fastest and respects the user's tool environment.
+3. Selected external GitHub links - let the user's agent read that project's README and install only after approval.
+4. GitHub search - when the first three miss niche domains.
 
-**What to install**: after finding skills, add the canonical copy to `.claude/skills/<name>/SKILL.md` and mirror the same file to `.agents/skills/<name>/SKILL.md` when Codex should discover it. Follow `Harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
+**What to install**: after finding skills, add the canonical copy to `.claude/skills/<name>/SKILL.md` and mirror the same file to `.agents/skills/<name>/SKILL.md` when Codex should discover it. Follow `Harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
 
-This scaffold includes built-in harness skills in `.claude/skills/*` and mirrored Codex repo skills in `.agents/skills/*`. Keep those. Add stack-specific ones alongside them.
+This scaffold includes built-in harness skills in `.claude/skills/*` and mirrored Codex repo skills in `.agents/skills/*`. Keep those. Add stack-specific ones alongside them.
 
 ## Optional Agent Assets
 
-After the product shape is known, Claude Code may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Codex-discoverable workflow skills belong in `.agents/skills/`. Follow `Harness/extension.md` for every added asset.
+After the product shape is known, Claude Code may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Codex-discoverable workflow skills belong in `.agents/skills/`. Follow `Harness/extension.md` for every added asset.
 
 Examples:
 
@@ -262,16 +297,16 @@ After both steps, `Harness/SETUP.md` is fully isolated — no file references it
 If you are an AI agent running `create-harness-vibe-coding` to scaffold your own project harness, use non-interactive mode:
 
 ```bash
-npx create-harness-vibe-coding@latest <project-name> <target-dir> -y
+npx create-harness-vibe-coding@latest <project-name> <target-dir> -y --on-conflict skip --json
 ```
 
 Example:
 
 ```bash
-npx create-harness-vibe-coding@latest my-agent-project ./my-agent-project -y
+npx create-harness-vibe-coding@latest my-agent-project ./my-agent-project -y --on-conflict skip --json
 ```
 
-After scaffolding, bootstrap the harness yourself:
+After scaffolding, use the JSON output first. Files in `plan.create[]` were handled by the script; only files in `agent.aiMergeRequired[]` need AI merge work. Then bootstrap the harness yourself:
 
 1. Read `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
 2. Follow the Required Bootstrap Sequence above.

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

@@ -33,15 +33,17 @@ const commonAgents = [
   'review-manager',
 ];
 
-const commonSkills = [
-  'wf',
-  'wf-update',
+const commonSkills = [
+  'wf',
+  'wf-update',
   'wf-max',
   'wf-review',
   'wf-learn',
   'subagent-orchestrator',
   'wf-readme',
   'wf-remove',
+  'wf-auto',
+  'wf-auto-spark',
 ];
 
 const memoryFiles = [
@@ -56,15 +58,15 @@ const required = [
   'README.md',
   'Harness/MEMORY.md',
   'Harness/WF.md',
-  'Harness/WF-MAX.md',
-  ...memoryFiles,
-  '.codex/config.toml',
-  '.codex/hooks.json',
-  '.claude/settings.json',
-  '.claude/rules/ecc/common.md',
-  ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
-  ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
-  ...commonSkills.map(skill => `.agents/skills/${skill}/SKILL.md`),
+  'Harness/WF-MAX.md',
+  ...memoryFiles,
+  '.codex/config.toml',
+  '.codex/hooks.json',
+  '.claude/settings.json',
+  '.claude/rules/ecc/common.md',
+  ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
+  ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
+  ...commonSkills.map(skill => `.agents/skills/${skill}/SKILL.md`),
   'Harness/README.md',
   'Harness/PROGRESS.md',
   'Harness/lifecycle.md',
@@ -77,11 +79,11 @@ const required = [
   'Harness/research/README.md',
   'Harness/research/research-results.md',
   'Harness/research/PRD.md',
-  'Harness/scripts/wf-update-check.mjs',
-  'Harness/scripts/wf-remove.mjs',
-  'Harness/scripts/scan-clean.mjs',
-  'Harness/.harness-version',
-];
+  'Harness/scripts/wf-update-check.mjs',
+  'Harness/scripts/wf-remove.mjs',
+  'Harness/scripts/scan-clean.mjs',
+  'Harness/.harness-version',
+];
 
 const projectFacts = [
   'Harness/PROGRESS.md',
@@ -97,7 +99,7 @@ const contextPacks = [
   'Docs Researcher:',
   'Architect:',
   'Test Writer:',
-  'Implementer:',
+  'Implementer', // matches "Implementer:", "Implementer (Frontend):", "Implementer (Backend):"
   'Reviewer:',
   'Debugger:',
   'Verifier:',
@@ -146,6 +148,28 @@ function listMarkdownFiles(rel) {
     .map(entry => `${normalizedRel}/${entry.name}`);
 }
 
+// Task naming convention: task-<verb>-<noun>[-detail], kebab-case, ≤46 chars
+// Prefix "task-" required for new tasks. Existing tasks without prefix grandfathered (warning only).
+// Reserved: _template (system), auto (auto-mode capsule)
+const TASK_NAME_RE = /^task-[a-z]+(-[a-z0-9]+){1,4}$/;
+const TASK_NAME_MAX = 46; // "task-" (5) + ≤40 chars body + 1 safety = 46
+const TASK_RESERVED = new Set(['_template', 'auto']);
+
+function validateTaskName(name, strict) {
+  if (TASK_RESERVED.has(name)) return null;
+  if (name.startsWith('_')) return `Task name "${name}" — leading underscore reserved for system dirs`;
+  if (name.length > TASK_NAME_MAX) return `Task name "${name}" — ${name.length} chars, max ${TASK_NAME_MAX}`;
+  if (!TASK_NAME_RE.test(name)) {
+    // Grandfather: existing tasks without "task-" prefix get a warning, not an error
+    if (/^[a-z]+(-[a-z0-9]+){1,4}$/.test(name)) {
+      if (strict) return `Task name "${name}" — missing "task-" prefix (required for new tasks). Rename to "task-${name}".`;
+      return null; // non-strict: allow grandfathered names
+    }
+    return `Task name "${name}" — must be task-<verb>-<noun>[-detail], kebab-case, 2-5 words after prefix`;
+  }
+  return null;
+}
+
 function unresolvedTemplatePlaceholders(text) {
   const placeholders = [];
   const pattern = /\{\{([^{}\r\n]+)\}\}/g;
@@ -161,7 +185,7 @@ function unresolvedTemplatePlaceholders(text) {
 
 function registeredSkillFiles(...texts) {
   const files = new Set();
-  const pattern = /(?:\.\.\/)?((?:\.claude|\.agents)\/skills\/[a-z0-9-]+\/SKILL\.md)/g;
+  const pattern = /(?:\.\.\/)?((?:\.claude|\.agents)\/skills\/[a-z0-9-]+\/SKILL\.md)/g;
 
   for (const text of texts) {
     for (const match of text.matchAll(pattern)) {
@@ -210,6 +234,10 @@ const taskDirs = fs.existsSync(path.join(root, 'Harness', 'tasks'))
       .map(e => e.name)
   : [];
 for (const taskDir of taskDirs) {
+  // Validate task naming convention
+  const nameErr = validateTaskName(taskDir, strict);
+  if (nameErr) errors.push(nameErr);
+
   const planPath = `Harness/tasks/${taskDir}/PLAN.md`;
   const planText = read(planPath);
   if (!planText) continue;
@@ -327,7 +355,8 @@ for (const skillFile of registeredSkillFiles(docsReadme, memory)) {
 
 for (const workflowFile of registeredWorkflowFiles(docsReadme, memory)) {
   if (!fs.existsSync(path.join(root, workflowFile))) {
-    errors.push(`registered workflow file is missing: ${workflowFile}`);
+    // Optional workflows (browser-e2e, ts-react-frontend, etc.) may not be installed
+    continue;
   }
 }
 
@@ -349,24 +378,24 @@ function requireUiSelectorContract(rel) {
 requireUiSelectorContract('Harness/workflows/browser-e2e.md');
 requireUiSelectorContract('Harness/workflows/ts-react-frontend.md');
 
-for (const skill of commonSkills) {
-  const rel = `.claude/skills/${skill}/SKILL.md`;
-  const text = read(rel);
-  if (!text) continue;
-  if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
-  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
-}
-
-for (const skill of commonSkills) {
-  const claudeRel = `.claude/skills/${skill}/SKILL.md`;
-  const codexRel = `.agents/skills/${skill}/SKILL.md`;
-  const claudeText = read(claudeRel);
-  const codexText = read(codexRel);
-  if (!claudeText || !codexText) continue;
-  if (claudeText !== codexText) errors.push(`${codexRel} must mirror ${claudeRel}`);
-}
-
-for (const skill of listDirectories('.claude/skills')) {
+for (const skill of commonSkills) {
+  const rel = `.claude/skills/${skill}/SKILL.md`;
+  const text = read(rel);
+  if (!text) continue;
+  if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
+  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
+}
+
+for (const skill of commonSkills) {
+  const claudeRel = `.claude/skills/${skill}/SKILL.md`;
+  const codexRel = `.agents/skills/${skill}/SKILL.md`;
+  const claudeText = read(claudeRel);
+  const codexText = read(codexRel);
+  if (!claudeText || !codexText) continue;
+  if (claudeText !== codexText) errors.push(`${codexRel} must mirror ${claudeRel}`);
+}
+
+for (const skill of listDirectories('.claude/skills')) {
   if (commonSkills.includes(skill)) continue;
 
   const rel = `.claude/skills/${skill}/SKILL.md`;
@@ -374,22 +403,22 @@ for (const skill of listDirectories('.claude/skills')) {
   if (!text) continue;
 
   if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
-  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
-}
-
-for (const skill of listDirectories('.agents/skills')) {
-  const rel = `.agents/skills/${skill}/SKILL.md`;
-  const text = read(rel);
-  if (!text) continue;
-
-  if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
-  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
-
-  const claudeMirror = `.claude/skills/${skill}/SKILL.md`;
-  if (fs.existsSync(path.join(root, claudeMirror)) && text !== read(claudeMirror)) {
-    errors.push(`${rel} must mirror ${claudeMirror}`);
-  }
-}
+  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
+}
+
+for (const skill of listDirectories('.agents/skills')) {
+  const rel = `.agents/skills/${skill}/SKILL.md`;
+  const text = read(rel);
+  if (!text) continue;
+
+  if (frontmatterField(text, 'name') !== skill) errors.push(`${rel} frontmatter name does not match directory`);
+  if (!frontmatterField(text, 'description')) errors.push(`${rel} missing frontmatter field: description`);
+
+  const claudeMirror = `.claude/skills/${skill}/SKILL.md`;
+  if (fs.existsSync(path.join(root, claudeMirror)) && text !== read(claudeMirror)) {
+    errors.push(`${rel} must mirror ${claudeMirror}`);
+  }
+}
 
 for (const agent of commonAgents) {
   const rel = `.claude/agents/${agent}.md`;
@@ -420,17 +449,17 @@ requireText('Harness/research/README.md', 'research-results.md');
 requireText('Harness/WF.md', 'Ralph-style harness loop', 'WF loop description');
 requireText('Harness/WF.md', 'Heartbeat Protocol', 'heartbeat protocol');
 requireText('Harness/WF.md', 'WF mode requires multi-subagent orchestration by default', 'WF multi-subagent default');
-requireText('Harness/WF.md', 'Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use at least 3 distinct role passes', 'explicit WF/WK role-pass minimum');
+requireText('Harness/WF.md', 'Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use at least 3 distinct role passes', 'explicit WF/WK role-pass minimum');
 requireText('Harness/WF.md', '.claude/agents/', 'WF built-in agent roster path');
 requireText('Harness/WF.md', 'Collaboration decision tree', 'WF decision tree');
 requireText('Harness/WF.md', 'Harness/tasks/', 'WF task directory reference');
 requireText('Harness/README.md', '`wf mode`, `workflow mode`, or `wk mode`', 'WF/WK router aliases');
 requireText('Harness/README.md', 'explicit WF/WK loads subagent docs immediately', 'explicit WF/WK router output');
-requireText('.claude/skills/wf/SKILL.md', 'Harness/WF.md', 'wf skill loads core WF doc');
-requireText('.agents/skills/wf/SKILL.md', 'Harness/WF.md', 'Codex wf skill loads core WF doc');
+requireText('.claude/skills/wf/SKILL.md', 'Harness/WF.md', 'wf skill loads core WF doc');
+requireText('.agents/skills/wf/SKILL.md', 'Harness/WF.md', 'Codex wf skill loads core WF doc');
 requireText('.claude/skills/subagent-orchestrator/SKILL.md', 'Harness/subagents.md', 'subagent-orchestrator loads subagents doc');
 requireText('.claude/skills/subagent-orchestrator/SKILL.md', '.claude/agents/', 'subagent-orchestrator built-in agent roster path');
-requireText('.claude/skills/subagent-orchestrator/SKILL.md', '`workflow mode`, or `wk mode`', 'subagent-orchestrator WF/WK aliases');
+requireText('.claude/skills/subagent-orchestrator/SKILL.md', '`workflow mode`, or `wk mode`', 'subagent-orchestrator WF/WK aliases');
 requireText('.claude/skills/wf-readme/SKILL.md', 'README.md', 'wf-readme loads README');
 requireText('.claude/skills/wf-readme/SKILL.md', 'Harness/architecture.md', 'wf-readme links architecture docs');
 requireText('Harness/subagents.md', '## Source Attribution', 'subagent source attribution');
@@ -449,6 +478,8 @@ requireText('Harness/architecture.md', 'Avoid speculative abstraction', 'anti-ov
 requireText('CLAUDE.md', 'Use explicit interfaces or state models only when they protect a real boundary', 'CLAUDE interface/state simplicity rule');
 requireText('CLAUDE.md', '/wf-update', 'wf update startup instruction');
 requireText('Harness/README.md', 'Need harness update', 'update routing row');
+requireText('Harness/WF-MAX.md', 'three-layer architecture', 'WF-MAX three-layer architecture');
+requireText('Harness/WF-MAX.md', 'agent role', 'WF-MAX agent role separation');
 requireText('Harness/WF-MAX.md', 'write-set coloring', 'WF-MAX coloring algorithm');
 requireText('Harness/WF-MAX.md', 'wave dispatch', 'WF-MAX wave dispatch');
 requireText('Harness/README.md', '/wf-max', 'wf max router alias');
@@ -457,6 +488,9 @@ requireText('Harness/subagents.md', 'Max parallelism', 'subagents max parallelis
 requireText('Harness/dispatch.md', 'Concurrency group', 'dispatch concurrency group field');
 requireText('Harness/dispatch.md', 'File claim', 'dispatch file claim field');
 requireText('CLAUDE.md', '/wf-max', 'wf max startup instruction');
+requireText('CLAUDE.md', 'three-layer architecture', 'CLAUDE.md three-layer role architecture');
+requireText('Harness/scripts/wf-mode-hook.mjs', 'agentRole', 'hook agentRole validation');
+requireText('Harness/scripts/wf-mode-hook.mjs', 'writeSet', 'hook writeSet enforcement');
 
 if (errors.length) {
   console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);