agent-context 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- checksums.yaml.gz.sig +4 -0
- data/bake/agent/context.rb +75 -0
- data/context/adding-context.mdc +166 -0
- data/context/examples.mdc +92 -0
- data/context/getting-started.mdc +56 -0
- data/context/markdown-context.mdc +91 -0
- data/design.md +149 -0
- data/lib/agent/context/helper.rb +109 -0
- data/lib/agent/context/version.rb +10 -0
- data/lib/agent/context.rb +7 -0
- data/license.md +21 -0
- data/readme.md +99 -0
- data.tar.gz.sig +0 -0
- metadata +94 -0
- metadata.gz.sig +0 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: fb68b016f45077bf445632b810e6f73ca397a262ae1baa5b1c151489ddeaa7a1
|
4
|
+
data.tar.gz: f7e9f38749e95d7561736ec30ba4db9bb3841da2c142f59f70508d8119ee890c
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 0daacfbf5d32738df4c426795f7a5f6a1409a30d5da02ce518c9a2bff0b95831765b9477261c76ee16814980fc2614ee6be6be607aff7374d8366ba0f9f7c35f
|
7
|
+
data.tar.gz: d2dc624eba0c6e3449c62067a1c5e28f6eccd4ed48c57a591fb3d7d5a33dcffe0699d2965b797fb781f149671f65b7ae0865897113e3abd08a8f6f20dfd6be30
|
checksums.yaml.gz.sig
ADDED
@@ -0,0 +1,75 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Released under the MIT License.
|
4
|
+
# Copyright, 2025, by Shopify Inc.
|
5
|
+
|
6
|
+
require_relative "../../lib/agent/context/helper"
|
7
|
+
|
8
|
+
include Agent::Context
|
9
|
+
|
10
|
+
def initialize(context)
|
11
|
+
super(context)
|
12
|
+
|
13
|
+
@helper = Helper.new
|
14
|
+
end
|
15
|
+
|
16
|
+
attr :helper
|
17
|
+
|
18
|
+
# List all gems that have context available.
|
19
|
+
# @parameter gem [String] Optional specific gem name to list context files for.
|
20
|
+
def list(gem: nil)
|
21
|
+
if gem
|
22
|
+
files = @helper.list_context_files(gem)
|
23
|
+
if files
|
24
|
+
puts "Context files for gem '#{gem}':"
|
25
|
+
files.each do |file|
|
26
|
+
relative_path = Pathname.new(file).relative_path_from(Pathname.new(@helper.find_gem_with_context(gem)[:path]))
|
27
|
+
puts " #{relative_path}"
|
28
|
+
end
|
29
|
+
else
|
30
|
+
puts "No context found for gem '#{gem}'"
|
31
|
+
end
|
32
|
+
else
|
33
|
+
gems = @helper.find_gems_with_context
|
34
|
+
if gems.any?
|
35
|
+
puts "Gems with context available:"
|
36
|
+
gems.each do |gem_info|
|
37
|
+
puts " #{gem_info[:name]} (#{gem_info[:version]})"
|
38
|
+
end
|
39
|
+
else
|
40
|
+
puts "No gems with context found"
|
41
|
+
end
|
42
|
+
end
|
43
|
+
end
|
44
|
+
|
45
|
+
# Show the content of a specific context file.
|
46
|
+
# @parameter gem [String] The gem name.
|
47
|
+
# @parameter file [String] The context file name.
|
48
|
+
def show(gem:, file:)
|
49
|
+
content = @helper.show_context_file(gem, file)
|
50
|
+
if content
|
51
|
+
puts content
|
52
|
+
else
|
53
|
+
puts "Context file '#{file}' not found in gem '#{gem}'"
|
54
|
+
end
|
55
|
+
end
|
56
|
+
|
57
|
+
# Install context files from gems into the current project.
|
58
|
+
# @parameter gem [String] Optional specific gem name to install context from.
|
59
|
+
def install(gem: nil)
|
60
|
+
if gem
|
61
|
+
if @helper.install_gem_context(gem)
|
62
|
+
puts "Installed context from gem '#{gem}'"
|
63
|
+
else
|
64
|
+
puts "No context found for gem '#{gem}'"
|
65
|
+
end
|
66
|
+
else
|
67
|
+
installed = @helper.install_all_context
|
68
|
+
if installed.any?
|
69
|
+
puts "Installed context from #{installed.length} gems:"
|
70
|
+
installed.each { |gem_name| puts " #{gem_name}" }
|
71
|
+
else
|
72
|
+
puts "No gems with context found"
|
73
|
+
end
|
74
|
+
end
|
75
|
+
end
|
@@ -0,0 +1,166 @@
|
|
1
|
+
---
|
2
|
+
description: When creating or updating a gem's public interface.
|
3
|
+
alwaysApply: false
|
4
|
+
---
|
5
|
+
# Adding Context to Your Gem
|
6
|
+
|
7
|
+
## How to provide context in your gem
|
8
|
+
|
9
|
+
### 1. Create a `context/` directory
|
10
|
+
|
11
|
+
In your gem's root directory, create a `context/` folder:
|
12
|
+
|
13
|
+
```
|
14
|
+
your-gem/
|
15
|
+
├── context/
|
16
|
+
│ ├── getting-started.mdc
|
17
|
+
│ ├── configuration.mdc
|
18
|
+
│ └── troubleshooting.mdc
|
19
|
+
├── lib/
|
20
|
+
└── your-gem.gemspec
|
21
|
+
```
|
22
|
+
|
23
|
+
### 2. Add context files
|
24
|
+
|
25
|
+
Create files with helpful information. Common types include:
|
26
|
+
|
27
|
+
- **getting-started.mdc** - Quick start guide
|
28
|
+
- **configuration.mdc** - Configuration options and examples
|
29
|
+
- **troubleshooting.mdc** - Common issues and solutions
|
30
|
+
- **migration.mdc** - Migration guides between versions
|
31
|
+
- **performance.mdc** - Performance tips and best practices
|
32
|
+
- **security.mdc** - Security considerations
|
33
|
+
|
34
|
+
### 3. Document your context
|
35
|
+
|
36
|
+
Add a section to your gem's README:
|
37
|
+
|
38
|
+
```markdown
|
39
|
+
## Context
|
40
|
+
|
41
|
+
This gem provides additional context files that can be installed using `agent-context`:
|
42
|
+
|
43
|
+
```bash
|
44
|
+
bake agent:context:install --gem your-gem-name
|
45
|
+
```
|
46
|
+
|
47
|
+
Available context files:
|
48
|
+
- `getting-started.mdc` - Quick start guide
|
49
|
+
- `configuration.mdc` - Configuration options
|
50
|
+
```
|
51
|
+
|
52
|
+
### 4. File format
|
53
|
+
|
54
|
+
Context files can be in any format, but `.mdc` and `.md` are commonly used for documentation. The content should be:
|
55
|
+
|
56
|
+
- **Practical** - Include real examples
|
57
|
+
- **Focused** - One topic per file
|
58
|
+
- **Clear** - Easy to understand and follow
|
59
|
+
- **Actionable** - Provide specific guidance
|
60
|
+
|
61
|
+
## Example context file
|
62
|
+
|
63
|
+
```markdown
|
64
|
+
# Configuration Guide
|
65
|
+
|
66
|
+
## Basic Setup
|
67
|
+
|
68
|
+
Add to your Gemfile:
|
69
|
+
```ruby
|
70
|
+
gem "your-gem"
|
71
|
+
```
|
72
|
+
|
73
|
+
## Configuration Options
|
74
|
+
|
75
|
+
```ruby
|
76
|
+
YourGem.configure do |config|
|
77
|
+
config.timeout = 30
|
78
|
+
config.retries = 3
|
79
|
+
end
|
80
|
+
```
|
81
|
+
|
82
|
+
## Environment Variables
|
83
|
+
|
84
|
+
- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
|
85
|
+
- `YOUR_GEM_RETRIES` - Number of retry attempts
|
86
|
+
|
87
|
+
|
88
|
+
- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
|
89
|
+
- `YOUR_GEM_RETRIES` - Number of retry attempts
|
90
|
+
# Adding Context to Your Gem
|
91
|
+
|
92
|
+
## How to provide context in your gem
|
93
|
+
|
94
|
+
### 1. Create a `context/` directory
|
95
|
+
|
96
|
+
In your gem's root directory, create a `context/` folder:
|
97
|
+
|
98
|
+
```
|
99
|
+
your-gem/
|
100
|
+
├── context/
|
101
|
+
│ ├── getting-started.mdc
|
102
|
+
│ ├── configuration.mdc
|
103
|
+
│ └── troubleshooting.mdc
|
104
|
+
├── lib/
|
105
|
+
└── your-gem.gemspec
|
106
|
+
```
|
107
|
+
|
108
|
+
### 2. Add context files
|
109
|
+
|
110
|
+
Create files with helpful information. Common types include:
|
111
|
+
|
112
|
+
- **getting-started.mdc** - Quick start guide
|
113
|
+
- **configuration.mdc** - Configuration options and examples
|
114
|
+
- **troubleshooting.mdc** - Common issues and solutions
|
115
|
+
- **migration.mdc** - Migration guides between versions
|
116
|
+
- **performance.mdc** - Performance tips and best practices
|
117
|
+
- **security.mdc** - Security considerations
|
118
|
+
|
119
|
+
### 3. Document your context
|
120
|
+
|
121
|
+
Add a section to your gem's README:
|
122
|
+
|
123
|
+
```markdown
|
124
|
+
## Context
|
125
|
+
|
126
|
+
This gem provides additional context files that can be installed using `bake agent:context:install`.
|
127
|
+
```
|
128
|
+
|
129
|
+
### 4. File format
|
130
|
+
|
131
|
+
Context files can be in any format, but `.mdc` and `.md` are commonly used for documentation. The content should be:
|
132
|
+
|
133
|
+
- **Practical** - Include real examples
|
134
|
+
- **Focused** - One topic per file
|
135
|
+
- **Clear** - Easy to understand and follow
|
136
|
+
- **Actionable** - Provide specific guidance
|
137
|
+
|
138
|
+
## Example context file
|
139
|
+
|
140
|
+
```markdown
|
141
|
+
# Configuration Guide
|
142
|
+
|
143
|
+
## Basic Setup
|
144
|
+
|
145
|
+
Add to your Gemfile:
|
146
|
+
```ruby
|
147
|
+
gem "your-gem"
|
148
|
+
```
|
149
|
+
|
150
|
+
## Configuration Options
|
151
|
+
|
152
|
+
```ruby
|
153
|
+
YourGem.configure do |config|
|
154
|
+
config.timeout = 30
|
155
|
+
config.retries = 3
|
156
|
+
end
|
157
|
+
```
|
158
|
+
|
159
|
+
## Environment Variables
|
160
|
+
|
161
|
+
- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
|
162
|
+
- `YOUR_GEM_RETRIES` - Number of retry attempts
|
163
|
+
|
164
|
+
|
165
|
+
- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
|
166
|
+
- `YOUR_GEM_RETRIES` - Number of retry attempts
|
@@ -0,0 +1,92 @@
|
|
1
|
+
---
|
2
|
+
description: Practical examples of using agent-context.
|
3
|
+
alwaysApply: false
|
4
|
+
---
|
5
|
+
|
6
|
+
# Practical Examples
|
7
|
+
|
8
|
+
## Example 1: Installing context from a web framework
|
9
|
+
|
10
|
+
```bash
|
11
|
+
# Install context from Rails
|
12
|
+
bake agent:context:install --gem rails
|
13
|
+
|
14
|
+
# See what Rails provides
|
15
|
+
bake agent:context:list --gem rails
|
16
|
+
|
17
|
+
# View Rails configuration guide
|
18
|
+
bake agent:context:show --gem rails --file configuration
|
19
|
+
```
|
20
|
+
|
21
|
+
## Example 2: Getting help with a specific gem
|
22
|
+
|
23
|
+
```bash
|
24
|
+
# You're having trouble with the async gem
|
25
|
+
bake agent:context:list --gem async
|
26
|
+
|
27
|
+
# Check the troubleshooting guide
|
28
|
+
bake agent:context:show --gem async --file troubleshooting
|
29
|
+
|
30
|
+
# Install all async context for offline reference
|
31
|
+
bake agent:context:install --gem async
|
32
|
+
```
|
33
|
+
|
34
|
+
## Example 3: Discovering new gems
|
35
|
+
|
36
|
+
```bash
|
37
|
+
# See what context is available in your project
|
38
|
+
bake agent:context:list
|
39
|
+
|
40
|
+
# Install context from all gems
|
41
|
+
bake agent:context:install
|
42
|
+
|
43
|
+
# Browse the installed context
|
44
|
+
ls .context/
|
45
|
+
```
|
46
|
+
|
47
|
+
## Example 4: Working with multiple gems
|
48
|
+
|
49
|
+
```bash
|
50
|
+
# Install context from your main dependencies
|
51
|
+
bake agent:context:install --gem rack
|
52
|
+
bake agent:context:install --gem sinatra
|
53
|
+
bake agent:context:install --gem puma
|
54
|
+
|
55
|
+
# Now you have context for your web stack
|
56
|
+
ls .context/
|
57
|
+
# => rack/ sinatra/ puma/
|
58
|
+
```
|
59
|
+
|
60
|
+
## Example 5: Using context in your workflow
|
61
|
+
|
62
|
+
```bash
|
63
|
+
# Before starting a new feature
|
64
|
+
bake agent:context:install --gem the-gem-you're-using
|
65
|
+
|
66
|
+
# Read the getting started guide
|
67
|
+
cat .context/the-gem-you're-using/getting-started.mdc
|
68
|
+
|
69
|
+
# Check performance tips
|
70
|
+
cat .context/the-gem-you're-using/performance.mdc
|
71
|
+
```
|
72
|
+
|
73
|
+
## Real-world scenario
|
74
|
+
|
75
|
+
You're building a Rails API and want to understand how to properly configure Puma:
|
76
|
+
|
77
|
+
```bash
|
78
|
+
# Install Puma context
|
79
|
+
bake agent:context:install --gem puma
|
80
|
+
|
81
|
+
# Read the configuration guide
|
82
|
+
cat .context/puma/configuration.mdc
|
83
|
+
|
84
|
+
# Check performance recommendations
|
85
|
+
cat .context/puma/performance.mdc
|
86
|
+
```
|
87
|
+
|
88
|
+
This gives you practical, gem-specific guidance that might not be in the main documentation.
|
89
|
+
description:
|
90
|
+
globs:
|
91
|
+
alwaysApply: false
|
92
|
+
---
|
@@ -0,0 +1,56 @@
|
|
1
|
+
---
|
2
|
+
description: Getting started with agent-context.
|
3
|
+
alwaysApply: false
|
4
|
+
---
|
5
|
+
|
6
|
+
# Getting Started
|
7
|
+
|
8
|
+
## What is this?
|
9
|
+
|
10
|
+
`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` directory.
|
11
|
+
|
12
|
+
## Quick Commands
|
13
|
+
|
14
|
+
```bash
|
15
|
+
# See what context is available
|
16
|
+
bake agent:context:list
|
17
|
+
|
18
|
+
# Install all available context
|
19
|
+
bake agent:context:install
|
20
|
+
|
21
|
+
# Install context from a specific gem
|
22
|
+
bake agent:context:install --gem async
|
23
|
+
|
24
|
+
# See what context files a gem provides
|
25
|
+
bake agent:context:list --gem async
|
26
|
+
|
27
|
+
# View a specific context file
|
28
|
+
bake agent:context:show --gem async --file thread-safety
|
29
|
+
```
|
30
|
+
|
31
|
+
## What happens when you install context?
|
32
|
+
|
33
|
+
When you run `bake agent:context:install`, the tool:
|
34
|
+
|
35
|
+
1. Scans all installed gems for `context/` directories
|
36
|
+
2. Creates a `.context/` directory in your current project
|
37
|
+
3. Copies context files organized by gem name
|
38
|
+
|
39
|
+
For example:
|
40
|
+
```
|
41
|
+
your-project/
|
42
|
+
├── .context/
|
43
|
+
│ ├── async/
|
44
|
+
│ │ ├── thread-safety.mdc
|
45
|
+
│ │ └── performance.mdc
|
46
|
+
│ └── rack/
|
47
|
+
│ └── middleware.mdc
|
48
|
+
```
|
49
|
+
|
50
|
+
## Why use this?
|
51
|
+
|
52
|
+
- **Discover hidden documentation** that gems provide
|
53
|
+
- **Get practical examples** and guidance
|
54
|
+
- **Understand best practices** from gem authors
|
55
|
+
- **Access migration guides** and troubleshooting tips
|
56
|
+
|
@@ -0,0 +1,91 @@
|
|
1
|
+
---
|
2
|
+
globs: *.mdc
|
3
|
+
alwaysApply: false
|
4
|
+
---
|
5
|
+
# Creating `.mdc` (Markdown Context) Files
|
6
|
+
|
7
|
+
## What is an `.mdc` file?
|
8
|
+
|
9
|
+
An `.mdc` file is a Markdown file with optional YAML frontmatter, used to provide context, documentation, or metadata for Ruby gems. These files are intended to be machine- and human-readable, and are used by tools like `agent-context` to expose useful information to users and agents.
|
10
|
+
|
11
|
+
## Structure
|
12
|
+
|
13
|
+
### 1. YAML Frontmatter (Optional but Recommended)
|
14
|
+
|
15
|
+
Start your `.mdc` file with a YAML frontmatter block:
|
16
|
+
|
17
|
+
```yaml
|
18
|
+
---
|
19
|
+
description: Short summary of the file's purpose
|
20
|
+
globs: "test/**/*.rb,lib/**/*.rb" # Optional: comma-separated file patterns
|
21
|
+
alwaysApply: false # Optional: should this context always be applied?
|
22
|
+
---
|
23
|
+
```
|
24
|
+
|
25
|
+
**Fields:**
|
26
|
+
- `description` (required): Short, human-readable summary.
|
27
|
+
- `globs` (optional): Comma-separated string of file patterns this context applies to.
|
28
|
+
- `alwaysApply` (optional): Whether to always apply this context (default: false).
|
29
|
+
|
30
|
+
### 2. Markdown Content
|
31
|
+
|
32
|
+
After the frontmatter, write your documentation in standard Markdown:
|
33
|
+
|
34
|
+
~~~markdown
|
35
|
+
# Title
|
36
|
+
|
37
|
+
## Section
|
38
|
+
|
39
|
+
- Bullet points
|
40
|
+
- More details
|
41
|
+
|
42
|
+
```ruby
|
43
|
+
# Code examples
|
44
|
+
```
|
45
|
+
~~~
|
46
|
+
|
47
|
+
## Best Practices
|
48
|
+
|
49
|
+
- **Start with a clear description** in the YAML frontmatter.
|
50
|
+
- **Use headings** (`#`, `##`) to organize content.
|
51
|
+
- **Keep each file focused** on a single topic.
|
52
|
+
- **Include code examples** where relevant.
|
53
|
+
- **Use lists** for options, steps, or best practices.
|
54
|
+
- **Be concise and actionable.**
|
55
|
+
- **Use tags and globs** to help agents and tools categorize and apply context.
|
56
|
+
|
57
|
+
## Example `.mdc` File
|
58
|
+
|
59
|
+
~~~markdown
|
60
|
+
---
|
61
|
+
description: How to configure the gem for production use.
|
62
|
+
globs: config/my_gem.rb
|
63
|
+
alwaysApply: false
|
64
|
+
---
|
65
|
+
|
66
|
+
# Production Configuration
|
67
|
+
|
68
|
+
To configure my_gem for production:
|
69
|
+
|
70
|
+
1. Set the environment variable:
|
71
|
+
```sh
|
72
|
+
export GEM_ENV=production
|
73
|
+
```
|
74
|
+
2. Update your config file:
|
75
|
+
```ruby
|
76
|
+
MyGem.configure do |config|
|
77
|
+
config.mode = :production
|
78
|
+
end
|
79
|
+
```
|
80
|
+
3. Restart your application.
|
81
|
+
~~~
|
82
|
+
|
83
|
+
## When to Use `.mdc` Files
|
84
|
+
|
85
|
+
- To provide documentation, guides, or metadata for your gem.
|
86
|
+
- To expose best practices, migration guides, or troubleshooting tips.
|
87
|
+
- To help AI agents and tools discover and apply context automatically.
|
88
|
+
|
89
|
+
## Further Reading
|
90
|
+
- [YAML Frontmatter Spec](https://jekyllrb.com/docs/front-matter/)
|
91
|
+
- [Markdown Guide](https://www.markdownguide.org/)
|
data/design.md
ADDED
@@ -0,0 +1,149 @@
|
|
1
|
+
# Design Document: agent-context
|
2
|
+
|
3
|
+
## Problem Statement
|
4
|
+
|
5
|
+
AI agents working with Ruby codebases often lack access to the rich contextual information that gem authors provide. While gems may have extensive documentation, examples, migration guides, and best practices, this information is typically scattered across READMEs, wikis, blog posts, and other sources that aren't easily accessible to AI agents.
|
6
|
+
|
7
|
+
## Core Design Principles
|
8
|
+
|
9
|
+
### 1. Context as a First-Class Concept
|
10
|
+
|
11
|
+
Context files are treated as a first-class part of a gem's public interface, alongside the code itself. This means:
|
12
|
+
- Context files are versioned with the gem.
|
13
|
+
- They're distributed as part of the gem package.
|
14
|
+
- They're discoverable and accessible programmatically.
|
15
|
+
- They follow a consistent structure and format.
|
16
|
+
|
17
|
+
### 2. Machine-Readable, Human-Friendly
|
18
|
+
|
19
|
+
Context files use `.mdc` (Markdown Context) format, which combines:
|
20
|
+
- **Human readability**: Standard Markdown for easy authoring and reading.
|
21
|
+
- **Machine structure**: YAML frontmatter for metadata and organization.
|
22
|
+
- **Extensibility**: Can include code examples, diagrams, and structured data.
|
23
|
+
|
24
|
+
### 3. Separation of Concerns
|
25
|
+
|
26
|
+
The design separates three distinct concerns:
|
27
|
+
- **Public Interface**: `context/` directory in gem root (what gem authors provide).
|
28
|
+
- **Private Working Directory**: `.context/` in consuming projects (where context is installed).
|
29
|
+
- **Tool Interface**: `bake agent:context:*` commands (how users interact).
|
30
|
+
|
31
|
+
## Architecture Decisions
|
32
|
+
|
33
|
+
### File Organization Strategy
|
34
|
+
|
35
|
+
**Decision**: Context files are installed into `.context/gem-name/` subdirectories
|
36
|
+
|
37
|
+
**Rationale**:
|
38
|
+
- **Isolation**: Prevents conflicts between different gems' context files.
|
39
|
+
- **Discoverability**: Easy to find context for a specific gem.
|
40
|
+
- **Scalability**: Supports installing context from multiple gems.
|
41
|
+
- **Clear Ownership**: Obvious which context files belong to which gem.
|
42
|
+
|
43
|
+
### Command Structure
|
44
|
+
|
45
|
+
**Decision**: Use `bake agent:context:*` command namespace
|
46
|
+
|
47
|
+
**Rationale**:
|
48
|
+
- **Consistency**: Matches the gem name `agent-context`.
|
49
|
+
- **Clarity**: Makes it obvious these commands are for AI agent workflows.
|
50
|
+
- **Namespace Safety**: Avoids conflicts with other gem-related commands.
|
51
|
+
- **Tool Integration**: Leverages existing Bake infrastructure.
|
52
|
+
|
53
|
+
### Module Structure
|
54
|
+
|
55
|
+
**Decision**: Use `Agent::Context` module namespace
|
56
|
+
|
57
|
+
**Rationale**:
|
58
|
+
- **Purpose Clarity**: Explicitly indicates this is for AI agents.
|
59
|
+
- **Namespace Safety**: Avoids potential conflicts with RubyGems' `Gem::` namespace.
|
60
|
+
- **Future-Proof**: Won't conflict if RubyGems adds their own context features.
|
61
|
+
|
62
|
+
## Context File Design
|
63
|
+
|
64
|
+
### YAML Frontmatter
|
65
|
+
|
66
|
+
Context files support structured metadata:
|
67
|
+
```yaml
|
68
|
+
---
|
69
|
+
description: Short summary of the file's purpose
|
70
|
+
globs: "test/**/*.rb,lib/**/*.rb" # Comma-separated file patterns
|
71
|
+
alwaysApply: false # Whether to always apply this context
|
72
|
+
---
|
73
|
+
```
|
74
|
+
|
75
|
+
**Design Decisions**:
|
76
|
+
- **`description`**: Required human-readable summary.
|
77
|
+
- **`globs`**: Optional file patterns this context applies to.
|
78
|
+
- **`alwaysApply`**: Optional flag for context that should always be available.
|
79
|
+
- **No tags**: Keeps the format simple and focused.
|
80
|
+
|
81
|
+
### File Naming Conventions
|
82
|
+
|
83
|
+
- **`.mdc` extension**: Indicates Markdown Context files.
|
84
|
+
- **Descriptive names**: `thread-safety.mdc`, `performance.mdc`, `migration-guide.mdc`.
|
85
|
+
- **Fallback support**: Commands can find files with or without extensions.
|
86
|
+
|
87
|
+
## Installation Strategy
|
88
|
+
|
89
|
+
### Copy vs. Symlink
|
90
|
+
|
91
|
+
**Decision**: Copy files rather than symlink
|
92
|
+
|
93
|
+
**Rationale**:
|
94
|
+
- **Offline Access**: Context remains available even if gems are uninstalled.
|
95
|
+
- **Version Stability**: Context doesn't change if gem is updated.
|
96
|
+
- **Project Independence**: Context becomes part of the project's knowledge base.
|
97
|
+
- **Simplicity**: No symlink management or broken link issues.
|
98
|
+
|
99
|
+
### Directory Structure
|
100
|
+
|
101
|
+
```
|
102
|
+
project/
|
103
|
+
├── .context/ # Private working directory
|
104
|
+
│ ├── async/ # Context from async gem
|
105
|
+
│ │ ├── thread-safety.mdc
|
106
|
+
│ │ └── performance.mdc
|
107
|
+
│ └── rails/ # Context from rails gem
|
108
|
+
│ └── configuration.mdc
|
109
|
+
```
|
110
|
+
|
111
|
+
## Use Cases and Workflows
|
112
|
+
|
113
|
+
### For Gem Authors
|
114
|
+
|
115
|
+
1. **Create Context Directory**: Add `context/` to gem root.
|
116
|
+
2. **Write Context Files**: Create `.mdc` files with documentation, examples, guides.
|
117
|
+
3. **Version and Distribute**: Context files are included in gem releases.
|
118
|
+
|
119
|
+
### For Developers
|
120
|
+
|
121
|
+
1. **Discover Context**: `bake agent:context:list` to see available context.
|
122
|
+
2. **Install Context**: `bake agent:context:install --gem async` to copy locally.
|
123
|
+
3. **Access Context**: AI agents can read from `.context/` directory.
|
124
|
+
|
125
|
+
### For AI Agents
|
126
|
+
|
127
|
+
1. **Scan Context**: Read from `.context/` directory for relevant information.
|
128
|
+
2. **Apply Context**: Use glob patterns to determine which context applies.
|
129
|
+
3. **Provide Guidance**: Reference gem-specific documentation and examples.
|
130
|
+
|
131
|
+
## Future Considerations
|
132
|
+
|
133
|
+
### Potential Enhancements
|
134
|
+
|
135
|
+
- **Context Validation**: Validate `.mdc` file structure and content.
|
136
|
+
- **Context Indexing**: Create searchable index of installed context.
|
137
|
+
- **Context Updates**: Mechanism to update context when gems are updated.
|
138
|
+
- **Context Dependencies**: Allow context files to reference other context files.
|
139
|
+
|
140
|
+
### Integration Opportunities
|
141
|
+
|
142
|
+
- **IDE Integration**: Context-aware code completion and documentation.
|
143
|
+
- **CI/CD Integration**: Validate context files during gem releases.
|
144
|
+
- **Documentation Sites**: Generate context-aware documentation.
|
145
|
+
- **AI Agent Frameworks**: Direct integration with AI agent platforms.
|
146
|
+
|
147
|
+
## Conclusion
|
148
|
+
|
149
|
+
The `agent-context` gem provides a simple but powerful mechanism for making Ruby gems more AI-friendly. By treating context as a first-class part of a gem's interface, it enables AI agents to access the rich knowledge that gem authors provide, leading to more effective and informed code assistance.
|
@@ -0,0 +1,109 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
# Released under the MIT License.
|
4
|
+
# Copyright, 2025, by Shopify Inc.
|
5
|
+
|
6
|
+
require "rubygems"
|
7
|
+
require "fileutils"
|
8
|
+
require "pathname"
|
9
|
+
|
10
|
+
module Agent
|
11
|
+
module Context
|
12
|
+
class Helper
|
13
|
+
def initialize(specifications: ::Gem::Specification)
|
14
|
+
@context_path = ".context"
|
15
|
+
@specifications = specifications
|
16
|
+
end
|
17
|
+
|
18
|
+
# Find all gems that have a context directory
|
19
|
+
def find_gems_with_context
|
20
|
+
gems_with_context = []
|
21
|
+
|
22
|
+
@specifications.each do |spec|
|
23
|
+
context_path = File.join(spec.full_gem_path, "context")
|
24
|
+
if Dir.exist?(context_path)
|
25
|
+
gems_with_context << {
|
26
|
+
name: spec.name,
|
27
|
+
version: spec.version.to_s,
|
28
|
+
path: context_path
|
29
|
+
}
|
30
|
+
end
|
31
|
+
end
|
32
|
+
|
33
|
+
gems_with_context
|
34
|
+
end
|
35
|
+
|
36
|
+
# Find a specific gem with context
|
37
|
+
def find_gem_with_context(gem_name)
|
38
|
+
spec = @specifications.find { |s| s.name == gem_name }
|
39
|
+
return nil unless spec
|
40
|
+
|
41
|
+
context_path = File.join(spec.full_gem_path, "context")
|
42
|
+
|
43
|
+
if Dir.exist?(context_path)
|
44
|
+
{
|
45
|
+
name: spec.name,
|
46
|
+
version: spec.version.to_s,
|
47
|
+
path: context_path
|
48
|
+
}
|
49
|
+
else
|
50
|
+
nil
|
51
|
+
end
|
52
|
+
end
|
53
|
+
|
54
|
+
# List context files for a gem
|
55
|
+
def list_context_files(gem_name)
|
56
|
+
gem_info = find_gem_with_context(gem_name)
|
57
|
+
return nil unless gem_info
|
58
|
+
|
59
|
+
Dir.glob(File.join(gem_info[:path], "**/*")).select { |f| File.file?(f) }
|
60
|
+
end
|
61
|
+
|
62
|
+
# Show content of a specific context file
|
63
|
+
def show_context_file(gem_name, file_name)
|
64
|
+
gem_info = find_gem_with_context(gem_name)
|
65
|
+
return nil unless gem_info
|
66
|
+
|
67
|
+
# Try to find the file with or without extension
|
68
|
+
possible_paths = [
|
69
|
+
File.join(gem_info[:path], file_name),
|
70
|
+
File.join(gem_info[:path], "#{file_name}.mdc"),
|
71
|
+
File.join(gem_info[:path], "#{file_name}.md")
|
72
|
+
]
|
73
|
+
|
74
|
+
file_path = possible_paths.find { |path| File.exist?(path) }
|
75
|
+
return nil unless file_path
|
76
|
+
|
77
|
+
File.read(file_path)
|
78
|
+
end
|
79
|
+
|
80
|
+
# Install context from a specific gem
|
81
|
+
def install_gem_context(gem_name)
|
82
|
+
gem_info = find_gem_with_context(gem_name)
|
83
|
+
return false unless gem_info
|
84
|
+
|
85
|
+
target_path = File.join(@context_path, gem_name)
|
86
|
+
FileUtils.mkdir_p(target_path)
|
87
|
+
|
88
|
+
# Copy all files from the gem's context directory
|
89
|
+
FileUtils.cp_r(File.join(gem_info[:path], "."), target_path)
|
90
|
+
|
91
|
+
true
|
92
|
+
end
|
93
|
+
|
94
|
+
# Install context from all gems
|
95
|
+
def install_all_context
|
96
|
+
gems = find_gems_with_context
|
97
|
+
installed = []
|
98
|
+
|
99
|
+
gems.each do |gem_info|
|
100
|
+
if install_gem_context(gem_info[:name])
|
101
|
+
installed << gem_info[:name]
|
102
|
+
end
|
103
|
+
end
|
104
|
+
|
105
|
+
installed
|
106
|
+
end
|
107
|
+
end
|
108
|
+
end
|
109
|
+
end
|
data/license.md
ADDED
@@ -0,0 +1,21 @@
|
|
1
|
+
# MIT License
|
2
|
+
|
3
|
+
Copyright, 2025, by Shopify Inc.
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
13
|
+
copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
+
SOFTWARE.
|
data/readme.md
ADDED
@@ -0,0 +1,99 @@
|
|
1
|
+
# Agent::Context
|
2
|
+
|
3
|
+
Provides tools for installing and managing context files from Ruby gems for AI agents.
|
4
|
+
|
5
|
+
[](https://github.com/ioquatix/agent-context/actions?workflow=Test)
|
6
|
+
|
7
|
+
## Overview
|
8
|
+
|
9
|
+
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.
|
10
|
+
|
11
|
+
## Context
|
12
|
+
|
13
|
+
This gem provides it's own context files in `context` and external dependencies in `.context`:
|
14
|
+
|
15
|
+
## Usage
|
16
|
+
|
17
|
+
### Installation
|
18
|
+
|
19
|
+
Add the `agent-context` gem to your project:
|
20
|
+
|
21
|
+
``` bash
|
22
|
+
$ bundle add agent-context
|
23
|
+
```
|
24
|
+
|
25
|
+
### Commands
|
26
|
+
|
27
|
+
#### List available context
|
28
|
+
|
29
|
+
List all gems that have context available:
|
30
|
+
|
31
|
+
``` bash
|
32
|
+
$ bake agent:context:list
|
33
|
+
```
|
34
|
+
|
35
|
+
List context files for a specific gem:
|
36
|
+
|
37
|
+
``` bash
|
38
|
+
$ bake agent:context:list --gem async
|
39
|
+
```
|
40
|
+
|
41
|
+
#### Show context content
|
42
|
+
|
43
|
+
Show the content of a specific context file:
|
44
|
+
|
45
|
+
``` bash
|
46
|
+
$ bake agent:context:show --gem async --file thread-safety
|
47
|
+
```
|
48
|
+
|
49
|
+
#### Install context
|
50
|
+
|
51
|
+
Install context from all available gems:
|
52
|
+
|
53
|
+
``` bash
|
54
|
+
$ bake agent:context:install
|
55
|
+
```
|
56
|
+
|
57
|
+
Install context from a specific gem:
|
58
|
+
|
59
|
+
``` bash
|
60
|
+
$ bake agent:context:install --gem async
|
61
|
+
```
|
62
|
+
|
63
|
+
This will create a `.context/` directory in your project with the installed context files organized by gem name.
|
64
|
+
|
65
|
+
## Providing Context in Your Gem
|
66
|
+
|
67
|
+
To provide context files in your gem, create a `context/` directory in your gem's root:
|
68
|
+
|
69
|
+
your-gem/
|
70
|
+
├── context/
|
71
|
+
│ ├── thread-safety.mdc
|
72
|
+
│ ├── performance.mdc
|
73
|
+
│ └── migration-guide.mdc
|
74
|
+
├── lib/
|
75
|
+
└── your-gem.gemspec
|
76
|
+
|
77
|
+
Context files can be in any format, but `.mdc` and `.md` files are commonly used for documentation.
|
78
|
+
|
79
|
+
## See Also
|
80
|
+
|
81
|
+
- [Bake](https://github.com/ioquatix/bake) — The bake task execution tool.
|
82
|
+
|
83
|
+
## Contributing
|
84
|
+
|
85
|
+
We welcome contributions to this project.
|
86
|
+
|
87
|
+
1. Fork it.
|
88
|
+
2. Create your feature branch (`git checkout -b my-new-feature`).
|
89
|
+
3. Commit your changes (`git commit -am 'Add some feature'`).
|
90
|
+
4. Push to the branch (`git push origin my-new-feature`).
|
91
|
+
5. Create new Pull Request.
|
92
|
+
|
93
|
+
### Developer Certificate of Origin
|
94
|
+
|
95
|
+
In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
|
96
|
+
|
97
|
+
### Community Guidelines
|
98
|
+
|
99
|
+
This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
|
data.tar.gz.sig
ADDED
Binary file
|
metadata
ADDED
@@ -0,0 +1,94 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: agent-context
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.0.0
|
5
|
+
platform: ruby
|
6
|
+
authors:
|
7
|
+
- Shopify Inc.
|
8
|
+
bindir: bin
|
9
|
+
cert_chain:
|
10
|
+
- |
|
11
|
+
-----BEGIN CERTIFICATE-----
|
12
|
+
MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
|
13
|
+
ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
|
14
|
+
CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
|
15
|
+
MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
|
16
|
+
MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
|
17
|
+
bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
|
18
|
+
igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
|
19
|
+
9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
|
20
|
+
sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
|
21
|
+
e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
|
22
|
+
XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
|
23
|
+
RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
|
24
|
+
tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
|
25
|
+
zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
|
26
|
+
xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
|
27
|
+
BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
|
28
|
+
aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
|
29
|
+
aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
|
30
|
+
cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
|
31
|
+
xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
|
32
|
+
c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
|
33
|
+
8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
|
34
|
+
JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
|
35
|
+
eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
|
36
|
+
Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
|
37
|
+
voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
|
38
|
+
-----END CERTIFICATE-----
|
39
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
40
|
+
dependencies:
|
41
|
+
- !ruby/object:Gem::Dependency
|
42
|
+
name: console
|
43
|
+
requirement: !ruby/object:Gem::Requirement
|
44
|
+
requirements:
|
45
|
+
- - "~>"
|
46
|
+
- !ruby/object:Gem::Version
|
47
|
+
version: '1.25'
|
48
|
+
type: :runtime
|
49
|
+
prerelease: false
|
50
|
+
version_requirements: !ruby/object:Gem::Requirement
|
51
|
+
requirements:
|
52
|
+
- - "~>"
|
53
|
+
- !ruby/object:Gem::Version
|
54
|
+
version: '1.25'
|
55
|
+
executables: []
|
56
|
+
extensions: []
|
57
|
+
extra_rdoc_files: []
|
58
|
+
files:
|
59
|
+
- bake/agent/context.rb
|
60
|
+
- context/adding-context.mdc
|
61
|
+
- context/examples.mdc
|
62
|
+
- context/getting-started.mdc
|
63
|
+
- context/markdown-context.mdc
|
64
|
+
- design.md
|
65
|
+
- lib/agent/context.rb
|
66
|
+
- lib/agent/context/helper.rb
|
67
|
+
- lib/agent/context/version.rb
|
68
|
+
- license.md
|
69
|
+
- readme.md
|
70
|
+
homepage: https://github.com/ioquatix/agent-context
|
71
|
+
licenses:
|
72
|
+
- MIT
|
73
|
+
metadata:
|
74
|
+
documentation_uri: https://ioquatix.github.io/agent-context/
|
75
|
+
funding_uri: https://github.com/sponsors/ioquatix/
|
76
|
+
source_code_uri: https://github.com/ioquatix/agent-context.git
|
77
|
+
rdoc_options: []
|
78
|
+
require_paths:
|
79
|
+
- lib
|
80
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
81
|
+
requirements:
|
82
|
+
- - ">="
|
83
|
+
- !ruby/object:Gem::Version
|
84
|
+
version: '3.2'
|
85
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
86
|
+
requirements:
|
87
|
+
- - ">="
|
88
|
+
- !ruby/object:Gem::Version
|
89
|
+
version: '0'
|
90
|
+
requirements: []
|
91
|
+
rubygems_version: 3.6.7
|
92
|
+
specification_version: 4
|
93
|
+
summary: Install and manage context files from Ruby gems.
|
94
|
+
test_files: []
|
metadata.gz.sig
ADDED
Binary file
|