Common project-specific patterns that could enhance MARR standards #79
Description
Summary
During MARR installation in an existing project, we identified several project-specific patterns that recur across projects and could be valuable additions to MARR standards (or documented extension patterns).
Local Overrides Created
We created three local-*.md files to extend MARR standards. These patterns may be common enough to warrant inclusion in MARR itself.
1. Workflow Extensions (local-workflow-standard.md)
Process-First Mandate
CRITICAL FOR AI AGENTS: Perceived urgency does NOT bypass process.
Before ANY Investigation or Code Changes:
1. Verify issue exists in GitHub: `gh issue view <number>`
2. Confirm issue has proper description
3. Check for existing branch
4. Create branch BEFORE investigation
When User Requests Implementation Without Issue Numbers:
DO NOT start implementation. Ask for issue numbers first.
Issue Type Definitions
- Bug: Observed behaviour differs from expected/documented behaviour
- Feature: Medium/large deliverable broken down into Stories
- Story: Small deliverable completable in <3 days
- Task: Bounded activity with clear completion criteria
Release Scripts Pattern
npm run release:patch # Bug fixes (0.0.X)
npm run release:minor # New features (0.X.0)
npm run release:major # Breaking changes (X.0.0)
npm run release:hotfix # Emergency fixesHotfix Workflow
- Branch from production tag, NOT main
- Specific naming:
hotfix/<issue>-<description>
2. Testing Extensions (local-testing-standard.md)
Stack Declaration Pattern
This project uses:
- Unit Tests: Vitest
- E2E Tests: Playwright
- Framework: Next.js 14+ with React
- Language: TypeScript
Coverage Thresholds Pattern
| Component Type | Threshold |
|---|---|
| Global | 50/40/50/50 (statements/branches/functions/lines) |
| API Routes | 70% |
| Utilities | 80% |
| Components | 40% |
| Critical Paths | 90% |
Framework-Specific Skip Lists
- Skip: Next.js routing, React rendering, third-party internals
- Focus: Business logic, API authorization, Server Actions
3. UI/UX Extensions (local-ui-ux-standard.md)
MCP Tool Chain Pattern
1. v0 MCP: Generate initial component
2. shadcn/ui MCP: Install required components
3. tailwind MCP: Refine styling
4. a11y MCP: Validate accessibility
5. playwright MCP: Visual validation
Brand Colour Exception Policy
- Brand colours may override WCAG contrast when documented
- Requires: documentation in design-system.md, content redundancy
Specific Viewport Targets
Priority 1 - Mobile:
- iPhone 12 Pro: 390x844
- iPhone 14 Pro Max: 430x932
Priority 2 - Tablet:
- iPad Air: 820x1180
Priority 3 - Desktop:
- MacBook Air: 1280x832
Visual Regression Pattern
- Baselines in
tests/visual/baseline/ - Acceptable variance: <1% pixel difference
Suggestions
Option A: Add to MARR standards directly
Some patterns are universal enough to include in base MARR standards:
- Process-First Mandate (workflow)
- Issue Type definitions (workflow)
- Stack declaration template (testing)
- Coverage threshold template (testing)
- MCP tool chain pattern (ui-ux)
Option B: Create "extension templates"
Provide marr init --extend that generates local override templates with placeholders:
# Local Testing Standard
## Stack
- Unit Tests: [YOUR_TOOL]
- E2E Tests: [YOUR_TOOL]
- Framework: [YOUR_FRAMEWORK]
## Coverage Thresholds
[DEFINE_YOUR_THRESHOLDS]Option C: Document the pattern
Add documentation explaining how to create local overrides that extend MARR standards, with precedence rules.
Related
See #78 for installation UX challenges that led to discovering these patterns.