agent-context 0.3.0 → 0.4.0

data/specification.md

@@ -15,7 +15,7 @@ AI agents and automated tools working with software projects often lack access t
 - **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.
+- **Extensibility**: Preserve additional provider-authored metadata alongside the fields defined by this specification.
 
 ## 2. Core Concepts
 
@@ -32,9 +32,10 @@ A **Context Provider** is any software package, library, or module that includes
 
 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.
+- Install context from their dependencies into a `.agents/context/` directory.
+- May install skill-marked context documents into a `.agents/skills/` directory.
 - Use tools to discover and access available context.
-- Apply context based on file patterns and metadata.
+- Read and apply guidance relevant to the task.
 
 ### 2.3 Context Files
 
@@ -47,6 +48,10 @@ A **Context Consumer** is any project or tool that utilizes contextual informati
 - Security considerations.
 - Troubleshooting guides.
 
+A **Definition** is one installable unit loaded from a provider: an ordinary file, or a skill document together with its companion resources. A parsed **Document** represents the Markdown source and front matter of a definition. Files such as images and examples remain opaque.
+
+A definition's **path** is its filename relative to the provider's `context/` directory, including any subdirectories and extension. Its **source path** locates the authored file in the installed package. A skill's **installed name** is its authored or derived `name`, used for its destination directory. These identifiers serve different purposes.
+
 ### 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.
@@ -63,6 +68,7 @@ Context providers MUST include a `context/` directory in their package root. Thi
 - **Versioning**: Must be versioned alongside the package code.
 
 Example structure:
+
 ```
 package-root/
 ├── context/
@@ -75,20 +81,23 @@ package-root/
 └── package.json
 ```
 
-### 3.2 Consumer Directory: `.context/`
+### 3.2 Consumer Directory: `.agents/context/`
 
-Context consumers SHOULD create a `.context/` directory in their project root to store installed context. This directory:
+Context consumers SHOULD create a `.agents/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`).
+- **Organization**: Must organize context by resolved provider in subdirectories named by a package selector.
+- **Exclusion**: The generated `.agents/context/` directory SHOULD be excluded from version control. A Git integration SHOULD add local exclusions to `.git/info/exclude` so projects do not need to commit rules for generated files. Other project-owned files may live directly under `.agents/`.
 - **Transient Nature**: Should contain only reproducible content that can be regenerated from installed packages and MUST NOT contain unique or modified files.
 
+A package selector identifies one resolved provider. It is normally the package name. Consumers that support multiple resolved versions MUST distinguish them, for example with `package-a@1.0.0` and `package-a@2.0.0`. Tools SHOULD display accepted selectors when listing providers and use those selectors consistently in commands and installed directory names.
+
 Example structure:
+
 ```
 project-root/
-├── .context/
+├── .agents/context/
 │   ├── package-a/
 │   │   ├── getting-started.md
 │   │   └── configuration.md
@@ -100,9 +109,9 @@ project-root/
 
 ### 3.3 Directory Separation Rationale
 
-The separation between `context/` and `.context/` serves several purposes:
+The separation between `context/` and `.agents/context/` serves several purposes:
 
-- **Ownership**: `context/` is controlled by the project itself, `.context/` contains external dependencies.
+- **Ownership**: `context/` is controlled by the project itself, `.agents/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.
@@ -135,6 +144,7 @@ Context files SHOULD follow these naming conventions:
 - Group related files in subdirectories when appropriate.
 
 Common file names:
+
 - `getting-started.md`
 - `configuration.md`
 - `troubleshooting.md`
@@ -142,6 +152,29 @@ Common file names:
 - `security.md`
 - `migration-guide.md`
 
+### 4.4 Skill Documents
+
+A context provider may distribute an Agent Skill as a Markdown document directly inside `context/`. The document MUST use YAML front matter with `metadata.type: skill` and a non-empty top-level `description`:
+
+```yaml
+---
+name: provider-workflow
+description: Run the provider workflow when preparing a project.
+metadata:
+  type: skill
+---
+```
+
+Within a context document's YAML `metadata` mapping, the string `skill` declares a skill. Consumers MUST treat all other `metadata.type` values, including absent, null, and unfamiliar values, as ordinary context. This allows providers to introduce new types while existing consumers continue installing their documents. Consumers MUST interpret only mappings as context metadata; other values of `metadata` are unrelated authored data and MUST be retained as ordinary context.
+
+An authored top-level `name` MUST be preserved and used as the installed directory name. When `name` is absent, consumers MUST derive it from the lowercase provider package name (normalizing underscores to hyphens), a hyphen, and the source filename without its `.md` extension. Installed names MUST use lowercase ASCII letters, digits, and single hyphens, contain 1–64 characters, and begin and end with a letter or digit. Descriptions MUST contain 1–1,024 characters after trimming whitespace for validation; consumers MUST retain the authored description value.
+
+Consumers MUST install the document as `.agents/skills/<name>/SKILL.md`. A companion directory named after the source filename without its extension MAY provide resources, independently of the installed name. Its files MUST be copied into the installed skill directory. Consumers MUST retain additional top-level fields and nested metadata, except for the resolved installation provenance defined in section 7. Skill documents and their resources belong exclusively to the installed skill.
+
+Consumers MUST preserve the original Markdown body bytes following the front matter. Front matter formatting MAY be normalized during serialization.
+
+Dependency-installed skill directories SHOULD be excluded from version control, while project-owned skills in `.agents/skills/` SHOULD remain trackable. Git integrations SHOULD add exact dependency-installed skill paths to `.git/info/exclude` rather than ignore the entire `.agents/skills/` directory. They SHOULD mark generated entries with comments and preserve user-authored rules outside that marked section.
+
 ## 5. Discovery and Installation
 
 ### 5.1 Discovery Process
@@ -163,14 +196,60 @@ The discovery process SHOULD integrate with the target language's package manage
 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.
+2. **Namespace Isolation**: Each resolved provider's ordinary context MUST be installed in its own subdirectory, named by its package selector.
+3. **Preserve Structure**: The internal structure of ordinary context files MUST be preserved.
+4. **Skill Separation**: Skill documents and their resources MUST be installed as skills only, not duplicated as ordinary context.
 
-### 5.3 Installation Algorithm
+Consumers SHOULD validate document data as part of loading or parsing it and use that validated representation when applying changes. Installation MAY use direct file writes and copies. Consumers MUST report failures; completed changes and partially written output MAY remain after an error. After resolving the reported failure, consumers SHOULD support refreshing generated output by rerunning installation.
 
+### 5.3 Installation Steps
+
+For each selected provider:
+
+1. Classify its context documents and identify companion skill resource directories, keeping their contents opaque.
+2. If skills are supported, install each declared skill once as `.agents/skills/<name>/SKILL.md` and copy its companion resources into that skill directory.
+3. Copy the remaining ordinary files into `.agents/context/<selector>/`, preserving their relative paths.
+
+Skill documents and their resources are excluded from ordinary context copying even when the consumer does not support skill installation.
+
+## 6. Discovering Installed Context
+
+Consumers SHOULD provide commands to list providers, list their definitions, and show a selected definition. Agents discover installed guidance by enumerating Markdown files under `.agents/context/<selector>/` and reading the files relevant to their task. A packaged usage skill SHOULD explain this workflow and how to install missing guidance.
+
+Providers SHOULD use descriptive filenames, keep guides focused on one topic, and link related documents. Ordinary documents need no front matter. Unrelated ordinary-document metadata MUST be tolerated. Skill resource files are opaque assets and MUST NOT be parsed as context documents.
+
+Provider lookup identifies dependencies with a `context/` directory, including empty directories. An empty provider has no definitions; listing commands MAY omit it from the available guidance list. Refreshing an empty provider still reconciles its installed output.
+
+Showing a definition MUST return its authored content. Lookup MUST prefer an exact provider-relative path, then that path with `.md` appended when no extension was supplied. Consumers MAY also accept installed skill names as a fallback after source path lookup. Definition paths retain their filename case and extension. Generated skill instructions add installation provenance when installed.
+
+The installed directory layout is the discovery interface.
+
+## 7. Skill Installation Ownership
+
+Consumers MUST record resolved installation provenance inside `SKILL.md` front matter:
+
+```yaml
+---
+name: provider-workflow
+description: Run the provider workflow when preparing a project.
+metadata:
+  type: skill
+  ecosystem: cargo
+  package: provider
+  version: "1.0.0"
+---
 ```
-FOR each package with context:
-  CREATE directory .context/package-name/
-  COPY all files recursively from package/context/ to .context/package-name/
-END
-```
+
+The installer supplies `metadata.ecosystem`, `metadata.package`, and `metadata.version` from its resolved provider, overriding source values for these fields. Ruby gems use `gem`; Cargo crates use `cargo`. These three fields MUST be non-empty strings, including a quoted version when YAML would otherwise decode it as a number. Additional metadata MUST be retained.
+
+Consumers MUST discover ownership by scanning direct child directories of `.agents/skills/` and parsing their `SKILL.md` files. The skills root and managed skill directories MUST be regular directories. Symbolic links and non-directory children are skipped. Instruction files MUST be regular files. Managed directory names MUST satisfy section 4.4.
+
+`metadata.type: skill` together with an explicit `metadata.ecosystem` identifies installation provenance. Consumers MUST validate the complete provenance tuple after recognizing that discriminator, and report malformed or unreadable metadata. Other directories are project-owned; an authored `metadata.version` alone is ordinary skill metadata.
+
+A full refresh reconciles the installer's ecosystem; a package refresh reconciles that ecosystem and package. Full reconciliation includes providers removed from the dependency graph and providers that become empty. Consumers MUST retain skills belonging to other ecosystems and packages outside the requested scope, and MUST reject conflicting destinations.
+
+Installers SHOULD write `SKILL.md` before copying companion resources, establishing ownership for subsequent refreshes. If writing the instructions fails, installers SHOULD remove that incomplete destination. Resource-copy failures leave completed instructions in place. The incremental failure behavior in section 5.2 applies to skills and Git exclusion updates.
+
+The top-level resource name `SKILL.md` is reserved case-insensitively for generated instructions. Consumers MUST reject a resource file or directory with that name. Nested files with that name and other resource names are copied as opaque assets.
+
+Git integrations SHOULD maintain one marked exclusion block per consuming project, covering generated context and exact dependency-owned skill directories from all ecosystems. Exclusion paths MUST be relative to the Git repository root. Nested projects SHOULD identify their block by appending the repository-relative project path, with a trailing slash, to the `# BEGIN bake-agent-context` and `# END bake-agent-context` markers. They MUST retain user-authored rules and blocks belonging to other projects. Installed instructions and resources are excluded with their containing skill directory.

data.tar.gz.sig

@@ -1,3 +1,4 @@
-i>J9k���7�TZ�V�{�c���t_7$38�#��iz����fǦ�M�׀�
-�m
-�&���,U_q�c4�U_���	wH����O.d)��8�8�T9�s�eQř����q@��V�3e��0Cf����ל_c��]��������/Ь[��:ӧ �Y+�'Z�&v�~?�<�sL�x���az�$�$��'�s�:��L��Jy����y��q���_ڣ
�6s���m���;�g���E\��l*�U�eq�����{�L^Y�ʅ�\�_�Nƌ<��宂�\�z�O�	Ip��F� ץ���"
+g���
+p�˺Xc�%m�~�8�
+��(��p��`�B���ƫ���N�����:���,fdd�sD]�iL�r�S�'��1eT���<��LB�Ww�����Z�+��A�A7�##k4�7�x*���\��౅	����k�&�x����`:��P��6����!Q�#^!
+�5i6��"{���_r�
v"����BN�"X���%��H�΅�S�*���Z���uG��-{����� Ń�����NrV����ف>Ʀ�=����=�ʾJtr+��MםV=��2q�,��"���?�t��ݖ�X��>�R\o�I����|(��a���*ےN�45S��O͋sX��./$�N�

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-context
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -10,32 +10,28 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
-  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
-  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
-  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
-  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
-  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
-  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
-  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
-  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
-  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
-  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
-  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
-  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
-  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
-  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
-  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
-  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
-  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
-  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
+  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
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -53,6 +49,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: markly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -60,9 +70,19 @@ files:
 - bake/agent/context.rb
 - context/getting-started.md
 - context/index.yaml
+- context/usage.md
+- design.md
 - lib/agent/context.rb
-- lib/agent/context/index.rb
+- lib/agent/context/definition.rb
+- lib/agent/context/document.rb
+- lib/agent/context/errors.rb
+- lib/agent/context/exclusion.rb
 - lib/agent/context/installer.rb
+- lib/agent/context/package.rb
+- lib/agent/context/paths.rb
+- lib/agent/context/skills.rb
+- lib/agent/context/skills/definition.rb
+- lib/agent/context/skills/ownership.rb
 - lib/agent/context/version.rb
 - license.md
 - post.md
@@ -73,6 +93,8 @@ homepage: https://github.com/ioquatix/agent-context
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/ioquatix/agent-context/issues
+  changelog_uri: https://github.com/ioquatix/agent-context/blob/main/releases.md
   documentation_uri: https://ioquatix.github.io/agent-context/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/ioquatix/agent-context.git
@@ -83,14 +105,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.21
 specification_version: 4
-summary: Install and manage context files from Ruby gems.
+summary: Install and manage context files and skills from Ruby gems.
 test_files: []

data/lib/agent/context/index.rb

@@ -1,325 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
-# Copyright, 2025, by Shopify Inc.
-
-require_relative "version"
-require "fileutils"
-require "yaml"
-
-# @namespace
-module Agent
-	# @namespace
-	module Context
-		# Represents an index for managing and generating agents.md files from context files.
-		# 
-		# This class provides functionality to update or create AGENTS.md files following
-		# the AGENTS.md specification for agentic coding tools. It can parse existing
-		# agents.md files, update the context section, and generate new files when needed.
-		class Index
-			# Initialize a new index instance.
-			# @parameter context_path [String] The path to the context directory (default: ".context").
-			def initialize(context_path = ".context")
-				@context_path = context_path
-			end
-			
-			attr :context_path
-			
-			# Update or create an AGENTS.md file in the project root with context section
-			# This follows the AGENTS.md specification for agentic coding tools
-			def update_agents_md(agents_md_path = "agents.md")
-				context_content = generate_context_section
-				
-				if File.exist?(agents_md_path)
-					update_existing_agents_md(agents_md_path, context_content)
-				else
-					create_new_agents_md(agents_md_path, context_content)
-				end
-				
-				Console.debug("Updated agents.md: #{agents_md_path}")
-			end
-			
-			# Generate just the context section content (without top-level headers)
-			def generate_context_section
-				sections = []
-				
-				sections << "This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`."
-				sections << ""
-				sections << "**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**"
-				sections << ""
-				sections << "**Setup Instructions:** If the referenced files are not present or if dependencies have been updated, run `bake agent:context:install` to install the latest context files."
-				sections << ""
-				
-				gem_contexts = collect_gem_contexts
-				
-				if gem_contexts.empty?
-					sections << "No context files found. Run `bake agent:context:install` to install context from gems."
-					sections << ""
-				else
-					gem_contexts.each do |gem_name, files|
-						sections << "### #{gem_name}"
-						sections << ""
-						
-						# Get gem directory and load index
-						gem_directory = File.join(@context_path, gem_name)
-						index = load_gem_index(gem_name, gem_directory)
-						
-						# Add gem description from index
-						if index["description"]
-							sections << index["description"]
-							sections << ""
-						end
-						
-						# Use files from index if available, otherwise fall back to parsing
-						if index["files"] && !index["files"].empty?
-							index["files"].each do |file_info|
-								sections << "#### [#{file_info['title']}](.context/#{gem_name}/#{file_info['path']})"
-								sections << ""
-								sections << file_info["description"] if file_info["description"] && !file_info["description"].empty?
-								sections << ""
-							end
-						else
-							# Fallback to parsing files directly
-							files.each do |file_path|
-								if File.exist?(file_path)
-									title, description = extract_content(file_path)
-									relative_path = file_path.sub("#{@context_path}/", "")
-									sections << "#### [#{title}](.context/#{relative_path})"
-									sections << ""
-									sections << description if description && !description.empty?
-									sections << ""
-								end
-							end
-						end
-					end
-				end
-				
-				sections.join("\n")
-			end
-			
-			private
-			
-			def update_existing_agents_md(agents_md_path, context_content)
-				content = File.read(agents_md_path)
-				
-				# Find the # Agent heading
-				agent_heading_line = find_agent_heading_line(content)
-				
-				if agent_heading_line
-					# Find or create the ## Context section
-					context_section = find_context_section_under_agent(content, agent_heading_line)
-					
-					if context_section
-						# Replace existing context section
-						updated_content = replace_context_section(content, context_section, context_content)
-					else
-						# Insert new context section after agent heading
-						updated_content = insert_context_section_after_agent(content, agent_heading_line, context_content)
-					end
-				else
-					# No # Agent heading found, prepend it with context
-					updated_content = prepend_agent_with_context(content, context_content)
-				end
-				
-				# Write the updated content back to file
-				File.write(agents_md_path, updated_content)
-			end
-			
-			def create_new_agents_md(agents_md_path, context_content)
-				content = [
-					"# Agent",
-					"",
-					"## Context",
-					"",
-					context_content,
-				].join("\n")
-				File.write(agents_md_path, content)
-			end
-			
-			def find_agent_heading_line(content)
-				lines = content.lines
-				lines.each_with_index do |line, index|
-					if line.strip.start_with?("# ") && line.strip.downcase == "# agent"
-						return index
-					end
-				end
-				nil
-			end
-			
-			def find_context_section_under_agent(content, agent_line_index)
-				lines = content.lines
-				
-				# Look for ## Context after the agent heading
-				(agent_line_index + 1).upto(lines.length - 1) do |index|
-					line = lines[index]
-					if line.strip == "## Context"
-						return index
-					elsif line.strip.start_with?("# ") && line.strip != "# Agent"
-						# We've hit another top-level heading, stop searching
-						break
-					end
-				end
-				
-				nil
-			end
-			
-			def replace_context_section(content, context_line_index, context_content)
-				lines = content.lines
-				
-				# Find the end of the context section
-				end_index = find_section_end(lines, context_line_index, 2)
-				
-				# Build the new content
-				new_lines = []
-				new_lines.concat(lines[0...context_line_index])
-				new_lines << "## Context\n"
-				new_lines << "\n"
-				new_lines.concat(context_content.lines)
-				new_lines.concat(lines[end_index..-1])
-				
-				new_lines.join
-			end
-			
-			def insert_context_section_after_agent(content, agent_line_index, context_content)
-				lines = content.lines
-				
-				# Build the new content
-				new_lines = []
-				new_lines.concat(lines[0..agent_line_index])
-				new_lines << "\n"
-				new_lines << "## Context\n"
-				new_lines << "\n"
-				new_lines.concat(context_content.lines)
-				new_lines.concat(lines[agent_line_index + 1..-1])
-				
-				new_lines.join
-			end
-			
-			def prepend_agent_with_context(content, context_content)
-				agent_context = [
-					"# Agent",
-					"",
-					"## Context",
-					"",
-					context_content,
-					""
-				].join("\n")
-				agent_context + content
-			end
-			
-			def find_section_end(lines, start_index, heading_level)
-				index = start_index + 1
-				
-				while index < lines.length
-					line = lines[index]
-					
-					if line.strip.start_with?("#")
-						level = line.strip.match(/^(#+)/)[1].length
-						if level <= heading_level
-							break
-						end
-					end
-					
-					index += 1
-				end
-				
-				index
-			end
-			
-			def collect_gem_contexts
-				gem_contexts = {}
-				
-				return gem_contexts unless Dir.exist?(@context_path)
-				
-				Dir.glob(File.join(@context_path, "*")).each do |gem_directory|
-					next unless File.directory?(gem_directory)
-					gem_name = File.basename(gem_directory)
-					
-					markdown_files = Dir.glob(File.join(gem_directory, "**", "*.md")).sort
-					gem_contexts[gem_name] = markdown_files if markdown_files.any?
-				end
-				
-				gem_contexts
-			end
-			
-			# Load a gem's index file
-			def load_gem_index(gem_name, gem_directory)
-				index_path = File.join(gem_directory, "index.yaml")
-				
-				if File.exist?(index_path)
-					YAML.load_file(index_path)
-				else
-					# Return a fallback index if no index.yaml exists
-					{
-						"description" => "Context files for #{gem_name}",
-						"files" => []
-					}
-				end
-			rescue => error
-				Console.debug("Error loading index for #{gem_name}: #{error.message}")
-				# Return a fallback index
-				{
-					"description" => "Context files for #{gem_name}",
-					"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
-		end
-	end
-end