Skip to content
Orator Docs

Team Context

Orator’s automatic pattern detection works well out of the box, but you can go further by defining context rules — custom rules that control exactly what context gets served for different types of queries. This is especially valuable for teams with established conventions, architectural decision records (ADRs), or specific context that AI tools should always know about.

Context Rule Types

There are four types of context rules:

Path Rules

Path rules associate specific file paths with query topics. When a query matches the topic, the specified files are always included in the context.

Terminal window
curl -X POST https://api.orator.dev/v1/context-rules \
  -H "Authorization: Bearer orator_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryId": "01JQKX8F7Y2M3N4P5R6S7T8V9W",
    "ruleType": "path",
    "pattern": "auth",
    "context": "src/middleware/auth.ts,src/services/auth-service.ts,src/types/auth.ts",
    "priority": 10
  }'

This rule ensures that any query mentioning “auth” always includes the core authentication files, even if the knowledge graph might otherwise prioritize other results.

File Type Rules

File type rules prioritize certain file extensions for specific query topics.

Terminal window
curl -X POST https://api.orator.dev/v1/context-rules \
  -H "Authorization: Bearer orator_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryId": "01JQKX8F7Y2M3N4P5R6S7T8V9W",
    "ruleType": "file_type",
    "pattern": "styling|css|design",
    "context": ".css,.scss,.module.css",
    "priority": 5
  }'

When someone asks about styling, CSS and SCSS files are prioritized in the results.

Query Type Rules

Query type rules match specific query patterns and inject additional context. These are useful for embedding team knowledge and ADRs.

Terminal window
curl -X POST https://api.orator.dev/v1/context-rules \
  -H "Authorization: Bearer orator_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryId": "01JQKX8F7Y2M3N4P5R6S7T8V9W",
    "ruleType": "query_type",
    "pattern": "database|db|migration",
    "context": "We use Drizzle ORM with PostgreSQL. Migrations are in db/migrations/ and must be created with drizzle-kit. Never write raw SQL for application queries. See ADR-003 for the decision to migrate from Prisma.",
    "priority": 8
  }'

This injects a team convention whenever someone asks about the database, ensuring AI tools follow your architectural decisions.

Exclusion Rules

Exclusion rules prevent specific paths or patterns from appearing in context results.

Terminal window
curl -X POST https://api.orator.dev/v1/context-rules \
  -H "Authorization: Bearer orator_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryId": "01JQKX8F7Y2M3N4P5R6S7T8V9W",
    "ruleType": "exclusion",
    "pattern": "*.generated.ts,*.min.js,dist/**,coverage/**",
    "context": "Generated and build output files excluded from context",
    "priority": 100
  }'

Exclusion rules should typically have high priority to ensure they override other rules.

Managing Rules via the API

List Rules

Terminal window
curl https://api.orator.dev/v1/repos/01JQKX8F7Y2M3N4P5R6S7T8V9W/context-rules \
  -H "Authorization: Bearer orator_abc123def456"
{
  "data": [
    {
      "id": "01JQKY3H9J0K1L2M3N4P5Q6R7S",
      "repositoryId": "01JQKX8F7Y2M3N4P5R6S7T8V9W",
      "ruleType": "path",
      "pattern": "auth",
      "context": "src/middleware/auth.ts,src/services/auth-service.ts",
      "priority": 10,
      "createdAt": "2025-06-01T14:00:00.000Z",
      "updatedAt": "2025-06-01T14:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "perPage": 20
  },
  "error": null
}

Update a Rule

Terminal window
curl -X PUT https://api.orator.dev/v1/context-rules/01JQKY3H9J0K1L2M3N4P5Q6R7S \
  -H "Authorization: Bearer orator_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "auth|authentication|login",
    "priority": 15
  }'

Delete a Rule

Terminal window
curl -X DELETE https://api.orator.dev/v1/context-rules/01JQKY3H9J0K1L2M3N4P5Q6R7S \
  -H "Authorization: Bearer orator_abc123def456"

Here are some rules most teams find useful:

1. Architecture Overview

{
  "ruleType": "query_type",
  "pattern": "architecture|structure|overview|how.*organized",
  "context": "This is a monorepo using pnpm workspaces. packages/api is the backend (Cloudflare Workers), packages/web is the frontend (Next.js), packages/shared contains shared types. See ARCHITECTURE.md in the repo root.",
  "priority": 10
}

2. Testing Conventions

{
  "ruleType": "query_type",
  "pattern": "test|testing|spec",
  "context": "We use Vitest for unit tests and Playwright for E2E tests. Test files live next to source files with .test.ts suffix. Use vi.mock() for mocking. Integration tests go in __tests__/ directories. See ADR-005 for testing strategy.",
  "priority": 8
}

3. Exclude Sensitive Files

{
  "ruleType": "exclusion",
  "pattern": ".env*,*secret*,*credential*,*.pem,*.key",
  "context": "Sensitive files excluded from context",
  "priority": 100
}

4. API Design Conventions

{
  "ruleType": "query_type",
  "pattern": "api|endpoint|route",
  "context": "API routes follow REST conventions with /v1/ prefix. Use kebab-case for URLs. All responses use the standard { data, meta, error } envelope. Validation is done with Zod schemas in the validators/ directory.",
  "priority": 8
}

Priority

Rules are evaluated in order of priority (highest first). When multiple rules match a query:

  • Higher priority rules are applied first
  • Exclusion rules remove items that other rules might have added
  • The final context respects the maxTokens limit, keeping higher-relevance items

A good practice is to use priorities in ranges:

  • 100+: Exclusion rules (always applied)
  • 10-50: Critical path and query type rules
  • 1-9: Nice-to-have file type and supplementary rules