Strategic planning across multiple repositories using MARR standards

[virtualian]

Cross-Repository Roadmap Governance

This document describes a pattern for managing strategic planning across multiple repositories using MARR standards.

The Problem

Organisations with multiple repositories often need a central place for high-level planning—ideas, features, release bundles—that spans individual codebases. GitHub Projects can serve this purpose, but Projects have limitations: draft items aren't full issues, cross-repo linking is manual, and there's no native hierarchy.

A common solution is a dedicated "roadmap" repository whose sole purpose is to hold strategic issues. These issues are then decomposed into repo-level work items as implementation proceeds.

This approach is sound but brittle. The connection between roadmap items and implementation items degrades without discipline. People forget to link. Links rot. New contributors don't know the upstream context exists.

How MARR Helps

A MARR standard can encode the governance rules for this workflow. When Claude Code works on roadmap items or repo-level issues, the standard triggers and provides binding constraints on structure, linking, and decomposition.

This shifts enforcement from reactive (validation after the fact) to proactive (correct behaviour at the point of work).

Standard Scope

A roadmap governance standard should cover:

Area	Guidance
Item structure	Required sections for roadmap issues (tier, target release, acceptance criteria, linked repos)
Tier definitions	What distinguishes an idea from a feature from a release bundle
Decomposition rules	When a roadmap item is ready for breakdown, how to create downstream items, linking conventions
Cross-repo linking	Consistent markdown format for upstream/downstream references
Status transitions	What "in progress" and "done" mean at the roadmap level vs. repo level

Complementary Automation

MARR standards govern AI agent behaviour. GitHub Actions can provide validation for human-created items and catch drift over time:

• Verify required sections exist on issue creation
• Check that PRs in downstream repos reference roadmap issues
• Scheduled scans for orphaned or stale items

Actions are reactive; MARR is proactive. Used together, they cover both modes of work.

Placement

This standard can operate at two levels:

• User-level (~/.claude/marr/): If the same governance applies across all your projects
• Project-level (.claude/marr/): If governance rules vary per organisation or product area

For most cases, project-level placement in the roadmap repository is appropriate, with downstream repos referencing the same standard or a simplified version that covers only the linking requirements.

Limitations

MARR cannot enforce behaviour by humans who bypass Claude Code. It cannot validate that decomposition has occurred or that links remain valid. These gaps require either manual discipline or complementary automation.

[virtualian]

Here's text for a proposed issue to work on the above:

Summary

Propose a new bundled standard covering governance of strategic planning across multiple repositories—specifically the pattern where a dedicated "roadmap" repo holds high-level issues that decompose into work items in downstream repos.

Problem

GitHub Projects don't natively support hierarchical issue relationships across repos. A common workaround is a roadmap repository for strategic items, with manual decomposition and linking to implementation repos. This works but degrades without discipline: links rot, people forget to reference upstream items, new contributors miss context.

MARR can help by encoding the governance rules as a standard that triggers when working on roadmap or cross-repo items.

Proposed Standard

File: prj-roadmap-governance-standard.md

Triggers:

• WHEN creating or modifying issues in a roadmap or planning repository
• WHEN decomposing high-level items into repository-level work
• WHEN creating issues or PRs that should trace to upstream roadmap items

Core rules should cover:

1. Required structure for roadmap issues (tier, target release, acceptance criteria, linked repos)
2. Tier definitions (idea → feature → release bundle, or similar)
3. Decomposition criteria—when an item is ready for breakdown
4. Linking conventions—consistent markdown format for upstream/downstream references
5. Status semantics—what "in progress" and "done" mean at roadmap vs. repo level

Anti-patterns:

• Creating implementation work without upstream reference
• Roadmap items with no acceptance criteria
• Using vague tier labels or omitting tier entirely
• Decomposing before the item is sufficiently defined

Complementary Automation

The standard could include guidance (in an appendix or separate doc) on GitHub Actions that validate adherence:

• Required sections on issue create/edit
• PR body must reference roadmap issue
• Scheduled orphan/stale detection

Placement

Likely project-level in the roadmap repo, with downstream repos optionally including a lighter "linking-only" variant.

Open Questions

• Should tier definitions be prescriptive or left to project customisation?
• How opinionated should the linking format be? (e.g., mandate Roadmap: org/roadmap#123 vs. any valid issue reference)
• Is a separate doc for Actions guidance appropriate, or out of MARR's scope?