Organizational

AI Agent Entrypoint

Pattern defining AGENTS.md as the mandatory entrypoint for AI coding agents in Ontopix repositories.

Production

This document defines how AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) operate within Ontopix repositories.

Core Principle

AGENTS.md is the single mandatory entrypoint for all AI agents in every Ontopix repository.

An agent MUST NOT begin work in a repository without first reading and understanding its AGENTS.md file.

What is AGENTS.md?

AGENTS.md is a proxy and router, not a knowledge dump.

Its purpose is to:

Define the repository's purpose and boundaries
Provide operational instructions (how to build, test, deploy)
Reference global patterns (via URL to engineering-patterns)
Reference local patterns (via relative paths within the repo)
State non-negotiable constraints and invariants

What MUST Live in AGENTS.md

Every AGENTS.md file MUST contain:

Repository Purpose
- One-sentence description of what this repository does
- Clear boundaries: what this repo is and is NOT responsible for
Operational Instructions
- How to run the repository in sandbox mode
- How to test the repository
- Which Taskfile tasks are available
- Any environment setup requirements
Pattern References
- Links to relevant global patterns in the engineering-patterns repository
- Links to local pattern documentation within the repository
- Explicit versioning where applicable
Constraints and Invariants
- Non-negotiable technical constraints (e.g., "must support offline mode")
- Performance requirements (e.g., "API responses must be < 200ms")
- Security boundaries (e.g., "never log PII")
- Data boundaries (e.g., "this service owns customer profiles")
Agent Escalation Rules
- When the agent MUST stop and ask for human feedback
- Which changes require human approval

What MUST NOT Live in AGENTS.md

AGENTS.md is NOT:

A complete pattern library (global patterns live in engineering-patterns, local patterns in each repository)
A duplication of README.md content
Implementation details or code examples
Historical context or changelog
Personal opinions or preferences

The Pattern Discrepancy Handling Rule

This is a critical contract.

If an AI agent (or human engineer) detects that the work being performed contradicts an existing pattern (global or local), they MUST NOT proceed silently.

Detection

A discrepancy exists when:

The proposed solution violates a documented pattern
The code structure diverges from the referenced pattern
A constraint or invariant would be broken
A convention is being ignored without justification

Required Response

When a discrepancy is detected, the agent MUST:

Stop work immediately
Explicitly surface the discrepancy with:
- Which pattern is being contradicted
- What the pattern prescribes
- What the current work is attempting to do
Propose one of two paths:
- Path A: Evolve the pattern — If the pattern is outdated or incorrect
- Path B: Introduce a justified exception — If the pattern doesn't apply here

If Path B (Exception) is Chosen

The exception MUST be:

Explicitly documented — In code comments or local documentation
Justified — With a clear explanation of why the pattern does not apply
Located close to the code — Not hidden in external documentation
Reviewable — A human MUST approve the exception

Example exception documentation:

# PATTERN EXCEPTION: authentication-flow-v2
# Reason: This endpoint requires stateless token validation for external API clients
# Pattern assumes session-based auth, which doesn't apply here
# Approved by: @engineering-lead (2025-12-10)
def validate_token_stateless(token: str) -> bool:
    ...