github-integration

--- ## 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 1. **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 2. **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 3. **Implement automation** - Build or reuse scripts/actions with least privilege - Add logging/metrics and sandbox tests - Gate production rollout with dry runs and approvals 4. **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