Verified by AI Team

This convention is integrated into OpenSpec workflow, with artifact management used for research and decision records in change proposals.

Change Artifacts

This document establishes conventions for managing supplementary documents that accompany OpenSpec change proposals. These artifacts capture the research, decisions, and communications that inform a change but are not part of the formal specification.

Problem Statement

During the lifecycle of a spec proposal, teams generate various supporting documents:

• Research notes comparing implementation approaches
• Architecture review conclusions
• PM scope discussions and priority decisions
• Meeting notes with stakeholders
• Vendor API analysis
• Security review findings

These documents are essential for understanding why decisions were made, but they are not generated by OpenSpec tooling. Without a clear convention, these files either:

1. Get scattered across different locations, losing traceability
2. Get mixed with OpenSpec-generated files, causing confusion
3. Get lost during archival, losing institutional knowledge

Solution: The artifacts/ Directory

Place all supplementary documents in an artifacts/ subdirectory within each change:

openspec/
└── changes/
    └── bulk-device-import/
        ├── proposal.md              # OpenSpec-generated
        └── artifacts/               # Supplementary documents
            ├── research.md
            ├── arch-review.md
            └── pm-discussion.md

Why artifacts/

Alternative	Issue
context/	Overloaded term in AI/LLM workflows
docs/	Too generic, conflicts with project-level docs
notes/	Implies informal, temporary content
supporting/	Verbose

artifacts/ clearly conveys: outputs produced during the change process.

Frontmatter Reference

Reference artifacts in the proposal's frontmatter for discoverability:

id: change-bulk-device-import
title: Bulk Device Import
status: active

artifacts:
  - artifacts/research.md
  - artifacts/arch-review.md
  - artifacts/pm-discussion.md

Typed References (Optional)

For more structured tracking:

id: change-bulk-device-import
title: Bulk Device Import
status: active

artifacts:
  research:
    - path: artifacts/research.md
      description: Batch processing approach comparison

  architecture:
    - path: artifacts/arch-review.md
      description: Architecture guild review conclusions

  communication:
    - path: artifacts/pm-discussion.md
      description: Scope and priority discussion with PM

Common Artifact Types

Type	Purpose	Example Filename
Research	Technical investigation, option analysis	research.md, poc-results.md
Architecture	Design reviews, ADR references	arch-review.md, adr-summary.md
Communication	Stakeholder discussions, scope decisions	pm-discussion.md, stakeholder-feedback.md
Security	Security review findings, threat analysis	security-review.md
External	Vendor docs, third-party specifications	vendor-api-notes.md

Lifecycle

During Development

Artifacts accumulate as the change progresses:

changes/bulk-device-import/
├── proposal.md
└── artifacts/
    ├── research.md           # Week 1: Initial research
    ├── arch-review.md        # Week 2: Architecture review
    ├── pm-discussion.md      # Week 3: Scope refinement
    └── security-review.md    # Week 4: Security approval

During Archival

When a change is completed and archived, the entire directory moves together:

# Entire change directory moves to archive
mv openspec/changes/bulk-device-import openspec/archive/bulk-device-import

The artifacts/ directory preserves the full decision history:

archive/bulk-device-import/
├── proposal.md
└── artifacts/
    ├── research.md
    ├── arch-review.md
    ├── pm-discussion.md
    └── security-review.md

For Postponed/Cancelled Changes

Artifacts remain with the change in changes/:

changes/bulk-device-import/       # status: postponed
├── proposal.md
└── artifacts/
    ├── research.md
    └── arch-review.md            # Preserved for when work resumes

Benefits

Benefit	Description
Clear separation	OpenSpec files vs. supplementary documents
Traceability	Artifacts move with the change through its lifecycle
AI-readable	Frontmatter references enable agent discovery
Tool compatibility	Doesn't interfere with OpenSpec CLI operations
Complete history	Archived changes retain full decision rationale

Anti-Patterns

1. Mixing with OpenSpec Files

Problem:

changes/bulk-device-import/
├── proposal.md
├── research.md          # Mixed at root level
└── arch-review.md

Why it fails: Unclear which files are OpenSpec-managed vs. supplementary.

Instead: Use artifacts/ subdirectory.

2. External Storage Without Reference

Problem:

# Artifacts stored elsewhere without reference
docs/research/bulk-import.md    # No link from proposal

Why it fails: Context is lost; artifacts become orphaned.

Instead: Reference in frontmatter, or store in artifacts/.

3. Overly Deep Nesting

Problem:

artifacts/
└── research/
    └── 2025/
        └── q1/
            └── bulk-import/
                └── notes.md

Why it fails: Over-engineering; harder to navigate.

Instead: Flat structure within artifacts/.

Note: If you're not using OpenSpec, you'll need to design similar artifact management conventions yourself. The core principles remain the same: supplementary documents should stay with the proposal, be referenced in frontmatter or the proposal, and move with the proposal throughout its lifecycle.

References

• OpenSpec - Specification-driven development framework