agent-context 0.0.1 → 0.1.0

data/specification.md

@@ -0,0 +1,176 @@
+# Agent Context Specification
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+Agent Context is a language-agnostic specification for providing and consuming contextual information from software packages to assist AI agents and other automated tools. This specification defines a standardized way for package authors to include supplementary documentation, examples, migration guides, and other contextual information that can be programmatically discovered and utilized.
+
+### 1.2 Problem Statement
+
+AI agents and automated tools working with software projects often lack access to the rich contextual information that package authors provide. While packages may have extensive documentation, examples, and best practices, this information is typically scattered across various sources and formats, making it difficult for automated tools to discover and utilize effectively.
+
+### 1.3 Goals
+
+- **Standardization**: Define a consistent structure for contextual information across different programming languages and ecosystems.
+- **Discoverability**: Enable automated tools to programmatically find and access contextual information.
+- **Separation of Concerns**: Clearly separate provider context from consumer context.
+- **Extensibility**: Allow for future enhancements while maintaining backward compatibility.
+
+## 2. Core Concepts
+
+### 2.1 Context Provider
+
+A **Context Provider** is any software package, library, or module that includes contextual information in its distribution. Context providers:
+
+- Include a `context/` directory in their package root.
+- Provide structured documentation and examples.
+- Follow the file format specifications defined in this document.
+- Version their context alongside their code.
+
+### 2.2 Context Consumer
+
+A **Context Consumer** is any project or tool that utilizes contextual information from its dependencies. Context consumers:
+
+- Install context from their dependencies into a `.context/` directory.
+- Use tools to discover and access available context.
+- Apply context based on file patterns and metadata.
+
+### 2.3 Context Files
+
+**Context Files** are structured documents that contain supplementary information about a package. They typically include:
+
+- Documentation beyond basic API references.
+- Configuration examples and templates.
+- Migration guides between versions.
+- Performance optimization tips.
+- Security considerations.
+- Troubleshooting guides.
+
+### 2.4 Context Installation
+
+**Context Installation** is the process of copying context files from dependencies into a consumer's local context directory, making them available for use by tools and AI agents.
+
+## 3. Directory Structure
+
+### 3.1 Provider Directory: `context/`
+
+Context providers MUST include a `context/` directory in their package root. This directory:
+
+- **Location**: Must be at the top level of the package (same level as main source directories).
+- **Purpose**: Contains all contextual information provided by the package.
+- **Distribution**: Must be included in the package's distribution artifacts.
+- **Versioning**: Must be versioned alongside the package code.
+
+Example structure:
+```
+package-root/
+├── context/
+│   ├── getting-started.md
+│   ├── configuration.md
+│   ├── troubleshooting.md
+│   └── migration/
+│       └── v2-to-v3.md
+├── src/
+└── package.json
+```
+
+### 3.2 Consumer Directory: `.context/`
+
+Context consumers SHOULD create a `.context/` directory in their project root to store installed context. This directory:
+
+- **Location**: Must be at the project root (typically where package manifests are located).
+- **Purpose**: Contains context files copied from dependencies.
+- **Organization**: Must organize context by package name in subdirectories.
+- **Exclusion**: SHOULD be excluded from version control (e.g., in `.gitignore`).
+- **Transient Nature**: Should contain only reproducible content that can be regenerated from installed packages and MUST NOT contain unique or modified files.
+
+Example structure:
+```
+project-root/
+├── .context/
+│   ├── package-a/
+│   │   ├── getting-started.md
+│   │   └── configuration.md
+│   └── package-b/
+│       └── troubleshooting.md
+├── src/
+└── package.json
+```
+
+### 3.3 Directory Separation Rationale
+
+The separation between `context/` and `.context/` serves several purposes:
+
+- **Ownership**: `context/` is controlled by the project itself, `.context/` contains external dependencies.
+- **Isolation**: Prevents conflicts between different packages' context files.
+- **Discoverability**: Makes it easy to find context for specific packages.
+- **Maintenance**: Allows independent management of provided vs. consumed context.
+
+## 4. Context File Format
+
+### 4.1 File Extensions
+
+Context files SHOULD use the following extensions:
+
+- **`.md`**: Markdown files (primary format).
+- **`.txt`**: Plain text files.
+- **`.yaml`** or **`.yml`**: YAML configuration files.
+- **`.json`**: JSON configuration files.
+
+### 4.2 Markdown Context Files
+
+Markdown files are the primary format for context files. They:
+
+- MUST use valid Markdown syntax.
+- SHOULD be named descriptively (e.g., `getting-started.md`, `configuration.md`).
+- SHOULD include clear section headers for organization.
+
+### 4.3 File Naming Conventions
+
+Context files SHOULD follow these naming conventions:
+
+- Use lowercase with hyphens for word separation.
+- Be descriptive and specific.
+- Group related files in subdirectories when appropriate.
+
+Common file names:
+- `getting-started.md`
+- `configuration.md`
+- `troubleshooting.md`
+- `performance.md`
+- `security.md`
+- `migration-guide.md`
+
+## 5. Discovery and Installation
+
+### 5.1 Discovery Process
+
+Tools MUST be able to discover context by:
+
+1. **Package Scanning**: Examining installed packages for `context/` directories.
+2. **Metadata Extraction**: Reading package manifests to identify context-providing packages.
+3. **File Enumeration**: Listing available context files for each package.
+
+The discovery process SHOULD integrate with the target language's package management system to:
+
+- Locate installed packages and their installation paths.
+- Read package metadata to identify packages that provide context.
+- Enumerate available context files within discovered packages.
+
+### 5.2 Installation Process
+
+Context installation MUST follow these principles:
+
+1. **Copy Strategy**: Context files SHOULD be copied rather than symlinked.
+2. **Namespace Isolation**: Each package's context MUST be installed in its own subdirectory.
+3. **Preserve Structure**: The internal structure of the `context/` directory MUST be preserved.
+
+### 5.3 Installation Algorithm
+
+```
+FOR each package with context:
+  CREATE directory .context/package-name/
+  COPY all files recursively from package/context/ to .context/package-name/
+END
+```

metadata

@@ -1,9 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: agent-context
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
+- Samuel Williams
 - Shopify Inc.
 bindir: bin
 cert_chain:
@@ -52,21 +53,35 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.25'
+- !ruby/object:Gem::Dependency
+  name: markly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- agent.md
 - bake/agent/context.rb
-- context/adding-context.mdc
-- context/examples.mdc
-- context/getting-started.mdc
-- context/markdown-context.mdc
-- design.md
+- context/usage.md
 - lib/agent/context.rb
-- lib/agent/context/helper.rb
+- lib/agent/context/index.rb
+- lib/agent/context/installer.rb
 - lib/agent/context/version.rb
 - license.md
+- post.md
 - readme.md
+- specification.md
 homepage: https://github.com/ioquatix/agent-context
 licenses:
 - MIT

data/context/adding-context.mdc

@@ -1,166 +0,0 @@
----
-description: When creating or updating a gem's public interface.
-alwaysApply: false
----
-# Adding Context to Your Gem
-
-## How to provide context in your gem
-
-### 1. Create a `context/` directory
-
-In your gem's root directory, create a `context/` folder:
-
-```
-your-gem/
-├── context/
-│   ├── getting-started.mdc
-│   ├── configuration.mdc
-│   └── troubleshooting.mdc
-├── lib/
-└── your-gem.gemspec
-```
-
-### 2. Add context files
-
-Create files with helpful information. Common types include:
-
-- **getting-started.mdc** - Quick start guide
-- **configuration.mdc** - Configuration options and examples
-- **troubleshooting.mdc** - Common issues and solutions
-- **migration.mdc** - Migration guides between versions
-- **performance.mdc** - Performance tips and best practices
-- **security.mdc** - Security considerations
-
-### 3. Document your context
-
-Add a section to your gem's README:
-
-```markdown
-## Context
-
-This gem provides additional context files that can be installed using `agent-context`:
-
-```bash
-bake agent:context:install --gem your-gem-name
-```
-
-Available context files:
-- `getting-started.mdc` - Quick start guide
-- `configuration.mdc` - Configuration options
-```
-
-### 4. File format
-
-Context files can be in any format, but `.mdc` and `.md` are commonly used for documentation. The content should be:
-
-- **Practical** - Include real examples
-- **Focused** - One topic per file
-- **Clear** - Easy to understand and follow
-- **Actionable** - Provide specific guidance
-
-## Example context file
-
-```markdown
-# Configuration Guide
-
-## Basic Setup
-
-Add to your Gemfile:
-```ruby
-gem "your-gem"
-```
-
-## Configuration Options
-
-```ruby
-YourGem.configure do |config|
-  config.timeout = 30
-  config.retries = 3
-end
-```
-
-## Environment Variables
-
-- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
-- `YOUR_GEM_RETRIES` - Number of retry attempts
-
-
-- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
-- `YOUR_GEM_RETRIES` - Number of retry attempts
-# Adding Context to Your Gem
-
-## How to provide context in your gem
-
-### 1. Create a `context/` directory
-
-In your gem's root directory, create a `context/` folder:
-
-```
-your-gem/
-├── context/
-│   ├── getting-started.mdc
-│   ├── configuration.mdc
-│   └── troubleshooting.mdc
-├── lib/
-└── your-gem.gemspec
-```
-
-### 2. Add context files
-
-Create files with helpful information. Common types include:
-
-- **getting-started.mdc** - Quick start guide
-- **configuration.mdc** - Configuration options and examples
-- **troubleshooting.mdc** - Common issues and solutions
-- **migration.mdc** - Migration guides between versions
-- **performance.mdc** - Performance tips and best practices
-- **security.mdc** - Security considerations
-
-### 3. Document your context
-
-Add a section to your gem's README:
-
-```markdown
-## Context
-
-This gem provides additional context files that can be installed using `bake agent:context:install`.
-```
-
-### 4. File format
-
-Context files can be in any format, but `.mdc` and `.md` are commonly used for documentation. The content should be:
-
-- **Practical** - Include real examples
-- **Focused** - One topic per file
-- **Clear** - Easy to understand and follow
-- **Actionable** - Provide specific guidance
-
-## Example context file
-
-```markdown
-# Configuration Guide
-
-## Basic Setup
-
-Add to your Gemfile:
-```ruby
-gem "your-gem"
-```
-
-## Configuration Options
-
-```ruby
-YourGem.configure do |config|
-  config.timeout = 30
-  config.retries = 3
-end
-```
-
-## Environment Variables
-
-- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
-- `YOUR_GEM_RETRIES` - Number of retry attempts
-
-
-- `YOUR_GEM_TIMEOUT` - Connection timeout in seconds
-- `YOUR_GEM_RETRIES` - Number of retry attempts

data/context/examples.mdc

@@ -1,92 +0,0 @@
----
-description: Practical examples of using agent-context.
-alwaysApply: false
----
-
-# Practical Examples
-
-## Example 1: Installing context from a web framework
-
-```bash
-# Install context from Rails
-bake agent:context:install --gem rails
-
-# See what Rails provides
-bake agent:context:list --gem rails
-
-# View Rails configuration guide
-bake agent:context:show --gem rails --file configuration
-```
-
-## Example 2: Getting help with a specific gem
-
-```bash
-# You're having trouble with the async gem
-bake agent:context:list --gem async
-
-# Check the troubleshooting guide
-bake agent:context:show --gem async --file troubleshooting
-
-# Install all async context for offline reference
-bake agent:context:install --gem async
-```
-
-## Example 3: Discovering new gems
-
-```bash
-# See what context is available in your project
-bake agent:context:list
-
-# Install context from all gems
-bake agent:context:install
-
-# Browse the installed context
-ls .context/
-```
-
-## Example 4: Working with multiple gems
-
-```bash
-# Install context from your main dependencies
-bake agent:context:install --gem rack
-bake agent:context:install --gem sinatra
-bake agent:context:install --gem puma
-
-# Now you have context for your web stack
-ls .context/
-# => rack/ sinatra/ puma/
-```
-
-## Example 5: Using context in your workflow
-
-```bash
-# Before starting a new feature
-bake agent:context:install --gem the-gem-you're-using
-
-# Read the getting started guide
-cat .context/the-gem-you're-using/getting-started.mdc
-
-# Check performance tips
-cat .context/the-gem-you're-using/performance.mdc
-```
-
-## Real-world scenario
-
-You're building a Rails API and want to understand how to properly configure Puma:
-
-```bash
-# Install Puma context
-bake agent:context:install --gem puma
-
-# Read the configuration guide
-cat .context/puma/configuration.mdc
-
-# Check performance recommendations
-cat .context/puma/performance.mdc
-```
-
-This gives you practical, gem-specific guidance that might not be in the main documentation.
-description:
-globs:
-alwaysApply: false
----

data/context/getting-started.mdc

@@ -1,56 +0,0 @@
----
-description: Getting started with agent-context.
-alwaysApply: false
----
-
-# Getting Started
-
-## What is this?
-
-`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.
-
-## Quick Commands
-
-```bash
-# See what context is available
-bake agent:context:list
-
-# Install all available context
-bake agent:context:install
-
-# Install context from a specific gem
-bake agent:context:install --gem async
-
-# See what context files a gem provides
-bake agent:context:list --gem async
-
-# View a specific context file
-bake agent:context:show --gem async --file thread-safety
-```
-
-## What happens when you install context?
-
-When you run `bake agent:context:install`, the tool:
-
-1. Scans all installed gems for `context/` directories
-2. Creates a `.context/` directory in your current project
-3. Copies context files organized by gem name
-
-For example:
-```
-your-project/
-├── .context/
-│   ├── async/
-│   │   ├── thread-safety.mdc
-│   │   └── performance.mdc
-│   └── rack/
-│       └── middleware.mdc
-```
-
-## Why use this?
-
-- **Discover hidden documentation** that gems provide
-- **Get practical examples** and guidance
-- **Understand best practices** from gem authors
-- **Access migration guides** and troubleshooting tips
-

data/context/markdown-context.mdc

@@ -1,91 +0,0 @@
----
-globs: *.mdc
-alwaysApply: false
----
-# Creating `.mdc` (Markdown Context) Files
-
-## What is an `.mdc` file?
-
-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.
-
-## Structure
-
-### 1. YAML Frontmatter (Optional but Recommended)
-
-Start your `.mdc` file with a YAML frontmatter block:
-
-```yaml
----
-description: Short summary of the file's purpose
-globs: "test/**/*.rb,lib/**/*.rb"   # Optional: comma-separated file patterns
-alwaysApply: false                  # Optional: should this context always be applied?
----
-```
-
-**Fields:**
-- `description` (required): Short, human-readable summary.
-- `globs` (optional): Comma-separated string of file patterns this context applies to.
-- `alwaysApply` (optional): Whether to always apply this context (default: false).
-
-### 2. Markdown Content
-
-After the frontmatter, write your documentation in standard Markdown:
-
-~~~markdown
-# Title
-
-## Section
-
-- Bullet points
-- More details
-
-```ruby
-# Code examples
-```
-~~~
-
-## Best Practices
-
-- **Start with a clear description** in the YAML frontmatter.
-- **Use headings** (`#`, `##`) to organize content.
-- **Keep each file focused** on a single topic.
-- **Include code examples** where relevant.
-- **Use lists** for options, steps, or best practices.
-- **Be concise and actionable.**
-- **Use tags and globs** to help agents and tools categorize and apply context.
-
-## Example `.mdc` File
-
-~~~markdown
----
-description: How to configure the gem for production use.
-globs: config/my_gem.rb
-alwaysApply: false
----
-
-# Production Configuration
-
-To configure my_gem for production:
-
-1. Set the environment variable:
-   ```sh
-   export GEM_ENV=production
-   ```
-2. Update your config file:
-   ```ruby
-   MyGem.configure do |config|
-     config.mode = :production
-   end
-   ```
-3. Restart your application.
-~~~
-
-## When to Use `.mdc` Files
-
-- To provide documentation, guides, or metadata for your gem.
-- To expose best practices, migration guides, or troubleshooting tips.
-- To help AI agents and tools discover and apply context automatically.
-
-## Further Reading
-- [YAML Frontmatter Spec](https://jekyllrb.com/docs/front-matter/)
-- [Markdown Guide](https://www.markdownguide.org/)