marr

Standards Reference

This document describes each bundled standard that ships with MARR.

Overview

MARR includes seven standards covering common development concerns:

Standard Purpose
Development Workflow Issues, tasks, releases, and hotfixes
Version Control Git branches, commits, PRs, and tagging
Testing Running, writing, and evaluating tests
Documentation Creating and organizing docs
MCP Usage Using Model Context Protocol tools
UI/UX Component design and accessibility
Writing Prompts Creating AI agent instructions

Development Workflow Standard

File: prj-development-workflow-standard.md

Triggers:

Core Rules

  1. Verify issue exists before any action — All work must be tracked
  2. Never start implementation without an issue number — Traceability matters
  3. Create branch before investigation — Even exploration should be tracked

Issue Types

Type Definition
Bug Observed behavior differs from expected
Feature Medium/large deliverable broken into Stories
Story Small deliverable completable in <3 days
Task Bounded activity with clear completion criteria

Release Management

Version Control Standard

File: prj-version-control-standard.md

Triggers:

Core Rules

  1. Never make code changes on main — Main must always be deployable
  2. Always squash merge — Linear history is easier to debug
  3. Delete merged branches — Keep the repository clean
  4. Branch from main only — Except hotfixes from production tags
  5. Use issue-based branch naming — Format: <issue-number>-<descriptive-name>

Key Practices

Testing Standard

File: prj-testing-standard.md

Triggers:

Core Rules

  1. Test behavior, not implementation — Users care about outcomes
  2. Focus on critical paths — That’s where bugs have the highest impact
  3. Meaningful tests over metrics — Quality trumps quantity
  4. Never commit with test failures — Broken tests break everyone

Testing Priorities

Always test:

Skip testing:

Coverage Philosophy

Coverage is a guide, not a goal. A well-tested critical path is more valuable than 100% coverage of trivial code.

Documentation Standard

File: prj-documentation-standard.md

Triggers:

Core Rules

  1. All documentation lives in docs/ — Scattered docs are invisible
  2. Organize by role first, then content type — Users identify by role before need
  3. Keep content types distinct — Mixed purposes confuse readers
  4. Update docs when code changes — Outdated docs mislead users
  5. No AI attribution — Content stands on merit

Content Types (Diátaxis Framework)

Type Purpose Key Requirement
how-to/ Task-oriented guides Steps only, assume competence
reference/ Technical descriptions Structured for lookup
explanation/ Design decisions The “why”, no procedures

MCP Usage Standard

File: prj-mcp-usage-standard.md

Triggers:

Core Rules

  1. Be specific in tool requests — Ambiguous requests cause wrong tool selection
  2. Use explicit tool names when unclear — AI cannot infer intent from vague descriptions
  3. Never assume tool capabilities — Each MCP has specific, limited functionality
  4. Verify tool availability before use — Not all environments have all MCPs

Best Practices

UI/UX Standard

File: prj-ui-ux-standard.md

Triggers:

Core Rules

  1. Always prioritize accessibility — Legal compliance and usability are non-negotiable
  2. Always use mobile-first design — Mobile traffic dominates modern web
  3. Always validate with accessibility tools — Automated validation catches issues early
  4. Always maintain brand consistency — Professional appearance builds trust
  5. Always optimize for conversion — Business goals require measurable outcomes

Accessibility Requirements

Mobile-First Priorities

  1. Mobile (375px-430px) — Primary design target
  2. Tablet (768px-1024px) — Secondary
  3. Desktop (1280px+) — Tertiary

Writing Prompts Standard

File: prj-writing-prompts-standard.md

Triggers:

Core Rules

  1. Always be user and project agnostic — Standards must apply anywhere
  2. Specify WHAT and WHY, never HOW — AI agents determine implementation
  3. Never include code, commands, or configuration — Prompts are directives, not tutorials
  4. Write unconditional imperatives — Standards are not suggestions
  5. Make every statement verifiable — Unenforceable rules are not standards
  6. Never modify standards without explicit approval — Controlled documents

Required Structure

Every standard file must have:

  1. YAML frontmatter (metadata)
  2. Header with AI agent instructions
  3. Core rules (non-negotiable requirements)
  4. Detailed sections (expanded guidance)
  5. Anti-patterns (forbidden behaviors)

Trigger Design

Triggers are natural language descriptions of situations:

Choosing Standards

Not every project needs every standard. Select based on your needs:

If your project… Consider these standards
Uses git Development Workflow, Version Control
Has tests Testing
Has documentation Documentation
Uses AI tools MCP Usage
Has a UI UI/UX
Has AI config files Writing Prompts

Install only what you need:

# Interactive selection
marr init --project

# All standards
marr init --project --standards all

# List available
marr init --standards list
This site is open source. Improve this page.