🧩 Hybrid Approach: SPARC + MADR for Decision Documentation

[tbowman01]

As a developer, I have a need to add Architectural Design Records to our projects in order to assist with the governance and transparency workflow. I would like to explore if this is a feature @ruvnet or the community are interested in.

Goal: Combine SPARC’s structured, AI-augmented development pipeline with the clarity and traceability of MADR-style Architectural Decision Records. In practice, this means running a SPARC project and maintaining an /adr folder (or docs/decisions) where all significant architectural decisions are logged in Markdown. The two systems complement each other: SPARC gives you a working product with rich artifacts (code, tests, generated docs), while MADR ensures you don’t lose sight of the reasoning behind the key design and architecture choices made along the way.

📂 Suggested Project Structure with ADRs

/adr/ # ADR markdown files (the decision records log)
/plans/ # SPARC-generated specifications and plans (Specification phase outputs)
/architecture/ # SPARC-generated architecture artifacts (Architecture phase outputs, diagrams, etc.)
/tests/ # Tests (from SPARC's testing/TDD phases)
/src/ # Source code (from Refinement/Completion phases)
... # (other SPARC files: .roo config, .roomodes, etc.)

In this layout, the ADRs live in their own directory alongside the other major components of the project. Keeping adr/ at the top level (or under a top-level docs/ folder) is a common practice so that these records are easily discoverable. Meanwhile, SPARC’s normal output folders (like plans, architecture, etc.) remain as expected. The point is not to alter SPARC’s structure, but to augment it: whenever SPARC’s process results in a decision or an artifact that represents a choice, we create a corresponding entry in the adr/ log documenting that choice. The ADR files are plain text and can cross-reference the other artifacts. For example, an ADR might say “see the design diagram in /architecture/auth_flow.png for details” and the architecture.md might note “decision rationale recorded in ADR-0005”. This parallel structure ensures code, documentation, and decision records all travel together in the project.

** I have more detailed plans drafted if interested.

[hjain-spcg]

Question - Since architectural decisions often apply across multiple services or repositories (especially in distributed systems), it might make sense to maintain a dedicated Decision Records repository at the org or program level.

This centralized ADR repo could:

Track decisions that impact multiple systems (e.g., authentication strategies, data contracts, shared infrastructure).

Reference individual project-level ADRs where needed (e.g., via links or IDs).

Serve as a governance artifact for architecture review boards.

Of course, some decisions are very localized, and it still makes sense to keep those in the repo where the implementation lives. So we could adopt a hybrid model:

Local /adr folders for repo-specific decisions.
Global ADR repo for cross-cutting or foundational decisions.

Furthermore, am I the only one who gets concerned that as the number of tools and supporting artifacts grows — things like SPARC outputs, ADRs, test scaffolding, architecture diagrams, and config files — the repo risks becoming increasingly cluttered? It starts to blur the line between core implementation and surrounding process/meta artifacts, which may impact maintainability

[tbowman01]

Thanks for the thoughtful input — there are some excellent ideas here. I especially agree with the value of a high-level ADR repository to capture platform-wide or system-of-systems architectural decisions. My original focus was scoped to the monorepo level, but this broader perspective is important for ensuring architectural consistency and transparency across teams.

✅ Proposed Hybrid Approach

Adopt a two-tiered ADR structure:

• Localized /adr folders for context-specific or repo-scoped decisions (close to implementation).
• Centralized ADR repository for foundational, cross-cutting, or organizational decisions (e.g., authentication strategies, shared infrastructure, data contracts).

This model supports key goals:

• Transparency & traceability: Clear lineage of decisions at both local and global levels.
• Clear provenance: Each decision is documented in context, and cross-referenced as needed.
• DRY principle: Shared rationale is referenced, not duplicated.
• Developer experience: Localized decisions remain easy to access and manage, with a path to escalate or reference global decisions.

📁 Suggested Repository Structure

To support clarity and reduce clutter, we should consider a consistent structure across repositories:

/src # Core implementation
/test # Unit, integration, and system tests
/adr # Repo-specific architectural decision records
/docs/meta # Governance/process artifacts (e.g., checklists)
/docs/sparc # SPARC outputs (specs, pseudocode, refinements, etc.)

This structure helps cleanly separate core code from supporting artifacts, while enabling effective documentation, decision tracking, and governance alignment.

---

see sample ADR record below for an example of how this would operate. Given our discussion here, a sample record would look like the following:

NNNN-hybrid-adr-structure

• Status: Proposed
• Deciders: [Your name(s) or team name]
• Date: [YYYY-MM-DD]

Context and Problem Statement

As the number of services and teams grows, so does the complexity of capturing, maintaining, and navigating architectural decisions.

Currently, ADRs are often written locally in individual repositories, which works well for context-specific decisions but breaks down when architecture decisions span multiple services or impact platform-wide concerns (e.g., authentication, shared infrastructure, data contracts).

This can lead to:

• Inconsistent visibility of critical architectural decisions.
• Duplication of rationale across projects.
• Decreased maintainability due to clutter from mixed artifacts.

We need a scalable, transparent approach that balances local autonomy with organization-wide traceability.

Decision

We will adopt a hybrid ADR model that supports both local and centralized decision documentation.

Structure

• Local ADRs
  Each repository will maintain its own /adr folder for implementation-specific or tightly coupled decisions.

• Central ADR Repository
  A dedicated repository at the org or platform level will track foundational, cross-cutting, or shared decisions. These may include:

  • Authentication & authorization strategies
  • Shared infrastructure architecture
  • Common libraries or service templates
  • Data contracts or versioning strategies

• Cross-linking
  Local ADRs can reference central ADRs by ID or URL. Central ADRs may link back to specific project ADRs for implementation details.

Consequences

Benefits

• Supports transparency, traceability, and provenance of decisions.
• Prevents duplication of architectural rationale across teams.
• Enables developer-friendly workflows by keeping local concerns localized.
• Promotes governance readiness for architecture review boards.

Risks / Mitigations

• Potential for disconnect between local and central ADRs.
  Mitigation: Encourage linking and periodic review.
• Clutter risk in repos due to meta artifacts (SPARC, tests, diagrams).
  Mitigation: Adopt a consistent repo structure to separate concerns.

Suggested Repository Structure

To promote clarity and maintainability, the following layout is recommended:

/src # Core implementation
/test # Unit/integration/system tests
/adr # Repo-specific architecture decisions
/docs/meta # Governance and process artifacts
/docs/sparc # SPARC outputs (specs, pseudocode, refinement, etc.)

Alternatives Considered

• Centralized-only ADR repository
  Rejected because it removes implementation context and creates excessive friction for individual teams.

• Local-only ADRs in each repo
  Rejected because cross-cutting decisions get duplicated or missed entirely.

References

• MADR — Markdown Architectural Decision Records
• SPARC Methodology (if applicable)

[jrevillard]

ADR for a single application works also.... This would be interesting indeed.

[tbowman01]

This would increase standards across multiple projects and reduce duplicate code and Maintenace of code.
A side effect of this approach would be increased visibility and reuse of code modules.

[tbowman01]

@ruvnet What are your thoughts?

[ruvnet]

Makes sense. I like the split between local ADRs for module-specific context and a central repo for shared protocol-level decisions. Fits well with how SPARC agents operate across scopes. Main concern is divergence… might be worth enforcing sync rules or having agents auto-flag conflicts. Let’s keep it lightweight and agent-parsable. What do you think about next steps? @ruv

…

On Wed, Jul 16, 2025 at 8:08 PM tbowman01 ***@***.***> wrote: @ruvnet <https://github.com/ruvnet> What are your thoughts? — Reply to this email directly, view it on GitHub <#268 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAWMM6RYZ62RL42C7JWAASD3I3SOLAVCNFSM6AAAAACBQSBMJKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNZYGQYTONQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[tbowman01]

• Agreed. I agree, I have been thinking about the divergence aspect and documentation, training plan, and rollout approach.
• I'll look for a rust native ADR solution (or let the queen create one).
• A few features I was thinking about allowing it to be modular would be a standalone approach if one wanted to use this ADR tool in other repos.
• How to address the drift detection? scheduled scans, include all ADRs in ./adr and compare against last-known state, if any changes are identified, an issue is automatically created documenting the deltas in a draft ADR ready for human review.
• The portable version would be able to be applied to any repo. Initial ADR created from inventory of the repository leveraging the analysis function. Then the scheduled drift detection cycle would follow.
• Roadmap: add tasks to create documentation, training plan, and quick start markdowns.

[tbowman01]

draft

🚀 Functional Requirements

• Initialize ADR environment with boilerplate and templates
• Generate and store an inventory hash of the repository content
• Compare current state to previous snapshot to detect drift
• Generate delta-based ADR proposals from detected drift
• Build and update an index.md referencing all known ADRs
• Lint and validate ADR files for metadata completeness and formatting
• Output all command results in JSON by default
• Provide Node.js-compatible WASM bindings for CI/CD use
• Integrate seamlessly into GitHub Actions workflows
• Support markdown and table output formatting via flags

🔧 Non-Functional Requirements

• Built using safe, idiomatic Rust with clap, serde, walkdir, ignore
• Produce deterministic, reproducible outputs from scans and diffs
• Support CI/CD with unit, integration, and regression test coverage
• Maintain a small binary size and minimal memory footprint for CLI and WASM
• Support multi-platform operation (Linux, macOS, Windows)
• Cross-compile cleanly to wasm32-unknown-unknown with minimal external dependencies
• Follow SemVer for release versioning and changelogs
• Emit clear, actionable errors for invalid input or repository state
• Enable offline operation and caching for repeated scans
• Use SPDX identifiers and include license metadata in distributed packages

Adrscan Cli Design.pdf

[tbowman01]

@ruvnet @ohdearquant @hjain-spcg
I've built something... cli based works today with some additional features that are planned.
open to comments, suggestions, support... https://github.com/tbowman01/PhotonDrift/releases/tag/v0.2.0-alpha.20250721

[tbowman01]

Here is my pilot of this solution.
https://github.com/tbowman01/photonDrift/