anima-core 1.2.0 → 1.3.0

data/lib/tui/screens/chat.rb

@@ -12,6 +12,8 @@ require_relative "../decorators/write_decorator"
 require_relative "../decorators/web_get_decorator"
 require_relative "../decorators/think_decorator"
 require_relative "../formatting"
+require_relative "../braille_spinner"
+require "toon"
 
 module TUI
   module Screens
@@ -28,7 +30,6 @@ module TUI
       MOUSE_SCROLL_STEP = 2
 
       TOOL_ICON = "\u{1F527}"
-      CLOCK_ICON = "\u{1F552}"
       CHECKMARK = "\u2713"
 
       # Viewport virtualization tuning
@@ -36,15 +37,26 @@ module TUI
       VIEWPORT_OVERFLOW_MULTIPLIER = 2 # build this many viewports worth of lines
       VIEWPORT_BOTTOM_THRESHOLD = 10   # entries from end before we include all trailing
 
-      ROLE_COLORS = {"user" => "green", "assistant" => "cyan"}.freeze
+      # Background-highlighted styles for conversation roles.
+      # Dark tinted backgrounds make user/assistant messages easy to scan.
+      # 22 = dark green (#005f00), 17 = dark navy (#00005f) in 256-color.
+      ROLE_STYLES = {
+        "user" => {fg: "white", bg: 22, modifiers: [:bold]},
+        "assistant" => {fg: "white", bg: 17, modifiers: [:bold]}
+      }.freeze
 
       # Intentionally duplicated from Session::VIEW_MODES to keep the TUI
       # independent of Rails. Must stay in sync when adding new modes.
       VIEW_MODES = %w[basic verbose debug].freeze
 
+      # @!attribute [r] session_loading
+      #   Whether the TUI is waiting for session history to arrive from the server.
+      #   Independent of cable_client.status (transport) and session_state (LLM processing).
+      #   Set on subscribing/session_changed/view_mode_changed; cleared on first content
+      #   message or connection failure. Drives the "Loading…" input title and yellow border.
       attr_reader :message_store, :scroll_offset, :session_info, :view_mode, :sessions_list,
         :authentication_required, :token_save_result, :parent_session_id,
-        :chat_focused
+        :chat_focused, :session_state, :spinner, :session_loading
       attr_accessor :hud_hint
 
       # @param cable_client [TUI::CableClient] WebSocket client connected to the brain
@@ -56,7 +68,9 @@ module TUI
         @perf_logger = perf_logger || PerformanceLogger.new(enabled: false)
         @input_buffer = InputBuffer.new
         @flash = Flash.new
-        @loading = false
+        @session_state = "idle"
+        @session_loading = false
+        @spinner = BrailleSpinner.new
         @scroll_offset = 0
         @auto_scroll = true
         @visible_height = 0
@@ -229,8 +243,12 @@ module TUI
       def finalize
       end
 
+      # Whether the session is actively processing (any state other than idle).
+      # Used by the App's HUD and scroll calculations.
+      #
+      # @return [Boolean]
       def loading?
-        @loading
+        @session_state != "idle"
       end
 
       # Switches focus to the chat pane for keyboard scrolling.
@@ -245,15 +263,49 @@ module TUI
         @chat_focused = false
       end
 
+      # Short label describing the current session state for HUD display.
+      #
+      # @return [String]
+      def spinner_label
+        case @session_state
+        when "llm_generating" then "Thinking..."
+        when "tool_executing" then "Executing..."
+        when "interrupting" then "Stopping..."
+        else "Working..."
+        end
+      end
+
+      # Color name for the spinner and HUD label based on session state.
+      # Follows the two-channel design: color = status (green = working,
+      # red = stopping). The braille animation pattern communicates type.
+      #
+      # @return [String]
+      def spinner_color
+        case @session_state
+        when "llm_generating", "tool_executing" then "green"
+        when "interrupting" then "red"
+        else "dark_gray"
+        end
+      end
+
       private
 
-      # Drains the WebSocket message queue and feeds events to the message store
+      # Drains the WebSocket message queue and feeds events to the message store.
+      #
+      # Called once per render frame. All operations here MUST be non-blocking:
+      # drain_messages uses Thread::Queue#pop(true), and every handler performs
+      # only in-memory state updates. Network I/O (WebSocket sends, reconnection)
+      # happens in CableClient's background thread via Thread::Queue.
       def process_incoming_messages
         @cable_client.drain_messages.each do |msg|
           action = msg["action"]
           type = msg["type"]
 
           case action
+          when "session_state"
+            handle_session_state(msg)
+          when "child_state"
+            handle_child_state(msg)
           when "session_changed"
             handle_session_changed(msg)
           when "view_mode_changed"
@@ -272,8 +324,10 @@ module TUI
             handle_children_updated(msg)
           when "sessions_list"
             @sessions_list = msg["sessions"]
-          when "user_message_recalled"
-            @message_store.remove_by_id(msg["message_id"]) if msg["message_id"]
+          when "pending_message_created"
+            @message_store.add_pending(msg["pending_message_id"], msg["content"]) if msg["pending_message_id"]
+          when "pending_message_removed"
+            @message_store.remove_pending(msg["pending_message_id"]) if msg["pending_message_id"]
           when "authentication_required"
             @authentication_required = true
           when "token_saved"
@@ -281,6 +335,8 @@ module TUI
             @token_save_result = {success: true, warning: msg["warning"]}.compact
           when "token_error"
             @token_save_result = {success: false, message: msg["message"]}
+          when "interrupt_acknowledged"
+            @flash.info("Interrupting...")
           when "error"
             @flash.error(msg["message"]) if msg["message"]
           else
@@ -290,18 +346,19 @@ module TUI
             when "connection"
               handle_connection_status(msg)
             when "user_message"
+              @session_loading = false
               @message_store.process_event(msg)
               unless action == "update"
                 @session_info[:message_count] += 1
-                @loading = true
               end
             when "agent_message"
+              @session_loading = false
               @message_store.process_event(msg)
               unless action == "update"
                 @session_info[:message_count] += 1
-                @loading = false
               end
             else # tool_call, tool_response, and other event types
+              @session_loading = false
               @message_store.process_event(msg)
             end
           end
@@ -341,10 +398,12 @@ module TUI
         case msg["status"]
         when "subscribing"
           @message_store.clear
-          @loading = false
+          @session_loading = true
+          update_session_state("idle")
           @session_info[:message_count] = 0
         when "disconnected", "failed"
-          @loading = false
+          @session_loading = false
+          update_session_state("idle")
         end
       end
 
@@ -357,7 +416,7 @@ module TUI
         error = msg["error"]
 
         @message_store.remove_by_id(message_id) if message_id
-        @loading = false
+        update_session_state("idle")
 
         if content
           @input_buffer.clear
@@ -371,6 +430,9 @@ module TUI
         new_id = msg["session_id"]
         @cable_client.update_session_id(new_id)
         @message_store.clear
+        # Only enter loading state when the session has messages to replay.
+        # Empty sessions send no history events, so the flag would never clear.
+        @session_loading = (msg["message_count"] || 0) > 0
         @view_mode = msg["view_mode"] if msg["view_mode"]
         @session_info = {id: new_id, name: msg["name"], agent_name: msg["agent_name"] || "Anima",
                          message_count: msg["message_count"] || 0,
@@ -378,7 +440,7 @@ module TUI
                          goals: msg["goals"] || [], children: msg["children"] || []}
         @parent_session_id = msg["parent_session_id"]
         @input_buffer.clear
-        @loading = false
+        update_session_state("idle")
         @scroll_offset = 0
         @auto_scroll = true
         @input_scroll_offset = 0
@@ -426,6 +488,58 @@ module TUI
         @session_info[:children] = msg["children"] || []
       end
 
+      # Handles explicit session state transitions from the server.
+      # Drives the braille spinner animation. Only processes broadcasts
+      # matching the current session.
+      #
+      # @param msg [Hash] ActionCable payload with "session_id" and "state" keys
+      # @return [void]
+      def handle_session_state(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        update_session_state(msg["state"])
+      end
+
+      # Handles a child session's state change broadcast from the
+      # parent stream. Merges the state into the children list so
+      # HUD icons update without a full children_updated query.
+      #
+      # @param msg [Hash] ActionCable payload with "child_id" and "state" keys
+      # @return [void]
+      def handle_child_state(msg)
+        child_id = msg["child_id"]
+        return unless child_id
+
+        child = @session_info[:children]&.find { |c| c["id"] == child_id }
+        child["session_state"] = msg["state"] if child
+      end
+
+      # Updates the session state and synchronizes the spinner.
+      #
+      # @param state [String] one of "idle", "llm_generating",
+      #   "tool_executing", "interrupting"
+      def update_session_state(state)
+        @session_state = state
+        @spinner.state = state
+      end
+
+      # Builds the animated spinner line for the current session state.
+      # The braille character communicates state through its animation
+      # pattern; a short label follows for clarity.
+      #
+      # @param tui [RatatuiRuby] TUI rendering API
+      # @return [RatatuiRuby::Widgets::Line]
+      def spinner_line(tui)
+        char = @spinner.tick || "\u2800"
+        label = spinner_label
+        color = spinner_color
+
+        tui.line(spans: [
+          tui.span(content: "#{char} ", style: tui.style(fg: color, modifiers: [:bold])),
+          tui.span(content: label, style: tui.style(fg: color))
+        ])
+      end
+
       # Handles server broadcast of view mode change. Clears the message store
       # in preparation for the re-decorated viewport events that follow.
       def handle_view_mode_changed(msg)
@@ -434,7 +548,10 @@ module TUI
 
         @view_mode = new_mode
         @message_store.clear
-        @loading = false
+        # Only enter loading state when there are messages to re-decorate.
+        # Empty sessions send no viewport events after a mode change.
+        @session_loading = (@session_info[:message_count] || 0) > 0
+        update_session_state("idle")
         @scroll_offset = 0
         @auto_scroll = true
       end
@@ -468,9 +585,7 @@ module TUI
         # from actual viewport height. Clamping here would cap scroll_offset
         # to the (under)estimated total, making the bottom unreachable.
         if @auto_scroll
-          est_total = @height_map.total_height
-          est_total += 1 if @loading
-          @scroll_offset = [est_total - @visible_height, 0].max
+          @scroll_offset = [@height_map.total_height - @visible_height, 0].max
         end
 
         # Phase 3: Find approximate first visible entry
@@ -495,8 +610,7 @@ module TUI
         vp_last = @viewport[:last]
         est_before = @height_map.cumulative_height(vp_first)
         est_after = @height_map.total_height - @height_map.cumulative_height(vp_last + 1)
-        loading_outside = @loading && vp_last < entries.size - 1
-        corrected_total = est_before + wrapped_height + est_after + (loading_outside ? 1 : 0)
+        corrected_total = est_before + wrapped_height + est_after
 
         @max_scroll = [corrected_total - @visible_height, 0].max
         @scroll_offset = @max_scroll if @auto_scroll
@@ -514,20 +628,45 @@ module TUI
         }
         @perf_logger.measure(:render_widget) { frame.render_widget(widget, area) }
 
-        return unless @max_scroll > 0
+        if @max_scroll > 0
+          scrollbar = tui.scrollbar(
+            content_length: @max_scroll,
+            position: @scroll_offset,
+            orientation: :vertical_right,
+            thumb_style: {fg: "cyan"},
+            track_symbol: "\u2502",
+            track_style: {fg: "dark_gray"}
+          )
+          frame.render_widget(scrollbar, area)
+        end
+
+        # Spinner overlay: rendered on top of the last line inside the
+        # chat border, rebuilt every frame. Independent of the viewport
+        # cache — the braille animation advances without cache invalidation.
+        render_spinner_overlay(frame, area, tui) if loading?
+      end
+
+      # Renders the spinner as a 1-line overlay at the bottom of the chat
+      # pane, inside the border. Painted on top of whatever the messages
+      # paragraph rendered there — same pattern as the token setup popup.
+      def render_spinner_overlay(frame, area, tui)
+        inner = tui.block(**chat_block_config).inner(area)
+        return if inner.height < 1
 
-        scrollbar = tui.scrollbar(
-          content_length: @max_scroll,
-          position: @scroll_offset,
-          orientation: :vertical_right,
-          thumb_style: {fg: "cyan"},
-          track_symbol: "\u2502",
-          track_style: {fg: "dark_gray"}
+        spinner_rect = tui.rect(
+          x: inner.x,
+          y: inner.y + inner.height - 1,
+          width: inner.width,
+          height: 1
         )
-        frame.render_widget(scrollbar, area)
+        frame.render_widget(tui.clear, spinner_rect)
+        widget = tui.paragraph(text: [spinner_line(tui)])
+        frame.render_widget(widget, spinner_rect)
       end
 
       # Renders the empty or loading state placeholder when no messages exist.
+      # Three states: active processing (spinner), session loading (loading
+      # indicator), and truly empty (start chatting prompt).
       # Resets scroll state since there is no scrollable content.
       #
       # @param frame [RatatuiRuby::Frame] current render frame
@@ -535,9 +674,11 @@ module TUI
       # @param tui [RatatuiRuby] TUI rendering API
       # @return [void]
       def render_empty_or_loading(frame, area, tui)
-        lines = if @loading
+        lines = if loading?
+          [spinner_line(tui)]
+        elsif @session_loading
           [tui.line(spans: [
-            tui.span(content: "Thinking...", style: tui.style(fg: "yellow", modifiers: [:bold]))
+            tui.span(content: "Loading session\u2026", style: tui.style(fg: "yellow"))
           ])]
         else
           [tui.line(spans: [
@@ -555,19 +696,18 @@ module TUI
       # Re-estimates entry heights when content or width changes.
       # Height estimation is O(n) string-length math — orders of
       # magnitude cheaper than building Line/Span objects. Skips
-      # re-estimation when version, width, and loading state are unchanged.
+      # re-estimation when version and width are unchanged.
       #
       # @param entries [Array<Hash>] message store entries
       # @param width [Integer] available terminal width
       # @param version [Integer] message store version counter
       # @return [void]
       def update_height_map(entries, width, version)
-        return if version == @height_map_version && width == @height_map_width && @loading == @height_map_loading
+        return if version == @height_map_version && width == @height_map_width
 
         @height_map.update(entries, width) { |entry, avail_width| estimate_entry_height(entry, avail_width) }
         @height_map_version = version
         @height_map_width = width
-        @height_map_loading = @loading
       end
 
       # Returns cached viewport lines, rebuilding only when content
@@ -581,7 +721,7 @@ module TUI
         vp_first = vp[:first]
 
         # Cache hit: content unchanged and scroll target within the built range
-        if version == vp[:version] && @loading == vp[:loading] &&
+        if version == vp[:version] &&
             vp_first && first_visible_est >= vp_first && first_visible_est <= vp[:last]
           return vp[:lines]
         end
@@ -611,19 +751,13 @@ module TUI
           break if pre_wrap_count >= target && entry_count - idx > VIEWPORT_BOTTOM_THRESHOLD
         end
 
-        if @loading && buf_last >= entry_count - 1
-          lines << tui.line(spans: [
-            tui.span(content: "Thinking...", style: tui.style(fg: "yellow", modifiers: [:bold]))
-          ])
-        end
-
         @perf_logger.info(
           "viewport MISS range=#{buf_first}..#{buf_last} " \
           "of=#{entry_count} lines=#{lines.size}"
         )
 
         @viewport = {
-          version: version, loading: @loading, width: nil,
+          version: version, width: nil,
           first: buf_first, last: buf_last,
           lines: lines, wrapped_height: nil
         }
@@ -636,7 +770,7 @@ module TUI
       def cached_viewport_line_count(widget, width, version)
         vp = @viewport
         cached_height = vp[:wrapped_height]
-        if cached_height && version == vp[:version] && @loading == vp[:loading] && width == vp[:width]
+        if cached_height && version == vp[:version] && width == vp[:width]
           return cached_height
         end
 
@@ -777,8 +911,8 @@ module TUI
       end
 
       # Renders a user or assistant message with optional timestamp and token count.
-      # Pending messages are dimmed with a clock icon to indicate they haven't
-      # been sent to the LLM yet.
+      # Pending messages are dimmed to indicate they haven't been sent to the
+      # LLM yet.
       # @param tui [RatatuiRuby] TUI rendering API
       # @param data [Hash] structured data with "role", "content", and optional
       # Display label for a conversation role. Uses the agent name from
@@ -798,18 +932,36 @@ module TUI
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_conversation_entry(tui, data, role)
         pending = data["status"] == "pending"
-        color = pending ? "dark_gray" : ROLE_COLORS.fetch(role, "white")
-        prefix = role_label(role)
-        prefix = "#{CLOCK_ICON} #{prefix}" if pending
-        style = tui.style(fg: color)
+        label = role_label(role)
 
-        meta = []
-        meta << "[#{format_ns_timestamp(data["timestamp"])}]" if data["timestamp"]
-        meta << format_token_label(data["tokens"], data["estimated"]) if data["tokens"]
-        header = meta.empty? ? "#{prefix}:" : "#{meta.join(" ")} #{prefix}:"
+        if pending
+          style = tui.style(fg: "gray")
+        else
+          role_cfg = ROLE_STYLES.fetch(role, {fg: "white"})
+          style = tui.style(**role_cfg)
+        end
 
+        tokens = data["tokens"]
         content_lines = data["content"].to_s.split("\n", -1)
-        lines = [tui.line(spans: [tui.span(content: "#{header} #{content_lines.first}", style: style)])]
+        first_content = content_lines.first
+        ts = data["timestamp"]
+        ts_prefix = ts ? "[#{format_ns_timestamp(ts)}] " : ""
+
+        first_spans = if tokens && !pending
+          tok_style = {fg: token_count_color(tokens)}
+          role_bg = ROLE_STYLES.dig(role, :bg)
+          tok_style[:bg] = role_bg if role_bg
+          [
+            tui.span(content: ts_prefix, style: style),
+            tui.span(content: "#{format_token_label(tokens, data["estimated"])} ", style: tui.style(**tok_style)),
+            tui.span(content: "#{label}: #{first_content}", style: style)
+          ]
+        else
+          header = ts_prefix.empty? ? "#{label}:" : "#{ts_prefix}#{label}:"
+          [tui.span(content: "#{header} #{first_content}", style: style)]
+        end
+
+        lines = [tui.line(spans: first_spans)]
         content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: line, style: style)]) }
         lines
       end
@@ -829,26 +981,55 @@ module TUI
         lines
       end
 
-      # Renders the assembled system prompt block in debug mode.
+      # Renders the assembled system prompt and tool schemas in debug mode.
+      # Tool schemas are converted to TOON format for readability.
       # @param tui [RatatuiRuby] TUI rendering API
-      # @param data [Hash] structured data with "content", "tokens", "estimated"
+      # @param data [Hash] structured data with "content", "tokens", "estimated",
+      #   and optionally "tools" (Array<Hash> of tool schemas)
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_system_prompt_entry(tui, data)
-        token_label = format_token_label(data["tokens"], data["estimated"])
-        header = "[SYSTEM] (#{token_label})"
-        style = tui.style(fg: "magenta")
+        tokens = data["tokens"]
         bold_style = tui.style(fg: "magenta", modifiers: [:bold])
+        style = tui.style(fg: "magenta")
+        tool_style = tui.style(fg: "cyan")
+
+        header_spans = [tui.span(content: "[SYSTEM] ", style: bold_style)]
+        if tokens
+          tok_label = format_token_label(tokens, data["estimated"])
+          header_spans << tui.span(content: "(#{tok_label})", style: tui.style(fg: token_count_color(tokens)))
+        end
 
-        lines = [tui.line(spans: [tui.span(content: header, style: bold_style)])]
+        lines = [tui.line(spans: header_spans)]
         data["content"].to_s.split("\n").each do |line|
           lines << tui.line(spans: [tui.span(content: "  #{line}", style: style)])
         end
+
+        if data["tools"].is_a?(Array) && data["tools"].any?
+          lines << tui.line(spans: [tui.span(content: "", style: style)])
+          lines << tui.line(spans: [tui.span(content: "\u00a0\u00a0## Tools (#{data["tools"].size})", style: bold_style)])
+          tools_toon(data).split("\n").each do |line|
+            lines << tui.line(spans: [tui.span(content: line, style: tool_style)])
+          end
+        end
+
         lines
       end
 
+      # Converts tool schemas to TOON format for display. Caches the result
+      # on the data hash so the conversion runs once per broadcast, not per
+      # frame. Uses non-breaking spaces for indentation because ratatui's
+      # Paragraph widget with wrap:true trims regular leading spaces.
+      # @param data [Hash] entry data containing "tools" array
+      # @return [String] TOON-formatted tool schemas
+      def tools_toon(data)
+        data["tools_toon"] ||= Toon.encode(data["tools"])
+          .gsub(/^( +)/) { "\u00a0" * _1.length }
+      end
+
       def build_chat_message_lines(tui, msg)
         role = msg[:role]
-        role_style = (role == ROLE_USER) ? tui.style(fg: "green", modifiers: [:bold]) : tui.style(fg: "cyan", modifiers: [:bold])
+        role_cfg = ROLE_STYLES.fetch(role, {fg: "white"})
+        role_style = tui.style(**role_cfg)
 
         label = role_label(role)
         content_lines = msg[:content].to_s.split("\n", -1)
@@ -913,6 +1094,8 @@ module TUI
       def input_styles(tui, disabled)
         border_color = if disabled || @chat_focused
           "dark_gray"
+        elsif @session_loading
+          "yellow"
         else
           "green"
         end
@@ -923,11 +1106,25 @@ module TUI
         }
       end
 
+      # Returns the input field title reflecting the current transport and
+      # session state. Only shows "Disconnected" when the WebSocket is
+      # truly down — not during the subscribe handshake or session loading.
+      #
+      # :connected (pre-subscription) still shows "Connecting…" because
+      # the user can't interact until the Action Cable subscription handshake
+      # completes and the server starts streaming events.
       def input_title
-        if !connected?
+        case @cable_client.status
+        when :disconnected
           "Disconnected"
+        when :reconnecting
+          "Reconnecting\u2026"
+        when :connecting, :connected
+          "Connecting\u2026"
+        when :subscribed
+          @session_loading ? "Loading\u2026" : "Input"
         else
-          "Input"
+          "Disconnected"
         end
       end
 
@@ -1046,17 +1243,17 @@ module TUI
 
       # Recalls the last pending user message for editing. Removes it from
       # the message store, puts its content back in the input buffer, and
-      # tells the server to delete the message.
+      # tells the server to delete the {PendingMessage}.
       #
       # @return [Boolean] true if a message was recalled
       def recall_pending_message
         pending = @message_store.last_pending_user_message
         return false unless pending
 
-        @message_store.remove_by_id(pending[:id])
+        @message_store.remove_pending(pending[:pending_message_id])
         @input_buffer.clear
         @input_buffer.insert(pending[:content])
-        @cable_client.recall_pending(pending[:id])
+        @cable_client.recall_pending(pending[:pending_message_id])
         true
       end
 
@@ -1071,6 +1268,12 @@ module TUI
         elsif event.down?
           scroll_down(SCROLL_STEP)
           true
+        elsif event.home?
+          scroll_up(@max_scroll)
+          true
+        elsif event.end?
+          scroll_down(@max_scroll)
+          true
         else
           false
         end

data/skills/activerecord/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: activerecord
-description: "Associations, validations, queries, migrations, eager loading. Activate when working with models, database schema, N+1 queries, scopes, includes/preload/eager_load, callbacks, or editing app/models/ or db/migrate/."
+description: "Associations, validations, queries, migrations, eager loading, N+1 queries, scopes, callbacks, app/models/, db/migrate/."
 ---
 
 # ActiveRecord

data/skills/dragonruby/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dragonruby
-description: "2D game development — game loops, sprites, input, collisions, scenes. Activate when building games with DRGTK, working with args.outputs/state/inputs, or editing game files."
+description: "2D game development — game loops, sprites, input, collisions, scenes, DRGTK, args.outputs/state/inputs."
 ---
 
 # DragonRuby Game Toolkit

data/skills/draper-decorators/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draper-decorators
-description: "Decorator patterns for Rails views — presentation logic separated from models. Activate when creating or testing decorators, moving formatting logic out of models/views, editing *_decorator.rb files, or working in app/decorators/."
+description: "Decorator patterns for Rails views — presentation logic separated from models, *_decorator.rb, app/decorators/."
 ---
 
 # Draper Decorators for Rails

data/skills/gh-issue.md

@@ -1,6 +1,6 @@
 ---
 name: gh-issue
-description: "Issue writing with WHAT/WHY/HOW framework. Activate when creating issues, writing tickets, drafting issue descriptions, or when issues lack clear rationale."
+description: "Issue writing with WHAT/WHY/HOW framework — tickets, bug reports, feature requests, issue descriptions, unclear rationale in existing issues."
 ---
 
 # GitHub Issue Writing

data/skills/mcp-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcp-server
-description: "Ruby server development — tools, prompts, resources, transport. Activate when building Model Context Protocol servers, defining MCP tools/prompts/resources, working with the mcp gem, or discussing LLM tool integrations."
+description: "Ruby MCP server development — tools, prompts, resources, transport, the mcp gem, LLM tool integrations."
 ---
 
 # MCP Ruby SDK - Server Development Guide

data/skills/ratatui-ruby/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ratatui-ruby
-description: "Terminal UI development — widgets, layouts, events, Tea MVU. Activate when building TUI apps, working with terminal rendering, or editing TUI application files."
+description: "Terminal UI development — widgets, layouts, events, Tea MVU, terminal rendering."
 ---
 
 # RatatuiRuby

data/skills/rspec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rspec
-description: "Testing with FactoryBot — matchers, test doubles, shared examples. Activate when writing specs, fixing failing tests, working with describe/it/expect blocks, editing *_spec.rb files, planning test strategy, or discussing unit/integration tests."
+description: "Testing with FactoryBot — matchers, test doubles, shared examples, describe/it/expect blocks, *_spec.rb files, test strategy."
 ---
 
 # RSpec Testing