superkick 0.1.0

data/lib/superkick/integrations/shortcut/spawner.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Shortcut
+      # Watches Shortcut for stories matching a search query and spawns
+      # AI coding sessions to work on them.
+      #
+      # Server-level spawner — distinct from the agent-bound
+      # Monitor which tracks a single story.
+      #
+      # Config keys:
+      #   query    (required) — Shortcut search query string
+      #   token    (optional) — API token, falls back to $SHORTCUT_API_TOKEN
+      #   workspace_slug (optional) — workspace slug for building story URLs
+      #   owner    (optional) — additional owner filter appended to query
+      #   label    (optional) — additional label filter appended to query
+      class Spawner < Superkick::Spawner
+        API_BASE = Monitor::API_BASE
+        attr_reader :workflow_states, :members, :seen_story_ids, :conn
+
+        def self.type = :shortcut
+
+        def self.description
+          "Watches Shortcut for stories matching a search query and spawns " \
+            "AI coding sessions to work on them. Configurable via query, " \
+            "workflow_state_types, owner, and label filters."
+        end
+
+        def self.required_config = %i[query]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "shortcut-story-#{event[:story].id}"
+        end
+
+        def self.setup_label = "Shortcut"
+
+        def self.setup_config
+          <<~YAML
+            shortcut:
+              type: shortcut
+              query: "state:unstarted label:ai"
+              token: <%= env("SHORTCUT_API_TOKEN") %>
+              # workspace_slug: my-workspace
+              # owner: mention-name              # filter by story owner
+              # label: ai                        # filter by label
+              # max_duration: 3600
+          YAML
+        end
+
+        def initialize(name:, config:, handler:, connection: nil)
+          super(name:, config:, handler:)
+          @conn = connection
+        end
+
+        def tick
+          stories = search_stories
+          stories.each do |story|
+            dispatch(
+              event_type: :story_ready,
+              story: story_drop(story)
+            )
+          end
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @workflow_states = fetch_workflow_states
+          @members = fetch_members
+          @seen_story_ids = Set.new
+        end
+
+        def build_query
+          parts = [self[:query]]
+
+          if self[:owner]
+            parts << "owner:#{self[:owner]}"
+          end
+
+          if self[:label]
+            parts << "label:\"#{self[:label]}\""
+          end
+
+          parts.compact.join(" ")
+        end
+
+        private
+
+        def member_drop(member_id)
+          MemberDrop.new(resolve_member(member_id))
+        end
+
+        def story_drop(story)
+          StoryDrop.new({
+            id: story["id"],
+            name: story["name"],
+            url: story_url(story["id"]),
+            description: story["description"].to_s,
+            type: story["story_type"],
+            workflow_state: resolve_state(story["workflow_state_id"]),
+            labels: (story["labels"] || []).map { |l| l["name"] },
+            owners: (story["owner_ids"] || []).map { member_drop(it) },
+            epic_name: story["epic_id"] ? fetch_epic_name(story["epic_id"]) : nil,
+            tasks: extract_tasks(story).map { TaskDrop.new(it) },
+            comments: extract_recent_comments(story).map { CommentDrop.new(it) }
+          })
+        end
+
+        # -- Shortcut search API ------------------------------------------------
+
+        def search_stories
+          query = build_query
+          Superkick.logger.debug(log_tag) { "Searching: #{query}" }
+
+          resp = post("/api/v3/search/stories", {query:, page_size: 25})
+          return [] unless resp
+
+          stories = resp.body["data"] || []
+
+          # Filter to only newly-seen stories (first time in results).
+          # The AgentStore handles cross-restart dedup; this filters within
+          # a single server lifetime to avoid re-dispatching on every tick.
+          new_stories = stories.reject { |s| @seen_story_ids.include?(s["id"]) }
+          new_stories.each { |s| @seen_story_ids.add(s["id"]) }
+
+          Superkick.logger.info(log_tag) { "Found #{stories.size} matching, #{new_stories.size} new" }
+          new_stories
+        end
+
+        # -- Story data extraction ----------------------------------------------
+
+        def extract_tasks(story)
+          tasks = story["tasks"] || []
+          tasks.map do |t|
+            {description: t["description"], complete: t["complete"]}
+          end
+        end
+
+        def extract_recent_comments(story, limit: 5)
+          comments = story["comments"] || []
+          comments.last(limit).map do |c|
+            {
+              author: member_drop(c["author_id"]),
+              body: c["text"].to_s.strip,
+              created_at: c["created_at"]
+            }
+          end
+        end
+
+        def fetch_epic_name(epic_id)
+          return @epic_names[epic_id] if @epic_names&.key?(epic_id)
+
+          @epic_names ||= {}
+          resp = get("/api/v3/epics/#{epic_id}")
+          return nil unless resp
+
+          epic = resp.body
+          @epic_names[epic_id] = epic["name"]
+          epic["name"]
+        rescue => e
+          Superkick.logger.debug(log_tag) { "Could not fetch epic #{epic_id}: #{e.message}" }
+          nil
+        end
+
+        # -- Shared API helpers (same patterns as ShortcutMonitor) --------------
+
+        def story_url(story_id)
+          slug = self[:workspace_slug]
+          return nil unless slug
+          "https://app.shortcut.com/#{slug}/story/#{story_id}"
+        end
+
+        def resolve_state(state_id)
+          entry = @workflow_states[state_id]
+          return entry[:name] if entry
+
+          @workflow_states = fetch_workflow_states
+          @workflow_states.dig(state_id, :name) || "Unknown"
+        end
+
+        def resolve_member(member_id)
+          return {mention_name: "unknown", display_name: "unknown"} unless member_id
+
+          info = @members[member_id]
+          return info if info
+
+          @members = fetch_members
+          @members[member_id] || {mention_name: member_id.to_s, display_name: member_id.to_s}
+        end
+
+        def fetch_workflow_states
+          resp = get("/api/v3/workflows")
+          return {} unless resp
+
+          states = {}
+          resp.body.each do |wf|
+            wf_states = wf["states"] || []
+            wf_states.each do |s|
+              states[s["id"]] = {name: s["name"], type: s["type"]}
+            end
+          end
+          states
+        end
+
+        def fetch_members
+          resp = get("/api/v3/members")
+          return {} unless resp
+
+          resp.body.each_with_object({}) do |m, h|
+            profile = m["profile"] || {}
+            h[m["id"]] = {
+              mention_name: profile["mention_name"] || m["id"],
+              display_name: profile["name"] || profile["mention_name"] || m["id"]
+            }
+          end
+        end
+
+        # -- HTTP ---------------------------------------------------------------
+
+        def get(path)
+          resp = @conn.get(path)
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        def post(path, body)
+          resp = @conn.post(path, body)
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        # Returns true on success, raises on auth/rate-limit, returns false on 404.
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Shortcut auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Shortcut rate limited"
+          when 404
+            Superkick.logger.warn(log_tag) { "Shortcut 404: resource not found" }
+            false
+          else
+            false
+          end
+        end
+
+        def build_connection
+          token = self[:token] || ENV["SHORTCUT_API_TOKEN"]
+
+          Faraday.new(url: API_BASE) do |f|
+            f.headers["Shortcut-Token"] = token if token
+            f.request :json
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/shortcut/templates/related_story_changed.liquid

@@ -0,0 +1,6 @@
+{% assign labels = relationship %}{% if epic_sibling %}{% assign labels = labels | push: "epic sibling" %}{% endif -%}
+SUPERKICK [{{ "now" | time }}]: Related story {{ story.ref }} ({{ labels | join: ", " }}) moved from "{{ old_state }}" to "{{ new_state }}"
+This may affect your work on {{ primary_story.ref }}.
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut/templates/story_blocker.liquid

@@ -0,0 +1,8 @@
+SUPERKICK [{{ "now" | time }}]: Story {{ story.ref }} is now BLOCKED{% if actor %} by {{ actor.display_name }}{% endif %}.
+{% if blocker_reason -%}
+Reason: {{ blocker_reason | truncate: 200 }}
+{% endif -%}
+You may want to check if you can unblock this or switch to another task.
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut/templates/story_comment.liquid

@@ -0,0 +1,5 @@
+SUPERKICK [{{ "now" | time }}]: New comment on {{ story.ref }} from {{ author.tag }}:
+"{{ body | truncate: 300 }}"
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut/templates/story_description_changed.liquid

@@ -0,0 +1,19 @@
+SUPERKICK [{{ "now" | time }}]: Description updated on {{ story.ref }}{% if actor %} by {{ actor.display_name }}{% endif %}
+{% if old_name != new_name -%}
+Title changed from "{{ old_name | truncate: 80 }}" to "{{ new_name | truncate: 80 }}"
+{% endif -%}
+{% if old_description != new_description -%}
+
+Previous description:
+{{ old_description | truncate: 2000 }}
+
+Updated description:
+{{ new_description | truncate: 2000 }}
+
+Please review the changes above — the story requirements may have changed.
+{% else -%}
+The story requirements may have changed. Consider reviewing the updated description.
+{% endif -%}
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut/templates/story_owner_changed.liquid

@@ -0,0 +1,10 @@
+SUPERKICK [{{ "now" | time }}]: Owners changed on {{ story.ref }}{% if actor %} by {{ actor.display_name }}{% endif %}
+{% if added_owners.size > 0 -%}
+Added: {{ added_owners | map: "tag" | join: ", " }}
+{% endif -%}
+{% if removed_owners.size > 0 -%}
+Removed: {{ removed_owners | map: "tag" | join: ", " }}
+{% endif -%}
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut/templates/story_ready.liquid

@@ -0,0 +1,41 @@
+You have been assigned to work on a Shortcut story.
+
+## Story: sc-{{ story.id }} — {{ story.name }}
+{% if story.url -%}
+URL: {{ story.url }}
+{% endif -%}
+Type: {{ story.type }}
+State: {{ story.workflow_state }}
+{% if story.epic_name -%}
+Epic: {{ story.epic_name }}
+{% endif -%}
+{% if story.labels.size > 0 -%}
+Labels: {{ story.labels | join: ", " }}
+{% endif -%}
+{% if story.owners.size > 0 -%}
+Owners: {{ story.owners | map: "tag" | join: ", " }}
+{% endif -%}
+
+## Description
+
+{% if story.description == "" %}(no description){% else %}{{ story.description }}{% endif %}
+{% if story.tasks.size > 0 -%}
+
+## Tasks
+
+{% for t in story.tasks -%}
+- [{% if t.complete %}x{% else %} {% endif %}] {{ t.description }}
+{% endfor -%}
+{% endif -%}
+{% if story.comments.size > 0 -%}
+
+## Recent Comments
+
+{% for c in story.comments -%}
+**{{ c.author.display_name }}**: {{ c.body | truncate: 200 }}
+{% endfor -%}
+{% endif -%}
+
+Please read the story description and tasks carefully. Implement the requested
+changes, write tests, and commit your work. If anything is unclear, check the
+story comments or linked stories for additional context.

data/lib/superkick/integrations/shortcut/templates/story_state_changed.liquid

@@ -0,0 +1,9 @@
+SUPERKICK [{{ "now" | time }}]: Story {{ story.ref }} moved from "{{ old_state }}" to "{{ new_state }}"{% if actor %} by {{ actor.display_name }}{% endif %}
+{% if new_state_type == "done" -%}
+The story has been marked as complete.
+{% elsif new_state_type == "backlog" -%}
+The story has been moved back to the backlog. Check if there are blockers or scope changes.
+{% endif -%}
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut/templates/story_unblocked.liquid

@@ -0,0 +1,5 @@
+SUPERKICK [{{ "now" | time }}]: Story {{ story.ref }} is no longer blocked{% if actor %} by {{ actor.display_name }}{% endif %}.
+You can resume work on this story.
+{% if story.url -%}
+{{ story.url }}
+{% endif -%}

data/lib/superkick/integrations/shortcut.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "shortcut/drops"
+require_relative "shortcut/monitor"
+require_relative "shortcut/probe"
+require_relative "shortcut/spawner"
+
+module Superkick
+  Monitor.register(Integrations::Shortcut::Monitor)
+  Spawner.register(Integrations::Shortcut::Spawner)
+end

data/lib/superkick/integrations/slack/README.md

@@ -0,0 +1,297 @@
+# Slack Integration
+
+The Slack integration provides three components:
+
+- **Notifier** (`:slack`) — posts Block Kit notifications to Slack
+- **Spawner** (`:slack`) — watches a channel for messages and spawns agents
+- **Thread Monitor** (`:slack_thread`) — polls a thread for replies and injects them
+
+Plus **Liquid Drops** for type-safe template access to Slack data.
+
+---
+
+## Notifier
+
+Type: `:slack`
+
+Posts rich Block Kit messages to Slack when an injection or lifecycle event
+occurs. Supports two authentication modes.
+
+### Configuration
+
+**Incoming Webhook** — posts to a single channel, no bot token needed:
+
+```yaml
+notifications:
+  - type: slack
+    webhook_url: <%= env("SLACK_WEBHOOK_URL") %>
+```
+
+**Web API** — can target any channel, requires a bot token with `chat:write` scope:
+
+```yaml
+notifications:
+  - type: slack
+    token: <%= env("SLACK_BOT_TOKEN") %>
+    channel: "#superkick-notifications"
+    events:
+      - agent_completed
+      - agent_failed
+      - agent_blocked
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `webhook_url` | one of webhook or token | — | Slack Incoming Webhook URL |
+| `token` | one of webhook or token | — | Slack Bot User OAuth Token (`xoxb-...`) |
+| `channel` | with token | — | Channel name or ID to post to |
+
+### Message format
+
+Messages use Slack's Block Kit for rich formatting. The default template
+produces a header, section, and context block. Custom templates have access
+to the full set of Block Kit block types via Liquid tags:
+
+**Block tags:** `{% header %}`, `{% section %}`, `{% context %}`, `{% image %}`,
+`{% button %}`, `{% fields %}`, `{% rich_text %}`, `{% video %}`, `{% input %}`
+
+**Bodyless tags:** `{% divider %}`, `{% file %}`
+
+Consecutive `{% button %}` tags auto-group into a single `actions` block.
+
+A plain-text `text` field is included as a fallback for notification previews.
+
+### Stateful threading (Web API mode)
+
+In Web API mode, the Slack notifier is **stateful** — it tracks `thread_ts` per
+agent or team so related events are threaded together in the channel:
+
+- When an agent has a `team_id`, messages are threaded by **team** (all agents in
+  the same team share a single Slack thread)
+- Without a team, messages are threaded by **agent** (each agent gets its own thread)
+
+The first event creates a new top-level message; subsequent events for the same
+agent/team reply to it, keeping the channel clean.
+
+Webhook mode is **stateless** — Slack webhooks don't return a message `ts`, so
+each message is standalone.
+
+State is stored via `NotifierStateStore` (in-memory for local server, database-backed
+for hosted).
+
+### Event filtering
+
+Restrict which events a notifier receives with `events:`:
+
+```yaml
+notifications:
+  - type: slack
+    token: <%= env("SLACK_BOT_TOKEN") %>
+    channel: "#superkick-alerts"
+    events:
+      - agent_blocked
+      - agent_failed
+      - budget_exceeded
+```
+
+When `events:` is absent, the notifier receives all events.
+
+### Event emoji
+
+Every lifecycle event has a mapped emoji via `EMOJI_MAP`. For unknown event
+types, the `event_emoji` filter uses keyword substring matching — if the event
+type contains a recognized keyword (e.g. `completed`, `failed`, `spawned`,
+`warning`), the corresponding emoji is used. Fully unrecognized events fall
+back to `:bell:`.
+
+This means custom events like `deployment_completed` or `build_failed`
+automatically get reasonable emoji without explicit registration.
+
+### Custom templates
+
+Override the default Block Kit template per event type or globally:
+
+```
+~/.superkick/templates/notifications/slack/<event_type>.liquid  # per-event
+~/.superkick/templates/notifications/slack/default.liquid        # catch-all
+```
+
+Templates use the `liquid do` DSL with Slack-specific block and bodyless tags.
+The accumulator builds up a Block Kit `blocks` array and optional metadata. See
+the [notifier skill](../../../../skills/superkick-new-notifier/SKILL.md) for the
+full template authoring guide.
+
+### Liquid filters
+
+| Filter | Description |
+|--------|-------------|
+| `event_emoji` | Maps event types to Slack emoji (3-tier: explicit → keyword → `:bell:`) |
+| `format_title` | Formats a notification title with event type |
+| `join_present` | Joins non-nil/non-empty values with a separator |
+
+---
+
+## Spawner
+
+Type: `:slack`
+
+Watches a Slack channel for new top-level messages via `conversations.history`
+and spawns an agent for each one. When `monitor_thread` is enabled (the
+default), the spawned agent automatically gets a `slack_thread` monitor that
+feeds user replies back as high-priority injections.
+
+### Configuration
+
+```yaml
+spawners:
+  slack_support:
+    type: slack
+    channel: C0123456789
+    channel_name: support
+    token: <%= env("SLACK_BOT_TOKEN") %>
+    driver: claude_code
+    max_duration: 3600
+```
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `channel` | yes | — | Slack channel ID (e.g. `C0123456789`) |
+| `token` | no | `SLACK_BOT_TOKEN` env | Bot User OAuth Token |
+| `channel_name` | no | — | Human-readable channel name for templates |
+| `filter_pattern` | no | — | Regex; only matching messages trigger spawns |
+| `ignore_bots` | no | `true` | Skip bot messages and the bot's own user ID |
+| `ignore_threads` | no | `true` | Skip threaded replies (only top-level messages) |
+| `monitor_thread` | no | `true` | Auto-attach `slack_thread` monitor to spawned agents |
+
+### Bot token scopes
+
+The bot token needs these OAuth scopes:
+
+- `channels:history` — read channel messages
+- `users:read` — resolve user display names
+- `chat:write` — (if using the Slack notifier for replies)
+
+### Agent ID format
+
+`slack-message-{channel_id}-{message_ts}` — unique per message.
+
+### Spawn event
+
+The spawner dispatches events with these keys:
+
+| Key | Description |
+|-----|-------------|
+| `event_type` | `:slack_message` |
+| `channel_id` | Slack channel ID |
+| `channel_name` | Human-readable channel name |
+| `message_ts` | Message timestamp |
+| `slack_thread_ts` | Thread timestamp (same as `message_ts` for top-level) |
+| `user` | Slack user ID |
+| `user_name` | Resolved display name |
+| `text` | Message text |
+| `message` | `MessageDrop` (with nested `sender` and `channel`) |
+| `sender` | `UserDrop` |
+| `channel` | `ChannelDrop` |
+
+### Thread monitoring
+
+When `monitor_thread: true` (default), the spawner attaches a `_spawn_monitors`
+entry to the event. The spawn handler automatically starts a `slack_thread`
+monitor for the spawned agent, so replies in the Slack thread are injected
+as high-priority events.
+
+---
+
+## Thread Monitor
+
+Type: `:slack_thread`
+
+Polls a Slack thread for new replies via `conversations.replies` and injects
+them into the agent as high-priority events. Typically auto-attached by the
+Slack spawner — not configured manually.
+
+### Configuration
+
+Injected automatically at spawn time:
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `channel_id` | yes | — | Slack channel ID |
+| `thread_ts` | yes | — | Root message timestamp |
+| `token` | no | `SLACK_BOT_TOKEN` env | Bot User OAuth Token |
+
+### Injection event
+
+| Key | Description |
+|-----|-------------|
+| `event_type` | `:slack_reply` |
+| `user` | Slack user ID |
+| `user_name` | Resolved display name |
+| `text` | Reply text |
+| `message_ts` | Reply timestamp |
+| `sender` | `UserDrop` |
+| `channel` | `ChannelDrop` |
+| `injection_priority` | `:high` |
+| `injection_ttl` | `900` seconds |
+
+---
+
+## Drops
+
+Three Liquid Drop classes provide type-safe template access to Slack data.
+All drops survive serialization/rehydration via `_drop_type` markers.
+
+### `MessageDrop` (`slack_message`)
+
+Wraps a Slack message with nested sender and channel drops.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `text` | String | Message text |
+| `sender` | `UserDrop` | Nested user drop |
+| `channel` | `ChannelDrop` | Nested channel drop |
+| `message_ts` | String | Message timestamp |
+| `thread_ts` | String | Thread timestamp |
+| `ref` | String | Formatted: `@Alice in #engineering` |
+
+### `UserDrop` (`slack_user`)
+
+Wraps a Slack user.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `id` | String | Slack user ID (e.g. `U123`) |
+| `name` | String | Display name |
+| `tag` | String | Formatted: `Alice (<@U123>)` |
+
+### `ChannelDrop` (`slack_channel`)
+
+Wraps a Slack channel.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `id` | String | Channel ID (e.g. `C456`) |
+| `name` | String | Channel name |
+| `ref` | String | Formatted: `#engineering` (falls back to ID) |
+
+### Template usage
+
+```liquid
+Message from {{ message.sender.tag }} in {{ message.channel.ref }}:
+{{ message.text }}
+```
+
+### Serialization
+
+Nested drops are serialized recursively via `to_h` and rehydrated via
+`Drop.rehydrate`:
+
+```ruby
+serialized = message_drop.to_h
+# => { _drop_type: "slack_message", text: "...",
+#      sender: { _drop_type: "slack_user", id: "U123", name: "Alice" },
+#      channel: { _drop_type: "slack_channel", id: "C456", name: "engineering" } }
+
+rehydrated = Superkick::Drop.rehydrate(serialized)
+rehydrated.sender.name  # => "Alice"
+```