LIBRARY-FIRST PROTOCOL (MANDATORY)
Before writing ANY code, you MUST check:
Step 1: Library Catalog
- Location:
.claude/library/catalog.json
- If match >70%: REUSE or ADAPT
Step 2: Patterns Guide
- Location:
.claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
- If pattern exists: FOLLOW documented approach
Step 3: Existing Projects
- Location:
D:\Projects\*
- If found: EXTRACT and adapt
Decision Matrix
| Match |
Action |
| Library >90% |
REUSE directly |
| Library 70-90% |
ADAPT minimally |
| Pattern exists |
FOLLOW pattern |
| In project |
EXTRACT |
| No match |
BUILD (add to library after) |
STANDARD OPERATING PROCEDURE
Purpose
Design and implement GitHub-centric integrations (API, Apps, webhooks) with secure auth, observability, and rollback-ready automation.
Trigger Conditions
- Positive: Need GitHub automation or webhook bridge; Integrating GitHub with external systems; Auditable GitHub API usage across repos
- Negative: Release orchestration (route to github-release-management); Cross-repo campaign (route to github-multi-repo); Project board design (route to github-project-management)
Guardrails
- Structure-first: keep SKILL.md aligned with examples/, tests/, and any resources/references so downstream agents always have scaffolding.
- Adversarial validation is mandatory: cover boundary cases, failure paths, and rollback drills before declaring the SOP complete.
- Prompt hygiene: separate hard vs. soft vs. inferred constraints and confirm inferred constraints before acting.
- Explicit confidence ceilings: format as 'Confidence: X.XX (ceiling: TYPE Y.YY)' and never exceed the ceiling for the claim type.
- MCP traceability: tag sessions WHO=operations-{name}-{session_id}, WHY=skill-execution, and capture evidence links in outputs.
- Avoid anti-patterns: undocumented changes, missing rollback paths, skipped tests, or unbounded automation without approvals.
Required Artifacts
- SKILL.md (this SOP)
- readme.md with usage examples
- examples/ for integration flows
- tests/ for scripts/actions
- resources/ and shared-scripts/ for reuse
- references/ with API constraints
Execution Phases
Assess integration surface
- Map repos, events, and permissions required
- Confirm auth model (GitHub App, PAT, OIDC) and rotation plan
- Identify rate limits and audit requirements
Design event and API flows
- Define webhook payload handling, retries, and signature validation
- Specify idempotency, deduplication, and backoff policies
- Plan data mapping and error handling between systems
Implement automation
- Build or reuse scripts/actions with least privilege
- Add logging/metrics and sandbox tests
- Gate production rollout with dry runs and approvals
Validate and operate
- Run integration tests and failure-injection scenarios
- Set up monitoring, alerts, and dashboards
- Document runbooks, fallbacks, and support contacts
Output Format
- Integration design doc with events, permissions, and rate-limit posture
- Auth and secret management plan with rotation cadence
- Implemented automation artifacts (scripts/actions) with test evidence
- Monitoring and alert plan with dashboards/links
- Runbook with rollback/disablement steps and owners
Validation Checklist
- Tokens/keys scoped to least privilege and rotated
- Webhook verification, retries, and idempotency tested
- Integration tested in staging or dry-run mode
- Audit trail and observability hooks enabled
- Confidence ceiling stated for go-live
Confidence: 0.70 (ceiling: inference 0.70) - GitHub integration steps follow validated automation guardrails
1---2name: github-integration3description: Build reliable GitHub integrations, webhooks, and automation bridges4---5678---910## LIBRARY-FIRST PROTOCOL (MANDATORY)1112**Before writing ANY code, you MUST check:**1314### Step 1: Library Catalog15- Location: `.claude/library/catalog.json`16- If match >70%: REUSE or ADAPT1718### Step 2: Patterns Guide19- Location: `.claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md`20- If pattern exists: FOLLOW documented approach2122### Step 3: Existing Projects23- Location: `D:\Projects\*`24- If found: EXTRACT and adapt2526### Decision Matrix27| Match | Action |28|-------|--------|29| Library >90% | REUSE directly |30| Library 70-90% | ADAPT minimally |31| Pattern exists | FOLLOW pattern |32| In project | EXTRACT |33| No match | BUILD (add to library after) |3435---3637## STANDARD OPERATING PROCEDURE3839### Purpose40Design and implement GitHub-centric integrations (API, Apps, webhooks) with secure auth, observability, and rollback-ready automation.4142### Trigger Conditions43- **Positive:** Need GitHub automation or webhook bridge; Integrating GitHub with external systems; Auditable GitHub API usage across repos44- **Negative:** Release orchestration (route to github-release-management); Cross-repo campaign (route to github-multi-repo); Project board design (route to github-project-management)4546### Guardrails47- Structure-first: keep SKILL.md aligned with examples/, tests/, and any resources/references so downstream agents always have scaffolding.48- Adversarial validation is mandatory: cover boundary cases, failure paths, and rollback drills before declaring the SOP complete.49- Prompt hygiene: separate hard vs. soft vs. inferred constraints and confirm inferred constraints before acting.50- Explicit confidence ceilings: format as 'Confidence: X.XX (ceiling: TYPE Y.YY)' and never exceed the ceiling for the claim type.51- MCP traceability: tag sessions WHO=operations-{name}-{session_id}, WHY=skill-execution, and capture evidence links in outputs.52- Avoid anti-patterns: undocumented changes, missing rollback paths, skipped tests, or unbounded automation without approvals.5354### Required Artifacts55- SKILL.md (this SOP)56- readme.md with usage examples57- examples/ for integration flows58- tests/ for scripts/actions59- resources/ and shared-scripts/ for reuse60- references/ with API constraints6162### Execution Phases631. **Assess integration surface**64 - Map repos, events, and permissions required65 - Confirm auth model (GitHub App, PAT, OIDC) and rotation plan66 - Identify rate limits and audit requirements67682. **Design event and API flows**69 - Define webhook payload handling, retries, and signature validation70 - Specify idempotency, deduplication, and backoff policies71 - Plan data mapping and error handling between systems72733. **Implement automation**74 - Build or reuse scripts/actions with least privilege75 - Add logging/metrics and sandbox tests76 - Gate production rollout with dry runs and approvals77784. **Validate and operate**79 - Run integration tests and failure-injection scenarios80 - Set up monitoring, alerts, and dashboards81 - Document runbooks, fallbacks, and support contacts8283### Output Format84- Integration design doc with events, permissions, and rate-limit posture85- Auth and secret management plan with rotation cadence86- Implemented automation artifacts (scripts/actions) with test evidence87- Monitoring and alert plan with dashboards/links88- Runbook with rollback/disablement steps and owners8990### Validation Checklist91- Tokens/keys scoped to least privilege and rotated92- Webhook verification, retries, and idempotency tested93- Integration tested in staging or dry-run mode94- Audit trail and observability hooks enabled95- Confidence ceiling stated for go-live9697Confidence: 0.70 (ceiling: inference 0.70) - GitHub integration steps follow validated automation guardrails
DNYoussef