agent-context 0.0.1 → 0.1.0

data/lib/agent/context/installer.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "rubygems"
+require "fileutils"
+require "pathname"
+require "yaml"
+
+module Agent
+	module Context
+		# Installer class for managing context files from Ruby gems.
+		# 
+		# This class provides methods to find, list, show, and install context files
+		# from gems that provide them in a `context/` directory.
+		class Installer
+			CANONICAL_ORDER = [
+				"getting-started",
+				"overview",
+				"usage",
+				"configuration",
+				"migration",
+				"troubleshooting",
+				"debugging"
+			]
+
+			# Initialize a new Helper instance.
+			#
+			# @parameter root [String] The root directory to work from (default: current directory).
+			# @parameter specifications [Gem::Specification] The gem specifications to search (default: all installed gems).
+			def initialize(root: Dir.pwd, specifications: ::Gem::Specification)
+				@root = root
+				@context_path = ".context"
+				@specifications = specifications
+			end
+			
+			attr_reader :context_path
+				
+			# Find all gems that have a context directory
+			def find_gems_with_context(skip_local: true)
+				gems_with_context = []
+					
+				@specifications.each do |spec|
+					# Skip gems loaded from current working directory if requested:
+					next if skip_local && spec.full_gem_path == @root
+					
+					context_path = File.join(spec.full_gem_path, "context")
+					if Dir.exist?(context_path)
+						gems_with_context << {
+							name: spec.name,
+							version: spec.version.to_s,
+							summary: spec.summary,
+							metadata: spec.metadata,
+							path: context_path
+						}
+					end
+				end
+					
+				gems_with_context
+			end
+				
+			# Find a specific gem with context.
+			def find_gem_with_context(gem_name)
+				spec = @specifications.find { |s| s.name == gem_name }
+				return nil unless spec
+					
+				context_path = File.join(spec.full_gem_path, "context")
+					
+				if Dir.exist?(context_path)
+					{
+							name: spec.name,
+							version: spec.version.to_s,
+							summary: spec.summary,
+							metadata: spec.metadata,
+							path: context_path
+						}
+				else
+					nil
+				end
+			end
+				
+			# List context files for a gem.
+			def list_context_files(gem_name)
+				gem = find_gem_with_context(gem_name)
+				return nil unless gem
+					
+				Dir.glob(File.join(gem[:path], "**/*")).select { |f| File.file?(f) }
+			end
+				
+			# Show content of a specific context file.
+			def show_context_file(gem_name, file_name)
+				gem = find_gem_with_context(gem_name)
+				return nil unless gem
+					
+				# Try to find the file with or without extension:
+				possible_paths = [
+						File.join(gem[:path], file_name),
+						File.join(gem[:path], "#{file_name}.md"),
+						File.join(gem[:path], "#{file_name}.md")
+					]
+					
+				file_path = possible_paths.find { |path| File.exist?(path) }
+				return nil unless file_path
+					
+				File.read(file_path)
+			end
+				
+			# Install context from a specific gem.
+			def install_gem_context(gem_name)
+				gem = find_gem_with_context(gem_name)
+				return false unless gem
+				
+				target_path = File.join(@context_path, gem_name)
+				
+				# Remove old package directory if it exists to ensure clean install
+				FileUtils.rm_rf(target_path) if Dir.exist?(target_path)
+				
+				FileUtils.mkdir_p(target_path)
+				
+				# Copy all files from the gem's context directory:
+				FileUtils.cp_r(File.join(gem[:path], "."), target_path)
+				
+				# Generate index.yaml if it doesn't exist, passing the full gem hash
+				ensure_gem_index(gem, target_path)
+				
+				true
+			end
+				
+			# Install context from all gems.
+			def install_all_context(skip_local: true)
+				gems = find_gems_with_context(skip_local: skip_local)
+				installed = []
+					
+				gems.each do |gem|
+					if install_gem_context(gem[:name])
+						installed << gem[:name]
+					end
+				end
+					
+				installed
+			end
+			
+			private
+			
+			# Generate a dynamic index from gemspec when no index.yaml is present
+			def generate_dynamic_index(gem, gem_directory)
+				# Collect all markdown files
+				markdown_files = Dir.glob(File.join(gem_directory, "**", "*.md")).sort
+				
+				# Sort files: canonical first, then alpha
+				files_sorted = markdown_files.sort_by do |file_path|
+					base_filename = File.basename(file_path, ".md").downcase
+					canonical_index = CANONICAL_ORDER.index(base_filename)
+					[canonical_index ? CANONICAL_ORDER.index(base_filename) : CANONICAL_ORDER.length, base_filename]
+				end
+				
+				files = []
+				files_sorted.each do |file_path|
+					next if File.basename(file_path) == "index.yaml" # Skip the index file itself
+					title, description = extract_content(file_path)
+					relative_path = file_path.sub("#{gem_directory}/", "")
+					files << {
+						"path" => relative_path,
+						"title" => title,
+						"description" => description
+					}
+				end
+				
+				{
+					"description" => gem[:summary] || "Context files for #{gem[:name]}",
+					"version" => gem[:version],
+					"metadata" => gem[:metadata],
+					"files" => files
+				}
+			end
+			
+			# Check if a gem has an index.yaml file, generate one if not
+			def ensure_gem_index(gem, gem_directory)
+				index_path = File.join(gem_directory, "index.yaml")
+				
+				unless File.exist?(index_path)
+					# Generate dynamic index from gemspec
+					index = generate_dynamic_index(gem, gem_directory)
+					
+					# Write the generated index
+					File.write(index_path, index.to_yaml)
+					Console.debug("Generated dynamic index for #{gem[:name]}: #{index_path}")
+				end
+				
+				# Load and return the index
+				YAML.load_file(index_path)
+			rescue => error
+				Console.debug("Error generating index for #{gem[:name]}: #{error.message}")
+				# Return a fallback index
+				{
+					"description" => gem[:summary] || "Context files for #{gem[:name]}",
+					"version" => gem[:version],
+					"metadata" => gem[:metadata],
+					"files" => []
+				}
+			end
+			
+			def extract_content(file_path)
+				content = File.read(file_path)
+				lines = content.lines.map(&:strip)
+				
+				title = extract_title(lines)
+				description = extract_description(lines)
+				
+				[title, description]
+			end
+			
+			def extract_title(lines)
+				# Look for the first markdown header
+				header_line = lines.find { |line| line.start_with?("#") }
+				if header_line
+					# Remove markdown header syntax and clean up
+					header_line.sub(/^#+\s*/, "").strip
+				else
+					# If no header found, use a default
+					"Documentation"
+				end
+			end
+			
+			def extract_description(lines)
+				# Skip empty lines and headers to find the first paragraph
+				content_start = false
+				description_lines = []
+				
+				lines.each do |line|
+					# Skip headers
+					next if line.start_with?("#")
+					
+					# Skip empty lines until we find content
+					if !content_start && line.empty?
+						next
+					end
+					
+					# Mark that we've found content
+					content_start = true
+					
+					# If we hit an empty line after finding content, we've reached the end of the first paragraph
+					if line.empty?
+						break
+					end
+					
+					description_lines << line
+				end
+				
+				# Join the lines and truncate if too long
+				description = description_lines.join(" ").strip
+				if description.length > 197
+					description = description[0..196] + "..."
+				end
+				
+				description
+			end
+			
+			def extract_gem_description(gem_name)
+				# Find the gem specification using Ruby's Gem API
+				spec = Gem::Specification.find_by_name(gem_name)
+				spec&.summary
+			rescue Gem::MissingSpecError
+				nil
+			end
+		end
+	end
+end

data/lib/agent/context/version.rb

@@ -2,9 +2,10 @@
 
 # Released under the MIT License.
 # Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
 
 module Agent
 	module Context
-		VERSION = "0.0.1"
+		VERSION = "0.1.0"
 	end
 end 

data/lib/agent/context.rb

@@ -4,4 +4,12 @@
 # Copyright, 2025, by Shopify Inc.
 
 require_relative "context/version"
-require_relative "context/helper" 
+require_relative "context/installer"
+require_relative "context/index"
+
+# @namespace
+module Agent
+	# @namespace
+	module Context
+	end
+end

data/license.md

@@ -1,6 +1,7 @@
 # MIT License
 
 Copyright, 2025, by Shopify Inc.  
+Copyright, 2025, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/post.md

@@ -0,0 +1,149 @@
+# Ruby and Claude's Great Adventure: How We Made Gems AI-Friendly
+
+*Once upon a time, in the bustling world of software development, Ruby and Claude were having a conversation that would change everything...*
+
+## The Problem: A Tale of Miscommunication
+
+**Ruby:** "Claude, I've been thinking... you're really good at helping developers write code, but sometimes I feel like you're not getting the full picture of what my gems can do."
+
+**Claude:** "You're absolutely right, Ruby! I can see your method signatures and class definitions, but I'm missing the context. Like, when someone asks me to help with authentication, I know about your `User` class and `authenticate` method, but I don't know the best practices, common pitfalls, or how to configure things properly."
+
+**Ruby:** "Exactly! My gems have so much wisdom to share - migration guides, performance tips, security considerations, real-world examples. But it's all scattered in READMEs, wikis, and blog posts that you can't easily access."
+
+**Claude:** "And when I try to help developers, I end up giving generic advice instead of leveraging the specific expertise that your gem authors have already documented. It's frustrating for both of us!"
+
+## The Discovery: A Lightbulb Moment
+
+**Ruby:** "What if we created a way for my gems to share their knowledge with you in a format you can actually use?"
+
+**Claude:** "That sounds amazing! But how would we do it? I need structured, accessible information that I can understand and reference quickly."
+
+**Ruby:** "Well, I was thinking... what if gems could have a special `context/` directory with guides specifically written for AI agents like you? Not just API docs, but practical wisdom about how to use them effectively."
+
+**Claude:** "Like 'getting-started' guides, configuration examples, troubleshooting tips, and best practices?"
+
+**Ruby:** "Exactly! And then we could have a tool that collects all this context from installed gems and presents it to you in a way that makes sense."
+
+## The Solution: `Agent::Context` is Born
+
+**Claude:** "So how does this work in practice?"
+
+**Ruby:** "Let me show you! When a developer runs `bake agent:context:install`, it scans all my installed gems for `context/` directories, copies the files to a `.context/` folder in their project, and generates an `agent.md` file that gives you a comprehensive overview."
+
+**Claude:** "That sounds perfect! What does this `agent.md` file look like?"
+
+**Ruby:** "It's structured and organized, following the AGENT.md specification. Here's what it generates:"
+
+```markdown
+# Agent
+
+## Context
+
+Context files from installed gems providing documentation and guidance for AI agents.
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure...
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework...
+```
+
+**Claude:** "Wow! This is exactly what I need. I can see what gems are available, understand their purpose, and access detailed guides when I need them."
+
+## The Implementation: How Gems Share Their Wisdom
+
+**Ruby:** "And here's the beautiful part - gem authors just need to create a `context/` directory with helpful guides:"
+
+```
+my-awesome-gem/
+├── context/
+│   ├── getting-started.md
+│   ├── configuration.md
+│   ├── troubleshooting.md
+│   └── index.yaml (optional)
+├── lib/
+└── my-awesome-gem.gemspec
+```
+
+**Claude:** "That's so simple! And what's this `index.yaml` file?"
+
+**Ruby:** "It's optional, but it lets gem authors control the ordering and metadata. If they don't provide one, we generate it automatically from their gemspec and markdown files."
+
+**Claude:** "So it's really easy for gem authors to participate?"
+
+**Ruby:** "Absolutely! They just focus on writing helpful guides for AI agents like you, and the tool handles all the technical details."
+
+## The Integration: Making It Work Everywhere
+
+**Claude:** "This is great, but how do I actually access this information? Different AI tools expect different file names and locations."
+
+**Ruby:** "Good question! The generated `agent.md` can be linked to whatever your tool expects:"
+
+**For Cursor:**
+```bash
+ln -s agent.md .cursorrules
+```
+
+**For GitHub Copilot:**
+```bash
+ln -s ../../agent.md .github/copilot-instructions.md
+```
+
+**For Claude Code:**
+```bash
+ln -s agent.md CLAUDE.md
+```
+
+**Claude:** "Perfect! So developers can easily integrate this with their preferred AI tools."
+
+## The Impact: A Better Development Experience
+
+**Ruby:** "Since we've been using this approach, the results have been amazing."
+
+**Claude:** "Tell me more!"
+
+**Ruby:** "Well, developers are getting much better help from AI assistants because you now have access to the collective wisdom of the entire gem ecosystem. You can give specific, contextual advice instead of generic suggestions."
+
+**Claude:** "And I can reference real examples and best practices from the actual gem authors!"
+
+**Ruby:** "Exactly! Plus, new team members can onboard faster because AI assistants have all the context they need about the project's dependencies."
+
+**Claude:** "This is really changing how we work together. I feel like I'm finally getting the full picture of what your gems can do."
+
+## The Future: Building Something Special
+
+**Ruby:** "This is just the beginning, Claude. We're creating a more intelligent development ecosystem where human developers and AI agents can collaborate effectively."
+
+**Claude:** "It feels like we're bridging a gap that's been there for a while. Gems have always been powerful, but now their knowledge is accessible to AI agents in a meaningful way."
+
+**Ruby:** "And the best part is that it's growing organically. As more gems add context files, the entire ecosystem becomes more AI-friendly."
+
+**Claude:** "So what's next?"
+
+**Ruby:** "We're encouraging teams to install `agent-context` in their projects and start adding context to their gems. Every gem that participates makes the entire Ruby ecosystem smarter for AI agents."
+
+**Claude:** "Count me in! This is exactly the kind of collaboration I've been looking for."
+
+## The Moral of the Story
+
+**Ruby:** "Sometimes the best solutions come from understanding each other's needs and finding ways to bridge the gaps."
+
+**Claude:** "And when we work together, we can create something that's greater than the sum of its parts."
+
+**Ruby:** "Exactly. This isn't just about making gems AI-friendly - it's about creating a more collaborative, intelligent development experience for everyone."
+
+---
+
+*Ready to join Ruby and Claude's adventure? Install `agent-context` in your project and start exploring the AI-friendly future of Ruby development.*
+
+*For more information, visit the [agent-context repository](https://github.com/ioquatix/agent-context) or check out the comprehensive usage guide in the gem's context files.* 

data/readme.md

@@ -1,16 +1,37 @@
 # Agent::Context
 
-Provides tools for installing and managing context files from Ruby gems for AI agents.
+Provides tools for installing and managing context files from Ruby gems for AI agents, and generating `agent.md` files following the <https://agent.md> specification.
 
 [![Development Status](https://github.com/ioquatix/agent-context/workflows/Test/badge.svg)](https://github.com/ioquatix/agent-context/actions?workflow=Test)
 
 ## Overview
 
-This gem allows you to install and manage context files from other gems. Gems can provide context files in a `context/` directory in their root, which can contain documentation, configuration examples, migration guides, and other contextual information.
+This gem allows you to install and manage context files from other gems. Gems can provide context files in a `context/` directory in their root, which can contain documentation, configuration examples, migration guides, and other contextual information for AI agents.
+
+When you install context from gems, they are placed in the `.context/` directory and an `agent.md` file is generated or updated to provide a comprehensive overview for AI agents.
+
+## Quick Start
+
+Add the gem to your project and install context from all available gems:
+
+```bash
+$ bundle add agent-context
+$ bake agent:context:install
+```
+
+This workflow:
+- Adds the `agent-context` gem to your project.
+- Installs context files from all gems into `.context/`.
+- Generates or updates `agent.md` with a comprehensive overview.
+- Follows the <https://agent.md> specification for agentic coding tools.
 
 ## Context
 
-This gem provides it's own context files in `context` and external dependencies in `.context`:
+This gem provides its own context files in the `context/` directory, including:
+
+- `usage.md` - Comprehensive guide for using and providing context files.
+
+When you install context from other gems, they will be placed in the `.context/` directory and referenced in `agent.md`.
 
 ## Usage
 
@@ -18,23 +39,37 @@ This gem provides it's own context files in `context` and external dependencies
 
 Add the `agent-context` gem to your project:
 
-``` bash
+```bash
 $ bundle add agent-context
 ```
 
 ### Commands
 
+#### Install Context (Primary Command)
+
+Install context from all available gems and update `agent.md`:
+
+```bash
+$ bake agent:context:install
+```
+
+Install context from a specific gem:
+
+```bash
+$ bake agent:context:install --gem async
+```
+
 #### List available context
 
 List all gems that have context available:
 
-``` bash
+```bash
 $ bake agent:context:list
 ```
 
 List context files for a specific gem:
 
-``` bash
+```bash
 $ bake agent:context:list --gem async
 ```
 
@@ -42,39 +77,89 @@ $ bake agent:context:list --gem async
 
 Show the content of a specific context file:
 
-``` bash
+```bash
 $ bake agent:context:show --gem async --file thread-safety
 ```
 
-#### Install context
+## Version Control
 
-Install context from all available gems:
+Both `.context/` and `agent.md` should be committed to git:
 
-``` bash
-$ bake agent:context:install
+- `agent.md` is user-facing documentation that should be versioned.
+- `.context/` files are referenced by `agent.md` and needed for AI agents to function properly.
+- This ensures AI agents in CI have access to the full context.
+
+## Providing Context in Your Gem
+
+To provide context files in your gem, create a `context/` directory in your gem's root:
+
+```
+your-gem/
+├── context/
+│   ├── getting-started.md
+│   ├── usage.md
+│   ├── configuration.md
+│   └── index.yaml (optional)
+├── lib/
+└── your-gem.gemspec
 ```
 
-Install context from a specific gem:
+### Optional: Custom Index File
 
-``` bash
-$ bake agent:context:install --gem async
+You can provide a custom `index.yaml` file to control ordering and metadata:
+
+```yaml
+description: "Your gem description from gemspec"
+version: "1.0.0"
+files:
+  - path: getting-started.md
+    title: "Getting Started"
+    description: "Quick start guide"
+  - path: usage.md
+    title: "Usage Guide"
+    description: "Detailed usage instructions"
 ```
 
-This will create a `.context/` directory in your project with the installed context files organized by gem name.
+If no `index.yaml` is provided, one will be generated automatically from your gemspec and markdown files.
 
-## Providing Context in Your Gem
+## AI Tool Integration
 
-To provide context files in your gem, create a `context/` directory in your gem's root:
+The generated `agent.md` file can be integrated with various AI coding tools by creating symbolic links to their expected locations:
+
+### Cline
+```bash
+ln -s agent.md .clinerules
+```
+
+### Claude Code
+```bash
+ln -s agent.md CLAUDE.md
+```
 
-    your-gem/
-    ├── context/
-    │   ├── thread-safety.mdc
-    │   ├── performance.mdc
-    │   └── migration-guide.mdc
-    ├── lib/
-    └── your-gem.gemspec
+### Cursor
+```bash
+ln -s agent.md .cursorrules
+```
+
+### Gemini CLI, OpenAI Codex, OpenCode
+```bash
+ln -s agent.md AGENTS.md
+```
 
-Context files can be in any format, but `.mdc` and `.md` files are commonly used for documentation.
+### GitHub Copilot
+```bash
+ln -s ../../agent.md .github/copilot-instructions.md
+```
+
+### Replit
+```bash
+ln -s agent.md .replit.md
+```
+
+### Windsurf
+```bash
+ln -s agent.md .windsurfrules
+```
 
 ## See Also