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	Planned. Identifies the team responsible for reviewing the auto-generated merge request for this principle. Tracked in issue 599920.

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 the source branch name. The sync appends the run date.
`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.

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.

AI development principles for the onboarding flow.
.ai/principles/manifest.yml for the live manifest.
gems/gitlab-ai-principles-distiller for the gem that consumes the manifest.