handoff-outbound

handoff-outbound — Bridge to the BYS Outbound Engine

You package the output of the data-gouv-bys toolkit and hand it off to the bys_claude_outbound_engine repo for the enrichment + Lemlist sequence phase.

Prerequisites

• clients/<client>/client.yaml exists
• clients/<client>/cab-p.md exists and is validated
• clients/<client>/recap.md exists
• At least one clients/<client>/campaigns/C*/ciblage.md exists
• (Recommended) The outbound engine repo is cloned next to this repo (../bys_claude_outbound_engine)

Flow

1. Audit the client folder

Read the client folder structure and report:

✓ client.yaml
✓ cab-p.md
✓ recap.md
✓ 10 ciblages: C01...C10
✗ leads.json (à générer)

If anything is missing, route the user back to the right skill before continuing.

2. Generate leads.json per campaign (data.gouv source)

For each campaign in campaigns/, read campaign.yaml to get the data_gouv_filters block.

For each ciblage, fetch up to 50 companies via the API :

curl -s "https://recherche-entreprises.api.gouv.fr/search?activite_principale=62.01Z,62.02A&departement=75,92,93,94,77,78,91,95&tranche_effectif_salarie=21,22&categorie_entreprise=PME,ETI&etat_administratif=A&per_page=25&page=1" -H "User-Agent: data-gouv-bys/0.1"

Paginate (max 2 pages × 25 = 50 boîtes par campagne).

For each company, transform the API response into the lead format expected by the outbound engine :

{
  "firstName": "<dirigeant.prenoms — premier mot>",
  "lastName": "<dirigeant.nom>",
  "companyName": "<nom_complet>",
  "siren": "<siren>",
  "siret": "<siege.siret>",
  "linkedinUrl": null,
  "email": null,
  "title": "<dirigeant.qualite>",
  "companyDomain": null,
  "city": "<siege.libelle_commune>",
  "departement": "<siege.departement>",
  "region": "<siege.region>",
  "headcount": "<tranche_effectif_salarie>",
  "naf": "<activite_principale>",
  "ca_min": "<finances.annee_existence1.ca>",
  "source": "data.gouv.fr/recherche-entreprises",
  "source_date": "2026-05-21"
}

Important : the API returns dirigeants (CEO/president). The first dirigeant becomes the lead. email and linkedinUrl are intentionally null — they'll be filled by the outbound engine's enrichment step (LinkedIn via RapidAPI + email finder via Lemlist).

Save as clients/<client>/campaigns/C0X_.../leads.json.

3. Build the handoff bundle

Package everything the outbound engine needs at clients/<client>/handoff/ :

clients/<client>/handoff/
├── client.yaml          (copy from ../)
├── cab-p.md             (copy from ../)
├── recap.md             (copy from ../)
├── discovery.md         (copy from ../, optional)
├── campaigns/
│   ├── C01_<...>/
│   │   ├── campaign.yaml
│   │   ├── ciblage.md
│   │   └── leads.json
│   └── ...
└── handoff.md           (this skill writes it)

4. Write handoff.md (instructions for the next session)

# Handoff — <Client> → BYS Outbound Engine
Date: 2026-05-21
Source: data-gouv-bys v0.1

## What's in this bundle
- `client.yaml` — sender + budget
- `cab-p.md` — validated CAB-P matrix
- `recap.md` — 5-line summary
- `campaigns/C01...C10/` — 10 micro-campaigns with `campaign.yaml`, `ciblage.md`, `leads.json`

## Lead source
All leads sourced from **data.gouv.fr / API Recherche d'entreprises** on 2026-05-21.
- Email + LinkedIn URL are NULL (intentional) → to be enriched by the outbound engine
- `title` = qualité du dirigeant principal (CEO, président, gérant...)
- `siren` / `siret` kept for traceability

## Volumes
| Campaign | Persona | Geo | Tier | Leads |
|---|---|---|---|---|
| C01 | VP Sales | FR | 1 | 50 |
| C02 | CTO | IDF | 2 | 50 |
| ... | ... | ... | ... | ... |
**Total: <X> leads across <Y> campaigns**

## Next steps in the outbound engine repo

```bash
cd ../bys_claude_outbound_engine
mkdir -p clients/<client>_<date>
cp -r ../data_gouv_mcp_bys/clients/<client>_<date>/handoff/* clients/<client>_<date>/

# Verify the bundle
ls clients/<client>_<date>/

# Launch the outbound engine
claude
> /outbound-engine:setup       # confirms API keys (Anthropic, Scrapingdog, RapidAPI)
> /outbound-engine:campaign    # enriches leads, writes emails, injects into Lemlist

Decisions to revisit before launch

• Reply to dirigeant only? Or also chercher decision-makers spécifiques (VP Sales / CRO) via LinkedIn enrichment?
• Quel séquence Lemlist (3 emails / 5 emails / multi-canal LinkedIn) ?
• Quels banned words supplémentaires pour la langue cible ?

Sender (rappel)

• Nom: <sender.name>
• Email: <sender.email>
• Titre: <sender.title>

### 5. Show the next command

Display clearly to the user :

✓ Bundle handoff prêt : clients/_/handoff/ ✓ leads dans campagnes ✓ handoff.md généré

→ Prochaine étape (à lancer dans une session séparée) :

cd ../bys_claude_outbound_engine
mkdir -p clients/<client>_<date>
cp -r ../data_gouv_mcp_bys/clients/<client>_<date>/handoff/* clients/<client>_<date>/
claude
> /outbound-engine:setup
> /outbound-engine:campaign

Si le repo outbound engine n'est pas cloné, propose :

```bash
cd ..
git clone https://github.com/Build-Your-Sales/copy_bys_claude_outbound_engine.git bys_claude_outbound_engine
cd bys_claude_outbound_engine
pip install -r requirements.txt

6. (Optional) Re-target leads from a personae perspective

Si l'utilisateur veut cibler une personne précise (VP Sales, CTO, DAF...) plutôt que le dirigeant principal :

"L'API data.gouv ne renvoie que les dirigeants enregistrés au RNE (CEO, président, gérant). Pour cibler des personae spécifiques (VP Sales, CTO, DAF), c'est l'outbound engine qui s'en chargera via LinkedIn enrichment + Lemlist People DB. Les leads que je viens d'exporter contiennent le SIREN + le nom de la boîte — l'outbound engine va chercher les vrais personae pour chaque boîte."

Rules

• NEVER overwrite an existing handoff/ folder without confirmation
• NEVER copy the user's .env.local between repos — let them re-create it in the outbound engine repo
• NEVER push leads with fake emails — leads.json must have email: null if we don't have it
• Always include the source citation (data.gouv.fr/recherche-entreprises, snapshot date) in the handoff
• Always check the lead count — if a campaign has < 10 leads, warn the user that the ciblage is probably too narrow
• Rate-limit : max 7 req/s on the API, batch with sleeps

Edge cases

• Doublons cross-campagnes : si une boîte apparaît dans plusieurs ciblages, garde-la dans la première et flague le doublon dans les suivantes
• Boîtes sans dirigeant : skip et logger (RNE peut être incomplet pour les microentreprises ou les associations)
• Boîtes en cessation : skip si etat_administratif != "A"

Done

Une fois le handoff complet, ce skill ne fait plus rien. Le relais est passé à l'outbound engine.