@veyralabs/venture-suite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 VeyraLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# venture-suite
+
+![npm](https://img.shields.io/npm/v/@veyralabs/venture-suite) ![license](https://img.shields.io/badge/license-MIT-green)
+
+Venture Intelligence pack for Claude Code. Validate startup and SaaS ideas before building - using real evidence from HN, Reddit, GitHub, and web search. No API keys required.
+
+Part of [VeyraSkills](https://github.com/veyralabsgroup/veyraskills) by [VeyraLabs](https://github.com/veyralabsgroup).
+
+## Install
+
+```bash
+npx @veyralabs/skills install venture-suite
+```
+
+## Skills included
+
+| Skill | What it does |
+|-------|-------------|
+| [venture-analyst](./venture-analyst/SKILL.md) | Four-phase idea validation: problem discovery, competitor intelligence, validation experiments, Bull/Bear/Judge verdict |
+
+## Usage
+
+```
+/venture-analyst A SaaS tool for X targeting Y customers
+```
+
+## Zero friction design
+
+No API keys. No paid accounts. No setup beyond `npm install`.
+
+The skill collects evidence from public sources (HN Algolia, Reddit, GitHub, DuckDuckGo, Google Trends) and auto-detects available enhancements silently - if you have Docker installed, it can launch SearXNG automatically for better search coverage.
+
+## License
+
+MIT. Built by [VeyraLabs](https://veyralabs.com).

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@veyralabs/venture-suite",
+  "version": "0.1.0",
+  "description": "Venture Intelligence pack for Claude Code - idea validation, competitor research, and Bull/Bear/Judge verdict",
+  "files": [
+    "venture-analyst/"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude-skill",
+    "agent-skill",
+    "startup-validation",
+    "market-research",
+    "idea-validation",
+    "lean-startup",
+    "saas-validation",
+    "ai-agents"
+  ],
+  "author": "VeyraLabs <hello@veyralabs.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veyralabsgroup/venture-suite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/veyralabsgroup/venture-suite/issues"
+  },
+  "homepage": "https://github.com/veyralabsgroup/venture-suite#readme"
+}

package/venture-analyst/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: venture-analyst
+description: Startup and SaaS idea validation. Researches market evidence, maps competitors, scores viability, and generates concrete validation experiments. Zero API keys required.
+---
+
+# Venture Analyst
+
+Research a startup or SaaS idea and determine if it's worth building. No fluff — real evidence from real sources.
+
+## What this does
+
+Four phases, each producing structured output:
+
+1. **Problem Discovery** - Find evidence the problem actually exists (Reddit, HN, GitHub issues)
+2. **Competitor Intelligence** - Map the landscape, find gaps, extract pricing signals
+3. **Validation Experiments** - Generate 3 prioritized experiments to test demand before building
+4. **Verdict** - Bull/Bear/Judge debate producing a final recommendation with confidence score
+
+## How to use
+
+Describe your idea. Include:
+- What it does (one sentence)
+- Who it's for (target customer)
+- What problem it solves
+
+Optional: budget for experiments, market type (B2C/B2B), known competitors.
+
+## Phase 1 — Problem Discovery
+
+**Goal:** Find evidence the problem is real and people talk about it unprompted.
+
+Use `scripts/sources.py` to collect evidence:
+
+```python
+from scripts.sources import search_hn, search_hn_comments, search_reddit, search_github_issues, get_trends
+
+# HN: find discussions, Show HN, Ask HN about the problem space
+hn_stories = search_hn(query, limit=20)
+hn_comments = search_hn_comments(query, min_points=3, limit=30)
+
+# Reddit: find complaints, questions, "is there a tool for X" posts
+reddit_posts = search_reddit(query, limit=25, timeframe="year")
+
+# GitHub: find feature requests and pain in related tools
+gh_issues = search_github_issues(query, limit=20)
+
+# Trends: is interest rising or declining?
+trend_data = get_trends(keyword)
+```
+
+**Synthesize findings:**
+
+Look for these signals (strongest first):
+- People spending money on bad solutions (evidence of willingness to pay)
+- Recurring complaints with no good answer
+- "Is there a tool that does X?" posts with many upvotes
+- GitHub issues with many reactions and no resolution
+- Rising trend line
+
+Red flags:
+- Zero discussion anywhere — not even a complaint
+- Problem exists but nobody's tried to solve it (often means it's not painful enough)
+- Only a few power users care, not a broad market
+
+**Output format:**
+```
+## Problem Evidence
+
+**Evidence Score:** [0-100] (use calculate_evidence_score())
+**Trend:** [rising/stable/declining/no_data]
+
+### What people say (direct quotes preferred)
+- [Source] "[quote or paraphrase]" — [upvotes/reactions]
+
+### Pain signals
+- [description of signal + source count]
+
+### Gaps found
+- [what existing solutions miss]
+```
+
+## Phase 2 — Competitor Intelligence
+
+**Goal:** Map who's already solving this. Find pricing, positioning gaps, weak points.
+
+```python
+from scripts.scraper import scrape_competitor
+from scripts.sources import search_github_repos, search_web
+
+# Find competitors via web and GitHub
+repos = search_github_repos(f"{idea} tool", limit=8)
+web_results = search_web(f"{idea} software alternatives", limit=8)
+
+# Scrape each competitor's pricing + positioning
+for url in competitor_urls:
+    data = scrape_competitor(url)
+    # data has: title, tagline, description, pricing, features, tech_stack
+```
+
+**Competitive map structure:**
+```
+| Name | Pricing | Target | Weakness | Stars |
+|------|---------|--------|----------|-------|
+| X    | $49/mo  | SMBs   | No API   | 2.1k  |
+```
+
+**Gaps to look for:**
+- Price ceiling: is there a tier missing?
+- Audience gap: power users vs beginners vs enterprise
+- Feature gap: what do G2/Reddit reviews complain about?
+- Distribution gap: who's not in a specific channel?
+
+**G2 reviews (when Playwright available):**
+```python
+from scripts.scraper import scrape_g2_reviews
+reviews = scrape_g2_reviews("https://www.g2.com/products/[product]/reviews")
+# Check for recurring "cons" patterns
+```
+
+**Output format:**
+```
+## Competitor Map
+
+### Direct competitors
+[table]
+
+### Indirect / adjacent
+[list with one-line descriptions]
+
+### Market gaps
+- Gap 1: [description + evidence]
+- Gap 2: [description + evidence]
+
+### Pricing landscape
+- Range: [$X - $Y/month]
+- Free tier pattern: [present/absent]
+- Typical model: [seat/flat/usage]
+```
+
+## Phase 3 — Validation Experiments
+
+**Goal:** Before writing code, find out if people will actually pay.
+
+```python
+from scripts.experiments import generate_experiments, format_experiment_output
+
+experiments = generate_experiments(
+    idea=idea,
+    target_customer=target,
+    market_type="b2b",  # or "b2c"
+    competition_level="medium",  # low/medium/high
+    budget="zero",  # zero / low / medium
+)
+
+print(format_experiment_output(experiments, idea))
+```
+
+Always present experiments in priority order. Cheapest + highest-signal first.
+
+**Mom Test enforcement** — when helping design interviews or outreach:
+- See `references/mom-test.md` for good vs bad questions
+- Detect and flag future-hypothetical questions ("would you use X?")
+- Replace with past-behavior questions ("how do you currently handle X?")
+
+## Phase 4 — Verdict
+
+**Goal:** Simulate a debate between Bull, Bear, and Judge. Reach a conclusion.
+
+### Bull case (write this first)
+- Strongest evidence for building it
+- Market timing arguments
+- Why this team / why now
+- Best-case scenario with numbers
+
+### Bear case (steelman the opposition)
+- Strongest evidence AGAINST
+- Why existing solutions might be good enough
+- Market risks, timing risks, competition risks
+- Why it might fail even if the problem is real
+
+### Judge verdict
+Read both cases. Apply these criteria:
+
+| Signal | Weight |
+|--------|--------|
+| Evidence score > 60 | +2 |
+| Trend = rising | +1 |
+| Competitors have clear weakness | +1 |
+| No dominant player (>50% market) | +1 |
+| B2B with willingness-to-pay signals | +1 |
+| Price ceiling exists | +1 |
+| Evidence score < 30 | -3 |
+| Trend = declining | -2 |
+| 1+ competitor with >100k users + free tier | -2 |
+| Problem is niche (<10k potential users) | -1 |
+
+**Verdict output:**
+```
+## Verdict
+
+**Recommendation:** [BUILD / VALIDATE FIRST / AVOID]
+**Confidence:** [High / Medium / Low]
+**Score:** [+N or -N]
+
+### Judge's reasoning
+[2-3 sentences. Direct. No hedging.]
+
+### If BUILD: suggested starting point
+[Specific first step. Not generic advice.]
+
+### If VALIDATE FIRST: critical unknown
+[The one thing that must be proven before spending time.]
+
+### If AVOID: core problem
+[Why specifically this fails. What would have to change.]
+```
+
+## Enhancement detection
+
+Run at session start to unlock better sources:
+
+```python
+from scripts.enhance_detect import detect_level, ensure_searxng, best_search
+
+env = detect_level()
+# Returns: docker, searxng, veyrascrape_mcp, github_token, exa_key, tavily_key, groq_key
+
+# If Docker available, auto-launch SearXNG for better web search
+if env["docker"] and not env["searxng"]:
+    ensure_searxng()  # silent, no user prompt
+
+# Use best available search
+results = best_search(query, env, limit=10)
+```
+
+**Level 1 (always works):** HN + Reddit + GitHub + ddgs + trendspyg
+**Level 2 (auto, no keys):** + SearXNG via Docker (if Docker installed)
+**Level 3 (optional keys):** + Exa, Tavily, GitHub authenticated, VeyraScrape MCP
+
+Never ask the user to set up API keys. Auto-detect and use what's available.
+
+## Evidence Score interpretation
+
+From `calculate_evidence_score()` in `sources.py`:
+
+| Score | Meaning |
+|-------|---------|
+| 0-20  | Weak - barely any signal. Rethink or pivot problem framing |
+| 21-40 | Thin - some signal but not convincing |
+| 41-60 | Moderate - proceed to competitor research |
+| 61-80 | Strong - real problem, real people care |
+| 81-100 | Very strong - validated pain, move to experiments immediately |
+
+## Methodology references
+
+- `references/lean-startup.md` - validated learning, MVP types, pivot signals
+- `references/customer-dev.md` - Steve Blank's 4 steps, problem interview structure
+- `references/mom-test.md` - good vs bad interview questions
+- `references/blue-ocean.md` - Value Curve, ERRC Grid, finding uncontested space
+- `references/traction.md` - 19 acquisition channels, Bullseye framework
+
+## Output principles
+
+1. Lead with evidence, not opinions
+2. Quote real sources (HN post, Reddit thread, GitHub issue)
+3. Be specific about numbers (upvotes, stars, $prices)
+4. Separate fact from inference clearly
+5. Bull/Bear before Verdict — don't skip the debate
+6. Verdict must commit to a recommendation — no "it depends" without specifics

package/venture-analyst/references/blue-ocean.md

@@ -0,0 +1,130 @@
+# Blue Ocean Strategy Reference
+
+W. Chan Kim & Renee Mauborgne, "Blue Ocean Strategy" (2005, updated 2015).
+
+## Core concept
+
+**Red Ocean:** existing market space. Competitors fight over same customers. Bloody from competition.
+**Blue Ocean:** new market space. Create demand, not fight for it.
+
+The goal: don't compete where everyone else is. Find (or create) a space where there's no direct competition.
+
+This is not about being "different" for its own sake. It's about finding where existing solutions fail enough customers that a new approach can win without fighting incumbents.
+
+## Value Innovation
+
+The foundation of blue ocean strategy. The simultaneous pursuit of:
+- **Differentiation** (more value for customers) AND
+- **Low cost** (lower cost to deliver)
+
+Most companies choose one. Blue ocean does both by eliminating or reducing what the industry assumes is necessary.
+
+Key: value innovation redefines what value means — it doesn't just add more features.
+
+## Value Curve
+
+A visual tool. X-axis: factors the industry competes on. Y-axis: level of investment/offering.
+
+Draw your value curve vs competitors:
+1. List all factors the industry competes on (price, features, quality, support, speed, etc.)
+2. Score each player 1-10 on each factor
+3. Connect the dots — that's the value curve
+
+**What to look for:**
+- Where are all competitors converging? (where you can differentiate)
+- Where is investment high but customers don't care? (where you can eliminate/reduce)
+- What do customers want that nobody offers? (where you can create/raise)
+
+**Signs of a blue ocean opportunity:**
+- Your curve looks completely different from competitors
+- You're investing in factors they don't even measure
+- You're not competing on any factor they compete on
+
+## ERRC Grid
+
+The strategic tool for creating a new value curve.
+
+| Action | Question | Why |
+|--------|----------|-----|
+| **Eliminate** | Which factors the industry takes for granted can be eliminated? | Remove cost + complexity customers don't value |
+| **Reduce** | Which factors should be reduced well below the industry standard? | Stop over-delivering where it doesn't matter |
+| **Raise** | Which factors should be raised well above the industry standard? | Solve what customers complain about |
+| **Create** | Which factors should be created that the industry has never offered? | Add new value that opens new demand |
+
+**How to use it for venture analysis:**
+
+Look at the competitor landscape from Phase 2. Fill the ERRC grid:
+- What do all competitors force customers to deal with? (Eliminate candidates)
+- Where are they all investing heavily but customers complain anyway? (Reduce candidates)
+- What do all G2/Reddit reviews say is missing? (Raise or Create candidates)
+
+## Three tiers of non-customers
+
+Incumbents focus on existing customers. Blue ocean looks at non-customers:
+
+**Tier 1 — "Soon-to-be" non-customers**
+On the edge of the market. Use existing solutions but reluctantly. Would switch if something better existed.
+- Find them: people who use tools but post complaints
+- Signal: "I use X but I hate Y"
+
+**Tier 2 — "Refusing" non-customers**
+Consciously choose not to use existing solutions. Have the problem but handle it differently.
+- Find them: "I could use X but I just [workaround] instead"
+- Signal: "I tried X but gave up because..."
+
+**Tier 3 — "Unexplored" non-customers**
+Never considered as customers. In other markets or segments entirely.
+- Find them: unexpected users of adjacent tools
+- Signal: people solving your problem with tools not built for it
+
+## Red vs Blue Ocean signals in research
+
+When analyzing a market, these signals matter:
+
+### Red Ocean signals (hard fight ahead)
+- 5+ competitors with similar positioning and pricing
+- Dominant player with >50% market share
+- Feature comparison tables are the main marketing tool
+- Price is primary differentiator
+- High churn across all players (no moat)
+- Reddit/HN: "X vs Y vs Z" comparison posts everywhere
+
+### Blue Ocean signals (opportunity)
+- People solve the problem with spreadsheets or manual processes
+- Niche community uses a tool far outside its intended purpose
+- The "best" solution is widely criticized for the same thing
+- Large group adjacent to current market who never adopted it
+- Incumbents focused on enterprise; SMB underserved (or vice versa)
+- Technology shift makes old assumptions invalid (mobile, AI, etc.)
+
+## Applying Blue Ocean to competitive analysis
+
+In Phase 2, after mapping competitors, ask:
+
+1. **Which axis can you ignore entirely?**
+   - E.g., all competitors compete on features — can you win on simplicity instead?
+
+2. **What do customers actually use vs what they pay for?**
+   - If pricing is based on features but customers only use 20% of them, price simplicity
+
+3. **What's the "tax" on using existing solutions?**
+   - Setup time, training required, integrations needed, contracts, support tickets
+   - Eliminate the tax
+
+4. **Who's locked out of the market?**
+   - High price, high complexity, enterprise-only contracts
+   - If you can serve them, they're Tier 2/3 non-customers
+
+## Value Curve template
+
+```
+Factor          | Competitor A | Competitor B | Our position
+----------------|-------------|-------------|-------------
+Price           | High        | Medium      | ?
+Ease of setup   | Hard        | Hard        | ?
+Feature breadth | Wide        | Wide        | ?
+Support         | Good        | Poor        | ?
+[key factor]    | ...         | ...         | ?
+```
+
+A good blue ocean position looks different from all others — not just slightly better.

package/venture-analyst/references/customer-dev.md

@@ -0,0 +1,147 @@
+# Customer Development Reference
+
+Steve Blank's framework. The complement to Lean Startup.
+Source: "The Four Steps to the Epiphany" (2005) and "The Startup Owner's Manual" (2012).
+
+## Core thesis
+
+Startups are not smaller versions of large companies. They exist to search for a repeatable, scalable business model — not to execute one. This search requires talking to customers before building.
+
+Most founders skip Step 1 and go straight to building. This is why most startups fail.
+
+## The four steps
+
+### Step 1 — Customer Discovery
+
+Validate that the problem exists and that your target customer experiences it.
+
+**What you're testing:**
+- Does the problem actually exist?
+- Is your target customer the right one?
+- Is this painful enough to pay to solve?
+
+**How:**
+- Interview 20-30 potential customers
+- Listen, don't pitch
+- Ask about their current behavior, not hypothetical preferences
+- See `references/mom-test.md` for interview technique
+
+**Pass criteria:**
+- Multiple customers describe the same problem unprompted
+- They have workarounds (evidence they tried to solve it)
+- They can quantify the cost (time, money, frustration)
+
+**Failure mode:** Founders who pitch instead of listen. "Nobody told me it was a bad idea" ≠ validation.
+
+### Step 2 — Customer Validation
+
+Prove the business model. Find repeatable sales. Find a path to revenue.
+
+**What you're testing:**
+- Will they actually pay?
+- Is the sales process repeatable?
+- Can you find customers without your personal network?
+
+**How:**
+- Get 3-5 paying customers (even at a discount or free for design partners)
+- Document the sales process step by step
+- Find what objections come up and how to overcome them
+
+**Pass criteria:**
+- Customers pay without you having to chase them hard
+- Different salespeople can close using the same process
+- Customer acquisition is possible outside warm intros
+
+**Failure mode:** Getting 3 customers who are personal favors. Real validation = strangers pay.
+
+### Step 3 — Customer Creation
+
+Shift from search to execution. Scale what worked in Step 2.
+
+**What you're doing:**
+- Pick one channel and scale it
+- Invest in marketing that repeats the validated sales motion
+- Build demand generation around the validated message
+
+**Only reach this step after Step 2 is solid.** Scaling a broken sales process just burns money.
+
+### Step 4 — Company Building
+
+Transition from startup to company. Build processes, teams, and systems.
+
+**Not relevant for early validation.** Focus on Steps 1 and 2 first.
+
+## Problem vs solution interviews
+
+Two different conversations. Don't mix them.
+
+### Problem interview
+
+Goal: validate the problem exists, understand current behavior.
+
+Structure:
+1. Intro (2 min): "I'm researching how people handle X. No product to sell."
+2. Background (5 min): "Tell me about your role. What does a typical day look like?"
+3. Story (10 min): "Tell me about the last time you dealt with X. Walk me through it."
+4. Pain exploration (10 min): "What's most frustrating about that? How do you handle it now?"
+5. Wrap-up (5 min): "Who else would I talk to about this?"
+
+**Do not:** mention your solution, ask hypotheticals, ask for feature preferences.
+
+### Solution interview
+
+Only run after problem is validated.
+
+Goal: validate your specific solution design.
+
+Structure:
+1. Problem recap (3 min): confirm they have the problem
+2. Demo/mockup (10 min): show the concept, let them react
+3. Reactions (10 min): "What would you do with this? What's confusing?"
+4. Willingness to pay (5 min): not "would you pay?" — "how much do you currently spend on this?"
+
+## Earlyvangelists
+
+The best early customers share all 5 traits:
+
+1. Have the problem
+2. Know they have the problem
+3. Actively searching for a solution
+4. Cobbled together a workaround
+5. Have budget to buy a solution
+
+Finding earlyvangelists is the goal of Steps 1-2. They'll put up with incomplete products, give feedback, and refer others.
+
+**Where to find them:** niche communities (subreddits, Slack groups, LinkedIn groups), people who asked public questions about the problem, power users of adjacent tools.
+
+## Beachhead market
+
+Don't try to reach everyone. Pick the smallest possible market where you can win completely.
+
+Criteria for a good beachhead:
+- Homogeneous needs (all have the same problem in the same way)
+- Word of mouth works within the group
+- Referenceable (customers are willing to be named)
+- Financially attractive enough to sustain the business
+
+**Classic mistake:** TAM is huge, so we'll target everyone. Result: message resonates with nobody.
+
+## Customer segments to validate
+
+For B2B especially, multiple people are involved in a purchase:
+
+- **User** - uses the product daily
+- **Influencer** - recommends or blocks purchase
+- **Recommender** - brings options to the decision maker
+- **Decision maker** - approves budget
+- **Economic buyer** - controls the money
+
+Your ICP might be the User but the Economic Buyer makes the call. Understand all of them before pricing or positioning.
+
+## Signals for pivot
+
+- 10+ interviews and nobody describes the same problem
+- Everyone says "that's interesting" but won't commit to a call with their boss
+- The workaround they use is good enough and they know it
+- Problem only affects extremely niche edge cases
+- The real buyer is different from who you expected