Feature Idea: "Living Architecture" — Syncing design.md to a central designs folder

[pacaplan]

Message: Hi there!

I’ve been using OpenSpec and really appreciate how it creates a "living source of truth" for requirements by syncing spec deltas into the central openspec/specs/ folder during the archive process.

I’d like to suggest extending this behavior to the design.md artifact. Currently, the technical design for a change stays within the specific change folder and eventually moves to the archive.

The Proposal: Just as specs are synced, could we have a central openspec/designs/ directory (or similar)? When a change is archived, the design.md (or relevant sections) would be synced or moved to this central directory.

Why this helps: Why this helps: This creates a persistent "Living Architecture" that provides essential context for both developers and AI agents, preventing critical technical documentation from being buried in historical archive folders.

Would love to hear your thoughts!

[alonl]

I agree it's essential.

[TabishB]

Similar to the ADR discussion here: #557

What needs to happen is we need to make this a customizable feature. Where users can choose to select what artifacts to sync and what a source of truth for those artifacts looks like!

Open to any change proposals where this kind of logic can be set in the schema and retrieved by an agent on demand to figure out

1. What needs to be synced
2. How to perform that sync

[whfreelove]

Seems to me we could extend schema.yaml with optional sections:

1. project — Define sources of truth (specs, ADRs, architecture)
2. flows — Configure sync with strategy + options pattern

I'm using flows.strategy: delta as the current ADDED/MODIFIED/REMOVED/RENAMED structure for specs because I think it can be broadly applied elsewhere with decent value (like minimal ADRs such as Y-Statements in a list). The main change to support that is to generalize what gets matched for a section ("### Requirements:" for specs) and its key (the rest of the header line for specs).

• Backward-compatible: Schemas without project/flows default to current spec-only "delta" matching and behavior
• Forward-compatible: supports other strategy ideas without a schema change
  • replace update whole target section with no list or keys required (no keyed list requirement)
  • prompt similar to change artifacts with instruction prompt to merge changes into a project source of truth

Example (in addition to specs, this would add ADRs and a list of capabilities from changes):

project:
  - id: specs
    path: "openspec/specs"
  - id: adr
    path: "openspec/adr.md"
  - id: capabilities
    path: "openspec/capabilities.md"

flows:
  # Spec sync (default options)
  - from: specs
    to: specs
    strategy: delta
    options:
      headers:
        added: "ADDED Requirements"
        modified: "MODIFIED Requirements"
        removed: "REMOVED Requirements"
        renamed: "RENAMED Requirements"
      source: "### Requirement:"
      target: "## Requirements"

  # Change design decisions -> ADRs source of truth
  - from: design
    to: adr
    strategy: delta
    options:
      headers:
        added: "New Decisions"
        modified: "Updated Decisions"
        removed: "Deprecated Decisions"
        renamed: "Renamed Decisions"
      source: "list-item"
      target: "## Decisions"

  # Change proposal capabilities -> capabilities source of truth
  - from: proposal
    to: capabilities
    strategy: delta
    options:
      headers:
        added: "New Capabilities"
        modified: "Modified Capabilities"
        removed: "Removed Capabilities"
        renamed: "Renamed Capabilities"
      source: "list-item"
      target: "## Capabilities"

Capabilities already has keyed lists for this to use (I don't know if anyone actually cares for that functionality; it was just a good model to start from), but tracking ADRs would require the design.md template to insert the structure and instructions to use it. Seems like a low hurdle. A similar approach for "Risks / Trade-Offs" might appeal to folks as a project source of truth as well, but they'd need similar template work.

If the structure makes sense, I should be able to get a PR for it this week.

[whfreelove]

Actually, this is problematic; it assumes a single schema per project. Maybe okay for a default use case and the vast majority of users, but I'd prefer different schemas for different types of changes myself.

To support that, you'd need both change schemas and project schemas which will have compatibility concerns. I'd maintain that kind of thing for my own projects, but I suspect that's even less interesting to everyone overall.