superkick 0.1.0

data/lib/superkick/templates/team_log/team_digest.liquid

@@ -0,0 +1,45 @@
+SUPERKICK: Team update — {{ entry_count }} new entries from teammates.
+{% if has_blockers %}
+⚠ BLOCKERS DETECTED — review and take action.
+{% endif %}
+{% if grouped.update -%}
+
+## Updates
+{% for e in grouped.update -%}
+[{{ e.agent_id }}{% if e.role %} ({{ e.role }}){% endif %}] [{{ e.kind }}] {{ e.message }}
+{% endfor -%}
+{% endif -%}
+{% if grouped.message -%}
+
+## Messages
+{% for e in grouped.message -%}
+[{{ e.agent_id }}{% if e.role %} ({{ e.role }}){% endif %} → {{ e.target_agent_id }}] {{ e.message }}
+{% endfor -%}
+{% endif -%}
+{% if grouped.lifecycle -%}
+
+## Lifecycle
+{% for e in grouped.lifecycle -%}
+* {{ e.agent_id }} {{ e.kind }}{% if e.message %}: {{ e.message }}{% endif %}
+{% endfor -%}
+{% endif -%}
+{% if grouped.artifact -%}
+
+## Artifacts
+{% for e in grouped.artifact -%}
+[{{ e.agent_id }}] published "{{ e.artifact_name }}"
+{% endfor -%}
+{% endif -%}
+{% if agent_role == "lead" %}
+
+As team lead, review this digest and take action:
+- superkick_team_status for full team state
+- superkick_read_artifact to review worker plans
+- superkick_post_update (with target_agent_id) for urgent coordination
+- superkick_signal_goal when all work is complete
+{% else %}
+
+Review this digest and adjust your work accordingly.
+- superkick_post_update to share your progress
+- superkick_team_status for full team state
+{% endif -%}

data/lib/superkick/templates/team_log/teammate_message.liquid

@@ -0,0 +1,7 @@
+SUPERKICK [{{ "now" | time }}]: A teammate has sent you a message.
+
+From: {{ sender_agent_id }} ({{ sender_role }})
+Message: {{ message }}
+
+This message is also recorded in the team log. The sender believes this
+needs your attention. Acknowledge and adjust your work accordingly.

data/lib/superkick/templates/team_log/worker_kickoff.liquid

@@ -0,0 +1,37 @@
+You are a worker agent on a team coordinated by a planning agent.
+
+## Your task
+{{ task }}
+
+## Repository: {{ repository_name }}
+
+## Team context
+Team ID: {{ team_id }}
+Team lead: {{ lead_agent_id }}
+{% if depends_on.size > 0 -%}
+
+## Dependencies
+You depend on work from these teammates:
+{% for dep in depends_on -%}
+- {{ dep }}
+{% endfor -%}
+Check superkick_team_status before starting work that depends on their output.
+{% endif -%}
+
+{% if monitor_names.size > 0 -%}
+## Active monitors
+The following monitors have been configured for you:
+{% for name in monitor_names -%}
+- {{ name }}
+{% endfor -%}
+{% endif -%}
+
+## Communication
+- Publish your implementation plan as an artifact using superkick_publish_artifact
+  (name: "implementation-plan") as your first action.
+- Use superkick_post_update regularly to share your progress.
+- Use superkick_team_status to check on teammates you depend on.
+- Use superkick_read_artifact to read teammates' implementation plans.
+- Use superkick_post_update with target_agent_id only for urgent coordination needs.
+- Signal superkick_signal_goal with status "completed" when your task is done,
+  or "failed" if you cannot complete it.

data/lib/superkick/templates/workflow/workflow_triggered.liquid

@@ -0,0 +1,22 @@
+You are a workflow agent, spawned automatically after agent "{{ parent_agent_id }}"
+{% if parent_goal_status == "completed" %}completed successfully{% else %}failed{% endif %}.
+
+{% if issue -%}
+Original issue: #{{ issue.number }} {{ issue.title }}{% if issue.url %} ({{ issue.url }}){% endif %}
+{% endif -%}
+{% if story -%}
+Original story: {{ story.ref }}{% if story.url %} ({{ story.url }}){% endif %}
+{% endif -%}
+{% if repo -%}
+Repository: {{ repo }}
+{% endif -%}
+{% if branch -%}
+Branch: {{ branch }}
+{% endif -%}
+
+{% if parent_goal_summary -%}
+Summary from previous agent:
+{{ parent_goal_summary }}
+
+{% endif -%}
+Review the work done by the previous agent and continue from where it left off.

data/lib/superkick/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Superkick
+  VERSION = "0.1.0"
+end

data/lib/superkick/version_control.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Superkick
+  # VersionControl — abstract base class for VCS adapters.
+  #
+  # A version control adapter knows how to acquire an isolated working copy
+  # of a repository and clean it up afterwards.  The adapter is selected
+  # automatically based on the Repository's `version_control` field.
+  #
+  # Subclass contract:
+  #   self.type                      → unique Symbol (e.g. :git, :mercurial, :subversion)
+  #   acquire(source:, destination:, → nil  (create an isolated working copy)
+  #           branch:, base_branch:)
+  #   teardown(destination:)         → nil  (remove the working copy)
+  #
+  # Subclasses register themselves:
+  #   Superkick::VersionControl.register(MyAdapter)
+  class VersionControl
+    # ── Probe — abstract base for VCS detection probes ──────────────────
+    #
+    # Probes detect whether a local directory is managed by a particular VCS
+    # by inspecting the filesystem directly (e.g. checking for `.git`).
+    #
+    # Subclass contract:
+    #   self.type             → unique Symbol (matches the adapter type)
+    #   self.detect_at(path:) → { type: :git } or nil
+    class Probe
+      @registry = {}
+
+      class << self
+        include Superkick::Registry
+
+        def register(klass)
+          raise ArgumentError, "#{klass} must define self.type" unless klass.respond_to?(:type)
+
+          key = klass.type.to_sym
+          raise ArgumentError, "VersionControl::Probe type :#{key} already registered" if @registry.key?(key)
+
+          @registry[key] = klass
+        end
+
+        def registered
+          @registry.dup.freeze
+        end
+
+        # Run all registered probes against a local directory path.
+        # Returns the first match (e.g. { type: :git }) or nil.
+        def detect_from_path(path:)
+          @registry.each_value do |klass|
+            result = klass.detect_at(path:)
+            return result if result
+          end
+          nil
+        end
+
+        def type
+          raise NotImplementedError, "#{self}.type not defined"
+        end
+
+        # Subclasses must override.
+        # @param path [String] absolute path to a directory
+        # @return [Hash, nil] e.g. { type: :git } or nil
+        def detect_at(path:)
+          raise NotImplementedError, "#{self}.detect_at not implemented"
+        end
+      end
+    end
+
+    # ── Registry (stores classes, keyed by type) ─────────────────────────
+    @registry = {}
+
+    class << self
+      include Superkick::Registry
+
+      def register(adapter_class)
+        key = adapter_class.type
+        raise ArgumentError, "VersionControl :#{key} already registered" if @registry.key?(key)
+        @registry[key] = adapter_class
+        Probe.register(adapter_class.probe_class) if adapter_class.probe_class
+      end
+
+      def lookup(name)
+        @registry[name.to_sym] or raise ArgumentError, "Unknown version control: #{name.inspect}"
+      end
+
+      def registered
+        @registry.dup.freeze
+      end
+
+      # Convenience alias — delegates to Probe.detect_from_path.
+      def detect_from_path(path:)
+        Probe.detect_from_path(path:)
+      end
+
+      # Returns the Probe class nested inside this adapter, or nil.
+      def probe_class
+        const_defined?(:Probe, false) ? const_get(:Probe) : nil
+      end
+
+      # Build an adapter for a given Repository.
+      #
+      # @param repository [Repository] the repository to work with
+      # @return [VersionControl] an adapter instance
+      def for_repository(repository)
+        vcs = repository.version_control
+        raise ArgumentError, "Repository #{repository.name} has no version_control set" unless vcs
+        klass = lookup(vcs)
+        klass.new
+      end
+    end
+
+    # ── Instance interface ───────────────────────────────────────────────
+
+    def self.type
+      raise NotImplementedError, "#{self}.type not implemented"
+    end
+
+    # Acquire an isolated working copy of the repository.
+    #
+    # @param source [Repository] the repository to work with
+    # @param destination [String] absolute path where the working copy should be created
+    # @param branch [String] the branch to create or check out
+    # @param base_branch [String] the branch to base the new branch on (default: "main")
+    def acquire(source:, destination:, branch:, base_branch: "main")
+      raise NotImplementedError, "#{self.class}#acquire not implemented"
+    end
+
+    # Remove the isolated working copy.
+    #
+    # @param destination [String] absolute path of the working copy to remove
+    def teardown(destination:)
+      raise NotImplementedError, "#{self.class}#teardown not implemented"
+    end
+  end
+end

data/lib/superkick/yaml_config.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+
+module Superkick
+  # Loads ~/.superkick/config.yml through ERB, then YAML.
+  #
+  # Load order:
+  #   1. plugins   — require each listed gem/file
+  #   2. driver    — call Superkick.use(:name, **driver_opts)
+  #   3. superkick:    — apply tunable keys to Superkick.config
+  #   4. monitors: — named monitor configs stored on Superkick.config.monitors
+  #
+  # Driver-specific options come from the `drivers:` top-level key:
+  #
+  #   driver: claude_code
+  #   drivers:
+  #     claude_code:
+  #       cli_command: /opt/bin/claude
+  #       config_dir: /custom/path/.claude
+  #
+  # Unknown keys under `superkick:` are warned.
+  # Unknown top-level keys are warned.
+  # Ruby config.rb is loaded after this and always wins.
+  module YamlConfig
+    SUPERKICK_KEYS = %i[
+      poll_interval idle_threshold inject_clear_delay
+      rate_limit_backoff error_backoff log_level
+      attach_history_size attach_escape_key attach_rw_idle_timeout
+      attach_replay_buffer_size attach_max_connections
+      cost_poll_interval cost_stale_after
+      max_workers_per_team
+    ].freeze
+
+    NUMERIC_KEYS = %i[poll_interval idle_threshold inject_clear_delay
+      rate_limit_backoff error_backoff attach_history_size attach_rw_idle_timeout
+      attach_replay_buffer_size attach_max_connections
+      cost_poll_interval cost_stale_after max_workers_per_team].freeze
+
+    RESERVED_KEYS = %i[plugins driver drivers superkick monitors notifications spawners budget repositories context_documents server runtime attach session_recording].freeze
+
+    # @param path [String] absolute path to config.yml
+    def self.load!(path)
+      return unless File.exist?(path)
+
+      raw = File.read(path)
+      source = ERB.new(raw).result(env_binding)
+      data = YAML.safe_load(source, permitted_classes: [], aliases: true, symbolize_names: true) || {}
+
+      apply_plugins(data[:plugins] || [])
+      apply_driver(data[:driver], data[:drivers])
+      apply_superkick_section(data[:superkick] || {})
+      apply_monitors_section(data[:monitors] || {})
+      apply_notifications_section(data[:notifications]) if data.key?(:notifications)
+      apply_spawners_section(data[:spawners] || {})
+      apply_budget_section(data[:budget]) if data.key?(:budget)
+      apply_repositories_section(data[:repositories]) if data.key?(:repositories)
+      apply_context_documents_section(data[:context_documents]) if data.key?(:context_documents)
+      apply_server_section(data[:server]) if data.key?(:server)
+      apply_runtime_section(data[:runtime]) if data.key?(:runtime)
+      apply_attach_section(data[:attach]) if data.key?(:attach)
+      apply_session_recording_section(data[:session_recording]) if data.key?(:session_recording)
+      warn_unknown_keys(data)
+    rescue KeyError, Psych::SyntaxError, Psych::DisallowedClass, SyntaxError => e
+      Superkick.logger.error("yaml_config") { "Failed to load config.yml: #{e.message}" }
+    end
+
+    private_class_method def self.env_binding
+      # Expose an env() helper in ERB templates that raises on missing vars.
+      env_mod = Module.new do
+        define_method(:env) do |key|
+          ENV.fetch(key) do
+            raise KeyError, "Required environment variable #{key.inspect} is not set"
+          end
+        end
+      end
+      Object.new.tap { |o| o.extend(env_mod) }.instance_eval { binding }
+    end
+
+    private_class_method def self.apply_plugins(plugins)
+      Array(plugins).each do |plugin|
+        name = plugin.is_a?(Hash) ? plugin[:name] : plugin.to_s
+        begin
+          require name
+          Superkick.logger.info("yaml_config") { "Loaded plugin: #{name}" }
+        rescue LoadError => e
+          Superkick.logger.warn("yaml_config") { "Could not load plugin #{name.inspect}: #{e.message}" }
+        end
+      end
+    end
+
+    private_class_method def self.apply_driver(driver_name, drivers_section)
+      drivers_section ||= {}
+
+      # Extract profiles from the drivers section
+      apply_driver_profiles(drivers_section[:profiles]) if drivers_section[:profiles]
+
+      return unless driver_name
+
+      options = drivers_section[driver_name.to_sym] || {}
+      Superkick.use(driver_name.to_sym, **options)
+    rescue ArgumentError => e
+      Superkick.logger.warn("yaml_config") { "Unknown driver #{driver_name.inspect}: #{e.message}" }
+    end
+
+    private_class_method def self.apply_driver_profiles(profiles)
+      unless profiles.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "drivers.profiles: expected a hash, got #{profiles.class}" }
+        return
+      end
+      Superkick.config.driver_profiles = profiles
+    end
+
+    private_class_method def self.apply_superkick_section(section)
+      configuration = Superkick.config
+
+      section.each do |key, value|
+        if SUPERKICK_KEYS.include?(key)
+          setter = "#{key}="
+          value = value.to_f if NUMERIC_KEYS.include?(key)
+          value = value.to_sym if key == :log_level
+          value = parse_escape_key(value) if key == :attach_escape_key
+          configuration.public_send(setter, value)
+        else
+          Superkick.logger.warn("yaml_config") { "Unknown superkick config key: #{key.inspect}" }
+        end
+      end
+    end
+
+    # Parse a human-readable key name like "ctrl-b" into a single control byte.
+    # Accepts: "ctrl-a" through "ctrl-z", or a raw single-byte string.
+    private_class_method def self.parse_escape_key(value)
+      str = value.to_s.strip.downcase
+      if str.match?(/\Actrl-[a-z]\z/)
+        letter = str[-1]
+        (letter.ord - "a".ord + 1).chr
+      else
+        Superkick.logger.warn("yaml_config") { "Invalid attach_escape_key #{value.inspect} — use 'ctrl-a' through 'ctrl-z'" }
+        "\x01" # fall back to default
+      end
+    end
+
+    private_class_method def self.apply_monitors_section(monitors)
+      if monitors.key?(:privileged_types)
+        apply_privileged_types(monitors[:privileged_types])
+      end
+
+      monitors.each do |name, config|
+        next if name == :privileged_types
+        next unless config.is_a?(Hash)
+        Superkick.config.monitors[name] = config
+        Superkick.logger.info("yaml_config") { "Configured monitor: #{name}" }
+      end
+    end
+
+    private_class_method def self.apply_privileged_types(types)
+      unless types.is_a?(Array)
+        Superkick.logger.warn("yaml_config") { "privileged_types: expected an array, got #{types.class}" }
+        return
+      end
+      Superkick.config.privileged_types = types.map(&:to_sym)
+    end
+
+    private_class_method def self.apply_notifications_section(notifications)
+      if notifications.is_a?(Hash)
+        # Hash form with privileged_types key
+        apply_notification_privileged_types(notifications[:privileged_types]) if notifications[:privileged_types]
+        items = notifications[:items]
+        if items.is_a?(Array)
+          Superkick.config.notifications = items.select { |n| n.is_a?(Hash) }
+        end
+        return
+      end
+
+      unless notifications.is_a?(Array)
+        Superkick.logger.warn("yaml_config") { "notifications: expected an array or hash, got #{notifications.class}" }
+        return
+      end
+
+      Superkick.config.notifications = notifications.select { |n| n.is_a?(Hash) }
+    end
+
+    private_class_method def self.apply_notification_privileged_types(types)
+      unless types.is_a?(Array)
+        Superkick.logger.warn("yaml_config") { "notification privileged_types: expected an array, got #{types.class}" }
+        return
+      end
+      Superkick.config.notification_privileged_types = types.map(&:to_sym)
+    end
+
+    private_class_method def self.apply_spawners_section(spawners)
+      spawners.each do |name, config|
+        next unless config.is_a?(Hash)
+        config[:name] = name
+        Superkick.config.spawners[name] = config
+        Superkick.logger.info("yaml_config") { "Configured spawner: #{name}" }
+      end
+    end
+
+    private_class_method def self.apply_budget_section(budget)
+      unless budget.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "budget: expected a hash, got #{budget.class}" }
+        return
+      end
+      Superkick.config.budget = budget
+    end
+
+    private_class_method def self.apply_repositories_section(repositories)
+      unless repositories.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "repositories: expected a hash, got #{repositories.class}" }
+        return
+      end
+      Superkick.config.repositories = repositories
+    end
+
+    private_class_method def self.apply_context_documents_section(context_documents)
+      unless context_documents.is_a?(Array)
+        Superkick.logger.warn("yaml_config") { "context_documents: expected an array, got #{context_documents.class}" }
+        return
+      end
+      Superkick.config.context_documents = context_documents
+    end
+
+    private_class_method def self.apply_server_section(server)
+      unless server.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "server: expected a hash, got #{server.class}" }
+        return
+      end
+      Superkick.config.server = server
+    end
+
+    private_class_method def self.apply_runtime_section(runtime)
+      unless runtime.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "runtime: expected a hash, got #{runtime.class}" }
+        return
+      end
+      Superkick.config.runtime = runtime
+    end
+
+    # Maps attach: YAML keys to their config accessor names.
+    ATTACH_KEY_MAP = {
+      history_size: :attach_history_size,
+      escape_key: :attach_escape_key,
+      rw_idle_timeout: :attach_rw_idle_timeout,
+      replay_buffer_size: :attach_replay_buffer_size,
+      max_connections: :attach_max_connections
+    }.freeze
+
+    private_class_method def self.apply_attach_section(attach)
+      unless attach.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "attach: expected a hash, got #{attach.class}" }
+        return
+      end
+
+      configuration = Superkick.config
+      attach.each do |key, value|
+        config_key = ATTACH_KEY_MAP[key]
+        unless config_key
+          Superkick.logger.warn("yaml_config") { "Unknown attach config key: #{key.inspect}" }
+          next
+        end
+
+        value = value.to_f if NUMERIC_KEYS.include?(config_key)
+        value = parse_escape_key(value) if config_key == :attach_escape_key
+        configuration.public_send("#{config_key}=", value)
+      end
+    end
+
+    SESSION_RECORDING_KEY_MAP = {
+      enabled: :session_recording_enabled,
+      max_size: :session_recording_max_size
+    }.freeze
+
+    private_class_method def self.apply_session_recording_section(section)
+      unless section.is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "session_recording: expected a hash, got #{section.class}" }
+        return
+      end
+
+      configuration = Superkick.config
+      section.each do |key, value|
+        config_key = SESSION_RECORDING_KEY_MAP[key]
+        unless config_key
+          Superkick.logger.warn("yaml_config") { "Unknown session_recording config key: #{key.inspect}" }
+          next
+        end
+
+        value = value.to_f if config_key == :session_recording_max_size
+        configuration.public_send("#{config_key}=", value)
+      end
+    end
+
+    private_class_method def self.warn_unknown_keys(data)
+      data.each_key do |key|
+        next if RESERVED_KEYS.include?(key)
+        next unless data[key].is_a?(Hash)
+        Superkick.logger.warn("yaml_config") { "Unknown top-level config key: #{key.inspect}" }
+      end
+    end
+  end
+end