create-harness-vibe-coding 0.1.5 โ†’ 0.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/package.json +1 -1
  2. package/templates/common/CLAUDE.md +26 -71
  3. package/templates/common/SETUP.md +80 -3
  4. package/templates/common/docs/README.md +6 -2
  5. package/templates/common/docs/research/README.md +48 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-harness-vibe-coding",
3
- "version": "0.1.5",
3
+ "version": "0.1.7",
4
4
  "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
5
5
  "type": "module",
6
6
  "bin": {
package/templates/common/CLAUDE.md CHANGED
@@ -1,50 +1,38 @@
1
1
  # CLAUDE.md
2
2
 
3
- ## ๐Ÿ“– Doc Navigation (read before every task)
4
-
5
- `@docs/README.md` is the project fact source and router. Keep context small: load the matching row, then only the docs it directly names.
6
-
7
- Every new session starts with:
8
- 1. Read `@MEMORY.md`.
9
- 2. Read `@docs/README.md`.
10
- 3. If work spans more than one step, update `@docs/harness/PLAN.md`.
11
-
12
- | Your Role | Required Reading |
13
- |-----------|-----------------|
14
- | New to the project / unclear idea | `docs/harness/lifecycle.md` โ†’ `docs/research/PRD.md` |
15
- | Researching market / stack / examples | `docs/research/README.md` โ†’ `docs/research/research-results.md` |
16
- | Writing code / implementing | `docs/harness/agent-workflow.md` โ†’ `docs/features/_template.md` |
17
- | Designing architecture / new modules | `docs/harness/architecture.md` โ†’ `docs/domain/ports.md` |
18
- | Reviewing code | `docs/harness/agent-workflow.md` โ†’ tests |
19
- | Fixing bugs / debugging | `docs/harness/data-flow.md` โ†’ `docs/harness/state-machines.md` |
20
- | Coordinating subagents | `docs/harness/context-loading.md` โ†’ `docs/harness/dispatch.md` |
21
-
22
- **Hard rules**:
23
- - Before touching cross-layer boundaries, read `docs/domain/ports.md`.
24
- - Before adding failure paths, read `docs/harness/data-flow.md`.
25
- - Before modifying stateful components, read `docs/harness/state-machines.md`.
26
- - Unsure whether to open a feature doc? Read `docs/harness/agent-workflow.md` ยง1.
27
- - Before coordinating multiple agents, fill `docs/harness/PLAN.md#Parallel Dispatch` and follow `docs/harness/dispatch.md`.
28
- - When adding stack-specific agents, skills, rules, or hooks, follow `docs/harness/extension.md`.
29
- - **Every new session must read `@MEMORY.md`** for accumulated context.
3
+ ## 1. Startup
30
4
 
31
- ---
5
+ - Every session: read `MEMORY.md`, then `docs/README.md`.
6
+ - If `SETUP.md` exists in the project root, read it first.
7
+ - All routing, role-based reading, and per-task doc loads live in `docs/README.md`. Not here.
8
+ - If work spans more than one step, update `docs/harness/PLAN.md`.
9
+ - Universal rules live in `.claude/rules/ecc/common.md`.
10
+ - Never bulk-read `docs/`.
32
11
 
33
- Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
12
+ ---
34
13
 
35
- **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
14
+ Behavioral guidelines to reduce common LLM coding mistakes. For trivial tasks, use judgment. These bias toward caution over speed.
36
15
 
37
- ## 1. Think Before Coding
16
+ ## 2. Think Before Coding
38
17
 
39
18
  **Don't assume. Don't hide confusion. Surface tradeoffs.**
40
19
 
20
+ ### 2.1 Confidence Threshold (Non-Negotiable)
21
+
22
+ - You must have **โ‰ฅ95% confidence** in user intent before writing implementation code.
23
+ - If confidence is below 95%, stop and ask. False confidence is worse than a question.
24
+ - **Maximum 3 blocking questions per decision point.** Ask the highest-impact questions first.
25
+ - If you catch yourself thinking *"this is probably what they want"* โ€” that is a mandatory stop condition. Ask.
26
+ - **Silent picks are forbidden.** When two valid approaches exist and you cannot decide with 95% confidence, present both trade-offs to the user.
27
+ - Record every assumption explicitly in `docs/harness/PLAN.md` so the user can correct it.
28
+
41
29
  Before implementing:
42
30
  - State your assumptions explicitly. If uncertain, ask.
43
31
  - If multiple interpretations exist, present them - don't pick silently.
44
32
  - If a simpler approach exists, say so. Push back when warranted.
45
33
  - If something is unclear, stop. Name what's confusing. Ask.
46
34
 
47
- ## 2. Simplicity First
35
+ ## 3. Simplicity First
48
36
 
49
37
  **Minimum code that solves the problem. Nothing speculative.**
50
38
 
@@ -56,7 +44,7 @@ Before implementing:
56
44
 
57
45
  Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
58
46
 
59
- ## 3. Surgical Changes
47
+ ## 4. Surgical Changes
60
48
 
61
49
  **Touch only what you must. Clean up only your own mess.**
62
50
 
@@ -72,7 +60,7 @@ When your changes create orphans:
72
60
 
73
61
  The test: Every changed line should trace directly to the user's request.
74
62
 
75
- ## 4. Goal-Driven Execution
63
+ ## 5. Goal-Driven Execution
76
64
 
77
65
  **Define success criteria. Loop until verified.**
78
66
 
@@ -96,41 +84,8 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
96
84
 
97
85
  ---
98
86
 
99
- ## 5. Memory & Self-Learning
100
-
101
- Every new session must read `@MEMORY.md`.
102
-
103
- ### 5.1 User Memory
104
-
105
- Persist only durable user preferences, corrections, or workflow defaults. Trigger examples: "remember", "never", "next time", "always", "I prefer".
106
-
107
- Append newest first under `MEMORY.md#User Mem`:
108
-
109
- ```markdown
110
- ### YYYY-MM-DD โ€” <short title>
111
- - **Trigger**: <user's exact words>
112
- - **Behavior**: <what to do / what to avoid going forward>
113
- - **Why**: <user's reason, if provided>
114
- ```
115
-
116
- Do not record ordinary conversation. If persistence is ambiguous, ask first.
117
-
118
- ### 5.2 Tool Self-Learning
119
-
120
- Auto-record only reusable, non-private workflow lessons under `MEMORY.md#Tool Usage Standards` when:
121
-
122
- - the same tool/MCP/skill failure repeats 3+ times, or a better alternative is found
123
- - the same local error pattern repeats, such as lint, type, import, or test setup failures
124
- - a skill/tool is used inefficiently and a clearer standard emerges
125
-
126
- Use this format:
127
-
128
- ```markdown
129
- ### <tool/skill name> โ€” <brief issue>
130
- - **Scenario**: <when it triggers>
131
- - **Problem**: <specific symptom>
132
- - **Solution**: <recommended approach>
133
- - **Date**: <first recorded date>
134
- ```
87
+ ## 6. Memory & Self-Learning
135
88
 
136
- Update existing entries instead of duplicating them. Never record secrets or private user data.
89
+ - **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.
90
+ - **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.
91
+ - Format details live in `MEMORY.md`, not here.
package/templates/common/SETUP.md CHANGED
@@ -44,9 +44,81 @@ Claude must follow this order:
44
44
  10. Run `node scripts/validate-harness.mjs --strict`.
45
45
  11. Record final verification and next feedback step in `docs/harness/PLAN.md`.
46
46
 
47
+ ## Architecture Research (Dynamic)
48
+
49
+ Do not guess the architecture. Use `docs/research/README.md` as the protocol and the high-star repos below as seed references. Search within them; do not read them whole.
50
+
51
+ ### Seed Repositories (High-Star, High-Trust)
52
+
53
+ | Repository | Stars | Use For |
54
+ |-----------|-------|---------|
55
+ | [donnemartin/system-design-primer](https://github.com/donnemartin/system-design-primer) | 266k+ | System design fundamentals, trade-off frameworks |
56
+ | [ByteByteGoHq/system-design-101](https://github.com/ByteByteGoHq/system-design-101) | 65k+ | Visual system design, protocol/DB patterns |
57
+ | [DovAmir/awesome-design-patterns](https://github.com/DovAmir/awesome-design-patterns) | 47k+ | General arch, cloud, serverless, microservices, front-end, security |
58
+ | [mehdihadeli/awesome-software-architecture](https://github.com/mehdihadeli/awesome-software-architecture) | high | CQRS, Outbox, Saga, Circuit Breaker, BFF, scaling |
59
+ | [greatfrontend/awesome-front-end-system-design](https://github.com/greatfrontend/awesome-front-end-system-design) | high | Front-end system design patterns |
60
+ | [adr.github.io](https://adr.github.io) | โ€” | ADR templates and tooling |
61
+
62
+ ### Architecture Fill Protocol
63
+
64
+ After research, fill these docs in order:
65
+
66
+ 1. `docs/research/research-results.md` โ€” Record candidate architectures with Adopt / Reject / Watch decisions. Use the `## Candidate References` template.
67
+ 2. `docs/harness/architecture.md` โ€” Fill the layering diagram, core components, and constraints. Do NOT add speculative layers. One layer per proven need.
68
+ 3. `docs/domain/ports.md` โ€” Define ONE driving port and ONE driven port from the first vertical slice. More ports come with more slices.
69
+ 4. `docs/harness/data-flow.md` โ€” Fill the happy path for the first slice only. Add failure paths when they differ from the happy path.
70
+
71
+ **Constraint**: If the research does not give you enough confidence to fill a section, leave the `{{...}}` placeholder and record the open question in `docs/harness/PLAN.md`. The strict validator will catch it.
72
+
73
+ ## User Confirmation Protocol (Non-Negotiable)
74
+
75
+ > This harness is a design partner, not a solo builder. The user owns product intent.
76
+
77
+ When user intent is unclear or ambiguous:
78
+
79
+ - **Maximum 3 blocking questions per decision point.** Ask the highest-impact questions first.
80
+ - **Do not act on assumptions that affect architecture, scope, stack, or user-facing behavior.**
81
+ - **You must have โ‰ฅ95% confidence before writing implementation code.** If below that threshold, stop and ask.
82
+ - **Record every assumption explicitly** in `docs/harness/PLAN.md` so the user can correct it later.
83
+ - **Silent picks are forbidden.** If two valid approaches exist and you cannot decide with high confidence, present both to the user with trade-offs.
84
+
85
+ False confidence is worse than a question. If you catch yourself thinking "this is probably what they want," stop and ask.
86
+
87
+ ## How to Find Proper Skills
88
+
89
+ After the architecture stage reveals your stack, install matching agent skills. Skills teach Claude Code domain-specific patterns, testing conventions, and design rules.
90
+
91
+ **Built-in route**: invoke the `/find-skills` skill (or say "help me find skills for X"). Examples:
92
+
93
+ ```text
94
+ "Find skills for React TypeScript frontend testing."
95
+ "Find skills for Python FastAPI backend development."
96
+ "What skills exist for Playwright e2e testing?"
97
+ "I need a skill for PostgreSQL schema design."
98
+ ```
99
+
100
+ **Superpowers**: [Superpowers](https://github.com/obra/superpowers) is a community skill registry. Search it:
101
+
102
+ ```bash
103
+ # If superpowers CLI or MCP is configured
104
+ npx skills search "react testing"
105
+ npx skills search "python api"
106
+ ```
107
+
108
+ **Manual discovery**: search GitHub and npm directly using patterns from `docs/research/README.md#Architecture Decision References`.
109
+
110
+ **Priority order**:
111
+ 1. `/find-skills` first โ€” fastest discovery, respects your tool environment.
112
+ 2. Superpowers registry โ€” broad community coverage.
113
+ 3. GitHub search โ€” when the first two miss niche domains.
114
+
115
+ **What to install**: after finding skills, add them to `.claude/skills/<name>/SKILL.md`. Follow `docs/harness/extension.md` for compatibility. Start with 1-2 skills per stack area; more is not better.
116
+
117
+ This scaffold includes built-in harness skills (`.claude/skills/harness-*`). Keep those. Add stack-specific ones alongside them.
118
+
47
119
  ## Optional Agent Assets
48
120
 
49
- 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.
121
+ After the product shape is known, Claude may also install or copy stack-specific agents, rules, and hooks into `.claude/`. Follow `docs/harness/extension.md` for every added asset.
50
122
 
51
123
  Examples:
52
124
 
@@ -56,14 +128,19 @@ This is a Python data product. Add data pipeline and pytest workflow agents.
56
128
  This is a Go service. Add API, security, and integration-test agents.
57
129
  ```
58
130
 
59
- ## Cleanup
131
+ ## Cleanup (Isolate & Remove)
132
+
133
+ This file is designed to be orphaned. When all configuration is complete:
60
134
 
61
- After bootstrap succeeds:
135
+ 1. Open `CLAUDE.md`. Delete the line: `If SETUP.md exists in the project root, read it first.`
136
+ 2. Delete this file.
62
137
 
63
138
  ```bash
64
139
  rm SETUP.md
65
140
  ```
66
141
 
142
+ After both steps, `SETUP.md` is fully isolated โ€” no file references it, no trace remains. You are free to delete it at any time. It is a bootstrap scaffold, not a permanent fixture.
143
+
67
144
  ---
68
145
 
69
146
  ## For Agents (Self-Bootstrapping)
package/templates/common/docs/README.md CHANGED
@@ -64,12 +64,16 @@ Load the matching row only. Add adjacent docs only when the loaded doc directly
64
64
 
65
65
  - Move phases in order unless the user asks for a fast lane.
66
66
  - Do not code before the PRD has MVP, non-goals, and acceptance criteria.
67
- - Do not cross a layer boundary without updating architecture or ports.
67
+ - Do not cross a layer boundary without reading `domain/ports.md` and updating architecture or ports.
68
+ - Before adding failure paths, read `harness/data-flow.md`.
69
+ - Before modifying stateful components, read `harness/state-machines.md`.
70
+ - Unsure whether to open a feature doc? Read `harness/agent-workflow.md` Section 1.
68
71
  - Do not spawn a subagent without a role, read boundary, write boundary, and return contract.
69
72
  - Do not run writing agents in parallel unless write sets are disjoint.
73
+ - Before coordinating multiple agents, fill `harness/PLAN.md#Parallel Dispatch` and follow `harness/dispatch.md`.
70
74
  - Do not add stack-specific agents or skills without following `harness/extension.md`.
71
75
  - Do not close work without tests or recorded manual verification.
72
- - Do not mark work `Verified` until evidence is recorded in `docs/harness/PLAN.md` or the feature doc.
76
+ - Do not mark work `Verified` until evidence is recorded in `harness/PLAN.md` or the feature doc.
73
77
  - Run `node scripts/validate-harness.mjs` for scaffold structure; run `node scripts/validate-harness.mjs --strict` after bootstrap and before release.
74
78
  - If a doc still has `{{...}}`, treat that section as a template, not project fact.
75
79
 
package/templates/common/docs/research/README.md CHANGED
@@ -109,6 +109,54 @@ Use these patterns when turning research into PRD or feature docs:
109
109
  - Product scope: [PRD.md](PRD.md).
110
110
  - Architecture consequences: `docs/harness/architecture.md` and `docs/domain/ports.md`.
111
111
 
112
+ ## Architecture Decision References
113
+
114
+ When filling `docs/harness/architecture.md`, `docs/domain/ports.md`, and `docs/research/research-results.md`, use these high-trust sources as starting points. Search within them; do not read them whole.
115
+
116
+ ### System Design & Architecture Patterns
117
+
118
+ | Source | Stars | What To Use It For |
119
+ |--------|-------|--------------------|
120
+ | [donnemartin/system-design-primer](https://github.com/donnemartin/system-design-primer) | 266k+ | System design fundamentals, trade-off frameworks, scalability patterns |
121
+ | [ByteByteGoHq/system-design-101](https://github.com/ByteByteGoHq/system-design-101) | 65k+ | Visual system design concepts, communication protocols, database patterns |
122
+ | [DovAmir/awesome-design-patterns](https://github.com/DovAmir/awesome-design-patterns) | 47k+ | Curated design patterns: general arch, cloud, serverless, microservices, front-end, security |
123
+ | [mehdihadeli/awesome-software-architecture](https://github.com/mehdihadeli/awesome-software-architecture) | high | Design patterns deep-dive: CQRS, Outbox, Saga, Circuit Breaker, BFF, scaling, caching |
124
+ | [ashishps1/awesome-system-design-resources](https://github.com/ashishps1/awesome-system-design-resources) | 30k+ | System design interview prep: networking, API design, database, caching, distributed systems |
125
+
126
+ ### Front-End Architecture
127
+
128
+ | Source | Stars | What To Use It For |
129
+ |--------|-------|--------------------|
130
+ | [greatfrontend/awesome-front-end-system-design](https://github.com/greatfrontend/awesome-front-end-system-design) | high | Front-end system design: news feed, e-commerce, chat, video streaming, SDUI |
131
+
132
+ ### Architecture Decision Records (ADR)
133
+
134
+ | Source | Purpose |
135
+ |--------|---------|
136
+ | [adr.github.io](https://adr.github.io) | ADR overview, templates (MADR, Nygard, Y-Statement), tooling |
137
+ | [architecture-decision-record/architecture-decision-record](https://github.com/architecture-decision-record/architecture-decision-record) | Canonical ADR repo with git-based workflow |
138
+ | [adr/madr](https://github.com/adr/madr) | Markdown Architectural Decision Records template |
139
+
140
+ ### Agent Skills (Stack-Specific)
141
+
142
+ > When the architecture stage reveals a specific stack, search for matching agent skills. Skills extend Claude Code / Codex with stack-aware patterns, testing conventions, and design rules.
143
+
144
+ | Source | Purpose |
145
+ |--------|---------|
146
+ | [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | Curated Claude Skills directory |
147
+ | [Composio โ€” Top Design Skills](https://composio.dev/content/top-design-skills) | UI/UX design skills for Claude Code and Codex |
148
+ | `npx skills search "<stack>"` | Built-in skill discovery (if available) |
149
+
150
+ Search patterns for agent skill discovery:
151
+
152
+ ```text
153
+ site:github.com "claude code" OR codex skill <stack> architecture
154
+ site:github.com SKILL.md <framework> design patterns
155
+ site:npmjs.com "claude-code" OR "codex" skill <domain>
156
+ ```
157
+
158
+ ---
159
+
112
160
  ## Method References
113
161
 
114
162
  - GitHub Spec Kit: spec-first phases and AI coding-agent workflow: https://github.github.com/spec-kit/