repo-context-forge AGENTS.md

AGENTS.md

Project Purpose

repo-context-forge is a local-first MCP-based repository intelligence platform. It creates compact, source-grounded repository context packs for coding agents such as Codex, Claude Code, and Cursor. The v0.2 alpha also contains an experimental local model provider, MCP client runtime, and read-only source-grounded agent loop.

Architecture Rules

• CLI code must not contain domain logic.
• MCP tools must delegate to service classes.
• Domain services must not depend on Typer or FastMCP.
• Filesystem paths must use pathlib.Path.
• Repository-relative paths must never be trusted without validation.
• Repository access must eventually be limited to configured workspace roots.
• Generated summaries must preserve source file and line references.
• Avoid oversized utility modules.
• Prefer explicit typed models over loosely structured dictionaries.
• Avoid hidden global state.
• Do not use eval.
• Do not use shell string interpolation.
• Do not introduce unrestricted subprocess execution.
• Do not silently ignore security failures.
• Do not fabricate repository facts when source evidence is unavailable.
• Never import or execute analyzed repository code.
• Never use shell search commands for repository intelligence.
• Static-analysis limitations must be surfaced honestly.
• Source references must remain repository-relative.
• Git subprocess use is allowed only through the safe Git runner.
• Only explicitly allowlisted read-only Git commands and flags are permitted.
• Analyzed repositories must never be mutated.
• Dependency manifests must never be executed.
• Dynamic dependency information must not be fabricated.
• Context artifacts must never fabricate repository facts.
• Deterministic facts and architectural inferences must remain explicitly separated.
• Generated output must remain outside analyzed repositories by default.
• Context manifests, configuration hashes, and artifact hashes must remain stable and validated.
• Provider code must not log prompts or complete model responses by default.
• API keys must never be logged or included in public model summaries.
• LLM output is untrusted input and must be validated into project-owned models.
• Tool-call arguments must always be validated before future use.
• Models must never execute tools directly; execution belongs to a future controlled runtime.
• MCP child processes must be explicitly allowlisted through trusted local configuration.
• Never invoke MCP server commands through a shell; use SDK stdio transport with argument lists.
• MCP server stdout is reserved exclusively for protocol messages; diagnostics belong on stderr.
• MCP tool arguments require local JSON Schema validation before every request.
• MCP tool schemas and results are untrusted input and must remain bounded.
• Every MCP session, transport, and child process must close on success, failure, and timeout.
• Model output is never trusted and cannot expand configured tool permissions.
• An agent run is locked to one configured workspace; model-requested workspace switching is forbidden.
• Agent citations must be validated against source evidence observed during that run.
• Duplicate tool loops and all configured iteration, message, and result limits must terminate safely.
• Default agent tools must remain read-only; context generation and task-bundle writes are excluded.
• Agent provider and MCP manager lifecycles must close on every success and failure path.