create-harness-vibe-coding 0.1.10 → 0.2.1

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

@@ -0,0 +1,176 @@
+# Subagent Orchestration
+
+Purpose: coordinate subagents for speed without losing control of scope, evidence, or integration.
+
+Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or `/wf`.
+
+project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+
+## Source Attribution
+
+This harness distills ideas from these sources. Keep the protocol local and conservative; do not import external runtimes by default.
+
+| Source | Found By | Adopted Idea |
+| --- | --- | --- |
+| `superpowers:dispatching-parallel-agents` | local skill | Dispatch one agent per independent problem domain; give focused scope and exact context. |
+| `superpowers:subagent-driven-development` | local skill | Fresh implementer per task; spec review before code-quality review; handle `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, and `BLOCKED`. |
+| [`flc1125/skills@subagent-orchestrator`](https://skills.sh/flc1125/skills/subagent-orchestrator) | `npx skills find "subagent orchestration"` | Explicit subagent invocation, role-specific prompts, tool permission awareness. |
+| [`davila7/claude-code-templates@parallel-agents`](https://skills.sh/davila7/claude-code-templates/parallel-agents) | `npx skills find "parallel agents"` | Discovery -> domain agents -> synthesis; one unified synthesis instead of scattered reports. |
+| [`ruvnet/ruflo@agent-workflow`](https://skills.sh/ruvnet/ruflo/agent-workflow) | `npx skills find "agent workflow"` | Workflow thinking: triggers, agent assignments, parallel processing, and stateful handoffs. |
+| [`pcvelz/superpowers@subagent-driven-development`](https://skills.sh/pcvelz/superpowers/subagent-driven-development) | `npx skills find "subagent driven development"` | Implementer plus review gates for spec compliance and code quality. |
+| [`oimiragieo/agent-studio`](https://skills.sh/oimiragieo/agent-studio/dispatching-parallel-agents) | Skills CLI / public docs | Router-subordinate architecture and durable handoff discipline. |
+| [`subagent-orchestration-skill`](https://skills.rest/rjtaryn/skills/subagent-orchestration-skill) | public docs | Multi-stage executor, spec reviewer, code reviewer, circuit breaker, and escalation pattern. |
+
+## Controller Role
+
+The main agent is the controller. It owns:
+
+- intent confidence and user questions
+- task decomposition
+- read/write set boundaries
+- dispatch table in `Harness/PLAN.md`
+- integration of returned summaries
+- final verification and closeout
+
+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.
+
+| Level | Use When | Pattern |
+| --- | --- | --- |
+| Solo pass | one file, low risk, clear intent | no subagent |
+| Single reviewer | small change with meaningful risk | implement, then reviewer |
+| Parallel read-only | broad reading, research, architecture, multiple independent failures | 2-3 read-only agents |
+| 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 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 planner/researcher/docs-researcher/architect subagents
+-> controller synthesis
+-> second plan with dependencies and write sets
+-> test-writer
+-> implementer
+-> spec reviewer
+-> code/architecture reviewer
+-> verifier
+-> if failed: debugger/fixer -> review -> verify -> loop
+-> close with evidence
+```
+
+Use this shape for `/wf`, long tasks, multi-file changes, architecture work, migrations, browser/API behavior, or repeated failures.
+
+## Dispatch Pack
+
+Every subagent dispatch must be self-contained:
+
+```text
+Role:
+Goal:
+Mode: read-only | write
+Read set:
+Write set:
+Forbidden scope:
+Injected docs:
+Dependencies:
+Expected evidence:
+Stop condition:
+Return format:
+```
+
+Do not make a subagent rediscover the entire project or read the whole harness. Inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`.
+
+## Parallelism Rules
+
+- Read-only agents may run in parallel.
+- Writing agents run serially unless write sets are disjoint and the controller has chosen an isolated worktree.
+- Reviewers may run in parallel after implementation, but spec compliance is evaluated before code-quality approval.
+- Do not let two agents edit `Harness/PLAN.md`, `Harness/MEMORY.md`, or `Harness/memory/*` concurrently. The controller writes durable state.
+- If two agents disagree, the controller records the conflict in `Harness/PLAN.md` and chooses the smallest reversible next step.
+
+## Review Gates
+
+Implementation is not complete until both gates pass:
+
+1. **Spec review**: confirms the result matches the user request, PRD, feature doc, acceptance criteria, and non-goals. Extra features are failures.
+2. **Code-quality review**: checks correctness, maintainability, architecture, tests, security, and integration risk.
+
+If either reviewer finds issues, the implementer or debugger fixes them and the same gate runs again. Do not move to verifier with open critical/high findings.
+
+## Subagent Status Handling
+
+| Status | Controller Action |
+| --- | --- |
+| `DONE` | start review gates |
+| `DONE_WITH_CONCERNS` | read concerns, decide whether to address before review, record in `PLAN.md` |
+| `NEEDS_CONTEXT` | provide only missing context and re-dispatch |
+| `BLOCKED` | change something: add context, split task, upgrade reasoning, use debugger, or ask user |
+
+Never retry the same failed prompt unchanged.
+
+## Failure Recovery
+
+- First failed verification: record evidence, dispatch debugger with the smallest reproduced failure.
+- Second same-class failure: narrow scope, update `PLAN.md#Heartbeat`, and add a reviewer before another fix.
+- Third same-class failure: stop blind fixes. Present evidence-backed options to the user.
+
+The recovery loop must preserve the same evidence standard as the main workflow: real commands, real browser/API checks when applicable, and recorded logs or artifacts.
+
+## Synthesis Output
+
+After subagents return, the controller writes one synthesis into `Harness/PLAN.md`:
+
+```text
+Agents used:
+Findings accepted:
+Findings rejected:
+Conflicts:
+Decisions:
+Next write set:
+Verification path:
+Residual risk:
+```
+
+Only the synthesis and named files enter main context. Do not replay full subagent conversations.

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

@@ -15,7 +15,7 @@
 
 ### v0.1 Must Be Able To
 
-> Each item below must be split into a separate `docs/features/<name>.md` created from `docs/features/_template.md` before implementation begins. One feature = one doc = one implementation unit.
+> Each item below must be split into a separate `Harness/features/<name>.md` created from `Harness/features/_template.md` before implementation begins. One feature = one doc = one implementation unit.
 
 - [ ] {{MUST_1}}
 - [ ] {{MUST_2}}

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 `docs/harness/PLAN.md`.
+Skip only when the task is local, narrow, and fully answerable from existing project files. Record the skip reason in `Harness/PLAN.md`.
 
 ## Research Agent
 
@@ -21,7 +21,7 @@ Built-in agents:
 - `.claude/agents/researcher.md`: product, market, open-source, dependency, pricing, policy, and ecosystem research.
 - `.claude/agents/docs-researcher.md`: official docs, API, SDK, config, limits, errors, and examples verification.
 
-For multi-agent research plus build work, create the dispatch table in `docs/harness/PLAN.md` and follow `docs/harness/dispatch.md`.
+For multi-agent research plus build work, create the dispatch table in `Harness/PLAN.md` and follow `Harness/dispatch.md`.
 
 Research Agent input:
 
@@ -104,14 +104,14 @@ Use these patterns when turning research into PRD or feature docs:
 
 ## Write Target
 
-- Research process, queries, and limitations: this file or `docs/harness/PLAN.md`.
+- Research process, queries, and limitations: this file or `Harness/PLAN.md`.
 - Final research decisions: [research-results.md](research-results.md).
 - Product scope: [PRD.md](PRD.md).
-- Architecture consequences: `docs/harness/architecture.md` and `docs/domain/ports.md`.
+- Architecture consequences: `Harness/architecture.md` and `Harness/domain/ports.md`.
 
 ## Architecture Decision References
 
-When filling `docs/harness/architecture.md`, `docs/domain/ports.md`, and `docs/research/research-results.md`, use these high-trust sources as starting points. Search within them; do not read them whole.
+When filling `Harness/architecture.md`, `Harness/domain/ports.md`, and `Harness/research/research-results.md`, use these high-trust sources as starting points. Search within them; do not read them whole.
 
 ### System Design & Architecture Patterns
 

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

@@ -7,7 +7,7 @@ const args = new Set(process.argv.slice(2));
 const strict = args.has('--strict') || args.has('--post-bootstrap');
 
 if (args.has('--help') || args.has('-h')) {
-  console.log(`Usage: node scripts/validate-harness.mjs [--strict]
+  console.log(`Usage: node Harness/scripts/validate-harness.mjs [--strict]
 
 Default mode checks scaffold structure, links, agents, and skills.
 --strict also fails when project fact docs still contain unresolved {{TOKEN}} placeholders.
@@ -33,46 +33,53 @@ const commonSkills = [
   'harness-research',
   'harness-context',
   'harness-build-loop',
+  'wf-mode',
+  'subagent-orchestrator',
+  'readme-optimizer',
 ];
 
 const memoryFiles = [
-  'memory/tool-usage-reflections.md',
-  'memory/user-corrections-preferences.md',
-  'memory/agent-lessons-patterns.md',
+  'Harness/memory/tool-usage-reflections.md',
+  'Harness/memory/user-corrections-preferences.md',
+  'Harness/memory/agent-lessons-patterns.md',
 ];
 
 const required = [
   'AGENTS.md',
   'CLAUDE.md',
-  'MEMORY.md',
+  'README.md',
+  'Harness/MEMORY.md',
+  'Harness/WF.md',
   ...memoryFiles,
   '.claude/settings.json',
+  '.claude/commands/wf.md',
   '.claude/rules/ecc/common.md',
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
   ...commonSkills.map(skill => `.claude/skills/${skill}/SKILL.md`),
-  'docs/README.md',
-  'docs/harness/PLAN.md',
-  'docs/harness/lifecycle.md',
-  'docs/harness/dispatch.md',
-  'docs/harness/extension.md',
-  'docs/harness/context-loading.md',
-  'docs/harness/agent-workflow.md',
-  'docs/harness/architecture.md',
-  'docs/harness/data-flow.md',
-  'docs/harness/state-machines.md',
-  'docs/features/_template.md',
-  'docs/research/README.md',
-  'docs/research/research-results.md',
-  'docs/research/PRD.md',
-  'docs/domain/ports.md',
+  'Harness/README.md',
+  'Harness/PLAN.md',
+  'Harness/lifecycle.md',
+  'Harness/subagents.md',
+  'Harness/dispatch.md',
+  'Harness/extension.md',
+  'Harness/context-loading.md',
+  'Harness/agent-workflow.md',
+  'Harness/architecture.md',
+  'Harness/data-flow.md',
+  'Harness/state-machines.md',
+  'Harness/features/_template.md',
+  'Harness/research/README.md',
+  'Harness/research/research-results.md',
+  'Harness/research/PRD.md',
+  'Harness/domain/ports.md',
 ];
 
 const projectFacts = [
-  'docs/harness/PLAN.md',
-  'docs/research/PRD.md',
-  'docs/research/research-results.md',
-  'docs/harness/architecture.md',
-  'docs/domain/ports.md',
+  'Harness/PLAN.md',
+  'Harness/research/PRD.md',
+  'Harness/research/research-results.md',
+  'Harness/architecture.md',
+  'Harness/domain/ports.md',
 ];
 
 const contextPacks = [
@@ -89,9 +96,10 @@ const contextPacks = [
 ];
 
 const durableCommunicationDocs = [
-  'docs/README.md',
-  'docs/harness/dispatch.md',
-  'docs/harness/context-loading.md',
+  'Harness/README.md',
+  'Harness/subagents.md',
+  'Harness/dispatch.md',
+  'Harness/context-loading.md',
 ];
 
 const errors = [];
@@ -141,14 +149,40 @@ function unresolvedTemplatePlaceholders(text) {
   return [...new Set(placeholders)];
 }
 
+function registeredSkillFiles(...texts) {
+  const files = new Set();
+  const pattern = /(?:\.\.\/)?(\.claude\/skills\/[a-z0-9-]+\/SKILL\.md)/g;
+
+  for (const text of texts) {
+    for (const match of text.matchAll(pattern)) {
+      files.add(match[1]);
+    }
+  }
+
+  return [...files].sort();
+}
+
+function registeredWorkflowFiles(...texts) {
+  const files = new Set();
+  const pattern = /(?:Harness\/)?workflows\/([A-Za-z0-9._-]+\.md)/g;
+
+  for (const text of texts) {
+    for (const match of text.matchAll(pattern)) {
+      files.add(`Harness/workflows/${match[1]}`);
+    }
+  }
+
+  return [...files].sort();
+}
+
 for (const rel of required) {
   if (!fs.existsSync(path.join(root, rel))) {
     errors.push(`missing required file: ${rel}`);
   }
 }
 
-if (fs.existsSync(path.join(root, 'docs/research/scaffolds.md'))) {
-  errors.push('legacy research file should be renamed: docs/research/scaffolds.md -> docs/research/research-results.md');
+if (fs.existsSync(path.join(root, 'Harness/research/scaffolds.md'))) {
+  errors.push('legacy research file should be renamed: Harness/research/scaffolds.md -> Harness/research/research-results.md');
 }
 
 if (strict) {
@@ -165,10 +199,10 @@ if (strict) {
   }
 }
 
-const docsReadme = read('docs/README.md');
+const docsReadme = read('Harness/README.md');
 if (docsReadme) {
   for (const marker of ['## Keyword Routing', '## Load By Task', 'When to Read', 'Keywords']) {
-    if (!docsReadme.includes(marker)) errors.push(`docs/README.md missing router marker: ${marker}`);
+    if (!docsReadme.includes(marker)) errors.push(`Harness/README.md missing router marker: ${marker}`);
   }
 }
 
@@ -179,50 +213,77 @@ for (const rel of durableCommunicationDocs) {
 
 requireText('CLAUDE.md', 'same tool/use pattern fails 3+ times', 'tool reflection trigger');
 requireText('CLAUDE.md', 'user corrects the same assumption/pattern 2+ times', 'user correction reflection trigger');
+requireText('CLAUDE.md', 'If `Harness/` exists, this repository is governed by the Harness contract', 'Harness binding contract');
+requireText('CLAUDE.md', 'Harness/MEMORY.md` is the memory/resource router', 'memory/resource router');
+requireText('CLAUDE.md', 'Harness/README.md#Load By Task', 'Harness task router');
+requireText('CLAUDE.md', 'Harness/SETUP.md` exists, follow it before normal project work', 'setup bootstrap contract');
+requireText('CLAUDE.md', 'subagent-orchestrator` and `Harness/subagents.md', 'subagent orchestrator entry trigger');
+for (const heading of ['## 2. Think Before Coding', '## 3. Simplicity First', '## 4. Surgical Changes', '## 5. Goal-Driven Execution']) {
+  requireText('CLAUDE.md', heading, `Karpathy-style rule heading: ${heading}`);
+}
 
-const plan = read('docs/harness/PLAN.md');
+const plan = read('Harness/PLAN.md');
 if (plan) {
-  for (const heading of ['## Current Goal', '## Phase', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Verification']) {
-    if (!plan.includes(heading)) errors.push(`docs/harness/PLAN.md missing heading: ${heading}`);
+  for (const heading of ['## Current Goal', '## Phase', '## Heartbeat', '## Success Criteria', '## Loaded Context', '## Tasks', '## Parallel Dispatch', '## Subagent Synthesis', '## Verification']) {
+    if (!plan.includes(heading)) errors.push(`Harness/PLAN.md missing heading: ${heading}`);
+  }
+  for (const marker of ['Next beat trigger', 'Recovery action']) {
+    if (!plan.includes(marker)) errors.push(`Harness/PLAN.md missing heartbeat marker: ${marker}`);
   }
 }
 
-const dispatch = read('docs/harness/dispatch.md');
+const dispatch = read('Harness/dispatch.md');
 if (dispatch) {
   for (const agent of commonAgents) {
-    if (!dispatch.includes(`\`${agent}\``)) errors.push(`docs/harness/dispatch.md missing common agent: ${agent}`);
+    if (!dispatch.includes(`\`${agent}\``)) errors.push(`Harness/dispatch.md missing common agent: ${agent}`);
   }
-  if (!dispatch.includes('## Handoff Format')) errors.push('docs/harness/dispatch.md missing heading: ## Handoff Format');
+  if (!dispatch.includes('## Handoff Format')) errors.push('Harness/dispatch.md missing heading: ## Handoff Format');
 }
 
-const contextLoading = read('docs/harness/context-loading.md');
+const contextLoading = read('Harness/context-loading.md');
 if (contextLoading) {
-  if (!contextLoading.includes('docs/README.md` is the primary router')) {
-    errors.push('docs/harness/context-loading.md must declare docs/README.md as the primary router');
+  if (!contextLoading.includes('Harness/README.md` is the primary router')) {
+    errors.push('Harness/context-loading.md must declare Harness/README.md as the primary router');
   }
   for (const pack of contextPacks) {
-    if (!contextLoading.includes(pack)) errors.push(`docs/harness/context-loading.md missing subagent pack: ${pack}`);
+    if (!contextLoading.includes(pack)) errors.push(`Harness/context-loading.md missing subagent pack: ${pack}`);
   }
 }
 
-const memory = read('MEMORY.md');
+const memory = read('Harness/MEMORY.md');
 if (memory) {
   for (const agent of commonAgents) {
     const rel = `.claude/agents/${agent}.md`;
-    if (!memory.includes(rel)) errors.push(`MEMORY.md missing agent registration: ${rel}`);
+    if (!memory.includes(rel)) errors.push(`Harness/MEMORY.md missing agent registration: ${rel}`);
   }
   for (const skill of commonSkills) {
     const rel = `.claude/skills/${skill}/SKILL.md`;
-    if (!memory.includes(rel)) errors.push(`MEMORY.md missing skill registration: ${rel}`);
+    if (!memory.includes(rel)) errors.push(`Harness/MEMORY.md missing skill registration: ${rel}`);
   }
   for (const rel of memoryFiles) {
-    if (!memory.includes(rel)) errors.push(`MEMORY.md missing memory file registration: ${rel}`);
+    const relativeRel = rel.replace(/^Harness\//, '');
+    if (!memory.includes(rel) && !memory.includes(relativeRel)) {
+      errors.push(`Harness/MEMORY.md missing memory file registration: ${rel}`);
+    }
+  }
+}
+
+for (const workflow of listMarkdownFiles('Harness/workflows')) {
+  const relativeWorkflow = workflow.replace(/^Harness\//, '');
+  if (!docsReadme.includes(workflow) && !docsReadme.includes(relativeWorkflow) && !memory.includes(workflow) && !memory.includes(relativeWorkflow)) {
+    errors.push(`workflow is not registered in Harness/README.md or Harness/MEMORY.md: ${workflow}`);
+  }
+}
+
+for (const skillFile of registeredSkillFiles(docsReadme, memory)) {
+  if (!fs.existsSync(path.join(root, skillFile))) {
+    errors.push(`registered skill file is missing: ${skillFile}`);
   }
 }
 
-for (const workflow of listMarkdownFiles('docs/workflows')) {
-  if (!docsReadme.includes(workflow) && !memory.includes(workflow)) {
-    errors.push(`workflow is not registered in docs/README.md or MEMORY.md: ${workflow}`);
+for (const workflowFile of registeredWorkflowFiles(docsReadme, memory)) {
+  if (!fs.existsSync(path.join(root, workflowFile))) {
+    errors.push(`registered workflow file is missing: ${workflowFile}`);
   }
 }
 
@@ -241,9 +302,9 @@ function requireUiSelectorContract(rel) {
   }
 }
 
-requireUiSelectorContract('docs/workflows/browser-e2e.md');
-requireUiSelectorContract('docs/workflows/ts-react-frontend.md');
-requireUiSelectorContract('docs/features/_template.md');
+requireUiSelectorContract('Harness/workflows/browser-e2e.md');
+requireUiSelectorContract('Harness/workflows/ts-react-frontend.md');
+requireUiSelectorContract('Harness/features/_template.md');
 
 for (const skill of commonSkills) {
   const rel = `.claude/skills/${skill}/SKILL.md`;
@@ -287,9 +348,42 @@ for (const agent of commonAgents) {
   }
 }
 
-requireText('docs/harness/extension.md', 'Skills should extend the harness');
-requireText('docs/harness/agent-workflow.md', 'docs/harness/PLAN.md');
-requireText('docs/research/README.md', 'research-results.md');
+requireText('Harness/extension.md', 'Skills should extend the harness');
+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');
+requireText('Harness/subagents.md', '## Source Attribution', 'subagent source attribution');
+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)' : ''}:`);
@@ -299,5 +393,5 @@ if (errors.length) {
 
 console.log(`Harness validation passed${strict ? ' (strict)' : ''}.`);
 if (!strict) {
-  console.log('Tip: run `node scripts/validate-harness.mjs --strict` after bootstrap to check unresolved project placeholders.');
+  console.log('Tip: run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap to check unresolved project placeholders.');
 }

package/templates/optional/skills/browser-e2e/.claude/skills/browser-e2e/SKILL.md

@@ -11,8 +11,8 @@ Use this skill when a change affects browser-visible behavior, navigation, forms
 
 ## Docs To Load
 
-- `docs/workflows/browser-e2e.md`
-- `docs/harness/PLAN.md`
+- `Harness/workflows/browser-e2e.md`
+- `Harness/PLAN.md`
 - Existing project test, build, and run instructions.
 
 ## Required Inputs
@@ -26,7 +26,7 @@ Use this skill when a change affects browser-visible behavior, navigation, forms
 
 - Browser test files in the project's existing test locations.
 - Evidence artifacts such as screenshots, traces, or reports in existing artifact folders.
-- Notes in `docs/harness/PLAN.md` when the active task asks for plan tracking.
+- Notes in `Harness/PLAN.md` when the active task asks for plan tracking.
 
 ## Output Format
 
@@ -35,8 +35,8 @@ Include the selectors used for CDP/Playwright/manual verification.
 
 ## PLAN.md Updates
 
-Update `docs/harness/PLAN.md` only when executing a tracked plan item or recording evidence requested by the current task.
+Update `Harness/PLAN.md` only when executing a tracked plan item or recording evidence requested by the current task.
 
 ## dispatch.md Usage
 
-Use `docs/harness/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.
+Use `Harness/dispatch.md` only when splitting independent browser checks across workers is explicitly useful.

package/templates/optional/skills/browser-e2e/docs/workflows/browser-e2e.md

@@ -19,7 +19,7 @@
 - Capture runtime exceptions, console errors, and failed network requests before and after the flow.
 - Interact through stable accessible labels/roles or `data-testid`, not brittle DOM paths.
 - Verify at least one critical flow end-to-end in the real browser target.
-- Save screenshot, trace, video, or result artifact paths and record them in `docs/harness/PLAN.md` or the feature doc.
+- Save screenshot, trace, video, or result artifact paths and record them in `Harness/PLAN.md` or the feature doc.
 - Clean up any dev server or browser processes started for verification.
 
 ## Common Commands

package/templates/optional/skills/github-pr-review/.claude/skills/github-pr-review/SKILL.md

@@ -11,8 +11,8 @@ Use this skill when reviewing a GitHub pull request, responding to PR feedback,
 
 ## Docs To Load
 
-- `docs/workflows/github-pr-review.md`
-- `docs/harness/PLAN.md`
+- `Harness/workflows/github-pr-review.md`
+- `Harness/PLAN.md`
 - Repository contribution, test, and review guidelines.
 
 ## Required Inputs
@@ -25,7 +25,7 @@ Use this skill when reviewing a GitHub pull request, responding to PR feedback,
 
 - Local files needed to address approved review feedback.
 - Review notes or evidence in existing docs only when requested.
-- `docs/harness/PLAN.md` when tracking review work.
+- `Harness/PLAN.md` when tracking review work.
 
 ## Output Format
 
@@ -33,8 +33,8 @@ Return findings first by severity with file and line references, then open quest
 
 ## PLAN.md Updates
 
-Update `docs/harness/PLAN.md` only when the PR review is part of a tracked implementation plan.
+Update `Harness/PLAN.md` only when the PR review is part of a tracked implementation plan.
 
 ## dispatch.md Usage
 
-Use `docs/harness/dispatch.md` when independent review areas can be assigned separately, such as backend, frontend, and CI.
+Use `Harness/dispatch.md` when independent review areas can be assigned separately, such as backend, frontend, and CI.

package/templates/optional/skills/python-backend/.claude/skills/python-backend/SKILL.md

@@ -11,8 +11,8 @@ Use this skill when changing Python API routes, service logic, persistence bound
 
 ## Docs To Load
 
-- `docs/workflows/python-backend.md`
-- `docs/harness/PLAN.md`
+- `Harness/workflows/python-backend.md`
+- `Harness/PLAN.md`
 - Project backend README, API docs, dependency files, and test configuration.
 
 ## Required Inputs
@@ -25,7 +25,7 @@ Use this skill when changing Python API routes, service logic, persistence bound
 
 - Python source, tests, fixtures, and backend docs in the task scope.
 - Local evidence artifacts such as test output snippets.
-- `docs/harness/PLAN.md` when the task requires plan tracking.
+- `Harness/PLAN.md` when the task requires plan tracking.
 
 ## Output Format
 
@@ -33,8 +33,8 @@ Return files changed, API or behavior summary, tests run, important logs, migrat
 
 ## PLAN.md Updates
 
-Update `docs/harness/PLAN.md` only when executing a tracked plan item or recording required validation evidence.
+Update `Harness/PLAN.md` only when executing a tracked plan item or recording required validation evidence.
 
 ## dispatch.md Usage
 
-Use `docs/harness/dispatch.md` for separable backend work such as API implementation, database changes, and test coverage.
+Use `Harness/dispatch.md` for separable backend work such as API implementation, database changes, and test coverage.