USM

Appearance

usm/gen-rules-files [built] ​

Tool-specific rules file generator with two-tier enforcement — detailed workflow per tool (Cursor .mdc, CLAUDE.md, AGENTS.md, copilot-instructions, opencode skill) plus always-on iron rules injected every request wherever the tool provides a mechanism (opencode instructions, Cursor alwaysApply, Copilot applyTo, Claude Code skill description). Codex/AGENTS.md has no per-message mechanism and gets the detailed tier only.

Status: built

Intent ​

USM's distribution model is not a standalone app — it's an MCP server plus rules files that teach agents how to use it. Each AI coding tool reads a specific file for project instructions: Cursor reads .cursor/rules/*.mdc, Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Copilot reads .github/copilot-instructions.md. Currently USM generates a generic AGENTS.md with structural context but no workflow instructions. This generator produces tool-specific files that instruct agents to follow the spec-first loop: discuss → draft .usm → human reviews → build → update .usm.

Decisions ​

one-generator-multiple-outputs [accepted] ​

Decision: Single generator produces all tool-specific files in one pass

Rationale: The workflow instructions are largely the same across tools; only the file path and format conventions differ. A single generator with per-tool templates avoids drift between instruction files.

workflow-instructions-not-just-context [accepted] ​

Decision: Rules files contain behavioural instructions, not just system description

Rationale: The current AGENTS.md generator outputs structural context (what apps exist, what packages exist). That's useful but passive. The rules files must actively instruct: "Before implementing a feature, draft a .usm spec and show the human the review markdown. After implementation, update the feature status." Behavioural instructions are what make USM a workflow, not just a reference.

smart-merge-for-rules-files [accepted] ​

Decision: Reuse the smart-merge strategy from AGENTS.md generator

Rationale: Teams may add tool-specific instructions (e.g. "use pnpm not npm") that must survive regeneration. The USM:START/USM:END marker strategy preserves human content outside the generated block.

cursor-uses-mdc-format [accepted] ​

Decision: Generate .cursor/rules/usm.mdc in Cursor's rule format

Rationale: Cursor rules (.mdc files) support frontmatter with globs and descriptions that control when the rule is injected. Generating in .mdc format means the rule auto-activates when agents work in .usm/ directories.

Flows ​

Generate rules files for all supported tools (generate-all-rules-files) ​

During usm generate, produce instruction files for each supported AI coding tool, each containing the spec-first workflow tailored to that tool's conventions.

  1. parse → system.usm for project identity and principles
  2. parse → service files for available MCP tools and CLI commands
  3. generate → .cursor/rules/usm.mdc with Cursor frontmatter + workflow
  4. generate → CLAUDE.md with Claude Code workflow instructions
  5. generate → AGENTS.md with enhanced workflow (extends current generator)
  6. generate → .github/copilot-instructions.md with Copilot workflow
  7. smart-merge → each file preserving human content outside USM markers

Generate Cursor .mdc rule file (generate-cursor-rule) ​

Cursor rules use .mdc format with YAML frontmatter specifying when the rule activates. The rule teaches the agent the spec-first workflow.

  1. generate → frontmatter with description, globs (*.usm, .usm/**)
  2. generate → workflow instructions (read .usm before work, draft before build, update after)
  3. generate → MCP tool reference (list available tools and when to use each)
  4. write → .cursor/rules/usm.mdc

Generate CLAUDE.md for Claude Code (generate-claude-md) ​

Claude Code reads CLAUDE.md for project instructions. The file teaches the spec-first workflow and references the MCP server.

  1. generate → project identity and system summary
  2. generate → spec-first workflow instructions
  3. generate → MCP server connection info and tool reference
  4. smart-merge → preserve existing CLAUDE.md content outside markers

Enhance AGENTS.md with workflow instructions (enhance-agents-md) ​

Extend the existing agentsMd generator to include spec-first workflow instructions alongside the structural context it already produces.

  1. parse → existing AGENTS.md content
  2. generate → structural context (current behaviour — apps, packages, patterns)
  3. generate → workflow instructions section (new — spec-first loop, MCP tools)
  4. smart-merge → replace between USM markers, preserve rest

Contracts ​

all-tools-covered ​

All tools covered with always-on iron rules where a per-message mechanism exists

Acceptance criteria:

  • [ ] Cursor usm.mdc plus usm-always.mdc
  • [ ] Claude CLAUDE.md plus skills SKILL.md
  • [ ] Codex AGENTS.md detail only
  • [ ] Copilot instructions plus usm-iron-rules.md
  • [ ] opencode SKILL.md plus wired instructions

two-tier-enforcement-parity ​

Iron rules from one shared function; SKILL.md identical for opencode and Claude Code

Acceptance criteria:

  • [ ] Shared iron-rules body in all tiers
  • [ ] Identical SKILL.md across runtimes

Tests ​

generate-all-files ​

Given:

  • system_usm: true
  • service_files: true

Then:

  • assertion: .cursor/rules/usm.mdc exists with frontmatter
  • assertion: CLAUDE.md exists with workflow instructions
  • assertion: AGENTS.md has workflow section between markers
  • assertion: .github/copilot-instructions.md exists

cursor-mdc-frontmatter-valid ​

Given:

  • generated_mdc_file: true

Then:

  • assertion: frontmatter has description field
  • assertion: frontmatter has globs field with .usm patterns
  • assertion: body contains spec-first workflow instructions

smart-merge-preserves-custom-instructions ​

Given:

  • existing_claude_md_with_custom_content: true

Then:

  • assertion: custom content outside markers preserved
  • assertion: generated content inside markers updated

workflow-consistent-across-files ​

Given:

  • all_rules_files_generated: true

Then:

  • assertion: all files mention draft_feature workflow
  • assertion: all files mention human review step
  • assertion: all files mention update_feature_status after implementation

Implementation ​

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

See Also ​

  • usm/gen-agentsmd
  • usm/mcp-write
  • usm/gen-feature-review