feat: restructure schemas as directories with templates

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

openspec/specs/artifact-graph/spec.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
+

package.json

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

schemas/spec-driven/schema.yaml

@@ -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

schemas/spec-driven/templates/design.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 -->

schemas/spec-driven/templates/proposal.md

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

schemas/spec-driven/templates/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

schemas/spec-driven/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->

schemas/tdd/schema.yaml

@@ -0,0 +1,27 @@
+name: tdd
+version: 1
+description: Test-driven development workflow - tests → implementation → docs
+artifacts:
+  - id: spec
+    generates: spec.md
+    description: Feature specification defining requirements
+    template: spec.md
+    requires: []
+  - id: tests
+    generates: "tests/*.test.ts"
+    description: Test files written before implementation
+    template: test.md
+    requires:
+      - spec
+  - id: implementation
+    generates: "src/*.ts"
+    description: Implementation code to pass the tests
+    template: implementation.md
+    requires:
+      - tests
+  - id: docs
+    generates: "docs/*.md"
+    description: Documentation for the implemented feature
+    template: docs.md
+    requires:
+      - implementation

schemas/tdd/templates/docs.md

@@ -0,0 +1,15 @@
+## Overview
+
+<!-- Feature overview -->
+
+## Getting Started
+
+<!-- Quick start guide -->
+
+## Examples
+
+<!-- Code examples -->
+
+## Reference
+
+<!-- API reference or additional details -->

schemas/tdd/templates/implementation.md

@@ -0,0 +1,11 @@
+## Implementation Notes
+
+<!-- Technical implementation details -->
+
+## API
+
+<!-- Public API documentation -->
+
+## Usage
+
+<!-- Usage examples -->

schemas/tdd/templates/spec.md

@@ -0,0 +1,11 @@
+## Feature: <!-- feature name -->
+
+<!-- Feature description -->
+
+## Requirements
+
+<!-- List of requirements -->
+
+## Acceptance Criteria
+
+<!-- List of acceptance criteria -->

schemas/tdd/templates/test.md

@@ -0,0 +1,11 @@
+## Test Plan
+
+<!-- Describe the testing strategy -->
+
+## Test Cases
+
+### <!-- Test case name -->
+
+- **Given:** <!-- preconditions -->
+- **When:** <!-- action -->
+- **Then:** <!-- expected result -->