usm/gen-agentsmd

AGENTS.md generator — produces AI agent context files with USM-augmented system descriptions, smart-merged with existing hand-written content.

Intent

AI coding agents (Claude, Cursor, Codex) read AGENTS.md for project context. The generator augments existing AGENTS.md files with USM-derived sections (apps, shared packages, key patterns) between USM:START/USM:END markers, preserving all hand-written content.

Flows

Generate AGENTS.md (gen-agents-md)

Augment AGENTS.md with USM content using smart merge

1. parse → system.usm and service files
2. generate → USM section with apps, packages, patterns, config
3. merge → insert between USM:START/USM:END markers or after first H1

Contracts

agents-md-preserve

AGENTS.md generator must never destroy hand-written content

Acceptance criteria:

• [ ] Content between USM:START and USM:END replaced with generated content
• [ ] Content outside markers preserved exactly
• [ ] If no markers exist, insert after first H1 heading

Tests

agents-md-with-markers

Given:

• agents_md_with_usm_markers: true

Then:

• assertion: Only content between markers replaced
• assertion: Content before and after markers unchanged

agents-md-no-markers

Given:

• agents_md_handwritten: true

Then:

• assertion: USM section inserted after first H1
• assertion: Original content preserved below

Implementation

• Primary: src/generators/agentsMd.ts
• Test code status: none

See Also

• usm/cli-generate