Hubspot Deal Pipeline AutomationSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: hubspot-deal-pipeline-automation
description: |
  Automate and audit HubSpot deal pipeline operations without destroying real
  pipeline — covering stage automation loops, stale-deal safe-close logic,
  forecast reconciliation, custom property drift detection, quota dashboard
  cache-busting, and multi-pipeline duplicate detection. Use when writing or
  debugging workflow automations that move deals between stages, auditing
  pipelines for stale or duplicated opportunities, reconciling forecast numbers
  that disagree across reports, or hardening RevOps dashboards against property
  deletions and reporting-cache lag. Trigger with "hubspot deal pipeline",
  "hubspot stage automation", "hubspot stale deals", "hubspot forecast
  reconciliation", "hubspot quota dashboard", "hubspot duplicate deals",
  "revops pipeline audit".
allowed-tools: Read, Write, Bash(curl:*), Bash(jq:*), Bash(python3:*)
version: 2.9.0
license: MIT
author: Jeremy Longshore <[email protected]>
compatibility: Designed for Claude Code
tags:
  - hubspot
  - crm
  - deals
  - revops
  - pipeline
---

# HubSpot Deal Pipeline Automation

## Overview

Automate HubSpot deal pipelines without blowing up real revenue. This is not a
walkthrough of workflow builder UI — it is the engineering behind six failure
modes that silently destroy RevOps data while every dashboard stays green until
a rep's quota call reveals the damage.

The six production failures this skill prevents:

1. **Stage automation loops** — a workflow moves a deal to "Demo Scheduled",
   which triggers a second workflow enrolled on "Demo Scheduled" that moves it
   back to "Qualified", which triggers the first workflow again. The deal
   bounces between stages until HubSpot's 100-action daily workflow execution
   limit for that deal is exhausted. RevOps sees "workflow failure" alerts but
   no stage history that makes sense.

2. **Stale-deal auto-closing** — a cleanup workflow auto-closes deals older
   than 90 days to clear pipeline bloat. The contact associated with deal #4872
   responded to an email this morning. The deal is closed as Lost. The rep calls
   the contact, who says "I just told someone we were ready to sign." This
   failure costs quota attainment, not just data quality.

3. **Forecast query inconsistency** — `amount`, `hs_projected_amount`, and a
   custom `arr_value` property all exist on the same deal. The CRO dashboard
   queries `amount`. The ops team queries `hs_projected_amount`. RevOps built a
   custom rollup on `arr_value`. At end of quarter they produce three different
   forecast numbers for the same deal set with no canonical answer.

4. **Custom property reporting gap** — a RevOps engineer renames
   `deal_source_detail` to `original_lead_source` in the property settings.
   Every deal-source dashboard built on the old property name silently returns
   zero. No error is thrown. The board sees a 100% collapse in deal source
   tracking that is entirely an artifact, not a pipeline signal.

5. **Quota dashboard staleness** — HubSpot's reporting layer caches deal stage
   aggregates. A deal closes at 4:47pm. The quota attainment dashboard doesn't
   reflect it until 8:30pm. A rep who hit quota at EOD is told they're 3%
   short. This is a 4-hour cache lag in the default reporting stack, and it
   affects every quota conversation at month-end.

6. **Multi-pipeline deal duplication** — a new business opportunity becomes an
   expansion after the initial close. Someone creates a deal in the Expansion
   pipeline for the same company without deleting the original, or a workflow
   auto-creates expansion deals. The same revenue is counted in two pipeline
   forecasts with no cross-reference key linking them.

## Prerequisites

All API calls use a HubSpot private app token or OAuth access token in the
`Authorization: Bearer $HUBSPOT_TOKEN` header. The `hubspot-auth` skill covers
token caching, rotation, and rate-limit backoff patterns. For deal pipeline
automation, the required scopes are listed below.

- HubSpot Sales Hub Professional or Enterprise (workflows + custom properties
  - API access)
- Private app token with scopes:
  `crm.objects.deals.read`, `crm.objects.deals.write`,
  `crm.schemas.deals.read`, `crm.schemas.deals.write`,
  `crm.associations.read`, `crm.associations.write`,
  `automation`
- Node.js 18+ or Python 3.10+ in the execution environment
- `jq` installed for shell-based audit scripts
- HubSpot portal ID (visible at top-right of any HubSpot page, or via
  `GET /oauth/v1/access-tokens/$TOKEN`)

## Instructions

Build in this order. Each section neutralizes one production failure mode.

### 1. Stage transition guard (neutralizes automation loops)

Workflow loops happen when a stage-change trigger has no memory of what caused
the change. The guard injects a sentinel property `hs_pipeline_loop_guard`
(type: `string`, format: `workflowId:epochMs`) that any workflow writes
immediately before it changes a stage, and reads before it fires. If the guard
was written by the same workflow within a debounce window, the workflow aborts.

**Create the sentinel property first (one-time setup per portal):**

```bash
curl -s -X POST "https://api.hubapi.com/crm/v3/properties/deals" \
  -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hs_pipeline_loop_guard",
    "label": "Pipeline Loop Guard",
    "type": "string",
    "fieldType": "text",
    "groupName": "dealinformation",
    "description": "Automation loop sentinel. Format: workflowId:epochMs. Written before any stage transition."
  }' | jq '{name, label, type}'
```

**TypeScript guard — wrap every stage-change call in this:**

```typescript
const DEBOUNCE_MS = 60_000; // 60s window per workflow

async function safeStageTransition(
  dealId: string,
  workflowId: string,
  targetStageId: string,
  token: string,
): Promise<{ transitioned: boolean; reason: string }> {
  // Read current guard value
  const deal =

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.