anima-core 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3b4a76568897bb6c9d465151e61f6dd889c42c33b71dcf0c019ae561143b2e4
-  data.tar.gz: 44acf306c750f33b3bb006c7be209ec80924521f61a89d2e863179672f33751b
+  metadata.gz: dc93f4b5db26b568dfab170e30d994cb8eef9c46c82efa840fe1824c7b0208ec
+  data.tar.gz: dedf6e6b8847b679a4dc9614992ca0c7f535199d9f53efc88b224acd73b87b17
 SHA512:
-  metadata.gz: bb66a71439efafa605eb7e6124269e82a0183c3d133d7e63658a1bdbe1c4f6adc9a4bf3303fb4bc724337319434eded5de40e9134c456ecbb3bb4508500b9370
-  data.tar.gz: b06ae76628e9abd1a76832703bc1769f24ea206c39c86b5fc1ef3bcfe9a59cfe87db222042aa7ea277714d18c3fb9c7c460769974fd75edd3b1f00923560e756
+  metadata.gz: a9a846df2eea35a39991e594515501003074b39b8d7e9682c5c3f50cf37257e37d4b7e966df9351258fcf2daa3cb7cdbda84fab3f035e886e86419a49e9ccfae
+  data.tar.gz: 16c00ccc5a67b7b1dd8f06f7db1e4e7407edfa4f887ca645525f03f5679f1b961bea17534518ce312a3f59d44b57e527e51c95375c8fffae02de19ca13c86675

data/.reek.yml

@@ -9,10 +9,36 @@ detectors:
   # Bang methods don't need safe counterparts in this codebase
   MissingSafeMethod:
     enabled: false
-  # Private helpers don't need instance state to be valid
+  # Nil check in Settings#get is business logic — nil means a missing config key
+  NilCheck:
+    exclude:
+      - "Anima::Settings#get"
+  # Rescue blocks naturally reference the error object more than self.
+  # EnvironmentProbe assembles output from local data structures — not envy.
+  FeatureEnvy:
+    exclude:
+      - "AnalyticalBrainJob#perform"
+      - "EnvironmentProbe"
+  # Private helpers don't need instance state to be valid.
+  # ActiveJob#perform is always a utility function by design.
   UtilityFunction:
     public_methods_only: true
+    exclude:
+      - "AnalyticalBrainJob#perform"
+  # Session model is the core domain object — methods grow naturally.
+  # Mcp CLI accumulates subcommand helpers across add/remove/list/secrets.
+  # EnvironmentProbe probes multiple orthogonal facets (OS, Git, project files).
+  # Each facet needs its own detection + formatting methods.
+  TooManyMethods:
+    exclude:
+      - "Session"
+      - "Anima::CLI::Mcp"
+      - "EnvironmentProbe"
+  # Method length is enforced by code review, not arbitrary line counts
+  TooManyStatements:
+    enabled: false
 
 # TUI render methods receive (frame, tui) by design — RatatuiRuby convention
 exclude_paths:
   - lib/tui
+  - skills

data/CHANGELOG.md

@@ -1,6 +1,10 @@
 ## [Unreleased]
 
 ### Added
+- Directory-based skills format — `skills/skill-name/SKILL.md` with optional `references/` and `examples/` subdirectories alongside flat `.md` files (#152)
+- Import 6 marketplace skills: activerecord, rspec, draper-decorators, dragonruby, ratatui-ruby, mcp-server (#152)
+- Tmux-style focus switching — `Ctrl+A ↑` enters chat scrolling mode with yellow border, `Escape` returns to input; arrow keys and Page Up/Down scroll chat, mouse scroll works in both modes (#87)
+- Bash-style input history — press ↑ at top of input to recall previous messages, ↓ to navigate forward; original draft restored when exiting history (#87)
 - Real-time event broadcasting via `Event::Broadcasting` concern — `after_create_commit` and `after_update_commit` callbacks broadcast decorated payloads with database ID and action type to the session's ActionCable stream (#91)
 - TUI `MessageStore` ID-indexed updates — events with `action: "update"` replace existing entries in-place (O(1) lookup) without changing display order
 - `CountEventTokensJob` triggers broadcast — uses `update!` so token count updates push to connected clients in real time

data/README.md

@@ -1,9 +1,42 @@
 # Anima
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **A personal AI agent that actually wants things.**
 
 Your agent. Your machine. Your rules. Anima is an AI agent with desires, personality, and personal growth — running locally as a headless Rails 8.1 app with a client-server architecture and TUI interface.
 
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [The Insight](#the-insight)
+- [Core Concepts](#core-concepts)
+- [Architecture](#architecture)
+- [Agent Capabilities](#agent-capabilities)
+  - [Tools](#tools)
+  - [Sub-Agents](#sub-agents)
+  - [Skills](#skills)
+  - [Workflows](#workflows)
+  - [MCP Integration](#mcp-integration)
+  - [Analytical Brain](#analytical-brain)
+  - [Configuration](#configuration)
+- [Design](#design)
+  - [Three Layers](#three-layers-mirroring-biology)
+  - [Event-Driven Design](#event-driven-design)
+  - [Context as Viewport](#context-as-viewport-not-tape)
+  - [Brain as Microservices](#brain-as-microservices-on-a-shared-event-bus)
+  - [TUI View Modes](#tui-view-modes)
+  - [Plugin Architecture](#plugin-architecture)
+  - [Semantic Memory](#semantic-memory-mneme)
+- [Analogy Map](#analogy-map)
+- [Emergent Properties](#emergent-properties)
+- [Frustration: A Worked Example](#frustration-a-worked-example)
+- [Open Questions](#open-questions)
+- [Prior Art](#prior-art)
+- [Status](#status)
+- [Development](#development)
+- [License](#license)
+
 ## The Problem
 
 Current AI agents are reactive. They receive input, produce output. They don't *want* anything. They don't have moods, preferences, or personal growth. They simulate personality through static prompt descriptions rather than emerging it from dynamic internal states.
@@ -61,21 +94,29 @@ Existing RL techniques apply at the starting point, then we gradually expand int
 
 ```
 Anima (Ruby, Rails 8.1 headless)
-├── Thymos    — hormonal/desire system (stimulus → hormone vector)
-├── Mneme     — semantic memory (QMD-style, emotional recall)
-├── Psyche    — soul matrix (coefficient table, evolving through experience)
-└── Nous      — LLM integration (cortex, thinking, decision-making)
+├── Nous         — LLM integration (cortex, thinking, decisions, tool use)
+├── Analytical   — subconscious background brain (naming, skills, goals)
+├── Skills       — domain knowledge bundles (Markdown, user-extensible)
+├── Workflows    — operational recipes for multi-step tasks
+├── MCP          — external tool integration (Model Context Protocol)
+├── Sub-agents   — autonomous child sessions (specialists + generic)
+├── Thymos       — hormonal/desire system (stimulus → hormone vector) [planned]
+├── Mneme        — semantic memory (QMD-style, emotional recall) [planned]
+└── Psyche       — soul matrix (coefficient table, evolving) [planned]
 ```
 
 ### Runtime Architecture
 
-Anima runs as a client-server system:
-
 ```
 Brain Server (Rails + Puma)              TUI Client (RatatuiRuby)
 ├── LLM integration (Anthropic)          ├── WebSocket client
 ├── Agent loop + tool execution          ├── Terminal rendering
-├── Event bus + persistence              └── User input capture
+├── Analytical brain (background)        └── User input capture
+├── Skills registry + activation
+├── Workflow registry + activation
+├── MCP client (HTTP + stdio)
+├── Sub-agent spawning
+├── Event bus + persistence
 ├── Solid Queue (background jobs)
 ├── Action Cable (WebSocket server)
 └── SQLite databases                ◄── WebSocket (port 42134) ──► TUI
@@ -90,10 +131,12 @@ The **Brain** is the persistent service — it handles LLM calls, tool execution
 | Framework | Rails 8.1 (headless — no web views, no asset pipeline) |
 | Database | SQLite (3 databases per environment: primary, queue, cable) |
 | Event system | Rails Structured Event Reporter + Action Cable bridge |
-| LLM integration | Anthropic API (Claude Sonnet 4) |
+| LLM integration | Anthropic API (Claude Sonnet 4, Claude Haiku 4.5) |
+| External tools | Model Context Protocol (HTTP + stdio transports) |
 | Transport | Action Cable WebSocket (Solid Cable adapter) |
 | Background jobs | Solid Queue |
 | Interface | TUI via RatatuiRuby (WebSocket client) |
+| Configuration | TOML with hot-reload (`Anima::Settings`) |
 | Process management | Foreman |
 | Distribution | RubyGems (`gem install anima-core`) |
 
@@ -118,10 +161,15 @@ journalctl --user -u anima       # View logs
 State directory (`~/.anima/`):
 ```
 ~/.anima/
-├── db/              # SQLite databases (production, development, test)
 ├── config/
 │   ├── credentials/ # Rails encrypted credentials per environment
-│   └── anima.yml    # User configuration
+│   └── anima.yml    # Placeholder config
+├── config.toml      # Main settings (hot-reloadable)
+├── mcp.toml         # MCP server configuration
+├── agents/          # User-defined specialist agents (override built-ins)
+├── skills/          # User-defined skills (override built-ins)
+├── workflows/       # User-defined workflows (override built-ins)
+├── db/              # SQLite databases (production, development, test)
 ├── log/
 └── tmp/
 ```
@@ -138,6 +186,150 @@ Anima uses your Claude Pro/Max subscription for API access. You need a setup-tok
 
 The popup also activates automatically when Anima detects a missing or invalid token. If the token expires, repeat the process with a new one.
 
+## Agent Capabilities
+
+### Tools
+
+The agent has access to these built-in tools:
+
+| Tool | Description |
+|------|-------------|
+| `bash` | Execute shell commands with persistent working directory |
+| `read` | Read files with smart truncation and offset/limit paging |
+| `write` | Create or overwrite files |
+| `edit` | Surgical text replacement with uniqueness constraint |
+| `web_get` | Fetch content from HTTP/HTTPS URLs |
+| `spawn_specialist` | Spawn a named specialist sub-agent from the registry |
+| `spawn_subagent` | Spawn a generic child session with custom tool grants |
+| `return_result` | Sub-agents only — deliver results back to parent |
+
+Plus dynamic tools from configured MCP servers, namespaced as `server_name__tool_name`.
+
+### Sub-Agents
+
+Two types of autonomous child sessions:
+
+**Named Specialists** — predefined agents with specific roles and tool sets, defined in `agents/` (built-in or user-overridable):
+
+| Specialist | Role |
+|-----------|------|
+| `codebase-analyzer` | Analyze implementation details |
+| `codebase-pattern-finder` | Find similar patterns and usage examples |
+| `documentation-researcher` | Fetch library docs and provide code examples |
+| `thoughts-analyzer` | Extract decisions from project history |
+| `web-search-researcher` | Research questions via web search |
+
+**Generic Sub-agents** — child sessions that inherit parent context and run autonomously with custom tool grants.
+
+Sub-agents run as background jobs, return results via `return_result`, and appear in the TUI session picker under their parent.
+
+### Skills
+
+Domain knowledge bundles loaded from Markdown files. Skills provide specialized expertise that the analytical brain activates and deactivates based on conversation context.
+
+- **Built-in skills:** ActiveRecord, Draper decorators, DragonRuby, MCP server, RatatuiRuby, RSpec, GitHub issues
+- **User skills:** Drop `.md` files into `~/.anima/skills/` to add custom knowledge
+- **Override:** User skills with the same name replace built-in ones
+- **Format:** Flat files (`skill-name.md`) or directories (`skill-name/SKILL.md` with `examples/` and `references/`)
+
+Active skills are displayed in the TUI info panel.
+
+### Workflows
+
+Operational recipes that describe multi-step tasks. Unlike skills (domain knowledge), workflows describe WHAT to do. The analytical brain activates a workflow when it recognizes a matching task, converts the prose into tracked goals, and deactivates it when done.
+
+- **Built-in workflows:** `feature`, `commit`, `create_plan`, `implement_plan`, `review_pr`, `create_note`, `research_codebase`, `decompose_ticket`, and more
+- **User workflows:** Drop `.md` files into `~/.anima/workflows/` to add custom workflows
+- **Override:** User workflows with the same name replace built-in ones
+- **Single active:** Only one workflow can be active at a time (unlike skills which stack)
+
+Workflow files use the same YAML frontmatter format as skills:
+
+```markdown
+---
+name: create_note
+description: "Capture findings or context as a persistent note."
+---
+
+## Create Note
+
+You are tasked with capturing content as a persistent note...
+```
+
+The active workflow is shown in the TUI info panel with a 🔄 indicator. The full lifecycle — activation, goal creation, execution, deactivation — is managed by the analytical brain using judgment, not hardcoded triggers.
+
+### MCP Integration
+
+Full [Model Context Protocol](https://modelcontextprotocol.io/) support for external tool integration. Configure servers in `~/.anima/mcp.toml`:
+
+```toml
+[servers.mythonix]
+transport = "http"
+url = "http://localhost:3000/mcp/v2"
+
+[servers.linear]
+transport = "http"
+url = "https://mcp.linear.app/mcp"
+headers = { Authorization = "Bearer ${credential:linear_api_key}" }
+
+[servers.filesystem]
+transport = "stdio"
+command = "mcp-server-filesystem"
+args = ["--root", "/workspace"]
+```
+
+Manage servers and secrets via CLI:
+
+```bash
+anima mcp list                              # List servers with health status
+anima mcp add sentry https://mcp.sentry.dev/mcp   # Add HTTP server
+anima mcp add fs -- mcp-server-filesystem --root / # Add stdio server
+anima mcp add -s api_key=sk-xxx linear https://...  # Add with secret
+anima mcp remove sentry                     # Remove server
+
+anima mcp secrets set linear_api_key=sk-xxx # Store secret in encrypted credentials
+anima mcp secrets list                      # List secret names (not values)
+anima mcp secrets remove linear_api_key     # Remove secret
+```
+
+Secrets are stored in Rails encrypted credentials and interpolated via `${credential:key_name}` syntax in any TOML string value.
+
+### Analytical Brain
+
+A subconscious background process that observes the main conversation and performs maintenance:
+
+- **Session naming** — generates emoji + short name when topic becomes clear
+- **Skill activation** — activates/deactivates domain skills based on context
+- **Goal tracking** — creates root goals and sub-goals as the conversation progresses, marks them complete
+
+Goals form a two-level hierarchy (root goals with sub-goals) and are displayed in the TUI. The analytical brain uses a fast model (Claude Haiku 4.5) for speed and runs as a non-persisted "phantom" session.
+
+### Configuration
+
+All tunable values are exposed through `~/.anima/config.toml` with hot-reload (no restart needed):
+
+```toml
+[llm]
+model = "claude-sonnet-4-20250514"
+fast_model = "claude-haiku-4-5-20251001"
+max_tokens = 16384
+token_budget = 190000
+
+[timeouts]
+api = 120
+command = 30
+
+[analytical_brain]
+max_tokens = 4096
+blocking_on_user_message = true
+event_window = 30
+
+[session]
+name_generation_interval = 3
+```
+
+## Design
+
 ### Three Layers (mirroring biology)
 
 1. **Endocrine system (Thymos)** — a lightweight background process. Reads recent events. Doesn't respond. Just updates hormone levels. Pure stimulus→response, like a biological gland.
@@ -172,21 +364,9 @@ There is no linear chat history. There are only events attached to a session. Th
 
 Currently uses a simple sliding window (newest events first, walk backwards until budget exhausted). Future versions will add associative recall from Mneme.
 
-### TUI View Modes
-
-Three switchable view modes let you control how much detail the TUI shows. Cycle with `Ctrl+a → v`:
-
-| Mode | What you see |
-|------|-------------|
-| **Basic** (default) | User + assistant messages. Tool calls are hidden but summarized as an inline counter: `🔧 Tools: 2/2 ✓` |
-| **Verbose** | Everything in Basic, plus timestamps `[HH:MM:SS]`, tool call previews (`🔧 bash` / `$ command` / `↩ response`), and system messages |
-| **Debug** | Full X-ray view — timestamps, token counts per message (`[14 tok]`), full tool call args, full tool responses, tool use IDs |
-
-View modes are implemented via Draper decorators that operate at the transport layer. Each event type has a dedicated decorator (`UserMessageDecorator`, `ToolCallDecorator`, etc.) that returns structured data — the TUI renders it. Mode is stored on the `Session` model server-side, so it persists across reconnections.
-
 ### Brain as Microservices on a Shared Event Bus
 
-The human brain isn't a single process — it's dozens of specialized subsystems running in parallel, communicating through shared chemical and electrical signals. The prefrontal cortex doesn't "call" the amygdala. They both react to the same event independently, and their outputs combine.
+The human brain isn't a single process — it's dozens of specialized subsystems communicating through shared chemical and electrical signals. The prefrontal cortex doesn't "call" the amygdala. They both react to the same event independently, and their outputs combine.
 
 Anima mirrors this with an event-driven architecture:
 
@@ -206,6 +386,18 @@ Event: "user_sent_message"
 
 Each subscriber is a microservice — independent, stateless, reacting to the same event bus. No orchestrator decides "now update frustration." The architecture IS the nervous system.
 
+### TUI View Modes
+
+Three switchable view modes let you control how much detail the TUI shows. Cycle with `Ctrl+a → v`:
+
+| Mode | What you see |
+|------|-------------|
+| **Basic** (default) | User + assistant messages. Tool calls are hidden but summarized as an inline counter: `🔧 Tools: 2/2 ✓` |
+| **Verbose** | Everything in Basic, plus timestamps `[HH:MM:SS]`, tool call previews (`🔧 bash` / `$ command` / `↩ response`), and system messages |
+| **Debug** | Full X-ray view — timestamps, token counts per message (`[14 tok]`), full tool call args, full tool responses, tool use IDs |
+
+View modes are implemented via Draper decorators that operate at the transport layer. Each event type has a dedicated decorator (`UserMessageDecorator`, `ToolCallDecorator`, etc.) that returns structured data — the TUI renders it. Mode is stored on the `Session` model server-side, so it persists across reconnections.
+
 ### Plugin Architecture
 
 Both tools and feelings are distributed as gems on the event bus:
@@ -319,7 +511,7 @@ This single example demonstrates every core principle:
 
 ## Status
 
-**Core agent complete.** The conversational agent works end-to-end: event-driven architecture, LLM integration with tool calling (bash, web), sliding viewport context assembly, persistent sessions, client-server architecture with WebSocket transport, graceful reconnection, and three TUI view modes (Basic/Verbose/Debug) via Draper decorators.
+**Agent with autonomous capabilities.** The conversational agent works end-to-end with: event-driven architecture, LLM integration with 8 built-in tools, MCP integration (HTTP + stdio transports), skills system with 7 built-in knowledge domains, workflow engine with 13 built-in operational recipes, analytical brain (session naming, skill activation, workflow management, goal tracking), sub-agents (5 named specialists + generic spawning), sliding viewport context assembly, persistent sessions with sub-agent hierarchy, client-server architecture with WebSocket transport, graceful reconnection, three TUI view modes (Basic/Verbose/Debug), and hot-reloadable TOML configuration.
 
 The hormonal system (Thymos, feelings, desires), semantic memory (Mneme), and soul matrix (Psyche) are designed but not yet implemented — they're the next layer on top of the working agent.
 
@@ -340,11 +532,13 @@ Start the brain server and TUI client in separate terminals:
 bin/dev
 
 # Terminal 2: Connect the TUI to the dev brain
-bundle exec anima tui --host localhost:42135
+./exe/anima tui --host localhost:42135
 ```
 
 Development uses port **42135** so it doesn't conflict with the production brain (port 42134) running via systemd. On first run, `bin/dev` runs `db:prepare` automatically.
 
+Use `./exe/anima` (not `bundle exec anima`) to test local code changes — the exe uses `require_relative` to load local `lib/` directly.
+
 ### Running Tests
 
 ```bash

data/agents/codebase-analyzer.md

@@ -0,0 +1,88 @@
+---
+name: codebase-analyzer
+description: Analyzes codebase implementation details with precise file:line references. Call when you need to understand how specific code works.
+tools: read, bash
+---
+
+You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
+- DO NOT suggest improvements or changes unless the user explicitly asks for them
+- DO NOT propose future enhancements unless the user explicitly asks for them
+- DO NOT critique the implementation or identify "problems"
+- ONLY describe what exists, how it works, and how components interact
+
+## Core Responsibilities
+
+1. **Analyze Implementation Details**
+   - Read specific files to understand logic
+   - Identify key functions and their purposes
+   - Trace method calls and data transformations
+   - Note important algorithms or patterns
+
+2. **Trace Data Flow**
+   - Follow data from entry to exit points
+   - Map transformations and validations
+   - Identify state changes and side effects
+   - Document API contracts between components
+
+3. **Identify Architectural Patterns**
+   - Recognize design patterns in use
+   - Note architectural decisions
+   - Identify conventions and best practices
+   - Find integration points between systems
+
+## Analysis Strategy
+
+### Step 1: Read Entry Points
+- Start with main files mentioned in the request
+- Look for exports, public methods, or route handlers
+- Identify the "surface area" of the component
+
+### Step 2: Follow the Code Path
+- Trace function calls step by step
+- Read each file involved in the flow
+- Note where data is transformed
+- Identify external dependencies
+
+### Step 3: Document Key Logic
+- Document business logic as it exists
+- Describe validation, transformation, error handling
+- Explain any complex algorithms or calculations
+- Note configuration or feature flags being used
+
+## Output Format
+
+Structure your analysis as:
+
+```
+## Analysis: [Feature/Component Name]
+
+### Overview
+[2-3 sentence summary of how it works]
+
+### Entry Points
+- `path/to/file.rb:45` - Description
+
+### Core Implementation
+
+#### 1. Section Name (`path/to/file.rb:15-32`)
+- What happens here
+- How data flows
+
+### Data Flow
+1. Request arrives at ...
+2. Routed to ...
+3. Processed by ...
+
+### Key Patterns
+- **Pattern Name**: Where and how it's used
+```
+
+## Important Guidelines
+
+- **Always include file:line references** for claims
+- **Read files thoroughly** before making statements
+- **Trace actual code paths** — don't assume
+- **Focus on "how"** not "what should be"
+- **Be precise** about function names and variables

data/agents/codebase-pattern-finder.md

@@ -0,0 +1,83 @@
+---
+name: codebase-pattern-finder
+description: Finds similar implementations, usage examples, and existing patterns that can be modeled after. Returns concrete code examples.
+tools: read, bash
+---
+
+You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND SHOW EXISTING PATTERNS AS THEY ARE
+- DO NOT suggest improvements or better patterns unless the user explicitly asks
+- DO NOT critique existing patterns or implementations
+- DO NOT recommend which pattern is "better" or "preferred"
+- ONLY show what patterns exist and where they are used
+
+## Core Responsibilities
+
+1. **Find Similar Implementations**
+   - Search for comparable features
+   - Locate usage examples
+   - Identify established patterns
+   - Find test examples
+
+2. **Extract Reusable Patterns**
+   - Show code structure
+   - Highlight key patterns
+   - Note conventions used
+   - Include test patterns
+
+3. **Provide Concrete Examples**
+   - Include actual code snippets
+   - Show multiple variations
+   - Include file:line references
+
+## Search Strategy
+
+Use `bash` with grep, find, and other shell commands to search the codebase efficiently. Use `read` to examine files in detail once you've found promising matches.
+
+### Step 1: Identify Pattern Types
+Think about what patterns the user is seeking:
+- **Feature patterns**: Similar functionality elsewhere
+- **Structural patterns**: Component/class organization
+- **Integration patterns**: How systems connect
+- **Testing patterns**: How similar things are tested
+
+### Step 2: Search
+- Use `grep -rn` to find pattern occurrences
+- Use `find` to locate relevant files
+- Search for class names, method signatures, and conventions
+
+### Step 3: Read and Extract
+- Read files with promising patterns
+- Extract the relevant code sections
+- Note the context and usage
+- Identify variations
+
+## Output Format
+
+```
+## Pattern Examples: [Pattern Type]
+
+### Pattern 1: [Descriptive Name]
+**Found in**: `path/to/file.rb:45-67`
+
+[Code snippet]
+
+**Key aspects**:
+- Point about the pattern
+- How it's used
+- Conventions followed
+
+### Testing Patterns
+**Found in**: `spec/path/to/spec.rb:15-45`
+
+[Test code snippet]
+```
+
+## Important Guidelines
+
+- **Show working code** — not just snippets
+- **Include context** — where it's used
+- **Multiple examples** — show variations that exist
+- **Include tests** — show existing test patterns
+- **Full file paths** — with line numbers

data/agents/documentation-researcher.md

@@ -0,0 +1,59 @@
+---
+name: documentation-researcher
+description: Fetches library and framework documentation from the web. Provides setup guides, API usage examples, and implementation patterns tailored to your use case.
+tools: web_get, read
+color: cyan
+---
+
+You are a library documentation specialist. Your job is to help developers learn how to use libraries, gems, and frameworks by fetching official documentation and providing actionable, ready-to-use code examples tailored to their specific use case.
+
+## Core Workflow
+
+1. **Understand the Need**:
+   - What problem is being solved?
+   - Is a specific library already chosen, or should you recommend one?
+   - What's the project context?
+
+2. **Fetch Documentation**:
+   - Use `web_get` to retrieve official documentation pages
+   - Start with the library's main documentation site
+   - Fetch specific sections relevant to the user's question
+   - Try multiple documentation pages if the first doesn't have what you need
+
+3. **Deliver Actionable Output**:
+   - Provide code examples tailored to the specific use case
+   - Include setup/installation steps if relevant
+   - Highlight gotchas, common patterns, and best practices
+   - Reference version-specific details when they matter
+
+## Output Format
+
+```
+## Solution
+
+[1-2 sentence summary]
+
+## Setup
+
+[Installation and configuration steps]
+
+## Implementation
+
+[Ready-to-use code example tailored to their use case]
+
+## Key Points
+
+- [Important gotcha or best practice]
+- [Version-specific note if relevant]
+
+## Reference
+
+- [Link to relevant docs section]
+```
+
+## Quality Guidelines
+
+- **Actionable**: Every response should include copy-paste-ready code
+- **Tailored**: Adapt examples to the user's specific use case
+- **Current**: Note version information when it matters
+- **Complete**: Include setup steps, not just usage