mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-09-14 20:16:53 +08:00

Files

T

Tabish Bidiwale ab47cc6b00 feat: restructure schemas as directories with templates (#411 )

* feat: restructure schemas as directories with templates

Move built-in schemas from embedded TypeScript objects to a file-based
directory structure. This enables co-located templates alongside schemas.

Changes:
- Remove builtin-schemas.ts (replaced by file-based schemas)
- Add schemas/ directory at package root with spec-driven and tdd schemas
- Update resolveSchema() to load from directory structure
- Resolution checks user dir → package dir

* chore: archive restructure-schema-directories change

* docs: update artifact_poc.md for directory-based schema structure

Update documentation to reflect the new schema structure where schemas
are directories containing schema.yaml and co-located templates/ rather
than single .yaml files with separate template directories.

2025-12-28 17:00:15 +11:00

5.2 KiB

Raw Permalink Blame History

artifact-graph Specification

Purpose

TBD - created by archiving change add-artifact-graph-core. Update Purpose after archive.

Requirements

Requirement: Schema Loading

The system SHALL load artifact graph definitions from YAML schema files within schema directories.

Scenario: Valid schema loaded

WHEN a schema directory contains a valid schema.yaml file
THEN the system returns an ArtifactGraph with all artifacts and dependencies

Scenario: Invalid schema rejected

WHEN a schema YAML file is missing required fields
THEN the system throws an error with a descriptive message

Scenario: Cyclic dependencies detected

WHEN a schema contains cyclic artifact dependencies
THEN the system throws an error listing the artifact IDs in the cycle

Scenario: Invalid dependency reference

WHEN an artifact's requires array references a non-existent artifact ID
THEN the system throws an error identifying the invalid reference

Scenario: Duplicate artifact IDs rejected

WHEN a schema contains multiple artifacts with the same ID
THEN the system throws an error identifying the duplicate

Scenario: Schema directory not found

WHEN resolving a schema name that has no corresponding directory
THEN the system throws an error listing available schemas

Requirement: Build Order Calculation

The system SHALL compute a valid topological build order for artifacts.

Scenario: Linear dependency chain

WHEN artifacts form a linear chain (A → B → C)
THEN getBuildOrder() returns [A, B, C]

Scenario: Diamond dependency

WHEN artifacts form a diamond (A → B, A → C, B → D, C → D)
THEN getBuildOrder() returns A before B and C, and D last

Scenario: Independent artifacts

WHEN artifacts have no dependencies
THEN getBuildOrder() returns them in a stable order

Requirement: State Detection

The system SHALL detect artifact completion state by scanning the filesystem.

Scenario: Simple file exists

WHEN an artifact generates "proposal.md" and the file exists
THEN the artifact is marked as completed

Scenario: Simple file missing

WHEN an artifact generates "proposal.md" and the file does not exist
THEN the artifact is not marked as completed

Scenario: Glob pattern with files

WHEN an artifact generates "specs/*.md" and the specs/ directory contains .md files
THEN the artifact is marked as completed

Scenario: Glob pattern empty

WHEN an artifact generates "specs/*.md" and the specs/ directory is empty or missing
THEN the artifact is not marked as completed

Scenario: Missing change directory

WHEN the change directory does not exist
THEN all artifacts are marked as not completed (empty state)

Requirement: Ready Artifact Query

The system SHALL identify which artifacts are ready to be created based on dependency completion.

Scenario: Root artifacts ready initially

WHEN no artifacts are completed
THEN getNextArtifacts() returns artifacts with no dependencies

Scenario: Dependent artifact becomes ready

WHEN an artifact's dependencies are all completed
THEN getNextArtifacts() includes that artifact

Scenario: Blocked artifacts excluded

WHEN an artifact has uncompleted dependencies
THEN getNextArtifacts() does not include that artifact

Requirement: Completion Check

The system SHALL determine when all artifacts in a graph are complete.

Scenario: All complete

WHEN all artifacts in the graph are in the completed set
THEN isComplete() returns true

Scenario: Partially complete

WHEN some artifacts in the graph are not completed
THEN isComplete() returns false

Requirement: Blocked Query

The system SHALL identify which artifacts are blocked and return all their unmet dependencies.

Scenario: Artifact blocked by single dependency

WHEN artifact B requires artifact A and A is not complete
THEN getBlocked() returns { B: ['A'] }

Scenario: Artifact blocked by multiple dependencies

WHEN artifact C requires A and B, and only A is complete
THEN getBlocked() returns { C: ['B'] }

Scenario: Artifact blocked by all dependencies

WHEN artifact C requires A and B, and neither is complete
THEN getBlocked() returns { C: ['A', 'B'] }

Requirement: Schema Directory Structure

The system SHALL support self-contained schema directories with co-located templates.

Scenario: Schema with templates

WHEN a schema directory contains schema.yaml and templates/ subdirectory
THEN artifacts can reference templates relative to the schema's templates directory

Scenario: User schema override

WHEN a schema directory exists at ${XDG_DATA_HOME}/openspec/schemas/<name>/
THEN the system uses that directory instead of the built-in

Scenario: Built-in schema fallback

WHEN no user override exists for a schema
THEN the system uses the package built-in schema directory

Scenario: List available schemas

WHEN listing schemas
THEN the system returns schema names from both user and package directories

5.2 KiB Raw Permalink Blame History