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.

Author: TabishB

docs/artifact_poc.md

@@ -52,8 +52,8 @@ Schemas can vary across multiple dimensions:
 Schemas follow the XDG Base Directory Specification with a 2-level resolution:
 
 ```
-1. ${XDG_DATA_HOME}/openspec/schemas/<name>.yaml   # Global user override
-2. <package>/schemas/<name>.yaml                    # Built-in defaults
+1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # Global user override
+2. <package>/schemas/<name>/schema.yaml                    # Built-in defaults
 ```
 
 **Platform-specific paths:**
@@ -69,25 +69,23 @@ Schemas follow the XDG Base Directory Specification with a 2-level resolution:
 
 ### Template Inheritance (2 Levels Max)
 
-Templates also use 2-level resolution (to be implemented in Slice 3):
+Templates are co-located with schemas in a `templates/` subdirectory:
 
 ```
-1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # Schema-specific
-2. ${XDG_DATA_HOME}/openspec/templates/<artifact>.md                   # Shared
-3. <package>/templates/<artifact>.md                                    # Built-in fallback
+1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+2. <package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
 ```
 
 **Rules:**
-- Schema-specific templates override shared templates
-- Shared templates override package built-ins
+- User overrides take precedence over package built-ins
 - A CLI command shows resolved paths (no guessing)
 - No inheritance between schemas (copy if you need to diverge)
-- Max 2 levels - no deeper inheritance chains
+- Templates are always co-located with their schema
 
 **Why this matters:**
 - Avoids "where does this come from?" debugging
 - No implicit magic that works until it doesn't
-- Clear boundaries between shared and specific
+- Schema + templates form a cohesive unit
 
 ---
 
@@ -333,21 +331,19 @@ This separation means:
 ### 3. XDG-Compliant Schema Resolution
 
 ```
-${XDG_DATA_HOME}/openspec/schemas/<name>.yaml   # User override
+${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # User override
     ↓ (not found)
-<package>/schemas/<name>.yaml                    # Built-in
+<package>/schemas/<name>/schema.yaml                    # Built-in
     ↓ (not found)
 Error (schema not found)
 ```
 
-### 4. Two-Level Template Fallback (Slice 3)
+### 4. Two-Level Template Fallback
 
 ```
-${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # Schema-specific
+${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
     ↓ (not found)
-${XDG_DATA_HOME}/openspec/templates/<artifact>.md                   # Shared
-    ↓ (not found)
-<package>/templates/<artifact>.md                                    # Built-in
+<package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
     ↓ (not found)
 Error (no silent fallback to avoid confusion)
 ```
@@ -487,21 +483,29 @@ Structured as **vertical slices** - each slice is independently testable.
 # Global (XDG paths - user overrides)
 ~/.local/share/openspec/           # Unix/macOS ($XDG_DATA_HOME/openspec/)
 %LOCALAPPDATA%/openspec/           # Windows
-├── schemas/                       # Schema overrides
-│   └── custom-workflow.yaml       # User-defined schema
-└── templates/                     # Template overrides (Slice 3)
-    └── proposal.md                # Custom proposal template
+└── schemas/                       # Schema overrides
+    └── custom-workflow/           # User-defined schema directory
+        ├── schema.yaml            # Schema definition
+        └── templates/             # Co-located templates
+            └── proposal.md
 
 # Package (built-in defaults)
 <package>/
-├── schemas/                       # Built-in schema definitions
-│   ├── spec-driven.yaml           # Default: proposal → specs → design → tasks
-│   └── tdd.yaml                   # TDD: tests → implementation → docs
-└── templates/                     # Built-in templates (Slice 3)
-    ├── proposal.md
-    ├── design.md
-    ├── specs.md
-    └── tasks.md
+└── schemas/                       # Built-in schema definitions
+    ├── spec-driven/               # Default: proposal → specs → design → tasks
+    │   ├── schema.yaml
+    │   └── templates/
+    │       ├── proposal.md
+    │       ├── design.md
+    │       ├── spec.md
+    │       └── tasks.md
+    └── tdd/                       # TDD: tests → implementation → docs
+        ├── schema.yaml
+        └── templates/
+            ├── test.md
+            ├── implementation.md
+            ├── spec.md
+            └── docs.md
 
 # Project (change instances)
 openspec/
@@ -528,8 +532,8 @@ openspec/
 ## Schema YAML Format
 
 ```yaml
-# Built-in: <package>/schemas/spec-driven.yaml
-# Or user override: ~/.local/share/openspec/schemas/spec-driven.yaml
+# Built-in: <package>/schemas/spec-driven/schema.yaml
+# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml
 name: spec-driven
 version: 1
 description: Specification-driven development
@@ -538,7 +542,7 @@ artifacts:
   - id: proposal
     generates: "proposal.md"
     description: "Create project proposal document"
-    template: "proposal.md"          # resolves via 2-level fallback (Slice 3)
+    template: "proposal.md"          # resolves from co-located templates/ directory
     requires: []
 
   - id: specs

…restructure-schema-directories/design.md …restructure-schema-directories/design.mdopenspec/changes/restructure-schema-directories/design.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md openspec/changes/restructure-schema-directories/design.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/design.md

@@ -4,10 +4,10 @@
 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.
+The system SHALL load artifact graph definitions from YAML schema files within schema directories.
 
 #### Scenario: Valid schema loaded
-- **WHEN** a valid schema YAML file is provided
+- **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
@@ -26,6 +26,10 @@ The system SHALL load artifact graph definitions from YAML schema files.
 - **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.
 
@@ -105,3 +109,22 @@ The system SHALL identify which artifacts are blocked and return all their unmet
 - **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
+

…structure-schema-directories/proposal.md …structure-schema-directories/proposal.mdopenspec/changes/restructure-schema-directories/proposal.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/proposal.md openspec/changes/restructure-schema-directories/proposal.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/proposal.md

@@ -32,6 +32,7 @@
   "files": [
     "dist",
     "bin",
+    "schemas",
     "scripts/postinstall.js",
     "!dist/**/*.test.js",
     "!dist/**/__tests__",

…directories/specs/artifact-graph/spec.md …directories/specs/artifact-graph/spec.mdopenspec/changes/restructure-schema-directories/specs/artifact-graph/spec.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/specs/artifact-graph/spec.md openspec/changes/restructure-schema-directories/specs/artifact-graph/spec.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/specs/artifact-graph/spec.md

@@ -0,0 +1,28 @@
+name: spec-driven
+version: 1
+description: Default OpenSpec workflow - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    requires: []
+  - id: specs
+    generates: "specs/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    requires:
+      - proposal
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    requires:
+      - proposal
+  - id: tasks
+    generates: tasks.md
+    description: Implementation tasks derived from specs and design
+    template: tasks.md
+    requires:
+      - specs
+      - design

…/restructure-schema-directories/tasks.md …-restructure-schema-directories/tasks.mdopenspec/changes/restructure-schema-directories/tasks.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/tasks.md openspec/changes/restructure-schema-directories/tasks.md renamed to openspec/changes/archive/2025-12-28-restructure-schema-directories/tasks.md

@@ -0,0 +1,19 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->

openspec/specs/artifact-graph/spec.md

@@ -0,0 +1,11 @@
+## Why
+
+<!-- Explain the motivation for this change -->
+
+## What Changes
+
+<!-- Describe what will change -->
+
+## Impact
+
+<!-- List affected areas -->