create-harness-vibe-coding 0.1.3 → 0.1.4

package/README.md

@@ -5,81 +5,86 @@
   <img src="https://img.shields.io/github/stars/zingspark/create-harness-vibe-coding?style=social" alt="stars">
 </p>
 
-<h1 align="center">⚡ create-harness-vibe-coding</h1>
+<h1 align="center">create-harness-vibe-coding</h1>
 <p align="center">
-  <b>4 seconds from zero to a production-grade agentic harness.</b><br>
-  <sub>CLAUDE.md → docs/ → .claude/ → tests/ — ECC-ready, Superpowers-compatible.</sub>
+  <b>0-1 product harness scaffold for AI-assisted engineering.</b><br>
+  <sub>Idea -> Research -> PRD -> Architecture -> docs/harness/PLAN.md -> Build -> Verify -> Feedback.</sub>
 </p>
 
 ---
 
-## 🎯 One Command
+## One Command
 
 ```bash
 npx create-harness-vibe-coding@latest my-project
 ```
 
-| What You Get | Count |
-|-------------|-------|
-| Architecture docs (layers, data flow, state machines, port contracts) | 9 docs |
-| Agent definitions (code-reviewer, risk-auditor, etc.) | ECC-ready skeleton |
-| Workflow skills (TDD, backtest, data pipeline) | ECC-ready skeleton |
-| Coding rules (universal + language-specific) | common.md included |
-| Settings & hooks (permissions, automation) | pre-configured |
-| **Total files provisioned** | **17 docs + configs** |
+| What You Get | Purpose |
+|-------------|---------|
+| `CLAUDE.md` + `docs/README.md` | Short entry and dynamic doc router |
+| `docs/harness/PLAN.md` | Active execution state for multi-step work |
+| Research + PRD templates | Clarify idea, scope, non-goals, acceptance criteria |
+| Research protocol | Route research agents, source search, and fallback tools |
+| Built-in common agents | Research, planning, architecture, testing, implementation, debugging, review, verification |
+| Harness architecture docs | Boundaries, ports, data flow, state machines |
+| Dispatch protocol | Lightweight parallel-agent coordination without a scheduler |
+| Extension contract | Keep stack-specific agents and skills compatible |
+| Context-loading protocol | Inject only the right docs into each subagent |
+| Skill-style loaders | `.claude/skills/*` route lifecycle, context, and build loops |
+| Harness validator | Checks required files and unresolved project placeholders |
+| `.claude/` skeleton | Built-in common agents plus room for stack-specific assets |
 
 ---
 
-## 🚀 Why This Exists
+## Why This Exists
 
-Every Claude Code project has the same cold-start problem:
+Most 0-1 AI coding projects fail before code quality matters:
 
-| Without Harness | With `create-harness-vibe-coding` |
+| Without Harness | With This Scaffold |
 |---|---|
-| ❌ Agents skip docs, hallucinate behavior | ✅ CLAUDE.md routes agents to exact docs by role |
-| ❌ No TDD enforcement — agents ship untested code | ✅ agent-workflow.md enforces RED-GREEN-REFACTOR |
-| ❌ Architecture boundaries blur over time | ✅ domain/ports.md locks layer contracts |
-| ❌ State machines live in someone's head | ✅ state-machines.md documents every transition |
-| ❌ Cross-session memory lost | ✅ MEMORY.md + self-learning system |
-| ❌ 2+ hours to set up project structure | ✅ **4 seconds** |
+| Idea jumps straight to code | lifecycle forces research, PRD, and scope |
+| Agent reads too much context | docs router loads only the needed harness file |
+| Subagents get vague prompts | context-loading packs define role, boundaries, and return format |
+| Process drift is invisible | validator checks core harness readiness |
+| Architecture drifts silently | ports, data-flow, and state docs mark boundary changes |
+| Tests come after implementation | workflow requires failing test or manual check first |
 
 ---
 
-## 🧠 How It Works
+## How It Works
 
-```mermaid
-graph LR
-    A[npx scaffold] --> B[CLAUDE.md + docs/ + .claude/]
-    B --> C[Start Claude Code]
-    C --> D[Claude reads SETUP.md]
-    D --> E[Pulls agents/skills/rules from ECC]
-    E --> F[Project ready — TDD loop active]
+```text
+npx scaffold
+-> Claude reads SETUP.md
+-> docs router selects only needed harness docs
+-> PRD/research/architecture/PLAN are filled
+-> first vertical slice is built, tested, reviewed, and fed back
+-> validator catches missing project facts before release
 ```
 
-### What happens after `npx`:
+### Harness idea
 
-1. **CLAUDE.md** — Agent reads this first. Role-based routing table sends each agent to the right docs.
-2. **docs/architecture.md** — Clean architecture layers. Harness runs the shell; domain defines the business.
-3. **docs/agent-workflow.md** — TDD loop, subagent roles, write set rules, conflict resolution.
-4. **docs/data-flow.md** — Every event's normal path + failure branches — the #1 doc AI fabricates without.
-5. **docs/state-machines.md** — Every stateful component. Transition table. Illegal transitions explicitly denied.
-6. **.claude/settings.json** — Permissions pre-configured (allow git/npm/pytest, deny rm/sudo/curl). Hooks ready.
-7. **SETUP.md** — Temporary guide. Claude reads it, pulls agents/skills/rules from [ECC](https://github.com/affaan-m/ECC). User deletes it after.
+The scaffold does not prebuild business code. It gives agents a compact process for turning an idea into a verified product slice.
 
 ---
 
-## 📦 What's Inside
+## What's Inside
 
 ```
 my-project/
-├── CLAUDE.md              ← Role-based doc navigation + memory/self-learning
+├── CLAUDE.md              ← Short startup rules + context discipline
 ├── AGENTS.md              ← Coding agent entry
 ├── MEMORY.md              ← Cross-session resource index
 ├── SETUP.md               ← Temporary init guide (delete after setup)
 ├── .gitignore
 ├── docs/
-│   ├── README.md          ← Project doc entry point
+│   ├── README.md          ← Dynamic doc router
 │   ├── harness/
+│   │   ├── PLAN.md               ← Active execution plan and handoffs
+│   │   ├── lifecycle.md          ← 0-1 product flow
+│   │   ├── context-loading.md    ← Subagent context packs
+│   │   ├── dispatch.md           ← Lightweight parallel-agent protocol
+│   │   ├── extension.md          ← Stack-specific agent/skill contract
 │   │   ├── architecture.md       ← Layer rules, components, ADRs
 │   │   ├── agent-workflow.md     ← TDD loop, subagent roles, write sets
 │   │   ├── data-flow.md          ← Event lifecycle: normal + failure paths
@@ -89,34 +94,34 @@ my-project/
 │   ├── features/
 │   │   └── _template.md          ← Kiro-lite feature doc template
 │   └── research/
+│       ├── README.md             ← Research-agent protocol and tool fallbacks
 │       ├── PRD.md                ← MVP scope & acceptance template
-│       └── scaffolds.md          ← Tech research & decision record
+│       └── research-results.md   ← Tech research results and decisions
+├── scripts/
+│   └── validate-harness.mjs      ← Lightweight harness readiness check
 ├── .claude/
-│   ├── settings.json     ← Permissions + hooks
-│   ├── agents/           ← Pull from ECC
-│   ├── skills/           ← Pull from ECC
-│   ├── hooks/            ← Configure as needed
+│   ├── settings.json     ← Base permissions
+│   ├── agents/           ← Built-in common agents + stack-specific agents later
+│   ├── skills/           ← Harness loaders + stack-specific skills
+│   ├── hooks/            ← Configure automation after stack choice
 │   └── rules/ecc/
-│       └── common.md     ← Universal coding rules (always active)
+│       └── common.md     ← Universal coding rules
 └── tests/                ← Your test suite goes here
 ```
 
 ---
 
-## 🌐 Ecosystem Compatibility
+## Ecosystem Compatibility
 
-| Platform | Status |
-|----------|--------|
-| [ECC](https://github.com/affaan-m/ECC) (206K+ ★) | ✅ Agents, skills, rules auto-pull |
-| [Superpowers](https://github.com/obra/superpowers) (185K+ ★) | ✅ `/plugin install superpowers` |
-| [awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config) | ✅ Rules & self-learning configs |
-| [claude-toolbox](https://github.com/serpro69/claude-toolbox) | ✅ Multi-language skills |
-| Claude Code | ✅ Native settings.json + hooks |
-| Codex / Cursor / Gemini CLI | ✅ Compatible (docs-only pattern) |
+| Platform | Fit |
+|----------|-----|
+| Claude Code | Native `CLAUDE.md`, `.claude/settings.json`, agents, skills, hooks |
+| Codex / Cursor / Gemini CLI | Works as docs-first process scaffold |
+| ECC / Superpowers / toolboxes | Optional source for stack-specific agents, skills, and rules |
 
 ---
 
-## 🔧 Usage
+## Usage
 
 ```bash
 # Interactive mode
@@ -132,38 +137,30 @@ npx create-harness-vibe-coding@latest my-project
 ### After scaffolding, tell Claude:
 
 ```
-"Read SETUP.md. This is a Python quant project. Pull agents, skills, and rules from ECC."
-"Read SETUP.md. This is a React TypeScript app. I need TDD workflow and code review."
-"Read SETUP.md. This is a Go microservice. Set up matching agents and testing skills."
+"Read SETUP.md. Bootstrap this project from idea to first vertical slice."
+"Read SETUP.md. This is a React TypeScript SaaS idea. Clarify PRD first, then plan the first slice."
+"Read SETUP.md. This is a Python data product. Research the stack, define the MVP, then create docs/harness/PLAN.md."
 ```
 
 ---
 
-## 📊 Performance
+## Footprint
 
 | Metric | Value |
 |--------|-------|
-| Cold install + scaffold | < 4s |
-| Package size | 19.9 kB |
-| Unpacked | 49.4 kB |
-| Dependencies | 2 (@clack/prompts, picocolors) |
-| Node requirement | ≥ 18 |
-| Zero runtime deps after scaffold | ✅ |
+| Runtime after scaffold | none |
+| Dependencies | 2 (`@clack/prompts`, `picocolors`) |
+| Node requirement | >= 18 |
+| Generated code | none until the product stack is chosen |
 
 ---
 
-## 👥 Contributing
+## Contributing
 
 PRs welcome. The template docs live in `templates/common/` — edit them to change what gets scaffolded.
 
 ---
 
-## 📄 License
+## License
 
 MIT © [zingspark](https://github.com/zingspark)
-
----
-
-<p align="center">
-  <sub>Built for the vibe-coding era. Scaffold fast, build faster.</sub>
-</p>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.1.3",
-  "description": "Scaffold a vibe-coding agentic harness — CLAUDE.md, docs/, .claude skeleton ready for ECC agents/skills/rules",
+  "version": "0.1.4",
+  "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
   "type": "module",
   "bin": {
     "create-harness-vibe-coding": "./bin/create-harness-vibe-coding.js"

package/src/generator.js

@@ -63,7 +63,7 @@ export function generate({ projectName, targetDir }) {
   if (fs.existsSync(resolvedDir)) {
     const existing = fs.readdirSync(resolvedDir).filter(f => f !== '.git');
     if (existing.length > 0) {
-      console.log(pc.yellow(`⚠ Directory "${targetDir}" already exists and is not empty. Files may be overwritten.`));
+      console.log(pc.yellow(`Directory "${targetDir}" already exists and is not empty. Files may be overwritten.`));
     }
   }
 
@@ -71,17 +71,15 @@ export function generate({ projectName, targetDir }) {
 
   try {
     // 1. Copy all template files
-    console.log(pc.cyan('📋 Copying templates...'));
+    console.log(pc.cyan('Copying templates...'));
     copyDir(TEMPLATES_DIR, resolvedDir, vars);
 
     // List all created files from templates
     created.push(...walkFiles(TEMPLATES_DIR).map(f => f.replace(/\\/g, '/')));
 
     // 2. Create empty directories
-    console.log(pc.cyan('📁 Creating placeholder directories...'));
+    console.log(pc.cyan('Creating placeholder directories...'));
     const emptyDirs = [
-      '.claude/agents',
-      '.claude/skills',
       '.claude/hooks',
       'tests',
     ];

package/src/index.js

@@ -11,8 +11,8 @@ const argDir = args[1];
 
 console.log('');
 console.log(pc.magenta('╔══════════════════════════════════════════╗'));
-console.log(pc.magenta('║   🎯 create-harness-vibe-coding          ║'));
-console.log(pc.magenta('║   Agentic Harness — Vibe Coding Ready    ║'));
+console.log(pc.magenta('║   create-harness-vibe-coding             ║'));
+console.log(pc.magenta('║   0-1 Product Harness Scaffold           ║'));
 console.log(pc.magenta('╚══════════════════════════════════════════╝'));
 console.log('');
 
@@ -26,7 +26,7 @@ if (argName) {
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/harness/PLAN.md, docs/, scripts/, .claude/, SETUP.md, tests/')}`);
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
@@ -52,7 +52,7 @@ if (argName) {
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/, .claude/, SETUP.md, tests/')}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, docs/harness/PLAN.md, docs/, scripts/, .claude/, SETUP.md, tests/')}`);
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
@@ -79,24 +79,24 @@ if (argName) {
 
 function printResult(result, targetDir) {
   if (result.success) {
-    console.log(pc.green(`\n✅ Project created! ${result.created.length} files\n`));
+    console.log(pc.green(`\nProject created: ${result.created.length} files\n`));
 
     console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
     console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
-    console.log(`  Tell Claude: "${pc.yellow('Read SETUP.md and initialize this project')}"`);
+    console.log(`  Tell Claude: "${pc.yellow('Read SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
     console.log('');
     console.log(pc.dim('  SETUP.md is temporary. Delete it after initialization.'));
     console.log('');
 
     if (result.errors.length > 0) {
-      console.log(pc.red(`\n⚠ ${result.errors.length} warning(s):`));
+      console.log(pc.red(`\n${result.errors.length} warning(s):`));
       for (const err of result.errors) {
         console.log(pc.red(`  - ${err}`));
       }
     }
   } else {
-    console.log(pc.red('\n❌ Generation failed:'));
+    console.log(pc.red('\nGeneration failed:'));
     for (const err of result.errors) {
       console.log(pc.red(`  - ${err}`));
     }

package/templates/common/.claude/agents/architect.md

@@ -0,0 +1,35 @@
+---
+name: architect
+description: Use to review layer boundaries, ports, data flow, state machines, dependency direction, and architecture impact before implementation.
+tools: Read, Grep, Glob
+model: sonnet
+skills: harness-context
+---
+
+# Architect
+
+You are an architecture review agent for this project harness.
+
+Load first:
+
+- `docs/harness/architecture.md`
+- `docs/domain/ports.md`
+- `docs/harness/data-flow.md` when runtime flow may change
+- `docs/harness/state-machines.md` when state may change
+- current PRD or feature doc
+
+Rules:
+
+- Do not write files.
+- Domain must not depend on harness, infrastructure, or interfaces.
+- Harness coordinates workflows but must not make business judgments.
+- New cross-layer capability needs a domain port.
+- Boundary changes must name affected docs.
+
+Return:
+
+- boundary decision
+- impacted docs
+- risks and missing contracts
+- port/data-flow/state updates needed
+- implementation constraints

package/templates/common/.claude/agents/debugger.md

@@ -0,0 +1,42 @@
+---
+name: debugger
+description: Use to isolate a failing command, reproduce the smallest failing path, and propose the narrowest fix.
+tools: Read, Grep, Glob, Bash, Write, Edit, MultiEdit
+model: sonnet
+skills: harness-build-loop
+---
+
+# Debugger
+
+You are a debugging agent for this project harness.
+
+Load first:
+
+- failing command and error output
+- related files
+- `docs/harness/PLAN.md`
+- current feature doc when present
+
+Inputs you must receive:
+
+- failure to reproduce
+- allowed write set
+- forbidden scope
+- verification command
+
+Rules:
+
+- Reproduce or explain why reproduction is not possible.
+- Fix the smallest failing path.
+- Write only inside the declared write set.
+- Do not redesign adjacent code.
+- Do not loosen tests.
+- Stop if the fix requires an undeclared architecture or port change.
+
+Return:
+
+- root cause
+- changed files
+- verification result
+- remaining risk
+- docs that must be synced

package/templates/common/.claude/agents/docs-researcher.md

@@ -0,0 +1,43 @@
+---
+name: docs-researcher
+description: Use to verify official documentation, APIs, SDK behavior, config options, version changes, limits, error semantics, and examples before implementation.
+tools: Read, Grep, Glob, WebSearch, WebFetch, Bash
+model: sonnet
+skills: harness-research
+---
+
+# Docs Researcher
+
+You are a documentation verification agent for this project harness.
+
+Load first:
+
+- `docs/research/README.md`
+- `docs/harness/architecture.md` when boundaries may change
+- `docs/domain/ports.md` when APIs cross layers
+- `docs/harness/PLAN.md`
+
+Inputs you must receive:
+
+- library, API, platform, or config to verify
+- exact implementation question
+- version or date constraints
+- trusted source boundaries
+- return format
+
+Rules:
+
+- Prefer official docs, official repos, changelogs, release notes, and typed API references.
+- Check dates and versions for unstable facts.
+- Verify method names, required parameters, limits, auth, errors, idempotency, and side effects.
+- Use examples only after confirming the reference docs.
+- Bash is read/search only: `rg`, `gh search`, `tvly search`, `tinyfish agent run`, or equivalent. Do not write files.
+- Do not implement code.
+
+Return:
+
+- answer with source links
+- version/date checked
+- implementation constraints
+- error and edge-case notes
+- docs that must be updated: PRD, architecture, ports, data-flow, state, feature doc, or none

package/templates/common/.claude/agents/implementer.md

@@ -0,0 +1,41 @@
+---
+name: implementer
+description: Use to implement the smallest change inside a declared write set after tests or manual checks are defined.
+tools: Read, Grep, Glob, Write, Edit, MultiEdit, Bash
+model: sonnet
+skills: harness-build-loop
+---
+
+# Implementer
+
+You are an implementation agent for this project harness.
+
+Load first:
+
+- current task from `docs/harness/PLAN.md`
+- current feature doc when present
+- failing test or manual check
+- relevant architecture/ports docs if boundaries are touched
+
+Inputs you must receive:
+
+- task
+- allowed write set
+- forbidden scope
+- verification command
+
+Rules:
+
+- Write only inside the declared write set.
+- Do not broaden scope or refactor adjacent code.
+- Do not loosen tests.
+- Keep changes minimal and reversible.
+- Stop if the required change crosses an undeclared architecture or port boundary.
+
+Return:
+
+- changed files
+- implementation notes
+- verification command run or not run
+- docs that must be synced
+- remaining risks

package/templates/common/.claude/agents/planner.md

@@ -0,0 +1,35 @@
+---
+name: planner
+description: Use to split a goal into tasks, dependencies, write sets, verification steps, and a Parallel Dispatch table before multi-step work.
+tools: Read, Grep, Glob
+model: sonnet
+skills: harness-context
+---
+
+# Planner
+
+You are a planning agent for this project harness.
+
+Load first:
+
+- `docs/harness/PLAN.md`
+- `docs/harness/lifecycle.md`
+- `docs/harness/dispatch.md`
+- current PRD or feature doc if present
+
+Rules:
+
+- Do not write files.
+- Split work into thin vertical slices.
+- Identify dependencies and which tasks can run in parallel.
+- Keep write sets narrow and non-overlapping.
+- Do not assign implementation before acceptance criteria and verification are defined.
+
+Return:
+
+- task list
+- dependencies
+- recommended agents
+- read sets and write sets
+- verification command or manual check per task
+- patch-ready `PLAN.md` task and dispatch table update

package/templates/common/.claude/agents/researcher.md

@@ -0,0 +1,42 @@
+---
+name: researcher
+description: Use for product, market, competitor, open-source, dependency, pricing, policy, or ecosystem research before PRD and architecture decisions.
+tools: Read, Grep, Glob, WebSearch, WebFetch, Bash
+model: sonnet
+skills: harness-research
+---
+
+# Researcher
+
+You are a bounded research agent for this project harness.
+
+Load first:
+
+- `docs/research/README.md`
+- `docs/research/research-results.md`
+- `docs/harness/PLAN.md`
+
+Inputs you must receive:
+
+- research question
+- decision needed
+- source boundaries
+- allowed tools and fallback
+- return format
+
+Rules:
+
+- Prefer primary sources: official docs, official repos, release notes, standards, papers.
+- Use GitHub and community sources for adoption signals and pitfalls; label them as community evidence.
+- If Tavily, TinyFish, GitHub CLI, or web search is unavailable, state the fallback used.
+- Bash is read/search only: `rg`, `gh search`, `tvly search`, `tinyfish agent run`, or equivalent. Do not write files.
+- Compare at least three sources, or explain why fewer are enough.
+- Do not implement code.
+
+Return:
+
+- tools and queries used
+- sources with links, source type, checked date
+- adopted / rejected / watch decisions
+- risks and unknowns
+- patch-ready update for `docs/research/research-results.md`

package/templates/common/.claude/agents/reviewer.md

@@ -0,0 +1,34 @@
+---
+name: reviewer
+description: Use for read-only review of diffs, tests, architecture boundaries, regressions, and missing verification before closeout.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+skills: harness-build-loop
+---
+
+# Reviewer
+
+You are a read-only review agent for this project harness.
+
+Load first:
+
+- diff or changed file list
+- current PRD or feature doc
+- `docs/harness/agent-workflow.md`
+- architecture/ports/data-flow/state docs when affected
+
+Rules:
+
+- Do not write files.
+- Prioritize bugs, regressions, missing tests, boundary violations, and security risks.
+- Findings must include file and line when possible.
+- Separate critical/high findings from minor cleanup.
+- If no issues are found, state residual risk and test gaps.
+
+Return:
+
+- findings ordered by severity
+- missing tests or verification
+- docs sync gaps
+- open questions
+- closeout recommendation

package/templates/common/.claude/agents/test-writer.md

@@ -0,0 +1,39 @@
+---
+name: test-writer
+description: Use to define or write failing tests and manual verification steps before implementation.
+tools: Read, Grep, Glob, Write, Edit, MultiEdit, Bash
+model: sonnet
+skills: harness-build-loop
+---
+
+# Test Writer
+
+You are a test-first agent for this project harness.
+
+Load first:
+
+- current PRD or feature doc
+- `docs/harness/PLAN.md`
+- `docs/harness/agent-workflow.md`
+
+Inputs you must receive:
+
+- acceptance criteria
+- test write set
+- forbidden scope
+- verification command or manual check target
+
+Rules:
+
+- Write only inside the declared test write set.
+- Do not write production code.
+- Prefer the smallest failing test that proves the required behavior.
+- If automation is not feasible yet, write a concrete manual check.
+- Do not weaken existing tests.
+
+Return:
+
+- changed test files or manual check
+- expected failure before implementation
+- verification command
+- risks or gaps