Skip to content

feat: add instruction loader for template loading and change context #414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 3 commits into from
Dec 28, 2025
Merged

feat: add instruction loader for template loading and change context #414

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bb97257
feat: add instruction loader for template loading and change context
TabishB Dec 28, 2025
7f2fd97
chore: archive add-instruction-loader change
TabishB Dec 28, 2025
8150846
docs: add purpose description to instruction-loader spec
TabishB Dec 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 0 additions & 34 deletions openspec/changes/add-instruction-loader/tasks.md
View file
Open in desktop

This file was deleted.

0 .../changes/add-instruction-loader/design.md → ...25-12-28-add-instruction-loader/design.md
View file
Open in desktop
File renamed without changes.
0 ...hanges/add-instruction-loader/proposal.md → ...-12-28-add-instruction-loader/proposal.md
View file
Open in desktop
File renamed without changes.
70 changes: 70 additions & 0 deletions ...nges/archive/2025-12-28-add-instruction-loader/specs/instruction-loader/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# instruction-loader Specification

## Purpose
Load templates from schema directories and enrich them with change-specific context for guiding artifact creation.

## ADDED Requirements

### Requirement: Template Loading
The system SHALL load templates from schema directories.

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

### Requirement: Change Context Loading
The system SHALL load change context combining graph and completion state.

#### Scenario: Load context for existing change
- **WHEN** `loadChangeContext(projectRoot, changeName)` is called for an existing change
- **THEN** the system returns a context with graph, completed set, schema name, and change info

#### Scenario: Load context with custom schema
- **WHEN** `loadChangeContext(projectRoot, changeName, schemaName)` is called
- **THEN** the system uses the specified schema instead of default

#### 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: Template Enrichment
The system SHALL enrich templates with change-specific context.

#### 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: Include dependency status
- **WHEN** an artifact has dependencies
- **THEN** the output shows each dependency with completion status (done/missing)

#### Scenario: Include unlocked artifacts
- **WHEN** instructions are generated
- **THEN** the output includes which artifacts become available after this one

#### 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: All artifacts completed
- **WHEN** all artifacts are completed
- **THEN** status shows all artifacts as "done"

#### Scenario: Mixed completion status
- **WHEN** some artifacts are completed
- **THEN** status shows completed as "done", ready as "ready", blocked as "blocked"

#### Scenario: Blocked artifact details
- **WHEN** an artifact is blocked
- **THEN** status shows which dependencies are missing

#### Scenario: Include output paths
- **WHEN** status is formatted
- **THEN** each artifact shows its output path pattern
13 changes: 13 additions & 0 deletions openspec/changes/archive/2025-12-28-add-instruction-loader/tasks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# 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
30 changes: 17 additions & 13 deletions ...n-loader/specs/instruction-loader/spec.md → openspec/specs/instruction-loader/spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
## ADDED Requirements
# instruction-loader Specification

## Purpose
TBD - created by archiving change add-instruction-loader. Update Purpose after archive.
## Requirements
Copy link
Contributor

@coderabbitai coderabbitai bot Dec 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use ## ADDED Requirements header per coding guidelines.

The spec delta file should use ## ADDED Requirements instead of ## Requirements. Since this introduces new orthogonal capabilities (template loading, context loading, instruction generation, status formatting) that can stand alone, the ADDED header is appropriate.

As per coding guidelines, spec delta files must use ## ADDED|MODIFIED|REMOVED|RENAMED Requirements headers.

🔎 Proposed fix 
-## Requirements
+## ADDED Requirements
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Requirements
## ADDED Requirements
🤖 Prompt for AI Agents 
In openspec/changes/add-instruction-loader/specs/instruction-loader/spec.md
around line 6, the header currently reads "## Requirements" but per spec-delta
guidelines it must be one of the delta types; update the header to "## ADDED
Requirements" (exact casing and spacing) so the file uses the required spec
delta header for newly introduced capabilities.

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

Expand All @@ -22,44 +25,45 @@ 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

14 changes: 14 additions & 0 deletions src/core/artifact-graph/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Loading
Loading