Skip to content

v1.md

Latest commit

 

History

History
221 lines (154 loc) · 10.3 KB

v1.md

File metadata and controls

221 lines (154 loc) · 10.3 KB
Raw

AGENTS.map Specification — v1

Status: Draft Date: 2026-02-21 Authors: Community

1. Overview

AGENTS.map is an optional repository-root "sitemap" for agent instruction files. It lists where nested AGENTS.md files live and provides short descriptions so an agent (or tool) can quickly identify the right subtree before applying the usual cascading discovery rules.

AGENTS.map is informational, not normative: the actual rules live in AGENTS.md. If AGENTS.map conflicts with an actual AGENTS.md, the AGENTS.md content wins for that subtree.

2. Goals

  • Make nested AGENTS.md locations discoverable without scanning the full tree.
  • Provide repo wayfinding — "where should I go for X?"
  • Stay low-maintenance and easy to validate.
  • Be safe to ignore by tools that don't support it.

3. Non-goals

  • Replacing existing "nearest AGENTS.md applies" semantics.
  • Defining the instruction format inside AGENTS.md.
  • Acting as a comprehensive documentation catalog (unless the repo chooses to).
  • Nesting: AGENTS.map files MUST only exist at the repository root.

4. File Location

4.1 Filename

The file MUST be named AGENTS.map.md and placed at the repository root.

4.2 Format

The file is Markdown. It is both human-readable (renders natively on GitHub, GitLab, etc.) and machine-parseable via simple line-by-line rules described in Section 6.

5. Core Semantics

  1. Each entry points to an AGENTS.md (or tool-recognized equivalent).
  2. Entries include a short purpose and a scope indicating which paths it applies to.
  3. If an entry is wrong or stale, tools SHOULD treat it as a hint and fall back to normal discovery.
  4. Authority rule: If AGENTS.map conflicts with an actual AGENTS.md, the AGENTS.md content wins for that subtree.

6. Format: AGENTS.map.md

6.1 Requirements

AGENTS.map.md MUST contain:

  1. A title (H1): # AGENTS.map
  2. A short "how to use" blurb.
  3. An ## Entries section with a list of entries.

6.2 Entry Format

Each entry is a Markdown list item with nested sub-items:

- Path: /services/payments/AGENTS.md
  - Purpose: Payments domain rules, PCI constraints, test fixtures.
  - Applies to: /services/payments/**
  - Priority: high
  - Last modified: 2026-02-21
  - Owners: @team-payments
  - Tags: backend, compliance
  - Last reviewed: 2026-02-21

6.3 Field Definitions

Field Required Description
Path Yes POSIX path relative to repo root, prefixed with /.
Purpose Yes 1–3 sentences explaining why/when to use this file.
Applies to No Comma-separated glob patterns (e.g., /services/payments/**). Defaults to the directory containing the Path entry plus /**.
Priority No How important this file is for agents: critical, high, normal, low. Default: normal.
Last modified No Date the AGENTS.md content was last meaningfully changed, in YYYY-MM-DD format. Tools MAY auto-populate this from version control.
Owners No Comma-separated team handles or CODEOWNERS aliases.
Tags No Comma-separated categorical labels (e.g., backend, security). Agents MAY use tags to filter entries by domain — see 6.3.3.
Last reviewed No Date a human last verified the instructions are still correct, in YYYY-MM-DD format.

6.3.1 Priority

Priority tells agents which instruction files matter most. When an agent matches multiple entries, it SHOULD load them in priority order (critical first, low last). If context window or token budget is limited, agents MAY skip low priority entries.

Value Meaning
critical Always load. Security policies, compliance rules, breaking-change warnings.
high Load by default. Core domain rules, architectural constraints.
normal Load when the scope matches the task. This is the default if omitted.
low Load only if specifically relevant. Style preferences, nice-to-haves.

6.3.3 Tags

Tags provide cross-cutting categorization that complements scope-based matching. While Applies to connects entries to file paths, tags connect entries to domains — frontend, backend, security, compliance, etc.

Agents MAY use tags to discover relevant entries outside the current scope. For example, an agent working on a frontend page may query for all entries tagged frontend to also load the component library rules, even if the component library's scope doesn't cover the page's directory.

Common tag patterns:

Tag Use case
frontend, backend Domain affinity — load related entries for a class of work.
security, compliance Cross-cutting concerns — always relevant regardless of path.
shared, infra Architectural layer — helps agents understand dependency boundaries.

Tags are free-form strings. Repos SHOULD document their tag vocabulary in the AGENTS.map.md blurb or root AGENTS.md.

6.3.2 Last modified

Last modified records when the AGENTS.md file's content was last meaningfully updated. This helps agents gauge freshness — instructions modified recently are more likely to reflect current practices than ones untouched for months.

The CLI tool can auto-populate this from git log. The field is distinct from Last reviewed, which records when a human confirmed the instructions are still accurate (even if unchanged).

6.4 Full Example

# AGENTS.map

This file lists where nested AGENTS.md files live and what they're for.
The AGENTS.md files themselves are authoritative for their subtrees.

## Entries

- Path: /AGENTS.md
  - Purpose: Global repo conventions, build/test, PR rules.
  - Applies to: /**
  - Priority: high
  - Last modified: 2026-02-15

- Path: /services/payments/AGENTS.md
  - Purpose: Payments domain rules, PCI constraints, test fixtures.
  - Applies to: /services/payments/**
  - Priority: critical
  - Last modified: 2026-02-20
  - Owners: @team-payments
  - Tags: backend, compliance

- Path: /frontend/AGENTS.md
  - Purpose: UI conventions, accessibility checks, component patterns.
  - Applies to: /frontend/**
  - Priority: normal
  - Last modified: 2026-01-10

6.5 Parsing Rules

Tools parsing AGENTS.map.md SHOULD:

  1. Look for lines matching - Path: <path> to identify entry boundaries.
  2. Extract sub-fields from indented - <Field>: <value> lines following each Path.
  3. Strip leading / from paths and scope patterns for internal use.
  4. Default Applies to to the directory of the Path entry plus /** if not specified (e.g., Path: /services/payments/AGENTS.md defaults to /services/payments/**; Path: /AGENTS.md defaults to /**).
  5. Ignore lines that don't match known field patterns (forward compatibility).

6.6 Validation Rules

  • Each Path SHOULD exist in the repo. CI validation is recommended.
  • If an AGENTS.md file exists but is not listed, tools MAY still find it via scanning/cascading.
  • Path values MUST NOT contain .. segments.
  • Applies to globs use the same syntax as .gitignore patterns.

6.7 Dependency Entries

Entries MAY reference AGENTS.md files shipped by installed dependencies (e.g., npm packages, Python packages). These paths start with node_modules/, vendor/, or equivalent dependency directories.

- Path: /node_modules/@acme/ui/AGENTS.md
  - Purpose: Acme UI component conventions, theming API, a11y requirements.
  - Applies to: /src/components/**, /frontend/**
  - Tags: frontend, shared

Semantics:

  • Dependency entries follow the same format and fields as local entries.
  • The Applies to scope defines where the dependency's instructions are relevant in your codebase — not the dependency's internal file structure.
  • Validation treats missing dependency paths as warnings (not errors), since node_modules/ is ephemeral and may not be populated in CI or clean checkouts.
  • The CLI's discover --deps and init --deps flags scan installed packages for AGENTS.md files at the package root.

When to use dependency entries:

  • A component library ships conventions for using its components (theming, accessibility, prop patterns).
  • A framework documents architectural patterns (route conventions, data fetching, middleware).
  • An internal shared package includes team standards that consumers should follow.

7. Recommended Agent/Tool Algorithm

Given a task that touches one or more target paths:

  1. Load the map: Check for AGENTS.map.md at the repository root. Parse it if found.
  2. Match entries: Identify entries whose Applies to globs match the target path(s).
  3. Rank matches: Sort by priority (critical > high > normal > low), then by scope specificity (longest matching prefix). If two entries have equal priority and specificity, load both.
  4. Load instructions in ranked order from step 3. After loading map-referenced entries, apply existing cascading logic toward the working directory (implementation-defined).
  5. Tag lookup (optional): If the agent can classify the task by domain (e.g., "frontend", "backend"), it MAY additionally query entries by tag to discover cross-cutting instruction files outside the matched scopes.
  6. Budget: If the agent has limited context, it MAY skip low priority entries and use Last modified to prefer fresher instructions over stale ones.
  7. Fallback: If AGENTS.map.md is missing or stale, fall back to normal AGENTS.md discovery (scan / nearest-parent search).

8. Maintenance

Repos SHOULD keep AGENTS.map.md in sync via:

  • CI validation that every listed path exists.
  • Optional discovery script to find AGENTS.md paths automatically, with human-authored purpose fields.
  • Periodic review using the Last reviewed field.

9. Security Considerations

  • AGENTS.map exposes repository layout. Avoid listing sensitive or internal-only paths in public repos.
  • AGENTS.map MUST be data-only. Tools MUST NOT execute anything referenced in the map.
  • Tools SHOULD validate that paths do not escape the repository root (no .., no absolute filesystem paths).

10. Future Considerations

The following are explicitly deferred to future versions:

  • Nested AGENTS.map files for multi-workspace monorepos.
  • Conditional entries (e.g., "only applies to Python files in this subtree").
  • Remote references (pointing to AGENTS.md files hosted outside the repo or its dependencies).