PTENES
v1 · core built and tested (47 tests)

A website agency for one person, automatically

Finds highly rated businesses with poor websites, redesigns the page, publishes it, and sends the proposal — deterministic orchestrator + AI only where needed, operated through Telegram.

Start the guide View on GitHub 
# the pipeline, from start to finish
descoberto
  → qualificado     # judges "bad site?" (AI)
  → redesenhado     # premium page (AI)
  → publicado       # git → GitHub Pages
  → [ PORTÃO ]      # approve on Telegram (or --auto)
  → enviado         # proposal via Resend
  → respondido → fechado
What it is

A pipeline that runs found → rebuilt → published → pitched

Semi-autonomous: the heavy phases run on their own, while you stay in control of sending. Based on the plugin prospector-de-sites (used as a reference), rebuilt as an operable service.

⛏️ Complete pipeline

Finds, qualifies, redesigns, publishes, and sends — each phase is a stage in a state machine that survives restarts and is idempotent per lead.

🧠 AI only where needed

The queue, approval gate, and states are pure, testable Python. The model (claude -p) only comes in to judge the site and redesign the page — everything else is code, with no token spend.

🔌 Pluggable and portable

Discovery switches from browser to API via config. The same codebase runs locally, in a hybrid setup on a VPS, or entirely on a VPS — without rewriting anything.

How it works

A lead's life cycle

Each arrow is an idempotent transition: if it has already happened, it is skipped. The only human step is gate before sending — and it disappears when the request comes with --auto.

discovered→ qualified→ redesigned→ published→ [ approval gate ]→ sent→ answered→ closed

Branches: no website / good website / no email → discarded. Network/API failure → error (Telegram alert, with /retry).

Prerequisites

What you'll need (v1, local)

v1 runs on your machine — the browser handles the Maps captcha with you nearby. Later versions migrate to API and VPS.

Python 3.11+

The entire core. No heavy dependencies to start.

# check the version
python3 --version

Claude Code CLI

The AI phases (qualifying, redesigning) use claude -p with skills.

# check the CLI
claude --version

Accounts + secrets

Resend (email), GitHub (Pages), Telegram (bot). Tokens only in the .env, never in chat.

# template
cp .env.example .env
User guide · milestone-by-milestone walkthrough

How to set it up

Development is organized into milestones, each delivering testable software. The M1 (Foundation) is the current target — the design and plan are already in the repo.

Status: v1 (deterministic core) built and tested — 47 tests passing. The commands demo e prospectar --provider fake already run; those that touch Google Maps, claude -p, Resend, Telegram, and deploy depend on your credentials (see README → "What's missing").
0

Clone and read the design

The entire project starts from a versioned spec and plan.

git clone https://github.com/inematds/prospector-agent
cd prospector-agent
# complete design and M1 plan:
#   docs/superpowers/specs/2026-07-14-prospector-agent-design.md
#   docs/superpowers/plans/2026-07-14-m1-fundacao.md
1

M1 · Foundation — the core and the dry run

Config, SQLite Store, state machine, and the CLI that moves a lead through the pipeline without publishing or sending.

python -m pytest -v                 # core suite
python -m prospector demo --dry-run --auto
# → discovered → qualified → redesigned → published → sent
2

M2 · Discovery + Qualification

Finds candidates on Google Maps (rating ≥ 4.7, with a website) and judges which ones have a bad website, extracting email and WhatsApp.

prospector prospectar nutricionistas Bauru
# → qualified leads saved in prospector.db
3

M3 · Creation + Publishing

Redesigns the page with a premium look (preserving the real logo, colors, and content) and publishes it on GitHub Pages with HTTPS.

prospector publicar <slug>
# → https://usuario.github.io/prospector-sites/<slug>/
4

M4 · Sending + Telegram (complete pipeline)

Sends the proposal via Resend, with the approval gate on Telegram. The bot runs everything; the --auto skips the gate.

# through the Telegram bot:
/prospectar nutricionistas Bauru --auto
# phases run on their own; the bot notifies you about each send
The core

Deterministic control, in code

The heart of the system isn't the agent — it's the state machine and the approval gate. They stay in simple, testable code; AI is called only within two stages.

# prospector/maquina_estados.py — valid transitions
TRANSICOES = {
  DESCOBERTO: {QUALIFICADO, DESCARTADO},
  QUALIFICADO: {REDESENHADO, DESCARTADO},
  REDESENHADO: {PUBLICADO, ERRO},
  PUBLICADO: {AGUARDANDO_APROVACAO, ENVIADO, ERRO},
  AGUARDANDO_APROVACAO: {ENVIADO, DESCARTADO},
  ENVIADO: {RESPONDIDO, ERRO},
  RESPONDIDO: {FECHADO, DESCARTADO},
}
# the A+B gate, in one line
if lead.sem_portao or aprovado_no_telegram(lead):
    enviar(lead)          # Resend
else:
    aguardar_aprovacao(lead)   # request approval on Telegram

# dry-run: run the pipeline without publishing or sending
$ python -m prospector demo --dry-run --auto
descoberto → qualificado → redesenhado
           → publicado → enviado
Roadmap

Local → hybrid → everything on a VPS

Topology portability is a design principle: the same codebase scales up just by changing the config and where it runs.

v1 · Local
Complete pipeline on your machineBrowser-based discovery (you handle the CAPTCHA), approval gate enabled, local dashboard.
v1.x · Hybrid
Orchestrator on the VPSThe bot, publishing, and sending always run on the VPS; the scanner (browser) stays local and pushes the leads.
v2 · All VPS
API-based discovery, without a browserOfficial Places API or third parties as a plug-in provider; your own repo + custom domain for each client upon conversion.