claude-ci-integration.cspec
1 # Claude CI Integration Plan 2 # id: CSPEC-2026-001 3 # purpose: AI-powered code review integrated into Forgejo CI 4 # status: implemented 5 # priority: P2 6 # effort: 2-3 sessions 7 # created: 2026-01 8 # implemented: 2026-01-05 9 # human_doc: infra/human/CSPEC-2026-001_Claude_CI_Integration.md 10 11 # === IMPLEMENTATION STATUS === 12 implementation: 13 phase_1: complete # CIConfig, ContextLoader, CLI 14 phase_2: complete # ClaudeCIClient with all review methods 15 phase_3: complete # Forgejo workflow 16 phase_4: pending # Advanced features (caching, rate limiting, cost tracking) 17 18 files_created: 19 - tools/claude_ci.py 20 - tools/requirements.txt 21 - tools/config.example.yaml 22 - .forgejo/workflows/claude-review.yml 23 24 next_steps: 25 - Configure ANTHROPIC_API_KEY secret in Forgejo 26 - Configure FORGEJO_TOKEN secret in Forgejo 27 - Test on a real PR 28 - Begin shadow mode rollout 29 30 # === SUMMARY === 31 32 summary: 33 goal: "Integrate Claude API into CI for automated code review" 34 value: 35 - "Automated architectural enforcement (Tech Spec 3.0)" 36 - "Security-first review for privacy/cross-chain ops" 37 - "Documentation drift detection" 38 - "Reduced human review burden" 39 40 success_criteria: 41 pr_review_time: "<5 minutes" 42 security_false_positive: "<5%" 43 arch_violations_caught: "before human review" 44 monthly_cost: "<$100" 45 46 # === ARCHITECTURE === 47 48 architecture: 49 current_flow: "PR → Lint → Test → Build → Admin Review → Merge" 50 target_flow: "PR → [Lint,Test,Build,Claude Review] → Admin Approval → Merge" 51 52 merge_to_main_requirements: 53 ci_must_pass: true 54 claude_review_must_pass: true # Security gate 55 admin_approval_required: true # Human sign-off for main only 56 57 other_branches: 58 # No approval required unless explicitly configured 59 ci_optional: true 60 admin_approval: false 61 62 claude_jobs: 63 - pr_review: "Full PR analysis" 64 - security_review: "Security-focused, CWE mapping" 65 - arch_validation: "Spec compliance check" 66 - docs_sync: "Code-to-docs drift detection" 67 68 context_source: "alpha-delta-context repository" 69 context_files: 70 - "project/architecture/machine/*.cspec" 71 - "project/governance/*.md" 72 - "infra/machine/security.cspec" 73 74 # === DEPENDENCIES === 75 76 dependencies: 77 anthropic_api: "2024-10+" 78 python: "3.10+" 79 forgejo_actions: "latest" 80 context_repo: "alpha-delta-context main branch" 81 82 infrastructure: 83 forgejo: "source.ac-dc.network" 84 runner: "ci.ac-dc.network (32vCPU/64GB)" 85 86 # === IMPLEMENTATION PHASES === 87 88 phase_1_infrastructure: 89 session: 1 90 objective: "Core integration components" 91 tasks: 92 - "Create /opt/ci/tools/claude-ci/ structure" 93 - "Implement ContextLoader class" 94 - "Implement CIConfig dataclass" 95 - "Create CLI with argparse" 96 files: 97 claude_ci.py: "alpha-delta-context/tools/" 98 requirements.txt: "alpha-delta-context/tools/" 99 config.example.yaml: "alpha-delta-context/tools/" 100 verify: "python3 claude_ci.py context-info" 101 102 phase_2_api_integration: 103 session: "1-2" 104 objective: "Claude API client with review capabilities" 105 tasks: 106 - "Implement ClaudeCIClient class" 107 - "review_pull_request() method" 108 - "validate_architecture() method" 109 - "security_review() method" 110 - "sync_documentation() method" 111 models: 112 pr_review: "claude-sonnet-4-20250514" 113 security: "claude-sonnet-4-20250514" 114 architecture: "claude-opus-4-20250514" 115 max_tokens: 8192 116 max_context: 150000 117 verify: | 118 python3 claude_ci.py review --pr 1 119 python3 claude_ci.py security-review --diff /tmp/test.diff 120 python3 claude_ci.py validate-arch --commit HEAD 121 122 phase_3_forgejo_integration: 123 session: 2 124 objective: "CI workflows and Forgejo API" 125 tasks: 126 - "Implement Forgejo API helpers (get_pr_diff, post_review_comment, set_commit_status)" 127 - "Create claude-review.yml workflow" 128 - "Configure workflow secrets" 129 - "Implement CI status integration" 130 workflow_jobs: 131 - setup-context 132 - claude-review 133 - security-review 134 - architecture-validation 135 - docs-sync 136 - review-summary 137 secrets: 138 - ANTHROPIC_API_KEY 139 - FORGEJO_TOKEN 140 141 phase_4_advanced: 142 session: 3 143 objective: "Enhancements and hardening" 144 tasks: 145 - "Implementation suggestion generator" 146 - "Caching layer (context + responses)" 147 - "Rate limiting (per-PR limits)" 148 - "Observability (token usage, latency, cost)" 149 - "Manual trigger workflow" 150 - "Merge gate integration" 151 cost_limits: 152 per_pr: "$1.00" 153 per_day: "$20.00" 154 155 # === FILES MANIFEST === 156 157 files_to_create: 158 - path: "tools/claude_ci.py" 159 repo: "alpha-delta-context" 160 purpose: "Main integration script" 161 - path: "tools/requirements.txt" 162 repo: "alpha-delta-context" 163 purpose: "Python dependencies" 164 - path: ".forgejo/workflows/claude-review.yml" 165 repo: "alpha-delta-protocol" 166 purpose: "CI workflow" 167 168 files_to_modify: 169 - path: "README.md" 170 repo: "alpha-delta-context" 171 changes: "Add Claude CI section" 172 173 # === ROLLOUT === 174 175 rollout: 176 week_1_shadow: 177 mode: "post-comment: false" 178 action: "Log reviews to artifacts only" 179 goal: "Monitor costs, tune prompts" 180 181 week_2_3_advisory: 182 mode: "Comments enabled, non-blocking" 183 action: "Gather team feedback" 184 goal: "Adjust sensitivity thresholds" 185 186 week_4_enforcement: 187 mode: "Security/arch gates enabled" 188 action: "Required status check" 189 goal: "Full production" 190 191 # === COST ESTIMATES === 192 193 cost_estimates: 194 pr_review: {per_call: "$0.17", monthly_80_prs: "$13.60"} 195 security: {per_call: "$0.10", monthly_80_prs: "$8.00"} 196 architecture: {per_call: "$0.19", monthly_80_prs: "$15.20"} 197 docs_sync: {per_call: "$0.13", monthly_80_prs: "$10.40"} 198 total_monthly: "~$47" 199 200 # === FAILURE MODES === 201 202 failure_modes: 203 api_unavailable: 204 impact: "Reviews skip" 205 mitigation: "continue-on-error: true" 206 rate_limited: 207 impact: "Delayed reviews" 208 mitigation: "Exponential backoff, queue" 209 context_unavailable: 210 impact: "Reviews lack context" 211 mitigation: "Cache last-known-good" 212 malformed_response: 213 impact: "Parse error" 214 mitigation: "Fallback to raw output" 215 216 # === SECURITY === 217 218 security: 219 api_key: "Store in Forgejo secrets, rotate quarterly" 220 context_sensitivity: "May contain arch details, control access" 221 output_sanitization: "Strip leaked secrets, validate JSON" 222 223 # === ACCEPTANCE CRITERIA === 224 225 acceptance: 226 functional: 227 - "PRs receive auto Claude review comments" 228 - "Security findings categorized by severity" 229 - "Arch violations reference spec sections" 230 - "Doc drift detected and reported" 231 - "Manual trigger available" 232 non_functional: 233 - "Reviews < 5 minutes" 234 - "API errors don't block CI" 235 - "Costs < $100/month at 80 PRs" 236 - "False positive < 10%" 237 238 # === IMPLEMENTATION COMMANDS === 239 240 implementation_prompts: 241 session_1: | 242 Implement Phase 1 of CSPEC-2026-001: Create ContextLoader class 243 and CLI structure in alpha-delta-context/tools/claude_ci.py. 244 session_1_2: | 245 Implement Phase 2 of CSPEC-2026-001: Add ClaudeCIClient class 246 with review methods and JSON output parsing. 247 session_2: | 248 Implement Phase 3 of CSPEC-2026-001: Create Forgejo workflow 249 at .forgejo/workflows/claude-review.yml with parallel jobs. 250 session_3: | 251 Implement Phase 4 of CSPEC-2026-001: Add caching, rate limiting, 252 cost tracking, and manual trigger workflow.