brainiac-basecamp 0.0.1

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Brainiac
+  module Plugins
+    module Basecamp
+      # Prompt templates for Basecamp-aware agent sessions.
+      module Prompts
+        # Injected into agent prompts when working on an epic task.
+        # Placeholders use %{name} format (rendered by the orchestrator).
+        EPIC_CONTEXT = <<~'PROMPT'
+          ## Basecamp Epic Context
+
+          You are working on a task that is part of a larger epic managed in Basecamp.
+          The orchestrator will automatically advance to the next task when you complete this one.
+
+          **Important:**
+          - Focus only on this specific card's requirements
+          - When done, commit and push as normal — the orchestrator handles sequencing
+          - If you discover the task needs changes to the plan (new dependencies, scope change),
+            mention it in your Fizzy comment so the human can adjust the Basecamp epic
+
+          Epic: %{epic_title}
+          Progress: %{epic_progress}
+          Your task: %{task_title} (Fizzy #%{fizzy_card})
+          %{dependencies}
+        PROMPT
+
+        # Template for the Basecamp channel (if agents post directly to Basecamp).
+        # Currently unused — agents post to Fizzy/Discord, orchestrator posts to Basecamp.
+        CHANNEL = <<~'PROMPT'
+          ## Basecamp Communication
+
+          When referencing Basecamp items:
+          - Use the basecamp CLI for queries: `basecamp todos list --in <project> --json`
+          - Format card references as: Fizzy #NNNN
+          - Keep Basecamp comments brief — detailed discussion happens in Fizzy/Discord
+        PROMPT
+      end
+    end
+  end
+end

data/lib/brainiac/plugins/basecamp/review_gate.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Brainiac
+  module Plugins
+    module Basecamp
+      # Review gate system for epic tasks.
+      #
+      # After an implementation agent completes a task PR, gate agents are
+      # dispatched IN PARALLEL to review it. All gates must approve before
+      # the PR auto-merges into the epic branch.
+      #
+      # Gate agents are triggered by:
+      #   - :agent_completed on the task (initial review)
+      #   - :pr_synchronized (re-review after fixes)
+      #
+      # Gate agents do NOT get assigned the Fizzy card — they review the PR
+      # directly on GitHub using their bot app identities.
+      #
+      # Configuration in ~/.brainiac/basecamp.json:
+      #   "review_gates": ["GLaDOS", "Threepio"]
+      #
+      # The agent's role is looked up from ~/.brainiac/agents.json and used
+      # to determine review focus (test-engineer -> testing, code-reviewer -> quality, etc.)
+      #
+      # All gates run in parallel by default.
+      #
+      # Gates can also be triggered by a Fizzy card tag "review-gates" for non-epic PRs.
+      module ReviewGate
+        BRAINIAC_DIR = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
+
+        class << self
+          # Get the configured review gates as normalized hashes.
+          # Supports both old format [{agent:, role:}] and new format ["AgentName"]
+          #
+          # @return [Array<Hash>] Gate configs [{agent:, role:}]
+          def gates
+            raw = Config.current["review_gates"] || []
+            raw.map do |entry|
+              if entry.is_a?(Hash)
+                # Old format: {"agent": "GLaDOS", "role": "testing"}
+                entry
+              else
+                # New format: just agent name string — look up role from registry
+                agent_name = entry.to_s
+                role = lookup_agent_role(agent_name)
+                { "agent" => agent_name, "role" => role }
+              end
+            end
+          end
+
+          # Check if review gates are configured.
+          #
+          # @return [Boolean]
+          def enabled?
+            gates.any?
+          end
+
+          # Check if all gates have approved for a task.
+          #
+          # @param task [Hash] Task state from epic
+          # @return [Boolean]
+          def all_gates_passed?(task)
+            return true unless enabled?
+
+            approvals = task["gate_approvals"] || []
+            required_agents = gates.map { |g| g["agent"].downcase }
+            approved_agents = approvals.map { |a| a["agent"].downcase }
+
+            required_agents.all? { |agent| approved_agents.include?(agent) }
+          end
+
+          # Sync gate approvals from GitHub PR reviews (self-healing).
+          # Queries actual PR review state and updates task accordingly.
+          #
+          # @param task [Hash] Task state (mutated in place)
+          # @param repo_path [String] Path to repo for gh CLI
+          # @return [Hash] Summary of changes made
+          def sync_from_github(task, repo_path:)
+            return { synced: false, reason: "no PR" } unless task["pr_number"]
+
+            pr_number = task["pr_number"]
+            stdout, _, status = Open3.capture3(
+              "gh", "pr", "view", pr_number.to_s,
+              "--json", "reviews",
+              "--jq", ".reviews[] | [.author.login, .state] | @tsv",
+              chdir: repo_path
+            )
+            return { synced: false, reason: "gh failed" } unless status.success?
+
+            # Parse reviews into {author => state}
+            reviews = {}
+            stdout.each_line do |line|
+              author, state = line.strip.split("\t")
+              reviews[author.downcase] = state.downcase if author && state
+            end
+
+            changes = { approvals_added: [], changes_cleared: [] }
+
+            # Check each gate agent's review state
+            gates.each do |gate|
+              agent = gate["agent"]
+              role = gate["role"] || "review"
+
+              # Match agent to GitHub login (agent-brainiac pattern)
+              github_login = "#{agent.downcase}-brainiac"
+              review_state = reviews[github_login]
+
+              next unless review_state
+
+              if review_state == "approved"
+                # Record approval if not already recorded
+                unless (task["gate_approvals"] || []).any? { |a| a["agent"].downcase == agent.downcase }
+                  record_approval(task, agent: agent, role: role)
+                  changes[:approvals_added] << agent
+                end
+                # Clear from changes_requested if present
+                if task["changes_requested_by"]&.include?(agent)
+                  task["changes_requested_by"].delete(agent)
+                  changes[:changes_cleared] << agent
+                end
+              elsif review_state == "changes_requested"
+                # Remove any stale approval
+                task["gate_approvals"]&.reject! { |a| a["agent"].downcase == agent.downcase }
+                # Track changes_requested
+                task["changes_requested_by"] ||= []
+                task["changes_requested_by"] << agent unless task["changes_requested_by"].include?(agent)
+              end
+            end
+
+            { synced: true, changes: changes }
+          rescue StandardError => e
+            { synced: false, reason: e.message }
+          end
+
+          # Record a gate approval.
+          #
+          # @param task [Hash] Task state (mutated in place)
+          # @param agent [String] Agent that approved
+          # @param role [String] Gate role
+          def record_approval(task, agent:, role:)
+            task["gate_approvals"] ||= []
+            # Don't duplicate
+            return if task["gate_approvals"].any? { |a| a["agent"].downcase == agent.downcase }
+
+            task["gate_approvals"] << {
+              "agent" => agent,
+              "role" => role,
+              "approved_at" => Time.now.iso8601
+            }
+          end
+
+          # Reset gate approvals (when changes are requested and code is updated).
+          #
+          # @param task [Hash] Task state (mutated in place)
+          def reset_approvals(task)
+            task["gate_approvals"] = []
+          end
+
+          # Dispatch all gate agents to review a PR in parallel.
+          # Uses brainiac-github's app client to post review requests as each bot.
+          #
+          # @param epic [Hash] Epic state
+          # @param task [Hash] Task state
+          # @param pr_number [Integer, String] PR number
+          # @param repo_name [String] e.g. "stowzilla/brainiac-basecamp"
+          # @param repo_path [String] Local repo path
+          # @return [Array<String>] Agent names dispatched
+          def dispatch_gates(epic:, task:, pr_number:, repo_name:, repo_path:)
+            dispatched = []
+
+            gates.each do |gate|
+              agent_name = gate["agent"]
+              role = gate["role"] || "review"
+
+              LOG.info "[Basecamp:ReviewGate] Dispatching #{agent_name} (#{role}) to review PR ##{pr_number}" if defined?(LOG)
+
+              # Dispatch the gate agent via brainiac-github's PR review mechanism.
+              # The agent gets the PR diff and reviews it using their bot identity.
+              Thread.new do
+                dispatch_agent_for_review(
+                  agent_name: agent_name,
+                  role: role,
+                  pr_number: pr_number,
+                  repo_name: repo_name,
+                  repo_path: repo_path,
+                  card_number: task["fizzy_card"],
+                  epic: epic
+                )
+              rescue StandardError => e
+                LOG.error "[Basecamp:ReviewGate] Failed to dispatch #{agent_name}: #{e.message}" if defined?(LOG)
+              end
+
+              dispatched << agent_name
+            end
+
+            # Update task state
+            task["status"] = "in_review"
+            task["gates_dispatched_at"] = Time.now.iso8601
+            task["gate_approvals"] ||= []
+
+            dispatched
+          end
+
+          # Build the summary comment for Fizzy after all gates pass and merge completes.
+          #
+          # @param task [Hash] Task state
+          # @param pr_url [String] PR URL
+          # @return [String] HTML comment for Fizzy
+          def build_gate_summary_comment(task, pr_url:)
+            approvals = task["gate_approvals"] || []
+            lines = []
+            lines << "<p>✅ <strong>All review gates passed</strong> — merged into epic branch.</p>"
+            lines << "<p><a href=\"#{pr_url}\">PR Link</a></p>"
+            lines << "<ul>"
+            approvals.each do |approval|
+              lines << "<li>#{approval['agent']} (#{approval['role']}): approved</li>"
+            end
+            lines << "</ul>"
+            lines.join("\n")
+          end
+
+          # Check if a Fizzy card has the review-gates tag (for non-epic PRs).
+          #
+          # @param tags [Array] Fizzy card tags
+          # @return [Boolean]
+          def tag_triggered?(tags)
+            tag_names = tags.map { |t| t.is_a?(Hash) ? t["name"] : t.to_s }.map(&:downcase)
+            tag_names.include?("review-gates") || tag_names.include?("qa")
+          end
+
+          private
+
+          # Dispatch a single gate agent to review a PR.
+          # This creates a review prompt and runs the agent in the repo directory.
+          def dispatch_agent_for_review(agent_name:, role:, pr_number:, repo_name:, repo_path:, card_number:, epic:)
+            # Build a review-specific prompt for the gate agent
+            prompt = build_gate_review_prompt(
+              agent_name: agent_name,
+              role: role,
+              pr_number: pr_number,
+              repo_name: repo_name,
+              card_number: card_number,
+              epic_title: epic["title"]
+            )
+
+            # Resolve the agent's GitHub token for their bot identity
+            agent_env = resolve_agent_github_env(agent_name, repo_name)
+
+            # Run the agent via the top-level helper method
+            # The run_agent method is defined in lib/brainiac/helpers.rb and loaded into main
+            pid = nil
+            log_file = nil
+            card_key = "gate-#{agent_name.downcase}-#{card_number}"
+
+            begin
+              pid, log_file = method(:run_agent).call(
+                prompt,
+                project_config: resolve_project_config(repo_path),
+                chdir: repo_path,
+                log_name: "gate-#{role}-#{card_number}",
+                agent_name: agent_name,
+                source: :github,
+                card_number: card_number,
+                env: agent_env
+              )
+            rescue NameError
+              # run_agent not available in this context — try calling via Object
+              if Object.respond_to?(:run_agent, true)
+                pid, log_file = Object.send(:run_agent,
+                            prompt,
+                            project_config: resolve_project_config(repo_path),
+                            chdir: repo_path,
+                            log_name: "gate-#{role}-#{card_number}",
+                            agent_name: agent_name,
+                            source: :github,
+                            card_number: card_number,
+                            env: agent_env)
+              else
+                LOG.warn "[Basecamp:ReviewGate] run_agent not available — gate dispatch skipped" if defined?(LOG)
+              end
+            end
+
+            # Register session for waybar visibility
+            if pid && defined?(register_session)
+              register_session(card_key, pid, log_file: log_file, agent_name: agent_name)
+            elsif pid && Object.respond_to?(:register_session, true)
+              Object.send(:register_session, card_key, pid, log_file: log_file, agent_name: agent_name)
+            end
+          end
+
+          # Build the prompt for a gate review agent.
+          def build_gate_review_prompt(agent_name:, role:, pr_number:, repo_name:, card_number:, epic_title:)
+            <<~PROMPT
+              You are reviewing PR ##{pr_number} on #{repo_name} as part of epic: "#{epic_title}".
+              Your role: **#{role}**
+
+              This is a review gate — the epic cannot proceed until you approve.
+
+              Review the PR changes with `gh pr diff #{pr_number}` and `gh pr view #{pr_number}`.
+
+              Based on your role (#{role}):
+              #{role_instructions(role)}
+
+              After your review:
+              - If the code meets your standards: `gh pr review #{pr_number} --approve --body "your summary"`
+              - If changes are needed: `gh pr review #{pr_number} --request-changes --body "what needs fixing"`
+
+              Be thorough but pragmatic. This is Fizzy card ##{card_number}.
+
+              IMPORTANT RESTRICTIONS:
+              - Do NOT open new PRs or modify code — you are a reviewer only
+              - Do NOT comment on the Fizzy card — your review goes on GitHub only
+              - Do NOT use the fizzy CLI at all
+            PROMPT
+          end
+
+          # Role-specific review instructions.
+          # Maps agent roles from the registry to review focus areas.
+          def role_instructions(role)
+            case role.to_s.downcase.gsub(/[-_]/, "")
+            # From registry role names
+            when "testengineer", "testing", "tests", "qa"
+              "- Verify tests exist for new functionality\n- Check test coverage\n- Run the test suite if possible\n- Flag missing edge cases"
+            when "codereviewer", "codequality", "quality"
+              "- Check code style and conventions\n- Look for code smells, duplication, complexity\n- Verify naming and structure\n- Ensure documentation for public interfaces"
+            when "securityengineer", "security"
+              "- Check for security vulnerabilities\n- Verify input validation\n- Check for secrets/credentials in code\n- Review auth/authz changes"
+            when "architect", "architecture"
+              "- Verify design patterns are followed\n- Check for proper separation of concerns\n- Review API design\n- Flag any architectural concerns"
+            when "androidengineer", "android"
+              "- Check Android-specific patterns and conventions\n- Verify lifecycle handling\n- Review resource usage and memory management"
+            when "frontenduxengineer", "frontend", "ux"
+              "- Check UI/UX patterns and accessibility\n- Verify responsive design\n- Review user interaction flows"
+            else
+              "- Review the changes thoroughly\n- Check for correctness and best practices"
+            end
+          end
+
+          # Look up an agent's role from the registry.
+          #
+          # @param agent_name [String] Agent name
+          # @return [String] Role name or "reviewer" as default
+          def lookup_agent_role(agent_name)
+            agents_file = File.join(BRAINIAC_DIR, "agents.json")
+            return "reviewer" unless File.exist?(agents_file)
+
+            agents = JSON.parse(File.read(agents_file))
+            agent = agents[agent_name.downcase]
+            agent&.dig("role") || "reviewer"
+          rescue StandardError
+            "reviewer"
+          end
+
+          # Resolve a project config from repo path.
+          def resolve_project_config(repo_path)
+            projects_file = File.join(BRAINIAC_DIR, "projects.json")
+            return {} unless File.exist?(projects_file)
+
+            projects = JSON.parse(File.read(projects_file))
+            projects.find { |_key, config| config["repo_path"] == repo_path }&.last || {}
+          rescue StandardError
+            {}
+          end
+
+          # Resolve GitHub env for an agent (GH_TOKEN from their app identity).
+          def resolve_agent_github_env(agent_name, repo_name)
+            # Try to use brainiac-github's AppClient if available
+            if defined?(Brainiac::Plugins::Github::AppClient)
+              repo_owner = repo_name.split("/").first
+              token = Brainiac::Plugins::Github::AppClient.installation_token_for(agent_name, repo_owner: repo_owner)
+              return { "GH_TOKEN" => token } if token
+            end
+            {}
+          rescue StandardError
+            {}
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/brainiac/plugins/basecamp/webhook.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Brainiac
+  module Plugins
+    module Basecamp
+      # Handles inbound Basecamp webhooks.
+      #
+      # Webhook types we care about:
+      #   - todo_assignment_changed: A todo was assigned/unassigned
+      #   - todo_completed: A todo was marked complete
+      #   - todolist_created: A new todolist appeared (potential epic)
+      #
+      # The trigger for epic orchestration:
+      #   When a todo inside a todolist (with "Epic:" prefix) is assigned to a bot account,
+      #   OR when any todo in an epic's todolist is assigned to the bot.
+      module Webhook
+        class << self
+          # Process a webhook payload from Basecamp.
+          #
+          # @param payload [Hash] Parsed JSON webhook payload
+          # @return [Array(Integer, String)] HTTP status code and response body
+          def handle(payload)
+            kind = payload["kind"]
+            recording = payload["recording"] || {}
+            details = payload["details"] || {}
+
+            LOG.info "[Basecamp:Webhook] Received event: #{kind}" if defined?(LOG)
+
+            case kind
+            when "todo_assignment_changed"
+              handle_todo_assignment(payload, recording, details)
+            when "todo_completed"
+              handle_todo_completed(payload, recording)
+            when "todolist_created"
+              handle_todolist_created(payload, recording)
+            when "comment_created"
+              handle_comment(payload, recording)
+            else
+              LOG.debug "[Basecamp:Webhook] Ignoring event kind: #{kind}" if defined?(LOG) && LOG.debug?
+              [200, { status: "ignored", kind: kind }.to_json]
+            end
+          end
+
+          private
+
+          # Handle todo assignment changes.
+          #
+          # Strategy:
+          # - When a todo is assigned to a bot account → start epic orchestration
+          # - When a todo is unassigned from a bot account → cancel/reset the epic
+          def handle_todo_assignment(payload, recording, details)
+            added_person_ids = details["added_person_ids"] || []
+            removed_person_ids = details["removed_person_ids"] || []
+            title = recording["title"] || ""
+            todo_id = recording["id"]
+            project_id = recording.dig("bucket", "id")
+            parent = recording["parent"] || {}
+            parent_type = parent["type"]
+            parent_title = parent["title"] || ""
+            parent_id = parent["id"]
+
+            # Handle UNASSIGNMENT — if bot is removed, cancel the epic
+            removed_person_ids.each do |person_id|
+              bot_account = Config.bot_account_for_person(person_id)
+              next unless bot_account
+
+              todolist_id = parent_type == "Todolist" ? parent_id : nil
+              next unless todolist_id
+
+              epic = Orchestrator.find_epic_by_todolist(todolist_id)
+              if epic && epic["status"] == "active"
+                epic["status"] = "cancelled"
+                epic["cancelled_at"] = Time.now.iso8601
+                epic["updated_at"] = Time.now.iso8601
+
+                # Save the cancellation
+                epics_file = File.join(ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac")), "basecamp_epics.json")
+                all = File.exist?(epics_file) ? (JSON.parse(File.read(epics_file))["epics"] || []) : []
+                idx = all.index { |e| e["id"] == epic["id"] }
+                all[idx] = epic if idx
+                File.write(epics_file, JSON.pretty_generate({ "epics" => all, "updated_at" => Time.now.iso8601 }))
+
+                LOG.info "[Basecamp:Webhook] Bot unassigned — cancelled epic '#{epic['title']}'" if defined?(LOG)
+                return [200, { status: "epic_cancelled", epic_id: epic["id"] }.to_json]
+              end
+            end
+
+            # Handle ASSIGNMENT — if bot is added, start the epic
+            added_person_ids.each do |person_id|
+              bot_account = Config.bot_account_for_person(person_id)
+              next unless bot_account
+
+              agent = bot_account["default_agent"]
+              LOG.info "[Basecamp:Webhook] Todo '#{title}' assigned to bot (agent: #{agent})" if defined?(LOG)
+
+              # Check if the parent todolist is an epic
+              epic_title = nil
+              todolist_id = nil
+
+              if parent_type == "Todolist"
+                todolist_id = parent_id
+                epic_title = parent_title
+              end
+
+              # If the todo itself has the epic prefix, it might be a standalone trigger
+              # But for Option C, we expect the TODOLIST to have the prefix
+              if todolist_id && epic_title&.start_with?(Config.epic_prefix)
+                Thread.new do
+                  Orchestrator.start_epic_from_todo(
+                    todo_id: todo_id,
+                    todolist_id: todolist_id,
+                    project_id: project_id,
+                    agent: agent,
+                    title: epic_title
+                  )
+                rescue StandardError => e
+                  LOG.error "[Basecamp:Webhook] Epic start failed: #{e.message}\n#{e.backtrace.first(5).join("\n")}" if defined?(LOG)
+                end
+
+                return [200, { status: "epic_started", todolist_id: todolist_id, agent: agent }.to_json]
+              end
+
+              # Also support: todo title itself starts with Epic: (single-todo trigger)
+              if title.start_with?(Config.epic_prefix)
+                LOG.info "[Basecamp:Webhook] Standalone epic todo detected — not a todolist. Ignoring." if defined?(LOG)
+                return [200, { status: "ignored", reason: "standalone_epic_todo_not_supported" }.to_json]
+              end
+
+              LOG.info "[Basecamp:Webhook] Todo assigned to bot but parent '#{parent_title}' is not an epic" if defined?(LOG)
+              return [200, { status: "ignored", reason: "parent_not_epic" }.to_json]
+            end
+
+            [200, { status: "ignored", reason: "no_bot_account_matched" }.to_json]
+          end
+
+          # Handle todo completed events.
+          # If the todo is part of an active epic but was completed externally (not by the orchestrator),
+          # we should still advance the epic state.
+          def handle_todo_completed(_payload, recording)
+            todo_id = recording["id"]
+            title = recording["title"] || ""
+
+            # Check if this todo is part of an active epic
+            active = Orchestrator.active_epics
+            active.each do |epic|
+              task = epic["tasks"].find { |t| t["todo_id"].to_s == todo_id.to_s }
+              next unless task
+              next if task["status"] == "complete" # Already handled
+
+              # Extract the fizzy card from the task
+              fizzy_card = task["fizzy_card"]
+              if fizzy_card
+                LOG.info "[Basecamp:Webhook] Todo '#{title}' completed externally, advancing epic" if defined?(LOG)
+                Thread.new { Orchestrator.on_card_completed(fizzy_card) }
+              end
+
+              return [200, { status: "epic_advanced", epic_id: epic["id"] }.to_json]
+            end
+
+            [200, { status: "noted" }.to_json]
+          end
+
+          # Handle new todolist creation.
+          # If it has the epic prefix, we could optionally auto-detect it.
+          # For now, just log it — orchestration starts on assignment.
+          def handle_todolist_created(_payload, recording)
+            title = recording["title"] || ""
+
+            if title.start_with?(Config.epic_prefix)
+              LOG.info "[Basecamp:Webhook] New epic todolist detected: '#{title}' — waiting for assignment to start" if defined?(LOG)
+            end
+
+            [200, { status: "noted" }.to_json]
+          end
+
+          # Handle comments on todos that are part of an epic.
+          # Could be used for @bot commands within Basecamp comments.
+          def handle_comment(_payload, recording)
+            # Future: detect @bot commands in comments
+            # e.g., "@Galen pause", "@Galen skip", "@Galen reassign to Sherlock"
+            [200, { status: "noted" }.to_json]
+          end
+        end
+      end
+    end
+  end
+end