create-harness-vibe-coding 0.2.0 → 0.2.1

package/README-CN.md

@@ -0,0 +1,94 @@
+# create-harness-vibe-coding 中文说明
+
+0-1 产品 Harness 脚手架，用于 AI 辅助工程：从想法、调研、PRD、架构、计划，到实现、验证和反馈闭环。
+
+English README: [README.md](README.md)
+
+## 一句话交给 Agent
+
+```text
+请按照 https://github.com/zingspark/create-harness-vibe-coding 的 README 为当前项目配置 create-harness-vibe-coding；编辑前先询问 Agent-link 安装前置问题；新项目走 0-1 bootstrap，老项目或老架构升级先 dry-run，保留现有文件，只合并缺失的 Harness 规范，然后遵循 Harness/SETUP.md。
+```
+
+## 两种安装方式
+
+### 1. npx 安装
+
+适合需要确定性写入、明确冲突策略、可重复 dry-run 的场景。
+
+### 2. 直接把链接丢给 agent
+
+适合老项目、老架构升级、已有复杂 `CLAUDE.md` / `AGENTS.md` / `.claude/` 的场景。agent 应该读取这个仓库 README，理解当前项目结构，执行或模拟 dry-run，然后给出最小迁移方案。
+
+如果项目里已经有 `CLAUDE.md`，agent 必须先告诉用户：`CLAUDE.md` 是根 agent 入口合同，不能静默覆盖或乱合并。正确流程是先请求用户确认是否重构/合并 `CLAUDE.md`，再在保留原项目规则的基础上补入 Harness 的 startup、memory、router、workflow、subagents 编排约束。
+
+Agent-link 安装前置问题，编辑前先问：
+
+只询问会影响写入、架构、安全或工作流的选择。开始时最多问 3 个 blocking 问题，其余采用安全默认值并记录到计划里，等真正触发时再继续追问。
+
+| 主题 | 什么时候问 | 没回答时的默认值 |
+| --- | --- | --- |
+| 根 agent 入口 | 已存在 `CLAUDE.md`、`AGENTS.md`、`.claude/` 或其他 agent 入口文件 | 保留现有文件；合并 Harness 入口合同前必须询问用户 |
+| Harness 存放位置 | `docs/` 已经用于 GitHub Pages、产品文档或生成文档 | 默认使用根目录 `Harness/`；不要把 Harness 文档写进 `docs/` |
+| README 归属 | 根 `README.md` 是公开产品页、包文档或已有大量自定义内容 | 保留现有 README，只提议追加最小 Development section |
+| README 优化 | 已有 README 过时、太单薄、缺少命令表格，或用户想要架构图/更生动的文档 | 可推荐 `readme-optimizer`；默认只追加 Development notes，结构化优化或重写必须先得到用户确认 |
+| 扩展能力 | ECC、Superpowers、自定义 rules 或栈相关 skills 可能有用 | 先推荐；只有用户同意后才安装 |
+| Skills | 技术栈已明确，测试、前端、后端、review、浏览器证据可用 optional skills 增强 | 用户同意后只安装 1-2 个最相关 skills |
+| CI/CD | 已有 CI 配置，或项目缺少测试/构建 gate | 先记录现有命令；只有用户同意后才新增或规范 CI/CD |
+| 验证深度 | 涉及浏览器可见行为、API、数据库、鉴权、支付或部署 | 必须有真实命令证据；相关场景必须有浏览器/API 证据 |
+| Memory/隐私 | 仓库包含敏感领域数据、客户数据、密钥或私有流程 | 只启用 memory index；禁止记录 secrets 或私有数据 |
+| Branch/worktree | 存在未提交改动、风险迁移或并行实现 lane | 保护当前工作区；大改前先提议 branch/worktree |
+| 包管理器/技术栈 | 存在多个包管理器、monorepo apps 或技术栈边界不清 | 写文件前先确认当前 workspace/app 范围 |
+
+## 一条命令
+
+```bash
+npx create-harness-vibe-coding@latest my-project
+```
+
+## 现有项目渐进安装
+
+先预览，不写文件：
+
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --dry-run
+```
+
+再保留现有文件，只补缺失的 Harness 文件：
+
+```bash
+npx create-harness-vibe-coding@latest my-app . -y --on-conflict skip
+```
+
+安装后让 agent 先读 `Harness/SETUP.md`，再开始正常工作。
+
+## 核心约束
+
+- `CLAUDE.md` 只做薄入口和路由，不放项目架构、构建脚本、git 规范。
+- 项目开发命令、构建、测试、git、发布流程放根目录 `README.md`。
+- 架构说明放 `Harness/architecture.md` 或当前 feature 文档。
+- Harness 文档、状态、记忆、工作流默认放根目录 `Harness/`。
+- 如果已有 `AGENTS.md`，agent 必须先询问用户是否同意修改。
+- 长任务、多文件、多 subagents、低置信度或重复失败时使用 `/wf`、`wf-mode` 和 `Harness/WF.md`。
+
+## 常用生成物
+
+| 文件 | 用途 |
+| --- | --- |
+| `CLAUDE.md` | Claude Code 根入口，保持短小 |
+| `Harness/README.md` | Harness 路由器 |
+| `Harness/SETUP.md` | 初次安装和 bootstrap 指南 |
+| `Harness/MEMORY.md` | agents、skills、记忆文件索引 |
+| `Harness/PLAN.md` | 当前计划、heartbeat、handoff、验证证据 |
+| `Harness/WF.md` | 长链路 workflow 和恢复循环 |
+| `Harness/subagents.md` | 多 subagents 编排方法论 |
+| `.claude/skills/*` | Claude Code 可加载的 Harness skills |
+
+## 验证
+
+```bash
+npm test
+node Harness/scripts/validate-harness.mjs
+```
+
+生成项目后，`Harness/scripts/validate-harness.mjs` 用于检查 Harness 结构、注册关系和必要规范是否完整。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin/",
     "src/",
-    "templates/"
+    "templates/",
+    "README-CN.md"
   ],
   "scripts": {
     "start": "node src/index.js",

package/templates/common/.claude/skills/harness-router/SKILL.md

@@ -8,7 +8,7 @@ description: Use at the start of any task, or when unsure which harness document
 1. Read `Harness/README.md`.
 2. Identify the current situation from "Load By Task".
 3. Apply routing priority before loading extra files:
-   - `/wf`, long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work routes to `wf-mode` first.
+   - `/wf`, `wf mode`, `workflow mode`, `wk mode`, long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work routes to `wf-mode` first.
    - Bounded subagent-only coordination routes to `subagent-orchestrator`.
 4. Load only the listed primary doc(s). Let `wf-mode` decide when to load subagent docs.
 5. If the task grows, update `Harness/PLAN.md` and use `harness-context`.

package/templates/common/.claude/skills/subagent-orchestrator/SKILL.md

@@ -12,12 +12,15 @@ Load:
 - `Harness/context-loading.md`
 - `Harness/PLAN.md`
 - `Harness/agent-workflow.md`
-- `Harness/WF.md` when in `/wf`, wf mode, or recovery loop
+- `Harness/WF.md` when in `/wf`, `wf mode`, `workflow mode`, `wk mode`, or recovery loop
+- `.claude/agents/` roster names before choosing roles
 
 Follow:
 
 - The main agent is the controller. It decomposes work, writes `Harness/PLAN.md`, integrates returns, and owns final verification.
 - Use the efficiency ladder in `Harness/subagents.md`: solo pass -> single reviewer -> parallel read-only -> serial build lane -> isolated lanes.
+- Explicit WF/WK mode requires at least 3 distinct agents from `.claude/agents/` before second planning.
+- Prefer the built-in roles `planner`, `researcher`, `docs-researcher`, `architect`, `test-writer`, `implementer`, `reviewer`, `debugger`, and `verifier` before inventing custom roles.
 - Every subagent dispatch needs a complete dispatch pack: role, goal, mode, read set, write set, forbidden scope, injected docs, dependencies, expected evidence, stop condition, and return format.
 - Prefer parallel read-only exploration first. Run writing agents serially unless write sets are disjoint and isolated.
 - Use two review gates after implementation: spec review first, then code-quality or architecture review.

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

@@ -1,6 +1,6 @@
 ---
 name: wf-mode
-description: Use for /wf, wf mode, workflow mode, long difficult tasks, multi-file or multi-agent work, low-confidence decisions, repeated failures, migrations, architecture-heavy changes, browser-visible work, or any task that needs exploration -> second plan -> implementation -> review -> verification -> recovery.
+description: Use for /wf, wf mode, workflow mode, wk mode, long difficult tasks, multi-file or multi-agent work, low-confidence decisions, repeated failures, migrations, architecture-heavy changes, browser-visible work, or any task that needs exploration -> second plan -> implementation -> review -> verification -> recovery.
 ---
 
 # WF Mode
@@ -10,7 +10,7 @@ Load:
 - `Harness/WF.md`
 - `Harness/PLAN.md`
 - `Harness/agent-workflow.md` when implementation, review, or verification starts
-- `Harness/subagents.md`, `Harness/dispatch.md`, and `Harness/context-loading.md` only when coordinating subagents or bounded role passes
+- `Harness/subagents.md`, `Harness/dispatch.md`, and `Harness/context-loading.md` immediately for explicit WF/WK mode; otherwise only when coordinating subagents or bounded role passes
 - current feature doc when one exists
 - `Harness/workflows/browser-e2e.md` when browser-visible behavior is affected and the workflow is installed
 
@@ -31,6 +31,8 @@ intake + 95% confidence gate
 Rules:
 
 - Update `Harness/PLAN.md#Heartbeat` before long commands, after failures, before handoff, and at closeout.
+- Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST use `subagent-orchestrator` and spawn at least 3 distinct subagents from `.claude/agents/` before second planning.
+- Use the 7:3 collaboration bias from `Harness/WF.md`: default to multi-agent collaboration for substantial work; use solo mode only for clearly small/local tasks outside explicit WF/WK mode.
 - Use `subagent-orchestrator` and `Harness/subagents.md` when the task has broad reading, cross-layer impact, independent review needs, or repeated failures.
 - If subagents are unavailable, emulate the same roles as separate bounded passes.
 - Do not claim browser/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.

package/templates/common/CLAUDE.md

@@ -10,7 +10,7 @@ Root entry for Claude Code. Keep this file short.
 - `Harness/MEMORY.md` is the memory/resource router: agents, skills, durable memories, and cross-session lessons. Follow its registrations when selecting agents/skills or recording memory.
 - `Harness/README.md` is the task router. For every request, check `Harness/README.md#Load By Task`; if a row matches, read and follow those docs before acting.
 - If work spans more than one step, update `Harness/PLAN.md`.
-- Use `/wf`, `wf-mode`, or `Harness/WF.md` for long, difficult, uncertain, multi-file, or repeated-failure work.
+- Use `/wf`, `wf-mode`, `wf mode`, `workflow mode`, `wk mode`, or `Harness/WF.md` for long, difficult, uncertain, multi-file, or repeated-failure work.
 - Use `subagent-orchestrator` and `Harness/subagents.md` when coordinating multiple subagents.
 - Universal rules live in `.claude/rules/ecc/common.md`.
 - Never bulk-read `Harness/`; route through `Harness/README.md` and `Harness/MEMORY.md`.
@@ -28,6 +28,7 @@ Root entry for Claude Code. Keep this file short.
 - No features beyond what was asked.
 - No abstractions for single-use code.
 - No unrequested flexibility, configurability, or speculative error handling.
+- Use explicit interfaces or state models only when they protect a real boundary, clarify ownership, or make verification/recovery simpler.
 - If a simpler approach exists, say so and prefer the smallest change that satisfies the request.
 - If the solution is growing faster than the problem, reduce scope before coding more.
 

package/templates/common/SETUP.md

@@ -39,7 +39,7 @@ Claude must follow this order:
 4. Read `Harness/research/README.md`, then fill `Harness/research/research-results.md` with adopted/rejected research choices.
 5. Fill minimum architecture: `Harness/architecture.md` and one port in `Harness/domain/ports.md`.
 6. Create the first vertical-slice plan in `Harness/PLAN.md`.
-7. Use `Harness/subagents.md`, `Harness/context-loading.md`, and `Harness/dispatch.md` when spawning subagents.
+7. Use `Harness/subagents.md`, `Harness/context-loading.md`, and `Harness/dispatch.md` when explicit WF/WK mode or any spawned subagents are involved.
 8. Fill `Harness/data-flow.md` or `Harness/state-machines.md` only when the slice changes runtime flow, failure behavior, or state.
 9. Implement only after a failing test or manual verification step is defined.
 10. Run `node Harness/scripts/validate-harness.mjs --strict`.
@@ -116,11 +116,13 @@ The harness validator checks for specific structural invariants. When comparing
 | `README.md` | Existing README is project-owned. Preserve by default; ask whether to append only Development notes or run `readme-optimizer` for a structure pass with tables/diagrams before broad edits |
 | `Harness/MEMORY.md` | All 9 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: "Adding harness to existing project", "Need implementation plan", "Need parallel agents", "Need subagents", "Need durable memory or reflection"; `## Doc Map` with `memory/` and `subagents.md` entries; the durable communication invariant text; `Harness/README.md is the primary router` |
+| `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 mode`, `workflow mode`, or `wk mode` requires at least 3 distinct `.claude/agents/` subagents before second planning; `7:3 collaboration bias`; `Heartbeat Protocol` |
 | `Harness/extension.md` | `## Non-Invasive Extension Rules` section with the "Preserve existing" rule; `## Agent Contract` section; `## Registration` section |
 | `Harness/dispatch.md` | The durable communication invariant; common agent entries for all 9 agents; `## Handoff Format` heading |
 | `Harness/context-loading.md` | The durable communication invariant; `Harness/README.md is the primary router`; all 10 subagent context packs (Explorer Pass, Planner, Researcher, Docs Researcher, Architect, Test Writer, Implementer, Reviewer, Debugger, Verifier) |
-| `Harness/subagents.md` | `## Source Attribution`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
+| `Harness/subagents.md` | `## Source Attribution`; `## Built-in Agent Roster`; `## WF Default Fan-Out`; `Controller Role`; `Efficiency Ladder`; `Review Gates`; `7:3 collaboration bias`; source markers for `npx skills find`, `dispatching-parallel-agents`, and `subagent-driven-development` |
+| `Harness/architecture.md` | `## 2. Interface Decoupling`; `## 3. State Design`; `Avoid speculative abstraction`; layer constraints derived from actual project facts |
 | `Harness/PLAN.md` | `## Current Goal`, `## Phase`, `## Success Criteria`, `## Loaded Context`, `## 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/workflows/browser-e2e.md` (if installed as optional) | `data-testid`, `accessible labels/roles`, and `inputs, buttons, filters, rows, empty/error/loading states` requirement |
@@ -134,7 +136,7 @@ The harness validator checks for specific structural invariants. When comparing
 - `.claude/skills/harness-*/SKILL.md`, `.claude/skills/wf-mode/SKILL.md`, and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills, WF mode, and subagent orchestration
 - `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
 - `.claude/settings.json` — harness settings
-- `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md`, `Harness/data-flow.md`, `Harness/state-machines.md` — harness runtime docs
+- `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md`, `Harness/data-flow.md`, `Harness/state-machines.md` — harness runtime docs
 - `Harness/research/*.md` — research protocol and templates
 - `Harness/domain/ports.md` — port contract template
 - `AGENTS.md` — agent registry; if it already exists, ask for user consent before merging or replacing it
@@ -168,8 +170,10 @@ Each template doc contains `{{PLACEHOLDER}}` markers. Below is what every placeh
 
 **`Harness/architecture.md`** — Layer structure. Derive from research-results:
 - Fill the ASCII layer diagram with actual layer names. Do NOT add layers without a proven need.
-- `2.1–2.5`: describe each harness core component (Runner, Permission Policy, Event Bus, State Store, Tool Registry) in project-specific terms.
-- `3. Architectural Constraints`: add project-specific non-negotiables. Keep the domain/harness purity rules.
+- `Interface Decoupling`: document only real boundaries and ports. Do not add speculative factories, plugin systems, generic repositories, or config layers.
+- `State Design`: name state owners, persistence level, legal transitions, and recovery behavior for long-running workflows.
+- `Harness Core Components`: describe each core component (Runner, Permission Policy, Event Bus, State Store, Tool Registry) in project-specific terms.
+- `Architectural Constraints`: add project-specific non-negotiables. Keep the domain/harness purity rules.
 
 **`Harness/domain/ports.md`** — Cross-layer contracts. One driving port + one driven port from the first slice:
 - `{{INBOUND_PORT_1}}`: the first inbound port (e.g., "CreateOrderPort").

package/templates/common/docs/README.md

@@ -51,7 +51,7 @@ Keywords are retrieval hints, not project facts.
 
 Load the matching row only. Add adjacent docs only when the loaded doc directly names them.
 
-Routing priority: if a request is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. `wf-mode` may then delegate subagent coordination to `subagent-orchestrator`.
+Routing priority: if a request explicitly says `/wf`, `wf mode`, `workflow mode`, or `wk mode`, or is long, difficult, uncertain, repeated-failure, migration, architecture-heavy, browser-visible, or broad multi-agent implementation work, choose the WF row first. `wf-mode` may then delegate subagent coordination to `subagent-orchestrator`.
 
 | When to Read | Keywords | Load | Output |
 | --- | --- | --- | --- |
@@ -59,7 +59,7 @@ Routing priority: if a request is long, difficult, uncertain, repeated-failure,
 | Need market/tech direction | research, market, competitor, stack, library, pricing, policy | [research/README.md](research/README.md), [research/research-results.md](research/research-results.md) | research protocol, adopted/rejected choices |
 | Need MVP/spec | PRD, MVP, scope, requirement, acceptance, non-goal | [research/PRD.md](research/PRD.md) | one-page PRD with verifiable acceptance criteria |
 | Need architecture or boundaries | architecture, boundary, layer, domain, port, adapter, dependency | [architecture.md](architecture.md), [domain/ports.md](domain/ports.md) | layer map, ports, constraints |
-| Need WF mode | wf, /wf, workflow mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PLAN.md](PLAN.md) | exploration plan, second plan, heartbeat, recovery loop; load subagent docs only when needed |
+| Need WF mode | wf, /wf, wf mode, workflow mode, wk mode, long task, difficult, stuck, repeated failure | [WF.md](WF.md), [PLAN.md](PLAN.md) | exploration plan, second plan, heartbeat, recovery loop; explicit WF/WK loads subagent docs immediately |
 | Adding harness to existing project | existing project, onboarding, migrate, bootstrap, preserve, conflict | [extension.md](extension.md), [PLAN.md](PLAN.md), root `README.md` and package/CI files | discovered project facts, preserved config, manual registration plan |
 | README optimization | README, docs, quickstart, install docs, architecture diagram, command table, documentation polish | root `README.md`, `.claude/skills/readme-optimizer/SKILL.md`, [PLAN.md](PLAN.md), [architecture.md](architecture.md) as needed | approved README mode, preserved sections, proposed diff plan |
 | Need implementation plan | plan, task, write set, verify, milestone, progress | [PLAN.md](PLAN.md), [agent-workflow.md](agent-workflow.md) | tasks, write set, verification commands |
@@ -77,7 +77,7 @@ Routing priority: if a request is long, difficult, uncertain, repeated-failure,
 ## Gates
 
 - Move phases in order unless the user asks for a fast lane.
-- Use `/wf` when a task is long, difficult, uncertain, multi-file, or repeatedly failing.
+- Use `/wf`, `wf mode`, `workflow mode`, or `wk mode` when a task is long, difficult, uncertain, multi-file, or repeatedly failing.
 - Do not code before the PRD has MVP, non-goals, and acceptance criteria.
 - Do not cross a layer boundary without reading `domain/ports.md` and updating architecture or ports.
 - Before adding failure paths, read `data-flow.md`.

package/templates/common/docs/domain/ports.md

@@ -10,6 +10,8 @@
 
 ## 1. Port Classification
 
+Create a port only for a real boundary: external service, storage, SDK, process, browser/API boundary, permission boundary, or cross-layer dependency. Do not create a port only because an interface might be useful someday.
+
 ### 1.1 Driving Ports (Inbound — external calls application)
 
 | Port | Definition Location | Purpose |
@@ -67,6 +69,7 @@ Fill in each port using the format below:
 - {{INVARIANT_1}}
 - {{INVARIANT_2}}
 - New ports must be defined in `domain/ports`; adapters go in `infrastructure/`.
+- Each port needs one clear owner and at least one real caller. Avoid speculative ports without a concrete adapter or testability need.
 
 ---
 

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

@@ -1,6 +1,6 @@
 # WF Mode - Long Task Workflow
 
-Use this when work is long, difficult, uncertain, multi-file, multi-agent, or user-triggered with `/wf`, `wf mode`, or `workflow mode`.
+Use this when work is long, difficult, uncertain, multi-file, multi-agent, or user-triggered with `/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.
 
@@ -8,18 +8,28 @@ This is a Ralph-style harness loop: keep moving through evidence, bounded explor
 
 Enter WF mode when any of these are true:
 
-- The user explicitly says `/wf`, `wf mode`, or asks for the full workflow.
+- The user explicitly says `/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.
 
+## Multi-Subagent Requirement
+
+WF mode requires multi-subagent orchestration by default.
+
+- Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents from `.claude/agents/` before second planning unless the runtime cannot spawn subagents.
+- Use a 7:3 collaboration bias: prefer multi-agent collaboration for long, uncertain, cross-file, cross-layer, browser/API, migration, or repeated-failure work; reserve solo mode for clearly local, low-risk, one-file tasks outside explicit WF/WK mode.
+- Default initial fan-out: `planner`, `researcher` or `docs-researcher`, and `architect`. Add `test-writer`, `reviewer`, `debugger`, or `verifier` when the phase needs them.
+- Record every dispatch or bounded-pass fallback in `Harness/PLAN.md#Parallel Dispatch`.
+- If subagents are unavailable, emulate the same roles as separate bounded passes and record why the fallback was used.
+
 ## WF Loop
 
 ```text
 Intake
 -> confidence gate
--> parallel explorer / researcher / docs-researcher / architect passes
+-> parallel planner / researcher / docs-researcher / architect subagents
 -> synthesis
 -> second plan
 -> test-writer
@@ -36,15 +46,15 @@ Intake
 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/PLAN.md#Heartbeat` before dispatching agents or running long commands.
-5. Load `Harness/subagents.md` before coordinating multiple agents.
+5. Load `Harness/subagents.md` before coordinating multiple agents; explicit WF/WK mode always coordinates multiple roles.
 
 ## Exploration
 
-Use parallel read-only passes first. Prefer three or fewer active agents.
+Use parallel read-only subagents first. Explicit WF/WK mode starts with at least three distinct `.claude/agents/` roles before the second plan. For automatic WF triggers, default to 3-5 active agents unless the task is clearly small enough for the solo exception.
 
 | Agent | Purpose | Writes |
 | --- | --- | --- |
-| Explorer Pass | map local project facts, commands, app entry points, existing docs | none |
+| `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 |

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

@@ -41,9 +41,33 @@
 
 ---
 
-## 2. Harness Core Components
+## 2. Interface Decoupling
 
-### 2.1 Runner / Loop
+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.
+
+---
+
+## 3. State Design
+
+State must have one owner, legal transitions, and observable recovery behavior.
+
+- 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/PLAN.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.
+
+---
+
+## 4. Harness Core Components
+
+### 4.1 Runner / Loop
 
 - **Responsibility**: Drives a task from input to completion: loading context, calling application use-cases, handling stop conditions.
 - **Design Decision**:
@@ -51,28 +75,28 @@
   - 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
 
-### 2.2 Permission Policy
+### 4.2 Permission Policy
 
 - **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
 
-### 2.3 Event Bus / Audit Trail
+### 4.3 Event Bus / Audit Trail
 
 - **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
 
-### 2.4 State / Checkpoint Store
+### 4.4 State / Checkpoint Store
 
 - **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
 
-### 2.5 Tool Registry
+### 4.5 Tool Registry
 
 - **Responsibility**: Registers callable tools along with their input/output contracts, permission labels, and error semantics.
 - **Design Decision**:
@@ -81,7 +105,7 @@
 
 ---
 
-## 3. Architectural Constraints (Non-Negotiable)
+## 5. Architectural Constraints (Non-Negotiable)
 
 - `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.

package/templates/common/docs/harness/state-machines.md

@@ -10,6 +10,14 @@
 
 Fill out each stateful component using this format:
 
+Before defining states, name the state owner and persistence level. State that crosses agent handoff, retry, browser session, API workflow, or release boundary must have explicit transitions; temporary derived state should stay local and should not become a new state machine.
+
+### State Ownership
+
+| State Slice | Owner | Persistence | Notes |
+| --- | --- | --- | --- |
+| `{{STATE_SLICE}}` | `{{OWNER}}` | durable / runtime / derived / external | {{NOTES}} |
+
 ### State Enumeration
 
 | State | Description | Entry Condition | Exit Condition |

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

@@ -34,6 +34,42 @@ The main agent is the controller. It owns:
 
 Subagents provide bounded work. They do not own final scope, architecture, release claims, or user-facing decisions.
 
+## Built-in Agent Roster
+
+Use the installed roster under `.claude/agents/` before inventing ad hoc roles.
+
+| Agent | Default Use |
+| --- | --- |
+| `planner` | decompose goals, map unknowns, define success criteria and write sets |
+| `researcher` | local/external ecosystem context, comparable projects, current facts |
+| `docs-researcher` | official docs, SDK/API behavior, browser/tool constraints |
+| `architect` | boundaries, interface decoupling, state ownership, data flow, migration risk |
+| `test-writer` | failing tests, manual check contracts, browser/API evidence plan |
+| `implementer` | bounded code or doc changes after the second plan |
+| `reviewer` | spec compliance, code quality, maintainability, security, missing tests |
+| `debugger` | reproduced failures, root cause isolation, smallest safe fix |
+| `verifier` | command execution, real browser/API checks, final evidence |
+
+## WF Default Fan-Out
+
+Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` requires at least 3 distinct agents from `.claude/agents/` before second planning.
+
+Default starter set:
+
+- `planner` for decomposition and local map
+- `architect` for boundaries, interfaces, and state impact
+- `researcher` or `docs-researcher` depending whether the unknowns are project/ecosystem facts or official tool/API behavior
+
+Then add phase-specific agents:
+
+- `test-writer` before implementation
+- `implementer` for the serial write lane
+- `reviewer` for spec and code-quality gates
+- `debugger` after a reproduced verification failure
+- `verifier` for final command/browser/API evidence
+
+The default decision ratio is a 7:3 collaboration bias: choose multi-agent collaboration for substantial or uncertain work about 70% of the time; choose solo mode only for clearly local, low-risk work that is not explicitly in WF/WK mode.
+
 ## Efficiency Ladder
 
 Choose the cheapest coordination level that is safe.
@@ -46,13 +82,13 @@ Choose the cheapest coordination level that is safe.
 | Serial build lane | normal feature or fix | test-writer -> implementer -> reviewers -> verifier |
 | Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
 
-Default: at most three active subagents. More agents increase coordination cost and conflict risk.
+Default for automatic WF triggers: 3-5 active read-only agents before second planning. For explicit WF/WK mode, never use the solo pass unless subagents are unavailable; use bounded role passes as the recorded fallback.
 
 ## WF Orchestration Shape
 
 ```text
 controller intake
--> parallel explorer/researcher/docs-researcher/architect passes
+-> parallel planner/researcher/docs-researcher/architect subagents
 -> controller synthesis
 -> second plan with dependencies and write sets
 -> test-writer

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

@@ -353,9 +353,20 @@ requireText('Harness/agent-workflow.md', 'Harness/PLAN.md');
 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 mode`, `workflow mode`, or `wk mode` MUST spawn at least 3 distinct subagents', 'explicit WF/WK subagent minimum');
+requireText('Harness/WF.md', '.claude/agents/', 'WF built-in agent roster path');
+requireText('Harness/WF.md', '7:3 collaboration bias', 'WF collaboration bias');
+requireText('Harness/README.md', '`/wf`, `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/harness-router/SKILL.md', '`/wf`, `wf mode`, `workflow mode`, `wk mode`', 'harness-router WF/WK aliases');
 requireText('.claude/skills/wf-mode/SKILL.md', 'Harness/WF.md', 'wf-mode loads WF document');
 requireText('.claude/skills/wf-mode/SKILL.md', 'Harness/subagents.md', 'wf-mode loads subagent orchestration');
+requireText('.claude/skills/wf-mode/SKILL.md', 'wk mode', 'wf-mode wk alias');
+requireText('.claude/skills/wf-mode/SKILL.md', 'spawn at least 3 distinct subagents from `.claude/agents/`', 'wf-mode subagent minimum');
 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`, `wk mode`', 'subagent-orchestrator WF/WK aliases');
 requireText('.claude/skills/harness-context/SKILL.md', 'Harness/subagents.md', 'harness-context loads subagents doc');
 requireText('.claude/skills/readme-optimizer/SKILL.md', 'README.md', 'readme-optimizer loads README');
 requireText('.claude/skills/readme-optimizer/SKILL.md', 'Harness/architecture.md', 'readme-optimizer links architecture docs');
@@ -363,8 +374,16 @@ requireText('Harness/subagents.md', '## Source Attribution', 'subagent source at
 requireText('Harness/subagents.md', 'npx skills find', 'find-skills discovery attribution');
 requireText('Harness/subagents.md', 'superpowers:dispatching-parallel-agents', 'parallel-agent source attribution');
 requireText('Harness/subagents.md', 'superpowers:subagent-driven-development', 'subagent-driven source attribution');
+requireText('Harness/subagents.md', '## Built-in Agent Roster', 'built-in agent roster');
+requireText('Harness/subagents.md', '## WF Default Fan-Out', 'WF default fan-out');
+requireText('Harness/subagents.md', '7:3 collaboration bias', 'subagent collaboration bias');
+requireText('Harness/subagents.md', 'parallel planner/researcher/docs-researcher/architect subagents', 'WF roster orchestration shape');
 requireText('Harness/subagents.md', '## Efficiency Ladder', 'subagent efficiency ladder');
 requireText('Harness/subagents.md', '## Review Gates', 'subagent review gates');
+requireText('Harness/architecture.md', '## 2. Interface Decoupling', 'architecture interface decoupling');
+requireText('Harness/architecture.md', '## 3. State Design', 'architecture state design');
+requireText('Harness/architecture.md', 'Avoid speculative abstraction', 'anti-overengineering architecture rule');
+requireText('CLAUDE.md', 'Use explicit interfaces or state models only when they protect a real boundary', 'CLAUDE interface/state simplicity rule');
 
 if (errors.length) {
   console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);