create-harness-vibe-coding 0.6.0 → 0.6.2

package/README.md

@@ -26,7 +26,7 @@ Follow the README at https://github.com/zingspark/create-harness-vibe-coding to
 
 That's it. Two paths into the harness — you type `npx`, or your agent reads the sentence.
 
-[README-CN.md](README-CN.md) (中文)
+Chinese README: [README-CN.md](README-CN.md)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {

package/src/generator.js

@@ -2,7 +2,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
 const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates', 'common');
 const OPTIONAL_DIR = path.resolve(__dirname, '..', 'templates', 'optional');
 const OPTIONAL_CATALOG = path.join(OPTIONAL_DIR, 'catalog.json');
@@ -327,7 +329,11 @@ export function generate({
 
   // Resolve targetDir relative to cwd
   const resolvedDir = path.resolve(process.cwd(), targetDir);
-  const vars = { projectName };
+  const vars = {
+    projectName,
+    generatorVersion: pkg.version,
+    generatedTimestamp: new Date().toISOString(),
+  };
 
   const optional = resolveOptionalSelection({ withOptions, withoutOptions, preset });
   const fileSpecs = [

package/templates/common/.claude/agents/context-master.md

@@ -1,7 +1,7 @@
 ---
 name: context-master
 description: Use when context exceeds ~85% of the window, or during WF closeout to extract durable knowledge before compression. Read-only analysis except for writing compression suggestions to PROGRESS.md#Heartbeat.
-tools: Read, Grep, Glob
+tools: Read, Grep, Glob, Write
 model: haiku
 skills: harness-context
 ---

package/templates/common/.claude/commands/{review.md → wf-review.md}

@@ -17,9 +17,10 @@ Cross-model peer review. Invokes the OTHER agent CLI to review changes from a fr
 
 ## CLI Detection
 
-- If `codex` is available: use `codex exec` for code review
-- If only `claude` is available: use `claude -p` for code review
-- Try `codex exec` first, fall back to `claude -p`
+- Check `which codex && echo CODEX || echo NO_CODEX` to detect Codex
+- Check `which claude && echo CLAUDE || echo NO_CLAUDE` to detect Claude
+- Use the OTHER CLI — the one NOT running this session. Never self-review.
+- If only one CLI is available: warn the user, suggest installing the other CLI. Do NOT proceed with self-review.
 
 ## Flow
 

package/templates/common/.claude/settings.json

@@ -18,6 +18,7 @@
       "WebSearch"
     ],
     "deny": [
+      "EnterPlanMode",
       "Bash(rm -rf *)",
       "Bash(sudo *)",
       "Bash(curl *)",

package/templates/common/.claude/skills/wf-review/SKILL.md

@@ -14,19 +14,20 @@ Cross-model peer review via the OTHER agent CLI. Fresh eyes on your changes.
 
 ## How It Works
 
-1. **Detect runtime**: Check `which codex` and `which claude`
+1. **Detect available CLIs**: Check `which codex` and `which claude`. Use the OTHER CLI — never the one running this session.
 2. **Prepare context**: Gather diff (`git diff`), relevant architecture docs, the specific question
 3. **Invoke the OTHER CLI** — the one we're NOT currently running under
 4. **Read and synthesize**: Present the raw output, then add analysis
 
 ## CLI Commands
 
-| Current Runtime | Review Command |
+| Runtime | Review Command |
 |---|---|
-| Claude Code | `git diff \| codex exec "review prompt"` |
-| Claude Code (commit) | `codex exec "review this commit: $(git log -1 --format=%B)"` |
-| Codex | `git diff \| claude -p "review prompt"` |
-| Either | fallback: try the other CLI, warn if neither available |
+| Claude → Codex | `git diff \| codex exec "..."` (include full diff, not just commit message) |
+| Codex → Claude | `git diff \| claude -p "..."` |
+| Either (fallback) | warn user, suggest installing the other CLI. Do NOT proceed with same-model review. |
+
+**Anti-self-review rule**: Detect which runtime we're in, then use the OTHER one. Never invoke the same CLI that's running the session.
 
 ## Context to Include
 

package/templates/common/CLAUDE.md

@@ -73,3 +73,4 @@ Root entry for Claude Code. Keep this file short.
 
 - Never call `EnterPlanMode` — delegate planning to `planner` subagents (see `Harness/WF.md`).
 - Never write code directly in `/wf` or `/wf-max` mode — delegate all implementation to subagents (see `Harness/WF-MAX.md`).
+- **Enforcement**: `.claude/settings.json` hooks prevent `EnterPlanMode` calls. Settings include `allowTools: ["!EnterPlanMode"]` for the main session.

package/templates/common/docs/README.md

@@ -103,7 +103,7 @@ Routing priority: if a request explicitly says `/wf <task>`, `/wf-max [task]`, `
 ```text
 Harness/README.md                  router only
 Harness/MEMORY.md                  resource index
-Harness/PLAN.md                    active project plan
+Harness/PLAN.md                    project-level plan (redirects to tasks/<id>/PLAN.md)
 Harness/SETUP.md                   install/bootstrap contract
 Harness/PROGRESS.md                global task index and cross-task decisions
 Harness/tasks/<id>/PROGRESS.md     per-task progress, phase, heartbeat
@@ -115,7 +115,7 @@ Harness/WF-MAX.md                  max-parallelism workflow with wave dispatch
 .claude/skills/wf-review/SKILL.md  cross-model peer review skill
 .claude/commands/wf-max.md         /wf-max slash command bridge
 .claude/commands/learn.md          /wf-learn slash command bridge
-.claude/commands/review.md         /wf-review slash command bridge
+.claude/commands/wf-review.md      /wf-review slash command bridge
 Harness/lifecycle.md               0-1 product flow
 Harness/subagents.md               controller-led subagent orchestration
 Harness/context-loading.md         dynamic loading and subagent packs

package/templates/common/docs/harness/WF-MAX.md

@@ -22,7 +22,7 @@ CEO(1) ──┬── Manager₁(span) ──┬── Worker₁..ₙ
 ```
 
 - CEO: intent, scope, integration, final verification. Direct reports 3-5 Managers. **CEO never writes code directly** — dispatch Workers for all file changes. CEO only synthesizes results and decides next waves.
-- Manager: domain partition → parallel dispatch → synthesize → report. Serial across domains; parallel within domain.
+- Manager: domain partition → parallel dispatch → synthesize → report. Serial across domains; parallel within domain. **Manager agents must be defined by the project** (not shipped by the harness) — create them under `.claude/agents/` with the `Agent` tool enabled for nested spawning.
 - Worker: single file per write Worker (implementer, one file_claim). Single dimension/topic per read Worker (reviewer, researcher). File claims must be file-level disjoint. Topic-level splitting within a single file is only allowed for read-only Workers.
 - depth ≥3: Manager spawns Sub-Manager (span ≤7) instead of Worker. Recursive until leaf condition met.
 

package/templates/common/docs/harness/architecture.md

@@ -1,114 +1,126 @@
-# Harness Architecture — {{projectName}}
+# Harness Architecture - create-harness-vibe-coding
 
-> **Responsibility**: Defines the system layering structure, component overview, and key design decisions.
-> **Does NOT cover**: Code details (AI can read code), API documentation (placed in docstrings).
->
-> Philosophical sources: arc42 Chapter 5 (Building Block View) + C4 Model Level 3 (Component) + matklad's lightweight ARCHITECTURE.md.
+> **Responsibility**: Define the repository structure and scaffold generation boundaries.
+> **Does NOT cover**: Generated target-project business architecture.
 
 ---
 
 ## 1. Layering Rules
 
-<!-- This is the hardest constraint in the entire architecture. Each layer's "allowed dependencies" must be explicit. -->
+```text
+bin/
+  CLI executable shim. Calls src/index.js.
 
-```
-┌──────────────────────────┐
-│     interfaces/          │  ← User entry (CLI / API / UI)
-│     May depend on: harness│
-├──────────────────────────┤
-│     harness/             │  ← Generic runtime shell: orchestration,
-│     May depend on:        │     security, auditing, scheduling
-│       application         │     Contains no business rules
-├──────────────────────────┤
-│     application/         │  ← Business use-case orchestration
-│     May depend on: domain │
-├──────────────────────────┤
-│     domain/              │  ← Pure business objects + port protocols
-│     Only depends on:      │     Depends on no external implementations
-│       standard library    │
-├──────────────────────────┤
-│     infrastructure/      │  ← Adapter implementations (data sources,
-│     Implements domain     │     external services)
-│       ports               │
-└──────────────────────────┘
+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**:
-- domain must never import infrastructure/ or interfaces/
-- application only depends on domain
-- harness coordinates workflows but contains no domain business rules
-- All cross-layer communication goes through port protocols defined in domain
+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 or ports to protect real boundaries, not to create abstraction for its own sake.
-
-- Define a port when code crosses a layer, process, network, storage, SDK, browser, or permission boundary.
-- Keep domain and application logic independent from infrastructure adapters.
-- Pass data through explicit contracts instead of reaching into another feature's internals.
-- Prefer direct calls inside the same cohesive module when there is only one caller, one implementation, and no boundary to protect.
-- Avoid speculative abstraction: do not add factories, plugin systems, service locators, generic repositories, or config layers until the feature has a concrete second use or a real testability/replacement need.
+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 must have one owner, legal transitions, and observable recovery behavior.
+State in this repo should be explicit, serializable, and owned by one layer.
 
-- Identify durable state, runtime cache, derived UI state, external system state, and audit/event history separately.
-- Name the owner of each state slice; do not let UI, application services, and infrastructure all mutate the same state directly.
-- Model long-running workflows with explicit states, guards, and failure transitions in `Harness/state-machines.md`.
-- Store resumable progress and recovery decisions in `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` or project-owned durable storage, not only in chat.
-- Keep state minimal: derive values when cheap, persist only what must survive reload, retry, or handoff.
+- 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. Harness Core Components
+### 4.1 CLI Entry
 
-### 4.1 Runner / Loop
+- **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.
 
-- **Responsibility**: Drives a task from input to completion: loading context, calling application use-cases, handling stop conditions.
-- **Design Decision**:
-  - Runner only orchestrates, does not interpret domain meaning — Rationale: keeps harness reusable across different business domains
-  - Stop conditions are explicitly modeled — Rationale: prevents agent loops from running indefinitely or silently half-completing
-- **Does NOT handle**: Business rules, domain object creation details, external service implementations
+### 4.2 Prompt Layer
 
-### 4.2 Permission Policy
+- **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`.
 
-- **Responsibility**: Decides whether a given tool, file, network, or external action is allowed to execute.
-- **Design Decision**:
-  - High-risk actions are denied by default, allow rules are explicitly declared — Rationale: the platform must first guarantee security boundaries
-- **Does NOT handle**: Judging whether a business action is correct
+### 4.3 Generator Core
 
-### 4.3 Event Bus / Audit Trail
+- **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.
 
-- **Responsibility**: Records task lifecycle, tool invocations, failures, human approvals, and final results.
-- **Design Decision**:
-  - Events are append-only, audit records cannot be overwritten in place — Rationale: facilitates replay, debugging, and post-mortem analysis
-- **Does NOT handle**: Saving final data on behalf of business systems
+### 4.4 Template Assets
 
-### 4.4 State / Checkpoint Store
+- **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.
 
-- **Responsibility**: Saves recoverable state, context summaries, task progress, and interrupt points.
-- **Design Decision**:
-  - State format must be serializable — Rationale: enables replay, resume, testing, and migration
-- **Does NOT handle**: Long-term business database modeling
+### 4.5 Validator
 
-### 4.5 Tool Registry
+- **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.
 
-- **Responsibility**: Registers callable tools along with their input/output contracts, permission labels, and error semantics.
-- **Design Decision**:
-  - Tool contracts explicitly specify input, output, errors, and side effects — Rationale: reduces the probability of agent tool misuse
-- **Does NOT handle**: Internal business implementation of tools
+### 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.
 
-## 5. Architectural Constraints (Non-Negotiable)
+## 7. Known Follow-Up Risks
 
-- `domain/` only defines business models, business invariants, and port protocols; does not import `harness/`, `infrastructure/`, or `interfaces/`.
-- `harness/` may orchestrate workflows, security gates, auditing, and stop conditions, but must not determine business meaning.
-- All cross-layer external capabilities are expressed through `domain` ports; adapter implementations live in `infrastructure/`.
-- Rejections and failures must be testable or documented with manual verification steps in the feature doc.
-- Audit events are append-only, never overwritten in place.
+- Interactive confirmation currently happens before full conflict-plan display in interactive mode.
+- Some README tests assert exact prose and can be made more structural.
+- `wf-mode` and `subagent-orchestrator` routing priority should continue to be tightened in templates.

package/templates/common/docs/research/README.md

@@ -6,7 +6,7 @@ Purpose: guide agent research. Record conclusions in [research-results.md](resea
 
 Use this before PRD, stack choice, external API use, public dependency choice, pricing/legal/security assumptions, or any fact likely to change.
 
-Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/tasks/<task-id>/PROGRESS.md`.
+Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/tasks/<task-id>/PLAN.md`.
 
 ## Research Agent
 
@@ -104,7 +104,7 @@ Use these patterns when turning research into PRD or feature docs:
 
 ## Write Target
 
-- Research process, queries, and limitations: this file or `Harness/tasks/<task-id>/PROGRESS.md`.
+- Research process, queries, and limitations: this file or `Harness/tasks/<task-id>/PLAN.md`.
 - Final research decisions: [research-results.md](research-results.md).
 - Product scope: [PRD.md](PRD.md).
 - Architecture consequences: `Harness/architecture.md` and `Harness/domain/ports.md`.