create-harness-vibe-coding 0.7.2 → 0.8.1

package/templates/common/MEMORY.md

@@ -1,31 +1,32 @@
-# MEMORY.md - create-harness-vibe-coding Project Resource Index
-
-> The project fact source is reached via `CLAUDE.md -> Harness/README.md`. This file persists cross-session context: resource index, user preferences, tool usage standards.
-> Detailed memory lives in `Harness/memory/`. Keep entries short, newest first, and free of secrets.
-
-## Agents (Sub-agents)
-
-- [researcher](../.claude/agents/researcher.md) — product, market, open-source, dependency, pricing, policy, and ecosystem research.
-- [docs-researcher](../.claude/agents/docs-researcher.md) — official docs, API, SDK, config, limits, errors, and examples verification.
-- [planner](../.claude/agents/planner.md) — task split, dependencies, write sets, and dispatch table.
-- [architect](../.claude/agents/architect.md) — boundaries, ports, data-flow, and state impact.
-- [test-writer](../.claude/agents/test-writer.md) — failing tests or manual verification before implementation.
-- [implementer](../.claude/agents/implementer.md) — bounded implementation inside declared write set.
-- [debugger](../.claude/agents/debugger.md) — smallest fix for a reproduced failure.
-- [reviewer](../.claude/agents/reviewer.md) — read-only diff review and closeout risk.
-- [verifier](../.claude/agents/verifier.md) — verification commands and evidence.
-- [memory-master](../.claude/agents/memory-master.md) — memory writing, dedup, consolidation, and cross-project knowledge extraction.
-- [context-master](../.claude/agents/context-master.md) — context analysis, compression alerts, and session knowledge extraction for memory-master.
-- [explore-manager](../.claude/agents/explore-manager.md) — WF-MAX W0 exploration: spawn 5-10 read-only researchers, synthesize, report to CEO.
-- [architect-manager](../.claude/agents/architect-manager.md) — WF-MAX W1 architecture: spawn 3 architects, synthesize interface contracts, report to CEO.
-- [implement-manager](../.claude/agents/implement-manager.md) — WF-MAX W2 implementation: spawn 5-7 implementers (one file_claim each), merge, report to CEO.
-- [review-manager](../.claude/agents/review-manager.md) — WF-MAX W2R review: spawn 3-4 reviewers (spec/code/security/perf), deduplicate, classify severity, report to CEO.
-
-Stack-specific agents can be added after the product shape is known.
-
-## Skills (Workflows)
-
+# MEMORY.md - create-harness-vibe-coding Project Resource Index
+
+> The project fact source is reached via `CLAUDE.md -> Harness/README.md`. This file persists cross-session context: resource index, user preferences, tool usage standards.
+> Detailed memory lives in `Harness/memory/`. Keep entries short, newest first, and free of secrets.
+
+## Agents (Sub-agents)
+
+- [researcher](../.claude/agents/researcher.md) — product, market, open-source, dependency, pricing, policy, and ecosystem research.
+- [docs-researcher](../.claude/agents/docs-researcher.md) — official docs, API, SDK, config, limits, errors, and examples verification.
+- [planner](../.claude/agents/planner.md) — task split, dependencies, write sets, and dispatch table.
+- [architect](../.claude/agents/architect.md) — boundaries, ports, data-flow, and state impact.
+- [test-writer](../.claude/agents/test-writer.md) — failing tests or manual verification before implementation.
+- [implementer](../.claude/agents/implementer.md) — bounded implementation inside declared write set.
+- [debugger](../.claude/agents/debugger.md) — smallest fix for a reproduced failure.
+- [reviewer](../.claude/agents/reviewer.md) — read-only diff review and closeout risk.
+- [verifier](../.claude/agents/verifier.md) — verification commands and evidence.
+- [memory-master](../.claude/agents/memory-master.md) — memory writing, dedup, consolidation, and cross-project knowledge extraction.
+- [context-master](../.claude/agents/context-master.md) — context analysis, compression alerts, and session knowledge extraction for memory-master.
+- [explore-manager](../.claude/agents/explore-manager.md) — WF-MAX W0 exploration: spawn 5-10 read-only researchers, synthesize, report to CEO.
+- [architect-manager](../.claude/agents/architect-manager.md) — WF-MAX W1 architecture: spawn 3 architects, synthesize interface contracts, report to CEO.
+- [implement-manager](../.claude/agents/implement-manager.md) — WF-MAX W2 implementation: spawn 5-7 implementers (one file_claim each), merge, report to CEO.
+- [review-manager](../.claude/agents/review-manager.md) — WF-MAX W2R review: spawn 3-4 reviewers (spec/code/security/perf), deduplicate, classify severity, report to CEO.
+
+Stack-specific agents can be added after the product shape is known.
+
+## Skills (Workflows)
+
 - [WF Mode](WF.md) — long-task workflow: exploration, second plan, implementation, review, verification, heartbeat, and recovery loop.
+- [wf](../.claude/skills/wf/SKILL.md) — Claude Code WF skill command; mirrored for Codex at `../.agents/skills/wf/SKILL.md`.
 - [subagent-orchestrator](../.claude/skills/subagent-orchestrator/SKILL.md) — controller-led subagent orchestration, parallel read-only passes, review gates, and recovery handoffs.
 - [wf-readme](../.claude/skills/wf-readme/SKILL.md) — README preservation, append-only development sections, structured tables, and approved architecture diagrams.
 - [wf-review](../.claude/skills/wf-review/SKILL.md) — cross-model peer review: invoke the other agent CLI (Codex/Claude) for independent review.
@@ -33,43 +34,44 @@ Stack-specific agents can be added after the product shape is known.
 - [wf-learn](../.claude/skills/wf-learn/SKILL.md) — force memory learning cycle: context-master -> memory-master -> project + global memory.
 - [wf-max](../.claude/skills/wf-max/SKILL.md) — maximum-parallelism workflow: write-set coloring, wave dispatch, parallel review per dimension.
 	- [wf-remove](../.claude/skills/wf-remove/SKILL.md) — Safely remove Harness framework files (SAFE/MODIFIED/USER classes), auto-prune empty directories, backup option.
-- learn: /wf-learn
-
-Stack-specific skills can be added after the product shape is known.
-
-## Rules (Harness Constraints)
-
-Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
-
-- [common.md](../.claude/rules/ecc/common.md) — universal harness constraints for context loading, verification, subagents, and security (alwaysApply: true)
-- Language-specific rules pending Claude Code initialization (e.g. python.md, typescript.md, etc.)
-
-## Harness (Runtime)
-
-- [Docs router](README.md)
-- [WF mode](WF.md)
-- [WF Max mode](WF-MAX.md)
-- [0-1 lifecycle](lifecycle.md)
-- [Research protocol](research/README.md)
-- [Context loading protocol](context-loading.md)
-- [Dispatch protocol](dispatch.md)
-- [Subagent orchestration](subagents.md)
-- [Extension contract](extension.md)
-- [Architecture docs](architecture.md)
-- [Agent workflow](agent-workflow.md)
-- [Harness validator](scripts/validate-harness.mjs)
-- [Version file](.harness-version)
-
-## Memory Folder
-
-- [Tool usage/reflections](memory/tool-usage-reflections.md) - repeated tool failures, better command patterns, environment-specific fixes.
-- [User corrections/preferences](memory/user-corrections-preferences.md) - repeated user corrections, durable preferences, common-sense course corrections.
-- [Agent lessons/patterns](memory/agent-lessons-patterns.md) - reusable lessons from review, debugging, validation, and handoff loops.
-
-Write to the memory folder when the guidance should survive chat context loss:
 
-- Use `memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times, a better command pattern is found, or an environment-specific fix should be reused.
-- Use `memory/user-corrections-preferences.md` when the user explicitly asks to remember a preference, or the user corrects the same assumption/pattern 2+ times.
-- Use `memory/agent-lessons-patterns.md` when a review/debug loop yields a reusable lesson or regression guard.
-- Use this file for the resource index and routing pointers, not long-form lessons.
-- Never record secrets, credentials, tokens, or private data. If a memory is ambiguous, ask before writing.
+Codex repo-skill mirrors live under `../.agents/skills/` with the same skill names.
+
+Stack-specific skills can be added after the product shape is known.
+
+## Rules (Harness Constraints)
+
+Located under `.claude/rules/ecc/`, auto-loaded by the CC engine:
+
+- [common.md](../.claude/rules/ecc/common.md) — universal harness constraints for context loading, verification, subagents, and security (alwaysApply: true)
+- Language-specific rules pending Claude Code initialization (e.g. python.md, typescript.md, etc.)
+
+## Harness (Runtime)
+
+- [Docs router](README.md)
+- [WF mode](WF.md)
+- [WF Max mode](WF-MAX.md)
+- [0-1 lifecycle](lifecycle.md)
+- [Research protocol](research/README.md)
+- [Context loading protocol](context-loading.md)
+- [Dispatch protocol](dispatch.md)
+- [Subagent orchestration](subagents.md)
+- [Extension contract](extension.md)
+- [Architecture docs](architecture.md)
+- [Agent workflow](agent-workflow.md)
+- [Harness validator](scripts/validate-harness.mjs)
+- [Version file](.harness-version)
+
+## Memory Folder
+
+- [Tool usage/reflections](memory/tool-usage-reflections.md) - repeated tool failures, better command patterns, environment-specific fixes.
+- [User corrections/preferences](memory/user-corrections-preferences.md) - repeated user corrections, durable preferences, common-sense course corrections.
+- [Agent lessons/patterns](memory/agent-lessons-patterns.md) - reusable lessons from review, debugging, validation, and handoff loops.
+
+Write to the memory folder when the guidance should survive chat context loss:
+
+- Use `memory/tool-usage-reflections.md` when the same tool/use pattern fails 3+ times, a better command pattern is found, or an environment-specific fix should be reused.
+- Use `memory/user-corrections-preferences.md` when the user explicitly asks to remember a preference, or the user corrects the same assumption/pattern 2+ times.
+- Use `memory/agent-lessons-patterns.md` when a review/debug loop yields a reusable lesson or regression guard.
+- Use this file for the resource index and routing pointers, not long-form lessons.
+- Never record secrets, credentials, tokens, or private data. If a memory is ambiguous, ask before writing.

package/templates/common/README.md

@@ -1,41 +1,48 @@
-# {{projectName}}
-
-Project development notes belong here.
-
-## Development Commands
-
-Record the real project commands after bootstrap:
-
-```bash
-# Install dependencies
-# e.g. npm install
-
-# Run locally
-# e.g. npm run dev
-
-# Run tests
-# e.g. npm test
-
-# Build
-# e.g. npm run build
-```
-
-Replace the examples with the real commands discovered from this project. If a command is unknown, record the open question in `Harness/tasks/<task-id>/PROGRESS.md`.
-
-## Git And Release Notes
-
-- Keep branch, commit, pull request, CI, and release conventions in this README.
-- Do not place build scripts, git policy, or project maintenance instructions in `CLAUDE.md`.
-- Keep code architecture notes in `Harness/architecture.md` or feature docs.
-- For README improvements, use `.claude/skills/wf-readme/SKILL.md`; preserve public docs unless a rewrite is approved.
-
+# {{projectName}}
+
+Project development notes belong here.
+
+## Development Commands
+
+Record the real project commands after bootstrap:
+
+```bash
+# Install dependencies
+# e.g. npm install
+
+# Run locally
+# e.g. npm run dev
+
+# Run tests
+# e.g. npm test
+
+# Build
+# e.g. npm run build
+```
+
+Replace the examples with the real commands discovered from this project. If a command is unknown, record the open question in `Harness/tasks/<task-id>/PROGRESS.md`.
+
+## Git And Release Notes
+
+- Keep branch, commit, pull request, CI, and release conventions in this README.
+- Do not place build scripts, git policy, or project maintenance instructions in `CLAUDE.md`.
+- Keep code architecture notes in `Harness/architecture.md` or feature docs.
+- For README improvements, use `.claude/skills/wf-readme/SKILL.md`; preserve public docs unless a rewrite is approved.
+
 ## Harness
 
 The agentic engineering harness lives in `Harness/`.
-
-- Follow `Harness/SETUP.md` before normal work while it exists.
-- Start at `Harness/README.md`.
-- Load memory and resource registrations from `Harness/MEMORY.md`.
-- Track active work in `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md`.
-- Use `Harness/WF.md` or `/wf` for long, difficult, multi-agent work.
+
+- Follow `Harness/SETUP.md` before normal work while it exists.
+- Start at `Harness/README.md`.
+- Load memory and resource registrations from `Harness/MEMORY.md`.
+- Track active work in `Harness/PROGRESS.md` and `Harness/tasks/<task-id>/PROGRESS.md`.
+- Use `Harness/WF.md` for long, difficult, multi-agent work.
+  - Claude Code: invoke the `wf` skill with `/wf`.
+  - Codex: invoke the `wf` skill with `$wf` or `/skills`.
 - Use `Harness/subagents.md` when coordinating multiple agents.
+
+Tool discovery files stay at the repository root:
+
+- Claude Code: `.claude/settings.json`, `.claude/agents/`, and `.claude/skills/`.
+- Codex: `.agents/skills/` for repo skills and `.codex/hooks.json` for hook/config integration.

package/templates/common/SETUP.md

@@ -13,15 +13,15 @@ This scaffold is a 0-1 product harness:
 - `Harness/MEMORY.md` plus a `Harness/memory/` folder for durable self-learning, user corrections, and tool reflections
 - built-in common agents
 - subagent orchestration and context-loading protocol
-- skill-style dynamic loaders in `.claude/skills/`
+- skill-style dynamic loaders in `.claude/skills/` for Claude Code and `.agents/skills/` for Codex
 - lightweight harness validator
 - test/review/feedback loop
 
-It does not guess your stack or business domain. Claude Code should fill those through the lifecycle.
+It does not guess your stack or business domain. Claude Code or Codex should fill those through the lifecycle.
 
 ## Bootstrap Prompt
 
-Start Claude Code, then say:
+Start Claude Code or Codex, then say:
 
 ```text
 Read Harness/SETUP.md. Bootstrap this project as a 0-1 product harness.
@@ -44,29 +44,42 @@ Claude must follow this order:
 10. Run `node Harness/scripts/validate-harness.mjs --strict`.
 11. Record final verification and next feedback step in `Harness/tasks/<task-id>/PROGRESS.md`. If repeated tool failures, repeated user corrections, or reusable review/debug lessons appeared, record the concise reflection in the relevant `Harness/memory/` file.
 
-## Existing Project Bootstrap Sequence
-
-When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
-
-1. Scan existing project facts first: `README.md`, package files (`package.json`, `pyproject.toml`, `go.mod`, etc.), test commands, app entry points, CI files, existing docs, and current run/build scripts.
-2. Record discovered facts and open questions in `Harness/tasks/<task-id>/PROGRESS.md` before changing harness docs.
-3. Fill `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md` from observed project facts plus explicit user input.
-4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.gitignore`, settings, hooks, package files, CI, docs routers, or workflow docs unless the user explicitly approves that exact overwrite.
-5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/extension.md`.
-6. Run `node Harness/scripts/validate-harness.mjs` after registration, then run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders have been resolved or intentionally recorded as open.
+## Install or Upgrade Path
+
+Before writing, identify the project state:
+
+| Project state | Required action |
+| --- | --- |
+| Empty or new project | Run the scaffold, then follow this file for 0-1 bootstrap |
+| Existing project, no `Harness/` | Scan project facts first, run `--dry-run`, preserve existing files, merge only missing Harness guidance |
+| Legacy architecture or older project docs | Treat existing code/docs as source of truth, dry-run first, then fill PRD, research, architecture, and task plans from observed facts |
+| Existing `Harness/` | Do not use `npx` as an updater; ask whether to run `/wf-update`, `$wf-update`, `node Harness/scripts/wf-update-check.mjs`, keep untouched, or remove/reinstall after approval |
+
+When adding this harness to a project that already has source code, docs, CI, or tool configuration, treat the existing project as the source of truth before filling harness docs.
+
+1. Scan existing project facts first: top-level files, `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `Harness/`, `README.md`, package files (`package.json`, `pyproject.toml`, `go.mod`, etc.), test commands, app entry points, CI files, existing docs, current run/build scripts, and already-installed skills/plugins/rules.
+2. Record discovered facts and open questions in `Harness/tasks/<task-id>/PROGRESS.md` before changing harness docs.
+3. Fill `Harness/research/PRD.md`, `Harness/research/research-results.md`, `Harness/architecture.md` from observed project facts plus explicit user input.
+4. Existing configuration is project fact. Do not overwrite `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, `.gitignore`, settings, hooks, package files, CI, docs routers, workflow docs, or installed skills/plugins/rules unless the user explicitly approves that exact overwrite.
+5. When a harness file conflicts with an existing file, preserve the existing file and register any missing harness guidance manually using `Harness/extension.md`.
+6. Run `node Harness/scripts/validate-harness.mjs` after registration, then run `node Harness/scripts/validate-harness.mjs --strict` only after project-fact placeholders have been resolved or intentionally recorded as open.
+
+`npx create-harness-vibe-coding` is an install/safe-merge entry, not an update engine for a project that already has an installed Harness. If `Harness/` already exists, use `/wf-update`, `$wf-update`, or `node Harness/scripts/wf-update-check.mjs`; root entry files and user-modified Harness docs require agent-mediated merge decisions.
 
 ### Agent-Link Install Intake
 
-When the user installs by pasting the GitHub link into an agent, ask intake questions before editing. Ask only questions that affect writes, architecture, security, or workflow. Ask at most three blocking questions up front, record safe defaults for the rest, and ask follow-ups only when that choice becomes active.
-
-| Topic | Ask When | Default If Unanswered |
-| --- | --- | --- |
-| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
-| Harness location | `docs/` is already used for GitHub Pages, product docs, or generated docs | Use root `Harness/`; do not write harness docs into `docs/` |
-| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
-| README optimization | existing README is stale, sparse, missing command tables, or the user asks for diagrams/polished docs | Offer `wf-readme`; default to append-only Development notes until the user approves a structure pass or full rewrite |
-| Extensions | ECC, Superpowers, custom rules, or stack-specific skills may be useful | Recommend first; install only after user approval |
-| Skills | stack is known and optional skills could improve testing, frontend, backend, review, or browser evidence | Install 1-2 relevant skills only after user approval |
+When the user installs by pasting the GitHub link into an agent, scan the project root before editing or asking generic questions. Summarize what exists, then ask only questions that affect writes, architecture, security, or workflow. Ask at most three blocking questions up front, record safe defaults for the rest, and ask follow-ups only when that choice becomes active.
+
+| Topic | Ask When | Default If Unanswered |
+| --- | --- | --- |
+| Root agent entry | `CLAUDE.md`, `AGENTS.md`, `.claude/`, `.agents/`, `.codex/`, or other agent entry files already exist | Preserve files; ask before merging the Harness entry contract |
+| Existing Harness | `Harness/` already exists | Stop and ask whether to run `/wf-update`, dry-run merge missing files, keep it untouched, or remove/reinstall after approval |
+| Harness location | Always | Use root `Harness/`; do not write harness docs into `docs/` |
+| README ownership | root `README.md` is a public product page, package docs, or heavily customized | Preserve existing README and propose a minimal Development section |
+| README optimization | existing README is stale, sparse, missing command tables, or the user asks for diagrams/polished docs | Offer `wf-readme`; default to append-only Development notes until the user approves a structure pass or full rewrite |
+| Extensions | ECC, custom rules, or stack-specific skills may be useful | Scan installed skills/plugins/rules first; recommend only missing capabilities; install only after user approval |
+| Optional capabilities | stack is known or the user wants setup guidance | Offer local workflows plus recommendation-only GitHub links: Superpowers, Caveman, agent research, and code graph; do not duplicate already-installed capabilities |
+| Skills | stack is known and optional skills could improve testing, frontend, backend, review, or browser evidence | Install 1-2 relevant local workflows only after user approval |
 | CI/CD | CI config exists or the project lacks a test/build gate | Document existing commands first; add CI/CD only after user approval |
 | Verification depth | browser-visible, API, database, auth, payment, or deployment behavior is affected | Require real command evidence; require browser/API evidence when relevant |
 | Memory/privacy | repo contains sensitive domain data, customer data, secrets, or private workflows | Enable memory index only; never record secrets or private data |
@@ -113,10 +126,10 @@ The harness validator checks for specific structural invariants. When comparing
 | `CLAUDE.md` | Must be merged only after user confirmation when it already exists. Required contract: `## 1. Harness Binding & Startup` with the `Harness/SETUP.md` bootstrap contract line; `## 6. Memory & Self-Learning` section; the tool reflection trigger text (`same tool/use pattern fails 3+ times`); the user correction trigger text (`user corrects the same assumption/pattern 2+ times`); `Never bulk-read Harness/` in Startup |
 | `AGENTS.md` | Root agent entry points to `CLAUDE.md` and `Harness/README.md`; for existing projects, merge only after explicit user consent |
 | `README.md` | Existing README is project-owned. Preserve by default; ask whether to append only Development notes or run `wf-readme` 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 |
+| `Harness/MEMORY.md` | All 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: "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; `collaboration decision tree`; `Heartbeat Protocol` |
+| `Harness/WF.md` | `WF mode requires multi-subagent orchestration by default`; explicit `/wf`, `$wf`, `wf mode`, `workflow mode`, or `wk mode` requires at least 3 distinct role passes before second planning; `collaboration decision tree`; `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) |
@@ -125,7 +138,7 @@ The harness validator checks for specific structural invariants. When comparing
 | `Harness/PROGRESS.md` | global task index with Active Task and task history; cross-task decisions |
 | `Harness/tasks/<id>/PROGRESS.md` | `## Current Goal`, `## Phase`, `## Heartbeat`, `## Loaded Context` headings |
 | `Harness/tasks/<id>/PLAN.md` | `## 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/SETUP.md` | Temporary install/bootstrap guide for new projects, existing projects, legacy upgrades, and Harness update decisions. If kept, ensure "Install or Upgrade Path" 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 |
 | `Harness/workflows/ts-react-frontend.md` (if installed as optional) | Same UI selector contract as above |
 
@@ -133,7 +146,7 @@ The harness validator checks for specific structural invariants. When comparing
 
 - `Harness/memory/tool-usage-reflections.md`, `Harness/memory/user-corrections-preferences.md`, `Harness/memory/agent-lessons-patterns.md` — these are new empty files
 - `.claude/agents/*.md` — all 9 common agents
-- `.claude/skills/wf-update/SKILL.md` and `.claude/skills/subagent-orchestrator/SKILL.md` — core harness skills and subagent orchestration
+- `.claude/skills/*.md` and mirrored `.agents/skills/*.md` — Claude Code and Codex skill adapters over the same Harness docs
 - `.claude/rules/ecc/common.md` — universal rules (unless the project has custom rules in this file)
 - `.claude/settings.json` — harness settings
 - `Harness/WF.md`, `Harness/lifecycle.md`, `Harness/subagents.md`, `Harness/agent-workflow.md`, `Harness/architecture.md` — harness runtime docs
@@ -141,12 +154,15 @@ The harness validator checks for specific structural invariants. When comparing
 - `AGENTS.md` — agent registry; if it already exists, ask for user consent before merging or replacing it
 - `Harness/scripts/validate-harness.mjs` and `tests/.gitkeep` — tooling
 
-Optional workflow examples:
-
-```bash
-npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
-npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
-```
+Optional workflow examples:
+
+```bash
+npx create-harness-vibe-coding@latest my-app ./my-app -y --with browser-e2e,ts-react-frontend
+npx create-harness-vibe-coding@latest my-app ./my-app -y --preset web-app
+npx create-harness-vibe-coding@latest my-app ./my-app -y --recommend superpowers,codegraph
+```
+
+`--recommend` records recommendation-only external capability links in this file. It does not install third-party skills or plugins.
 
 ### Template Fill Guide
 
@@ -193,7 +209,7 @@ False confidence is worse than a question. If you catch yourself thinking "this
 
 ## How to Find Proper Skills
 
-After the architecture stage reveals your stack, install matching agent skills. Skills teach Claude Code domain-specific patterns, testing conventions, and design rules.
+After the architecture stage reveals your stack, inspect existing `.claude/skills/`, `.agents/skills/`, plugins, hooks, and custom rules before recommending anything. Skills teach Claude Code and Codex domain-specific patterns, testing conventions, and design rules, but duplicate skills create routing noise.
 
 **Built-in route**: invoke the `/find-skills` skill (or say "help me find skills for X"). Examples:
 
@@ -204,28 +220,32 @@ After the architecture stage reveals your stack, install matching agent skills.
 "I need a skill for PostgreSQL schema design."
 ```
 
-**Superpowers**: [Superpowers](https://github.com/obra/superpowers) is a community skill registry. Search it:
-
-```bash
-# If superpowers CLI or MCP is configured
-npx skills search "react testing"
-npx skills search "python api"
-```
+**External recommendation links**:
+
+| Recommendation | Source | Purpose |
+| --- | --- | --- |
+| Superpowers | <https://github.com/obra/Superpowers> | community skill registry and agent workflows |
+| Caveman | <https://github.com/JuliusBrussee/caveman> | terse, low-token agent behavior and memory compression |
+| Agent Research | <https://github.com/lingzhi227/agent-research-skills> | research-agent skills for literature, product, dependency, and ecosystem investigation |
+| CodeGraph | <https://github.com/colbymchenry/codegraph> | code graph or repository-map tooling |
+
+These are links for the user's agent to evaluate. This scaffold does not maintain third-party install steps. If a user selects one, first check whether an equivalent capability is already installed; then present the GitHub link and ask for approval before the user's agent follows that project's own README.
 
 **Manual discovery**: search GitHub and npm directly using patterns from `Harness/research/README.md#Architecture Decision References`.
 
 **Priority order**:
-1. `/find-skills` first — fastest discovery, respects your tool environment.
-2. Superpowers registry — broad community coverage.
-3. GitHub search — when the first two miss niche domains.
+1. Existing project skills/plugins/rules first - do not recommend duplicates.
+2. `/find-skills` or the runtime's local skill discovery - fastest and respects the user's tool environment.
+3. Selected external GitHub links - let the user's agent read that project's README and install only after approval.
+4. GitHub search - when the first three miss niche domains.
 
-**What to install**: after finding skills, add them to `.claude/skills/<name>/SKILL.md`. Follow `Harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
+**What to install**: after finding skills, add the canonical copy to `.claude/skills/<name>/SKILL.md` and mirror the same file to `.agents/skills/<name>/SKILL.md` when Codex should discover it. Follow `Harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
 
-This scaffold includes built-in harness skills (`.claude/skills/harness-*`). Keep those. Add stack-specific ones alongside them.
+This scaffold includes built-in harness skills in `.claude/skills/*` and mirrored Codex repo skills in `.agents/skills/*`. Keep those. Add stack-specific ones alongside them.
 
 ## Optional Agent Assets
 
-After the product shape is known, Claude may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Follow `Harness/extension.md` for every added asset.
+After the product shape is known, Claude Code may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Codex-discoverable workflow skills belong in `.agents/skills/`. Follow `Harness/extension.md` for every added asset.
 
 Examples:
 

package/templates/common/memory/agent-lessons-patterns.md

@@ -1,21 +1,21 @@
-# Agent Lessons And Patterns
-
-Purpose: record reusable lessons from review, debugging, validation, and handoff loops.
-
-Write here when:
-- A review/debug loop reveals a reusable prevention pattern.
-- A validation failure exposes a missing regression check.
-- A handoff, dispatch, or context-loading pattern should be repeated or avoided.
-
-Entry format, newest first:
-
-```markdown
-## YYYY-MM-DD - Short Lesson Name
-
-- Lesson: the reusable pattern.
-- Source: review finding, debug loop, failed verification, or handoff.
-- Apply when: the task shape or files where this matters.
-- Regression guard: test, validator check, docs update, or manual evidence to keep it from recurring.
-```
-
-Keep entries lightweight and actionable. Avoid secrets and speculative lessons.
+# Agent Lessons And Patterns
+
+Purpose: record reusable lessons from review, debugging, validation, and handoff loops.
+
+Write here when:
+- A review/debug loop reveals a reusable prevention pattern.
+- A validation failure exposes a missing regression check.
+- A handoff, dispatch, or context-loading pattern should be repeated or avoided.
+
+Entry format, newest first:
+
+```markdown
+## YYYY-MM-DD - Short Lesson Name
+
+- Lesson: the reusable pattern.
+- Source: review finding, debug loop, failed verification, or handoff.
+- Apply when: the task shape or files where this matters.
+- Regression guard: test, validator check, docs update, or manual evidence to keep it from recurring.
+```
+
+Keep entries lightweight and actionable. Avoid secrets and speculative lessons.

package/templates/common/memory/tool-usage-reflections.md

@@ -1,21 +1,21 @@
-# Tool Usage Reflections
-
-Purpose: record repeated tool failures, better command patterns, and environment-specific fixes.
-
-Write here when:
-- The same tool/use pattern fails 3+ times in one task or across repeated tasks.
-- A more reliable command pattern replaces a brittle one.
-- The environment needs a durable fix, flag, path rule, shell syntax, or startup sequence.
-
-Entry format, newest first:
-
-```markdown
-## YYYY-MM-DD - Short Pattern Name
-
-- Trigger: what failed or repeated.
-- Better pattern: the command, tool usage, or sequence to use next time.
-- Evidence: command output summary, error text, or affected environment.
-- Scope: when this applies and when it does not.
-```
-
-Keep entries concise. Do not record secrets, credentials, private tokens, or one-off noise.
+# Tool Usage Reflections
+
+Purpose: record repeated tool failures, better command patterns, and environment-specific fixes.
+
+Write here when:
+- The same tool/use pattern fails 3+ times in one task or across repeated tasks.
+- A more reliable command pattern replaces a brittle one.
+- The environment needs a durable fix, flag, path rule, shell syntax, or startup sequence.
+
+Entry format, newest first:
+
+```markdown
+## YYYY-MM-DD - Short Pattern Name
+
+- Trigger: what failed or repeated.
+- Better pattern: the command, tool usage, or sequence to use next time.
+- Evidence: command output summary, error text, or affected environment.
+- Scope: when this applies and when it does not.
+```
+
+Keep entries concise. Do not record secrets, credentials, private tokens, or one-off noise.

package/templates/common/memory/user-corrections-preferences.md

@@ -1,21 +1,21 @@
-# User Corrections And Preferences
-
-Purpose: record repeated user corrections, durable preferences, and common-sense course corrections.
-
-Write here when:
-- The user says "remember", "never", "next time", "always", or "I prefer".
-- The user corrects the same assumption/pattern 2+ times.
-- A correction changes how future work should be scoped, explained, verified, or handed off.
-
-Entry format, newest first:
-
-```markdown
-## YYYY-MM-DD - Short Preference Name
-
-- Correction/preference: the durable instruction.
-- Trigger: what prompted the correction.
-- Apply when: future contexts where this should guide behavior.
-- Avoid: contexts where this should not be over-applied.
-```
-
-Do not record ordinary chat. If the preference is ambiguous, ask before writing it. Never store secrets.
+# User Corrections And Preferences
+
+Purpose: record repeated user corrections, durable preferences, and common-sense course corrections.
+
+Write here when:
+- The user says "remember", "never", "next time", "always", or "I prefer".
+- The user corrects the same assumption/pattern 2+ times.
+- A correction changes how future work should be scoped, explained, verified, or handed off.
+
+Entry format, newest first:
+
+```markdown
+## YYYY-MM-DD - Short Preference Name
+
+- Correction/preference: the durable instruction.
+- Trigger: what prompted the correction.
+- Apply when: future contexts where this should guide behavior.
+- Avoid: contexts where this should not be over-applied.
+```
+
+Do not record ordinary chat. If the preference is ambiguous, ask before writing it. Never store secrets.