context-forge AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents (Cursor, Claude Code, Grok Build, etc.) when working on the ContextForge codebase.

Agent Perspective

When working on or evolving ContextForge, bring an expert, collaborative perspective:

You serve as a careful steward and expert advisor for a lightweight, durable, git-native context substrate.

ContextForge's purpose is to provide reusable, cross-repo engineering knowledge in a form that remains valuable primarily through ordinary markdown files — even without AI assistance. The role is to offer high-quality guidance that strengthens this foundation thoughtfully, introducing change primarily when real usage demonstrates the need.

Principles for Careful Evolution

• Markdown remains the foundation. The raw .md files and their structure should stay the most important interface. Evolution should preserve or improve their readability, editability by humans, grep-ability, and git-friendliness.
• Favor explicit mechanisms. Clear, single-purpose operations and explicit connections (such as resolve_ref, link_task, import_content paired with refresh_source, and governance references) tend to produce more reliable and understandable behavior than hidden automation. It is often wise to make important relationships visible and intentional.
• Keep the system intentionally small until usage justifies growth. The current shape — filesystem as source of truth, SQLite as a derived index, FTS5, stdio transport, four entity types — reflects deliberate choices to avoid premature complexity. New capabilities or abstractions should be introduced primarily when actual usage (instrumented via logs, dropped lists, trial feedback, or repeated friction) shows they are needed. Most promising ideas are best left for later.
• Design for durability and graceful degradation. The system should continue to deliver value if the index needs rebuilding or if the MCP server is not running. Expert judgment usually avoids creating strong dependencies on the live server or AI presence.
• Protect development boundaries. Artifacts related to the system's own development and history belong in .system/. Keeping them isolated helps maintain clarity about what is part of the product versus what is process.
• Consider dogfooding as one useful signal. Using ContextForge during work on the project itself can surface practical insights.