# Hermes Sales Pipeline Automation: Design Spec

| Field | Value |
|---|---|
| Project | `05_projects/Hermes_Sales_Pipeline` |
| Date | 2026-09-24 |
| Status | Approved for planning (brainstorming complete) |
| Owner | Coordenadas (Pablo / Miguel) |
| Client | Factronics USA LLC |
| Related repos | `factronics-hermes-fleet` (branch `audit/icm-contract-fidelity`), `factronics-hermes`, `Knowledge-Base-Hermes-Factronics`, `Gateway-QB`, `Factronics-control-panel` |

---

## 1. Context and problem

Factronics USA runs two systems that barely talk to each other:

- **The sales pipeline** (executed today in HubSpot, with n8n automations). Seven deal stages exist. Only two stages have automations today: entering Proyecto Viable emails the deal owner a link to the Product Details Form, and entering Ganado emails the owner a link to the Equipment Installation Form. Each form submission fills a Google Docs template, generates a PDF, emails it back to the owner (CEO copied), and attaches it to the deal. A parallel Hermes branch on Ganado is defined but not applied.
- **The Hermes agent fleet** (deployed and running since 2026-09-17): six LLM profiles (`orchestrator`, `contable`, `inbox`, `operations`, `onboarding`, `gateway`) coordinated by a kanban board, with hard mechanical limits, an immutable `audit_log`, a global kill switch, RAG over the Factronics knowledge base, and a QuickBooks gateway with human write approval.

The stage-to-automation logic is incomplete, hardcoded into one n8n workflow, and the two systems have no shared record of which deal produced which task. The goal of this project is to make a stage change in the pipeline a first-class trigger for the Hermes fleet, to close the gaps in owner- and client-facing automation across all seven stages, and to automate the solution presentation.

### Platform neutrality

The pipeline and the conversation flow are the same regardless of the CRM platform. This spec therefore defines every automation in terms of a **stage transition** and an **audience** (owner or client). HubSpot, GoHighLevel, and n8n are interchangeable executors. Where concrete IDs are listed (HubSpot stages, n8n workflow IDs) they are given as the current implementation reference, not as a design constraint.

---

## 2. Goals and non-goals

### Goals

1. Every pipeline stage transition can create a routed Hermes task (all seven stages).
2. A persistent `deal_map` links a deal to the Hermes tasks it produced, idempotent per (deal, stage).
3. Owner-facing reminders and tasks, and client-facing sends (draft-only), defined and templated per stage.
4. A reusable structured-intake mechanism (form, then branded document plus PDF) generalizing the existing Product Details and Equipment Installation pattern.
5. A solution presentation generator that customizes a master deck with the prospect's logo and accent colors.
6. Reuse the existing Hermes domains. No new profile without explicit sign-off.

### Non-goals (this run)

- **Demo Van initiative is out of scope.** No demo-van booking, scheduling, or visit report.
- No new Hermes profile.
- No full re-theme of the presentation (logo plus accent colors only).
- Master deck scope is Linx and Anritsu only.
- No changes to the QuickBooks write-approval model (human `approve_write` stays).

---

## 3. Locked decisions

| # | Decision | Choice |
|---|---|---|
| D1 | Trigger model | A deal entering a stage is the single trigger primitive |
| D2 | Stage-to-task coverage | All seven stages spawn a Hermes task |
| D3 | Ownership model | Reuse existing Hermes domains; no new profile |
| D4 | Demo Van | Excluded from this run |
| D5 | Presentation scope | Master deck = Linx and Anritsu only |
| D6 | Presentation customization | Prospect logo plus accent colors |
| D7 | Presentation rails | Strip the template editing rails in generated decks |
| D8 | Presentation output | Editable Google Slides plus an exported PDF |
| D9 | Client sends | Draft-only, human-approved (contractual) |
| D10 | CEO copy | Jovan copied on all owner-facing emails |
| D11 | Presentation access | A Google service account is granted full access to the Google Drive and Google Slides APIs; the automation performs the changes on its own |

---

## 4. Target architecture

```
Deal enters a stage (HubSpot / GHL / any CRM)
        |
        | stage-change event
        v
n8n "Webhook Deal Stage" (single HMAC-SHA256 V2 branch for every stage)
        |
        | POST /p/orchestrator/webhooks/deal-stage   (HMAC, idempotency)
        v
Hermes orchestrator
        | verify HMAC (fail closed), idempotency key (deal_id, dealstage)
        | lookup stage -> (domain, task_type) in workspace/shared/deal_stages.yaml
        | kanban_create(domain, task_type, metadata = {deal_id, dealstage, ...})
        v
kanban board "factronics"
        | lifecycle hook (no LLM)
        v
plugin kanban-hubspot-bridge (deterministic)
        | UPSERT deal_map (deal_id, dealstage) -> kanban_task_id
        | (later) notify n8n to write back to the deal
        v
domain agent (inbox | operations | onboarding | contable)
        | does the work, writes audit_log, verify_audit.sh gate
        v
closes task; results surfaced (panel, Telegram, deal note)
```

The design reuses, unchanged: the HMAC-SHA256 V2 webhook pattern, the `asana_map` mapping pattern and its `kanban-asana-bridge` plugin shape, `verify_audit.sh`, the kill-switch enforcement, and the draft-only contract.

---

## 5. Sub-projects

### 5.1 SP1: Bridge and routing (foundation)

**Purpose.** Generalize the half-built bridge so any stage transition can create a routed task, with a persistent deal-to-task record.

**Components.**

1. **n8n workflow change (current reference: "Webhook Deal Stage", `oGMm7eDclq6VrVfW`).** Connect the currently dormant Switch outputs (Calificar, Presentación, Negociación/Revisión, Expectativa de Cierre, Perdido). Replace the single closedwon-only branch with one signing branch that fires for every connected stage, sending the stage in the payload.
2. **Payload contract.**
   ```
   { deal_id, dealname, dealstage, amount, hubspot_owner_id, source }
   ```
   Signed HMAC-SHA256 V2: `signature = HMAC(secret, timestamp + "." + body)`.
3. **Hermes webhook route** `deal-stage` on `orchestrator` (replaces the closedwon-only `onboarding-intake`; keep the old route as a thin alias during migration).
4. **Routing config** `workspace/shared/deal_stages.yaml`: maps `dealstage` to `(domain, task_type, action)`.
5. **`deal_map` table** in the shared Postgres, sibling of `asana_map`.
6. **`kanban-hubspot-bridge` plugin** (deterministic, no LLM): on task creation, UPSERT `deal_map`; later, trigger the writeback.

**Routing map (draft).**

| dealstage | Stage name | domain | task_type |
|---|---|---|---|
| `appointmentscheduled` | Calificar | `inbox` | `deal_qualified` |
| `qualifiedtobuy` | Proyecto Viable | `operations` | `deal_product_details_track` |
| `presentationscheduled` | Presentación de Solución | `orchestrator` | `deal_presentation_prep` |
| `decisionmakerboughtin` | Negociación/Revisión | `inbox` | `deal_negotiation_monitor` |
| `contractsent` | Expectativa de Cierre | `operations` | `deal_close_expectation` |
| `closedwon` | Ganado | `onboarding` | `onboarding_intake` (existing) |
| `closedlost` | Perdido | `operations` | `deal_lost_record` |

**Data model.**

```sql
CREATE TABLE deal_map (
    deal_id        TEXT        NOT NULL,
    dealstage      TEXT        NOT NULL,
    kanban_task_id TEXT,
    domain         TEXT,
    task_type      TEXT,
    created_at     TIMESTAMPTZ DEFAULT NOW(),
    updated_at     TIMESTAMPTZ DEFAULT NOW(),
    PRIMARY KEY (deal_id, dealstage)
);
```

**Idempotency.** Primary key `(deal_id, dealstage)`. A repeated delivery is a no-op UPSERT. This closes the pending dedup gap noted in the n8n changelog.

**Verification.** New `verify_deal_map.sh <deal_id> <dealstage>` (analog of `verify_audit.sh`) asserts a `deal_map` row plus a matching `audit_log` row.

### 5.2 SP2: Owner tasks, reminder engine, template library

**Purpose.** Define the owner-facing task and the reminder cadence for every stage, formalizing stages Proyecto Viable and Ganado and adding the rest.

**Owner task per stage.** Each stage creates a task for the deal owner (salesperson) with a clear deliverable (see section 6).

**Reminder engine (two generic cadences).**

- Internal, owner task pending:
  `T0` task created, `T0 + 2 business days` reminder, `T0 + 5 business days` reminder, then escalate to Jovan. Stop when the task is completed.
- External, client silent:
  `72h`, then `3d`, `5d`, `15d` follow-ups, then tag cold/nurture. Applies to stages awaiting a client response.

**Template library (bilingual EN/ES).**

`owner_task_calificar`, `owner_task_product_details`, `owner_task_presentation`, `owner_task_quote`, `owner_task_close`, `owner_task_equipment_install`, `owner_task_loss_reason`, `owner_reminder_plus2d`, `owner_reminder_plus5d`, `owner_escalation_jovan`, `client_welcome_qualify`, `client_solution_presentation`, `client_quote`, `client_contract_reminder`, `client_thankyou_won`, `client_nurture_30_60_90`.

Spanish-first for cluster #1 (Miami food and beverage).

### 5.3 SP3: Hermes to pipeline writeback

**Purpose.** Let agents reflect their verified work back onto the deal, within strict autonomy limits.

**Components.**

- **Autonomy matrix** defining, per agent, which deal fields and stages it may write, and the confidence gate (default `confidence > 0.85`, matching the current `inbox` rule).
- Never schema changes (no property creation or modification).
- Every write is audited (a `hubspot_updated` style row in `audit_log`) and reversible.
- Builds on the existing `inbox` scoped-write capability.

### 5.4 SP4: Presentation generator

**Purpose.** Replace the manual process of trimming a master deck and swapping in prospect branding.

**Current manual process.** A master Google Slides deck contains slides for every solution, organized by supplier. The seller deletes unwanted slides and customizes the deck with the prospect's logo and colors.

**Automated process.**

1. **Seller fills the Solution Brief** at stage 3 (Presentación de Solución): prospect name and contact, logo (upload or URL), brand colors (auto-suggested, overridable), and the ticked solutions (Laser, Inkjet, Thermal Transfer, X-Ray, Combination, Metal Detectors), optional case study.
2. **Brand extraction** from the logo or the prospect website (auto), with manual override.
3. **Generation** (deterministic, plus agent assistance):
   - copy the master,
   - delete unselected solution sections and their dividers,
   - rebuild the agenda from the included sections,
   - update the prospect slides with prospect name and logo,
   - apply prospect accent colors to the brand-bearing slides,
   - strip the editing rails (the "(OJO...)" advisory boxes and the grey image placeholders),
   - export a PDF,
   - share the editable deck with the owner,
   - attach the PDF and deck link to the deal.
4. **Owner edits and sends.** Draft-only is preserved.

**Master deck inventory (source: `COPIA COORDENADAS - Irrisept_Intro_to_Linx_Technologies_Presentation.pptx`, 41 slides).**

| Slides | Section | Type | Include rule |
|---|---|---|---|
| 1 | Title | prospect | always, brand |
| 2 | Agenda | auto | regenerate from included sections |
| 3-4 | Intro: Factronics | fixed | always |
| 5 | Intro: Linx | supplier | if any Linx solution included |
| 6 | Intro: Prospect | prospect | always |
| 7 | Intro: Anritsu | supplier | if any Anritsu solution included |
| 8-9 | Prospect application / process | prospect | always |
| 10-16 | Laser | solution | if selected |
| 17-18 | Inkjet | solution | if selected |
| 19-28 | Thermal Transfer (TTO) | solution | if selected |
| 29-32 | X-Ray | solution | if selected |
| 33-36 | Combination (Checkweigher + Metal Detector) | solution | if selected |
| 37-39 | Metal Detectors | solution | if selected |
| 40 | Q&A / Next Steps | fixed | always |
| 41 | Thank You | fixed | brand |

**Access.** Resolved: a Google service account is granted full access to the Google Drive and Google Slides APIs, and the automation performs the copy, edits, and export on its own. Remaining open item: designate which file is the canonical master deck (the current artifact is a working copy, `COPIA COORDENADAS...`).

### 5.5 SP5: New form processes

**Purpose.** Add the structured intakes that do not exist yet, reusing the Product Details / Equipment Installation pattern.

**Intake pattern.** Form submitted, then merge fields into a branded Google Docs template, then generate a PDF, then email the owner (CEO copied), then attach to the deal.

See section 7 for the full form inventory.

### 5.6 SP6: Unified visibility

**Purpose.** Single view of deal-to-task state and unified notifications.

- Panel (based on `Factronics-control-panel`) shows, per deal, the linked Hermes tasks and their state, fed by `deal_map`.
- Notifications: Telegram remains the internal channel; decision needed on whether HubSpot tasks and Telegram duplicate or one is canonical.

---

## 6. Stage-by-stage automation matrix

| Stage (dealstage) | To OWNER | To CLIENT | Intake / document | Hermes action |
|---|---|---|---|---|
| 1 Calificar (`appointmentscheduled`) | qualify task | welcome / qualify message | none (structured via conversation) | `inbox` drafts |
| 2 Proyecto Viable (`qualifiedtobuy`) | email plus task, complete Product Details Form (exists) | none | **Product Details Form** (exists, 16 fields) | track completion |
| 3 Presentación de Solución (`presentationscheduled`) | email plus task, deliver solution presentation | the customized presentation (owner sends) | **Solution Brief** (new) | **deck generator** |
| 4 Negociación/Revisión (`decisionmakerboughtin`) | prepare quote / negotiate task | quote / response (draft) | **Quote/Negotiation Details** (new) | `inbox` monitors thread |
| 5 Expectativa de Cierre (`contractsent`) | confirm close date task | contract / expectation email plus reminders | **Close/PO Details** (new) | `onboarding` pre-checks (EIN, resale) |
| 6 Ganado (`closedwon`) | email plus task, complete Equipment Installation Form (exists) | thank-you / welcome | **Equipment Installation Form** (exists, 33 fields) | `onboarding` creates QB customer (via `gateway`, human approval) |
| 7 Perdido (`closedlost`) | record loss reason task | nurture sequence (if salvageable) | **Loss Reason** (new) | `operations` logs reason |

```text
LEAD IN
  |
(1) CALIFICAR          owner: qualify task    client: welcome/qualify
  |
(2) PROYECTO VIABLE    owner: mail+task "Product Details"    form -> doc+PDF -> owner(+CEO) -> deal
  |                                                          reminder +2d/+5d
  |
(3) PRESENTACION       owner: task            client: presentation (owner sends)
  |                    Solution Brief -> deck generator -> editable Slides + PDF
  |
(4) NEGOCIACION        owner: quote task      client: quote (draft on approval)
  |                    Quote/Negotiation Details            follow-up 72h/3d/5d
  |
(5) EXPECTATIVA CIERRE owner: close task      client: contract reminders 3d/7d
  |                    Close/PO Details -> feeds onboarding
  |
(6) GANADO             owner: mail+task "Equipment Installation"  form -> doc+PDF
  |                    Hermes onboarding -> QB customer            client: thank-you
  |
(7) PERDIDO            owner: loss-reason task   client: nurture 30/60/90
```

---

## 7. Forms inventory

| # | Form | Stage | Fields (target) | Generates | Flows to |
|---|---|---|---|---|---|
| 1 | Product Details | 2 Proyecto Viable | 16 (exists) | doc plus PDF | presentation, quote |
| 2 | Equipment Installation | 6 Ganado | 33 (exists) | doc plus PDF | onboarding, install |
| 3 | Solution Brief | 3 Presentación | prospect info, logo, colors, selected solutions, optional case study | editable deck plus PDF | owner send |
| 4 | Close/PO Details | 5 Expectativa | expected close date, PO number, payment terms, delivery date, billing/shipping, tax-exemption status | doc plus PDF | onboarding, QB |
| 5 | Quote/Negotiation Details | 4 Negociación | scope, price, terms, leasing, competitors, decision-makers, objections | quote doc, or QB Estimate | close, QB |
| 6 | Loss Reason | 7 Perdido | reason category (price/timing/competitor/no-fit/no-response), free note | logged | reporting, nurture |

Reference IDs (current HubSpot implementation): Product Details Form `f85e5ef8-f91c-4a29-b587-fd23bbb38b88`, Equipment Installation Form `740f1057-9086-4315-9958-65c438af98b7`.

---

## 8. Reminder cadences

**Internal (owner task pending).**

```
T0            task created (email + CRM task)
T0 + 2 bd     reminder
T0 + 5 bd     reminder
T0 + 6 bd     escalate to Jovan
on completion stop
```

**External (client silent).**

```
72h    follow-up
+3d    follow-up
+5d    follow-up
+15d   final follow-up
then   tag cold / nurture
```

**Event reminders.** Contract/close: 3d and 7d before the expected close date.

---

## 9. Data model

### `deal_map` (Postgres, shared fleet DB)

As defined in 5.1.

### Reuse

- `audit_log` (one row per agent action; existing).
- `kill_switch` (per-agent; existing).
- `asana_map` (analogous mapping; existing).
- `llm_usage`, `gmail_inbox_status` (existing).

---

## 10. Interfaces and components

| Component | Type | Responsibility | Depends on |
|---|---|---|---|
| n8n signing branch | workflow | one HMAC V2 POST per stage change | stage IDs |
| `deal-stage` webhook route | Hermes orchestrator config | verify HMAC, idempotency, route | `deal_stages.yaml` |
| `deal_stages.yaml` | config | stage to (domain, task_type, action) | decisions in this spec |
| `deal_map` | table | deal to task record, idempotent | Postgres |
| `kanban-hubspot-bridge` | plugin | UPSERT `deal_map`; writeback trigger | kanban hooks, n8n |
| reminder engine | agent logic / schedule | internal and external cadences | task states |
| form-to-document pipeline | n8n plus Google Docs API | form to branded doc plus PDF | templates |
| deck generator | Google Drive plus Slides API | master to branded editable deck | master file, service account |
| writeback policy | config plus agent limits | scoped writes with confidence gate | `deal_map`, `audit_log` |
| panel visibility | Next.js | deal-to-task state view | `deal_map` |

---

## 11. Error handling and safety

- Invalid HMAC: reject with 401 and drop. Never proceed.
- Unknown `dealstage`: notify the general Telegram group, create no task. Fail visible, never silent.
- Target agent killed (F8): park the task and notify, following the existing kill-switch pattern.
- Duplicate delivery: safe and idempotent via `(deal_id, dealstage)`.
- Agent blocked: `kanban_block` with a specific reason; surface in the panel.
- Client sends never automatic; draft-only is a hard contractual clause.
- QuickBooks writes unchanged: only `gateway`, with human `approve_write` (SF20).

---

## 12. Testing and verification

- **Unit.** HMAC verification; routing map lookup; idempotent second delivery creates no duplicate.
- **Integration.** Signed POST per stage in a sandbox pipeline; assert a kanban task, a `deal_map` row, and an `audit_log` row for each.
- **Deck generator.** Golden test: given the master and a fixed Solution Brief, assert the output deck contains exactly the selected sections, the prospect logo, and the prospect accent colors, with no editing rails.
- **Form pipeline.** Per form, assert the generated PDF matches the template with all placeholders replaced.
- **Gates.** `verify_deal_map.sh` and `verify_audit.sh` must pass before a task is considered closed.

---

## 13. Rollout and phasing

| Phase | Scope |
|---|---|
| P1 | SP1 spine: bridge plus routing plus `deal_map` |
| P2 | SP2 owner tasks plus reminder engine plus templates (stage 2 and stage 6 first, then 4 and 5) |
| P3 | SP5 Close/PO Details intake (kills onboarding double entry) plus Loss Reason |
| P4 | SP4 presentation generator |
| P5 | SP5 Quote/Negotiation Details plus QB Estimate wiring |
| P6 | SP3 writeback policy, then SP6 visibility |

---

## 14. Risks and assumptions

1. **Stage IDs.** The seven names map to HubSpot default IDs. Confirmed by the live Switch conditions in `webhook-deal-stage.json`.
2. **Live workflow state.** Whether "Webhook Deal Stage" is active and whether the `CHANGES.md` patches are applied is unverified.
3. **Master deck access.** Resolved: a Google service account has full Drive and Slides API access (D11). The only remaining item is designating the canonical master file; the current artifact is a working copy (`COPIA COORDENADAS...`).
4. **Slides API limits.** Logo swap and per-shape color replacement are supported. Applying a full theme is deliberately not in scope.
5. **Spec traceability.** The canonical `General-spec/spec.md` (F1 to F10 and SF1 to SF20) is not reachable in the repos. Needed for full requirement traceability.
6. **Reminder delivery channel.** Whether client reminders go by email, WhatsApp, or both is not yet fixed, and is executor dependent.

---

## 15. Appendix

### A. Client journey (source: Factronics knowledge base)

A manufacturer (cluster #1 Miami food and beverage; then pharma/compounding; then cosmetics) with an FDA/FSMA/DSCSA/MoCRA traceability need or a failing coding line becomes a lead via website, ads, LinkedIn, Instagram, referral, or direct route prospecting. The sales arc is: qualify, viability, solution presentation, negotiation, close expectation, won, or lost. On close, installation follows, then ongoing consumables and service. Personas: Risk-Averse Owner, Compliance-Scarce Regulator, Scaling Founder, Internal Champion.

### B. Reference IDs

- n8n "Webhook Deal Stage": `oGMm7eDclq6VrVfW`
- n8n "Product Details Form": `eIO36RTLqMcCjcfE`
- n8n "Equipment Installation Form": `JL93sJ79F2peDf6Y`
- Hermes webhook base: `/p/orchestrator/webhooks/` (port 8644)
- Product Details Form: `f85e5ef8-f91c-4a29-b587-fd23bbb38b88` (16 fields)
- Equipment Installation Form: `740f1057-9086-4315-9958-65c438af98b7` (33 fields)

### C. Source documents

- `05_projects/Hermes_Proposal/` (proposal, blueprint, RFP)
- `factronics-hermes-fleet` branch `audit/icm-contract-fidelity` (`AGENTS.md`, `fleet.yaml`, `docs/fleet-decisions.md`, `docs/tech-decisions.md`, `n8n/factronics-forms-live/CHANGES.md`)
- Fleet report, 2026-09-24 (`reporte-fleet-factronics-2026-09-24.md`)
- Knowledge base: `01_knowledge_base/`, `04_hl_subaccount_config/v1/research/01_Strategy_Brief.md`, `02_Conversation_Flow_Final.md`
- Master deck: `COPIA COORDENADAS - Irrisept_Intro_to_Linx_Technologies_Presentation.pptx`