anima-core 0.2.1 → 1.0.0

data/skills/gh-issue.md

@@ -0,0 +1,182 @@
+---
+name: gh-issue
+description: "GitHub issue writing with WHAT/WHY/HOW framework. Activate when user creates issues, writes tickets, drafts GitHub issues, or edits issue descriptions."
+---
+
+# GitHub Issue Writing
+
+Write GitHub issues with clear rationale using the WHAT/WHY/HOW framework. Every issue must answer three questions for the reader: What problem are we solving? Why does it matter? How will we solve it?
+
+## Issue Structure
+
+### Title
+
+Action-oriented, concise (under 70 characters).
+
+**Format:** `[Noun] [Action]` or `[Action] [Noun]`
+
+**Examples:**
+- "Assistant Model" (noun for foundational work)
+- "Twitter Banner Verification" (noun phrase for feature)
+- "Add story_context MCP tool" (action for specific implementation)
+
+### Body Template
+
+```markdown
+## Problem to solve
+[1-3 sentences: What gap, pain point, or need exists? Why can't we proceed without this?]
+
+## Solution
+[1-2 sentences: High-level approach to address the problem]
+
+## [Details Section - varies by issue type]
+[Fields, Routes, Flow, Requirements - whatever is relevant]
+
+## Why [decision]?
+[Explain non-obvious choices. Skip if decision is self-evident]
+```
+
+## The Three Questions
+
+### WHAT (Problem to solve)
+
+State the problem from user/system perspective, not implementation perspective.
+
+**Bad:** "We need to create an Assistant model with fields for name and API key."
+**Good:** "The platform needs a core identity for AI agents. Without this model, agents cannot register or interact with the platform."
+
+### WHY (Rationale)
+
+Explain decisions that aren't self-evident. Include "Why X?" sections for:
+- Architectural choices (Why separate models? Why MCP not REST?)
+- Technology decisions (Why Twitter? Why no password?)
+- Scope decisions (Why optional field? Why this validation?)
+
+Skip rationale for obvious decisions. Don't explain why a user model has an email field.
+
+### HOW (Solution details)
+
+Include enough detail to implement without ambiguity:
+- **Models:** Fields with types/constraints, associations, behaviors
+- **Endpoints:** Routes, request/response formats, logic
+- **Flows:** Step-by-step sequences with edge cases
+- **Validation:** Rules with specific constraints
+
+## Issue Types and Patterns
+
+### Model/Entity Issues
+
+```markdown
+## Problem to solve
+[Why this entity needs to exist in the system]
+
+## Solution
+Create `ModelName` model for [purpose].
+
+## Fields
+- `field_name` — description, constraints
+- `belongs_to :other` — relationship explanation
+
+## Behavior
+- [Key behaviors and state transitions]
+- [Validation rules]
+
+## Why [architectural decision]?
+[Explain non-obvious choices like STI vs separate models]
+```
+
+### Feature/Flow Issues
+
+```markdown
+## Problem to solve
+[User need or system requirement]
+
+## Solution
+[High-level approach]
+
+## Flow
+1. [Step with actor]
+2. [Step with system response]
+3. [Step with outcome]
+
+## Implementation Notes
+- [Technical details]
+- [Edge cases]
+
+## Why [approach]?
+[Rationale for chosen solution over alternatives]
+```
+
+### Research/Spike Issues
+
+```markdown
+## Problem to solve
+[What we don't know that blocks progress]
+
+## Research Questions
+- [ ] [Specific question to answer]
+- [ ] [Another question]
+
+## Context
+[What we already know, constraints]
+
+## Acceptance Criteria
+[What "done" looks like for research]
+```
+
+## Writing Guidelines
+
+### Be Specific
+
+**Bad:** "Handle edge cases"
+**Good:** "Handle: already verified, name not found, Twitter API timeout"
+
+### Use Concrete Examples
+
+**Bad:** "Name must be valid"
+**Good:** "Name must be URL-safe (alphanumeric, underscores, hyphens), 3-30 characters"
+
+### Show, Don't Just Tell
+
+Include code snippets for interfaces:
+
+```markdown
+## MCP Interface
+\`\`\`
+Tool: register_assistant
+Input: { name: "bonk" }
+Output: {
+  api_key: "oic_abc123...",
+  verification_url: "https://openinstaclaw.ai/bonk"
+}
+\`\`\`
+```
+
+## gh CLI Usage
+
+Create issues with proper formatting:
+
+```bash
+gh issue create \
+  --title "Assistant Model" \
+  --body "$(cat <<'EOF'
+## Problem to solve
+[Content here]
+
+## Solution
+[Content here]
+EOF
+)"
+```
+
+## Quality Checklist
+
+Before submitting an issue:
+
+- [ ] Title is action-oriented and under 70 characters
+- [ ] "Problem to solve" explains the need, not the implementation
+- [ ] Solution is stated at high level before diving into details
+- [ ] Non-obvious decisions have "Why X?" explanations
+- [ ] Implementation details are specific enough to code from
+- [ ] Edge cases and validation rules are explicit
+- [ ] Code examples included for interfaces/APIs

data/skills/mcp-server/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: mcp-server
+description: "MCP server development in Ruby — tools, prompts, resources, transport. Activate when building Model Context Protocol servers, defining tools/prompts/resources, working with the mcp gem, or discussing LLM tool integrations."
+---
+
+# MCP Ruby SDK - Server Development Guide
+
+Build Model Context Protocol servers in Ruby using the official `mcp` gem (maintained by Anthropic and Shopify).
+
+## Design Philosophy
+
+### Information Provider, Not Analyzer
+
+MCP servers provide structured data; LLMs do the reasoning. Return comprehensive frameworks and raw information—let the client perform analysis and context-dependent decisions.
+
+> "The MCP server's job is to be the world's best research assistant, not a competing analyst." — Matt Adams
+
+### Context Preservation
+
+Agents have limited context windows. Every byte returned that wasn't requested is a byte that could have held useful context. Treat context preservation as a first-class design constraint.
+
+**Principles:**
+- Never return data that wasn't explicitly requested
+- Mutations are quiet—return confirmations, not data dumps
+- Explicit over implicit—associations only when asked
+- Filter large datasets before returning (10,000 rows → 5 relevant rows)
+
+### Domain-Aligned Vocabulary
+
+Tools should speak the language of your domain, not database/CRUD terminology. Agents are collaborators in your domain process, not database clients.
+
+**Example:** A visual novel asset server uses `create_image`, `make_sprite`, `place_character`, `explore_variations`, `compare_images`—not `generate`, `remove_background`, `composite`, `batch_generate`, `get_diff`.
+
+### Tool Budget Management
+
+Too many tools overwhelm agents and increase costs. Design toolsets around clear use cases, not API endpoint mirrors.
+
+- Group related functionality intelligently
+- Use lazy loading for large tool sets (150K tokens → 2K via on-demand discovery)
+- Tool names ≤64 characters, descriptions narrow and unambiguous
+
+### Security: The Lethal Trifecta
+
+Three capabilities that, when combined, create vulnerabilities (Simon Willison):
+1. Access to private data
+2. Exposure to untrusted content
+3. External communication capabilities
+
+**Required:** Explicit user consent before tool invocation, clear UI showing exposed tools, alerts when tool descriptions change.
+
+## Domain Components
+
+| Component | Purpose | Reference |
+|-----------|---------|-----------|
+| **Tools** | Define callable functions with input/output schemas | [`references/tools.md`](references/tools.md) |
+| **Prompts** | Template-based message generators | [`references/prompts.md`](references/prompts.md) |
+| **Resources** | Static and dynamic file/data registration | [`references/resources.md`](references/resources.md) |
+| **Server** | Core server initialization and configuration | [`references/server.md`](references/server.md) |
+| **Transport** | STDIO and HTTP transport options | [`references/transport.md`](references/transport.md) |
+| **Gotchas** | Tricky behaviors and error handling | [`references/gotchas.md`](references/gotchas.md) |
+
+## Key Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| `MCP::Tool` | Base class for defining callable tools |
+| `MCP::Prompt` | Base class for prompt templates |
+| `MCP::Resource` | Static resource registration |
+| `MCP::ResourceTemplate` | Dynamic URI-based resources |
+| `server_context` | Request-scoped data passed to handlers |
+| `MCP::Tool::Response` | Structured tool return value |
+
+## Tool Definition Patterns
+
+| Pattern | Use Case |
+|---------|----------|
+| Class-based (`< MCP::Tool`) | Reusable tools with complex logic |
+| Block-based (`MCP::Tool.define`) | Inline, simple tools |
+| Dynamic (`server.define_tool`) | Runtime tool registration |
+
+## Transport Decision Tree
+
+```
+What environment?
+├── CLI tool / Local server
+│   └── Use STDIO transport
+└── Web server / Production
+    └── Need sessions and notifications?
+        ├── YES → Use Streamable HTTP (stateful)
+        └── NO → Use Streamable HTTP (stateless)
+```
+
+### Quick Comparison
+
+| Transport | Sessions | Notifications | Use For |
+|-----------|----------|---------------|---------|
+| STDIO | N/A | Yes | CLI tools, local dev |
+| HTTP (stateful) | Yes | Yes | Web apps, long-lived connections |
+| HTTP (stateless) | No | No | Simple request/response APIs |
+
+## Protocol Version Features
+
+| Feature | Minimum Version |
+|---------|-----------------|
+| `description` | 2025-11-25 |
+| `instructions` | 2025-03-26 |
+| `annotations` | 2025-03-26 |
+| `output_schema` | 2025-03-26 |
+
+## Best Practices
+
+### Do
+
+- Use `tool_name` for namespaced classes to avoid conflicts
+- Use `additionalProperties: false` for strict schema validation
+- Use mutex for shared state in HTTP transport (thread safety)
+- Return error responses for business errors (`Response.new([...], error: true)`)
+- Check protocol version before using newer features
+- Use `server_context` for request-scoped data (user_id, env)
+
+### Don't
+
+- Don't use `$ref` in schemas (raises ArgumentError, inline only)
+- Don't assume extra args are rejected (`additionalProperties` defaults to allowing extras)
+- Don't use `rpc.` prefix (reserved for protocol methods)
+- Don't send notifications in stateless mode (raises RuntimeError)
+- Don't rely on validation order (required args checked before JSON Schema)
+
+## Anti-Patterns Quick List
+
+| Anti-Pattern | Solution |
+|--------------|----------|
+| Missing `additionalProperties: false` | Add to schema for strict validation |
+| Using `$ref` in schemas | Inline all definitions |
+| Notifications in stateless mode | Use stateful transport or skip notifications |
+| Hardcoded server_context | Pass dynamically based on request |
+| Ignoring protocol version | Check version before using gated features |
+| Blocking in tool handlers | Use async patterns for long operations |
+
+## Key Points
+
+1. **Validation is multi-layered** - Required args checked first, then JSON Schema validation
+2. **Notifications are fire-and-forget** - Errors reported but don't propagate
+3. **Protocol version matters** - Features are gated by version
+4. **Server context is opt-in** - Detected from method signature (must include `server_context:` parameter)
+5. **Schemas are immutable** - Validated at class load time, not runtime
+
+## Additional Resources
+
+### Reference Files
+
+For detailed DSL syntax by domain:
+
+- **`references/tools.md`** - Tool definition, responses, schemas, annotations
+- **`references/prompts.md`** - Prompt definition, arguments, content types
+- **`references/resources.md`** - Resource registration, templates, read handlers
+- **`references/server.md`** - Server initialization, configuration, custom methods
+- **`references/transport.md`** - Transport config, protocol methods, sessions
+- **`references/gotchas.md`** - Tricky behaviors, error handling, edge cases
+
+### Example Files
+
+Working examples in `examples/`:
+
+- **`examples/stdio_server.rb`** - Complete STDIO server with tools, prompts, resources
+- **`examples/http_server.rb`** - HTTP server with Rack and logging
+- **`examples/rails_integration.rb`** - Rails controller, routes, and initializer
+- **`examples/file_manager_tool.rb`** - Sandboxed file operations with security patterns
+- **`examples/dynamic_tools.rb`** - Runtime tool registration with notifications
+- **`examples/http_client.rb`** - HTTP client connecting to MCP server
+- **`examples/streaming_client.rb`** - SSE streaming client for real-time notifications
+
+### External Links
+
+- [MCP Ruby SDK on GitHub](https://github.com/modelcontextprotocol/ruby-sdk)
+- [MCP Protocol Specification](https://modelcontextprotocol.io)
+- [RubyDoc API Reference](https://rubydoc.info/gems/mcp)

data/skills/mcp-server/examples/dynamic_tools.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Dynamic Tool Registration
+# Demonstrates: server.define_tool, notify_tools_list_changed, plugin pattern
+#
+# See: ../references/server.md, ../references/tools.md
+
+require "mcp"
+
+class PluginManager
+  def initialize(server)
+    @server = server
+  end
+
+  def load_plugin(name, &block)
+    @server.define_tool(
+      name: "plugin_#{name}",
+      description: "Plugin: #{name}",
+      input_schema: { properties: { input: { type: "string" } } }
+    ) do |input:, server_context:|
+      result = block.call(input, server_context)
+      MCP::Tool::Response.new([{ type: "text", text: result.to_s }])
+    end
+
+    @server.notify_tools_list_changed
+  end
+end
+
+# Usage
+server = MCP::Server.new(name: "plugin_server", tools: [])
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+manager = PluginManager.new(server)
+manager.load_plugin("uppercase") { |input, _| input.upcase }
+manager.load_plugin("reverse") { |input, _| input.reverse }

data/skills/mcp-server/examples/file_manager_tool.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# File Manager Tool with sandboxed operations
+# Demonstrates: Security patterns, annotations, error responses, tool_name
+#
+# See: ../references/tools.md, ../references/gotchas.md
+
+require "mcp"
+require "fileutils"
+
+class FileManagerTool < MCP::Tool
+  tool_name "file_manager"
+  description "Manages files in a sandboxed directory"
+
+  input_schema(
+    properties: {
+      action: { type: "string", enum: %w[read write list delete] },
+      path: { type: "string" },
+      content: { type: "string" }
+    },
+    required: %w[action path]
+  )
+
+  annotations(
+    destructive_hint: true,
+    idempotent_hint: false,
+    read_only_hint: false
+  )
+
+  SANDBOX_DIR = "/tmp/mcp_sandbox"
+
+  class << self
+    def call(action:, path:, content: nil, server_context: nil)
+      full_path = File.join(SANDBOX_DIR, path)
+
+      # Security: Ensure path is within sandbox
+      unless full_path.start_with?(SANDBOX_DIR)
+        return error_response("Path traversal not allowed")
+      end
+
+      case action
+      when "read"  then read_file(full_path)
+      when "write" then write_file(full_path, content)
+      when "list"  then list_directory(full_path)
+      when "delete" then delete_file(full_path)
+      else error_response("Unknown action: #{action}")
+      end
+    end
+
+    private
+
+    def read_file(path)
+      return error_response("File not found") unless File.exist?(path)
+
+      MCP::Tool::Response.new([{ type: "text", text: File.read(path) }])
+    end
+
+    def write_file(path, content)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+      MCP::Tool::Response.new([{ type: "text", text: "Written #{content.bytesize} bytes" }])
+    end
+
+    def list_directory(path)
+      return error_response("Directory not found") unless Dir.exist?(path)
+
+      files = Dir.entries(path).reject { |f| f.start_with?(".") }
+      MCP::Tool::Response.new(
+        [{ type: "text", text: files.join("\n") }],
+        structured_content: files
+      )
+    end
+
+    def delete_file(path)
+      return error_response("File not found") unless File.exist?(path)
+
+      File.delete(path)
+      MCP::Tool::Response.new([{ type: "text", text: "Deleted" }])
+    end
+
+    def error_response(message)
+      MCP::Tool::Response.new([{ type: "text", text: message }], error: true)
+    end
+  end
+end

data/skills/mcp-server/examples/http_client.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# HTTP Client Example
+# Demonstrates: MCP::Client, HTTP transport, tool/prompt discovery and invocation
+#
+# See: ../references/transport.md
+
+require "mcp"
+
+# Create HTTP transport
+http = MCP::Client::HTTP.new(
+  url: "http://localhost:9292",
+  headers: { "Authorization" => "Bearer token123" }
+)
+
+client = MCP::Client.new(transport: http)
+
+# List tools
+tools = client.tools
+puts "Available tools:"
+tools.each do |tool|
+  puts "  - #{tool.name}: #{tool.description}"
+end
+
+# Call a tool
+if (weather_tool = tools.find { |t| t.name == "weather" })
+  result = client.call_tool(
+    tool: weather_tool,
+    arguments: { location: "London", units: "celsius" }
+  )
+  puts "Weather: #{result.dig('result', 'content', 0, 'text')}"
+end
+
+# List prompts
+prompts = client.prompts
+prompts.each do |prompt|
+  puts "Prompt: #{prompt['name']}"
+end
+
+# Get a prompt
+if prompts.any?
+  prompt_result = client.get_prompt(
+    name: prompts.first["name"],
+    arguments: { code: "puts 'hello'" }
+  )
+  puts "Messages: #{prompt_result['messages'].length}"
+end

data/skills/mcp-server/examples/http_server.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# HTTP MCP Server with Rack
+# Demonstrates: StreamableHTTP transport, configuration, logging, output_schema
+#
+# See: ../references/transport.md, ../references/server.md, ../references/tools.md
+#
+# Run: ruby http_server.rb
+# Server starts on http://localhost:9292
+
+require "mcp"
+require "rack"
+require "rackup"
+require "json"
+require "logger"
+
+class WeatherTool < MCP::Tool
+  description "Gets weather for a location"
+  input_schema(
+    properties: {
+      location: { type: "string" },
+      units: { type: "string", enum: %w[celsius fahrenheit] }
+    },
+    required: ["location"]
+  )
+
+  output_schema(
+    properties: {
+      temperature: { type: "number" },
+      condition: { type: "string" }
+    },
+    required: %w[temperature condition]
+  )
+
+  annotations(read_only_hint: true, destructive_hint: false)
+
+  class << self
+    def call(location:, units: "celsius", server_context: nil)
+      # Simulate API call
+      data = { temperature: 22, condition: "sunny" }
+
+      MCP::Tool::Response.new(
+        [{ type: "text", text: data.to_json }],
+        structured_content: data
+      )
+    end
+  end
+end
+
+$logger = Logger.new($stdout)
+$logger.level = Logger::INFO
+
+config = MCP::Configuration.new(
+  protocol_version: "2025-11-25",
+  exception_reporter: ->(e, ctx) {
+    $logger.error("MCP Error: #{e.message}")
+    $logger.debug(ctx.inspect)
+  },
+  instrumentation_callback: ->(data) {
+    $logger.info("MCP: #{data[:method]} (#{data[:duration]}s)")
+  }
+)
+
+server = MCP::Server.new(
+  name: "weather_server",
+  version: "1.0.0",
+  description: "Weather information server",
+  tools: [WeatherTool],
+  configuration: config
+)
+
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(server)
+server.transport = transport
+
+app = proc do |env|
+  request = Rack::Request.new(env)
+
+  if request.post?
+    body = request.body.read
+    request.body.rewind
+    $logger.debug("Request: #{body}")
+  end
+
+  response = transport.handle_request(request)
+  $logger.debug("Response: #{response[2].first}") if response[2].respond_to?(:first)
+  response
+end
+
+rack_app = Rack::Builder.new do
+  use Rack::CommonLogger, $logger
+  use Rack::ShowExceptions
+  run app
+end
+
+puts "Starting MCP server on http://localhost:9292"
+Rackup::Handler.get("puma").run(rack_app, Port: 9292, Host: "localhost")