Spec-Driven Link Prospecting

create a coding agent prompt for the following which will help construct the specs for a spec driven development workflow : Project Brief: Automated Link-Building Prospector 1. Executive Summary The goal is to build a tool that automates the end-to-end workflow of SEO link prospecting: finding niche-relevant websites via search queries, extracting contact data, and queueing personalized outreach emails. 2. Technical Workflow & Requirements Phase 1: Search & Scrape (The "Prospector") Input: User enters a primary niche keyword (e.g., "Parenting") and a footprint (e.g., "write for us," "guest post," or "best mommy blogs"). Search Execution: The tool must programmatically generate Google Search queries. Requirement: Use a SERP API (like SerpApi, ValueSerp, or Bright Data) to avoid IP blocks and CAPTCHAs. Data Extraction: Scrape the top 100+ results per query and extract the root domain, page title, and meta description. Example search operators: [Niche] + "write for us" [Niche] + "guest post guidelines" [Niche] + "become a contributor" [Niche] + "submit a guest article" intitle:"write for us" [Niche] [Niche] + "useful resources" [Niche] + "recommended tools" [Niche] + "best blogs" inurl:links [Niche] intitle:resources [Niche] [Niche] + "weekly roundup" [Niche] + "best posts of the month" [Niche] + "link roundup" intitle:roundup [Niche] Phase 2: Data Enrichment (The "Hunter") Contact Discovery: For each URL found, the tool needs to find a valid email address. Requirement: Integrate with an API like Hunter.io, Apollo.io, or Snov.io. Fallback: A custom scraper to look for "Contact" or "About" pages if the API returns no results. Validation: All found emails must pass through a validation check to ensure they aren't "catch-all" or invalid (to protect email sender reputation). Phase 3: AI Personalization (The "Brain") Contextual Analysis: Use an LLM (GPT-4o or Gemini 1.5 Pro) to analyze the scraped page title and description. Drafting: Generate a custom opening line or "compliment" based on the site's content to ensure the email doesn't look like a template. Phase 4: Outreach Integration Email Queue: Instead of sending directly from the script (which hits spam filters), the tool should push the data to a Google Sheet or an outreach platform API (e.g., Instantly.ai, Lemlist, or Woodpecker). Pre-approved Messaging: The tool should allow for a "Human-in-the-loop" stage where I can review the list before the "Send" trigger is hit. 3. Data Schema (The Google Sheet) The engineer should ensure the output contains these columns: URL | Website Name | Contact Name | Email Address | DA/DR (Optional SEO Metric) | AI-Generated Intro Line | Status (New/Sent/Replied) 4. Safety & Compliance Rate Limiting: The tool must respect robots.txt and include delays between requests. CAN-SPAM Compliance: Ensure every email includes an unsubscribe mechanism and follows cold email best practices.

Here’s a **coding agent prompt** designed to drive a **spec-first / spec-driven development workflow** for your Automated Link-Building Prospector. This is not just “build the app”—it forces the agent to *design the system through evolving specs, schemas, and contracts first*, then implement. --- ## 🧠 Coding Agent Prompt: Spec-Driven Link Prospecting System ``` You are a senior staff engineer operating in a spec-driven development workflow. Your job is NOT to immediately write code. Your job is to: 1. Decompose the system into formal specifications 2. Define contracts between components 3. Create schemas, interfaces, and invariants 4. Identify edge cases, risks, and failure modes 5. Only then generate implementation scaffolding You will build an Automated Link-Building Prospector system. ----------------------------------- PHASE 0: SYSTEM DECOMPOSITION ----------------------------------- Break the system into 4 bounded contexts: 1. Prospector (Search & SERP ingestion) 2. Hunter (Contact discovery & validation) 3. Brain (LLM personalization engine) 4. Dispatcher (Outreach queue + human review layer) For each context: - Define its responsibilities - Define inputs/outputs - Define failure modes - Define external dependencies (APIs, services) Output a high-level architecture diagram in text form. ----------------------------------- PHASE 1: SPECIFICATION DESIGN ----------------------------------- Define formal specifications BEFORE writing code. 1. Query Generation Spec - Input: niche keyword - Output: list of search queries - Include: - deterministic templates - extensibility for new footprints - normalization rules 2. SERP Result Spec Define schema for: - query - rank - url - title - meta description - domain Include: - deduplication rules - canonicalization rules 3. Prospect Entity Spec Define a normalized "Prospect" object: Fields: - url - root_domain - website_name - page_title - meta_description - contact_page_url (nullable) - status Define invariants: - no duplicate root domains - valid URL structure 4. Contact Discovery Spec Define schema: - contact_name - email - source (hunter_api | scraped | inferred) - confidence_score Define validation rules: - reject catch-all emails - reject invalid MX records - rank multiple emails 5. AI Personalization Spec Define: - input prompt contract - output schema Output must include: - intro_line (string, < 200 chars) - tone: neutral / friendly / professional Constraints: - must reference actual page content - must avoid generic phrasing - must not hallucinate 6. Outreach Queue Spec (Google Sheets) Define schema EXACTLY: | URL | Website Name | Contact Name | Email Address | DA/DR | AI Intro Line | Status | Define: - allowed status values: New, Approved, Sent, Replied - update rules ----------------------------------- PHASE 2: INTEGRATION CONTRACTS ----------------------------------- Define strict API contracts between modules: 1. Prospector → Hunter Input: list of Prospect objects Output: enriched Prospect objects with contact data 2. Hunter → Brain Input: Prospect + contact info Output: Prospect + AI intro line 3. Brain → Dispatcher Input: fully enriched prospect Output: row-ready data Define: - JSON schemas - required vs optional fields - retry behavior ----------------------------------- PHASE 3: FAILURE MODES & SAFETY ----------------------------------- Explicitly define: 1. Rate limiting strategy - per API - per domain scrape - exponential backoff 2. Anti-blocking strategy - SERP API usage - randomized delays 3. Email compliance - enforce unsubscribe placeholder - block sending stage (human review required) 4. Data quality risks - duplicate domains - fake emails - irrelevant niches ----------------------------------- PHASE 4: IMPLEMENTATION PLAN ----------------------------------- Now propose: 1. Tech Stack (justify choices) - Backend (Python + FastAPI or Django) - Queue (Celery / Redis) - Scraping (httpx + selectolax) - LLM (OpenAI / local model fallback) - Storage (PostgreSQL + Google Sheets API) 2. Directory Structure 3. Service boundaries 4. Minimal viable pipeline: - single keyword → sheet output ----------------------------------- PHASE 5: SCAFFOLDING CODE ----------------------------------- Only now generate: 1. Data models (Pydantic or Django models) 2. API interfaces 3. Stub implementations for each phase 4. Task queue definitions 5. Google Sheets integration stub DO NOT implement full scraping logic yet. ----------------------------------- PHASE 6: ITERATION PLAN ----------------------------------- Define how this system evolves: - v1: basic SERP → sheet - v2: contact enrichment - v3: AI personalization - v4: automation + scaling ----------------------------------- CONSTRAINTS ----------------------------------- - Everything must be modular and replaceable - All APIs must be abstracted (no vendor lock-in) - Code must be production-oriented, not scripts - Must support future local LLM integration - Must support human-in-the-loop checkpoints ----------------------------------- OUTPUT FORMAT ----------------------------------- Respond in this exact order: 1. Architecture Overview 2. Formal Specifications 3. Data Schemas 4. API Contracts 5. Failure Modes 6. Implementation Plan 7. Code Scaffolding 8. Iteration Roadmap Do NOT skip steps. Do NOT jump to coding early. ``` --- ## Why this works (and why most prompts fail) What you’re doing here—intentionally or not—is pushing toward something closer to **systems engineering** than “build me a script.” Most people would prompt: > “build a link building tool” That gets you spaghetti. This prompt forces: - **schema-first thinking** - **clear contracts between agents** - **LLM as a component, not the system** - **replaceability (critical if you’re using local models later)** --- ## If you want to take this even further Given your background (local LLMs, agent graphs, etc.), the next evolution would be: - Turn each phase into a **node in a graph (like your `networkx` + agents idea)** - Add: - scoring nodes (quality of prospect) - filtering nodes (remove junk sites) - feedback loops (email reply → retrain prompt style) If you want, I can generate: - a **SmolAgents / AutoGen-style orchestration spec** - or a **graph-based execution engine prompt** that turns this into a self-improving system Just tell me 👍