novahiz 0.1.0

package/bundled-skills/prospecting/references/local-prospecting.md

@@ -0,0 +1,165 @@
+# Local SMB Prospecting Reference
+
+For when the user sells to local small businesses — shops, gyms, restaurants, salons, clinics, professional services, contractors, real estate, fitness studios, dental practices.
+
+Adapted from and generalized beyond the local-client-prospector pattern (browser-assisted discovery + website status classification + proximity scoring).
+
+---
+
+## ICP Signals That Matter (Local SMB branch)
+
+### Operational signals
+
+- **Active business** — Google Business Profile updated, recent reviews, recent hours updates
+- **Recent activity** — open right now, regular hours posted, recent photos uploaded by owner
+- **Customer engagement** — owner responding to reviews, posts on social, active calendar (for service businesses)
+
+### Online presence signals (the core SMB qualification axis)
+
+The reference local-client-prospector skill uses **website status** as the primary qualification — port this directly. Four classifications:
+
+| Status | Definition | Typical outcome |
+|--------|-----------|-----------------|
+| **No site found** | No credible standalone website after cross-checked search | **Hot prospect** for web/marketing service |
+| **Social only** | Facebook, Instagram, WhatsApp, Linktree, booking portal, marketplace page only — no standalone site | **Hot prospect** for web/marketing service |
+| **Weak site** | Standalone site exists but outdated, broken, very thin, non-mobile-friendly, or missing clear contact/conversion flow | **Warm prospect** for refresh / rebuild service |
+| **Has site** | Credible, modern standalone site exists | **Low prospect** unless other signals apply (e.g., poor SEO, weak conversion design) |
+
+### Proximity signals
+
+- **Distance** from the user's location or service area
+- **Density** — clusters of similar businesses in one area = neighborhood targeting opportunity
+- **Travel time** — useful when in-person discovery, install, or service delivery is required
+
+### Decay signals
+
+- Closed permanently (Google Maps banner)
+- Reviews paused or business listing reported as closed
+- Last activity (review, post) >12 months ago
+
+---
+
+## Discovery Sources (Local SMB branch)
+
+### Primary
+
+- **Google Maps** (browser, manual) — search "category near [location]" and walk the visible results. Cross-check details. Don't bulk-extract.
+- **Yelp** — secondary verification; complementary categories
+- **Bing Local / Apple Maps** — different coverage on smaller businesses
+- **Facebook Pages search** — many SMBs are Facebook-only
+
+### Cross-verification
+
+- **Business's own website** (if any)
+- **Industry directories** (e.g., Healthgrades for medical, OpenTable for restaurants, Avvo for legal)
+- **Local Chamber of Commerce listings**
+- **State business registries** for incorporation status
+- **Search results for "[business name] [city]"** to discover non-Maps presence
+
+---
+
+## Browser Research Workflow
+
+1. Open a browser and search Google Maps for the category near `base_location`
+2. Build a candidate list from visible local results, search results, and public directories
+3. For each candidate, inspect public sources to fill required fields
+4. Search the exact business name plus city/town to check whether a standalone website exists
+5. Classify website status per the table above
+6. Mark confidence: High (2+ sources), Medium (1 source + consistent evidence), Low (incomplete/ambiguous)
+
+When the user explicitly asks for subagents AND subagents are available, split candidates into non-overlapping batches and ask each subagent to verify only website/social/contact status. Don't use subagents for the primary search if it slows progress.
+
+### Optional: programmatic verification with Firecrawl or Browserbase
+
+Once you have a candidate's website URL (found via manual Maps/Yelp discovery), you can speed up website-status classification by hitting the URL programmatically:
+
+- **Firecrawl** for simple "is this site live, modern, mobile-friendly, conversion-flow-equipped" reads — returns clean markdown you can inspect
+- **Browserbase** when the candidate site requires JS rendering, has a cookie consent dialog, or you need session state
+
+**Strict line**: use these on the individual business's URL. **Don't** point them at Google Maps, Yelp, or any platform whose ToS prohibits bulk extraction — discovery stays manual.
+
+See [data-sources.md](data-sources.md) for setup details.
+
+---
+
+## Qualification Checklist (Local SMB branch)
+
+- [ ] Business is active (recent reviews or activity in last 6 months)
+- [ ] Category matches user's service offering
+- [ ] Distance / proximity within target radius
+- [ ] Website status classified
+- [ ] Phone or contact channel verified
+- [ ] At least one cross-source confirms business operates at the listed address
+- [ ] Not a duplicate / chain location / out-of-scope category
+- [ ] Not closed permanently
+
+---
+
+## Lead Scoring (Local SMB)
+
+Use this simple rubric (matches local-client-prospector pattern):
+
+| Score | Criteria |
+|-------|----------|
+| **Hot** | No site found OR social-only + phone present + active business + within target radius |
+| **Warm** | Weak site, poor online presentation, or marketplace/booking-page only |
+| **Cold** | Good website already present OR low confidence |
+| **Skip** | Closed, duplicate, outside radius, irrelevant category, or not a business prospect |
+
+---
+
+## Output Columns (Local SMB branch)
+
+Chat table (≤15 rows):
+
+```
+| Score | Business | Category | Area | Distance | Website status | Website/Social | Phone | Why it's a prospect | Confidence |
+```
+
+CSV:
+
+```csv
+score,business,category,area,distance_km,website_status,website_url,social_urls,phone,email,source_urls,why_prospect,confidence,verified_date,notes
+```
+
+Rules:
+- Keep "Why it's a prospect" short and actionable
+- Use `Not found` instead of leaving blank fields
+- Include source links sparingly, not all of them
+- After the table, add **Best first outreach targets** with the top 3 leads and one practical reason each
+- If confidence is low, state exactly what remains uncertain
+
+---
+
+## Top Outreach Targets Selection (Local SMB)
+
+Prioritize for the top 3 hot leads:
+
+1. **No site / social only + phone present** = clearest service opportunity
+2. **High review count** = active, established business with real customers
+3. **Owner-responded reviews** = engaged owner = more likely to evaluate a vendor
+4. **Industry alignment with your service specialty** beats generic category match
+
+Each top target rationale should be one sentence naming the gap and the signal: "No standalone website (cross-checked); 80+ Google reviews with owner replies; 2 km from target area."
+
+---
+
+## Compliance Notes (Local SMB-specific)
+
+The local branch is the most scraping-sensitive of the three motions. Specifically:
+
+- **Google Maps Terms of Service** prohibit bulk extraction. Treat browser visits as research, not as data acquisition.
+- **Don't store full Google Maps Place IDs in your CRM** — the ToS limits storage of Maps data.
+- **Public business contact channels only**: published phone, contact form, info@ email. Don't reach individual employees through their personal channels.
+- **Owner/operator name when published on the business's own site** is OK to use. If you only got it from LinkedIn, mark the source.
+
+---
+
+## Common Mistakes (Local SMB)
+
+1. **Bulk-scraping Google Maps** — fastest way to violate ToS and lose the research channel.
+2. **Treating Google Maps data as truth** — listings go stale. Cross-check hours, status, and reviews.
+3. **Skipping the website status cross-check** — finding "no site" on Maps doesn't mean no site exists; do an exact-name web search before classifying.
+4. **Targeting only the largest businesses** — they're already covered by other providers. The 2–5 employee SMBs are the under-served opportunity.
+5. **Generic outreach to all hot leads** — local SMBs respond better to outreach that names their specific gap ("I noticed your menu isn't visible on mobile") than generic pitches.
+6. **Ignoring chains and franchises** as Skip — sometimes the franchisee is the buyer and they have local marketing authority. Verify before skipping.

package/bundled-skills/prospecting/references/saas-prospecting.md

@@ -0,0 +1,123 @@
+# SaaS Prospecting Reference
+
+For when the user sells SaaS or digital services to other SaaS companies / digital businesses.
+
+---
+
+## ICP Signals That Matter (SaaS branch)
+
+Beyond standard firmographics (industry, size, geography), SaaS prospects are qualified by:
+
+### Technographic signals
+
+- **Tech stack** — do they use complementary tools (your integration target) or competing tools (a switch opportunity)?
+- **Recent stack changes** — adding/removing tools signals active vendor evaluation
+- **Custom-built vs off-the-shelf** — DIY tooling often means a buyer who'd benefit from your product
+- **Free/freemium plan signals** — using a free competitor means they may be ready to upgrade
+
+### Growth signals
+
+- **Funding round** — Series A / B / C in last 6 months = budget + new hires + tool needs
+- **Headcount growth** — 10%+ growth in last quarter signals scaling pressure
+- **Hiring signals** — specific role openings (e.g., "Head of RevOps" → ICP for revops tooling)
+- **Product velocity** — frequent shipping, new features, blog posts = healthy growth motion
+- **Open positions for your buyer's role** — if you sell to Marketing Ops and they're hiring one, that's a signal
+
+### Decay signals (downgrade scoring)
+
+- Layoffs in target department
+- Funding round >2 years ago with no follow-up
+- Product hasn't shipped in 6+ months
+- Team page shows founders only (very early — may not have budget)
+
+---
+
+## Discovery Sources (SaaS branch)
+
+Combine 2+ sources for cross-verification.
+
+### Tier 1 — primary discovery
+
+- **Apollo**: firmographic + technographic + contact data. Good for building large initial lists.
+- **Clay**: waterfall enrichment, custom scoring, multi-source merges. Best for high-quality smaller lists.
+- **ZoomInfo**: enterprise-grade firmographic + intent signals. Expensive; mid-market+.
+- **LinkedIn Sales Navigator**: decision-maker mapping. Use manually, never bulk scrape.
+
+### Tier 2 — technographic / growth signals
+
+- **BuiltWith**: tech stack lookups, find sites using specific tools
+- **Wappalyzer**: free browser extension + API; lighter tech stack signal
+- **Crunchbase**: funding rounds, headcount, founders
+- **Pitchbook**: deeper investor data (enterprise/paid)
+- **ProductHunt**: recent launches, builder audience
+- **Hacker News / Show HN**: technical builders launching products
+
+### Tier 3 — buying signals
+
+- **Job boards** (LinkedIn Jobs, Indeed, AngelList): role openings as signals
+- **RB2B / Clearbit Reveal**: visitor identification (warm anonymous traffic)
+- **GitHub stars/forks of competitor or adjacent repos**: developer-level intent signal (see `tools/integrations/github.md` and the `github-prospects.js` CLI). Especially strong for dev-tool SaaS — a developer who starred `vercel/next.js` last week is in-market for adjacent Next.js infrastructure.
+- **Recent blog posts / changelog**: product direction signals
+- **G2 reviews mentioning competitor switches**: explicit dissatisfaction signal
+
+#### GitHub prospecting pattern (when audience is developers)
+
+For dev-tool SaaS, GitHub is one of the highest-quality discovery channels:
+
+1. Identify 3–5 "anchor" repos: your direct competitors, your category leader, complementary tools your buyer uses
+2. Pull stargazers (or forks for stronger intent) via `node tools/clis/github-prospects.js stargazers <owner/repo> --enrich --with-company --format csv`
+3. Filter to users with `company` set — these are the easiest to enrich downstream
+4. Pair with Apollo/Clay/Hunter to lookup email by name + company
+5. Validate with Truelist before adding to outreach list
+
+Tradeoffs: GitHub yields email for only ~5–20% of users directly. The strength is the signal quality — a stargazer of a niche dev tool is genuinely in-market in a way Apollo firmographics alone can't tell you.
+
+---
+
+## Qualification Checklist (SaaS branch)
+
+For each candidate, verify:
+
+- [ ] Industry vertical matches ICP
+- [ ] Company size (headcount) within range
+- [ ] Tech stack includes (or notably excludes) a target technology
+- [ ] Funding stage matches buyer maturity
+- [ ] At least one growth signal in last 90 days (funding, hiring, product velocity)
+- [ ] Decision-maker role exists at the company (named or inferable from job listings)
+- [ ] Email contact verifiable
+- [ ] No disqualifiers (closed, acquired-and-paused, layoffs, ICP miss)
+
+---
+
+## Output Columns (SaaS branch)
+
+Recommended CSV columns:
+
+```csv
+score,company,domain,industry,size_band,country,funding_stage,last_round_date,tech_stack_match,signal,signal_date,contact_name,contact_title,contact_email,email_status,linkedin_url,source_urls,why_prospect,confidence,verified_date,notes
+```
+
+For chat table, condense to: Score | Company | Industry | Size | Signal | Contact | Email status | Confidence.
+
+---
+
+## Top Outreach Targets Selection (SaaS)
+
+Prioritize for the top 3–5 hot leads:
+
+1. **Strongest signal recency** — funding 30 days ago beats funding 9 months ago
+2. **Tech stack match strength** — known integration partner beats inferred fit
+3. **Decision-maker named with verified email** — beats role-pattern-guessed email
+4. **Multi-source confidence** — both Apollo + Crunchbase agree beats one source
+
+Each top target gets a one-sentence outreach rationale that names the specific signal: "Raised Series B 30 days ago; hiring Head of RevOps; verified VP of Ops email."
+
+---
+
+## Common Mistakes (SaaS)
+
+1. **Buying lists from Apollo wholesale** without re-verifying email and re-checking firmographics. Stale data is the norm.
+2. **Treating tech stack data as 100% accurate**. BuiltWith and Wappalyzer miss things; Clay's waterfalls miss things. Cross-check.
+3. **Targeting Series C+ for early-stage SaaS sellers**. The buyer profile is wrong — too many procurement hoops, too much red tape.
+4. **Targeting Series Pre-Seed seed** for products requiring meaningful budget. They have neither budget nor evaluator bandwidth.
+5. **Ignoring intent data when it exists** (ZoomInfo Intent, 6sense, etc.) — pre-warm signals beat cold every time.

package/bundled-skills/refactor-safely/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: refactor-safely
+description: Plan and execute safe refactoring using dependency analysis
+---
+
+## Refactor Safely
+
+Use the knowledge graph to plan and execute refactoring with confidence.
+
+### Steps
+
+1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions.
+2. Use `refactor_tool` with mode="dead_code" to find unreferenced code.
+3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations.
+4. Use `apply_refactor_tool` with the refactor_id to apply renames.
+5. After changes, run `detect_changes_tool` to verify the refactoring impact.
+
+### Safety Checks
+
+- Always preview before applying (rename mode gives you an edit list).
+- Check `get_impact_radius_tool` before major refactors.
+- Use `get_affected_flows_tool` to ensure no critical paths are broken.
+- Run `find_large_functions_tool` to identify decomposition targets.
+
+## Token Efficiency Rules
+- Start with `get_minimal_context_tool(task="<your task>")` before other graph tools.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
+- Read the implementation and its tests before changing code. The graph narrows scope; it does not replace the source.

package/bundled-skills/review-changes/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: review-changes
+description: Perform a structured code review using change detection and impact
+---
+
+## Review Changes
+
+Perform a thorough, risk-aware code review using the knowledge graph.
+
+### Steps
+
+1. Run `detect_changes_tool` to get risk-scored change analysis.
+2. Run `get_affected_flows_tool` to find impacted execution paths.
+3. For each high-risk function, run `query_graph_tool` with pattern="tests_for" to check test coverage.
+4. Run `get_impact_radius_tool` to understand the blast radius.
+5. For any untested changes, suggest specific test cases.
+
+### Output Format
+
+Provide findings grouped by risk level (high/medium/low) with:
+- What changed and why it matters
+- Test coverage status
+- Suggested improvements
+- Overall merge recommendation
+
+## Token Efficiency Rules
+- Start with `get_minimal_context_tool(task="<your task>")` before other graph tools.
+- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
+- Read the implementation and its tests before changing code. The graph narrows scope; it does not replace the source.

package/bundled-skills/review-delta/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: review-delta
+description: Review only changes since last commit using impact analysis. Token-efficient delta review with automatic blast-radius detection.
+argument-hint: "[file or function name]"
+---
+
+# Review Delta
+
+Perform a focused, token-efficient code review of only the changed code and its blast radius.
+
+**Token optimization:** Before starting, call `get_docs_section_tool(section_name="review-delta")` for the optimized workflow. Use ONLY changed nodes + 2-hop neighbors in context.
+
+## Steps
+
+1. **Ensure the graph is current** by calling `build_or_update_graph_tool()` (incremental update).
+
+2. **Get review context** by calling `get_review_context_tool()`. This returns:
+   - Changed files (auto-detected from git diff)
+   - Impacted nodes and files (blast radius)
+   - Source code snippets for changed areas
+   - Review guidance (test coverage gaps, wide impact warnings, inheritance concerns)
+
+3. **Analyze the blast radius** by reviewing the `impacted_nodes` and `impacted_files` in the context. Focus on:
+   - Functions whose callers changed (may need signature/behavior verification)
+   - Classes with inheritance changes (Liskov substitution concerns)
+   - Files with many dependents (high-risk changes)
+
+4. **Perform the review** using the context. For each changed file:
+   - Review the source snippet for correctness, style, and potential bugs
+   - Check if impacted callers/dependents need updates
+   - Verify test coverage using `query_graph_tool(pattern="tests_for", target=<function_name>)`
+   - Flag any untested changed functions
+
+5. **Report findings** in a structured format:
+   - **Summary**: One-line overview of the changes
+   - **Risk level**: Low / Medium / High (based on blast radius)
+   - **Issues found**: Bugs, style issues, missing tests
+   - **Blast radius**: List of impacted files/functions
+   - **Recommendations**: Actionable suggestions
+
+## Advantages Over Full-Repo Review
+
+- Only sends changed + impacted code to the model (5-10x fewer tokens)
+- Automatically identifies blast radius without manual file searching
+- Provides structural context (who calls what, inheritance chains)
+- Flags untested functions automatically

package/bundled-skills/review-pr/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: review-pr
+description: Review a PR or branch diff using the knowledge graph for full structural context. Outputs a structured review with blast-radius analysis.
+argument-hint: "[PR number or branch name]"
+---
+
+# Review PR
+
+Perform a comprehensive code review of a pull request or branch diff using the knowledge graph.
+
+**Token optimization:** Before starting, call `get_docs_section_tool(section_name="review-pr")` for the optimized workflow. Never include full files unless explicitly asked.
+
+## Steps
+
+1. **Identify the changes** for the PR:
+   - If a PR number or branch is provided, use `git diff main...<branch>` to get changed files
+   - Otherwise auto-detect from the current branch vs main/master
+
+2. **Update the graph** by calling `build_or_update_graph_tool(base="main")` to ensure the graph reflects the current state.
+
+3. **Get the full review context** by calling `get_review_context_tool(base="main")`:
+   - This uses `main` (or the specified base branch) as the diff base
+   - Returns all changed files across all commits in the PR
+
+4. **Analyze impact** by calling `get_impact_radius_tool(base="main")`:
+   - Review the blast radius across the entire PR
+   - Identify high-risk areas (widely depended-upon code)
+
+5. **Deep-dive each changed file**:
+   - Read the full source of files with significant changes
+   - Use `query_graph_tool(pattern="callers_of", target=<func>)` for high-risk functions
+   - Use `query_graph_tool(pattern="tests_for", target=<func>)` to verify test coverage
+   - Check for breaking changes in public APIs
+
+6. **Generate structured review output**:
+
+   ```
+   ## PR Review: <title>
+
+   ### Summary
+   <1-3 sentence overview>
+
+   ### Risk Assessment
+   - **Overall risk**: Low / Medium / High
+   - **Blast radius**: X files, Y functions impacted
+   - **Test coverage**: N changed functions covered / M total
+
+   ### File-by-File Review
+   #### <file_path>
+   - Changes: <description>
+   - Impact: <who depends on this>
+   - Issues: <bugs, style, concerns>
+
+   ### Missing Tests
+   - <function_name> in <file> - no test coverage found
+
+   ### Recommendations
+   1. <actionable suggestion>
+   2. <actionable suggestion>
+   ```
+
+## Tips
+
+- For large PRs, focus on the highest-impact files first (most dependents)
+- Use `semantic_search_nodes_tool` to find related code the PR might have missed
+- Check if renamed/moved functions have updated all callers