brainiac-github 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0429a02480efea5f24251aa7dfc818a7140867fd971367523c35125993bdaaca'
+  data.tar.gz: a15b23fbce8f026cdc592cce528d7f1ca48fa304e21176a1d6bc6c34cdf54d5f
+SHA512:
+  metadata.gz: 60af838671e16cf03b1e0488059c216c08094661a63689ccc203361e7a337dfd9d1bacbad64563bdb2fb7dd1a59432c1ac137b5f0b854fb22ae3973da0723ecc
+  data.tar.gz: 6040fb703d23aac121df9f34c4188af9d643f8de9c8cb2d6a807954ebf57d7d56948ce32e62d1dfb58fd01e25c36de35a2eeb67ba7abad9e558a3facec0552ff

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# brainiac-github
+
+GitHub webhook plugin for [Brainiac](https://github.com/stowzilla/brainiac) — the multi-agent orchestration layer.
+
+## What It Does
+
+- **PR Reviews** — dispatches agents to address review feedback
+- **PR Comments** — routes PR conversation to the assigned agent
+- **PR Merges** — cleans up worktrees, emits hooks for card management plugins
+- **Workflow Runs** — notifies on CI failures and deploy completions
+- **Issues** — logs new issues for tracking
+
+## Installation
+
+```bash
+brainiac install github
+brainiac restart
+```
+
+## Configuration
+
+Config lives at `~/.brainiac/github.json`:
+
+```json
+{
+  "webhook_secret": "your-github-webhook-secret",
+  "repos": {}
+}
+```
+
+Generate a webhook secret:
+
+```bash
+ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
+```
+
+### GitHub Webhook Setup
+
+1. Go to your repo → Settings → Webhooks → Add webhook
+2. Payload URL: `https://your-ngrok.ngrok-free.app/github`
+3. Content type: `application/json`
+4. Secret: paste your `webhook_secret`
+5. Events: Pull requests, Pull request reviews, Issue comments, Issues, Workflow runs
+
+## CLI
+
+```bash
+brainiac github setup     # Create config file from template
+brainiac github config    # Show current configuration
+brainiac github status    # Check if webhook endpoint is active
+```
+
+## Hooks Emitted
+
+| Hook | When | Payload |
+|------|------|---------|
+| `:pr_merged` | PR merged to default branch | card_number, pr_url, project_key, ... |
+| `:pr_review_received` | Review submitted | card_number, reviewer, agent_name, ... |
+| `:pr_synchronized` | PR updated (force push) | card_number, worktree, branch, ... |
+| `:production_deployed` | Deploy workflow succeeds | project_key, project_config |
+
+## Development
+
+```bash
+git clone https://github.com/stowzilla/brainiac-github.git
+cd brainiac-github
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/brainiac/plugins/github/cli.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Github
+      module Cli
+        class << self
+          def run(args)
+            command = args.shift
+            case command
+            when "setup" then cmd_setup
+            when "config" then cmd_config
+            when "status" then cmd_status
+            else print_help
+            end
+          end
+
+          private
+
+          def cmd_setup
+            brainiac_dir = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+            config_file = File.join(brainiac_dir, "github.json")
+
+            if File.exist?(config_file)
+              puts "GitHub config already exists at #{config_file}"
+              return
+            end
+
+            template = File.expand_path("../../../../templates/github.json.example", __dir__)
+            if File.exist?(template)
+              FileUtils.cp(template, config_file)
+              puts "Created #{config_file} from template"
+            else
+              default_config = { "webhook_secret" => "", "repos" => {} }
+              File.write(config_file, JSON.pretty_generate(default_config))
+              puts "Created #{config_file}"
+            end
+
+            puts "Edit the file to add your GitHub webhook secret."
+            puts "Generate one with: ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'"
+          end
+
+          def cmd_config
+            brainiac_dir = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+            config_file = File.join(brainiac_dir, "github.json")
+
+            unless File.exist?(config_file)
+              puts "No GitHub config found. Run: brainiac github setup"
+              return
+            end
+
+            config = JSON.parse(File.read(config_file))
+            secret = config["webhook_secret"]
+            puts "GitHub Configuration:"
+            puts "  Config file: #{config_file}"
+            puts "  Webhook secret: #{secret && !secret.empty? ? "#{secret[0..5]}..." : "(not set)"}"
+            puts "  Repos: #{config.fetch("repos", {}).keys.join(", ").then { |s| s.empty? ? "(none)" : s }}"
+          end
+
+          def cmd_status
+            require "net/http"
+            uri = URI("http://localhost:4567/api/status")
+            res = Net::HTTP.get_response(uri)
+            if res.is_a?(Net::HTTPSuccess)
+              puts "✅ Brainiac server is running — GitHub webhook endpoint active at POST /github"
+            else
+              puts "⚠️  Server returned #{res.code}"
+            end
+          rescue Errno::ECONNREFUSED
+            puts "❌ Brainiac server is not running"
+          end
+
+          def print_help
+            puts "Usage: brainiac github <command>"
+            puts ""
+            puts "Commands:"
+            puts "  setup     Create GitHub config file (~/.brainiac/github.json)"
+            puts "  config    Show current GitHub configuration"
+            puts "  status    Check if GitHub webhook endpoint is active"
+          end
+        end
+      end
+
+      # Plugin CLI entry points
+      def self.cli(args)
+        Cli.run(args)
+      end
+
+      def self.completions
+        %w[setup config status]
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Github
+      module Config
+        CONFIG_FILE = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "github.json")
+
+        @config = {}
+        @last_mtime = nil
+
+        class << self
+          attr_reader :config
+
+          def load!
+            @config = load_config
+            @last_mtime = File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+          end
+
+          def reload!
+            return unless file_changed?
+
+            @config = load_config
+            @last_mtime = File.exist?(CONFIG_FILE) ? File.mtime(CONFIG_FILE) : nil
+            LOG.info "[GitHub] Reloaded configuration"
+          end
+
+          def webhook_secret
+            @config["webhook_secret"] || ENV.fetch("GITHUB_WEBHOOK_SECRET", nil)
+          end
+
+          private
+
+          def load_config
+            return {} unless File.exist?(CONFIG_FILE)
+
+            JSON.parse(File.read(CONFIG_FILE))
+          rescue JSON::ParserError => e
+            LOG.error "[GitHub] Failed to parse config: #{e.message}"
+            {}
+          end
+
+          def file_changed?
+            return false unless File.exist?(CONFIG_FILE)
+
+            current_mtime = File.mtime(CONFIG_FILE)
+            return false if @last_mtime && current_mtime == @last_mtime
+
+            @last_mtime = current_mtime
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/handler.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Github
+      module Handler
+        class << self
+          def handle_pr_merged(payload)
+            pr = payload["pull_request"]
+            branch = pr.dig("head", "ref")
+            base = pr.dig("base", "ref")
+            pr_url = pr["html_url"]
+            pr_title = pr["title"]
+            repo_full_name = payload.dig("repository", "full_name")
+
+            default_branch = payload.dig("repository", "default_branch") || "main"
+            unless base == default_branch
+              LOG.info "PR merged into #{base}, not #{default_branch} — ignoring"
+              return [200, { status: "ignored", reason: "not merged into #{default_branch}" }.to_json]
+            end
+
+            project_result = identify_project_by_repo(repo_full_name)
+            unless project_result
+              LOG.info "No project found for GitHub repo #{repo_full_name}"
+              return [200, { status: "ignored", reason: "no matching project" }.to_json]
+            end
+
+            project_key, project_config = project_result
+            repo_path = project_config["repo_path"]
+
+            result = find_work_item_by_branch(branch)
+            unless result
+              LOG.info "No card found for branch #{branch}"
+              return [200, { status: "ignored", reason: "no matching card" }.to_json]
+            end
+
+            _internal_id, card_info = result
+            card_number = card_info["number"]
+            unless card_number
+              LOG.warn "Card has no number — can't comment or move"
+              return [200, { status: "ignored", reason: "card has no number" }.to_json]
+            end
+
+            LOG.info "PR merged into main for card ##{card_number} (project: #{project_key}): #{pr_url}"
+            process_merged_pr(card_info, card_number, branch, pr, pr_url, pr_title, project_key, project_config, repo_path)
+
+            [200, { status: "processed", card: card_number, pr: pr_url, action: "merged_to_uat", project: project_key }.to_json]
+          rescue StandardError => e
+            LOG.error "Error handling merged PR: #{e.message}"
+            [500, { error: e.message }.to_json]
+          end
+
+          def handle_pr_opened(payload)
+            track_pr_in_work_items(payload)
+            [200, { status: "processed", action: "pr_tracked" }.to_json]
+          end
+
+          def handle_pr_synchronized(payload)
+            pr = payload["pull_request"]
+            branch = pr.dig("head", "ref")
+
+            result = find_work_item_by_branch(branch)
+            return [200, { status: "ignored", reason: "no matching card" }.to_json] unless result
+
+            _internal_id, card_info = result
+            card_number = card_info["number"]
+            worktree = card_info["worktree"]
+
+            return [200, { status: "ignored", reason: "no worktree" }.to_json] unless worktree && File.directory?(worktree)
+
+            results = Brainiac.emit(:pr_synchronized, card_number: card_number, card_info: card_info,
+                                                      worktree: worktree, pull_request: pr, branch: branch)
+
+            if results.any?
+              [200, { status: "processed", action: "pr_sync", card: card_number }.to_json]
+            else
+              [200, { status: "ignored", reason: "no deployment plugin" }.to_json]
+            end
+          rescue StandardError => e
+            LOG.error "[PR Sync] Error: #{e.message}"
+            [500, { error: e.message }.to_json]
+          end
+
+          def handle_pr_review_submitted(payload)
+            pr = payload["pull_request"]
+            review = payload["review"]
+            branch = pr.dig("head", "ref")
+            pr_number = pr["number"]
+            repo_name = payload.dig("repository", "full_name")
+            review_state = review["state"]
+            reviewer = review.dig("user", "login")
+
+            unless %w[changes_requested commented].include?(review_state)
+              return [200, { status: "ignored", reason: "review state: #{review_state}" }.to_json]
+            end
+
+            project_result = identify_project_by_repo(repo_name)
+            return [200, { status: "ignored", reason: "no matching project" }.to_json] unless project_result
+
+            project_key, project_config = project_result
+            repo_path = project_config["repo_path"]
+
+            result = find_work_item_by_branch(branch)
+            return [200, { status: "ignored", reason: "no matching card" }.to_json] unless result
+
+            _internal_id, card_info = result
+            card_number = card_info["number"]
+            unless card_number
+              LOG.warn "Card has no number — can't dispatch review"
+              return [200, { status: "ignored", reason: "card has no number" }.to_json]
+            end
+
+            card_key = "card-#{card_number}"
+            return [200, { status: "ignored", reason: "session already active" }.to_json] if session_active?(card_key)
+
+            LOG.info "PR review submitted by #{reviewer} on PR ##{pr_number} for card ##{card_number} (project: #{project_key})"
+            dispatch_pr_review(card_number, card_key, card_info, pr_number, review, reviewer,
+                               repo_name, project_key, project_config, repo_path)
+
+            [200, { status: "processed", card: card_number, pr: pr_number, reviewer: reviewer, project: project_key }.to_json]
+          rescue StandardError => e
+            LOG.error "Error handling PR review: #{e.message}"
+            [500, { error: e.message }.to_json]
+          end
+
+          def handle_issue_comment(payload)
+            comment = payload["comment"]
+            issue = payload["issue"]
+            comment_body = comment["body"] || ""
+            comment_id = comment["id"]
+            comment_user = comment.dig("user", "login")
+            repo_name = payload.dig("repository", "full_name")
+
+            unless issue["pull_request"]
+              LOG.info "Issue comment on non-PR issue ##{issue["number"]}, ignoring"
+              return [200, { status: "ignored", reason: "not a PR comment" }.to_json]
+            end
+
+            project_result = identify_project_by_repo(repo_name)
+            unless project_result
+              LOG.info "No project found for GitHub repo #{repo_name}"
+              return [200, { status: "ignored", reason: "no matching project" }.to_json]
+            end
+
+            project_key, project_config = project_result
+            pr_number = issue["number"]
+
+            pr_data = run_cmd("gh", "api", "/repos/#{repo_name}/pulls/#{pr_number}", "--jq", "{branch: .head.ref}",
+                              chdir: project_config["repo_path"])
+            branch = JSON.parse(pr_data)["branch"]
+
+            result = find_work_item_by_branch(branch)
+            unless result
+              LOG.info "No card found for PR ##{pr_number} (branch: #{branch})"
+              return [200, { status: "ignored", reason: "no matching card" }.to_json]
+            end
+
+            _, card_info = result
+            card_number = card_info["number"]
+            worktree = card_info["worktree"]
+
+            unless worktree && File.directory?(worktree)
+              LOG.info "No active worktree for PR ##{pr_number}, ignoring comment"
+              return [200, { status: "ignored", reason: "no active worktree" }.to_json]
+            end
+
+            card_key = "card-#{card_number}"
+            if session_active?(card_key)
+              LOG.info "Skipping PR comment on card ##{card_number} — agent session already active"
+              return [200, { status: "ignored", reason: "session already active" }.to_json]
+            end
+
+            LOG.info "PR comment from #{comment_user} on PR ##{pr_number} for card ##{card_number} (project: #{project_key})"
+            dispatch_pr_comment(card_number, card_key, pr_number, comment_id, comment_user, comment_body,
+                                repo_name, worktree, project_key, project_config)
+
+            [200, { status: "processed", card: card_number, pr: pr_number, comment_id: comment_id, project: project_key }.to_json]
+          rescue StandardError => e
+            LOG.error "Error handling PR comment: #{e.message}"
+            [500, { error: e.message }.to_json]
+          end
+
+          def handle_issue_opened(payload)
+            issue = payload["issue"]
+            issue_url = issue["html_url"]
+            issue_title = issue["title"]
+            issue_number = issue["number"]
+            repo_name = payload.dig("repository", "full_name")
+
+            LOG.info "New GitHub issue ##{issue_number} on #{repo_name}: #{issue_title} (#{issue_url})"
+            [200, { status: "logged", issue: issue_number, title: issue_title, url: issue_url }.to_json]
+          end
+
+          def handle_workflow_run(payload)
+            workflow = payload["workflow_run"]
+            workflow_name = workflow["name"]
+            conclusion = workflow["conclusion"]
+            repo_full_name = payload.dig("repository", "full_name")
+            run_url = workflow["html_url"]
+
+            if workflow_name == "Deploy to Production" && conclusion == "failure"
+              project_key = identify_project_by_repo(repo_full_name)&.first || repo_full_name
+              Notifications.send_workflow_failure(project_key, workflow_name, run_url)
+              return [200, { status: "processed", action: "prod_deploy_failure_notified", project: project_key }.to_json]
+            end
+
+            if workflow_name == "Deploy to UAT" && conclusion == "success"
+              project_key = identify_project_by_repo(repo_full_name)&.first || repo_full_name
+              Notifications.send_uat_deploy(project_key)
+              return [200, { status: "processed", action: "uat_deploy_notified", project: project_key }.to_json]
+            end
+
+            return [200, { status: "ignored", reason: "conclusion: #{conclusion}" }.to_json] unless conclusion == "success"
+            return [200, { status: "ignored", reason: "workflow: #{workflow_name}" }.to_json] unless workflow_name == "Deploy to Production"
+
+            project_result = identify_project_by_repo(repo_full_name)
+            return [200, { status: "ignored", reason: "no matching project" }.to_json] unless project_result
+
+            project_key, project_config = project_result
+            close_uat_cards_after_deploy(project_key, project_config)
+          rescue StandardError => e
+            LOG.error "Error handling workflow run: #{e.message}"
+            [500, { error: e.message }.to_json]
+          end
+
+          private
+
+          def process_merged_pr(card_info, card_number, branch, pull_request, pr_url, pr_title, project_key, project_config, repo_path)
+            mark_work_item_merged(card_number)
+            cleanup_work_item_worktrees(card_number, repo_path: repo_path,
+                                                     primary_worktree: card_info["worktree"], primary_branch: branch)
+
+            Brainiac.emit(:pr_merged,
+                          card_number: card_number, card_info: card_info,
+                          branch: branch, pull_request: pull_request,
+                          pr_url: pr_url, pr_title: pr_title,
+                          project_key: project_key, project_config: project_config, repo_path: repo_path)
+          end
+
+          def track_pr_in_work_items(payload)
+            pr = payload["pull_request"]
+            branch = pr.dig("head", "ref")
+            pr_number = pr["number"]
+            pr_url = pr["html_url"]
+
+            result = find_work_item_by_branch(branch)
+            unless result
+              LOG.info "[PR Track] No card found for branch #{branch}"
+              return
+            end
+
+            internal_id, card_info = result
+            prs = card_info["prs"] || []
+            return if prs.any? { |p| p["number"] == pr_number }
+
+            prs << { "number" => pr_number, "url" => pr_url }
+            card_info["prs"] = prs
+
+            map = load_work_item_map
+            map[internal_id] = card_info
+            save_work_item_map(map)
+            LOG.info "[PR Track] Tracked PR ##{pr_number} on card ##{card_info["number"]} (branch: #{branch})"
+          end
+
+          def dispatch_pr_comment(card_number, card_key, pr_number, comment_id, comment_user, comment_body,
+                                  repo_name, worktree, project_key, project_config)
+            Thread.new do
+              run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/issues/comments/#{comment_id}/reactions",
+                      "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: worktree)
+            rescue StandardError => e
+              LOG.warn "Could not add reaction to comment: #{e.message}"
+            end
+
+            agent_name = agent_name_for(project_config)
+            prompt = render_prompt(Prompts::PR_COMMENT,
+                                   { "CARD_NUMBER" => card_number, "CARD_ID" => card_number,
+                                     "COMMENT_CREATOR" => comment_user, "COMMENT_BODY" => comment_body,
+                                     "PR_NUMBER" => pr_number.to_s, "WORKTREE_PATH" => worktree },
+                                   brain_context: build_brain_context(agent_name: agent_name, card_number: card_number,
+                                                                      project_key: project_key, comment_body: comment_body),
+                                   agent_name: agent_name, channel: :github)
+
+            pid, log_file = run_agent(prompt, project_config: project_config, chdir: worktree,
+                                              log_name: "pr-comment-#{pr_number}",
+                                              model: detect_model(project_config, text: comment_body),
+                                              effort: detect_effort(project_config, text: comment_body),
+                                              agent_name: agent_name, source: :github,
+                                              source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: worktree })
+            register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
+          end
+
+          def dispatch_pr_review(card_number, card_key, card_info, pr_number, review, reviewer,
+                                 repo_name, project_key, project_config, repo_path)
+            review_id = review["id"]
+            Thread.new do
+              run_cmd("gh", "api", "-X", "POST", "/repos/#{repo_name}/pulls/reviews/#{review_id}/reactions",
+                      "-f", "content=eyes", "-H", "Accept: application/vnd.github+json", chdir: repo_path)
+            rescue StandardError => e
+              LOG.warn "Could not add reaction to review: #{e.message}"
+            end
+
+            agent_name = agent_name_for(project_config)
+            Brainiac.emit(:pr_review_received, card_number: card_number, reviewer: reviewer,
+                                               agent_name: agent_name, project_config: project_config, repo_path: repo_path)
+
+            review_context = build_review_context(reviewer, review, pr_number, repo_name)
+            worktree = card_info["worktree"]
+            work_dir = worktree && File.directory?(worktree) ? worktree : repo_path
+
+            prompt = render_prompt(Prompts::PR_REVIEW,
+                                   { "CARD_NUMBER" => card_number, "CARD_ID" => card_number,
+                                     "COMMENT_CREATOR" => reviewer, "REVIEW_CONTEXT" => review_context,
+                                     "PR_NUMBER" => pr_number.to_s, "WORKTREE_PATH" => work_dir },
+                                   brain_context: build_brain_context(agent_name: agent_name, card_number: card_number,
+                                                                      project_key: project_key),
+                                   agent_name: agent_name, channel: :github)
+
+            pid, log_file = run_agent(prompt, project_config: project_config, chdir: work_dir,
+                                              log_name: "review-#{card_number}", agent_name: agent_name,
+                                              source: :github,
+                                              source_context: { pr_number: pr_number, repo_name: repo_name, work_dir: work_dir })
+            register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
+          end
+
+          def build_review_context(reviewer, review, pr_number, repo_name)
+            context = "GitHub PR Review from @#{reviewer}:\n\n"
+            context += "Review body:\n#{review["body"]}\n\n" if review["body"] && !review["body"].empty?
+
+            review_comments = fetch_pr_review_comments(pr_number, repo_name)
+            if review_comments.any?
+              context += "Line-specific comments:\n"
+              review_comments.each do |comment|
+                context += "- #{comment["path"]}:#{comment["line"]} (@#{comment["user"]}): #{comment["body"]}\n"
+              end
+            end
+            context
+          end
+
+          def fetch_pr_review_comments(pr_number, repo)
+            output = run_cmd("gh", "api", "/repos/#{repo}/pulls/#{pr_number}/comments",
+                             "--jq", ".[] | {path, line, body, user: .user.login}",
+                             chdir: PROJECTS.values.first&.dig("repo_path") || Dir.pwd)
+            output.lines.map { |line| JSON.parse(line) }
+          rescue StandardError => e
+            LOG.warn "Could not fetch PR review comments: #{e.message}"
+            []
+          end
+
+          def close_uat_cards_after_deploy(project_key, project_config)
+            results = Brainiac.emit(:production_deployed, project_key: project_key, project_config: project_config)
+            closed_cards = results.flatten.compact
+
+            if closed_cards.any?
+              Notifications.send_deploy(project_key, closed_cards)
+              LOG.info "Prod deploy complete — closed #{closed_cards.size} cards"
+            else
+              LOG.info "Prod deploy processed — no cards closed (plugin may not be installed)"
+            end
+
+            [200, { status: "processed", action: "prod_deploy", closed_cards: closed_cards.map { |c| c[:number] }, project: project_key }.to_json]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/metadata.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Lightweight metadata for brainiac-github.
+# Loaded by `brainiac help` without pulling in the full plugin runtime.
+
+require_relative "version"
+
+module Brainiac
+  module Plugins
+    module Github
+      # Returns true if GitHub webhook secret is configured.
+      def self.configured?
+        config_file = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "github.json")
+        return false unless File.exist?(config_file)
+
+        config = JSON.parse(File.read(config_file))
+        !config["webhook_secret"].to_s.empty?
+      rescue StandardError
+        false
+      end
+
+      # Help text shown in `brainiac help` when the plugin is installed.
+      def self.help_text
+        "    brainiac github <command>     Manage GitHub webhooks (setup, config, status)"
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/notifications.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Github
+      module Notifications
+        class << self
+          def send_deploy(project_key, closed_cards)
+            card_lines = closed_cards.map { |c| "• [##{c[:number]} — #{c[:title]}](#{c[:url]})" }.join("\n")
+            message = "🚀 **#{project_key.capitalize}** deployed to production\nClosed UAT cards:\n#{card_lines}"
+            send_notification(:deploy, message, metadata_project: project_key)
+          end
+
+          def send_uat_deploy(project_key)
+            message = "✅ **#{project_key.capitalize}** deployed to UAT successfully"
+            send_notification(:deploy, message, metadata_project: project_key)
+          end
+
+          def send_workflow_failure(project_key, workflow_name, run_url)
+            message = "❌ **#{project_key.capitalize}** — #{workflow_name} failed\n[View run](#{run_url})"
+            send_notification(:ci_failure, message, metadata_project: project_key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/prompts.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Github
+      module Prompts
+        CHANNEL = <<~PROMPT
+          ## GitHub Channel Rules
+
+          ### Formatting
+          Use GitHub-Flavored Markdown for all comments:
+          - `## Heading` for sections
+          - `**bold**` for emphasis
+          - ``` ```language ``` for code blocks
+          - `- item` for lists
+
+          ### Scope
+          You are responding to activity on a GitHub PR. Focus on the code changes and review feedback.
+          When posting comments, post on the PR unless specifically asked to update the card.
+
+        PROMPT
+
+        PR_COMMENT = <<~'PROMPT'
+          There's a new comment from @{{COMMENT_CREATOR}} on your PR #{{PR_NUMBER}} for card #{{CARD_NUMBER}}.
+
+          Comment:
+          {{COMMENT_BODY}}
+
+          Please:
+          1. Read the comment and understand what's being requested
+          2. Make any necessary changes
+          3. Commit and push your updates
+          4. Reply on the PR summarizing what you changed
+
+          You are in the worktree at {{WORKTREE_PATH}}.
+        PROMPT
+
+        PR_REVIEW = <<~'PROMPT'
+          A code review has been submitted on your PR #{{PR_NUMBER}} for card #{{CARD_NUMBER}}.
+
+          {{REVIEW_CONTEXT}}
+
+          Please:
+          1. Read the review comments carefully
+          2. Address each piece of feedback
+          3. Make the necessary code changes
+          4. Commit and push your updates
+          5. Post a comment on the PR summarizing the changes
+
+          You are in the worktree at {{WORKTREE_PATH}}.
+        PROMPT
+
+        UAT = <<~'PROMPT'
+          PR #{{PR_NUMBER}} has been merged into main for card #{{CARD_NUMBER}}: "{{CARD_TITLE}}"
+
+          The card has been moved to the UAT column. The changes are now deployed to the UAT environment.
+
+          Your job: post a comment on card #{{CARD_NUMBER}} with clear, specific steps for how to manually test this feature in UAT. Include:
+          1. What URL(s) or screen(s) to visit
+          2. Step-by-step actions to verify the feature works
+          3. What the expected behavior should be
+          4. Any edge cases worth checking
+          5. Links to relevant pages if applicable (use the UAT/staging URL, not localhost)
+
+          Base your testing steps on the card title, the PR diff, and any card context provided. Be specific — "verify it works" is not a testing step.
+
+          Do NOT make any code changes. This is a read-only review task.
+        PROMPT
+
+        PRE_POST_CHECK = <<~PROMPT
+          ## Pre-Post Comment Check (MANDATORY — do this BEFORE posting your comment)
+
+          Your session may have been running for a while. Before you post your final comment,
+          re-check the PR for new comments that arrived while you were working:
+
+          ```bash
+          gh pr view {{PR_NUMBER}} --comments --json comments
+          ```
+
+          If there are **new comments** that weren't in your original context:
+
+          1. **Read them carefully** — a reviewer may have added feedback or changed direction
+          2. **Adjust your work or response** to account for the new information
+          3. **Do NOT ignore new comments** — avoid posting a response that's already outdated
+
+          If no new comments appeared, proceed normally.
+
+        PROMPT
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/github/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Github
+      VERSION = "0.0.1"
+    end
+  end
+end

data/lib/brainiac/plugins/github.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative "github/version"
+require_relative "github/metadata"
+require_relative "github/cli"
+require_relative "github/config"
+require_relative "github/prompts"
+require_relative "github/notifications"
+require_relative "github/handler"
+
+module Brainiac
+  module Plugins
+    module Github
+      class << self
+        # Called by Brainiac plugin system during server startup.
+        #
+        # @param app [Sinatra::Application] The running Brainiac server
+        def register(app)
+          Config.load!
+          Brainiac.register_channel_prompt(:github, Prompts::CHANNEL, pre_post_check: Prompts::PRE_POST_CHECK)
+          register_crash_handler!
+          setup_routes(app)
+          LOG.info "[GitHub] Plugin registered (webhook: /github)"
+        end
+
+        # Called after `brainiac install github` — creates config from template.
+        def post_install(brainiac_dir)
+          config_file = File.join(brainiac_dir, "github.json")
+          return if File.exist?(config_file)
+
+          template = File.expand_path("../../../templates/github.json.example", __dir__)
+          if File.exist?(template)
+            FileUtils.cp(template, config_file)
+          else
+            default_config = { "webhook_secret" => "", "repos" => {} }
+            File.write(config_file, JSON.pretty_generate(default_config))
+          end
+        end
+
+        private
+
+        def register_crash_handler!
+          Brainiac.on(:agent_crashed) do |ctx|
+            next unless ctx[:source] == :github
+
+            source_context = ctx[:source_context] || {}
+            pr_number = source_context[:pr_number]
+            repo_name = source_context[:repo_name]
+            next unless pr_number && repo_name
+
+            work_dir = source_context[:work_dir] || Dir.pwd
+            agent_display = ctx[:agent_name] || "Agent"
+            snippet = ctx[:snippet]
+            snippet_block = snippet ? "\n```\n#{snippet[-1500..]}\n```" : ""
+            comment_body = "💥 **#{agent_display} crashed** (exit code #{ctx[:exit_status]})\n\nLog: `#{ctx[:log_file]}`#{snippet_block}"
+
+            begin
+              run_cmd("gh", "pr", "comment", pr_number.to_s, "--repo", repo_name, "--body", comment_body, chdir: work_dir)
+              LOG.info "[GitHub] Posted crash comment on PR ##{pr_number}"
+            rescue StandardError => e
+              LOG.error "[GitHub] Failed to post crash comment: #{e.message}"
+            end
+
+            :github
+          end
+        end
+
+        def setup_routes(app)
+          app.post "/github" do
+            content_type :json
+            request.body.rewind
+            payload_body = request.body.read
+
+            Brainiac::Plugins::Github.verify_signature!(request, payload_body)
+
+            payload = JSON.parse(payload_body)
+            event = request.env["HTTP_X_GITHUB_EVENT"]
+
+            reload_projects!
+            reload_agent_registry!
+            Brainiac::Plugins::Github::Config.reload!
+
+            action = payload["action"]
+
+            case event
+            when "pull_request"
+              status_code, body = case action
+                                  when "closed"
+                                    if payload.dig("pull_request", "merged")
+                                      Handler.handle_pr_merged(payload)
+                                    else
+                                      [200, { status: "ignored", reason: "PR closed without merge" }.to_json]
+                                    end
+                                  when "opened"
+                                    Handler.handle_pr_opened(payload)
+                                  when "synchronize"
+                                    Handler.handle_pr_synchronized(payload)
+                                  else
+                                    [200, { status: "ignored", reason: "pull_request action: #{action}" }.to_json]
+                                  end
+              halt status_code, body
+            when "pull_request_review"
+              if action == "submitted"
+                status_code, body = Handler.handle_pr_review_submitted(payload)
+                halt status_code, body
+              else
+                halt 200, { status: "ignored", reason: "pull_request_review action: #{action}" }.to_json
+              end
+            when "issue_comment"
+              if action == "created"
+                status_code, body = Handler.handle_issue_comment(payload)
+                halt status_code, body
+              else
+                halt 200, { status: "ignored", reason: "issue_comment action: #{action}" }.to_json
+              end
+            when "issues"
+              if action == "opened"
+                status_code, body = Handler.handle_issue_opened(payload)
+                halt status_code, body
+              else
+                halt 200, { status: "ignored", reason: "issues action: #{action}" }.to_json
+              end
+            when "workflow_run"
+              if action == "completed"
+                status_code, body = Handler.handle_workflow_run(payload)
+                halt status_code, body
+              else
+                halt 200, { status: "ignored", reason: "workflow_run action: #{action}" }.to_json
+              end
+            when "ping"
+              halt 200, { status: "pong" }.to_json
+            else
+              halt 200, { status: "ignored", event: event }.to_json
+            end
+          rescue JSON::ParserError => e
+            LOG.error "Invalid JSON: #{e.message}"
+            halt 400, { error: "Invalid JSON" }.to_json
+          rescue StandardError => e
+            LOG.error "Unhandled error: #{e.message}\n#{e.backtrace.first(5).join("\n")}"
+            halt 500, { error: e.message }.to_json
+          end
+        end
+      end
+
+      # Verify the X-Hub-Signature-256 header (HMAC-SHA256 of the raw body).
+      def self.verify_signature!(request, payload_body)
+        signature = request.env["HTTP_X_HUB_SIGNATURE_256"]
+        halt 403, { error: "Missing GitHub signature" }.to_json unless signature
+        secret = Config.webhook_secret
+        halt 500, { error: "GitHub webhook secret not configured" }.to_json unless secret
+        computed = "sha256=#{OpenSSL::HMAC.hexdigest("sha256", secret, payload_body)}"
+        halt 403, { error: "Invalid GitHub signature" }.to_json unless Rack::Utils.secure_compare(signature, computed)
+      end
+    end
+  end
+end

data/lib/brainiac_github.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "brainiac/plugins/github"

data/templates/github.json.example

@@ -0,0 +1,4 @@
+{
+  "webhook_secret": "your-github-webhook-secret",
+  "repos": {}
+}

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: brainiac-github
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Andy Davis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: brainiac
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+description: Full GitHub integration for Brainiac — PR reviews, PR comments, PR merges,
+  CI workflow notifications, and issue tracking. Uses Brainiac's hook system for lifecycle
+  integration (PR merge → work item close, deploy → card close).
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/brainiac/plugins/github.rb
+- lib/brainiac/plugins/github/cli.rb
+- lib/brainiac/plugins/github/config.rb
+- lib/brainiac/plugins/github/handler.rb
+- lib/brainiac/plugins/github/metadata.rb
+- lib/brainiac/plugins/github/notifications.rb
+- lib/brainiac/plugins/github/prompts.rb
+- lib/brainiac/plugins/github/version.rb
+- lib/brainiac_github.rb
+- templates/github.json.example
+homepage: https://github.com/stowzilla/brainiac-github
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: GitHub webhook plugin for Brainiac
+test_files: []