Add complete automation SOP system for BlackRoad ERP

This implements the "Automate The Company" initiative with comprehensive Standard Operating Procedures for GitHub + Salesforce + Asana integration. New directory: sop/ ├── workflows/ - End-to-end process documentation │ ├── new-client-kickoff.md - Flagship workflow from deal → repos → Asana │ └── release-pipeline.md - Deploy → update Salesforce + Asana ├── playbooks/ - Human-friendly checklists │ └── brenda-new-client-checklist.md - Non-technical operator guide ├── salesforce/ - Salesforce automation specifications │ ├── flows/opp-automation-onstagechange.md - Trigger on Closed Won │ └── orchestrations/new-client-kickoff-orchestration.md - Multi-stage process ├── integrations/ - API integration specifications │ ├── salesforce-to-github.md - Create repos from Salesforce │ ├── github-to-salesforce.md - Update Salesforce after deploy │ └── salesforce-to-asana.md - Create Asana projects from Salesforce └── templates/ - Reusable templates ├── github-actions/ - CI/CD workflows (ci.yml, deploy.yml, safety.yml) └── repo-template/ - Standard repo config (PR template, labels, branch protection) Key Features: - Event-driven automation (Closed Won → repos + Asana creation) - GitHub Actions templates for CI/CD baseline - Salesforce Flow & Orchestration specs - Complete API integration documentation - Operator-friendly playbooks - Two-view approach (operator + engineer) - No manual status syncing across systems This provides the complete backbone for next-gen ERP automation.
2026-03-17 05:57:21 -05:00 · 2025-11-17 08:17:51 +00:00
parent 9b137af555
commit 7cde897040
18 changed files with 6077 additions and 0 deletions
--- a/sop/workflows/new-client-kickoff.md
+++ b/sop/workflows/new-client-kickoff.md
@@ -0,0 +1,384 @@
+# New Client / Project Kickoff Workflow
+
+**Owner:** Operations
+**Systems:** Salesforce → GitHub → Asana
+**Status:** Active
+**Last Updated:** 2025-11-17
+
+---
+
+## Overview
+
+This is the **flagship automation workflow** that orchestrates the entire journey from "deal closed" to "project ready for development." It connects Salesforce, GitHub, and Asana to eliminate manual setup and ensure consistency.
+
+**Flow Duration:** ~5-10 minutes (automated)
+**Human Touch Points:** Initial validation + final review
+
+---
+
+## The Golden Path
+
+```
+Salesforce Opp (Closed Won)
+    ↓
+Salesforce Flow creates Project record
+    ↓
+Orchestration kicks off (4 stages)
+    ↓
+Stage 2: Technical Setup
+    ↓
+    ├─→ GitHub: Create repos + CI/CD
+    └─→ Asana: Create project + tasks
+    ↓
+Feedback loops: Deploy events → Salesforce + Asana
+```
+
+---
+
+## Stage-by-Stage Breakdown
+
+### **Stage A: Salesforce – Opportunity Closure**
+
+**Trigger:**
+Sales Stage moves to `Closed Won` on Opportunity
+
+**Salesforce Flow:** `Opp_Automation_OnStageChange`
+
+**Actions:**
+
+1. **Validate required fields:**
+   - Account Name
+   - Primary Contact
+   - Domain/Subdomain
+   - Package Type (OS / Console / Custom)
+   - Service Tier (Starter / Pro / Enterprise)
+
+2. **Create/Update Records:**
+   - Link or create Account record
+   - Link or create Contact record (Primary)
+   - Create **Project** record (Custom Object: `Project__c`)
+
+3. **Project Record Fields:**
+   ```
+   Project_Key__c:          {ACCOUNT_SLUG}-{RANDOM_4CHAR}
+                           Example: ACME-X7K9
+
+   Account__c:              Lookup to Account
+   Opportunity__c:          Lookup to Opportunity
+   Primary_Domain__c:       Text (e.g., "acme-portal")
+   Package_Type__c:         Picklist (OS / Console / Custom)
+   Service_Tier__c:         Picklist (Starter / Pro / Enterprise)
+   Start_Date__c:           Date (auto: today)
+   Status__c:               Picklist → "Setup In Progress"
+   Technical_Owner__c:      Lookup to User
+   ```
+
+4. **Launch Orchestration:**
+   - Name: `New_Client_Kickoff_Orchestration`
+   - Input: Project record ID
+   - Stages:
+     - Sales Handoff
+     - Technical Setup ← **We care about this**
+     - Customer Onboarding
+     - Review & Go-Live
+
+**Outputs:**
+✅ Project record created
+✅ Orchestration started
+✅ Notification sent to #ops Slack channel (optional)
+
+---
+
+### **Stage B: GitHub – Repository Scaffolding**
+
+**Trigger:**
+Orchestration Stage "Technical Setup" begins
+
+**Mechanism:**
+Salesforce **Autolaunched Flow** → HTTP Callout to GitHub API (or GitHub App webhook receiver)
+
+**API Endpoint:**
+```
+POST https://api.github.com/orgs/blackboxprogramming/repos
+Authorization: Bearer {GITHUB_APP_TOKEN}
+```
+
+**Payload (per repo):**
+```json
+{
+  "name": "blackroad-{project_key}-backend",
+  "description": "Backend for {Account Name} ({Project Key})",
+  "private": true,
+  "auto_init": true,
+  "gitignore_template": "Python",
+  "license_template": "mit"
+}
+```
+
+**Repos Created:**
+
+1. `blackroad-{project_key}-backend`
+2. `blackroad-{project_key}-frontend`
+3. `blackroad-{project_key}-ops`
+
+**Apply Repo Template** (via GitHub API or Actions):
+
+1. **Branch Protection** (on `main`):
+   - Require PR before merge
+   - Require 1 approval
+   - Require status checks: `test`, `lint`, `build`
+   - No force pushes
+   - No deletions
+
+2. **Labels** (via API):
+   ```
+   type:feature, type:bug, type:docs, type:refactor
+   priority:p0, priority:p1, priority:p2, priority:p3
+   area:backend, area:frontend, area:ops, area:infra
+   status:blocked, status:in-review
+   ```
+
+3. **Issue Templates** (from `sop/templates/repo-template/.github/ISSUE_TEMPLATE/`):
+   - `bug_report.md`
+   - `feature_request.md`
+   - `deployment_checklist.md`
+
+4. **PR Template** (`.github/pull_request_template.md`)
+
+5. **GitHub Actions Workflows** (from `sop/templates/github-actions/`):
+   - `.github/workflows/ci.yml` – Run tests + lint on every push/PR
+   - `.github/workflows/deploy.yml` – Deploy on release tag or approved PR to `main`
+   - `.github/workflows/safety.yml` – SAST + dependency scanning
+   - `.github/workflows/notify-salesforce.yml` – Send deploy events back to Salesforce
+
+**Secrets Setup** (manual or via API):
+```
+RAILWAY_TOKEN
+CLOUDFLARE_API_TOKEN
+SALESFORCE_WEBHOOK_URL
+ASANA_API_TOKEN
+```
+
+**Outputs:**
+✅ 3 repos created
+✅ CI/CD pipelines active
+✅ Branch protection enabled
+✅ Repo URLs written back to Salesforce Project record:
+   - `Backend_Repo_URL__c`
+   - `Frontend_Repo_URL__c`
+   - `Ops_Repo_URL__c`
+
+---
+
+### **Stage C: Asana – Task Space for Humans**
+
+**Trigger:**
+Same Orchestration Stage "Technical Setup", after GitHub repos created
+
+**Mechanism:**
+Salesforce Flow → HTTP Callout to Asana API (or via Zapier/Make)
+
+**API Endpoint:**
+```
+POST https://app.asana.com/api/1.0/projects
+Authorization: Bearer {ASANA_PAT}
+```
+
+**Payload:**
+```json
+{
+  "data": {
+    "name": "{Account Name} - {Project Key}",
+    "notes": "Salesforce Project: {Project_URL}\nRepos:\n- Backend: {Backend_Repo_URL}\n- Frontend: {Frontend_Repo_URL}\n- Ops: {Ops_Repo_URL}",
+    "workspace": "{WORKSPACE_GID}",
+    "team": "{TEAM_GID}",
+    "default_view": "board",
+    "color": "light-green"
+  }
+}
+```
+
+**Create Sections:**
+```
+POST /projects/{project_gid}/sections
+{
+  "data": {
+    "name": "Discovery"
+  }
+}
+```
+
+Repeat for: `Architecture`, `Build`, `Testing`, `Go-Live`
+
+**Create Standard Tasks:**
+
+| Section | Task | Assignee | Description |
+|---------|------|----------|-------------|
+| Discovery | Confirm domain + DNS with client | Sales Ops | Get final domain, subdomain, and DNS setup requirements |
+| Discovery | Gather branding assets | Design | Logo, colors, fonts for custom theming |
+| Architecture | Wire up Railway/Cloudflare envs | DevOps | Create staging + production environments |
+| Architecture | Enable CI/CD secrets | DevOps | Add RAILWAY_TOKEN, CLOUDFLARE_API_TOKEN to GitHub |
+| Build | Set up database schema | Backend | Initialize Postgres + migrations |
+| Build | Implement authentication | Backend | SSO or email/password setup |
+| Testing | Run first end-to-end test | QA | Verify deploy pipeline works end-to-end |
+| Go-Live | Final client walkthrough | Customer Success | Demo + training session |
+
+**Each Task Contains:**
+- Link to Salesforce Project record
+- Link to relevant GitHub repo + issues
+- Due date (calculated from Project start date + offsets)
+
+**Outputs:**
+✅ Asana project created
+✅ Standard task set populated
+✅ Asana project URL written back to Salesforce:
+   - `Asana_Project_URL__c`
+
+---
+
+### **Stage D: Feedback Loop – GitHub → Salesforce & Asana**
+
+**Trigger:**
+GitHub events:
+- PR merged to `main` with label `release`
+- GitHub Release created
+- CI pipeline `deploy` job succeeds
+
+**Mechanism:**
+GitHub Action: `.github/workflows/notify-salesforce.yml`
+
+**Action Workflow (Pseudocode):**
+
+```yaml
+name: Notify Salesforce & Asana on Deploy
+
+on:
+  workflow_run:
+    workflows: ["Deploy"]
+    types:
+      - completed
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Extract deploy metadata
+        run: |
+          echo "SHA=${{ github.sha }}" >> $GITHUB_ENV
+          echo "TAG=${{ github.ref_name }}" >> $GITHUB_ENV
+          echo "REPO=${{ github.repository }}" >> $GITHUB_ENV
+
+      - name: Update Salesforce Project
+        run: |
+          curl -X PATCH "$SALESFORCE_WEBHOOK_URL/services/data/v58.0/sobjects/Project__c/ExternalId__c/${{ secrets.PROJECT_KEY }}" \
+            -H "Authorization: Bearer ${{ secrets.SALESFORCE_ACCESS_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d '{
+              "Last_Deploy_At__c": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
+              "Last_Deploy_SHA__c": "'$SHA'",
+              "Last_Deploy_Tag__c": "'$TAG'",
+              "Environment__c": "production",
+              "Release_Notes_URL__c": "https://github.com/'$REPO'/releases/tag/'$TAG'"
+            }'
+
+      - name: Complete Asana deploy task
+        run: |
+          TASK_GID=$(curl -s "https://app.asana.com/api/1.0/projects/${{ secrets.ASANA_PROJECT_GID }}/tasks?opt_fields=name,gid" \
+            -H "Authorization: Bearer ${{ secrets.ASANA_PAT }}" | \
+            jq -r '.data[] | select(.name | contains("Deploy to production")) | .gid')
+
+          curl -X PUT "https://app.asana.com/api/1.0/tasks/$TASK_GID" \
+            -H "Authorization: Bearer ${{ secrets.ASANA_PAT }}" \
+            -H "Content-Type: application/json" \
+            -d '{"data": {"completed": true}}'
+
+          # Post comment
+          curl -X POST "https://app.asana.com/api/1.0/tasks/$TASK_GID/stories" \
+            -H "Authorization: Bearer ${{ secrets.ASANA_PAT }}" \
+            -H "Content-Type: application/json" \
+            -d '{"data": {"text": "✅ Deployed '$TAG' from '$REPO'@'$SHA' to production"}}'
+```
+
+**Outputs:**
+✅ Salesforce Project updated with latest deploy info
+✅ Asana tasks auto-completed
+✅ Asana comments added with deploy details
+
+---
+
+## Human Touch Points (Brenda View)
+
+**What You See:**
+
+1. **Day 0 – Deal Closes:**
+   - You mark Opportunity as "Closed Won" in Salesforce
+   - Wait 5-10 minutes ⏱️
+
+2. **Day 0 – Automatic Magic:**
+   - Repos appear in GitHub (you get a Slack notification)
+   - Asana project appears with all tasks assigned
+   - No manual work needed
+
+3. **Throughout Project:**
+   - Engineers merge code → tasks auto-update in Asana
+   - Deploy happens → Salesforce shows "Last Deploy: 2 hours ago"
+   - You just monitor Asana and communicate with client
+
+**If Something Breaks:**
+- Create an issue in `blackroad-sop` repo with label `automation-bug`
+- Tag @ops or @devops team
+- Include: Salesforce Project URL, expected vs. actual behavior
+
+---
+
+## Validation Checklist
+
+After this workflow runs, verify:
+
+- [ ] Project record exists in Salesforce with all fields populated
+- [ ] 3 repos created in GitHub with correct naming
+- [ ] CI/CD workflows present in each repo
+- [ ] Branch protection enabled on `main`
+- [ ] Asana project created with 8+ tasks
+- [ ] Salesforce Project has Asana + GitHub URLs filled in
+- [ ] Test deploy updates Salesforce + Asana correctly
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| No repos created after 10 min | GitHub API token expired | Refresh token in Salesforce Named Credential |
+| Asana project missing | Webhook failed | Check Salesforce debug logs for HTTP callout errors |
+| Deploy doesn't update Salesforce | Missing secret `PROJECT_KEY` | Add `PROJECT_KEY` secret to each repo |
+| Tasks not auto-completing | Asana API token wrong | Verify `ASANA_PAT` secret in GitHub |
+
+---
+
+## Related Docs
+
+- [Salesforce Flow Spec: Opp_Automation_OnStageChange](../salesforce/flows/opp-automation-onstagechange.md)
+- [Salesforce Orchestration Spec](../salesforce/orchestrations/new-client-kickoff-orchestration.md)
+- [GitHub Actions: CI Baseline](../templates/github-actions/ci.yml)
+- [Integration: Salesforce → GitHub](../integrations/salesforce-to-github.md)
+- [Integration: GitHub → Salesforce](../integrations/github-to-salesforce.md)
+- [Playbook: Brenda's New Client Checklist](../playbooks/brenda-new-client-checklist.md)
+
+---
+
+## Metrics to Track
+
+- **Time to First Commit:** From Closed Won to first commit in project repo (target: < 48 hours)
+- **Automation Success Rate:** % of deals that auto-create repos + Asana (target: > 95%)
+- **Manual Intervention Rate:** % of projects requiring manual fixes (target: < 10%)
+- **Deploy Frequency:** Avg deploys per week per project (target: > 5)
+
+---
+
+**This is the backbone.** Every other automation workflow should follow this pattern:
+1. Event-driven trigger
+2. Cross-system orchestration
+3. Feedback loops
+4. Human-friendly visibility