Manifest reference for AI development principles

The principles sync reads .ai/principles/manifest.yml to determine which principles to generate, which source files each principle is derived from, and how to open the auto-generated merge request.

For the onboarding flow, see AI development principles.

Top-level keys

Key Type Required Description
auto_mr map Yes Configuration for the merge request opened by the scheduled sync.
principles map Yes Map of principle slug to principle entry. See Principle entry.
static_entries list No Manually maintained files included in the agent context-loading skill.

Principle entry

Each key under principles: is a slug. The value is a map with the following keys:

Key Type Required Description
description string Yes One-line summary used in the agent routing table. Start with a capital letter. Do not end with a period.
group string Yes Group label used to cluster related principles in the routing table. For example: Database, Backend, Frontend.
sources list of maps Yes Source documentation files for the principle. See Source entry.
file_filters list of strings No Glob patterns that identify which repository paths the principle applies to. The sync uses these to scope drift detection.
baseline string No Path to a file containing hand-curated rules. The distiller preserves baseline content verbatim. See Baseline files.
prerequisite boolean No When true, the routing table marks this principle as a prerequisite for all other principles in the same group and the distiller prepends a note referencing it in every non-prerequisite distilled file in that group. Default: false.
owner_team string No CODEOWNERS handle of the team that owns the source documentation. The sync groups principles by this value, opens one merge request per team, and routes approval to this team through CODEOWNERS.
secondary_teams list of strings No Additional CODEOWNERS handles for source documentation that spans more than one team. Listed as inline code in a “Request a review from” section so the merge request does not notify these groups.
fallback_ping_team boolean No Fallback ping behavior when no source-documentation author resolves to a user. When true (default), the merge request summary mentions the owner_team handle. When false, it uses the non-mention team slug so a large group is not notified on every run.
team_slug string No Short, URL-safe name used for the per-team branch and merge request title. Defaults to the last path segment of owner_team. Set this when the last segment is generic (for example, approvers) and would collide across teams.

Source entry

Each item in sources: is a map with the following keys:

Key Type Required Description
path string Yes Repository path to the source documentation file, relative to the repository root.
url string Yes Canonical URL on docs.gitlab.com for the source file. The distilled file links back here so reviewers can verify rules against the published documentation.

Auto-merge request configuration

The auto_mr: map controls how the scheduled sync opens its merge request:

Key Type Required Description
branch_prefix string Yes Prefix for source branch names. The sync reuses an open team or tooling branch, or appends the run date when creating one.
title_template string Yes Title template for the merge request. Supports %{date} interpolation.
labels list of strings Yes Labels applied to the merge request.
remove_source_branch boolean Yes When true, the source branch is deleted after the merge request merges.

Merge request reviewers

Each per-team merge request pings the people who changed the source documentation since the principle was last distilled. The sync queries the GitLab GraphQL API for the commit authors in the range between the previous distillation and the target branch, and mentions the linked GitLab users in the merge request summary. This matches on any confirmed email associated with the account, not only a public one. The sync skips authors that are bot accounts, on a small deny-list of known service accounts, or whose commit email is not linked to any GitLab account.

When no author resolves to a user, the summary falls back to the fallback_ping_team behavior for the owner_team. Approval always routes to the owner_team through CODEOWNERS, so an unavailable author never blocks the merge request.

Static entries

Files listed under static_entries: are referenced from the agent context-loading skill but are not generated by the sync. Use this list for hand-maintained topical modules under .ai/ that are not derived from source documentation.

Key Type Required Description
description string Yes Task description that triggers loading. For example, Git, commits, or branches.
path string Yes Repository path to the file, relative to the repository root.

Examples

Minimal principle entry

principles:
  rest-api:
    description: REST API design and conventions
    group: API
    sources:
      - path: doc/development/api_styleguide.md
        url: https://docs.gitlab.com/development/api_styleguide/

Principle entry with all fields

principles:
  database-migrations:
    description: Database migration patterns and zero-downtime safety
    group: Database
    prerequisite: false
    file_filters:
      - 'db/migrate/**/*.rb'
      - 'db/post_migrate/**/*.rb'
    baseline: .ai/principles/baselines/database-migrations.md
    sources:
      - path: doc/development/migration_style_guide.md
        url: https://docs.gitlab.com/development/migration_style_guide/
      - path: doc/development/database/avoiding_downtime_in_migrations.md
        url: https://docs.gitlab.com/development/database/avoiding_downtime_in_migrations/

Auto-merge request block

auto_mr:
  branch_prefix: docs-sync/principles
  title_template: "Update AI development principles from SSOT (%{date})"
  labels:
    - ai-agent
    - documentation
    - type::maintenance
  remove_source_branch: true

Static entry

static_entries:
  - description: Git, commits, or branches
    path: .ai/git.md

Validation

The distiller validates the manifest at load time and aborts with an error when:

  • The auto_mr: block is missing or is missing any of its required keys.
  • Any principle is missing the sources: key, or sources: is empty.

This validation runs at sync time, not at merge time: an invalid manifest entry fails the next scheduled (or manual) sync run rather than blocking the merge request that introduced it.