create-harness-vibe-coding 0.1.9 → 0.2.0

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

@@ -0,0 +1,36 @@
+---
+name: subagent-orchestrator
+description: Use when work needs bounded subagent coordination, parallel read-only exploration, independent review gates, broad context partitioning, or controlled handoffs after wf-mode has been selected when applicable.
+---
+
+# Subagent Orchestrator
+
+Load:
+
+- `Harness/subagents.md`
+- `Harness/dispatch.md`
+- `Harness/context-loading.md`
+- `Harness/PLAN.md`
+- `Harness/agent-workflow.md`
+- `Harness/WF.md` when in `/wf`, wf mode, or recovery loop
+
+Follow:
+
+- The main agent is the controller. It decomposes work, writes `Harness/PLAN.md`, integrates returns, and owns final verification.
+- Use the efficiency ladder in `Harness/subagents.md`: solo pass -> single reviewer -> parallel read-only -> serial build lane -> isolated lanes.
+- 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/PLAN.md#Parallel Dispatch`; update `Harness/PLAN.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

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

@@ -0,0 +1,48 @@
+---
+name: wf-mode
+description: Use for /wf, wf mode, workflow mode, long difficult tasks, multi-file or multi-agent work, low-confidence decisions, repeated failures, migrations, architecture-heavy changes, browser-visible work, or any task that needs exploration -> second plan -> implementation -> review -> verification -> recovery.
+---
+
+# WF Mode
+
+Load:
+
+- `Harness/WF.md`
+- `Harness/PLAN.md`
+- `Harness/agent-workflow.md` when implementation, review, or verification starts
+- `Harness/subagents.md`, `Harness/dispatch.md`, and `Harness/context-loading.md` only when coordinating subagents or bounded role passes
+- current feature doc when one exists
+- `Harness/workflows/browser-e2e.md` when browser-visible behavior is affected and the workflow is installed
+
+Follow:
+
+```text
+intake + 95% confidence gate
+-> parallel read-only exploration
+-> synthesis and second plan
+-> failing test or manual check
+-> bounded implementation
+-> review
+-> verification
+-> debugger recovery loop when verification fails
+-> close with evidence
+```
+
+Rules:
+
+- Update `Harness/PLAN.md#Heartbeat` before long commands, after failures, before handoff, and at closeout.
+- Use `subagent-orchestrator` and `Harness/subagents.md` when the task has broad reading, cross-layer impact, independent review needs, or repeated failures.
+- If subagents are unavailable, emulate the same roles as separate bounded passes.
+- Do not claim browser/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
+- If `Harness/workflows/browser-e2e.md` is not installed, use `Harness/WF.md#Browser And API Evidence` as the fallback evidence contract or ask the user before adding the optional workflow.
+- If the same failure class happens three times, stop blind fixes and ask the user with evidence-backed options.
+
+Return:
+
+- changed files
+- agents or bounded passes used
+- commands run
+- browser/API evidence when applicable
+- review findings
+- remaining risks
+- updated heartbeat status

package/templates/common/AGENTS.md

@@ -2,6 +2,6 @@
 
 Entry point for coding agents.
 
-Read `CLAUDE.md` first, then `docs/README.md`.
+Read `CLAUDE.md` first and follow its startup sequence: `Harness/MEMORY.md`, then `Harness/README.md`.
 
-Do not bulk-read `docs/`. Let `docs/README.md` route you to the smallest useful context.
+Do not bulk-read `Harness/`. Let `Harness/README.md` route you to the smallest useful context.

package/templates/common/CLAUDE.md

@@ -1,91 +1,59 @@
 # CLAUDE.md
 
-## 1. Startup
-
-- Every session: read `MEMORY.md`, then `docs/README.md`.
-- If `SETUP.md` exists in the project root, read it first.
-- All routing, role-based reading, and per-task doc loads live in `docs/README.md`. Not here.
-- If work spans more than one step, update `docs/harness/PLAN.md`.
+Root entry for Claude Code. Keep this file short.
+
+## 1. Harness Binding & Startup
+
+- If `Harness/` exists, this repository is governed by the Harness contract. Treat these files as mandatory operating instructions, not optional references.
+- Every session: load `Harness/MEMORY.md` first, then `Harness/README.md`.
+- If `Harness/SETUP.md` exists, follow it before normal project work; it is the install/bootstrap contract and may be deleted only after setup is complete.
+- `Harness/MEMORY.md` is the memory/resource router: agents, skills, durable memories, and cross-session lessons. Follow its registrations when selecting agents/skills or recording memory.
+- `Harness/README.md` is the task router. For every request, check `Harness/README.md#Load By Task`; if a row matches, read and follow those docs before acting.
+- If work spans more than one step, update `Harness/PLAN.md`.
+- Use `/wf`, `wf-mode`, or `Harness/WF.md` for long, difficult, uncertain, multi-file, or repeated-failure work.
+- Use `subagent-orchestrator` and `Harness/subagents.md` when coordinating multiple subagents.
 - Universal rules live in `.claude/rules/ecc/common.md`.
-- Never bulk-read `docs/`.
-
----
-
-Behavioral guidelines to reduce common LLM coding mistakes. For trivial tasks, use judgment. These bias toward caution over speed.
+- Never bulk-read `Harness/`; route through `Harness/README.md` and `Harness/MEMORY.md`.
 
 ## 2. Think Before Coding
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-### 2.1 Confidence Threshold (Non-Negotiable)
-
-- You must have **≥95% confidence** in user intent before writing implementation code.
-- If confidence is below 95%, stop and ask. False confidence is worse than a question.
-- **Maximum 3 blocking questions per decision point.** Ask the highest-impact questions first.
-- If you catch yourself thinking *"this is probably what they want"* — that is a mandatory stop condition. Ask.
-- **Silent picks are forbidden.** When two valid approaches exist and you cannot decide with 95% confidence, present both trade-offs to the user.
-- Record every assumption explicitly in `docs/harness/PLAN.md` so the user can correct it.
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
+- You must have **>=95% confidence** in user intent before writing implementation code.
+- If confidence is below 95%, stop and ask up to 3 blocking questions.
+- If multiple valid approaches exist and the choice affects architecture, scope, stack, or user-facing behavior, present trade-offs instead of picking silently.
+- State assumptions before implementation and record durable assumptions, decisions, blockers, handoffs, and verification evidence in `Harness/PLAN.md`.
+- If something is unclear, stop. Name what is unclear and ask instead of guessing.
 
 ## 3. Simplicity First
 
-**Minimum code that solves the problem. Nothing speculative.**
-
 - No features beyond what was asked.
 - No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+- No unrequested flexibility, configurability, or speculative error handling.
+- If a simpler approach exists, say so and prefer the smallest change that satisfies the request.
+- If the solution is growing faster than the problem, reduce scope before coding more.
 
 ## 4. Surgical Changes
 
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
+- Touch only files and lines required by the task.
+- Do not improve adjacent code, comments, formatting, or architecture unless it is required for the task.
+- Match existing style even when you would choose a different style in a new project.
+- Clean up imports, variables, functions, and files made unused by your own changes; do not delete pre-existing dead code unless asked.
+- Keep every changed line traceable to the user's request.
 
 ## 5. Goal-Driven Execution
 
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
----
-
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
-
----
+- Define verifiable success criteria before implementation.
+- For bugs, reproduce the failure or document why reproduction is impossible before fixing.
+- For multi-step work, keep `Harness/PLAN.md` current with loaded context, task state, assumptions, and verification.
+- Every task needs a test, build check, validator run, or recorded manual check.
+- Do not claim web/UI acceptance without real-browser evidence from Chrome DevTools, CDP, Playwright, or documented manual browser checks.
+- Do not place project build scripts, git conventions, run commands, or release process in this file. Put them in `README.md`.
+- Do not place code architecture here. Put architecture in `Harness/architecture.md` or the current feature doc.
+- If this file has accumulated unrelated project notes, pause and propose moving them to the right place: `README.md` for development operations, `Harness/architecture.md` for architecture, `Harness/WF.md` or `Harness/workflows/` for workflow rules.
 
 ## 6. Memory & Self-Learning
 
-- **User memory**: triggers "remember", "never", "next time", "always", "I prefer" — persist newest-first under `MEMORY.md#User Mem`. Don't record ordinary chat. Ambiguous? Ask.
-- **Tool memory**: auto-record under `MEMORY.md#Tool Usage Standards` when a tool/pattern fails 3+ times or a better alternative is found. Update old entries, don't duplicate. Never record secrets.
-- Format details live in `MEMORY.md`, not here.
+- `Harness/MEMORY.md` is the resource index. Detailed durable memory lives in `Harness/memory/`.
+- **Tool reflection trigger**: record a lightweight reflection when the same tool/use pattern fails 3+ times, or when a better command pattern/environment fix is found. Write it newest-first in `Harness/memory/tool-usage-reflections.md`.
+- **User correction trigger**: record a lightweight preference/correction when the user asks to remember it, or when the user corrects the same assumption/pattern 2+ times. Write it newest-first in `Harness/memory/user-corrections-preferences.md`.
+- **Agent lesson trigger**: record reusable lessons from review/debug loops in `Harness/memory/agent-lessons-patterns.md` when they would prevent recurrence.
+- Never record secrets, credentials, tokens, or private data.

package/templates/common/MEMORY.md

@@ -1,28 +1,32 @@
-# MEMORY.md — {{projectName}} Project Resource Index
+# MEMORY.md - {{projectName}} Project Resource Index
 
-> The project fact source is reached via `CLAUDE.md -> docs/README.md`. This file persists cross-session context: resource index, user preferences, tool usage standards.
+> 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.
+- [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.
 
 Stack-specific agents can be added after the product shape is known.
 
 ## Skills (Workflows)
 
-- [harness-router](.claude/skills/harness-router/SKILL.md) — start-of-task routing to the smallest useful doc set.
-- [harness-lifecycle](.claude/skills/harness-lifecycle/SKILL.md) — idea, PRD, scope, lifecycle, and feedback loops.
-- [harness-research](.claude/skills/harness-research/SKILL.md) — market, product, stack, dependency, API, and open-source research.
-- [harness-context](.claude/skills/harness-context/SKILL.md) — context splitting, subagent packs, and dispatch preparation.
-- [harness-build-loop](.claude/skills/harness-build-loop/SKILL.md) — implementation, debugging, review, verification, and closeout.
+- [harness-router](../.claude/skills/harness-router/SKILL.md) — start-of-task routing to the smallest useful doc set.
+- [harness-lifecycle](../.claude/skills/harness-lifecycle/SKILL.md) — idea, PRD, scope, lifecycle, and feedback loops.
+- [harness-research](../.claude/skills/harness-research/SKILL.md) — market, product, stack, dependency, API, and open-source research.
+- [harness-context](../.claude/skills/harness-context/SKILL.md) — context splitting, subagent packs, and dispatch preparation.
+- [harness-build-loop](../.claude/skills/harness-build-loop/SKILL.md) — implementation, debugging, review, verification, and closeout.
+- [wf-mode](../.claude/skills/wf-mode/SKILL.md) — long-task workflow: exploration, second plan, implementation, review, verification, heartbeat, and recovery loop.
+- [subagent-orchestrator](../.claude/skills/subagent-orchestrator/SKILL.md) — controller-led subagent orchestration, parallel read-only passes, review gates, and recovery handoffs.
+- [readme-optimizer](../.claude/skills/readme-optimizer/SKILL.md) — README preservation, append-only development sections, structured tables, and approved architecture diagrams.
 
 Stack-specific skills can be added after the product shape is known.
 
@@ -30,29 +34,34 @@ Stack-specific skills can be added after the product shape is known.
 
 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)
+- [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)
 
-- [Active plan](docs/harness/PLAN.md)
-- [Docs router](docs/README.md)
-- [0-1 lifecycle](docs/harness/lifecycle.md)
-- [Research protocol](docs/research/README.md)
-- [Context loading protocol](docs/harness/context-loading.md)
-- [Dispatch protocol](docs/harness/dispatch.md)
-- [Extension contract](docs/harness/extension.md)
-- [Architecture docs](docs/harness/architecture.md)
-- [Agent workflow](docs/harness/agent-workflow.md)
+- [Active plan](PLAN.md)
+- [Docs router](README.md)
+- [WF mode](WF.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)
 
-## User Mem
+## Memory Folder
 
-> User preferences, habits, corrections. Written by CLAUDE.md §5.1 triggers, newest first.
-> No entries yet — awaiting first "remember…" instruction.
+- [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.
 
-## Tool Usage Standards
+Write to the memory folder when the guidance should survive chat context loss:
 
-> Claude Code self-learning: high-frequency tool/MCP/skill pitfalls, alternatives, common error fix templates.
-> Written by CLAUDE.md §5.2 triggers.
-> No entries yet — awaiting first auto-discovery.
+- 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

@@ -0,0 +1,41 @@
+# {{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/PLAN.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/readme-optimizer/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/PLAN.md`.
+- Use `Harness/WF.md` or `/wf` for long, difficult, multi-agent work.
+- Use `Harness/subagents.md` when coordinating multiple agents.