Repository Structure

Minimum Required Files

Every Ontopix repository MUST contain the following files at the repository root:

my-repository/
├─ README.md          # Human-oriented documentation
├─ AGENTS.md          # AI agent entrypoint and contract
├─ Taskfile.yaml      # Operational interface
├─ .editorconfig      # Editor consistency
└─ CODEOWNERS         # Ownership and review assignments

File Purposes

README.md

Audience: Humans Purpose: Explain what the repository is and why it exists

README.md MUST contain:

• What this repository is — One-sentence description
• Why it exists — Business or technical purpose
• Key concepts — Domain-specific terminology
• Architecture overview — High-level system design (if applicable)
• Getting started — How to run locally (or reference to Taskfile)

README.md SHOULD contain:

• Links to related repositories
• Links to relevant documentation
• Contributing guidelines (or link to CONTRIBUTING.md)

README.md SHOULD NOT contain:

• Operational instructions (those belong in Taskfile and AGENTS.md)
• Detailed API documentation (those belong in code or separate docs)
• Implementation details (those belong in code comments)

Template: See templates/README.md.tpl

AGENTS.md

Audience: AI agents (Claude Code, Cursor, GitHub Copilot, etc.) Purpose: Provide explicit operational context and constraints

AGENTS.md MUST contain:

• Repository purpose — What this repository does
• Operational instructions — How to build, test, run
• Pattern references — Links to global and local patterns
• Constraints — Non-negotiable requirements
• Escalation rules — When to request human feedback

See principles/agents.md for complete requirements.

Template: See templates/AGENTS.md.tpl

Taskfile.yaml

Audience: Humans and AI agents Purpose: Expose all repository operations through a consistent interface

Taskfile.yaml MUST contain:

• Standard task namespaces (dev, test, lint, sandbox, infra)
• Descriptions for all tasks
• Dependencies between tasks (where applicable)

See principles/taskfile.md for complete requirements.

Template: See templates/Taskfile.yaml.tpl

.editorconfig

Audience: Code editors and IDEs Purpose: Ensure consistent formatting across editors and developers

.editorconfig MUST define:

• Indentation style (spaces vs tabs)
• Indentation size
• Line endings (LF)
• Character encoding (UTF-8)
• Trailing whitespace handling

Example:

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{js,jsx,ts,tsx,json,yml,yaml}]
indent_style = space
indent_size = 2

[*.{py,go}]
indent_style = space
indent_size = 4

[Makefile]
indent_style = tab

CODEOWNERS

Audience: GitHub Purpose: Define ownership and default reviewers for pull requests

CODEOWNERS MUST define:

• Default owners for the entire repository
• Specific owners for critical paths (if needed)

Example:

# CODEOWNERS

# Default owners for everything
* @ontopix/engineering

# Infrastructure owned by platform team
/.infra/ @ontopix/platform

# Security-sensitive code requires security team review
/src/auth/ @ontopix/security

# API contracts require architect review
/src/api/schema/ @ontopix/architects

Why CODEOWNERS Exists:

• Ensures appropriate review for critical changes
• Makes ownership explicit
• Automates reviewer assignment
• Distributes review load appropriately

Optional But Recommended Files

LICENSE

If the repository is open-source or has licensing requirements:

LICENSE

CONTRIBUTING.md

If the repository has specific contribution guidelines:

CONTRIBUTING.md

.gitignore

To prevent committing generated files, secrets, or environment-specific files:

.gitignore

.github/

For CI/CD pipelines, issue templates, and pull request templates:

.github/
├─ workflows/
│  ├─ ci.yml
│  ├─ test.yml
│  ├─ release.yml
│  └─ deploy.yml
├─ ISSUE_TEMPLATE/
└─ PULL_REQUEST_TEMPLATE.md

CHANGELOG.md

For tracking changes between releases:

CHANGELOG.md

Directory Conventions

Source Code

Application code SHOULD live in:

• src/ (most languages)
• lib/ (libraries)
• cmd/ (Go command-line tools)
• Language-specific conventions as appropriate

Tests

Tests SHOULD live in:

• tests/ (separate test directory)
• __tests__/ (JavaScript convention)
• test/ (acceptable alternative)
• Co-located with source (for some languages like Go)

Infrastructure

Infrastructure-as-code MUST live in:

• .infra/ (see principles/infra.md)

Documentation

Additional documentation SHOULD live in:

• docs/ (comprehensive documentation)
• docs/api/ (API documentation)
• docs/architecture/ (architecture decision records)
• docs/patterns/ (local patterns used in the repository)

Scripts

Utility scripts SHOULD live in:

• scripts/ (bash, python, etc.)
• Exposed through Taskfile when reusable

Configuration

Configuration files SHOULD live at repository root or in:

• config/ (application configuration)
• .infra/ (infrastructure configuration)

Local Developer Files

Repositories SHOULD support a .local/ directory for developer-specific files:

• This directory MUST be added to .gitignore
• Files in this directory MUST NOT be committed

Repository Categories

Application Repository

Contains application code and related infrastructure:

my-service/
├─ src/
├─ tests/
├─ .infra/
├─ README.md
├─ AGENTS.md
├─ Taskfile.yaml
├─ .editorconfig
└─ CODEOWNERS

Library Repository

Contains reusable code without infrastructure:

my-library/
├─ src/
├─ tests/
├─ README.md
├─ AGENTS.md
├─ Taskfile.yaml
├─ .editorconfig
└─ CODEOWNERS

Infrastructure Repository

Contains platform infrastructure (exception to .infra/ rule):

infra/
├─ platform/
├─ shared-services/
├─ README.md
├─ AGENTS.md
├─ Taskfile.yaml
├─ .editorconfig
└─ CODEOWNERS

Monorepo

Contains multiple applications or libraries:

monorepo/
├─ apps/
│  ├─ frontend/
│  └─ backend/
├─ libs/
│  ├─ shared/
│  └─ ui-components/
├─ README.md
├─ AGENTS.md            # Top-level agent entrypoint
├─ Taskfile.yaml        # Top-level orchestration
├─ .editorconfig
└─ CODEOWNERS

Validation

To validate that a repository meets minimum requirements:

# Taskfile.yaml
validate:structure:
  desc: Validate repository structure
  cmds:
    - |
      missing=()
      for file in README.md AGENTS.md Taskfile.yaml .editorconfig CODEOWNERS; do
        [ -f "$file" ] || missing+=("$file")
      done
      if [ ${#missing[@]} -ne 0 ]; then
        echo "❌ Missing required files: ${missing[*]}"
        exit 1
      fi
      echo "✅ All required files present"

New Repository Checklist

When creating a new Ontopix repository:

1. ✅ Copy templates/README.md.tpl → README.md and customize
2. ✅ Copy templates/AGENTS.md.tpl → AGENTS.md and customize
3. ✅ Copy templates/Taskfile.yaml.tpl → Taskfile.yaml and customize
4. ✅ Create .editorconfig matching Ontopix standards
5. ✅ Create CODEOWNERS with appropriate owners
6. ✅ Add .gitignore for language/framework
7. ✅ Set up CI/CD pipelines in .github/workflows/
8. ✅ Configure branch protection rules
9. ✅ Link to relevant patterns in AGENTS.md
10. ✅ Test that task --list shows useful operations

Evolution and Exceptions

When to Deviate

Repositories MAY deviate from these conventions when:

• Language or framework conventions conflict strongly
• The repository has a unique purpose requiring special structure
• External constraints require different organization

How to Document Exceptions

Exceptions MUST be documented in:

• README.md — Explain why the structure differs
• AGENTS.md — Explain how agents should navigate the non-standard structure

Related Patterns

• AI Agent Entrypoint — AGENTS.md requirements
• Taskfile as Contract — Taskfile.yaml requirements
• Infrastructure Layout — .infra/ convention
• Sandbox Environments — Sandbox task requirements

Templates

All required files have templates in the templates/ directory:

• templates/README.md.tpl
• templates/AGENTS.md.tpl
• templates/Taskfile.yaml.tpl

See templates/README.md for usage instructions.