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/
├── 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
├── roadmaps/                      # Medium-term outcomes, phases, and sequencing
│   └── YYYYMMDD-<slug>.md
├── patterns/                      # What we've learned — recurring solutions
│   ├── index.md
│   └── <pattern-slug>.md
├── epics/                         # Atomic, independently deliverable units of development
│   └── YYYYMMDD-<slug>/           # YYYYMMDD = creation date (stable identity and ordering)
│       ├── spec.md                # Required: delivery contract
│       ├── plan.md                # Required: implementation approach and tasks
│       ├── design.md              # Optional: alternatives and detailed design
│       ├── tasks.md               # Optional: extracted work queue
│       └── handoff.md             # Optional: continuation state between sessions
├── audits/                        # Domain audit evidence (security, a11y, …) — kept with history
│   ├── checklists/
│   │   └── <domain>.md
│   └── reports/
│       └── <domain>-<YYYY-MM-DD>.md
├── compliance/                    # Org-pattern compliance — accepted exceptions + latest report
│   ├── exceptions.md              # Accepted exceptions — human-maintained
│   ├── report.md                  # Latest check-compliance report — generated, overwritten
│   └── decisions/                 # Optional extended justifications
│       └── 001-<slug>.md
└── scratchpad/                    # Notes worth keeping across sessions

The .context/ directory holds contextual knowledge for the repository as a whole — useful to both AI agents and human contributors. Not all subdirectories are required. Start with patterns/index.md and expand as needed.

Folder Semantics

Each folder under .context/ 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
• roadmaps = the where we're going and in what outcome sequence — medium-term direction
• epics = the what and how of the next atomic delivery — per-unit planning and execution
• operations = the how to run and fix in production
• audits = point-in-time domain audit evidence, kept with history
• compliance = current standing against org patterns — accepted exceptions + latest report

The planning hierarchy and artifact contracts under roadmaps/ and epics/ are defined by Roadmap and Epic Planning. This pattern defines their canonical location and boundary; it does not duplicate their lifecycle or metadata rules.

No archive folders

.context/ is version-controlled. Deprecated decisions, superseded PRDs, and planning artifacts that no longer provide current context should be deleted — git history provides the archive. Completed epics MAY remain while they explain an active roadmap or the current system; durable knowledge must be promoted to architecture, patterns, operations, or API documentation before obsolete planning context is removed. No archive/ subdirectories are needed.

Implementation

Step 1: Create the minimal structure

mkdir -p .context/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/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>

Roadmaps and Epics

A roadmap captures one medium-term repository outcome and defines its phases in a single roadmaps/YYYYMMDD-<slug>.md file. An epic is one atomic, independently reviewable and deliverable change, normally mapped to one branch and one pull request.

Each epic lives under epics/YYYYMMDD-<slug>/. spec.md and plan.md are required before execution; design.md, tasks.md, and handoff.md are optional. Tasks normally live in plan.md and are extracted to tasks.md only when that improves readability or work-queue management. handoff.md records continuation state when an active epic spans sessions.

Use Roadmap and Epic Planning for identifiers, metadata, lifecycle, content contracts, branch naming, and delivery rules.

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)

Compliance

The compliance/ folder records this repository's standing against org-level Ontopix patterns — which deviations have been accepted, and the latest report produced by the check-compliance skill. It is distinct from audits/: audits hold point-in-time, domain-specific evidence (security, accessibility, …) with a timestamped history; compliance tracks the current state against the engineering handbook and keeps only the latest report.

.context/compliance/
├── exceptions.md      # Accepted exceptions — human-maintained, never tool-written
├── report.md          # Latest compliance report — generated, overwritten each run
└── decisions/         # Optional extended justifications, linked from the files above
    ├── 001-<slug>.md
    └── 002-<slug>.md

exceptions.md — accepted exceptions

Human-maintained. Lists deviations from org patterns that are intentional and justified — for example, a repo on Amplify Hosting that does not need deploy:* Taskfile tasks. The check-compliance skill reads this file before evaluating and renders a listed deviation as ACCEPTED instead of VIOLATION.

# Compliance Exceptions

<!-- Accepted exceptions for this repo. Maintained by humans. -->
<!-- The check-compliance skill reads this file before evaluating. -->

## <pattern-name> / <requirement>

- **Status**: ACCEPTED
- **Justification**: <one-line reason>
- **Detail**: [decisions/001-slug.md](decisions/001-slug.md)  <!-- optional -->
- **Owner**: @handle
- **Revisit when**: <condition>

report.md — latest compliance report

Generated and overwritten on every check-compliance run; never edited by hand. Each finding carries one of four statuses: PASS, ACCEPTED (a deviation matched in exceptions.md), VIOLATION, or SUGGESTION.

# Compliance Report

_Generated: YYYY-MM-DD by check-compliance skill_

## Summary

| Status | Count |
|--------|-------|
| PASS | 25 |
| ACCEPTED | 5 |
| VIOLATION | 3 |
| SUGGESTION | 2 |

## Findings

### taskfile-contract

| Requirement | Status | Notes |
|-------------|--------|-------|
| `build` task | PASS | |
| `deploy:staging` | ACCEPTED | Deployment handled by Amplify Hosting. See [decisions/002-taskfile-deploy.md](decisions/002-taskfile-deploy.md) |
| `dev:up` / `dev:down` | VIOLATION | Pattern requires these names; repo uses `dev:run` and `sandbox:*` |

decisions/ — extended justifications

Optional. When a one-line justification in exceptions.md is not enough, add a numbered file (001-<slug>.md, 002-<slug>.md, …) with the full rationale and link it from both exceptions.md and report.md.

Lifecycle

Boundaries

• vs audits/ — a security or accessibility audit report belongs in audits/ (kept with history); the handbook-conformance report belongs in compliance/ (latest only).
• vs patterns/index.md — patterns/index.md may note an accepted exception in passing as agent working memory, but compliance/exceptions.md is the canonical, structured source of truth that tooling consumes. Point the index entry at exceptions.md rather than duplicating the justification.

Tooling contract

The check-compliance skill (in ontopix/claude-setup) MUST:

1. Read compliance/exceptions.md before evaluating.
2. Render a deviation listed there as ACCEPTED — with its justification inline — instead of VIOLATION.
3. Write its output to compliance/report.md, overwriting the previous report.
4. Never modify exceptions.md or decisions/.

AI Agent Rules

Agents working in repositories with .context/ MUST:

• Read patterns/index.md at session start — before any implementation work
• Register new patterns before marking a task complete
• Store roadmaps in roadmaps/YYYYMMDD-<slug>.md, never at the repo root
• Store epics in epics/YYYYMMDD-<slug>/, never at the repo root
• When working on an epic, read its spec.md, plan.md, and any linked roadmap context before implementation
• Delete outdated content rather than archiving — git history is the archive
• Read compliance/exceptions.md before reporting an org-pattern deviation — a listed exception is ACCEPTED, not a VIOLATION; never hand-edit compliance/report.md
• 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
• Roadmap and Epic Planning — planning hierarchy, artifact contracts, metadata, and delivery conventions

References

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