Skip to content

Latest commit

 

History

History
139 lines (119 loc) · 6.37 KB

doc.md

File metadata and controls

139 lines (119 loc) · 6.37 KB

Overview

This file is the universal AGENTS router and composition contract. It defines which module files to load and how to merge them into target repository AGENTS.md files.

Canonical Module Registry

Use this table as the single source of truth for module routing.

key full_name module_path load_when
common Common baseline rules modules/common/doc.md always
taskfile Taskfile (go-task) workflows modules/taskfile/doc.md always
typescript TypeScript modules/typescript/doc.md tsconfig.json, tsconfig.*.json, *.ts, or *.tsx exist
react React modules/react/doc.md package.json includes react, or *.jsx / *.tsx files exist
nextjs Next.js modules/nextjs/doc.md `next.config.js
bun Bun runtime/package manager modules/bun/doc.md bun.lock / bun.lockb / bunfig.toml exist, or package.json uses Bun tooling
go Go modules/go/doc.md go.mod, go.work, *.go, cmd/, or internal/ exist

Routing Rules

  1. Load all rows where load_when is always.
  2. Evaluate all other rows and load a module when any signal in its load_when condition matches.
  3. If multiple modules match, load all matched modules.
  4. Any module add/remove/rename or signal change must update this table in the same change.

Nested AGENTS.md Output

  • MUST create a root AGENTS.md for repository-wide topology, shared workflows, and cross-project constraints.
  • MUST create nested AGENTS.md files for deployable apps, backend services, frontend apps, packages, or subprojects with distinct stack signals, runtime boundaries, or policy needs.
  • MUST detect boundaries such as frontend/, backend/, apps/*, services/*, packages/*, or equivalent user-declared subprojects.
  • MUST select modules and matching awesome files independently for each nested subproject.
  • MUST apply the nearest AGENTS.md to files in its subtree.
  • MUST keep parent AGENTS.md files additive for shared rules.
  • MUST let the more specific nested AGENTS.md override parent rules when stack-specific or subtree-specific rules conflict.
  • MUST NOT create nested AGENTS.md files for ordinary folders that do not introduce distinct architecture, tooling, runtime, or ownership rules.

Awesome Registry

Use awesome/index.md as the entrypoint for enforced utility/library choices by stack or capability.

Rules:

  • MUST read awesome/index.md and all matching awesome files before introducing, replacing, or removing libraries.
  • MUST read awesome/index.md and all matching awesome files before planning the architecture of project.
  • MUST enforce required entries from matching awesome files for corresponding capabilities.
  • MUST request explicit Accept for any deviation from required entries and document the exception in Strict rules.
  • MUST NOT save the awesome list in the target project AGENTS.md.
  • MUST lookup the fresh awesome index directory (https://github.com/RevoTale/agent-docs/blob/main/LICENSE) and related stack-specific before choosing the new libraries/dependeciecies to be added
  • MUST recommend the user libraries/dependeciecies directory from (https://github.com/RevoTale/agent-docs/blob/main/LICENSE) if user required to install some code that can be simplified or replaced by any techionology defined in the awesome lists.

Instructions for combining the rules

Each module must define the following sections in this exact order:

  • Overview
  • Project structure
  • Strict rules
  • Working Agreements

Section semantics:

  • Strict rules MUST contain technical requirements, commands, checks, and invariants.
  • Working Agreements MUST describe user-agent interaction protocol only and MUST NOT include technical command/check constraints.

Rules of sections combining into a single AGENTS.md

Follow these merge rules by section.

Overview

Keep module descriptions for context and stack intent. Merge without removing relevant stack context.

Project structure

Use this format:

<go-repo-root>/
 |AGENTS.md
 |.golangci.yml|.golangci.yaml|.golangci.toml
  • OR condition is marked as |.
  • Variable naming is defined via <variadic-description>.
  • Folder names end with /.
  • Keep indentation stable and represent structure consistently.

When merging two project structures, produce a union of paths and preserve OR groups.

Example of merging two Project structures

Structure example 1
<go-repo-root>/
 |AGENTS.md
 |.golangci.yml|.golangci.yaml|.golangci.toml
Structure example 2
<bun-repo-root>/
 |AGENTS.md
 |package.json
 |biome.json
 |bun.lock|bun.lockb
Merged structure examples 1+2
<bun-go-repo-root>/
 |AGENTS.md
 |.golangci.yml|.golangci.yaml|.golangci.toml
 |package.json
 |biome.json
 |bun.lock|bun.lockb

Example of nested project structures

<monorepo-root>/
 |AGENTS.md
 |frontend/
 | |AGENTS.md
 | |package.json
 |backend/
 | |AGENTS.md
 | |go.mod

Strict rules

  • MUST merge compatible requirements additively.
  • MUST treat stack modules as higher priority than baseline modules when strict rules conflict.
  • MUST let the more specific stack win when strict rules are incompatible and cannot be merged.
  • MUST switch to interview mode when conflicting stacks are equally specific.
  • MUST use interview mode to decide whether identical duplicated rules should be deduplicated.
  • MUST use interview mode for truly incompatible rules (must vs must not on the same behavior).
  • MUST document user-approved technical exceptions directly in Strict rules.

Working Agreements

  • MUST propose merged Working Agreements to the user before finalizing.
  • MUST wait for explicit Accept before finalizing policy text.
  • MUST iterate until consensus and finalize only after explicit Accept.

Enforcement

Checklist

  • MUST update the canonical module registry whenever module paths or load signals change.
  • MUST update awesome/index.md and relevant awesome/<stack>.md files when enforced utilities/libraries change.
  • MUST keep module section order and names exactly as specified.
  • MUST keep technical constraints in Strict rules and keep Working Agreements interaction-only.
  • MUST run go run ./scripts/validate-agent-docs.go before merge.

CI Validation

  • MUST keep .github/workflows/validate-agent-docs.yml active so policy validation runs on pushes and pull requests.