agent-context 0.0.2 → 0.1.1

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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-context
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,33 +40,34 @@ cert_chain:
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: console
+  name: bake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.25'
+        version: '0.23'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.25'
+        version: '0.23'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- agent.md
 - bake/agent/context.rb
-- context/adding-context.md
-- context/examples.md
-- context/getting-started.md
-- 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.md

@@ -1,162 +0,0 @@
-# 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.md
-│   ├── configuration.md
-│   └── troubleshooting.md
-├── lib/
-└── your-gem.gemspec
-```
-
-### 2. Add context files
-
-Create files with helpful information. Common types include:
-
-- **getting-started.md** - Quick start guide
-- **configuration.md** - Configuration options and examples
-- **troubleshooting.md** - Common issues and solutions
-- **migration.md** - Migration guides between versions
-- **performance.md** - Performance tips and best practices
-- **security.md** - 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.md` - Quick start guide
-- `configuration.md` - Configuration options
-```
-
-### 4. File format
-
-Context files can be in any format, but `.md` 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.md
-│   ├── configuration.md
-│   └── troubleshooting.md
-├── lib/
-└── your-gem.gemspec
-```
-
-### 2. Add context files
-
-Create files with helpful information. Common types include:
-
-- **getting-started.md** - Quick start guide
-- **configuration.md** - Configuration options and examples
-- **troubleshooting.md** - Common issues and solutions
-- **migration.md** - Migration guides between versions
-- **performance.md** - Performance tips and best practices
-- **security.md** - 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 `.md` 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.md

@@ -1,87 +0,0 @@
-# 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.md
-
-# Check performance tips
-cat .context/the-gem-you're-using/performance.md
-```
-
-## 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.md
-
-# Check performance recommendations
-cat .context/puma/performance.md
-```
-
-This gives you practical, gem-specific guidance that might not be in the main documentation.
-description:
-globs:
-alwaysApply: false
----

data/context/getting-started.md

@@ -1,51 +0,0 @@
-# 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.md
-│   │   └── performance.md
-│   └── rack/
-│       └── middleware.md
-```
-
-## 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/design.md

@@ -1,149 +0,0 @@
-# Design Document: agent-context
-
-## Problem Statement
-
-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.
-
-## Core Design Principles
-
-### 1. Context as a First-Class Concept
-
-Context files are treated as a first-class part of a gem's public interface, alongside the code itself. This means:
-- Context files are versioned with the gem.
-- They're distributed as part of the gem package.
-- They're discoverable and accessible programmatically.
-- They follow a consistent structure and format.
-
-### 2. Machine-Readable, Human-Friendly
-
-Context files use `.md` (Markdown Context) format, which combines:
-- **Human readability**: Standard Markdown for easy authoring and reading.
-- **Machine structure**: YAML frontmatter for metadata and organization.
-- **Extensibility**: Can include code examples, diagrams, and structured data.
-
-### 3. Separation of Concerns
-
-The design separates three distinct concerns:
-- **Public Interface**: `context/` directory in gem root (what gem authors provide).
-- **Private Working Directory**: `.context/` in consuming projects (where context is installed).
-- **Tool Interface**: `bake agent:context:*` commands (how users interact).
-
-## Architecture Decisions
-
-### File Organization Strategy
-
-**Decision**: Context files are installed into `.context/gem-name/` subdirectories
-
-**Rationale**:
-- **Isolation**: Prevents conflicts between different gems' context files.
-- **Discoverability**: Easy to find context for a specific gem.
-- **Scalability**: Supports installing context from multiple gems.
-- **Clear Ownership**: Obvious which context files belong to which gem.
-
-### Command Structure
-
-**Decision**: Use `bake agent:context:*` command namespace
-
-**Rationale**:
-- **Consistency**: Matches the gem name `agent-context`.
-- **Clarity**: Makes it obvious these commands are for AI agent workflows.
-- **Namespace Safety**: Avoids conflicts with other gem-related commands.
-- **Tool Integration**: Leverages existing Bake infrastructure.
-
-### Module Structure
-
-**Decision**: Use `Agent::Context` module namespace
-
-**Rationale**:
-- **Purpose Clarity**: Explicitly indicates this is for AI agents.
-- **Namespace Safety**: Avoids potential conflicts with RubyGems' `Gem::` namespace.
-- **Future-Proof**: Won't conflict if RubyGems adds their own context features.
-
-## Context File Design
-
-### YAML Frontmatter
-
-Context files support structured metadata:
-```yaml
----
-description: Short summary of the file's purpose
-globs: "test/**/*.rb,lib/**/*.rb"  # Comma-separated file patterns
-alwaysApply: false                  # Whether to always apply this context
----
-```
-
-**Design Decisions**:
-- **`description`**: Required human-readable summary.
-- **`globs`**: Optional file patterns this context applies to.
-- **`alwaysApply`**: Optional flag for context that should always be available.
-- **No tags**: Keeps the format simple and focused.
-
-### File Naming Conventions
-
-- **`.md` extension**: Indicates Markdown Context files.
-- **Descriptive names**: `thread-safety.md`, `performance.md`, `migration-guide.md`.
-- **Fallback support**: Commands can find files with or without extensions.
-
-## Installation Strategy
-
-### Copy vs. Symlink
-
-**Decision**: Copy files rather than symlink
-
-**Rationale**:
-- **Offline Access**: Context remains available even if gems are uninstalled.
-- **Version Stability**: Context doesn't change if gem is updated.
-- **Project Independence**: Context becomes part of the project's knowledge base.
-- **Simplicity**: No symlink management or broken link issues.
-
-### Directory Structure
-
-```
-project/
-├── .context/           # Private working directory
-│   ├── async/         # Context from async gem
-│   │   ├── thread-safety.md
-│   │   └── performance.md
-│   └── rails/         # Context from rails gem
-│       └── configuration.md
-```
-
-## Use Cases and Workflows
-
-### For Gem Authors
-
-1. **Create Context Directory**: Add `context/` to gem root.
-2. **Write Context Files**: Create `.md` files with documentation, examples, guides.
-3. **Version and Distribute**: Context files are included in gem releases.
-
-### For Developers
-
-1. **Discover Context**: `bake agent:context:list` to see available context.
-2. **Install Context**: `bake agent:context:install --gem async` to copy locally.
-3. **Access Context**: AI agents can read from `.context/` directory.
-
-### For AI Agents
-
-1. **Scan Context**: Read from `.context/` directory for relevant information.
-2. **Apply Context**: Use glob patterns to determine which context applies.
-3. **Provide Guidance**: Reference gem-specific documentation and examples.
-
-## Future Considerations
-
-### Potential Enhancements
-
-- **Context Validation**: Validate `.md` file structure and content.
-- **Context Indexing**: Create searchable index of installed context.
-- **Context Updates**: Mechanism to update context when gems are updated.
-- **Context Dependencies**: Allow context files to reference other context files.
-
-### Integration Opportunities
-
-- **IDE Integration**: Context-aware code completion and documentation.
-- **CI/CD Integration**: Validate context files during gem releases.
-- **Documentation Sites**: Generate context-aware documentation.
-- **AI Agent Frameworks**: Direct integration with AI agent platforms.
-
-## Conclusion
-
-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.