create-harness-vibe-coding 0.7.2 → 0.8.0

package/templates/common/Harness/WF.md

@@ -0,0 +1,217 @@
+# WF Mode - Long Task Workflow
+
+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`.
+
+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.
+
+## 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 uses at least three role passes before the second plan.
+- 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.
+
+## Multi-Subagent Requirement
+
+WF mode requires multi-subagent orchestration by default.
+
+Normative rule: Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use at least 3 distinct role passes before second planning.
+
+- Explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use at
+  least 3 distinct role passes before second planning. Use real subagents when
+  the runtime supports them; otherwise emulate those roles as bounded passes and
+  record the fallback.
+- 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 -> always multi-role, no exceptions.
+  - 3+ files changed -> multi-role at minimum: planner, implementer, reviewer.
+  - Cross-layer change -> architect plus implementers plus reviewer.
+  - Uncertain scope or approach -> planner plus researcher plus architect.
+  - 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 initial fan-out: `planner`, `researcher` or `docs-researcher`, and
+  `architect`. Add `test-writer`, `reviewer`, `debugger`, or `verifier` when
+  the phase needs them.
+
+## Exploration Gate
+
+- [ ] Controller has not read source files directly; only Harness docs, root
+  agent entries, and subagent or bounded-pass returns.
+- [ ] At least 3 distinct role types, each with one specific question.
+- [ ] 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
+
+```text
+Intake
+-> confidence gate
+-> parallel planner / researcher / docs-researcher / architect roles
+-> synthesis
+-> second plan
+-> test-writer
+-> implementer
+-> reviewers
+-> verifier
+-> if failed: debugger -> review -> e2e/API verification -> loop
+-> close with evidence
+```
+
+## Intake
+
+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, 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.
+
+## 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, 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`.
+
+## Build And Review
+
+1. `test-writer` defines a failing test or written manual check first.
+2. `implementer` changes only the declared write set.
+3. At least one `reviewer` checks diff, architecture, risks, and missing tests.
+4. For cross-layer or risky work, run separate reviewers for architecture and
+   test adequacy.
+5. `verifier` runs the declared checks and records exact evidence.
+
+## 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
+
+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 failing command, error output, and smallest
+   relevant files.
+3. Fix the smallest reproduced failure.
+4. Run reviewer again.
+5. Run verifier again.
+6. 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.
+
+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.
+
+## Closeout
+
+Close only when:
+
+- acceptance criteria are satisfied
+- reviewer has no unresolved critical/high findings
+- 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

package/templates/common/{docs/harness → 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`
-- **Responsibility**: Resolve optional selections, map template paths to destination paths, detect conflicts, render templates, register optional workflows, and write files.
-- **Critical functions**:
-  - `harnessDest()` maps legacy template source paths such as `docs/harness/*` into 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.
+# 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**:
+  - `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.