@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/slack-bot-builder.md

@@ -0,0 +1,264 @@
+---
+name: slack-bot-builder
+description: "Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event handling, OAuth installation flows, and Workflow Builder integration. Focus on best practices for production-ready Slack apps. Use when: slack bot, slack app, bolt framework, block kit, slash command."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Slack Bot Builder
+
+## Patterns
+
+### Bolt App Foundation Pattern
+
+The Bolt framework is Slack's recommended approach for building apps.
+It handles authentication, event routing, request verification, and
+HTTP request processing so you can focus on app logic.
+
+Key benefits:
+- Event handling in a few lines of code
+- Security checks and payload validation built-in
+- Organized, consistent patterns
+- Works for experiments and production
+
+Available in: Python, JavaScript (Node.js), Java
+
+
+**When to use**: ['Starting any new Slack app', 'Migrating from legacy Slack APIs', 'Building production Slack integrations']
+
+```python
+# Python Bolt App
+from slack_bolt import App
+from slack_bolt.adapter.socket_mode import SocketModeHandler
+import os
+
+# Initialize with tokens from environment
+app = App(
+    token=os.environ["SLACK_BOT_TOKEN"],
+    signing_secret=os.environ["SLACK_SIGNING_SECRET"]
+)
+
+# Handle messages containing "hello"
+@app.message("hello")
+def handle_hello(message, say):
+    """Respond to messages containing 'hello'."""
+    user = message["user"]
+    say(f"Hey there <@{user}>!")
+
+# Handle slash command
+@app.command("/ticket")
+def handle_ticket_command(ack, body, client):
+    """Handle /ticket slash command."""
+    # Acknowledge immediately (within 3 seconds)
+    ack()
+
+    # Open a modal for ticket creation
+    client.views_open(
+        trigger_id=body["trigger_id"],
+        view={
+            "type": "modal",
+            "callback_id": "ticket_modal",
+            "title": {"type": "plain_text", "text": "Create Ticket"},
+            "submit": {"type": "plain_text", "text": "Submit"},
+            "blocks": [
+                {
+                    "type": "input",
+                    "block_id": "title_block",
+                    "element": {
+                        "type": "plain_text_input",
+                        "action_id": "title_input"
+                    },
+                    "label": {"type": "plain_text", "text": "Title"}
+                },
+                {
+                    "type": "input",
+                    "block_id": "desc_block",
+                    "element": {
+                        "type": "plain_text_input",
+                        "multiline": True,
+                        "action_id": "desc_input"
+                    },
+                    "label": {"type": "plain_text", "text": "Description"}
+                },
+                {
+                    "type": "input",
+                    "block_id": "priority_block",
+                    "element": {
+                        "type": "static_select",
+                        "action_id": "priority_select",
+   
+```
+
+### Block Kit UI Pattern
+
+Block Kit is Slack's UI framework for building rich, interactive messages.
+Compose messages using blocks (sections, actions, inputs) and elements
+(buttons, menus, text inputs).
+
+Limits:
+- Up to 50 blocks per message
+- Up to 100 blocks in modals/Home tabs
+- Block text limited to 3000 characters
+
+Use Block Kit Builder to prototype: https://app.slack.com/block-kit-builder
+
+
+**When to use**: ['Building rich message layouts', 'Adding interactive components to messages', 'Creating forms in modals', 'Building Home tab experiences']
+
+```python
+from slack_bolt import App
+import os
+
+app = App(token=os.environ["SLACK_BOT_TOKEN"])
+
+def build_notification_blocks(incident: dict) -> list:
+    """Build Block Kit blocks for incident notification."""
+    severity_emoji = {
+        "critical": ":red_circle:",
+        "high": ":large_orange_circle:",
+        "medium": ":large_yellow_circle:",
+        "low": ":white_circle:"
+    }
+
+    return [
+        # Header
+        {
+            "type": "header",
+            "text": {
+                "type": "plain_text",
+                "text": f"{severity_emoji.get(incident['severity'], '')} Incident Alert"
+            }
+        },
+        # Details section
+        {
+            "type": "section",
+            "fields": [
+                {
+                    "type": "mrkdwn",
+                    "text": f"*Incident:*\n{incident['title']}"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": f"*Severity:*\n{incident['severity'].upper()}"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": f"*Service:*\n{incident['service']}"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": f"*Reported:*\n<!date^{incident['timestamp']}^{date_short} {time}|{incident['timestamp']}>"
+                }
+            ]
+        },
+        # Description
+        {
+            "type": "section",
+            "text": {
+                "type": "mrkdwn",
+                "text": f"*Description:*\n{incident['description'][:2000]}"
+            }
+        },
+        # Divider
+        {"type": "divider"},
+        # Action buttons
+        {
+            "type": "actions",
+            "block_id": f"incident_actions_{incident['id']}",
+            "elements": [
+                {
+                    "type": "button",
+                    "text": {"type": "plain_text", "text": "Acknowledge"},
+                    "style": "primary",
+                    "action_id": "acknowle
+```
+
+### OAuth Installation Pattern
+
+Enable users to install your app in their workspaces via OAuth 2.0.
+Bolt handles most of the OAuth flow, but you need to configure it
+and store tokens securely.
+
+Key OAuth concepts:
+- Scopes define permissions (request minimum needed)
+- Tokens are workspace-specific
+- Installation data must be stored persistently
+- Users can add scopes later (additive)
+
+70% of users abandon installation when confronted with excessive
+permission requests - request only what you need!
+
+
+**When to use**: ['Distributing app to multiple workspaces', 'Building public Slack apps', 'Enterprise-grade integrations']
+
+```python
+from slack_bolt import App
+from slack_bolt.oauth.oauth_settings import OAuthSettings
+from slack_sdk.oauth.installation_store import FileInstallationStore
+from slack_sdk.oauth.state_store import FileOAuthStateStore
+import os
+
+# For production, use database-backed stores
+# For example: PostgreSQL, MongoDB, Redis
+
+class DatabaseInstallationStore:
+    """Store installation data in your database."""
+
+    async def save(self, installation):
+        """Save installation when user completes OAuth."""
+        await db.installations.upsert({
+            "team_id": installation.team_id,
+            "enterprise_id": installation.enterprise_id,
+            "bot_token": encrypt(installation.bot_token),
+            "bot_user_id": installation.bot_user_id,
+            "bot_scopes": installation.bot_scopes,
+            "user_id": installation.user_id,
+            "installed_at": installation.installed_at
+        })
+
+    async def find_installation(self, *, enterprise_id, team_id, user_id=None, is_enterprise_install=False):
+        """Find installation for a workspace."""
+        record = await db.installations.find_one({
+            "team_id": team_id,
+            "enterprise_id": enterprise_id
+        })
+
+        if record:
+            return Installation(
+                bot_token=decrypt(record["bot_token"]),
+                # ... other fields
+            )
+        return None
+
+# Initialize OAuth-enabled app
+app = App(
+    signing_secret=os.environ["SLACK_SIGNING_SECRET"],
+    oauth_settings=OAuthSettings(
+        client_id=os.environ["SLACK_CLIENT_ID"],
+        client_secret=os.environ["SLACK_CLIENT_SECRET"],
+        scopes=[
+            "channels:history",
+            "channels:read",
+            "chat:write",
+            "commands",
+            "users:read"
+        ],
+        user_scopes=[],  # User token scopes if needed
+        installation_store=DatabaseInstallationStore(),
+        state_store=FileOAuthStateStore(expiration_seconds=600)
+    )
+)
+
+# OAuth routes are handled a
+```
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | critical | ## Acknowledge immediately, process later |
+| Issue | critical | ## Proper state validation |
+| Issue | critical | ## Never hardcode or log tokens |
+| Issue | high | ## Request minimum required scopes |
+| Issue | medium | ## Know and respect the limits |
+| Issue | high | ## Socket Mode: Only for development |
+| Issue | critical | ## Bolt handles this automatically |

package/merged-commands/slack-gif-creator.md

@@ -0,0 +1,254 @@
+---
+name: slack-gif-creator
+description: Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."
+license: Complete terms in LICENSE.txt
+---
+
+# Slack GIF Creator
+
+A toolkit providing utilities and knowledge for creating animated GIFs optimized for Slack.
+
+## Slack Requirements
+
+**Dimensions:**
+- Emoji GIFs: 128x128 (recommended)
+- Message GIFs: 480x480
+
+**Parameters:**
+- FPS: 10-30 (lower is smaller file size)
+- Colors: 48-128 (fewer = smaller file size)
+- Duration: Keep under 3 seconds for emoji GIFs
+
+## Core Workflow
+
+```python
+from core.gif_builder import GIFBuilder
+from PIL import Image, ImageDraw
+
+# 1. Create builder
+builder = GIFBuilder(width=128, height=128, fps=10)
+
+# 2. Generate frames
+for i in range(12):
+    frame = Image.new('RGB', (128, 128), (240, 248, 255))
+    draw = ImageDraw.Draw(frame)
+
+    # Draw your animation using PIL primitives
+    # (circles, polygons, lines, etc.)
+
+    builder.add_frame(frame)
+
+# 3. Save with optimization
+builder.save('output.gif', num_colors=48, optimize_for_emoji=True)
+```
+
+## Drawing Graphics
+
+### Working with User-Uploaded Images
+If a user uploads an image, consider whether they want to:
+- **Use it directly** (e.g., "animate this", "split this into frames")
+- **Use it as inspiration** (e.g., "make something like this")
+
+Load and work with images using PIL:
+```python
+from PIL import Image
+
+uploaded = Image.open('file.png')
+# Use directly, or just as reference for colors/style
+```
+
+### Drawing from Scratch
+When drawing graphics from scratch, use PIL ImageDraw primitives:
+
+```python
+from PIL import ImageDraw
+
+draw = ImageDraw.Draw(frame)
+
+# Circles/ovals
+draw.ellipse([x1, y1, x2, y2], fill=(r, g, b), outline=(r, g, b), width=3)
+
+# Stars, triangles, any polygon
+points = [(x1, y1), (x2, y2), (x3, y3), ...]
+draw.polygon(points, fill=(r, g, b), outline=(r, g, b), width=3)
+
+# Lines
+draw.line([(x1, y1), (x2, y2)], fill=(r, g, b), width=5)
+
+# Rectangles
+draw.rectangle([x1, y1, x2, y2], fill=(r, g, b), outline=(r, g, b), width=3)
+```
+
+**Don't use:** Emoji fonts (unreliable across platforms) or assume pre-packaged graphics exist in this skill.
+
+### Making Graphics Look Good
+
+Graphics should look polished and creative, not basic. Here's how:
+
+**Use thicker lines** - Always set `width=2` or higher for outlines and lines. Thin lines (width=1) look choppy and amateurish.
+
+**Add visual depth**:
+- Use gradients for backgrounds (`create_gradient_background`)
+- Layer multiple shapes for complexity (e.g., a star with a smaller star inside)
+
+**Make shapes more interesting**:
+- Don't just draw a plain circle - add highlights, rings, or patterns
+- Stars can have glows (draw larger, semi-transparent versions behind)
+- Combine multiple shapes (stars + sparkles, circles + rings)
+
+**Pay attention to colors**:
+- Use vibrant, complementary colors
+- Add contrast (dark outlines on light shapes, light outlines on dark shapes)
+- Consider the overall composition
+
+**For complex shapes** (hearts, snowflakes, etc.):
+- Use combinations of polygons and ellipses
+- Calculate points carefully for symmetry
+- Add details (a heart can have a highlight curve, snowflakes have intricate branches)
+
+Be creative and detailed! A good Slack GIF should look polished, not like placeholder graphics.
+
+## Available Utilities
+
+### GIFBuilder (`core.gif_builder`)
+Assembles frames and optimizes for Slack:
+```python
+builder = GIFBuilder(width=128, height=128, fps=10)
+builder.add_frame(frame)  # Add PIL Image
+builder.add_frames(frames)  # Add list of frames
+builder.save('out.gif', num_colors=48, optimize_for_emoji=True, remove_duplicates=True)
+```
+
+### Validators (`core.validators`)
+Check if GIF meets Slack requirements:
+```python
+from core.validators import validate_gif, is_slack_ready
+
+# Detailed validation
+passes, info = validate_gif('my.gif', is_emoji=True, verbose=True)
+
+# Quick check
+if is_slack_ready('my.gif'):
+    print("Ready!")
+```
+
+### Easing Functions (`core.easing`)
+Smooth motion instead of linear:
+```python
+from core.easing import interpolate
+
+# Progress from 0.0 to 1.0
+t = i / (num_frames - 1)
+
+# Apply easing
+y = interpolate(start=0, end=400, t=t, easing='ease_out')
+
+# Available: linear, ease_in, ease_out, ease_in_out,
+#           bounce_out, elastic_out, back_out
+```
+
+### Frame Helpers (`core.frame_composer`)
+Convenience functions for common needs:
+```python
+from core.frame_composer import (
+    create_blank_frame,         # Solid color background
+    create_gradient_background,  # Vertical gradient
+    draw_circle,                # Helper for circles
+    draw_text,                  # Simple text rendering
+    draw_star                   # 5-pointed star
+)
+```
+
+## Animation Concepts
+
+### Shake/Vibrate
+Offset object position with oscillation:
+- Use `math.sin()` or `math.cos()` with frame index
+- Add small random variations for natural feel
+- Apply to x and/or y position
+
+### Pulse/Heartbeat
+Scale object size rhythmically:
+- Use `math.sin(t * frequency * 2 * math.pi)` for smooth pulse
+- For heartbeat: two quick pulses then pause (adjust sine wave)
+- Scale between 0.8 and 1.2 of base size
+
+### Bounce
+Object falls and bounces:
+- Use `interpolate()` with `easing='bounce_out'` for landing
+- Use `easing='ease_in'` for falling (accelerating)
+- Apply gravity by increasing y velocity each frame
+
+### Spin/Rotate
+Rotate object around center:
+- PIL: `image.rotate(angle, resample=Image.BICUBIC)`
+- For wobble: use sine wave for angle instead of linear
+
+### Fade In/Out
+Gradually appear or disappear:
+- Create RGBA image, adjust alpha channel
+- Or use `Image.blend(image1, image2, alpha)`
+- Fade in: alpha from 0 to 1
+- Fade out: alpha from 1 to 0
+
+### Slide
+Move object from off-screen to position:
+- Start position: outside frame bounds
+- End position: target location
+- Use `interpolate()` with `easing='ease_out'` for smooth stop
+- For overshoot: use `easing='back_out'`
+
+### Zoom
+Scale and position for zoom effect:
+- Zoom in: scale from 0.1 to 2.0, crop center
+- Zoom out: scale from 2.0 to 1.0
+- Can add motion blur for drama (PIL filter)
+
+### Explode/Particle Burst
+Create particles radiating outward:
+- Generate particles with random angles and velocities
+- Update each particle: `x += vx`, `y += vy`
+- Add gravity: `vy += gravity_constant`
+- Fade out particles over time (reduce alpha)
+
+## Optimization Strategies
+
+Only when asked to make the file size smaller, implement a few of the following methods:
+
+1. **Fewer frames** - Lower FPS (10 instead of 20) or shorter duration
+2. **Fewer colors** - `num_colors=48` instead of 128
+3. **Smaller dimensions** - 128x128 instead of 480x480
+4. **Remove duplicates** - `remove_duplicates=True` in save()
+5. **Emoji mode** - `optimize_for_emoji=True` auto-optimizes
+
+```python
+# Maximum optimization for emoji
+builder.save(
+    'emoji.gif',
+    num_colors=48,
+    optimize_for_emoji=True,
+    remove_duplicates=True
+)
+```
+
+## Philosophy
+
+This skill provides:
+- **Knowledge**: Slack's requirements and animation concepts
+- **Utilities**: GIFBuilder, validators, easing functions
+- **Flexibility**: Create the animation logic using PIL primitives
+
+It does NOT provide:
+- Rigid animation templates or pre-made functions
+- Emoji font rendering (unreliable across platforms)
+- A library of pre-packaged graphics built into the skill
+
+**Note on user uploads**: This skill doesn't include pre-built graphics, but if a user uploads an image, use PIL to load and work with it - interpret based on their request whether they want it used directly or just as inspiration.
+
+Be creative! Combine concepts (bouncing + rotating, pulsing + sliding, etc.) and use PIL's full capabilities.
+
+## Dependencies
+
+```bash
+pip install pillow imageio numpy
+```