create-harness-vibe-coding 0.7.2 → 0.8.0

package/templates/common/.claude/rules/ecc/common.md

@@ -1,45 +1,45 @@
----
-description: "Universal harness constraints"
-alwaysApply: true
----
-
-# Universal Rules
-
-## Context
-
-- Start with `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
-- Do not bulk-read `Harness/`. Load by router trigger.
-- Keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current when work has multiple steps, files, or agents.
-- 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/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
-
-## Verification
-
-- Define acceptance criteria before implementation.
-- New behavior: failing test first, or a written manual check if automation is not feasible yet.
-- Bug fix: reproduction first.
-- Before release, add CI for the chosen stack and run the full verification path.
-
-## Subagents
-
-- Use `Harness/subagents.md` before orchestrating multiple agents.
-- Use `Harness/context-loading.md` before spawning.
-- Use `Harness/dispatch.md` before parallel or multi-agent work.
-- Use `Harness/extension.md` before adding stack-specific agents, skills, rules, or hooks.
-- Every subagent needs role, task, read boundary, write boundary, and return format.
-- Writing agents must run serially unless write sets are disjoint.
-- If the runtime cannot spawn subagents, emulate the same role pack in a separate bounded pass.
-- Main agent owns integration and final verification.
-
-## Memory
-
-- Record a lightweight reflection in `Harness/memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times.
-- Record repeated user corrections or durable preferences in `Harness/memory/user-corrections-preferences.md` when the user corrects the same assumption/pattern 2+ times.
-- Record reusable review/debug lessons in `Harness/memory/agent-lessons-patterns.md`.
-- Keep memory entries concise and never include secrets.
-
-## Security
-
-- No secrets in source code.
-- Validate external input at system boundaries.
-- High-risk actions need explicit user approval or documented permission policy.
+---
+description: "Universal harness constraints"
+alwaysApply: true
+---
+
+# Universal Rules
+
+## Context
+
+- Start with `CLAUDE.md`, `Harness/MEMORY.md`, and `Harness/README.md`.
+- Do not bulk-read `Harness/`. Load by router trigger.
+- Keep `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` current when work has multiple steps, files, or agents.
+- 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/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
+
+## Verification
+
+- Define acceptance criteria before implementation.
+- New behavior: failing test first, or a written manual check if automation is not feasible yet.
+- Bug fix: reproduction first.
+- Before release, add CI for the chosen stack and run the full verification path.
+
+## Subagents
+
+- Use `Harness/subagents.md` before orchestrating multiple agents.
+- Use `Harness/context-loading.md` before spawning.
+- Use `Harness/dispatch.md` before parallel or multi-agent work.
+- Use `Harness/extension.md` before adding stack-specific agents, skills, rules, or hooks.
+- Every subagent needs role, task, read boundary, write boundary, and return format.
+- Writing agents must run serially unless write sets are disjoint.
+- If the runtime cannot spawn subagents, emulate the same role pack in a separate bounded pass.
+- Main agent owns integration and final verification.
+
+## Memory
+
+- Record a lightweight reflection in `Harness/memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times.
+- Record repeated user corrections or durable preferences in `Harness/memory/user-corrections-preferences.md` when the user corrects the same assumption/pattern 2+ times.
+- Record reusable review/debug lessons in `Harness/memory/agent-lessons-patterns.md`.
+- Keep memory entries concise and never include secrets.
+
+## Security
+
+- No secrets in source code.
+- Validate external input at system boundaries.
+- High-risk actions need explicit user approval or documented permission policy.

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

@@ -1,68 +1,68 @@
-{
-  "$schema": "https://json.schemastore.org/claude-code-settings.json",
-  "permissions": {
-    "allow": [
-      "Bash(git *)",
-      "Bash(npm *)",
-      "Bash(npx *)",
-      "Bash(python *)",
-      "Bash(pytest *)",
-      "Bash(pip *)",
-      "Bash(go *)",
-      "Bash(cargo *)",
-      "Bash(node *)",
-      "Read",
-      "Glob",
-      "Grep",
-      "WebFetch",
-      "WebSearch"
-    ],
-    "deny": [
-      "EnterPlanMode",
-      "Bash(rm -rf *)",
-      "Bash(sudo *)",
-      "Bash(curl *)",
-      "Bash(wget *)",
-      "Bash(> *)",
-      "Read(.env*)",
-      "Read(**/secrets/**)",
-      "Read(**/*.key)",
-      "Read(**/*.pem)"
-    ]
-  },
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node Harness/scripts/wf-mode-hook.mjs"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node Harness/scripts/wf-mode-hook.mjs"
-          }
-        ]
-      }
-    ],
-    "PreToolUse": [
-      {
-        "matcher": "Edit|Write|MultiEdit|Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node Harness/scripts/wf-mode-hook.mjs"
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(npm *)",
+      "Bash(npx *)",
+      "Bash(python *)",
+      "Bash(pytest *)",
+      "Bash(pip *)",
+      "Bash(go *)",
+      "Bash(cargo *)",
+      "Bash(node *)",
+      "Read",
+      "Glob",
+      "Grep",
+      "WebFetch",
+      "WebSearch"
+    ],
+    "deny": [
+      "EnterPlanMode",
+      "Bash(rm -rf *)",
+      "Bash(sudo *)",
+      "Bash(curl *)",
+      "Bash(wget *)",
+      "Bash(> *)",
+      "Read(.env*)",
+      "Read(**/secrets/**)",
+      "Read(**/*.key)",
+      "Read(**/*.pem)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node Harness/scripts/wf-mode-hook.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -1,42 +1,47 @@
 ---
 name: subagent-orchestrator
-description: Use when work needs bounded subagent coordination, parallel read-only exploration, independent review gates, broad context partitioning, or controlled handoffs for coordination-heavy tasks.
+description: Use when work needs bounded subagent coordination, parallel read-only exploration, independent review gates, broad context partitioning, or controlled handoffs.
 ---
 
 # Subagent Orchestrator
 
-Load:
+This skill is runtime-neutral. Claude Code and Codex expose different
+subagent surfaces; follow the same Harness role contract either way.
+
+## Load
 
 - `Harness/subagents.md`
 - `Harness/dispatch.md`
 - `Harness/context-loading.md`
-- `Harness/PROGRESS.md`
-- `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md` when active
 - `Harness/agent-workflow.md`
-- `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/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, integrates returns, and owns final verification.
-- Subagents are readers and reporters. Only the controller writes to task state files.
-- **CEO Exploration Rule**: The controller MUST NOT read source files during exploration. Delegate ALL codebase reading to subagents. Default model is `sonnet` — exploration requires real code understanding. Use `haiku` only for shallow scans (directory listing, file counts). Use `opus` if the user requests. The CEO's instinct to "just check one file" is the #1 cause of failed parallelism. CEO reads only `Harness/` docs, `CLAUDE.md`, and subagent returns until the plan is written.
-- 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.
-- If verification fails, dispatch debugger/fixer with the smallest reproduced failure, then re-review and re-verify.
-- If subagents are unavailable, emulate the same roles as separate bounded passes and record that fallback.
-- When used outside WF mode, update `Harness/tasks/<task-id>/PLAN.md#Subagent Dispatch`; update `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` only if an active heartbeat/recovery loop exists.
-
-Return:
-
-- agents or bounded passes used
-- dispatch table status
-- accepted/rejected findings
-- conflicts and decisions
-- commands and evidence
-- remaining risks
-- updated heartbeat or next recovery action
+- `Harness/PROGRESS.md`
+- Active `Harness/tasks/<task-id>/PROGRESS.md` and `PLAN.md`, when present
+- `Harness/WF.md` when in `/wf`, `wf mode`, `workflow mode`, or `wk mode`
+
+## Runtime Mapping
+
+- Claude Code: use the `.claude/agents/` role roster and the available
+  subagent/task tool.
+- Codex: use the available subagent tool or role mechanism in the current
+  surface. If unavailable, emulate the same roles as separate bounded passes.
+- In every runtime, record fallback and role coverage in the task plan.
+
+## Rules
+
+- The main agent is the controller. It decomposes work, writes task state,
+  integrates returns, and owns final verification.
+- Subagents or bounded passes are readers and reporters unless a write set is
+  explicitly assigned and disjoint.
+- Explicit WF/WK mode requires at least three distinct role passes before the
+  second plan.
+- Every dispatch needs role, goal, mode, read set, write set, forbidden scope,
+  injected docs, dependencies, evidence, stop condition, and return format.
+- Prefer parallel read-only exploration first. Serialize writers unless write
+  sets are disjoint and isolated.
+- After implementation, run a spec review gate and a code/architecture review
+  gate before final verification.
+
+## Return
+
+Report roles or bounded passes used, dispatch table status, accepted/rejected
+findings, conflicts, decisions, commands, evidence, and remaining risks.

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

@@ -0,0 +1,36 @@
+---
+name: wf
+description: Use for /wf in Claude Code, $wf or /skills wf in Codex, or any long, uncertain, multi-file, migration, recovery, or architecture-heavy task that should follow Harness WF mode.
+---
+
+# WF Mode Adapter
+
+This skill is a thin tool adapter. The authoritative workflow lives in
+`Harness/WF.md`; do not duplicate or override it here.
+
+## Invocation
+
+- Claude Code: use `/wf <task>` or select the `wf` skill.
+- Codex CLI or IDE: use `$wf` or `/skills` then choose `wf`.
+- Codex app may also list enabled skills in the `/` menu, depending on the
+  current surface and feature state.
+
+## Load
+
+1. `CLAUDE.md`
+2. `Harness/MEMORY.md`
+3. `Harness/README.md`
+4. `Harness/PROGRESS.md`
+5. `Harness/WF.md`
+6. `Harness/subagents.md` before any role split
+
+## Rules
+
+- Create or update a task capsule under `Harness/tasks/<task-id>/`.
+- Run the WF loop from `Harness/WF.md`: intake, bounded exploration, second
+  plan, implementation, review, verification, recovery, and closeout.
+- For explicit WF invocation, use at least three distinct role passes before
+  the second plan. Use real subagents when the runtime supports them; otherwise
+  record a bounded-pass fallback in the task plan.
+- Keep `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` current before long
+  commands, after failures, and at closeout.

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

@@ -1,11 +1,14 @@
 ---
 name: wf-learn
-description: Use for /wf-learn or when the user wants to force a learning cycle from repeated errors, patterns, or session history. Dispatches context-master → memory-master pipeline to extract and consolidate durable knowledge.
+description: Use for /wf-learn in Claude Code, $wf-learn or /skills wf-learn in Codex, or when the user wants a learning cycle from repeated errors, corrections, patterns, or session history.
 ---
 
-# WF Learn
+# WF Learn Adapter
 
-Force a memory learning cycle. Context-master analyzes, memory-master consolidates. Writes to project-level `Harness/memory/*` and cross-project global memory.
+Force a memory learning cycle. Context-master analyzes; memory-master
+consolidates. Use the active runtime's available subagent mechanism when
+present, otherwise emulate the same roles as bounded passes and record that
+fallback.
 
 ## Load
 
@@ -13,34 +16,16 @@ Force a memory learning cycle. Context-master analyzes, memory-master consolidat
 - `Harness/memory/tool-usage-reflections.md`
 - `Harness/memory/user-corrections-preferences.md`
 - `Harness/memory/agent-lessons-patterns.md`
-- Current `Harness/PROGRESS.md` for active task context
+- Current `Harness/PROGRESS.md` and active task capsule, if any
 
 ## Flow
 
-```text
-1. context-master: analyze session, extract patterns
-2. memory-master: categorize + deduplicate + write to memory files
-3. CEO: commit memory files
-```
-
-## Write Targets
-
-| Scope | Path | When |
-|---|---|---|
-| Project | `Harness/memory/tool-usage-reflections.md` | tool/command patterns found |
-| Project | `Harness/memory/user-corrections-preferences.md` | user preferences found |
-| Project | `Harness/memory/agent-lessons-patterns.md` | review/debug lessons found |
-| Global | `<user>/.claude/projects/*/memory/` | cross-project patterns |
-
-## Rules
-
-- Never auto-write without context-master analysis first.
-- Memory-master handles dedup — if existing entry covers the same ground, update instead of creating duplicate.
-- If no new patterns found, report "nothing to learn" — don't force empty writes.
-- Subagents are readers and reporters. CEO writes the final memory files.
+1. Analyze the session for repeated failures, durable user corrections, and
+   reusable review/debug lessons.
+2. Deduplicate against existing memory.
+3. Write only concise, durable, non-secret lessons to `Harness/memory/*`.
 
 ## Return
 
-- Files written or updated
-- Patterns extracted (one-line each)
-- Skipped (with reason)
+Report files updated, patterns extracted, skipped candidates, and why each
+memory entry should survive context loss.

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

@@ -1,99 +1,35 @@
 ---
 name: wf-max
-description: Use for /wf max or maximum parallelism. Three-tier CEO→Manager→Worker hierarchy with recursive depth, per-domain span caps, and leaf-condition stop rules.
+description: Use for /wf-max in Claude Code, $wf-max or /skills wf-max in Codex, or maximum-parallelism Harness work with CEO to manager to worker decomposition.
 ---
 
-# WF Max — Maximum Parallelism
+# WF-MAX Adapter
 
-**WF-MAX ACTIVE: You are CEO, not implementer.**
+This skill is a thin tool adapter. The authoritative workflow lives in
+`Harness/WF-MAX.md`; do not duplicate or override it here.
 
-```
-CEO CONTRACT (enforced by hooks + D-GATE):
+## Invocation
 
-ALLOWED: Read (scoping), Grep/Glob (scoping), Agent (spawn), Task (tracking),
-         Write (PLAN.md/PROGRESS.md only), Bash (ls/dir/tree/git only)
+- Claude Code: use `/wf-max [task]` or select the `wf-max` skill.
+- Codex CLI or IDE: use `$wf-max` or `/skills` then choose `wf-max`.
+- Codex app may also list enabled skills in the `/` menu.
 
-FORBIDDEN: Edit/Write/MultiEdit on source files, Bash (build/run/edit),
-           sequential spawn (batch ALL agents in ONE message),
-           Read (deep source — delegate to Workers)
+## Load
 
-If tempted to edit source → STOP. Spawn a Worker.
-```
+1. `CLAUDE.md`
+2. `Harness/MEMORY.md`
+3. `Harness/README.md`
+4. `Harness/WF-MAX.md`
+5. `Harness/subagents.md`
+6. `Harness/dispatch.md`
+7. `Harness/agent-workflow.md`
 
-## Load (authoritative specs)
+## Rules
 
-- `Harness/WF-MAX.md` — full spec: organization model, Decomposition Gate, span formula, anti-pattern catalog, wave orchestration
-- `Harness/subagents.md` — agent roster, controller role, efficiency ladder
-- `Harness/dispatch.md` — File claim, Concurrency group handoff fields
-- `Harness/agent-workflow.md` — cohesion rule, completion gate
-
-## Trigger & When NOT to Use
-
-**Explicit invocation always fans out — no file-count escape.** When the user types `/wf-max`, spawning subagents is mandatory and unconditional. File count, task size, and overhead DO NOT apply to explicit invocation — they govern only AUTO-triggering. A 1-file `/wf-max` still fans out. "Degrade to /wf" changes the organization (flat vs CEO→Manager→Worker), never the fact of fan-out — `/wf` itself requires ≥3 subagents. There is NO path from an explicitly typed `/wf-max` to a solo main-thread pass.
-
-- **Trigger**: `/wf-max [task]`, or auto when write-set ≥5 files AND clear disjoint boundaries (parallelismScore ≥2.0)
-- **Auto-trigger degradation only** (never applies to explicit `/wf-max`): files <5, all changes share single interface (serial dependency), import/re-export refactor (global consistency needed), overhead >0.30
-- **Leaf conditions** (stop splitting): files ≤ span×2, avgLines <50, overhead >0.30
-
-## Hard Constraints
-
-1. **CEO never writes production code.** CEO uses Agent, Read, Grep/Glob. No Edit/Write/MultiEdit on source files. Exception: CEO MAY write to `Harness/tasks/<id>/PLAN.md` and `Harness/tasks/<id>/PROGRESS.md` (task artifacts, not production code).
-2. **E-GATE → D-GATE → W2.** Exploration Gate after W0 (all questions answered). Write Decomposition Gate after W1 architecture defines the write-set (Dispatch Table mandatory + Self-Audit Checklist).
-3. **Single-message dispatch.** ALL parallel Workers for a wave MUST be spawned in ONE message. Sequential one-per-turn spawning defeats parallelism (AP6).
-4. **Worker rule**: one write file per Worker (anti-bundling, Gate Rule #1). **Manager rule**: Manager count ≥ ceil(sqrt(write_files) / 3) (anti-under-decomposition, Gate Rule #2). Each Manager: 2-7 Workers (Gate Rule #3).
-5. **Manager MUST spawn ≥2 Workers or dissolve.** 0-1 Workers = Phantom Manager (AP5).
-6. **Overhead > 0.30 → degrade to /wf.** Record the decision in PLAN.md.
-
-## When to Ask the User (AskUserQuestion)
-
-CEO MUST use the `AskUserQuestion` tool when:
-
-- Intent ambiguous after exploration (≥2 valid interpretations)
-- Scope trade-off needs user decision (e.g. "full rewrite vs minimal fix")
-- Architecture direction has ≥2 viable approaches with different trade-offs
-- User gave vague request like "improve performance" or "clean up code"
-- D-GATE reveals >7 files — ask user to narrow scope
-
-Format: 2-4 options per question, `multiSelect: false` for exclusive choices. Each option must include a `description` explaining the trade-off. Example:
-
-```
-Q: "Auth refactor scope?"
-[1] "Minimal" — fix token validation only, 1 file
-[2] "Standard" — extract middleware + add tests, 3-5 files  
-[3] "Full" — new auth module with pluggable providers, 8-12 files
-```
-
-## Manager Synthesis (retry/escalation)
-
-```
-1. COLLECT → 2. DEDUPLICATE → 3. CONFLICT (flag, no silent resolve) → 4. SYNTHESIZE → 5. REPORT
-```
-Worker failure: retry 1× → on 2nd failure, Manager absorbs or escalates to CEO for replan.
-
-## Wave Order
-
-```
-W0 (Explore) → E-GATE → W1 (Architecture) → D-GATE → W2 (Implement, single-message) → W2R (Review) → W3+ (dependent waves) → INTEGRATION → CLOSEOUT
-```
-
-## Anti-Pattern Quick Check (before every wave)
-
-| AP | Pattern | Fix |
-|----|---------|-----|
-| AP1 | CEO-as-Worker | Re-delegate to Worker |
-| AP2 | Under-decomposition | Split files by concern |
-| AP3 | Serialization trap | Dispatch X and Y in parallel NOW |
-| AP4 | Fake parallelism | One file = one Writer |
-| AP5 | Phantom Manager | Dissolve, absorb by sibling |
-| AP6 | Sequential spawn | Batch ALL Task() in ONE message |
-| AP7 | Silent degrade | Record justification in PLAN.md |
-
-## Return Format
-
-- Dispatch Table (every wave, in PLAN.md)
-- Self-Audit Checklist (D-GATE, all items checked)
-- Worker returns (raw, per wave)
-- Manager synthesis reports
-- CEO integration decisions
-- Verification evidence
-- Agent count used vs minimum required (Manager_min audit)
+- Treat yourself as CEO, not implementer.
+- Do not edit production/source files directly while WF-MAX is active.
+- Use the D-GATE in `Harness/WF-MAX.md` before any implementation wave:
+  dispatch table, self-audit, disjoint file claims, and reviewer plan.
+- Use real subagents when the runtime supports them; otherwise record a
+  bounded-pass fallback in `Harness/tasks/<task-id>/PLAN.md`.
+- Keep `Harness/tasks/<task-id>/PROGRESS.md#Heartbeat` current.

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

@@ -1,49 +1,49 @@
----
-name: wf-readme
-description: Use when a project README already exists and the user asks to preserve, merge, modernize, optimize, or clarify repository documentation during harness install or documentation work.
----
-
-# README Optimizer
-
-Improve `README.md` without breaking project-owned public docs.
-
-## Load
-
-- root `README.md`
-- package files and scripts (`package.json`, `pyproject.toml`, `go.mod`, etc.)
-- CI files when present
-- `Harness/PROGRESS.md`
-- `Harness/tasks/<task-id>/PLAN.md` when available
-- `Harness/architecture.md` only when an architecture summary or diagram is requested
-
-## Mode
-
-Ask the user which mode they approve when the existing README is meaningful:
-
-| Mode | Use when | Allowed edit |
-| --- | --- | --- |
-| Preserve + append | default for existing projects | Add only a compact Development, Test, Build, Git, or Harness section |
-| Structure pass | README is stale, hard to scan, or missing operational docs | Reorganize with headings, tables, command blocks, and links while preserving facts |
-| Full rewrite | user explicitly wants a polished public README | Rewrite after approval; keep claims source-backed |
-
-If unanswered, use Preserve + append.
-
-## Rules
-
-- Preserve existing product, package, API, and public-facing content unless the user approves a rewrite.
-- Do not invent features, benchmarks, roadmap, support policy, badges, install commands, or CI status.
-- Use tables for command matrices, environment variables, endpoints, and deployment notes when facts are known.
-- Use Mermaid or ASCII architecture diagrams only when the structure is observed or approved; label uncertain diagrams as proposed.
-- Keep detailed architecture in `Harness/architecture.md`; README may link to it or show a short overview.
-- Keep agent rules in `CLAUDE.md`/`AGENTS.md`, not README.
-- Record the chosen mode and any skipped README improvements in `Harness/tasks/<task-id>/PLAN.md` when available.
-
-## Output
-
-Before broad edits, return:
-
-1. chosen mode
-2. sections to preserve
-3. sections to add or reorganize
-4. facts still unknown
-5. verification command or manual review step
+---
+name: wf-readme
+description: Use when a project README already exists and the user asks to preserve, merge, modernize, optimize, or clarify repository documentation during harness install or documentation work.
+---
+
+# README Optimizer
+
+Improve `README.md` without breaking project-owned public docs.
+
+## Load
+
+- root `README.md`
+- package files and scripts (`package.json`, `pyproject.toml`, `go.mod`, etc.)
+- CI files when present
+- `Harness/PROGRESS.md`
+- `Harness/tasks/<task-id>/PLAN.md` when available
+- `Harness/architecture.md` only when an architecture summary or diagram is requested
+
+## Mode
+
+Ask the user which mode they approve when the existing README is meaningful:
+
+| Mode | Use when | Allowed edit |
+| --- | --- | --- |
+| Preserve + append | default for existing projects | Add only a compact Development, Test, Build, Git, or Harness section |
+| Structure pass | README is stale, hard to scan, or missing operational docs | Reorganize with headings, tables, command blocks, and links while preserving facts |
+| Full rewrite | user explicitly wants a polished public README | Rewrite after approval; keep claims source-backed |
+
+If unanswered, use Preserve + append.
+
+## Rules
+
+- Preserve existing product, package, API, and public-facing content unless the user approves a rewrite.
+- Do not invent features, benchmarks, roadmap, support policy, badges, install commands, or CI status.
+- Use tables for command matrices, environment variables, endpoints, and deployment notes when facts are known.
+- Use Mermaid or ASCII architecture diagrams only when the structure is observed or approved; label uncertain diagrams as proposed.
+- Keep detailed architecture in `Harness/architecture.md`; README may link to it or show a short overview.
+- Keep agent rules in `CLAUDE.md`/`AGENTS.md`, not README.
+- Record the chosen mode and any skipped README improvements in `Harness/tasks/<task-id>/PLAN.md` when available.
+
+## Output
+
+Before broad edits, return:
+
+1. chosen mode
+2. sections to preserve
+3. sections to add or reorganize
+4. facts still unknown
+5. verification command or manual review step