Feature request: unified system overview / architecture document generated from specs

[clay-good]

Note

Moved from issue #978, originally opened by @henriqueajs on 2026-04-16. Continuing the conversation here in Discussions — the original issue thread (including any comments) stays available at #978 for the record.

---

Problem

As a project grows, the number of specs grows with it. At 10 specs you can keep them in your head. At 50 you start forgetting what exists. At 100+ it becomes impossible to understand the system as a whole by reading individual specs.

Today, OpenSpec is an excellent catalog of capabilities — each spec describes one piece of the system precisely. But there is no "map" that answers:

• What does this system do? (high-level, for a new team member or stakeholder)
• Which spec should I look at? (given a domain like "notifications" or "onboarding")
• How do capabilities relate to each other? (dependencies, shared data flows)
• What changed recently? (without reading every archived change)

This is not a documentation problem — it's a navigation problem. The content exists in the specs. What's missing is an aggregated view.

Real-world context

We have a React Native + FastAPI project with:

• 129 specs, 216 requirements
• 49 archived changes
• Domains spanning: onboarding, events/timers, notifications, analytics, auth, chat, reports, support network, medical consultations, and more

When we need to reason about the system (e.g., before a major refactor, or onboarding a new developer), we have to manually open dozens of spec files and build the mental model ourselves. An auto-generated overview would save hours per month.

Proposed solution

Core: openspec overview

A command that reads all specs and generates a unified document (e.g., SYSTEM_OVERVIEW.md or outputs to stdout). The document would contain:

1. Summary — total specs, requirements, recent changes count
2. Capabilities by domain — grouped list where each entry shows:
   • Spec name
   • 1-line summary (extracted from the ## Purpose / ## Propósito section)
   • Requirement count
   • Key files (from the ## Arquivos / ## Files table)
3. Recent changes — last N archived changes with date and summary
4. Dependency hints — specs that reference the same files or share Modified Capabilities

Enabling: openspec tag

To make grouping work, specs need a lightweight categorization mechanism:

# Tag a spec with a domain
openspec tag user-auth auth
openspec tag milestone-notifications notifications
openspec tag breastfeed-screen events

# View tags
openspec tag list

# Generate overview grouped by tag
openspec overview --by-tag

Tags could be stored as frontmatter in the spec file (e.g., tags: [notifications, milestones]) or in a separate index file. Either way, they should be optional — untagged specs go under "Uncategorized".

Variants

# Full overview document
openspec overview > SYSTEM_OVERVIEW.md

# Only recent changes (last 30 days)
openspec overview --recent --days 30

# Filter by domain
openspec overview --tag notifications

# JSON output for tooling/CI
openspec overview --json

Why this doesn't conflict with OpenSpec's core design

OpenSpec core	This proposal	Conflict?
Individual specs are the source of truth	Overview is read-only, generated from specs	No
Changes are the unit of work	Overview shows recent changes as a changelog	No
Specs describe capabilities, not architecture	Tags add navigation, not new content	No
openspec view shows a dashboard	Overview is a document (exportable, committable)	Complementary

The overview is an index to the catalog, not a replacement. Like a table of contents in a book — it doesn't duplicate the chapters, it helps you find them.

Additional ideas (lower priority)

• openspec view integration — the interactive dashboard could show specs grouped by tag instead of a flat list sorted by requirement count
• Auto-tagging — infer domain from file paths in the ## Files table (e.g., specs touching lib/notifications* → tag notifications)
• Staleness detection — flag specs whose referenced files have been modified since the spec was last updated (via git blame)
• Mermaid diagram — generate a simple dependency graph between specs that share files or were modified in the same change

Summary

OpenSpec scales well for writing specs. This proposal addresses reading them at scale. The core idea is simple: generate a navigable overview document from the existing spec catalog, optionally grouped by domain tags.

---

Submitted from a project with 129 specs, 216 requirements, and a team that loves OpenSpec but needs a map to navigate it.

[maciejmatczak]

I see a detachment from overall system abstraction as well. I think it relates.

Merged specs are very raw gherkins. These feel like unit tests.

I am missing a higher order documents that describe and design how the system works.

What is confusing is that open spec does help me to design how the system works: but only during a change creation where it additionally creates a proposal and design files.

Upon syncing these files are discarded.

And I am really missing sort of hierarchical details disclosing docs, where gherkins would serve lowest layer only.