ADR-0010: Repository Context Directory Convention

Context

Ontopix repositories rely on AGENTS.md (ADR-0002) as the entrypoint for AI coding agents. This works well for operational instructions — what tools to use, how to run tests, what conventions to follow. However, it does not address a growing need: persistent, structured context that accumulates across sessions and is shared between contributors and their AI agents.

Today, each developer's AI agent starts every session with limited knowledge: it reads AGENTS.md, the code, and git history. But architectural decisions, debugging notes, audit results, feature specs, and operational patterns learned during previous sessions are lost unless manually documented somewhere. This leads to:

• Repeated discovery: Agents (and humans) rediscover the same architectural constraints, edge cases, and patterns session after session.
• Context fragmentation: Some knowledge lives in Slack threads, some in PR descriptions, some in developer-local notes. None of it is discoverable by agents in future sessions.
• No shared agent memory: When developer A's agent learns a pattern, developer B's agent has no way to access that knowledge.
• Spec and plan sprawl: Feature specifications, implementation plans, and task breakdowns have no canonical location — they end up in PR descriptions, Notion pages, or temporary files.

The .context/ directory addresses this by providing a structured, version-controlled location for repository knowledge that is explicitly designed to be consumed by both humans and AI agents.

Decision

Every Ontopix repository MAY include a .context/ directory at the repository root, following a standardized structure. The directory serves as the repository's knowledge base — a shared context layer between contributors (human and AI) that persists across sessions.

Directory Structure

.context/
├── agents/                        # Knowledge base FOR agents (and humans who work with agents)
│   ├── api/                       # Contracts — internal and external API surfaces
│   ├── architecture/              # How the system is built — structure, components, repo-local ADRs, tech debt
│   │   ├── decisions/
│   │   │   └── ADR-001-<slug>.md
│   │   ├── overview.md
│   │   └── tech-debt.md
│   ├── changelogs/                # Notable changes worth surfacing beyond git log
│   ├── operations/                # How to run it — deploy, debug, environments, incident response
│   │   ├── debugging.md
│   │   ├── deployment.md
│   │   └── environments.md
│   ├── prd/                       # What we're building and why — product requirements, goals, priorities
│   │   └── current.md
│   ├── patterns/                  # What we've learned — recurring solutions, conventions, exceptions
│   │   ├── index.md               # All patterns, 3 lines each — append-only
│   │   └── <pattern-slug>.md      # Extended doc for complex patterns (optional)
│   ├── spec/                      # How to build a specific feature — design → spec → plan → tasks
│   │   └── <feature>/
│   │       ├── design.md
│   │       ├── spec.md
│   │       ├── plan.md
│   │       └── tasks.md
│   └── audits/                    # Compliance evidence — checklists and timestamped reports
│       ├── checklists/
│       │   └── <domain>.md
│       └── reports/
│           └── <domain>-<YYYY-MM-DD>.md
├── docs/                          # Content FOR humans, may be published to docs.ontopix.dev
└── scratchpad/                    # Notes worth keeping across sessions

See the companion pattern for a full folder semantics table.

Key Principles

1. Structured by purpose, not by date. Content is organized by what it describes (architecture, patterns, specs), not when it was written.
2. Agents as first-class consumers. The agents/ subtree is explicitly designed for agent consumption — concise, machine-parseable, cross-referenced. Agents MUST read patterns/index.md at session start.
3. Patterns are append-only. The patterns/index.md file is an append-only registry of decisions and conventions learned during development. Each entry is 3 sentences maximum. Extended documentation goes in a companion <slug>.md file.
4. Specs live with their feature. Feature specifications, plans, and task breakdowns are co-located under spec/<feature>/, not scattered across external tools.
5. Audits are timestamped and structured. Checklists define what to check; reports record the results with PASS/FAIL/EXCEPTION per item.
6. Delete, don't archive. .context/ is version-controlled — git history is the archive. Outdated specs, deprecated decisions, and superseded PRDs should be deleted to keep the directory current and avoid stale content misleading agents.

Gitignore Strategy

The .context/ directory follows a promotion lifecycle:

Repositories currently experimenting with .context/ SHOULD add it to .gitignore. Once this ADR is approved, .context/ SHOULD be committed in all active repositories.

Implementation

For new repositories

Include .context/ in the repository scaffold (see Repository Structure pattern). At minimum, create:

.context/
└── agents/
    └── patterns/
        └── index.md    # Empty, with header: "# Agent Patterns — {repo-name}"

For existing repositories

1. Create the .context/agents/patterns/ directory.
2. Create index.md with any patterns already known from the codebase.
3. Remove .context/ from .gitignore if present.
4. Add patterns incrementally as they are discovered during development.

Agent startup protocol

Agents MUST include .context/agents/patterns/index.md in their startup reads, alongside AGENTS.md and task --list. The recommended startup sequence becomes:

1. Read AGENTS.md — operational instructions
2. Run task --list — available operations
3. Read .context/agents/patterns/index.md — accumulated patterns and decisions
4. Query ontopix-docs MCP — org-level patterns for the current task type

Pattern registration

When an agent (or human) makes a non-obvious decision during development, it MUST be registered in patterns/index.md before the task is marked complete. Format:

## <Pattern Name>

**Context:** <one sentence — what problem this solves>
**Decision:** <one or two sentences — what was decided and why>
**Applies to:** <this repo / all repos / specific layer>

---

If more than 3 sentences are needed, create .context/agents/patterns/<slug>.md and link to it.

Alternatives Considered

Keep everything in AGENTS.md

AGENTS.md is already the agent entrypoint. We could expand it to include patterns, specs, and architectural context. Rejected because AGENTS.md would grow unboundedly and mix operational instructions with accumulated knowledge. The entrypoint should be stable and concise; the knowledge base should grow.

Use a wiki or external tool (Notion, Confluence)

External tools are not accessible to AI agents during coding sessions without additional MCP integrations. The knowledge needs to be in the repo, version-controlled, and available offline.

Use git commit messages and PR descriptions as the knowledge base

This is where much of this context currently lives. But it is not discoverable — agents cannot efficiently search git history for "what pattern did we use for X?". Structured files with a known location solve discoverability.

Put patterns in CLAUDE.md

CLAUDE.md is a personal or project-level instruction file for Claude Code specifically. It is not version-controlled in team repos and is not accessible to other AI tools. .context/ is tool-agnostic and team-shared.

Consequences

Positive

• Agents accumulate and share knowledge across sessions and contributors — no more repeated discovery.
• Feature specs, plans, and task breakdowns have a canonical, version-controlled location.
• Audit results are structured and timestamped, enabling compliance tracking over time.
• The pattern registry creates an append-only institutional memory for each repository.
• The structure is tool-agnostic — works with Claude Code, Cursor, Copilot, or any agent that can read files.

Negative / Trade-offs

• Adds another directory to learn and maintain. Mitigated by clear structure and agent-driven population.
• Risk of stale content if patterns are not maintained. Mitigated by making registration part of the task completion checklist.
• Initial overhead to populate .context/ in existing repositories. Mitigated by incremental adoption — start with patterns/index.md only.

Applies Principles

• Ownership & Responsibility — each pattern entry identifies what it applies to; audit reports are timestamped and attributable.
• Automation Over Manual Work — agents populate and consume the knowledge base as part of their normal workflow.
• Long-Term Thinking — accumulated context compounds over time; each session makes the next one more productive.
• Evidence Over Assumptions — patterns are registered when discovered, not assumed from memory.

Related

• ADR-0002 — Agents Entrypoint — .context/ complements AGENTS.md, not replaces it
• ADR-0001 — Pattern Library Organization — org-level patterns in the handbook; .context/ is for repo-level patterns
• Pattern: Repository Context Directory — implementation guide for this decision