Decisions

ADR-0002: AI Agent Entrypoint

Decision to require AGENTS.md as mandatory entrypoint for AI agents in every repository.

ApprovedNo MCP

Status: Accepted

Date: 2025-12-16

Deciders: Engineering Leadership

Context

AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) are becoming integral to Ontopix engineering workflows. However, agents face challenges:

  • Context Discovery: Agents don't know where to start in a new repository
  • Operational Instructions: Agents don't know how to build, test, or run code
  • Pattern Adherence: Agents may violate organizational patterns unknowingly
  • Constraint Awareness: Agents don't know non-negotiable requirements
  • Escalation: Agents don't know when to request human feedback

Without a standardized entrypoint, agents either:

  1. Make dangerous assumptions
  2. Ask excessive questions upfront
  3. Violate patterns silently
  4. Fail to operate the repository correctly

We need a single, mandatory, standardized entrypoint for AI agents in every repository.

Decision

We will require every Ontopix repository to contain an AGENTS.md file at the repository root.

AGENTS.md is a Proxy and Router

AGENTS.md is NOT a knowledge dump. It is a proxy and router that:

  • Defines repository purpose and boundaries
  • Provides operational instructions (via Taskfile references)
  • References global patterns (via URLs to engineering-patterns)
  • References local patterns (via relative paths)
  • States non-negotiable constraints
  • Defines escalation rules (when to ask humans)

Required Contents

Every AGENTS.md MUST contain:

  1. Repository Purpose
    • One-sentence description
    • Clear boundaries (what this repo IS and IS NOT)
  2. Operational Instructions
    • How to run in sandbox mode
    • How to test
    • Available Taskfile tasks
    • Environment setup
  3. Pattern References
    • Links to global patterns (engineering-patterns repo)
    • Links to local patterns (within repo)
    • Explicit versioning where needed
  4. Constraints and Invariants
    • Non-negotiable technical requirements
    • Performance requirements
    • Security boundaries
    • Data constraints
  5. Escalation Rules
    • When agent MUST stop and ask for human feedback
    • Architecture changes
    • Infrastructure changes
    • External contracts
    • High-risk operations

Pattern Discrepancy Handling Rule

AGENTS.md MUST include the pattern discrepancy handling rule:

If an agent detects work contradicting an existing pattern, it MUST:

  1. Stop immediately
  2. Surface the discrepancy explicitly
  3. Propose either:
    • Path A: Evolve the pattern (with justification)
    • Path B: Document a justified exception

Agents MUST NOT:

  • Silently ignore patterns
  • Proceed without surfacing discrepancies
  • Introduce undocumented exceptions

Rationale

Why a Standardized File?

Consistency:

  • Every repository has the same agent entrypoint
  • Engineers know AGENTS.md exists in every repo
  • Agents have predictable starting point

Discoverability:

  • Obvious location (repository root)
  • Obvious name (AGENTS.md)
  • No guessing required

Versioned:

  • Lives in version control
  • Changes tracked in git history
  • Can be reviewed in pull requests

Self-Documenting:

  • Agents read instructions from the repository itself
  • No external documentation required
  • Instructions always in sync with code

Why "AGENTS.md" Instead of Other Names?

Considered alternatives:

  • AI.md — Too vague
  • ASSISTANT.md — Not specific enough
  • CLAUDE.md — Vendor-specific
  • COPILOT.md — Vendor-specific
  • .agentrules — Hidden, less discoverable
  • Including in README.md — Mixes human and agent audiences

Why AGENTS.md wins:

  • Clear and descriptive
  • Vendor-agnostic
  • Visible (not hidden)
  • Separate from README.md
  • Conventional .md format

Why Proxy Instead of Knowledge Dump?

Avoids Duplication:

  • Patterns live in engineering-patterns
  • AGENTS.md links to patterns, doesn't duplicate them
  • Changes propagate automatically

Reduces Maintenance:

  • Patterns evolve independently
  • AGENTS.md stays focused
  • Less drift between repositories

Improves Agent Efficiency:

  • Smaller file for agents to read
  • References reduce token usage
  • Focus on repository-specific context

Why Pattern Discrepancy Rule?

Prevents Silent Violations:

  • Agents may not know patterns exist
  • Silent violations discovered too late
  • Explicit contract prevents assumptions

Enables Pattern Evolution:

  • Discrepancies reveal outdated patterns
  • Feedback loop improves patterns
  • Exceptions surface special cases

Documents Deviations:

  • Justified exceptions are explicit
  • Future engineers understand why
  • Prevents "why does this work differently?" questions

Consequences

Positive

Predictable Agent Behavior:

  • Agents have clear starting point
  • Operational instructions explicit
  • Pattern adherence enforced

Reduced Friction:

  • Less back-and-forth with agents
  • Fewer dangerous assumptions
  • Clear escalation rules

Better Pattern Adherence:

  • Agents reference patterns
  • Discrepancies surfaced immediately
  • Exceptions documented explicitly

Human Oversight:

  • Clear escalation rules
  • Human approval for high-risk changes
  • Architecture decisions remain human-led

Repository Consistency:

  • Same structure across all repos
  • Same operational interface
  • Predictable for engineers and agents

Negative

Additional File to Maintain:

  • Every repository needs AGENTS.md
  • Must be kept up to date
  • Can drift if neglected

Potential Duplication:

  • Some content overlaps with README.md
  • Risk of information being in both places
  • Requires discipline to avoid duplication

Pattern Reference Breakage:

  • External URLs can break
  • Pattern versioning needed
  • Link maintenance required

Mitigations

Templates Provided:

  • templates/AGENTS.md.tpl available
  • Clear structure defined
  • Easy to create for new repos

PR Reviews:

  • AGENTS.md changes reviewed
  • Patterns referenced correctly
  • Escalation rules appropriate

Automated Checks:

  • CI validates AGENTS.md exists
  • Link checkers (future)
  • Pattern reference validation (future)

Clear Separation:

  • README.md for humans
  • AGENTS.md for agents
  • Minimal overlap enforced

Alternatives Considered

Alternative 1: Include in README.md

Rejected because:

  • Mixes human and agent audiences
  • README already serves humans
  • Hard to structure for both audiences
  • Agents need different information than humans

Alternative 2: Separate File Per Agent (CLAUDE.md, cursor rules)

Rejected as primary approach because:

  • Duplication across agent-specific files
  • Common instructions not shared
  • More files to maintain
  • However: Agent-specific files are OPTIONAL supplements to AGENTS.md

Alternative 3: External Documentation Platform

Rejected because:

  • Not version-controlled with code
  • Can drift from code
  • Not accessible to agents without API
  • Additional infrastructure to maintain

Alternative 4: No Standard (Ad-hoc Comments/Docs)

Rejected because:

  • Inconsistent across repositories
  • Hard for agents to discover
  • No enforcement
  • No pattern adherence mechanism

References

Success Criteria

This decision is successful if:

  • Every repository has AGENTS.md
  • Agents consistently read AGENTS.md first
  • Pattern violations are surfaced explicitly
  • Agents know when to escalate to humans
  • Maintenance burden is reasonable
  • Engineers find AGENTS.md useful (not just agents)

ADR-0001: Pattern Library Organization

Decision to organize engineering knowledge into three levels with patterns in this repository.

ADR-0003: Taskfile as Contract

Decision to use Taskfile as the mandatory operational contract for repository operations.