Installation UX challenges when adopting MARR in existing projects

[virtualian]

Summary

Installing MARR in a project with existing standards revealed several UX challenges that made the adoption process confusing and error-prone.

Context

The project had existing standards in prompts/ directory:

• prj-git-workflow-standard.md (509 lines, project-specific)
• prj-testing-standard.md (Vitest/Playwright specific)
• prj-ui-ux-standard.md (v0 MCP workflow specific)
• prj-brand-voice-standard.md (unique to project)

Challenges Encountered

1. No guidance on "extend vs replace" pattern

When running marr init --project, it installs generic MARR standards that overlap with existing project-specific ones. There's no guidance on:

• Should I delete my existing standards?
• Should I keep both? (precedence unclear)
• How do I create "local overrides" that extend MARR?

Resolution we used: Created prompts/local-*.md files that explicitly state "This standard EXTENDS and OVERRIDES MARR standards" and imported them in CLAUDE.md.

2. marr doctor false positives

Doctor flags documentation files as "conflicts" when they're not standards at all:

[2/6] Duplicate Standard
  Location: docs/component-architecture.md
  Found: "Custom ui/ux development rules in component-architecture.md"

This is a docs file, not a standard. The detection appears to be keyword-based rather than semantic.

3. marr doctor lacks context for decision-making

When doctor shows a conflict, it only displays:

• File location
• A single line "Found: ..."
• What MARR expects

Missing information needed to judge:

• What does the existing file actually contain?
• Is this truly a conflict or a false positive?
• What would be lost if I choose "Use MARR"?
• Is the existing file an intentional extension or accidental duplication?

Example output:

[1/6] Duplicate Standard
  Location: prompts/local-workflow-standard.md
  Found: "Custom workflow rules in local-workflow-standard.md"
  MARR expects: MARR provides prj-workflow-standard.md

  Options:
    [k] Keep yours
    [m] Use MARR (recommended)
    [b] Keep both
    [s] Skip

I cannot judge this without knowing:

• What's in local-workflow-standard.md?
• What's in the MARR prj-workflow-standard.md?
• Does my file add project-specific value or just duplicate MARR?

4. marr init --force overwrites customisations

After customising MARR-PROJECT-CLAUDE.md to reference existing prompts/ standards, running marr init --project --force overwrote those changes.

5. No "local override" concept in MARR

MARR assumes standards live in .claude/marr/standards/. There's no built-in pattern for:

• Project-specific extensions that layer on top of MARR
• Preserving project-specific details (tools, thresholds, processes)
• Clear precedence chain

Suggestions

1. Add "extend" mode to init: marr init --extend that creates local override templates referencing MARR standards

2. Improve doctor context: Show file previews or summaries, allow viewing full files before deciding

3. Smarter conflict detection: Check for YAML frontmatter (marr: standard) before flagging files as potential standards

4. Document the local override pattern: Explain how to create local-*.md files that extend MARR

5. Protect customisations: Warn before overwriting modified MARR-PROJECT-CLAUDE.md

Environment

• MARR version: (run marr --version)
• Project: Next.js 14+, TypeScript
• Existing standards: 4 files in prompts/