ContextQMD
Back to Gitlabhq

Manifest reference for AI development principles

doc/development/agent_principles/manifest_reference.md

19.1.06.2 KB
Original Source

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

KeyTypeRequiredDescription
auto_mrmapYesConfiguration for the merge request opened by the scheduled sync.
principlesmapYesMap of principle slug to principle entry. See Principle entry.
static_entrieslistNoManually 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:

KeyTypeRequiredDescription
descriptionstringYesOne-line summary used in the agent routing table. Start with a capital letter. Do not end with a period.
groupstringYesGroup label used to cluster related principles in the routing table. For example: Database, Backend, Frontend.
sourceslist of mapsYesSource documentation files for the principle. See Source entry.
file_filterslist of stringsNoGlob patterns that identify which repository paths the principle applies to. The sync uses these to scope drift detection.
baselinestringNoPath to a file containing hand-curated rules. The distiller preserves baseline content verbatim. See Baseline files.
prerequisitebooleanNoWhen 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_teamstringNoPlanned. 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:

KeyTypeRequiredDescription
pathstringYesRepository path to the source documentation file, relative to the repository root.
urlstringYesCanonical 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:

KeyTypeRequiredDescription
branch_prefixstringYesPrefix for the source branch name. The sync appends the run date.
title_templatestringYesTitle template for the merge request. Supports %{date} interpolation.
labelslist of stringsYesLabels applied to the merge request.
remove_source_branchbooleanYesWhen 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.

KeyTypeRequiredDescription
descriptionstringYesTask description that triggers loading. For example, Git, commits, or branches.
pathstringYesRepository path to the file, relative to the repository root.

Examples

Minimal principle entry

yaml
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

yaml
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

yaml
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

yaml
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.