Repository Context Directory

Status: Approved Type: Organizational (Recommended) ADR: ADR-0010 — Repository Context Directory Convention

Problem

AI coding agents start each session with no memory of previous sessions. Architectural decisions, debugging patterns, feature specs, and operational knowledge discovered during development are lost unless manually documented. This leads to repeated discovery, fragmented context, and no shared memory between contributors' agents.

Context

When to Use This Pattern

• Any repository where AI coding agents are used regularly
• Repositories with multiple contributors whose agents need shared context
• Projects with non-trivial architecture, operational patterns, or client-specific conventions

When NOT to Use This Pattern

• Single-file scripts or trivial utilities
• Repositories where no AI agents are used

Solution

Add a .context/ directory at the repository root with a standardized structure optimized for both human and agent consumption.

Directory Structure

.context/
├── agents/                        # Knowledge base FOR agents
│   ├── api/                       # Contracts — internal and external API surfaces
│   ├── architecture/              # How the system is built
│   │   ├── 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, incident response
│   │   ├── debugging.md
│   │   ├── deployment.md
│   │   └── environments.md
│   ├── prd/                       # What we're building and why
│   │   └── current.md
│   ├── patterns/                  # What we've learned — recurring solutions
│   │   ├── index.md
│   │   └── <pattern-slug>.md
│   ├── spec/                      # How to build a specific feature
│   │   └── <feature>/
│   │       ├── design.md
│   │       ├── spec.md
│   │       ├── plan.md
│   │       └── tasks.md
│   └── audits/                    # Compliance evidence
│       ├── checklists/
│       │   └── <domain>.md
│       └── reports/
│           └── <domain>-<YYYY-MM-DD>.md
├── docs/                          # Content for humans (may publish to docs site)
└── scratchpad/                    # Notes worth keeping across sessions

Not all subdirectories are required. Start with agents/patterns/index.md and expand as needed.

Folder Semantics

Each folder under agents/ has a distinct purpose. Understanding the boundaries prevents content from ending up in the wrong place.

Key distinctions:

• prd = the what and why from a product perspective
• architecture = the how at the structural level
• patterns = the how we've done it before — accumulated wisdom
• spec = the how we'll build this specific thing — per-feature, ephemeral
• operations = the how to run and fix in production

No archive folders

.context/ is version-controlled. Outdated specs, deprecated decisions, and superseded PRDs should be deleted — git history provides the archive. No archive/ subdirectories needed.

Implementation

Step 1: Create the minimal structure

mkdir -p .context/agents/patterns

Step 2: Initialize patterns/index.md

# Agent Patterns — {repo-name}

<!-- Append-only. Each entry: 3 sentences max. Link extended docs if needed. -->

Step 3: Remove from .gitignore (when promoted)

If .context/ is currently gitignored, remove the entry once the team agrees to share it:

# Remove .context/ from .gitignore
sed -i '' '/.context/d' .gitignore

Step 4: Update personal CLAUDE.md, repo AGENTS.md, or rely on ontopix-plugin

The startup protocol is fundamentally this:

## Startup Protocol

1. Read this file (`AGENTS.md`)
2. Run `task --list`
3. Read `.context/agents/patterns/index.md`

Should be added somewhere to guarantee all sessions follows the protocol.

If https://github.com/ontopix/claude-setup already provides this, then this step is not needed.

Pattern Registration

Register a pattern when any of the following occurs:

• A non-obvious architectural decision is made
• A naming or structural convention is established for the first time
• A tool integration pattern is resolved
• An exception to an Ontopix global pattern is justified

Format — entry in patterns/index.md

## <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>

---

Rules:

• 3 sentences maximum per entry
• If more needed, create patterns/<slug>.md and link it
• No preamble, no filler
• Exceptions to org patterns: add **Exception to:** <pattern name or MCP path>

Feature Specs

Feature specifications live under spec/<feature>/ with a consistent structure:

Agents use tasks.md as their work queue. Each task maps to one atomic commit.

Audit Workflow

1. Define a checklist in audits/checklists/<domain>.md
2. Run the audit (agent or human)
3. Produce a report in audits/reports/<domain>-<YYYY-MM-DD>.md
4. Report format: PASS / FAIL / EXCEPTION per checklist item
5. For each FAIL: propose a fix + effort estimate (trivial / small / large)

AI Agent Rules

Agents working in repositories with .context/ MUST:

• Read agents/patterns/index.md at session start — before any implementation work
• Register new patterns before marking a task complete
• Store feature specs in agents/spec/<feature>/, never at the repo root
• Delete outdated content rather than archiving — git history is the archive
• Surface pattern conflicts with org-level patterns (from MCP) rather than silently diverging

Applies Principles

• Automation Over Manual Work — agents populate the knowledge base as part of their workflow
• Ownership & Responsibility — patterns identify scope; audits are timestamped
• Long-Term Thinking — accumulated context compounds; each session makes the next more productive
• Consistency — same structure across all repositories

Consequences

Related Patterns

• Agents Entrypoint — .context/ complements AGENTS.md, not replaces it
• Repository Structure — .context/ fits within the standard repo layout

References

• ADR-0010 — Repository Context Directory Convention
• ADR-0002 — Agents Entrypoint