create-harness-vibe-coding 0.8.7 → 0.8.9

package/templates/common/Harness/WF.md

@@ -1,255 +1,135 @@
-# WF Mode - Long Task Workflow
+# WF Mode — Dynamic Orchestration Kernel
 
-Use this when work is long, difficult, uncertain, multi-file, multi-agent, or
-user-triggered with `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode`.
+`/wf` is a **dynamic workflow kernel**, not a fixed serial pipeline. The orchestrator (main agent) makes decisions, dispatches agents, synthesizes returns, and owns final acceptance. It does NOT do bulk source reading, log scraping, or task-state paperwork — those are delegated to appropriate subagents.
 
-This is a Ralph-style harness loop: keep moving through evidence, bounded
-exploration, second planning, implementation, review, verification, and recovery
-instead of stalling on the first obstacle.
+WF is **explicit only**. Complexity does not auto-trigger WF.
 
-WF is acceptance-driven. The source of truth is not the implementation, not the
-tests, and not the agent's summary. The source of truth is the PRD-derived
-Acceptance Criteria. Code, tests, review, validation, debug, and memory must
-trace to AC IDs. Load [ACCEPTANCE_PROTOCOL.md](ACCEPTANCE_PROTOCOL.md) for the
-gate contract, [AGENT_ISOLATION.md](AGENT_ISOLATION.md) for role separation, and
-[HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) for UI/API/browser evidence.
+## Shared Kernel
+
+All WF variants (`/wf`, `/wf-max`, `/wf-auto`, `/wf-auto-spark`, `/wf-review`, `/wf-browser`) share the orchestration engine defined in [WF-KERNEL.md](WF-KERNEL.md). That file is the authoritative source for:
+
+- Role / Model Matrix (which agent, which model tier, for which work)
+- Dynamic ready-queue pseudocode
+- Dispatch packet fields
+- Task type → agent/skill routing
+- Tier-aware acceptance gates
+- State ownership rules (controller + task-scribe)
+
+Resumable state follows [WF-STATE.md](WF-STATE.md): STATE.json is the machine-readable resume truth; the ready queue is persisted there across sessions.
+
+This file defines the `/wf` user contract, tiers, and the standard orchestration loop.
 
 ## Trigger
 
-Enter WF mode when any of these are true:
-
-- The user explicitly says `/wf`, `$wf`, `wf mode`, `workflow mode`, `wk mode`,
-  or asks for the full workflow.
-- The task needs more than one step, more than three files, or more than one
-  subsystem.
-- The task needs research, architecture judgment, browser/API validation, or
-  migration planning.
-- Confidence in intent, architecture, or implementation is below 95%.
-- The same command, test, tool, or approach fails twice.
-- The user explicitly says `/wf-max [task]`, `$wf-max [task]`, or `wf max` (for
-  maximum-parallelism mode, see [WF-MAX.md](WF-MAX.md)).
-
-Two distinct trigger classes; do not conflate them:
-
-- Explicit invocation (`/wf`, `$wf`, `wf mode`, `workflow mode`, `wk mode`,
-  `/wf-max`, `$wf-max`): role fan-out is mandatory and unconditional. File
-  count, task size, and subsystem count are irrelevant. A one-file task invoked
-  with WF still schedules the complete role chain before closeout.
-- Auto-triggering decides whether the harness enters WF mode on its own. It can
-  only escalate into WF, never downgrade an explicit command out of WF.
-
-## Complete Role Chain Requirement
-
-WF mode requires the complete role chain by default.
-
-Normative rule: Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST cover every mandatory role class before closeout: Plan, Research, Architecture, Test, Implement, Independent Validation, Cross-Review, Reflect, and Final Acceptance.
-
-- Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST schedule
-  the complete role chain at intake. Use real subagents when the runtime
-  supports them; otherwise emulate those roles as bounded passes and record the
-  fallback.
-- Mandatory role classes:
-  - Plan: `planner`
-  - Research: `researcher` or `docs-researcher`; use both when local and external/current facts matter
-  - Architecture: `architect`
-  - Test: `test-writer`
-  - Implement: `implementer` and `debugger` when needed
-  - Independent Validation: `verifier` records AC-mapped evidence before cross-review
-  - Cross-Review: at least two independent review lenses after implementation
-  - Reflect: `reflector`
-  - Final Acceptance: controller accepts only after cross-review passes and `reflector` returns PASS
-- Runtime mapping:
-  - Claude Code: prefer subagents from `.claude/agents/`.
-  - Codex: prefer the available Codex subagent surface; if unavailable, use
-    bounded passes with the same roles and evidence contract.
-- Collaboration decision tree (replaces the old "7:3" heuristic with concrete
-  conditions):
-  - Explicit WF/WK mode -> complete role chain, no exceptions.
-  - 3+ files changed -> complete role chain.
-  - Cross-layer change -> complete role chain plus separate architecture review.
-  - Uncertain scope or approach -> complete role chain with both researcher and architect passes.
-  - 1-2 files, well-understood, not in WF mode -> solo is acceptable.
-  - Repeated failure on the same task -> stop solo and switch to multi-role.
-- Default `/wf` startup records the full chain in the task plan. Dependency-bound
-  roles run when their phase is ready; they are not optional.
-
-## Exploration Gate
-
-- [ ] Controller has not read source files directly; only Harness docs, root
-  agent entries, and subagent or bounded-pass returns.
-- [ ] Complete role chain is scheduled in the task plan.
-- [ ] Plan, Research, and Architecture role passes each have one specific question before second planning.
-- [ ] Role passes were dispatched together when the runtime supports parallel
-  dispatch.
-- [ ] Agent count is at least `max(3, ceil(estimated_dirs / 2))`; estimate from
-  prompt/docs and run a second wave if returns reveal more.
-- [ ] Fallbacks are recorded in `Harness/tasks/<task-id>/PLAN.md`.
-
-For maximum-parallelism mode (write-set coloring, wave dispatch, parallel
-reviewers), use `/wf-max [task]` in Claude Code or `$wf-max [task]` in Codex and
-see [WF-MAX.md](WF-MAX.md).
-
-## WF Loop
+WF is **explicit only**. Enter WF ONLY when the user explicitly types:
+- `/wf`, `$wf`, `/skills wf`
+
+These are NOT WF triggers:
+- Multi-step work, multi-file changes, complexity, uncertainty, architecture scope, browser/API behavior, repeated failure
+- Those may need planning, subagents, or tests — but not WF
+
+## Memory Preflight
+
+1. Load `CLAUDE.md`, `Harness/MEMORY.md` index only, then `Harness/README.md`.
+2. Load `Harness/memory/*` only when `MEMORY_PROTOCOL.md` scenario hints match.
+3. Record `Memory preflight: done` and `Memory hints: none | <file/path + reason>`.
+
+## Standard Orchestration Loop
+
+The `/wf` kernel follows a dependency-driven ready-queue, NOT a fixed serial phase list.
 
 ```text
 Intake
--> confidence gate
--> parallel planner / researcher / docs-researcher / architect roles
--> Mini PRD
--> Acceptance Criteria
--> UI/API contracts
--> test plan
--> second plan
--> test-writer
--> implementer
--> independent validator
--> cross-review: spec/AC reviewer + code/architecture/test reviewer
--> reflector
--> if failed: debugger -> verifier -> cross-review -> reflector -> loop
--> memory closeout with evidence
+-> Understand user goal; ask <=3 blocking decision questions (each with recommendation)
+-> Requirement analysis: scope, non-goals, risks, acceptance direction
+-> Mini PRD (compact, not a large document)
+-> 1-3 ACs (expand only for high-risk triggers)
+-> Plan: task split, dependencies, readSet/writeSet, verification commands, subagent dispatch
+
+// Ready-queue dispatch (NOT serial phase)
+while task not accepted:
+    update readyQueue from dependency graph
+
+    // Read-only and chore — always parallel when ready
+    dispatch codebase-explorer(s) for scoped source reading
+    dispatch docs-researcher / researcher as needed
+    dispatch planner for decomposition (unless already done)
+    dispatch task-scribe alongside any work
+
+    // Write gate
+    for each independent writeSet:
+        dispatch implementer (one file_claim each)
+        when wave complete: dispatch verifier
+
+    // Review gate — wave-level, not end-of-task
+    when verifier evidence exists for a wave:
+        dispatch reviewer(s) on that wave
+
+    // Fix gate — on-demand
+    if review finding or failed AC:
+        dispatch debugger or implementer (smallest fix)
+        re-run verifier
+
+    // Reflect gate — WF-Full only or risk-triggered
+    if WF-Full or unresolved contradiction:
+        dispatch reflector
+
+    // Closeout
+    task-scribe records final state
+    if durable lesson: context-master -> memory-master
+
+    stop on: accepted | blocked | user decision required
 ```
 
-## Intake
+## WF Tiers
 
-1. Read `CLAUDE.md`, `Harness/MEMORY.md`, `Harness/README.md`,
-   `Harness/PROGRESS.md`, and the active task capsule if present.
-2. State the goal, non-goals, confidence level, known risks, acceptance truth
-   files, and write boundaries.
-3. Ask up to three blocking questions only when the next action cannot reach
-   95% confidence.
-4. Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` before dispatching
-   roles or running long commands.
-5. Load `Harness/subagents.md` before coordinating multiple roles.
+### WF-Light
+1-2 files, well-understood, low risk.
+- planner + test-writer + implementer + verifier
+- task-scribe maintains state
+- codebase-explorer optional
+- **Acceptance**: verification passes = closeout
+- Cross-review and reflector NOT mandatory
+
+### WF-Standard
+Multi-file or behavior change.
+- WF-Light baseline + research/docs + at least one independent review lens
+- Parallel: codebase-explorer(s), docs-researcher/researcher, planner, task-scribe
+- **Acceptance**: verifier evidence + one review PASS = closeout
+- Reflector: only when risk, contradiction, or high impact triggers
+
+### WF-Full
+High-risk, cross-layer, security/data-loss, browser/API acceptance, ambiguous architecture.
+- Full chain per [WF-KERNEL.md](WF-KERNEL.md) Role/Model Matrix
+- **Acceptance**: cross-review PASS + reflector PASS
+
+## State Ownership
+
+Per [WF-KERNEL.md](WF-KERNEL.md):
+- **Controller** (main agent): decisions, decomposition, synthesis, final verification
+- **task-scribe** (haiku): writes task state (PLAN, PROGRESS, ARTIFACTS, NOTES). Controller supplies structured updates; task-scribe formats and writes.
+- **Production source agents**: write ONLY their assigned writeSet. Never write task state.
 
 ## Exploration
 
-Use read-only role passes first. For automatic WF triggers, default to 3-5
-active agents or bounded passes unless the task is clearly small enough for the
-solo exception.
-
-| Role | Purpose | Writes |
-| --- | --- | --- |
-| `planner` | map local project facts, commands, app entry points, existing docs, and initial decomposition | none |
-| `researcher` | product, ecosystem, dependency, and external context | none unless returning a docs patch |
-| `docs-researcher` | official docs, SDK/API versions, browser/tool limits | none unless returning a docs patch |
-| `architect` | boundaries, ports, data flow, state impact, migration risks | none unless returning a docs patch |
-
-Use local files first. Use web search or official docs only when the decision
-needs current or external evidence. Record tool choice and limitations in
-`Harness/research/research-results.md` or the task plan.
-
-## Subagent Orchestration
-
-Use `Harness/subagents.md` as the orchestration methodology and
-`Harness/dispatch.md` as the dispatch table protocol.
-
-- The main agent is the controller and owns synthesis, integration, and final
-  verification.
-- Subagents are readers and reporters. Only the main agent writes task
-  `PROGRESS.md` and `PLAN.md`.
-- Parallelize read-only exploration; serialize writers unless write sets are
-  disjoint and isolated.
-- Every role gets a dispatch pack with role, goal, mode, read set, write set,
-  forbidden scope, injected docs, evidence, stop condition, and return format.
-- After implementation, run spec review before code-quality or architecture
-  review.
-- If subagents are unavailable, emulate the same roles as bounded passes and
-  record the fallback.
-
-## Second Plan
-
-After exploration, synthesize facts found, assumptions, risks,
-accepted/rejected options, Mini PRD, AC IDs, UI/API contracts, tasks,
-read/write sets, verification path, and rollback or recovery plan.
-
-Write the result to `Harness/tasks/<task-id>/PLAN.md` before implementation.
-Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`.
-
-The second plan must pass:
-
-- PRD-GATE: goal, scope, non-scope, user flow, and verification commands exist.
-- AC-GATE: each behavior has an AC ID and Given/When/Then.
-- CONTRACT-GATE: UI/API/state contracts exist when the feature touches UI/API/state.
-- TEST-GATE: verification commands and test levels map to AC IDs.
-- IMPLEMENT-GATE: implementer forbidden set includes PRD, AC, UI/API contracts, test plan, and validation report unless a Change Request is approved.
-
-## Build And Review
-
-1. `test-writer` defines failing tests or written manual checks from AC IDs and contracts first.
-2. `implementer` changes only the declared write set and may not edit truth files without Change Request.
-3. `verifier` or independent validator runs AC-mapped checks against running behavior and records an evidence matrix before cross-review.
-4. Cross-review is mandatory: at least two independent review lenses must pass before acceptance.
-   - Spec/AC review checks request, scope, contracts, and non-goals.
-   - Code/architecture/test review checks implementation risk, maintainability, security, and verification adequacy.
-5. `reflector` reads verifier evidence and reviewer findings, resolves contradictions with the controller, and returns PASS before final acceptance.
-6. For cross-layer or risky work, run separate reviewers for spec/AC compliance, architecture, security, and test adequacy.
-
-## Browser And API Evidence
-
-For browser-visible changes, typecheck/build/unit tests are not enough. Use
-Chrome DevTools, CDP, Playwright, or a documented real-browser run:
-
-- start the app and record URL/port
-- click through the critical flow
-- capture frontend console/runtime errors
-- capture failed network requests
-- collect backend logs when the flow crosses an API
-- record screenshot, trace, video, or manual evidence path
-- produce an AC-by-AC acceptance result matrix
-- for frontend-backend paths, check UI selectors and API behavior against `HARNESS_BRIDGE.md`
-
-For API changes, run the project API/integration test path or a documented real
-request against a local service and record request, response, logs, and failure
-behavior.
-
-## Recovery Loop
-
-If verification fails:
-
-1. Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` with failure count
-   and blocker.
-2. Dispatch `debugger` with the failed AC ID, failing command, error output,
-   trace/screenshot/network evidence, and smallest relevant files.
-3. Classify the failure layer using [DEBUG_PROTOCOL.md](DEBUG_PROTOCOL.md), then fix the smallest reproduced failure.
-4. Run verifier again and record fresh AC-mapped evidence.
-5. Run cross-review again.
-6. Run reflector again.
-7. Repeat until verified or blocked by missing user input/external state.
-
-Before asking the user after repeated failures, run the context-master then
-memory-master learning cycle or use `wf-learn`.
-
-## Heartbeat Protocol
-
-Heartbeat is a lightweight recovery protocol, not a background daemon.
-Keep heartbeat entries to one or two lines: phase, blocker/failure, next action,
-and evidence pointer. Do not paste command logs or subagent transcripts.
-
-Update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat`:
-
-- before a long command
-- after a long command
-- before spawning subagents or bounded passes
-- after integrating returns
-- after each failed verification
-- before stopping for user input
-
-When context approaches about 85% of the window, run context-master or the
-equivalent bounded pass to append a compression suggestion to the task heartbeat.
+Controller delegates source reading to subagents. Controller does NOT read source files directly before dispatch.
+
+First wave — dispatch in parallel:
+- codebase-explorer(s): scoped source discovery
+- planner: decomposition, dependencies, writeSet
+- researcher / docs-researcher: external context as needed
+- task-scribe: compact heartbeat and dispatch ledger
+
+Second wave — after synthesis:
+- architect (if cross-layer or architecture risk)
+- test-writer: failing tests from AC IDs
+
+## Browser and API Evidence
+
+See [HARNESS_BRIDGE.md](HARNESS_BRIDGE.md) and [WF-KERNEL.md](WF-KERNEL.md) Task Type Routing for UI/browser and API/backend task types.
+
+Agents live under `.claude/agents/` and `.opencode/agents/`. Task state lives under `Harness/tasks/<task-id>/`.
 
 ## Closeout
 
-Close only when:
-
-- PRD-GATE, AC-GATE, CONTRACT-GATE, TEST-GATE, VALIDATION-GATE, REVIEW-GATE, and REFLECT-GATE are satisfied
-- acceptance criteria are satisfied and reported by AC ID
-- cross-review has passed with no unresolved critical/high findings
-- reflector verdict is PASS
-- test/API/browser evidence is recorded
-- affected Harness docs are synced
-- context-master has analyzed the session and extracted durable knowledge
-- memory-master has consolidated extracted knowledge into `Harness/memory/*`
-- current task PROGRESS.md and PLAN.md are archived under `Harness/tasks/<task-id>/`
-  with Phase set to Verified
-- `Harness/PROGRESS.md` task index is updated and Active Task is cleared or set
-  to the next task
+Closeout is tier-aware. WF-Light: verification + task state update = done. WF-Full: full gate chain per [WF-KERNEL.md](WF-KERNEL.md).

package/templates/common/Harness/agent-workflow.md

@@ -118,8 +118,8 @@ Use [subagents.md](subagents.md) and [dispatch.md](dispatch.md) for multi-agent
 | Mode | Agent Count Rule | Source |
 |------|-----------------|--------|
 | Default (non-WF) | up to 3 active agents by default | This file |
-| `/wf` | complete role chain mandatory before closeout | [WF.md](WF.md) |
-| `/wf max` | complete WF role chain plus maximum useful fan-out | [WF-MAX.md](WF-MAX.md) |
+| `/wf` | WF-KERNEL tier selection (Light/Standard/Full) by risk and scope; full role chain only at WF-Full | [WF.md](WF.md) |
+| `/wf-max` | WF kernel plus maximum useful fan-out (WF-Max-Useful default; WF-Max-Strict explicit only) | [WF-MAX.md](WF-MAX.md) |
 
 Prefer parallel read-only work first, then serial writes.
 

package/templates/common/Harness/architecture.md

@@ -1,126 +1,126 @@
-# Harness Architecture - create-harness-vibe-coding
-
-> **Responsibility**: Define the repository structure and scaffold generation boundaries.
-> **Does NOT cover**: Generated target-project business architecture.
-
----
-
-## 1. Layering Rules
-
-```text
-bin/
-  CLI executable shim. Calls src/index.js.
-
-src/
-  CLI orchestration and scaffold generation logic.
-  May read templates/ and write the chosen target directory.
-
-templates/
-  Source of generated scaffold assets.
-  Must stay declarative: markdown, skill files, agent files, scripts, and optional workflow docs.
-
-Harness/ and .claude/
-  Dogfood runtime for this repository's own agent work.
-  Must not be treated as package source unless intentionally copied into templates/.
-
-tests/
-  Node test suite for CLI behavior, generator behavior, package contents, and generated harness validation.
-```
-
-Hard constraints:
-
-- `templates/common/**` and `templates/optional/**` are the source of generated output.
-- Root `Harness/**` is this repository's operating harness; changing it does not change generated projects.
-- Generated output paths are normalized by `harnessDest()` in `src/generator.js`.
-- Existing-project safety is owned by conflict planning in `src/generator.js`, not by template prose alone.
-- Package publication is constrained by `package.json#files`; root dogfood files are not package contents.
-
-## 2. Interface Decoupling
-
-Use interfaces and module boundaries to protect real seams in the generator, not to decorate straightforward code.
-
-- `src/index.js` owns CLI/user interaction; `src/generator.js` owns planning and file writes.
-- Template files are declarative inputs; source code should not depend on root dogfood `Harness/**`.
-- Optional catalog structure is the extension contract for presets and optional skills.
-- Avoid speculative abstraction: do not add plugin systems, generic runners, extra config layers, or service containers until a real second use or testability boundary exists.
-- When a boundary is real, express it with a small data contract and test it through generated output behavior.
-
-## 3. State Design
-
-State in this repo should be explicit, serializable, and owned by one layer.
-
-- Generator plan state is computed in memory and returned as `plan`/`summary`; file writes consume that plan instead of re-deciding conflicts.
-- Filesystem state is authoritative only through existence/type checks and write results.
-- Optional selection state comes from CLI flags plus `templates/optional/catalog.json`; do not duplicate it in template prose.
-- Release state lives in `package.json`, npm, git tags, and GitHub; document commands in `README.md`, not `CLAUDE.md`.
-- Long-running agent work records resumable status in `Harness/tasks/<task-id>/PLAN.md#Heartbeat`.
-
-## 4. Core Components
-
-### 4.1 CLI Entry
-
-- **Location**: `bin/create-harness-vibe-coding.js`, `src/index.js`
-- **Responsibility**: Parse flags, handle interactive/non-interactive modes, print plans/results, and call the generator.
-- **Does NOT handle**: Template walking, conflict classification, or file writing internals.
-
-### 4.2 Prompt Layer
-
-- **Location**: `src/prompts.js`
-- **Responsibility**: Ask basic interactive npx questions: project name and target directory.
-- **Does NOT handle**: Agent-link install intake. That matrix is read by coding agents from `README.md` and `Harness/SETUP.md`.
-
-### 4.3 Generator Core
-
-- **Location**: `src/generator.js`
+# Harness Architecture - create-harness-vibe-coding
+
+> **Responsibility**: Define the repository structure and scaffold generation boundaries.
+> **Does NOT cover**: Generated target-project business architecture.
+
+---
+
+## 1. Layering Rules
+
+```text
+bin/
+  CLI executable shim. Calls src/index.js.
+
+src/
+  CLI orchestration and scaffold generation logic.
+  May read templates/ and write the chosen target directory.
+
+templates/
+  Source of generated scaffold assets.
+  Must stay declarative: markdown, skill files, agent files, scripts, and optional workflow docs.
+
+Harness/ and .claude/
+  Dogfood runtime for this repository's own agent work.
+  Must not be treated as package source unless intentionally copied into templates/.
+
+tests/
+  Node test suite for CLI behavior, generator behavior, package contents, and generated harness validation.
+```
+
+Hard constraints:
+
+- `templates/common/**` and `templates/optional/**` are the source of generated output.
+- Root `Harness/**` is this repository's operating harness; changing it does not change generated projects.
+- Generated output paths are normalized by `harnessDest()` in `src/generator.js`.
+- Existing-project safety is owned by conflict planning in `src/generator.js`, not by template prose alone.
+- Package publication is constrained by `package.json#files`; root dogfood files are not package contents.
+
+## 2. Interface Decoupling
+
+Use interfaces and module boundaries to protect real seams in the generator, not to decorate straightforward code.
+
+- `src/index.js` owns CLI/user interaction; `src/generator.js` owns planning and file writes.
+- Template files are declarative inputs; source code should not depend on root dogfood `Harness/**`.
+- Optional catalog structure is the extension contract for presets and optional skills.
+- Avoid speculative abstraction: do not add plugin systems, generic runners, extra config layers, or service containers until a real second use or testability boundary exists.
+- When a boundary is real, express it with a small data contract and test it through generated output behavior.
+
+## 3. State Design
+
+State in this repo should be explicit, serializable, and owned by one layer.
+
+- Generator plan state is computed in memory and returned as `plan`/`summary`; file writes consume that plan instead of re-deciding conflicts.
+- Filesystem state is authoritative only through existence/type checks and write results.
+- Optional selection state comes from CLI flags plus `templates/optional/catalog.json`; do not duplicate it in template prose.
+- Release state lives in `package.json`, npm, git tags, and GitHub; document commands in `README.md`, not `CLAUDE.md`.
+- Long-running agent work records resumable status in `Harness/tasks/<task-id>/PLAN.md#Heartbeat`.
+
+## 4. Core Components
+
+### 4.1 CLI Entry
+
+- **Location**: `bin/create-harness-vibe-coding.js`, `src/index.js`
+- **Responsibility**: Parse flags, handle interactive/non-interactive modes, print plans/results, and call the generator.
+- **Does NOT handle**: Template walking, conflict classification, or file writing internals.
+
+### 4.2 Prompt Layer
+
+- **Location**: `src/prompts.js`
+- **Responsibility**: Ask basic interactive npx questions: project name and target directory.
+- **Does NOT handle**: Agent-link install intake. That matrix is read by coding agents from `README.md` and `Harness/SETUP.md`.
+
+### 4.3 Generator Core
+
+- **Location**: `src/generator.js`
 - **Responsibility**: Resolve optional selections, keep Harness-owned template paths under `Harness/**`, detect conflicts, render templates, register optional workflows, and write files.
-- **Critical functions**:
+- **Critical functions**:
   - `harnessDest()` keeps root entry files at root and Harness-owned files under generated root `Harness/*`.
-  - `createPlan()` and `addFileActions()` classify directories and file actions before writes.
-  - `registerOptionalContent()` updates generated router/memory docs when optional workflows are selected.
-
-### 4.4 Template Assets
-
-- **Location**: `templates/common/**`, `templates/optional/**`
-- **Responsibility**: Define generated `CLAUDE.md`, `AGENTS.md`, `README.md`, `Harness/**`, `.claude/**`, optional skills, and optional workflows.
-- **Does NOT handle**: Existing-project decisions. Templates state contracts; generator and agents apply them safely.
-
-### 4.5 Validator
-
-- **Source template**: `templates/common/scripts/validate-harness.mjs`
-- **Generated location**: `Harness/scripts/validate-harness.mjs`
-- **Responsibility**: Validate required scaffold files, skill/agent registrations, router invariants, optional workflow registrations, and strict project-fact placeholders.
-
-### 4.6 Dogfood Runtime
-
-- **Location**: root `Harness/**`, `.claude/**`, `CLAUDE.md`, `AGENTS.md`, `MEMORY.md`
-- **Responsibility**: Govern future AI-agent work in this repository.
-- **Does NOT handle**: Changing package output unless edits are made to `templates/**` or source code.
-
-## 5. Data Flow
-
-```text
-CLI args / prompts
--> src/index.js parse and display
--> src/generator.js resolve optional catalog
--> walk templates/common and selected templates/optional
--> harnessDest maps source paths to generated destinations
--> createPlan/addFileActions classify create/skip/backup/overwrite/conflict
--> renderTemplate substitutes projectName
--> registerOptionalContent updates generated Harness router/memory
--> write files or return dry-run/json plan
--> tests and generated validator verify behavior
-```
-
-## 6. Architectural Constraints
-
-- Do not add generated-output behavior by editing only root `Harness/`; edit `templates/common/**` or `templates/optional/**`.
-- Do not add user-facing CLI behavior without tests in `tests/cli-smoke.test.js` or `tests/generator.test.js`.
-- Do not add required generated files without updating `templates/common/scripts/validate-harness.mjs` and relevant tests.
-- Do not write Harness docs into generated `docs/`; `Harness/` is the generated root for harness-owned docs.
-- Do not make root `CLAUDE.md` a dumping ground for build commands, architecture, or release process.
-
-## 7. Known Follow-Up Risks
-
-- Interactive confirmation currently happens before full conflict-plan display in interactive mode.
-- Some README tests assert exact prose and can be made more structural.
-- `subagent-orchestrator` routing priority should continue to be tightened in templates.
+  - `createPlan()` and `addFileActions()` classify directories and file actions before writes.
+  - `registerOptionalContent()` updates generated router/memory docs when optional workflows are selected.
+
+### 4.4 Template Assets
+
+- **Location**: `templates/common/**`, `templates/optional/**`
+- **Responsibility**: Define generated `CLAUDE.md`, `AGENTS.md`, `README.md`, `Harness/**`, `.claude/**`, optional skills, and optional workflows.
+- **Does NOT handle**: Existing-project decisions. Templates state contracts; generator and agents apply them safely.
+
+### 4.5 Validator
+
+- **Source template**: `templates/common/scripts/validate-harness.mjs`
+- **Generated location**: `Harness/scripts/validate-harness.mjs`
+- **Responsibility**: Validate required scaffold files, skill/agent registrations, router invariants, optional workflow registrations, and strict project-fact placeholders.
+
+### 4.6 Dogfood Runtime
+
+- **Location**: root `Harness/**`, `.claude/**`, `CLAUDE.md`, `AGENTS.md`, `MEMORY.md`
+- **Responsibility**: Govern future AI-agent work in this repository.
+- **Does NOT handle**: Changing package output unless edits are made to `templates/**` or source code.
+
+## 5. Data Flow
+
+```text
+CLI args / prompts
+-> src/index.js parse and display
+-> src/generator.js resolve optional catalog
+-> walk templates/common and selected templates/optional
+-> harnessDest maps source paths to generated destinations
+-> createPlan/addFileActions classify create/skip/backup/overwrite/conflict
+-> renderTemplate substitutes projectName
+-> registerOptionalContent updates generated Harness router/memory
+-> write files or return dry-run/json plan
+-> tests and generated validator verify behavior
+```
+
+## 6. Architectural Constraints
+
+- Do not add generated-output behavior by editing only root `Harness/`; edit `templates/common/**` or `templates/optional/**`.
+- Do not add user-facing CLI behavior without tests in `tests/cli-smoke.test.js` or `tests/generator.test.js`.
+- Do not add required generated files without updating `templates/common/scripts/validate-harness.mjs` and relevant tests.
+- Do not write Harness docs into generated `docs/`; `Harness/` is the generated root for harness-owned docs.
+- Do not make root `CLAUDE.md` a dumping ground for build commands, architecture, or release process.
+
+## 7. Known Follow-Up Risks
+
+- Interactive confirmation currently happens before full conflict-plan display in interactive mode.
+- Some README tests assert exact prose and can be made more structural.
+- `subagent-orchestrator` routing priority should continue to be tightened in templates.