create-harness-vibe-coding 0.1.3 → 0.1.5

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,81 +94,93 @@ 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
+
+### Human
 
 ```bash
-# Interactive mode
+# Interactive mode — prompts for project name and directory
 npx create-harness-vibe-coding@latest
+```
 
-# Non-interactive (CI/CD)
-npx create-harness-vibe-coding@latest my-app ./dist/my-app
+### Agent / CI/CD
 
-# Always get the latest version
-npx create-harness-vibe-coding@latest my-project
+Agents and automation can skip all prompts with `-y`:
+
+```bash
+# One-liner with defaults (project name = my-vibe-project)
+npx create-harness-vibe-coding@latest -y
+
+# Named project, auto directory
+npx create-harness-vibe-coding@latest my-app -y
+
+# Named project, explicit directory
+npx create-harness-vibe-coding@latest my-app ./dist/my-app -y
 ```
 
+| Flag | Purpose |
+|------|---------|
+| `-y`, `--yes` | Skip all prompts. Uses positional args or defaults. |
+| `-h`, `--help` | Print usage and exit. |
+
+> [!TIP]
+> Agents should always pass `-y` to avoid hanging on interactive prompts.
+> If the agent needs to discover the CLI surface first, run with `--help`.
+
 ### 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.5",
+  "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

@@ -4,29 +4,65 @@ import pc from 'picocolors';
 import { askProjectName, askTargetDir } from './prompts.js';
 import { generate } from './generator.js';
 
-// Parse CLI args for non-interactive mode
-const args = process.argv.slice(2);
-const argName = args[0];
-const argDir = args[1];
+// ── CLI flags ──────────────────────────────────────────────
+const raw = process.argv.slice(2);
+const flags = new Set(raw.filter(a => a.startsWith('-')));
+const has = name => flags.has(name) || flags.has(`--${name}`);
+const showHelp = has('h') || has('help');
+const skipPrompts = has('y') || has('yes');
+
+if (showHelp) {
+  console.log('');
+  console.log('  create-harness-vibe-coding');
+  console.log('');
+  console.log('  Usage:');
+  console.log('    npx create-harness-vibe-coding@latest [project-name] [target-dir] [flags]');
+  console.log('');
+  console.log('  Arguments:');
+  console.log('    project-name   Name for the new project (default: my-vibe-project)');
+  console.log('    target-dir     Directory to create the project in (default: ./<project-name>)');
+  console.log('');
+  console.log('  Flags:');
+  console.log('    -y, --yes      Skip all prompts, use defaults or provided args');
+  console.log('    -h, --help     Show this help');
+  console.log('');
+  console.log('  Examples:');
+  console.log('    npx create-harness-vibe-coding@latest');
+  console.log('    npx create-harness-vibe-coding@latest -y');
+  console.log('    npx create-harness-vibe-coding@latest my-project');
+  console.log('    npx create-harness-vibe-coding@latest my-project ./dist/my-project -y');
+  console.log('');
+  process.exit(0);
+}
+
+// Positional args (non-flag)
+const positional = raw.filter(a => !a.startsWith('-'));
+const argName = positional[0];
+const argDir = positional[1];
+
+const DEFAULT_NAME = 'my-vibe-project';
 
 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('');
 
 let projectName, targetDir;
 
-// Non-interactive mode: use CLI args or defaults
-if (argName) {
-  projectName = argName;
+// Non-interactive: positionals provided OR -y/--yes flag set
+if (argName || skipPrompts) {
+  projectName = argName || DEFAULT_NAME;
   targetDir = argDir || `./${projectName}`;
 
   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/')}`);
+  if (skipPrompts) {
+    console.log(`  Mode        ${pc.dim('non-interactive (-y)')}`);
+  }
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log('');
 
@@ -52,7 +88,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 +115,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`