mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
ab47cc6b00
* 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.
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
# 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
|
|
|