create-harness-vibe-coding 0.1.2 → 0.1.4

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

@@ -1,32 +1,35 @@
 ---
-description: "Universal coding principles — always applied"
+description: "Universal harness constraints"
 alwaysApply: true
 ---
 
-# Universal Coding Rules
+# Universal Rules
 
-## Architecture Boundaries (CLAUDE.md enforced)
-- `domain/` depends on stdlib only — no infrastructure imports ever
-- `application/` depends on `domain/` only
-- `infrastructure/` implements ports defined in `domain/`
-- `harness/` coordinates workflows, contains no domain business rules
+## Context
 
-## Code Style
-- Prefer small, deterministic, pure functions
-- Functions > 30 lines need a comment explaining why they can't be split
-- No hidden global state in strategy or service objects
-- Explicit over implicit: type hints on all function signatures
+- Start with `CLAUDE.md`, `MEMORY.md`, and `docs/README.md`.
+- Do not bulk-read `docs/`. Load by router trigger.
+- Keep `docs/harness/PLAN.md` current when work has multiple steps, files, or agents.
 
-## Git Workflow
-- Commit format: `type(scope): message` — types: feat/fix/test/docs/refactor/chore
-- Every feature PR must include: implementation + tests + doc update
-- Keep commits atomic; one logical change per commit
+## Verification
 
-## Testing
-- Write tests before or alongside implementation, not after
-- Test behavior, not implementation details
-- Tests must be deterministic and not depend on wall-clock time
+- 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 `docs/harness/context-loading.md` before spawning.
+- Use `docs/harness/dispatch.md` before parallel or multi-agent work.
+- Use `docs/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.
 
 ## Security
-- No API keys or secrets in source code — use environment variables
-- Validate all external data at system boundaries
+
+- 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/skills/harness-build-loop/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: harness-build-loop
+description: Use for implementation, review, debugging, verification, and closing a feature.
+---
+
+# Harness Build Loop
+
+Load:
+
+- `docs/harness/agent-workflow.md`
+- `docs/harness/dispatch.md` when more than one agent is useful
+- `docs/harness/PLAN.md`
+- current feature doc if present
+
+Follow:
+
+```text
+acceptance criteria -> failing test/manual check -> implementation -> verify -> review -> docs sync
+```
+
+Close only with recorded verification evidence.

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

@@ -0,0 +1,24 @@
+---
+name: harness-context
+description: Use before spawning subagents, splitting work, or when context is growing.
+---
+
+# Harness Context
+
+Load:
+
+- `docs/harness/context-loading.md`
+- `docs/harness/dispatch.md` when more than one agent is useful
+- `docs/harness/PLAN.md`
+- current feature doc if present
+
+For each subagent or bounded pass, provide:
+
+- role
+- task
+- mode
+- read boundary
+- write boundary
+- dependency
+- injected docs
+- return format

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

@@ -0,0 +1,19 @@
+---
+name: harness-lifecycle
+description: Use for raw ideas, vague product requests, 0-1 planning, PRD work, scope decisions, or feedback loops.
+---
+
+# Harness Lifecycle
+
+Load:
+
+- `docs/harness/lifecycle.md`
+- `docs/research/PRD.md`
+- `docs/harness/PLAN.md`
+
+Output:
+
+- current phase
+- blocking questions or recorded assumptions
+- next artifact to fill
+- gate before coding

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

@@ -0,0 +1,29 @@
+---
+name: harness-research
+description: Use for market, product, stack, dependency, API, pricing, legal, security, or open-source research before PRD or architecture decisions.
+---
+
+# Harness Research
+
+Load:
+
+- `docs/research/README.md`
+- `docs/research/research-results.md`
+- `docs/harness/PLAN.md`
+
+Define:
+
+- research question
+- decision needed
+- source boundaries
+- tool choice: local / GitHub / Tavily / TinyFish / built-in web search / user-provided sources
+- fallback when the preferred tool is unavailable
+- return format
+
+Return:
+
+- queries and tools used
+- sources with links and source type
+- adopted / rejected / watch decisions
+- risks and unknowns
+- patch-ready `docs/research/research-results.md` update

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

@@ -0,0 +1,14 @@
+---
+name: harness-router
+description: Use at the start of any task, or when unsure which harness document applies. Keeps context small by routing to one primary doc.
+---
+
+# Harness Router
+
+1. Read `docs/README.md`.
+2. Identify the current situation from "Load By Task".
+3. Load only the listed primary doc(s).
+4. If the task grows, update `docs/harness/PLAN.md` and use `harness-context`.
+5. If multiple agents are useful, use `docs/harness/dispatch.md`.
+
+Do not bulk-read `docs/`.

package/templates/common/AGENTS.md

@@ -2,4 +2,6 @@
 
 Entry point for coding agents.
 
-Read `CLAUDE.md` first, then follow docs in `docs/`.
+Read `CLAUDE.md` first, then `docs/README.md`.
+
+Do not bulk-read `docs/`. Let `docs/README.md` route you to the smallest useful context.

package/templates/common/CLAUDE.md

@@ -2,22 +2,31 @@
 
 ## 📖 Doc Navigation (read before every task)
 
-`@docs/README.md` is the project fact source. Route by role:
+`@docs/README.md` is the project fact source and router. Keep context small: load the matching row, then only the docs it directly names.
+
+Every new session starts with:
+1. Read `@MEMORY.md`.
+2. Read `@docs/README.md`.
+3. If work spans more than one step, update `@docs/harness/PLAN.md`.
 
 | Your Role | Required Reading |
 |-----------|-----------------|
+| New to the project / unclear idea | `docs/harness/lifecycle.md` → `docs/research/PRD.md` |
+| Researching market / stack / examples | `docs/research/README.md` → `docs/research/research-results.md` |
 | Writing code / implementing | `docs/harness/agent-workflow.md` → `docs/features/_template.md` |
 | Designing architecture / new modules | `docs/harness/architecture.md` → `docs/domain/ports.md` |
-| Reviewing code | `docs/harness/state-machines.md` → tests |
+| Reviewing code | `docs/harness/agent-workflow.md` → tests |
 | Fixing bugs / debugging | `docs/harness/data-flow.md` → `docs/harness/state-machines.md` |
-| New to the project | `docs/research/PRD.md` → `docs/harness/architecture.md` |
+| Coordinating subagents | `docs/harness/context-loading.md` → `docs/harness/dispatch.md` |
 
 **Hard rules**:
-- Before touching cross-layer boundaries, read `docs/domain/ports.md`
-- Before adding failure paths, read `docs/harness/data-flow.md`
-- Before modifying stateful components, read `docs/harness/state-machines.md`
-- Unsure whether to open a feature doc? Read `docs/harness/agent-workflow.md` §1
-- **Every new session must read `@MEMORY.md`** for accumulated context
+- Before touching cross-layer boundaries, read `docs/domain/ports.md`.
+- Before adding failure paths, read `docs/harness/data-flow.md`.
+- Before modifying stateful components, read `docs/harness/state-machines.md`.
+- Unsure whether to open a feature doc? Read `docs/harness/agent-workflow.md` §1.
+- Before coordinating multiple agents, fill `docs/harness/PLAN.md#Parallel Dispatch` and follow `docs/harness/dispatch.md`.
+- When adding stack-specific agents, skills, rules, or hooks, follow `docs/harness/extension.md`.
+- **Every new session must read `@MEMORY.md`** for accumulated context.
 
 ---
 
@@ -89,25 +98,13 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 
 ## 5. Memory & Self-Learning
 
-When a user expresses "remember / preference / habit / correction" intent, **persist to `MEMORY.md`** for reuse across sessions.
-**Important**: Every new session must read `@MEMORY.md`.
-
-### 5.1 Trigger Words
-
-When the user's message contains these keywords or intent, write to `MEMORY.md`:
+Every new session must read `@MEMORY.md`.
 
-| Trigger Phrase | Meaning | Write To |
-|---|---|---|
-| "remember…", "note…", "save…" | User wants to persist a fact/preference | User Mem |
-| "don't ever…", "never…", "stop doing…" | User corrects a behavior — avoid in future | User Mem |
-| "next time…", "always…", "from now on…" | User specifies a future default behavior | User Mem |
-| "I prefer…", "I like…", "my workflow…" | User expresses a work habit or preference | User Mem |
+### 5.1 User Memory
 
-If unclear whether a message triggers memory, ask the user before writing. Don't auto-record every conversation.
+Persist only durable user preferences, corrections, or workflow defaults. Trigger examples: "remember", "never", "next time", "always", "I prefer".
 
-### 5.2 MEMORY.md Write Format
-
-Append to `## User Mem` in `MEMORY.md`, newest first:
+Append newest first under `MEMORY.md#User Mem`:
 
 ```markdown
 ### YYYY-MM-DD — <short title>
@@ -116,17 +113,17 @@ Append to `## User Mem` in `MEMORY.md`, newest first:
 - **Why**: <user's reason, if provided>
 ```
 
-### 5.3 Self-Learning: Tool Usage Standards
+Do not record ordinary conversation. If persistence is ambiguous, ask first.
+
+### 5.2 Tool Self-Learning
 
-When Claude Code discovers the following patterns (without involving user privacy), auto-append to `## Tool Usage Standards` in `MEMORY.md`:
+Auto-record only reusable, non-private workflow lessons under `MEMORY.md#Tool Usage Standards` when:
 
-| Pattern Discovered | Record |
-|---|---|
-| A tool/MCP/skill fails 3+ times when called frequently, or has a better alternative | Record: scenario → failure cause → recommended alternative |
-| A code error repeats in the same file/module (lint errors, type errors, import errors) | Record: error type → trigger condition → fix template |
-| A skill/MCP is called in a way that deviates from best practices, causing inefficiency | Record: correct usage → usage to avoid |
+- the same tool/MCP/skill failure repeats 3+ times, or a better alternative is found
+- the same local error pattern repeats, such as lint, type, import, or test setup failures
+- a skill/tool is used inefficiently and a clearer standard emerges
 
-Format:
+Use this format:
 
 ```markdown
 ### <tool/skill name> — <brief issue>
@@ -136,4 +133,4 @@ Format:
 - **Date**: <first recorded date>
 ```
 
-If the same issue already exists, update it rather than creating a duplicate. If a new finding contradicts an old record, replace the old one and note the date.
+Update existing entries instead of duplicating them. Never record secrets or private user data.

package/templates/common/MEMORY.md

@@ -4,32 +4,55 @@
 
 ## Agents (Sub-agents)
 
-> Pending initialization by Claude Code from [ECC](https://github.com/affaan-m/ECC).
-> Init command: describe your project type and language to Claude — it will pull matching 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.
+
+Stack-specific agents can be added after the product shape is known.
 
 ## Skills (Workflows)
 
-> Pending initialization by Claude Code from [ECC](https://github.com/affaan-m/ECC) or [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config).
+- [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.
 
-## Rules (Code Rules)
+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 coding rules (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)
+- [Harness validator](scripts/validate-harness.mjs)
 
 ## User Mem
 
-> User preferences, habits, corrections. Written by CLAUDE.md §5 triggers, newest first.
+> User preferences, habits, corrections. Written by CLAUDE.md §5.1 triggers, newest first.
 > No entries yet — awaiting first "remember…" instruction.
 
 ## Tool Usage Standards
 
 > Claude Code self-learning: high-frequency tool/MCP/skill pitfalls, alternatives, common error fix templates.
-> Written by CLAUDE.md §5.3 triggers.
+> Written by CLAUDE.md §5.2 triggers.
 > No entries yet — awaiting first auto-discovery.

package/templates/common/SETUP.md

@@ -1,91 +1,65 @@
-# SETUP.md — Project Initialization Guide
+# SETUP.md - Bootstrap This Product Harness
 
-> ⚠️ **Temporary file** — Delete after initialization: `rm SETUP.md`
+Temporary file. Delete after the first vertical slice is verified.
 
----
+## What This Is
 
-## What You Just Created
+This scaffold is a 0-1 product harness:
 
-`npx create-harness-vibe-coding` scaffolded a **vibe-coding agentic harness** skeleton:
+- short agent entry files
+- dynamic docs router
+- PRD, research protocol, architecture, ports, data-flow, state templates
+- active `docs/harness/PLAN.md`
+- built-in common agents
+- subagent context-loading protocol
+- skill-style dynamic loaders in `.claude/skills/`
+- lightweight harness validator
+- test/review/feedback loop
 
-```
-{{projectName}}/
-  CLAUDE.md              ← Agent behavior guidelines + memory/self-learning system
-  AGENTS.md              ← Coding agent entry point
-  MEMORY.md              ← Cross-session resource index
-  docs/                  ← Architecture docs (layer rules, workflows, port contracts)
-  .claude/
-    settings.json        ← Permissions + Hooks config
-    agents/              ← Empty — pull ECC agents here
-    skills/              ← Empty — pull ECC skills here
-    hooks/               ← Empty — configure automation hooks here
-    rules/ecc/
-      common.md          ← Universal coding rules (always active)
-  tests/                 ← Pending initialization
-  .gitignore             ← Basic Git ignore rules
-```
+It does not guess your stack or business domain. Claude Code should fill those through the lifecycle.
 
----
+## Bootstrap Prompt
 
-## Next Steps: Initialize with Claude Code
+Start Claude Code, then say:
 
-### Step 1 — Start Claude Code
-
-```bash
-claude
+```text
+Read SETUP.md. Bootstrap this project as a 0-1 product harness.
+Use docs/README.md as the router. Keep context small.
+First clarify the idea, then create PRD, research, architecture, docs/harness/PLAN.md, and the first vertical-slice task.
 ```
 
-### Step 2 — Describe Your Project
+## Required Bootstrap Sequence
 
-Tell Claude your project type, language, and tech stack. Claude will:
+Claude must follow this order:
 
-1. Pull matching **agents** from [ECC](https://github.com/affaan-m/ECC) (e.g. code-reviewer, planner, security-reviewer)
-2. Pull matching **skills** from ECC (e.g. tdd-workflow, django-patterns, react-patterns)
-3. Pull language-specific **rules** from ECC (e.g. python.md, typescript.md)
-4. Configure **hooks** as needed (e.g. PostToolUse auto-lint, PreToolUse security gate)
+1. Read `CLAUDE.md`, `MEMORY.md`, `docs/README.md`, and `docs/harness/lifecycle.md`.
+2. Ask up to 3 blocking product questions. If not blocked, record assumptions in `docs/harness/PLAN.md`.
+3. Fill `docs/research/PRD.md` with MVP, non-goals, and acceptance criteria.
+4. Read `docs/research/README.md`, then fill `docs/research/research-results.md` with adopted/rejected research choices.
+5. Fill minimum architecture: `docs/harness/architecture.md` and one port in `docs/domain/ports.md`.
+6. Create the first vertical-slice plan in `docs/harness/PLAN.md`.
+7. Use `docs/harness/context-loading.md` and `docs/harness/dispatch.md` when spawning subagents.
+8. Fill `docs/harness/data-flow.md` or `docs/harness/state-machines.md` only when the slice changes runtime flow, failure behavior, or state.
+9. Implement only after a failing test or manual verification step is defined.
+10. Run `node scripts/validate-harness.mjs --strict`.
+11. Record final verification and next feedback step in `docs/harness/PLAN.md`.
 
-**Example prompts**:
+## Optional Agent Assets
 
-```
-You: This is a Python quant trading project. Initialize agents, skills, and rules from ECC.
-You: This is a React + TypeScript frontend project. I need the TDD workflow.
-You: This is a Go microservice project. Set up code review and testing skills.
-```
+This scaffold includes common research and workflow agents. After the product shape is known, Claude may install or copy more stack-specific agents, skills, rules, and hooks into `.claude/`. Follow `docs/harness/extension.md` for every added asset.
 
-### Step 3 — Optional: Install Superpowers
+Examples:
 
-```bash
-# Inside Claude Code
-/plugin install superpowers@claude-plugins-official
+```text
+This is a React TypeScript SaaS app. Add frontend testing and review agents.
+This is a Python data product. Add data pipeline and pytest workflow agents.
+This is a Go service. Add API, security, and integration-test agents.
 ```
 
-Superpowers provides: brainstorming → writing-plans → TDD → code-review loop.
+## Cleanup
 
-### Step 4 — Clean Up
+After bootstrap succeeds:
 
 ```bash
 rm SETUP.md
 ```
-
----
-
-## Reference Resources
-
-| Resource | URL | Purpose |
-|----------|-----|---------|
-| ECC | https://github.com/affaan-m/ECC | Main agents/skills/rules repo |
-| awesome-claude-code-config | https://github.com/Mizoreww/awesome-claude-code-config | Multi-language rules + self-learning config |
-| Superpowers | https://github.com/obra/superpowers | Engineering discipline plugin |
-| claude-toolbox | https://github.com/serpro69/claude-toolbox | Multi-language skills toolkit |
-
----
-
-## Customization
-
-- **CLAUDE.md** — Edit behavior guidelines per project needs
-- **.claude/settings.json** — Adjust permissions and hooks as needed
-- **.claude/rules/ecc/** — Language rules auto-added by Claude Code
-
----
-
-> Generated by `create-harness-vibe-coding`. MIT License.