USM

Appearance

usm/gen-agentsmd ​

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

Why this exists ​

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.

How it works ​

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

Guarantees ​

agents-md-preserve ​

AGENTS.md generator must never destroy hand-written content and must be idempotent

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
  • [ ] Repeated runs are byte-identical — no trailing-newline accumulation (issue #32)

agents-md-reference-pointer ​

AGENTS.md includes a compact USM reference block so agents in consumer repos know where authoritative USM documentation lives — without injecting dogfood content into the repo's own docs.

Acceptance criteria:

  • [ ] USM section lists: docs.usm.dev (tool reference), usm.dev (user docs), schema URL, and the upstream tracker
  • [ ] Instructs agents to prefer MCP tools (usm_list/usm_read/usm_search) for spec context, USM site for tool reference
  • [ ] Zero repo-specific dogfood content in the block — same links for every consumer
  • [ ] Idempotent and marker-preserved like the rest of the generated section

Test specifications ​

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

agents-md-idempotent ​

Given:

  • agents_md_with_usm_markers: true

Then:

  • assertion: merging the generated section repeatedly is byte-identical
  • assertion: exactly one newline follows the end marker for a single trailing merge

Implementation ​

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

See Also ​

  • usm/cli-generate