feat: add instruction loader for template loading and change context

openspec/changes/add-instruction-loader/specs/instruction-loader/spec.md

@@ -1,13 +1,18 @@
-## ADDED Requirements
+# instruction-loader Specification
+
+## Purpose
+Load templates from schema directories and enrich them with change-specific context for guiding artifact creation.
+
+## Requirements
 
 ### Requirement: Template Loading
 The system SHALL load templates from schema directories.
 
-#### Scenario: Template loaded from schema directory
+#### Scenario: Load template from schema directory
 - **WHEN** `loadTemplate(schemaName, templatePath)` is called
 - **THEN** the system loads the template from `schemas/<schemaName>/templates/<templatePath>`
 
-#### Scenario: Template not found
+#### Scenario: Template file not found
 - **WHEN** a template file does not exist in the schema's templates directory
 - **THEN** the system throws an error with the template path
 
@@ -22,44 +27,44 @@ The system SHALL load change context combining graph and completion state.
 - **WHEN** `loadChangeContext(projectRoot, changeName, schemaName)` is called
 - **THEN** the system uses the specified schema instead of default
 
-#### Scenario: Load context for missing change
+#### Scenario: Load context for non-existent change directory
 - **WHEN** `loadChangeContext` is called for a non-existent change directory
 - **THEN** the system returns context with empty completed set
 
-### Requirement: Instruction Enrichment
+### Requirement: Template Enrichment
 The system SHALL enrich templates with change-specific context.
 
-#### Scenario: Header with change info
+#### Scenario: Include artifact metadata
 - **WHEN** instructions are generated for an artifact
 - **THEN** the output includes change name, artifact ID, schema name, and output path
 
-#### Scenario: Dependency status shown
+#### Scenario: Include dependency status
 - **WHEN** an artifact has dependencies
 - **THEN** the output shows each dependency with completion status (done/missing)
 
-#### Scenario: Next steps shown
+#### Scenario: Include unlocked artifacts
 - **WHEN** instructions are generated
 - **THEN** the output includes which artifacts become available after this one
 
-#### Scenario: Root artifact dependencies
+#### Scenario: Root artifact indicator
 - **WHEN** an artifact has no dependencies
 - **THEN** the dependency section indicates this is a root artifact
 
 ### Requirement: Status Formatting
 The system SHALL format change status as readable output.
 
-#### Scenario: Format complete change
+#### Scenario: All artifacts completed
 - **WHEN** all artifacts are completed
 - **THEN** status shows all artifacts as "done"
 
-#### Scenario: Format partial change
+#### Scenario: Mixed completion status
 - **WHEN** some artifacts are completed
 - **THEN** status shows completed as "done", ready as "ready", blocked as "blocked"
 
-#### Scenario: Show blocked dependencies
+#### Scenario: Blocked artifact details
 - **WHEN** an artifact is blocked
 - **THEN** status shows which dependencies are missing
 
-#### Scenario: Show output paths
+#### Scenario: Include output paths
 - **WHEN** status is formatted
 - **THEN** each artifact shows its output path pattern

openspec/changes/add-instruction-loader/tasks.md

@@ -1,34 +1,13 @@
-## 1. Template Loading
-
-- [ ] 1.1 Create `src/core/artifact-graph/template.ts`
-- [ ] 1.2 Implement `loadTemplate(schemaName, templatePath)` using schema directory structure
-- [ ] 1.3 Add tests for template loading from schema directory
-- [ ] 1.4 Add tests for error when template not found
-
-## 2. Change Context
-
-- [ ] 2.1 Create `src/core/artifact-graph/context.ts`
-- [ ] 2.2 Define `ChangeContext` interface
-- [ ] 2.3 Implement `loadChangeContext()` function
-- [ ] 2.4 Add tests for context loading with existing change
-- [ ] 2.5 Add tests for context loading with missing change directory
-
-## 3. Instruction Enrichment
-
-- [ ] 3.1 Create `src/core/artifact-graph/instructions.ts`
-- [ ] 3.2 Implement `getInstructions()` with header injection
-- [ ] 3.3 Add dependency status formatting (done/missing)
-- [ ] 3.4 Add next steps calculation
-- [ ] 3.5 Add tests for enrichment output
-
-## 4. Status Formatting
-
-- [ ] 4.1 Implement `formatStatus()` function in instructions.ts
-- [ ] 4.2 Format as markdown table with status and output path
-- [ ] 4.3 Show blocked dependencies
-- [ ] 4.4 Add tests for status formatting
-
-## 5. Integration
-
-- [ ] 5.1 Export new functions from `src/core/artifact-graph/index.ts`
-- [ ] 5.2 Ensure all tests pass
+# Tasks
+
+## Implementation Tasks
+
+- [x] Create `instruction-loader` spec in `openspec/specs/instruction-loader/spec.md`
+- [x] Implement `loadTemplate` function to load templates from schema directories
+- [x] Implement `loadChangeContext` function to combine graph and completion state
+- [x] Implement `generateInstructions` function to enrich templates with change context
+- [x] Implement `formatChangeStatus` function for readable status output
+- [x] Export new functions from `src/core/artifact-graph/index.ts`
+- [x] Add comprehensive tests in `test/core/artifact-graph/instruction-loader.test.ts`
+- [x] Verify build passes
+- [x] Verify all tests pass

src/core/artifact-graph/index.ts

@@ -26,3 +26,17 @@ export {
   getUserSchemasDir,
   SchemaLoadError,
 } from './resolver.js';
+
+// Instruction loading
+export {
+  loadTemplate,
+  loadChangeContext,
+  generateInstructions,
+  formatChangeStatus,
+  TemplateLoadError,
+  type ChangeContext,
+  type ArtifactInstructions,
+  type DependencyStatus,
+  type ArtifactStatus,
+  type ChangeStatus,
+} from './instruction-loader.js';