Design

Internal spec and implementation plan. The README is the user intro; this file is for architecture, detailed interfaces, and decisions.

Goals

• Compose canonical AGENTS.md from small fragments.
• Deterministic outputs with nearest‑wins routing and explicit overrides.
• Zero‑config defaults; ergonomic overrides when needed.
• Fast, safe, CI‑friendly; clear exit codes and reporting.
• Installable and runnable across npm/pnpm/yarn/bun.

Non‑Goals

• No network access by default.
• No runtime code execution from fragments (imports are file content only).
• No editor extensions in core (document hooks, not implement them).

Stack & Compatibility

• Runtime: Bun 1.x (Node APIs compatible); support Node 18+ via published package.
• CLI: yargs for command/flag parsing.
• Tests: bun test.
• Bundling/Publish: bunup; ship ESM with a small CJS shim if needed; add bin entry for CLI.
• Invocation: npx/pnpm dlx/yarn dlx/bunx should work.

Architecture

• CLI (src/cli)
  • yargs command modules: init, compose, report, watch, help, version.
  • Minimal options; avoid advanced flags in v0.
• Core (src/core)
  • config.ts: discover/load/merge config; defaults.
  • discovery.ts: globbing, filter via includeFiles, ignore rules.
  • directives.ts: parse HTML comment directives and apply per‑fragment.
  • compose.ts: target resolution, ordering, annotation, truncation, write.
  • report.ts: compute summaries and JSON payloads.
  • logger.ts: leveled logs; --silent flag.
  • fs.ts: IO helpers (safe write, banner insertion, header detection).
• Watcher (src/watch)
  • fs.watch with debounced rebuild; fallback polling where needed.

CLI Spec

• agents-md init

  • If a config or generated AGENTS.md is present, print a reminder to run agents-md compose and exit.
  • If CLAUDE.md exists, move it to project.agents.md and edit CLAUDE.md to onliner @AGENTS.md.
  • Move any existing AGENTS.md files' content to <"project" | directory-name>.agents.md.
  • Create a config file agents-md.config.ts with defaults.
  • Run agents-md compose to generate AGENTS.md files from inputs.

• agents-md compose

  • No flags in v0. Uses config/includes for discovery.

• agents-md report

  • Human view
    • Report on the current state:
  • AGENTS.md files: - Directory tree for all AGENTS.md files - Character size and token predictions - if oversized - Warn with colorized output on over-size AGENTS.md and list their sourced inputs in descending order of size.
    • Bad comment directives
      • Missing imports
  • JSON view for machine readability

• agents-md watch

  • Rebuild on changes quietly; --verbose prints logs.

Exit codes: 0 ok, 1 error, 2 invalid config, 4 limit violation.

Quick Start

1. Install with your preferred package manager, e.g.

   bun install agents-md -D
   

2. Initialize with:

   bun agents-md init
   

   This will move any existing AGENTS.md or CLAUDE.md files to <"project" if root | directory-name>.agents.md and scaffold a config file agents-md.config.ts to get started quickly. If a config or generated AGENTS.md already exists, it prints a reminder to run agents-md compose instead.

   Important: AGENTS.md files are now codegen and managed by agents-md. We SHOULD NOT HAND-WRITE AGENTS.md files anymore.

3. Write new documents or reshape existing ones in any of the following path formats:

   • **/agents-md/*.md
   • **/*.agents.md
   • **/<customised-directories>/*.md
   • **/*.<customised-file-formats>

   These files will be included in the composition process.

4. Compose AGENTS.md files with:

   bun agents-md compose
   

   This will codegen AGENTS.md file(s) from our inputs.

If we want to have multiple AGENTS.md files for dynamic location-based context, simply add a new empty AGENTS.md file in any target directory and rerun bun agents-md compose.

Config Schema (TypeScript)

// agents-md.config.ts
export type AgentsMdConfig = {
  // Discovery
  include?: string[];              // ['**/agents-md/**/*.md','**/*.agents.md']
  exclude?: string[];              // ['**/node_modules/**','**/.git/**']
  includeFiles?: (ctx: { path: string; cwd: string }) => boolean;

  // Targets and routing
  defaultTarget?: 'nearest' | 'root';

  // Composition behavior
  annotateSources?: boolean;       // wrap fragments with `<!-- source: ... priority=n -->` and `<!-- /source: ... -->`
  truncate?: { atChars?: number; strategy?: 'end' | 'middle' };

  // Limits
  limits?: {
    warnSourceChars?: number;
    maxSourceChars?: number;
    warnOutputChars?: number;
    maxOutputChars?: number;
  };
}

export interface Fragment {
  path: string;
  content: string;
  directives: Directive;
}

export interface Directive {
  target?: string;
  imports?: { path: string; line: number }[];
  priority?: number;
  title?: string;
}

export type TargetSelector = 'nearest' | 'root' | { path: string };
export interface Output {
  path: string;                    // target file path (AGENTS.md)
  chars: number;                   // output size
  sources: { path?: string; chars: number }[];
}

export interface JsonReport {
  outputs: Output[];
  totals: { outputs: number; chars: number; sources: number };
  limits?: { violated: boolean; details: string[] };
}

Config discovery: look for agents-md.config.ts, then .mjs/.js; ignore local overrides unless explicitly supported in future.

Markdown Directives (Spec)

• Syntax: HTML comments, agents-md: prefix, space/comma separated key=value pairs.
• Supported keys:
  • target: nearest | root | relative dir (e.g., ../docs) | named target.
  • import: @<relative-path>; multiple allowed; processed in order.
  • priority: integer; higher numbers surface earlier among same target.
  • title: string; optional section heading hint (no auto‑insertion by core).
• Precedence: directives > defaultTarget.
• Errors: missing import files (warn), circular imports (error), unknown target (warn).

Composition Algorithm

1. Discover fragments via include globs and includeFiles filter.
2. Parse directives (per fragment); resolve imports; detect cycles; inline imported content before host content.
3. Determine target for each fragment: directive → nearest directory with AGENTS.md → root.
4. Group by target; sort within target by priority (desc) then path.
5. Compose content; optionally annotate sources; apply truncation; check limits.
6. Write outputs with banner header.

Banner header: <!-- Generated by agents-md: DO NOT EDIT DIRECTLY. Edit *.agents.md fragments instead. Higher priority fragments appear first and win conflicts. -->.

Init & Migration

• Move existing AGENTS.md or CLAUDE.md into *.agents.md fragments.
• Create agents-md.config.ts with defaults if missing.
• Optionally rewrite CLAUDE.md to @AGENTS.md for interop.
• Create an empty root AGENTS.md with a banner if none exists.
• Never overwrite hand‑edited files without backup (e.g., .bak).

Reporting

• Human: tree of targets, sizes (k chars), token estimates (heuristic), top‑N sources by size, warnings.
• JSON (--json): JsonReport above; stable keys, deterministic ordering.

Watch Mode

• Use fs.watch recursively where supported; debounce (e.g., 100–300ms).
• On change: re-run discovery for affected subtree; incremental compose for impacted targets only.
• Ignore writes to generated AGENTS.md outputs to avoid infinite rebuild loops.

Limits & Truncation

• Limits apply to source fragments and final outputs; warn vs hard fail based on thresholds.
• Truncation strategies: end (simple cut) or middle (keep head+tail with ellipsis marker).

Determinism

• Sorting is stable and deterministic across platforms.

Safety & Idempotency

• Writes only change files when content differs.
• Avoid advanced flags in v0; changes are only written when content differs.
• Generated banner prevents accidental hand edits.

Testing Strategy (bun test)

• Unit: directives parser, discovery filters, ordering, limits.
• Integration: compose on fixtures (single/multi‑target, imports, errors).
• CLI: yargs command wiring, exit codes.
• Snapshot: output content with source annotations and banners.

Packaging & Distribution

• Build with bunup: ESM bundle for library; CLI entry with Node shebang.
• package.json:
  • type: module, exports for ESM; add main CJS shim if required.
  • bin: { "agents-md": "dist/cli.js" }.
  • Engines: node >=18 || bun >=1.
• Publish to npm for cross‑ecosystem install.

Telemetry & Privacy

• No telemetry. No network by default. Plugins run locally.

Roadmap

• Official plugin kit (JSDoc, TS types, DB schemas).
• Per‑target summaries and tokenization adapters.
• Cross‑target references and lightweight templating.
• Watch perf improvements and editor integrations.
• Dedupe strategies (content/path) — future option if needed.
• Import paths not working
  • Comment directive paths must start with @ for Claude Code compatibility
  • Use relative paths from the importing file's directory
  • Check file exists: ``

Roadmap

• Provider framework for more dynamic content. E.g. jsdoc extractions.
• Better hot reloading supports for ecosystem tools
• MCP cross-directory reference support

Credits

• OpenAI's efforts on AGENTS.md standardization.
• Inspired by Ruler for distribution to agents that don't read AGENTS.md directly.