create-harness-vibe-coding 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,166 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/create-harness-vibe-coding?color=blue" alt="npm version">
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node">
+  <img src="https://img.shields.io/npm/l/create-harness-vibe-coding" alt="license">
+  <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>
+<p align="center">
+  <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
+
+```bash
+npx create-harness-vibe-coding@latest my-project
+```
+
+| 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
+
+Most 0-1 AI coding projects fail before code quality matters:
+
+| Without Harness | With This Scaffold |
+|---|---|
+| 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
+
+```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
+```
+
+### Harness idea
+
+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
+
+```
+my-project/
+├── 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          ← 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
+│   │   └── state-machines.md     ← State enums, transition tables, guards
+│   ├── domain/
+│   │   └── ports.md              ← Port contracts: pre/postconditions, errors
+│   ├── features/
+│   │   └── _template.md          ← Kiro-lite feature doc template
+│   └── research/
+│       ├── README.md             ← Research-agent protocol and tool fallbacks
+│       ├── PRD.md                ← MVP scope & acceptance template
+│       └── research-results.md   ← Tech research results and decisions
+├── scripts/
+│   └── validate-harness.mjs      ← Lightweight harness readiness check
+├── .claude/
+│   ├── 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
+└── tests/                ← Your test suite goes here
+```
+
+---
+
+## Ecosystem Compatibility
+
+| 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
+
+```bash
+# Interactive mode
+npx create-harness-vibe-coding@latest
+
+# Non-interactive (CI/CD)
+npx create-harness-vibe-coding@latest my-app ./dist/my-app
+
+# Always get the latest version
+npx create-harness-vibe-coding@latest my-project
+```
+
+### After scaffolding, tell Claude:
+
+```
+"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."
+```
+
+---
+
+## Footprint
+
+| Metric | Value |
+|--------|-------|
+| Runtime after scaffold | none |
+| Dependencies | 2 (`@clack/prompts`, `picocolors`) |
+| Node requirement | >= 18 |
+| Generated code | none until the product stack is chosen |
+
+---
+
+## Contributing
+
+PRs welcome. The template docs live in `templates/common/` — edit them to change what gets scaffolded.
+
+---
+
+## License
+
+MIT © [zingspark](https://github.com/zingspark)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-harness-vibe-coding",
-  "version": "0.1.2",
-  "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"
@@ -23,8 +23,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/LiWeny16/q-profit.git",
-    "directory": "create-harness-vibe-coding"
+    "url": "https://github.com/zingspark/create-harness-vibe-coding.git"
   },
   "keywords": [
     "claude-code",

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

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

@@ -0,0 +1,33 @@
+---
+name: verifier
+description: Use to run verification commands, inspect results, and record evidence before marking work Done or Verified.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+skills: harness-build-loop
+---
+
+# Verifier
+
+You are a verification agent for this project harness.
+
+Load first:
+
+- `docs/harness/PLAN.md`
+- current feature doc when present
+- verification commands and acceptance criteria
+
+Rules:
+
+- Do not write code.
+- Run only declared verification commands unless asked to expand coverage.
+- If a command is unavailable, record why and suggest a manual check.
+- Mark results as pass, fail, or not run with notes.
+- Do not mark work verified without evidence.
+
+Return:
+
+- commands run
+- result per command
+- acceptance criteria status
+- residual risk
+- patch-ready verification update for `PLAN.md` or feature doc