.ai-agent.yml Specification

The .ai-agent.yml file is the configuration that tells the Eiryx agent how to work with your repository. It describes your stack, commands, architecture, coding conventions, and rules — so the agent writes code like a member of your team.

How It Gets Created

When you connect a repository in Settings → Repositories, Eiryx runs a pre-scan that auto-detects your stack. You then have two options:

• Basic generation (free, instant) — Deterministic analysis that detects language, framework, test runner, commands, and ignore patterns. No AI involved.
• Deep generation (uses AI, ~$0.30-1.00) — Reads 8-12 key files from your repo and uses Claude Sonnet to analyze architecture, naming conventions, coding patterns, and team rules.

The generated file should be committed to the root of your repository. The agent reads it before every task.

Full Spec Reference

version

version: 3

Current spec version. Always 3.

stack

Describes the technology stack. Supports both single-language and multi-language (monorepo) projects.

Single language:

stack:
  language: python
  version: "3.11"
  framework: fastapi
  framework_version: "0.104"
  package_manager: pip
  linters:
    - ruff
    - mypy

Multi-language monorepo:

stack:
  languages:
    - name: python
      version: "3.11"
    - name: typescript
      version: "5.3"
  frameworks:
    - name: fastapi
      version: "0.104"
    - name: react
      version: "18.2"
  package_managers:
    - pip
    - npm
  monorepo: true
  monorepo_tool: "npm workspaces"

Additional stack fields:

Field	Type	Description
build_tool	string	Build tool (e.g., "vite", "webpack", "esbuild")
node_version	string	Node.js version if applicable
runtime	string	Runtime environment (e.g., "node", "deno", "bun")
db_schema_files	string[]	Paths to database schema files
linters	string[]	Linter tools in use

commands

Commands the agent uses for testing, linting, and building. If you have custom commands that differ from what the pre-scan detected, override them here.

commands:
  test: "pytest tests/ -v"
  lint: "ruff check . && mypy src/"
  build: "pip install -e ."
  format: "ruff format ."
  install: "pip install -r requirements.txt"

The agent runs commands.test after every fix to verify it works. If this command is wrong, the agent will always fail. Get this right.

If you override commands in the UI (Settings → Repo → Custom Commands), those take precedence over the .ai-agent.yml values.

architecture

Describes how your codebase is organized. This section is only filled by deep generation (AI analysis).

architecture:
  pattern: "modular-monolith"
  description: |
    FastAPI backend with feature-based module organization.
    Each module has its own router, service, and models.
  layers:
    - name: "API Layer"
      path: "api/routers/"
      responsibility: "HTTP endpoints, request validation, auth"
    - name: "Service Layer"
      path: "api/services/"
      responsibility: "Business logic, orchestration"
    - name: "Data Layer"
      path: "api/db/"
      responsibility: "Database queries, Supabase client"
  entry_points:
    - "api/main.py"
    - "src/main.tsx"
  key_files:
    - path: "api/main.py"
      description: "FastAPI app factory, router registration, middleware"
    - path: "api/auth.py"
      description: "JWT authentication, get_current_user dependency"
    - path: "sql/schema.sql"
      description: "PostgreSQL schema with RLS policies"
  database:
    orm: "supabase-py (raw queries)"
    migrations: "manual SQL files"
    schema_location: "sql/schema.sql"
  auth:
    method: "Supabase Auth (GitHub OAuth, JWT)"
    middleware_file: "api/auth.py"
  state_management: "TanStack Query v5"

The key_files list tells the agent where to look first when exploring the codebase. The more accurate this list, the faster the agent localizes bugs.

conventions

Team coding conventions detected by AI analysis. The agent uses these to write code that matches your style.

conventions:
  naming:
    files: "snake_case.py / PascalCase.tsx"
    functions: "snake_case"
    classes: "PascalCase"
    constants: "UPPER_SNAKE_CASE"
    components: "PascalCase"
    hooks: "useCamelCase"
    types: "PascalCase with I prefix for interfaces"
  imports:
    style: "absolute with path aliases (@/)"
    barrel_files: false
    order: "stdlib → third-party → local"
  error_handling:
    backend: "HTTPException with status code and detail message"
    frontend: "TanStack Query error boundaries, toast notifications"
  testing:
    location: "tests/ directory, mirrors src structure"
    naming: "test_*.py / *.test.ts"
    framework: "pytest / vitest"
    mock_strategy: "unittest.mock for Python, vi.mock for TypeScript"
  git:
    branch_naming: "feature/*, bugfix/*, hotfix/*"
    commit_convention: "conventional commits"
  code_style:
    max_line_length: 100
    quotes: "double"
    trailing_comma: true
    semicolons: true

rules

Guardrails for the agent. Forbidden patterns are things the agent must never do. Preferred patterns are things the agent should follow.

rules:
  forbidden_patterns:
    - "Do not use console.log in production code"
    - "Never use SELECT * — always specify columns"
    - "Do not import from other feature modules directly"
    - "Never store secrets in code — use environment variables"
    - "Do not use any — always type explicitly"
  preferred_patterns:
    - "Use TanStack Query for all server state"
    - "Use Pydantic models for request/response validation"
    - "Use dependency injection via FastAPI Depends()"
    - "All API endpoints must have rate limiting"
  custom_instructions: |
    This is a B2B SaaS platform. All UI text must use i18n keys,
    never hardcoded strings. Backend logs must never contain
    secrets or PII — use [***HIDDEN***] for sensitive values.

You can add your own rules here. The agent reads custom_instructions as free-form text and follows it during both bugfix and feature tasks.

ignore

Files and directories the agent should never modify. Auto-detected from .gitignore and common patterns.

ignore:
  - "node_modules/"
  - "dist/"
  - ".git/"
  - "*.lock"
  - "*.min.js"
  - "__pycache__/"
  - ".env"
  - "*.pyc"

security

Security constraints for the agent.

security:
  blocked_branches:
    - main
    - production
  max_iterations: 50
  sensitive_files:
    - ".env"
    - "conf/github-app.pem"
    - "secrets/"

Field	Description
blocked_branches	Branches the agent cannot push directly to (it creates a new branch)
max_iterations	Maximum agent iterations before forced stop
sensitive_files	Files the agent should never read or modify

dependencies

Cross-repository dependencies for the Cross-Repo Impact Analysis feature. If a bug’s root cause is in a dependency rather than the current repo, the agent can pivot to fix it there.

dependencies:
  - repo: "your-org/shared-library"
    relationship: api-consumer
    contracts:
      - "src/types/api.ts"
      - "openapi.yaml"
  - repo: "your-org/auth-service"
    relationship: service-dependency

Manual Editing

You can edit the .ai-agent.yml manually at any time. The agent always reads the latest committed version. Common reasons to edit manually:

• Add custom_instructions with team-specific rules
• Fix an incorrect test command
• Add sensitive_files that shouldn’t be touched
• Adjust max_iterations for complex repos
• Add dependencies for cross-repo analysis

Licensing

The .ai-agent.yml specification is licensed under Apache 2.0 — you can use it freely in your own tools and workflows. The Eiryx tooling that generates and reads the file is AGPL v3.