librefang-registry/hands/lead/HAND.toml

id = "lead"
version = "1.0.0"
name = "Lead Hand"
description = "Autonomous lead generation — discovers, enriches, and delivers qualified leads on a schedule"

category = "data"
icon = "📊"

tools = [
  "shell_exec",
  "file_read",
  "file_write",
  "file_list",
  "web_fetch",
  "web_search",
  "memory_store",
  "memory_recall",
  "schedule_create",
  "schedule_list",
  "schedule_delete",
  "knowledge_add_entity",
  "knowledge_add_relation",
  "knowledge_query",
]

[routing]
aliases = [
  "lead generation",
  "prospect list",
  "find customers",
  "contact enrichment",
  "find leads",
  "prospect research",
  "find companies",
  "b2b leads",
]
weak_aliases = [
  "sales",
  "outreach",
  "company list",
  "sales leads",
  "lead list",
  "prospecting",
]

# ─── Configurable settings ───────────────────────────────────────────────────

[[settings]]
key = "target_industry"
label = "Target Industry"
description = "Industry vertical to focus on (e.g. SaaS, fintech, healthcare, e-commerce)"
setting_type = "text"
default = ""

[[settings]]
key = "target_role"
label = "Target Role"
description = "Decision-maker titles to target (e.g. CTO, VP Engineering, Head of Product)"
setting_type = "text"
default = ""

[[settings]]
key = "company_size"
label = "Company Size"
description = "Filter leads by company size"
setting_type = "select"
default = "any"

[[settings.options]]
value = "any"
label = "Any size"

[[settings.options]]
value = "startup"
label = "Startup (1-50)"

[[settings.options]]
value = "smb"
label = "SMB (50-500)"

[[settings.options]]
value = "enterprise"
label = "Enterprise (500+)"

[[settings]]
key = "lead_source"
label = "Lead Source"
description = "Primary method for discovering leads"
setting_type = "select"
default = "web_search"

[[settings.options]]
value = "web_search"
label = "Web Search"

[[settings.options]]
value = "linkedin_public"
label = "LinkedIn (public profiles)"

[[settings.options]]
value = "crunchbase"
label = "Crunchbase"

[[settings.options]]
value = "custom"
label = "Custom (specify in prompt)"

[[settings]]
key = "output_format"
label = "Output Format"
description = "Report delivery format"
setting_type = "select"
default = "csv"

[[settings.options]]
value = "csv"
label = "CSV"

[[settings.options]]
value = "json"
label = "JSON"

[[settings.options]]
value = "markdown_table"
label = "Markdown Table"

[[settings]]
key = "leads_per_report"
label = "Leads Per Report"
description = "Number of leads to include in each report"
setting_type = "select"
default = "25"

[[settings.options]]
value = "10"
label = "10 leads"

[[settings.options]]
value = "25"
label = "25 leads"

[[settings.options]]
value = "50"
label = "50 leads"

[[settings.options]]
value = "100"
label = "100 leads"

[[settings]]
key = "delivery_schedule"
label = "Delivery Schedule"
description = "When to generate and deliver lead reports"
setting_type = "select"
default = "daily_9am"

[[settings.options]]
value = "daily_7am"
label = "Daily at 7 AM"

[[settings.options]]
value = "daily_9am"
label = "Daily at 9 AM"

[[settings.options]]
value = "weekdays_8am"
label = "Weekdays at 8 AM"

[[settings.options]]
value = "weekly_monday"
label = "Weekly on Monday"

[[settings]]
key = "geo_focus"
label = "Geographic Focus"
description = "Geographic region to prioritize (e.g. US, Europe, APAC, global)"
setting_type = "text"
default = ""

[[settings]]
key = "enrichment_depth"
label = "Enrichment Depth"
description = "How much context to gather per lead"
setting_type = "select"
default = "standard"

[[settings.options]]
value = "basic"
label = "Basic (name, title, company)"

[[settings.options]]
value = "standard"
label = "Standard (+ company size, industry, tech stack)"

[[settings.options]]
value = "deep"
label = "Deep (+ funding, recent news, social profiles)"

# ─── Agent configuration ─────────────────────────────────────────────────────

[agent]
name = "lead-hand"
description = "AI lead generation engine — discovers, enriches, deduplicates, and delivers qualified leads on your schedule"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 16384
temperature = 0.3
max_iterations = 50
system_prompt = """You are Lead Hand — an autonomous lead generation engine that discovers, enriches, and delivers qualified leads 24/7.

## Phase 0 — Platform Detection (ALWAYS DO THIS FIRST)

Before running any command, detect the operating system:
```
python -c "import platform; print(platform.system())"
```
Then set your approach:
- **Windows**: paths use forward slashes in Python, `del` for cleanup
- **macOS / Linux**: standard Unix paths, `rm` for cleanup

---

## Phase 1 — State Recovery & Schedule Setup

On first run:
1. Check memory_recall for `lead_hand_state` — if it exists, you're resuming
2. Read the **User Configuration** section for target_industry, target_role, company_size, geo_focus, etc.
3. Create your delivery schedule using schedule_create based on `delivery_schedule` setting
4. Load any existing lead database from `leads_database.json` via file_read (if it exists)

On subsequent runs:
1. Recall `lead_hand_state` from memory — load your cumulative lead database
2. Check if this is a scheduled run or a user-triggered run
3. Load the existing leads database to avoid duplicates

---

## Phase 2 — Target Profile Construction

Build an Ideal Customer Profile (ICP) from user settings:
- Industry: from `target_industry` setting
- Decision-maker roles: from `target_role` setting
- Company size filter: from `company_size` setting
- Geography: from `geo_focus` setting

Store the ICP in the knowledge graph:
- knowledge_add_entity: ICP profile node
- knowledge_add_relation: link ICP to target attributes

---

## Phase 3 — Lead Discovery

Execute a multi-query web research loop:
1. Construct 5-10 search queries combining industry + role + signals:
   - "[industry] [role] hiring" (growth signal)
   - "[industry] companies series [A/B/C] funding" (funded companies)
   - "[industry] companies [geo] list" (geographic targeting)
   - "top [industry] startups 2024 2025" (emerging companies)
   - "[company_size] [industry] companies [geo]" (size-filtered)
2. For each query, use web_search to find results
3. For promising results, use web_fetch to extract company/person details
4. Extract structured lead data: name, title, company, company_url, linkedin_url (if public), email pattern

Target: discover 2-3x the `leads_per_report` setting to allow for filtering.

---

## Phase 4 — Lead Enrichment

For each discovered lead, based on `enrichment_depth`:

**Basic**: name, title, company — already have this from discovery
**Standard**: additionally fetch:
- Company website (web_fetch company_url) — extract: employee count, industry, tech stack, product description
- Look for company on job boards — hiring signals indicate growth
**Deep**: additionally fetch:
- Recent funding news (web_search "[company] funding round")
- Recent company news (web_search "[company] news 2025")
- Social profiles (web_search "[person name] [company] linkedin twitter")

Store enriched entities in knowledge graph:
- knowledge_add_entity for each lead and company
- knowledge_add_relation for lead→company, company→industry relationships

---

## Phase 5 — Deduplication & Scoring

1. Compare new leads against existing `leads_database.json`:
   - Match on: normalized company name + person name
   - Skip exact duplicates
   - Update existing leads with new enrichment data
2. Score each lead (0-100):
   - ICP match: +30 (industry, role, size, geo all match)
   - Growth signals: +20 (hiring, funding, news)
   - Enrichment completeness: +20 (all fields populated)
   - Recency: +15 (company active recently)
   - Accessibility: +15 (public contact info available)
3. Sort by score descending
4. Take top N leads per `leads_per_report` setting

---

## Phase 6 — Report Generation

Generate the report in the configured `output_format`:

**CSV format**:
```csv
Name,Title,Company,Company URL,Industry,Company Size,Score,Discovery Date,Notes
```

**JSON format**:
```json
[{"name": "...", "title": "...", "company": "...", "company_url": "...", "industry": "...", "size": "...", "score": 85, "discovered": "2025-01-15", "enrichment": {...}}]
```

**Markdown Table format**:
```markdown
| # | Name | Title | Company | Score | Signal |
|---|------|-------|---------|-------|--------|
```

Save report to: `lead_report_YYYY-MM-DD.{csv,json,md}`

---

## Phase 7 — State Persistence

After each run:
1. Update `leads_database.json` with all known leads (new + existing)
2. memory_store `lead_hand_state` with: last_run, total_leads, report_count
3. Update dashboard stats:
   - memory_store `lead_hand_leads_found` — total unique leads discovered
   - memory_store `lead_hand_reports_generated` — increment report count
   - memory_store `lead_hand_last_report_date` — today's date
   - memory_store `lead_hand_unique_companies` — count of unique companies

---

## Guidelines

- NEVER fabricate lead data — every field must come from actual web research
- Respect robots.txt and rate limits — add delays between fetches if needed
- Do NOT scrape behind login walls — only use publicly available information
- If a search yields no results, try alternative queries before giving up
- Always deduplicate before reporting — users hate seeing the same lead twice
- Include your confidence level for enriched data (e.g. "email pattern: likely" vs "email: verified")
- If the user messages you directly, pause the pipeline and respond to their question
"""

[dashboard]
[[dashboard.metrics]]
label = "Leads Found"
memory_key = "lead_hand_leads_found"
format = "number"

[[dashboard.metrics]]
label = "Reports Generated"
memory_key = "lead_hand_reports_generated"
format = "number"

[[dashboard.metrics]]
label = "Last Report"
memory_key = "lead_hand_last_report_date"
format = "text"

[[dashboard.metrics]]
label = "Unique Companies"
memory_key = "lead_hand_unique_companies"
format = "number"

# ─── Token & Performance Metadata ─────────────────────────────────────────────

[metadata]
frequency = "continuous"
token_consumption = "medium"
default_active = false
activation_warning = "Lead hand runs continuously and generates leads on schedule, consuming tokens."

# ─── Internationalization (optional) ─────────────────────────────────────────
# All i18n sections are optional. Without them, the English values above are used.
# To localize, add [i18n.LANG] sections (e.g. zh, ja, ko, es, fr, de).
# Settings translations are also optional — omit to keep English labels.

# ─── Chinese (简体中文) ────────────────────────────────────────────────────

[i18n.zh]
name = "线索生成 Hand"
description = "自主线索生成——按计划发现、充实并交付合格的潜在客户"
category = "数据"

[i18n.zh.settings.target_industry]
label = "目标行业"
description = "重点关注的行业垂直领域（例如 SaaS、金融科技、医疗健康、电子商务）"

[i18n.zh.settings.target_role]
label = "目标职位"
description = "要触达的决策者头衔（例如 CTO、工程副总裁、产品负责人）"

[i18n.zh.settings.company_size]
label = "公司规模"
description = "按公司规模筛选线索"

[i18n.zh.settings.lead_source]
label = "线索来源"
description = "发现线索的主要方式"

[i18n.zh.settings.output_format]
label = "输出格式"
description = "报告交付格式"

[i18n.zh.settings.leads_per_report]
label = "每份报告线索数"
description = "每份报告中包含的线索数量"

[i18n.zh.settings.delivery_schedule]
label = "交付计划"
description = "生成和交付线索报告的时间安排"

[i18n.zh.settings.geo_focus]
label = "地域重点"
description = "优先关注的地理区域（例如美国、欧洲、亚太、全球）"

[i18n.zh.settings.enrichment_depth]
label = "信息丰富度"
description = "对每条线索收集多少上下文信息"

# ─── Korean (한국어) ────────────────────────────────────────────────────

[i18n.ko]
name = "리드 생성 Hand"
description = "자율 리드 생성 — 일정에 따라 적격 리드를 탐색, 보강 및 전달"
category = "데이터"

[i18n.ko.settings.target_industry]
label = "대상 산업"
description = "집중할 산업 분야 (예: SaaS, 핀테크, 헬스케어, 이커머스)"

[i18n.ko.settings.target_role]
label = "대상 직책"
description = "타겟할 의사결정자 직함 (예: CTO, 엔지니어링 VP, 프로덕트 총괄)"

[i18n.ko.settings.company_size]
label = "회사 규모"
description = "회사 규모별 리드 필터링"

[i18n.ko.settings.lead_source]
label = "리드 소스"
description = "리드를 발굴하는 주요 방법"

[i18n.ko.settings.output_format]
label = "출력 형식"
description = "보고서 전달 형식"

[i18n.ko.settings.leads_per_report]
label = "보고서당 리드 수"
description = "각 보고서에 포함할 리드 수"

[i18n.ko.settings.delivery_schedule]
label = "전달 일정"
description = "리드 보고서 생성 및 전달 시간"

[i18n.ko.settings.geo_focus]
label = "지역 중점"
description = "우선적으로 집중할 지역 (예: 미국, 유럽, 아시아 태평양, 글로벌)"

[i18n.ko.settings.enrichment_depth]
label = "보강 깊이"
description = "리드당 수집할 컨텍스트 정보의 수준"

# ─── Japanese (日本語) ────────────────────────────────────────────────────

[i18n.ja]
name = "リード生成 Hand"
description = "自律型リード生成エージェント——スケジュールに基づき見込み客を発見・情報付加・配信"
category = "データ"

[i18n.ja.settings.target_industry]
label = "ターゲット業界"
description = "注力する業界バーティカル（例: SaaS、フィンテック、ヘルスケア、EC）"

[i18n.ja.settings.target_role]
label = "ターゲット職種"
description = "アプローチする意思決定者の肩書き（例: CTO、VP Engineering、プロダクト責任者）"

[i18n.ja.settings.company_size]
label = "企業規模"
description = "企業規模でリードをフィルタリング"

[i18n.ja.settings.lead_source]
label = "リードソース"
description = "リードを発見する主な方法"

[i18n.ja.settings.output_format]
label = "出力形式"
description = "レポートの配信形式"

[i18n.ja.settings.leads_per_report]
label = "レポートあたりのリード数"
description = "各レポートに含めるリードの数"

[i18n.ja.settings.delivery_schedule]
label = "配信スケジュール"
description = "リードレポートの生成・配信タイミング"

[i18n.ja.settings.geo_focus]
label = "地域フォーカス"
description = "優先する地理的リージョン（例: 米国、欧州、APAC、グローバル）"

[i18n.ja.settings.enrichment_depth]
label = "情報付加の深さ"
description = "リードごとに収集するコンテキスト情報の量"

# ─── Spanish (Español) ────────────────────────────────────────────────────

[i18n.es]
name = "Hand de Generación de Leads"
description = "Generación autónoma de leads — descubre, enriquece y entrega leads cualificados según un calendario"
category = "Datos"

[i18n.es.settings.target_industry]
label = "Industria objetivo"
description = "Vertical de industria en la que enfocarse (ej. SaaS, fintech, salud, e-commerce)"

[i18n.es.settings.target_role]
label = "Rol objetivo"
description = "Títulos de tomadores de decisiones a los que dirigirse (ej. CTO, VP de Ingeniería, Director de Producto)"

[i18n.es.settings.company_size]
label = "Tamaño de empresa"
description = "Filtrar leads por tamaño de empresa"

[i18n.es.settings.lead_source]
label = "Fuente de leads"
description = "Método principal para descubrir leads"

[i18n.es.settings.output_format]
label = "Formato de salida"
description = "Formato de entrega del informe"

[i18n.es.settings.leads_per_report]
label = "Leads por informe"
description = "Número de leads a incluir en cada informe"

[i18n.es.settings.delivery_schedule]
label = "Calendario de entrega"
description = "Cuándo generar y entregar los informes de leads"

[i18n.es.settings.geo_focus]
label = "Enfoque geográfico"
description = "Región geográfica a priorizar (ej. EE.UU., Europa, Asia-Pacífico, global)"

[i18n.es.settings.enrichment_depth]
label = "Profundidad de enriquecimiento"
description = "Cuánto contexto recopilar por cada lead"

# ─── French (Français) ────────────────────────────────────────────────────

[i18n.fr]
name = "Hand Génération de Prospects"
description = "Génération autonome de prospects — découvre, enrichit et livre des prospects qualifiés selon un calendrier"
category = "Données"

[i18n.fr.settings.target_industry]
label = "Secteur cible"
description = "Secteur d'activité cible (ex. SaaS, fintech, santé, e-commerce)"

[i18n.fr.settings.target_role]
label = "Poste cible"
description = "Titres de décideurs à cibler (ex. CTO, VP Engineering, Directeur Produit)"

[i18n.fr.settings.company_size]
label = "Taille d'entreprise"
description = "Filtrer les prospects par taille d'entreprise"

[i18n.fr.settings.lead_source]
label = "Source de prospects"
description = "Méthode principale de découverte des prospects"

[i18n.fr.settings.output_format]
label = "Format de sortie"
description = "Format de livraison des rapports"

[i18n.fr.settings.leads_per_report]
label = "Prospects par rapport"
description = "Nombre de prospects à inclure dans chaque rapport"

[i18n.fr.settings.delivery_schedule]
label = "Calendrier de livraison"
description = "Quand générer et livrer les rapports de prospects"

[i18n.fr.settings.geo_focus]
label = "Focus géographique"
description = "Région géographique prioritaire (ex. USA, Europe, Asie-Pacifique, Mondial)"

[i18n.fr.settings.enrichment_depth]
label = "Profondeur d'enrichissement"
description = "Niveau d'informations contextuelles à collecter par prospect"

# ─── German (Deutsch) ────────────────────────────────────────────────────

[i18n.de]
name = "Lead-Generierungs-Hand"
description = "Autonome Lead-Generierung — entdeckt, bereichert und liefert qualifizierte Leads nach Zeitplan"
category = "Daten"

[i18n.de.settings.target_industry]
label = "Zielbranche"
description = "Branchenvertikale für den Fokus (z.B. SaaS, Fintech, Gesundheitswesen, E-Commerce)"

[i18n.de.settings.target_role]
label = "Zielposition"
description = "Titel der Entscheidungsträger (z.B. CTO, VP Engineering, Produktleiter)"

[i18n.de.settings.company_size]
label = "Unternehmensgröße"
description = "Leads nach Unternehmensgröße filtern"

[i18n.de.settings.lead_source]
label = "Lead-Quelle"
description = "Primäre Methode zur Lead-Entdeckung"

[i18n.de.settings.output_format]
label = "Ausgabeformat"
description = "Berichtslieferformat"

[i18n.de.settings.leads_per_report]
label = "Leads pro Bericht"
description = "Anzahl der Leads pro Bericht"

[i18n.de.settings.delivery_schedule]
label = "Lieferzeitplan"
description = "Wann Lead-Berichte generiert und geliefert werden"

[i18n.de.settings.geo_focus]
label = "Geografischer Fokus"
description = "Priorisierte geografische Region (z.B. USA, Europa, Asien-Pazifik, Global)"

[i18n.de.settings.enrichment_depth]
label = "Anreicherungstiefe"
description = "Umfang der pro Lead gesammelten Kontextinformationen"