Skip to content

Latest commit

 

History

History
124 lines (77 loc) · 5.79 KB

AGENTS.md

File metadata and controls

124 lines (77 loc) · 5.79 KB

AI Agent Guidelines for Domain Connect Templates

This document provides guidance for AI tools working with Domain Connect templates in this repository.

Scope

These rules apply when adding or modifying templates in this repository.

Template Schema

The template file schema is defined in template.schema. This schema MUST be followed for all template files.

Key schema requirements:

  • Templates must include required fields: providerId, providerName, serviceId, serviceName, records
  • Record types supported: A, AAAA, CNAME, NS, TXT, MX, SPFM, SRV, REDIR301, REDIR302, APEXCNAME, and ANY
  • Templates must follow the JSON Schema defined in template.schema

Template Validation

Before submitting changes, you MUST validate every added or modified template with the official linter.

Fast track vs. manual review

PRs whose templates pass the Automerge Check workflow (dc-template-linter -merge-or-fail) receive the automerge-possible label and are approved and merged much faster. PRs that fail it are queued for manual review by a maintainer, which takes considerably longer. Always aim for a clean -merge-or-fail run; only deviate when a documented exception applies, and then justify it in the PR description.

Installation

Requires Go 1.22 or newer:

go install github.com/Domain-Connect/dc-template-linter@latest

The binary lands in $(go env GOPATH)/bin; ensure it is on PATH.

Usage

Run these checks on each changed template file and inspect the exit code (echo $?):

  1. Fast-track check (identical to the Automerge Check workflow):

    dc-template-linter -merge-or-fail <template-file.json>

    Exit code 0 means the PR qualifies for fast-track approval. A non-zero exit code means it will go to manual review — fix the reported DCTLxxxx issues (see the linter wiki) and re-run.

  2. Full check (identical to the Lint Domain Connect Templates workflow):

    dc-template-linter -tolerate warn <template-file.json>

    Must exit 0, otherwise the workflow fails and the PR cannot be merged.

  3. Version bump (modified templates only): the version field must be incremented; the workflow fails if a changed template has no version change.

  4. Logo reachability (not run in CI, but required by the PR template checkbox; requires network):

    dc-template-linter -logos <template-file.json>

All templates must pass the full check and, if modified, carry a version bump before being considered valid.

Note: If dc-template-linter returns a non-zero exit value, the template is invalid (full check) or not eligible for fast track (-merge-or-fail) and should be corrected before submission. Never report a check as passed without actually running it and seeing exit code 0.

Template Naming Convention

Template files must be named following this pattern:

providerId.serviceId.json

Example: myprovider.com.website.json

Place template files in the root directory of the repository.

Example Templates

For reference, example templates using the provider exampleservice.domainconnect.org are available in this repository. These templates demonstrate proper structure and can be used as a starting point when creating new templates.

Commit Message Format

When committing template changes, use the following format for the subject line:

  • New template: add <providerName>, <serviceName> (e.g., add Example Domain Connect Service, Stateless Hosting Primary)
  • Modified template: modify <providerName>, <serviceName>
  • Deleted template: delete <providerName>, <serviceName>
  • Multiple templates: <providerName>, <num> templates (e.g., Example Domain Connect Service, 3 templates)

Commit Body

The commit body should follow the structure defined in .github/pull_request_template.md. When creating commit messages, AI tools may:

  • Assist with checking [ ] checkboxes from the PR template
  • Help verify template quality rules

IMPORTANT: AI tools MUST NEVER fabricate or hallucinate "Online Editor test results" links. These must be generated by actually using the Online Editor.

Key Quality Rules

When modifying or creating templates, ensure compliance with these critical rules:

  1. Always set syncPubKeyDomain - Enables cryptographic verification (preferred over warnPhishing)
  2. Never set syncPubKeyDomain and warnPhishing together - They are mutually exclusive
  3. Set syncRedirectDomain when using redirect_uri in synchronous flow
  4. Never use TXT records for SPF - Use the SPFM record type instead
  5. Set txtConflictMatchingMode on TXT records that must be unique (e.g., DMARC, verification tokens)
  6. Scope variables narrowly - Avoid bare variables as full record values; use fixed prefixes
  7. Scope host variables narrowly - Fix non-variable parts in host fields
  8. Never use variables in host to target subdomains - Use the standard host parameter instead
  9. Never write %host% explicitly in the host attribute - The protocol handles this automatically
  10. Set essential on records users may need to change independently

For complete details, see the README.md.

References