@arkone_ai/pipeline-report 1.0.0

package/README.md

@@ -0,0 +1,31 @@
+# @arkone_ai/pipeline-report
+
+A [Claude Code](https://claude.ai/code) skill that generates pipeline snapshot reports with forecasting, velocity metrics, and at-risk deal analysis.
+
+## Install
+
+```bash
+npm install -g @arkone_ai/pipeline-report
+```
+
+## Usage
+
+In any Claude Code session:
+
+```
+/pipeline-report
+```
+
+## What it does
+
+- Pulls pipeline data from HubSpot, Salesforce, or Pipedrive — or reads a local `./pipeline.csv`
+- Analyzes deals by stage (count + value), weighted pipeline (value × stage probability), and forecast (committed / best case / pipeline)
+- Calculates velocity: average days per stage, average deal cycle length
+- Identifies stale deals (no activity in 14+ days) and at-risk deals (stalled, no next steps, champion left)
+- Computes stage-to-stage conversion rates, new deals added, and deals lost with reasons
+- Produces executive summary, pipeline-by-stage table, forecast, velocity, at-risk list, and rep comparison
+- Saves to `./pipeline-report-{date}.md`
+
+## License
+
+MIT

package/install/install.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { copyFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const root = join(import.meta.dirname, '..');
+const home = homedir();
+
+const agents = [
+  { name: 'Claude Code', dir: join(home, '.claude', 'skills') },
+  { name: 'Codex',       dir: join(home, '.codex',  'skills') },
+  { name: 'Kiro',        dir: join(home, '.kiro',   'skills') },
+];
+
+const files = [
+  { src: join(root, 'skill.md'), dest: 'pipeline-report.md' },
+];
+
+let installed = 0;
+for (const agent of agents) {
+  if (!existsSync(agent.dir)) continue;
+  for (const file of files) {
+    copyFileSync(file.src, join(agent.dir, file.dest));
+  }
+  console.log(`\u2713 ${agent.name}: ${agent.dir}`);
+  installed++;
+}
+
+if (installed === 0) {
+  mkdirSync(agents[0].dir, { recursive: true });
+  for (const file of files) {
+    copyFileSync(file.src, join(agents[0].dir, file.dest));
+  }
+  console.log(`\u2713 Claude Code: ${agents[0].dir}`);
+}
+
+console.log('\nUse /pipeline-report in any supported AI session.');

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@arkone_ai/pipeline-report",
+  "version": "1.0.0",
+  "description": "Claude Code skill: generate pipeline snapshot reports with forecast, velocity metrics, and at-risk deal analysis from CRM or CSV",
+  "type": "module",
+  "scripts": { "postinstall": "node install/install.js" },
+  "bin": { "pipeline-report": "install/install.js" },
+  "files": ["skill.md", "install/", "README.md"],
+  "keywords": ["claude", "claude-code", "arkone", "bd-ops", "pipeline-report", "pipeline", "forecast"],
+  "license": "MIT",
+  "engines": { "node": ">=18" }
+}

package/skill.md

@@ -0,0 +1,225 @@
+---
+name: pipeline-report
+description: "Generate a pipeline snapshot report with deal-stage analysis, forecast, velocity metrics, and at-risk deals from CRM or local CSV. Use this skill when: 'pipeline report', 'show pipeline', 'forecast report', 'pipeline analysis', 'deal pipeline status'. Also trigger for: 'pipeline review', 'sales forecast', 'pipeline health', 'quarterly pipeline', 'pipeline snapshot'."
+license: MIT
+compatibility: Designed for Claude Code
+---
+
+# Pipeline Report
+
+Generate a pipeline snapshot: deals by stage, weighted forecast, velocity metrics, at-risk deals, and conversion rates. Pulls from HubSpot, Salesforce, Pipedrive, or a local CSV.
+
+## When to Use
+
+- Weekly or monthly pipeline reviews
+- Board meeting prep
+- Identifying stale or at-risk deals
+- Forecasting committed vs. best-case revenue
+
+## Step 1: Gather Inputs
+
+### Required
+
+| Input | Default |
+|---|---|
+| Time period | Current quarter |
+
+### Optional
+
+| Input | Default |
+|---|---|
+| Pipeline data source | Auto-detect (CRM env vars or `./pipeline.csv`) |
+| Filter by rep name | All reps |
+| Filter by stage | All stages |
+| Filter by deal size | No filter |
+| Target revenue for period | Not specified |
+| Historical comparison period | Prior quarter |
+
+## Step 2: CRM Config Discovery
+
+Check for CRM configuration in this order:
+
+### Priority 1: Environment Variables
+
+| Env Var(s) | Provider |
+|---|---|
+| `HUBSPOT_API_KEY` | HubSpot |
+| `SALESFORCE_ACCESS_TOKEN` + `SALESFORCE_INSTANCE_URL` | Salesforce |
+| `PIPEDRIVE_API_KEY` | Pipedrive |
+
+### Priority 2: Config File
+
+Check `~/.claude/crm-config.json`:
+
+```json
+{
+  "provider": "hubspot",
+  "api_key": "pat-xxxx",
+  "instance_url": "",
+  "default_pipeline": "default",
+  "default_owner": ""
+}
+```
+
+### Priority 3: Local CSV Fallback
+
+If no CRM config is found or user declines setup, look for:
+1. `./pipeline.csv` in the current directory
+2. User-specified CSV file path
+
+**Expected CSV columns:** `deal_name, company, stage, value, probability, owner, created_date, last_activity_date, close_date, next_step, notes`
+
+If none exists, ask the user to provide their pipeline data.
+
+## Step 3: Pull Pipeline Data
+
+### HubSpot
+
+```
+POST https://api.hubapi.com/crm/v3/objects/deals/search
+Authorization: Bearer {api_key}
+Body: filter by close_date within period, return deal name, amount, dealstage, owner, last activity
+```
+
+### Salesforce
+
+```
+GET {instance_url}/services/data/v59.0/query?q=SELECT+Name,Amount,StageName,OwnerId,LastActivityDate,CloseDate+FROM+Opportunity+WHERE+CloseDate>=PERIOD_START+AND+CloseDate<=PERIOD_END
+Authorization: Bearer {access_token}
+```
+
+### Pipedrive
+
+```
+GET https://api.pipedrive.com/v1/deals?status=open&api_token={key}
+Filter by expected_close_date within period
+```
+
+Apply any user-specified filters (rep, stage, deal size) after pulling data.
+
+## Step 4: Analyze the Pipeline
+
+### Deals by Stage
+
+For each stage: count of deals, total value, average deal size.
+
+### Weighted Pipeline
+
+For each deal: `weighted_value = deal_value × (stage_probability / 100)`
+
+Default stage probabilities:
+| Stage | Probability |
+|---|---|
+| Prospecting | 10% |
+| Qualification | 20% |
+| Discovery | 30% |
+| Demo / Proposal | 50% |
+| Negotiation | 70% |
+| Contract Sent | 90% |
+| Closed Won | 100% |
+| Closed Lost | 0% |
+
+Use CRM-defined probabilities if available.
+
+### Forecast
+
+| Category | Definition |
+|---|---|
+| Committed | Deals with ≥90% probability or "Commit" forecast category |
+| Best Case | Committed + deals ≥50% probability |
+| Pipeline | All open deals (weighted sum) |
+
+### Velocity Metrics
+
+- Average days per stage (based on stage entry dates if available, else last_activity_date)
+- Average total deal cycle (created_date to close_date for closed deals this period)
+- Compare to prior period if historical data available
+
+### Stale Deals
+
+Deals where `last_activity_date` is 14 or more days ago AND status is not closed.
+
+### At-Risk Deals
+
+Flag a deal as at-risk if any of these are true:
+- Time in current stage is more than 2× the average for that stage
+- No `next_step` defined
+- `next_step_date` is overdue by more than 7 days
+- Champion/primary contact left (flag for user to investigate)
+
+### Conversion Rates
+
+For each stage transition, calculate: `deals_advanced / deals_entered × 100%`
+
+## Step 5: Generate Report
+
+### Executive Summary
+
+Total pipeline value, weighted value, forecast (committed / best / pipeline), active deal count, key risks (top 3 at-risk deals), vs. target (if provided).
+
+### Pipeline by Stage Table
+
+| Stage | Deals | Total Value | Avg Size | Weighted |
+|---|---|---|---|---|
+
+### Forecast Table
+
+| Category | Value | Notes |
+|---|---|---|
+| Committed | ${amount} | {count} deals at ≥90% |
+| Best Case | ${amount} | Committed + ≥50% |
+| Pipeline | ${amount} | All open (weighted) |
+
+### Velocity Metrics
+
+| Stage | Avg Days | vs. Prior Period |
+|---|---|---|
+
+### At-Risk Deals
+
+| Deal | Company | Value | Stage | Risk Reason | Recommended Action |
+|---|---|---|---|---|---|
+
+### Rep Performance (if multi-rep)
+
+| Rep | Deals | Pipeline | Weighted | Avg Cycle | Win Rate |
+|---|---|---|---|---|---|
+
+### Trend vs. Prior Period
+
+If historical data is available: total pipeline change (%), new deals added, deals lost, win rate change.
+
+## Step 6: Save Output
+
+Save to:
+
+```
+./pipeline-report-{YYYY-MM-DD}.md
+```
+
+## Step 7: Output Summary
+
+```
+Pipeline Report Generated
+─────────────────────────
+Period:         {time period}
+Active Deals:   {count}
+Pipeline Value: ${total}
+Weighted:       ${weighted}
+Committed:      ${committed}
+At-Risk:        {count} deals
+Stale:          {count} deals
+Saved to:       ./pipeline-report-{date}.md
+```
+
+## Error Handling
+
+| Error | Action |
+|---|---|
+| CRM returns 401/403 | Inform user — credentials may be expired. Offer CSV fallback. |
+| CRM returns 500 | Warn user, retry once, then offer CSV fallback |
+| CSV not found | Ask user for file path or offer to accept pasted data |
+| CSV malformed | Show parsing error, list expected columns |
+| No deals in period | Report empty pipeline, note the time period |
+| API rate limit | Wait 10 seconds, retry once |
+| Missing stage probabilities | Use default table above |