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.