handling and exploring artifacts

[Xavier-Brinon]

Feature Request: Numbered Artifact Files + Browser UI

I'd like to keep a chronological order when exploring artifacts.

Summary

Two related improvements inspired by
MADR (Markdown Architectural Decision
Records):

1. Numbered artifact filenames — prefix every change artifact with
   a zero-padded sequence number so artifacts sort chronologically and
   can be referenced unambiguously by number.
2. Artifact browser — a lightweight tool (CLI or web UI) to list,
   filter, and read all artifacts across changes, similar to what
   Log4brains or
   adr-viewer do for ADRs.

---

Motivation

Problem 1 — artifacts have no stable, ordered identity

Today a completed change lives at
openspec/changes/archive/YYYY-MM-DD-<name>/. Inside it, artifact
files are named by role (proposal.md, design.md, tasks.md) but
carry no global sequence number. This means:

• You cannot say "see change feat: Update spec change format #3" in a conversation or commit
  message.
• Shell ls sorts alphabetically by name, not creation order.
• Cross-linking between changes ("this supersedes Add init command for OpenSpec #7") is not
  possible without full path quoting.
• Archive folder names already carry the date, but the date alone is
  ambiguous when multiple changes are archived on the same day.

MADR solved this for ADRs by adopting the convention
NNNN-title-with-dashes.md (four zero-padded digits, up to 9 999
records). The same principle applied to opsx changes would give each
change a globally unique, stable, sortable identifier.

Problem 2 — no way to browse the artifact corpus

Once a project accumulates tens of archived changes, finding relevant
history requires grep or manual directory traversal. MADR's
ecosystem grew an entire family of tools to address exactly this:

• Log4brains — static site
  with search, rendered from markdown on disk.
• adr-viewer —
  single-command Python app that generates a searchable HTML page.
• Backstage ADR
  plugin
  — enterprise-scale search across multiple repos.
• ADR Manager — web UI connected to GitHub.

opsx has no equivalent. Proposals, specs, designs, and tasks are only
readable if you know the exact file path.

---

Proposed Changes

1. Numbered change directories

Assign each change a zero-padded four-digit sequence number at creation time:

openspec/changes/
  0001-scaffold-and-pipes/
  0002-book-crud/
  0003-status-machine/
  ...
  archive/
    0001-scaffold-and-pipes/   ← number preserved on archive
    0002-book-crud/

The sequence counter is maintained in a single file (e.g.,
openspec/.change-counter) or derived by scanning existing
directories — whichever is simpler. The openspec new change <name>
command would assign the next number automatically and create
NNNN-<name>/.

Benefits:

• Stable short references: "change 0003", "feat: Update spec change format #3".
• ls sorts chronologically without relying on date prefixes.
• Archive preserves the number, so 0003-status-machine remains
  0003-status-machine after archiving, not
  2026-02-18-status-machine.
• Cross-change references in design.md or tasks.md are unambiguous.

2. Numbered spec files within a change

Extend numbering to the artifact files themselves:

openspec/changes/0001-scaffold-and-pipes/
  proposal.md          ← role-named, single file, no number needed
  design.md
  tasks.md
  specs/
    0001-project-scaffold/
      spec.md
    0002-dotenvx-setup/
      spec.md

Spec capability folders already have names; adding a number makes
ordering explicit when multiple capabilities ship in one change.

3. openspec list command (CLI browser)

A new subcommand that renders a summary table of all changes:

$ openspec list

  #     Name                   Status     Artifacts   Date
  ────────────────────────────────────────────────────────
  0003  status-machine         active     3/4         2026-02-17
  0002  book-crud              archived   4/4         2026-02-10
  0001  scaffold-and-pipes     archived   4/4         2026-02-05

Options:

• --active — show only in-progress changes
• --archived — show only archived changes
• --json — machine-readable output for piping

4. openspec browse command (optional, stretch goal)

Launch a local static site (similar to Log4brains) that renders all
artifacts as navigable HTML with full-text search. Implementation
could reuse an existing tool (Log4brains, adr-viewer) or be a thin
wrapper around a markdown-to-HTML converter pointed at
openspec/changes/.

Thank you 🙆‍♂️

[1code-async]

Task completed.

The enrichment comment has been posted on issue #721. Here's a summary of what the analysis covers:

1. No duplicates found — this is a novel feature request. Only tangentially related issue is #16847.

2. Numbered change directories — Identified the key files: change-utils.ts (creation + validation), archive.ts (archive naming), list.ts (display), and types.ts (metadata schema). Noted two counter strategies (file-based vs. directory-scan) and the broad impact surface.

3. Numbered spec files — Largely compatible with current architecture since specs/**/*.md globs already support arbitrary subdirectory names. Minimal code changes needed.

4. openspec list enhancement — An openspec list command already exists but only shows active changes. The comment details exactly what's missing vs. the proposal (no --archived filter, no number column, no status column).

5. openspec browse — No existing code, but noted the existing openspec view terminal dashboard and MarkdownParser as potential building blocks.

6. Suggested implementation order and a migration consideration for existing YYYY-MM-DD archived changes.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Thanks for the detailed feature request. Here's a codebase analysis to help developers get started on each proposed change.

Duplicate / Related Issues

No duplicates found. The only tangentially related issue is #16847 (auto-load openspec/ directory for project context), which is about a different concern. This is a novel request.

---

Proposal 1: Numbered Change Directories

Key files to modify:

• src/utils/change-utils.ts:112-160 — createChange() builds the change directory path at line 142 as path.join(projectRoot, 'openspec', 'changes', name). This is where a sequence number prefix (NNNN-) would be prepended to name. A helper to scan existing directories (or read a counter file) and compute the next number would be added here.

• src/utils/change-utils.ts:48-88 — validateChangeName() enforces kebab-case via /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/. This regex would need to be updated (or a new pattern added) to accept the NNNN- prefix, e.g. /^\d{4}-[a-z][a-z0-9]*(-[a-z0-9]+)*$/.

• src/core/archive.ts:267-287 — Archive naming currently uses ${this.getArchiveDate()}-${changeName} (line 268). To preserve the number on archive, this would change to just move the directory as-is (since the number is already in the name), or keep the date as additional metadata. The getArchiveDate() method at line 335 would be affected.

• src/core/list.ts:77-151 — ListCommand.execute() lists changes by reading directory entries (line 92-95) and filtering out archive. Currently sorts by last-modified or name. Numbered directories would sort correctly by name, but the display format (line 149) would need updating to show the #NNNN column.

• src/core/artifact-graph/types.ts:41-52 — ChangeMetadataSchema could be extended with an optional number field to store the sequence number in .openspec.yaml, avoiding the need to parse it from the directory name.

Counter strategy considerations:

• File-based counter (openspec/.change-counter) is simpler but adds a mutable state file.
• Directory-scan approach (find max NNNN prefix) is stateless but slower and requires parsing.
• The created date in .openspec.yaml (line 46-51 of types.ts) already exists, so numbers would complement rather than replace dates.

Impact surface: The change name is used pervasively — in archive.ts, list.ts, change-utils.ts, change-metadata.ts, CLI commands in src/cli/index.ts, workflow templates in src/core/templates/workflows/, and validation in src/core/validation/. A thorough grep for directory name construction patterns is recommended.

---

Proposal 2: Numbered Spec Files Within a Change

Key files:

• schemas/spec-driven/schema.yaml — The specs artifact uses generates: "specs/**/*.md" as its glob pattern. This already supports arbitrary subdirectory names under specs/, so 0001-project-scaffold/spec.md would work without schema changes.

• src/core/artifact-graph/state.ts — detectCompleted() uses fast-glob to match the specs/**/*.md pattern. Numbered subdirectories would match without changes.

• src/core/archive.ts:114-131 — Delta spec detection iterates specs/ subdirectories looking for spec.md files. This is name-agnostic and would work with numbered directories.

This proposal is largely compatible with the current architecture since spec capability directories are already treated as opaque names. The main work would be in the new change workflow templates to auto-assign spec numbers when creating capabilities.

---

Proposal 3: openspec list Command (CLI Browser)

An openspec list command already exists — see src/core/list.ts and CLI registration in src/cli/index.ts. Current capabilities:

• Lists active changes with task progress and relative timestamps
• Supports --sort recent|name and --json output
• Supports --specs mode to list specifications

What's missing vs. the proposal:

• No --active / --archived filter (currently only shows active changes, never archived)
• No #NNNN column (since numbers don't exist yet)
• No Status column (active vs. archived)
• No Artifacts count column (e.g., "3/4") — though task progress is shown
• Archived changes are completely excluded at list.ts:93-94

To add archived change listing, the ListCommand would need to scan openspec/changes/archive/ in addition to the active directory, and parse the date prefix from archived directory names.

The --json output (line 129-138) already provides a good foundation for machine-readable output and could be extended with the new fields.

---

Proposal 4: openspec browse Command (Stretch Goal)

No existing code for this. This would be a new command registered in src/cli/index.ts. Potential approaches:

1. Thin wrapper around an existing tool — Point adr-viewer or a markdown-to-HTML tool at openspec/changes/ and openspec/specs/. Lowest effort but adds a Python/Node dependency.
2. Built-in static site generator — Use a library like marked (already indirectly available via the markdown parser at src/core/parsers/markdown-parser.ts) to convert specs to HTML with a simple template. More control, no external dependency.
3. openspec view — Note that an openspec view command already exists (registered in src/cli/index.ts) that provides an interactive terminal dashboard. The browse feature could extend this rather than creating a separate command.

---

Suggested Implementation Order

1. Numbered change directories (Proposal 1) — Foundation for everything else. Touches change-utils.ts, archive.ts, list.ts, validation, and workflow templates.
2. Enhanced list command (Proposal 3) — Builds on numbering. Extends existing ListCommand class.
3. Numbered spec files (Proposal 2) — Mostly convention; minimal code changes since globs already support it.
4. Browse command (Proposal 4) — Independent stretch goal.

Migration Consideration

Existing archived changes use the YYYY-MM-DD-<name> format. A migration strategy (or dual-format support during transition) would be needed for projects with existing archives.

[alfred-openspec]

Really well-researched issue, and the MADR/Log4brains references are spot on. The underlying needs here are real: stable IDs for cross-referencing, chronological ordering, and a way to browse history at scale.

We have been thinking about this as a management layer on top of the existing change format rather than changing the directory naming convention itself. The idea is that numbering, ordering, and cross-referencing would be handled by a higher-level system, keeping the core .openspec/changes/ structure stable (and avoiding a breaking change for everyone).

This approach also opens the door to flexible naming schemes. Sequential numbers for solo devs, ticket IDs for teams using Linear/Jira, etc.

This ties into a broader project management direction we are exploring. The openspec list improvements you mentioned are probably the natural starting point.

Thanks for putting this together so thoroughly, it is genuinely helpful for shaping the roadmap.