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 07:57:19 -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/templates/repo-template/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/sop/templates/repo-template/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,61 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: '[BUG] '
+labels: 'type:bug, priority:p2'
+assignees: ''
+---
+
+## Description
+
+<!-- Clear and concise description of the bug -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen -->
+
+## Actual Behavior
+
+<!-- What actually happens -->
+
+## Environment
+
+- **Environment:** (production / staging / local)
+- **Browser/Client:** (if applicable)
+- **OS:** (if applicable)
+- **Version/Commit:**
+
+## Screenshots/Logs
+
+<!-- If applicable, add screenshots or relevant error logs -->
+
+```
+Paste error logs here
+```
+
+## Possible Fix
+
+<!-- Optional: Suggest a potential solution or workaround -->
+
+## Additional Context
+
+<!-- Any other relevant information -->
+
+## Impact
+
+- [ ] Blocks production users
+- [ ] Blocks internal users
+- [ ] Minor inconvenience
+- [ ] Nice to have fix
+
+## Related
+
+- **Asana Task:** [link]
+- **Salesforce Case:** [link]
+- **Related Issues:** #
--- a/sop/templates/repo-template/.github/ISSUE_TEMPLATE/deployment_checklist.md
+++ b/sop/templates/repo-template/.github/ISSUE_TEMPLATE/deployment_checklist.md
@@ -0,0 +1,114 @@
+---
+name: Deployment Checklist
+about: Pre/post deployment checklist
+title: '[DEPLOY] Release v'
+labels: 'type:deployment, priority:p1'
+assignees: ''
+---
+
+## Release Information
+
+- **Version:** v
+- **Target Date:**
+- **Environment:** (staging / production)
+- **Deployment Window:**
+
+## Pre-Deployment Checklist
+
+### Code & Testing
+- [ ] All PRs merged to `main`
+- [ ] CI pipeline passes (tests, lint, build)
+- [ ] Security scans pass
+- [ ] Code review completed
+- [ ] Release notes drafted
+
+### Infrastructure
+- [ ] Database migrations tested in staging
+- [ ] Environment variables updated (if needed)
+- [ ] Secrets rotated (if needed)
+- [ ] Resource scaling planned (if needed)
+
+### Stakeholder Communication
+- [ ] Asana tasks updated with deploy plan
+- [ ] Salesforce Project record current
+- [ ] #deploys channel notified
+- [ ] Customer success team informed (if customer-facing changes)
+
+### Backup & Rollback
+- [ ] Database backup created
+- [ ] Current version tagged for rollback
+- [ ] Rollback procedure documented
+
+## Deployment Steps
+
+1. [ ] Tag release in GitHub
+2. [ ] Trigger deploy workflow
+3. [ ] Monitor deployment logs
+4. [ ] Wait for health checks to pass
+5. [ ] Verify backend API responding
+6. [ ] Verify frontend loads correctly
+
+## Post-Deployment Checklist
+
+### Verification
+- [ ] Health checks passing
+- [ ] Critical user flows tested
+- [ ] Database migrations applied
+- [ ] No errors in application logs
+- [ ] No spike in error rates (monitoring)
+- [ ] Performance metrics within acceptable range
+
+### Stakeholder Updates
+- [ ] Salesforce Project record updated (automated)
+- [ ] Asana deploy task marked complete (automated)
+- [ ] Slack notification sent (automated)
+- [ ] Release notes published
+
+### Monitoring
+- [ ] Set up alerts for next 24 hours
+- [ ] Monitor error rates
+- [ ] Monitor performance metrics
+- [ ] Check user feedback channels
+
+## Rollback Plan
+
+**Trigger Rollback If:**
+- Critical functionality broken
+- Error rate > 5%
+- Performance degradation > 50%
+- Database corruption detected
+
+**Rollback Procedure:**
+1. Navigate to: https://github.com/$REPO/actions/workflows/rollback.yml
+2. Click "Run workflow"
+3. Enter previous stable SHA:
+4. Enter rollback reason:
+5. Monitor rollback completion
+
+## Issues Discovered
+
+<!-- Document any issues found during/after deployment -->
+
+| Issue | Severity | Status | Resolution |
+|-------|----------|--------|------------|
+|       |          |        |            |
+
+## Post-Mortem Notes
+
+<!-- After deployment, document lessons learned -->
+
+**What went well:**
+-
+
+**What could be improved:**
+-
+
+**Action items:**
+- [ ]
+- [ ]
+
+## Related
+
+- **Release Notes:** [link]
+- **Salesforce Project:** [link]
+- **Asana Deploy Task:** [link]
--- a/sop/templates/repo-template/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/sop/templates/repo-template/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,57 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: '[FEATURE] '
+labels: 'type:feature, priority:p3'
+assignees: ''
+---
+
+## Problem/Need
+
+<!-- What problem does this feature solve? Who needs it? -->
+
+## Proposed Solution
+
+<!-- Describe your proposed solution -->
+
+## Alternatives Considered
+
+<!-- What other approaches did you consider? Why is this the best option? -->
+
+## User Stories
+
+<!-- How will users interact with this feature? -->
+
+As a **[user type]**, I want **[goal]** so that **[benefit]**.
+
+## Success Criteria
+
+<!-- How will we know this feature is successful? -->
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Technical Considerations
+
+<!-- Any technical constraints, dependencies, or implementation notes -->
+
+## Mockups/Designs
+
+<!-- Optional: Add mockups, wireframes, or design references -->
+
+## Priority Justification
+
+- **Business Value:** (High / Medium / Low)
+- **Technical Complexity:** (High / Medium / Low)
+- **User Impact:** (High / Medium / Low)
+
+## Related
+
+- **Asana Epic:** [link]
+- **Salesforce Opportunity:** [link]
+- **Related Issues:** #
+
+## Additional Context
+
+<!-- Any other relevant information -->
--- a/sop/templates/repo-template/.github/branch-protection.md
+++ b/sop/templates/repo-template/.github/branch-protection.md
@@ -0,0 +1,206 @@
+# Branch Protection Configuration
+
+This document specifies the branch protection rules to be applied to all BlackRoad project repositories.
+
+## Main Branch Protection
+
+**Branch:** `main`
+
+### Settings
+
+**Require Pull Request:**
+- ✅ Require a pull request before merging
+- Require approvals: **1**
+- Dismiss stale pull request approvals when new commits are pushed
+- Require review from Code Owners (if CODEOWNERS file exists)
+
+**Status Checks:**
+- ✅ Require status checks to pass before merging
+- ✅ Require branches to be up to date before merging
+
+**Required Status Checks:**
+- `test (3.11)`
+- `test (3.12)`
+- `lint`
+- `build`
+- `security / summary` (allow to fail)
+
+**Restrictions:**
+- ✅ Restrict who can push to matching branches
+- Allowed to push: **Repository admins only**
+- Allowed to bypass: **None** (not even admins)
+
+**Other Rules:**
+- ✅ Require linear history (enforce rebase or squash merge)
+- ✅ Require deployments to succeed before merging (if applicable)
+- ✅ Lock branch (prevent all changes) - **❌ Disabled** (allow normal development)
+- ✅ Do not allow force pushes
+- ✅ Do not allow deletions
+
+**Enforcement:**
+- ✅ Include administrators (admins must follow the same rules)
+
+---
+
+## Development Branch Protection (Optional)
+
+**Branch:** `develop` (if using GitFlow)
+
+### Settings
+
+**Require Pull Request:**
+- ✅ Require a pull request before merging
+- Require approvals: **1**
+
+**Status Checks:**
+- ✅ Require status checks to pass before merging
+- Required checks: `test`, `lint`, `build`
+
+**Other Rules:**
+- ✅ Do not allow force pushes
+- ✅ Do not allow deletions
+
+---
+
+## Tag Protection
+
+**Pattern:** `v*` (all version tags)
+
+### Settings
+- ✅ Only repository admins can create tags matching this pattern
+- ✅ Only repository admins can delete tags matching this pattern
+
+**Purpose:** Prevent accidental or malicious deletion of release tags
+
+---
+
+## Implementation
+
+### Via GitHub API
+
+Use this script to apply branch protection rules programmatically:
+
+```bash
+#!/bin/bash
+
+REPO="blackboxprogramming/blackroad-{PROJECT_KEY}-backend"
+BRANCH="main"
+TOKEN="${GITHUB_TOKEN}"
+
+curl -X PUT \
+  "https://api.github.com/repos/${REPO}/branches/${BRANCH}/protection" \
+  -H "Authorization: token ${TOKEN}" \
+  -H "Accept: application/vnd.github.v3+json" \
+  -d '{
+    "required_status_checks": {
+      "strict": true,
+      "contexts": [
+        "test (3.11)",
+        "test (3.12)",
+        "lint",
+        "build"
+      ]
+    },
+    "enforce_admins": true,
+    "required_pull_request_reviews": {
+      "dismissal_restrictions": {},
+      "dismiss_stale_reviews": true,
+      "require_code_owner_reviews": true,
+      "required_approving_review_count": 1
+    },
+    "restrictions": null,
+    "required_linear_history": true,
+    "allow_force_pushes": false,
+    "allow_deletions": false
+  }'
+```
+
+### Via GitHub Web UI
+
+1. Go to repository → Settings → Branches
+2. Click "Add branch protection rule"
+3. Branch name pattern: `main`
+4. Configure settings as specified above
+5. Click "Create" or "Save changes"
+
+---
+
+## CODEOWNERS File
+
+Create `.github/CODEOWNERS` to automatically request reviews from specific teams:
+
+```
+# Default owners for everything
+* @blackboxprogramming/engineering
+
+# Backend code
+/backend/ @blackboxprogramming/backend-team
+
+# Frontend code
+/frontend/ @blackboxprogramming/frontend-team
+
+# Infrastructure
+/ops/ @blackboxprogramming/devops-team
+/terraform/ @blackboxprogramming/devops-team
+/.github/workflows/ @blackboxprogramming/devops-team
+
+# Documentation
+/docs/ @blackboxprogramming/documentation-team
+*.md @blackboxprogramming/documentation-team
+
+# Security-sensitive files
+/secrets/ @blackboxprogramming/security-team
+.env.* @blackboxprogramming/security-team
+```
+
+---
+
+## Merge Strategy
+
+**Preferred:** Squash and merge
+
+**Reasoning:**
+- Clean, linear history
+- Each PR becomes a single commit
+- Easy to revert if needed
+- Clear attribution
+
+**Alternative:** Rebase and merge (for repos with well-structured commit history)
+
+**Avoid:** Merge commits (creates messy history)
+
+---
+
+## Exceptions
+
+**When to bypass branch protection:**
+- **NEVER** for regular development
+- Only in absolute emergencies:
+  - Critical production bug fix (with manager approval)
+  - Security vulnerability patch (with security team approval)
+  - Service outage (with on-call engineer approval)
+
+**Process for emergency bypass:**
+1. Get approval in #ops or #engineering Slack channel
+2. Document reason in channel
+3. Make the emergency change
+4. Create follow-up PR immediately after to document the change
+5. Post-mortem within 24 hours
+
+---
+
+## Monitoring
+
+**Weekly:** Review bypass logs
+**Monthly:** Audit branch protection settings across all repos
+**Quarterly:** Review and update required status checks
+
+**Tool:** Use GitHub audit log API to track who bypassed protection and why
+
+---
+
+## Related
+
+- [GitHub Actions: CI Workflow](../../github-actions/ci.yml)
+- [New Client Kickoff Workflow](../../workflows/new-client-kickoff.md)
+- [Pull Request Template](./pull_request_template.md)
--- a/sop/templates/repo-template/.github/labels.json
+++ b/sop/templates/repo-template/.github/labels.json
@@ -0,0 +1,137 @@
+[
+  {
+    "name": "type:feature",
+    "color": "0E8A16",
+    "description": "New feature or enhancement"
+  },
+  {
+    "name": "type:bug",
+    "color": "D73A4A",
+    "description": "Bug or defect"
+  },
+  {
+    "name": "type:docs",
+    "color": "0075CA",
+    "description": "Documentation changes"
+  },
+  {
+    "name": "type:refactor",
+    "color": "FBCA04",
+    "description": "Code refactoring without functionality change"
+  },
+  {
+    "name": "type:test",
+    "color": "BFD4F2",
+    "description": "Test-related changes"
+  },
+  {
+    "name": "type:chore",
+    "color": "FEF2C0",
+    "description": "Maintenance, dependencies, tooling"
+  },
+  {
+    "name": "type:security",
+    "color": "D93F0B",
+    "description": "Security-related changes"
+  },
+  {
+    "name": "type:deployment",
+    "color": "5319E7",
+    "description": "Deployment or release-related"
+  },
+  {
+    "name": "priority:p0",
+    "color": "B60205",
+    "description": "Critical - Drop everything"
+  },
+  {
+    "name": "priority:p1",
+    "color": "D93F0B",
+    "description": "High - Should be next"
+  },
+  {
+    "name": "priority:p2",
+    "color": "FBCA04",
+    "description": "Medium - Normal priority"
+  },
+  {
+    "name": "priority:p3",
+    "color": "C5DEF5",
+    "description": "Low - Nice to have"
+  },
+  {
+    "name": "area:backend",
+    "color": "5319E7",
+    "description": "Backend/API changes"
+  },
+  {
+    "name": "area:frontend",
+    "color": "1D76DB",
+    "description": "Frontend/UI changes"
+  },
+  {
+    "name": "area:ops",
+    "color": "0E8A16",
+    "description": "Infrastructure/DevOps"
+  },
+  {
+    "name": "area:infra",
+    "color": "006B75",
+    "description": "Infrastructure as code"
+  },
+  {
+    "name": "area:database",
+    "color": "5319E7",
+    "description": "Database/schema changes"
+  },
+  {
+    "name": "status:blocked",
+    "color": "D93F0B",
+    "description": "Blocked by external dependency"
+  },
+  {
+    "name": "status:in-review",
+    "color": "FBCA04",
+    "description": "In code review"
+  },
+  {
+    "name": "status:needs-info",
+    "color": "D876E3",
+    "description": "Needs more information"
+  },
+  {
+    "name": "status:wontfix",
+    "color": "FFFFFF",
+    "description": "Will not be addressed"
+  },
+  {
+    "name": "release",
+    "color": "0E8A16",
+    "description": "Trigger deployment on merge"
+  },
+  {
+    "name": "breaking-change",
+    "color": "D93F0B",
+    "description": "Contains breaking changes"
+  },
+  {
+    "name": "good-first-issue",
+    "color": "7057FF",
+    "description": "Good for newcomers"
+  },
+  {
+    "name": "help-wanted",
+    "color": "008672",
+    "description": "Extra attention needed"
+  },
+  {
+    "name": "automation",
+    "color": "BFDADC",
+    "description": "Automation or workflow changes"
+  },
+  {
+    "name": "automation-bug",
+    "color": "D93F0B",
+    "description": "Automation system malfunction"
+  }
+]
--- a/sop/templates/repo-template/.github/pull_request_template.md
+++ b/sop/templates/repo-template/.github/pull_request_template.md
@@ -0,0 +1,50 @@
+## What
+
+<!-- Brief description of what this PR changes -->
+
+## Why
+
+<!-- Business/technical justification for these changes -->
+
+## How
+
+<!-- Implementation approach and key technical decisions -->
+
+## Testing
+
+- [ ] Unit tests added/updated
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] Edge cases considered
+
+## Checklist
+
+- [ ] Code follows project style guidelines
+- [ ] Self-reviewed the code
+- [ ] Commented complex/non-obvious code
+- [ ] Documentation updated (if applicable)
+- [ ] No new warnings introduced
+- [ ] Backward compatibility maintained (or breaking changes documented)
+
+## Screenshots/Logs
+
+<!-- If applicable, add screenshots or relevant logs -->
+
+## Related
+
+- **Asana Task:** [link]
+- **Salesforce Project:** [link]
+- **Related Issues:** Closes #
+
+## Deployment Notes
+
+<!-- Any special deployment steps, migrations, or configuration changes needed -->
+
+---
+
+**Reviewer Checklist:**
+- [ ] Code is clean and maintainable
+- [ ] Tests are adequate
+- [ ] No security vulnerabilities introduced
+- [ ] Performance implications considered
+- [ ] Documentation is clear