feat: add instructionFile support for external instruction file references

src/commands/workflow/instructions.ts

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import {
   loadChangeContext,
   generateInstructions,
+  loadInstruction,
   resolveSchema,
   resolveArtifactOutputs,
   type ArtifactInstructions,
@@ -260,7 +261,9 @@ export async function generateApplyInstructions(
   // Fallback: if no apply block, require all artifacts
   const requiredArtifactIds = applyConfig?.requires ?? schema.artifacts.map((a) => a.id);
   const tracksFile = applyConfig?.tracks ?? null;
-  const schemaInstruction = applyConfig?.instruction ?? null;
+  const schemaInstruction = applyConfig?.instructionFile
+    ? loadInstruction(context.schemaName, applyConfig.instructionFile, projectRoot)?.trim()
+    : applyConfig?.instruction?.trim() ?? null;
 
   // Check which required artifacts are missing
   const missingArtifacts: string[] = [];
@@ -320,7 +323,7 @@ export async function generateApplyInstructions(
   } else if (!tracksFile) {
     // No tracking file configured in schema - ready to apply
     state = 'ready';
-    instruction = schemaInstruction?.trim() ?? 'All required artifacts complete. Proceed with implementation.';
+    instruction = schemaInstruction ?? 'All required artifacts complete. Proceed with implementation.';
   } else {
     state = 'ready';
     instruction = schemaInstruction?.trim() ?? 'Read context files, work through pending tasks, mark complete as you go.\nPause if you hit blockers or need clarification.';

src/commands/workflow/templates.ts

@@ -26,6 +26,7 @@ export interface TemplatesOptions {
 export interface TemplateInfo {
   artifactId: string;
   templatePath: string;
+  instructionFilePath: string | null;
   source: 'project' | 'user' | 'package';
 }
 
@@ -67,20 +68,35 @@ export async function templatesCommand(options: TemplatesOptions): Promise<void>
       source = 'package';
     }
 
-    const templates: TemplateInfo[] = graph.getAllArtifacts().map((artifact) => ({
-      artifactId: artifact.id,
-      templatePath: FileSystemUtils.canonicalizeExistingPath(
-        path.join(schemaDir, 'templates', artifact.template)
-      ),
-      source,
-    }));
+    const templates: TemplateInfo[] = graph.getAllArtifacts().map((artifact) => {
+      const instructionFilePath = artifact.instructionFile
+        ? FileSystemUtils.canonicalizeExistingPath(
+            path.join(schemaDir, 'instructions', artifact.instructionFile)
+          )
+        : null;
+
+      return {
+        artifactId: artifact.id,
+        templatePath: FileSystemUtils.canonicalizeExistingPath(
+          path.join(schemaDir, 'templates', artifact.template)
+        ),
+        instructionFilePath,
+        source,
+      };
+    });
 
     spinner?.stop();
 
     if (options.json) {
-      const output: Record<string, { path: string; source: string }> = {};
+      const output: Record<string, { template: { path: string; source: string }; instructionFile?: { path: string } }> = {};
       for (const t of templates) {
-        output[t.artifactId] = { path: t.templatePath, source: t.source };
+        const entry: { template: { path: string; source: string }; instructionFile?: { path: string } } = {
+          template: { path: t.templatePath, source: t.source },
+        };
+        if (t.instructionFilePath) {
+          entry.instructionFile = { path: t.instructionFilePath };
+        }
+        output[t.artifactId] = entry;
       }
       console.log(JSON.stringify(output, null, 2));
       return;
@@ -92,7 +108,10 @@ export async function templatesCommand(options: TemplatesOptions): Promise<void>
 
     for (const t of templates) {
       console.log(`${t.artifactId}:`);
-      console.log(`  ${t.templatePath}`);
+      console.log(`  template:    ${t.templatePath}`);
+      if (t.instructionFilePath) {
+        console.log(`  instruction: ${t.instructionFilePath}`);
+      }
     }
   } catch (error) {
     spinner?.stop();

src/core/artifact-graph/index.ts

@@ -33,10 +33,12 @@ export {
 // Instruction loading
 export {
   loadTemplate,
+  loadInstruction,
   loadChangeContext,
   generateInstructions,
   formatChangeStatus,
   TemplateLoadError,
+  InstructionLoadError,
   type ChangeContext,
   type ArtifactInstructions,
   type DependencyInfo,

src/core/artifact-graph/instruction-loader.ts

@@ -24,6 +24,19 @@ export class TemplateLoadError extends Error {
   }
 }
 
+/**
+ * Error thrown when loading an instruction file fails.
+ */
+export class InstructionLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly instructionPath: string
+  ) {
+    super(message);
+    this.name = 'InstructionLoadError';
+  }
+}
+
 /**
  * Change context containing graph, completion state, and metadata.
  */
@@ -160,6 +173,53 @@ export function loadTemplate(
   }
 }
 
+/**
+ * Loads an instruction file from a schema's instructions directory.
+ *
+ * Mirrors loadTemplate() — resolves the file relative to
+ * <schemaDir>/instructions/<instructionPath>.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param instructionPath - Relative path within the instructions directory (e.g., "requirements.md")
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns The instruction content
+ * @throws InstructionLoadError if the instruction file cannot be loaded
+ */
+export function loadInstruction(
+  schemaName: string,
+  instructionPath: string,
+  projectRoot?: string
+): string {
+  const schemaDir = getSchemaDir(schemaName, projectRoot);
+  if (!schemaDir) {
+    throw new InstructionLoadError(
+      `Schema '${schemaName}' not found`,
+      instructionPath
+    );
+  }
+
+  const instructionPathOnDisk = path.join(schemaDir, 'instructions', instructionPath);
+
+  if (!fs.existsSync(instructionPathOnDisk)) {
+    throw new InstructionLoadError(
+      `Instruction file not found: ${instructionPathOnDisk}`,
+      instructionPathOnDisk
+    );
+  }
+
+  const fullPath = FileSystemUtils.canonicalizeExistingPath(instructionPathOnDisk);
+
+  try {
+    return fs.readFileSync(fullPath, 'utf-8');
+  } catch (err) {
+    const ioError = err instanceof Error ? err : new Error(String(err));
+    throw new InstructionLoadError(
+      `Failed to read instruction file: ${ioError.message}`,
+      fullPath
+    );
+  }
+}
+
 /**
  * Loads change context combining graph and completion state.
  *
@@ -224,6 +284,12 @@ export function generateInstructions(
   }
 
   const templateContent = loadTemplate(context.schemaName, artifact.template, context.projectRoot);
+
+  // Resolve instruction: external file (instructionFile) takes priority over inline (instruction)
+  const instructionContent = artifact.instructionFile
+    ? loadInstruction(context.schemaName, artifact.instructionFile, context.projectRoot)
+    : artifact.instruction;
+
   const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
   const unlocks = getUnlockedArtifacts(context.graph, artifactId);
 
@@ -270,7 +336,7 @@ export function generateInstructions(
     changeDir: context.changeDir,
     outputPath: artifact.generates,
     description: artifact.description,
-    instruction: artifact.instruction,
+    instruction: instructionContent,
     context: configContext,
     rules: configRules,
     template: templateContent,

src/core/artifact-graph/schema.ts

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import { parse as parseYaml } from 'yaml';
-import { SchemaYamlSchema, type SchemaYaml, type Artifact } from './types.js';
+import { SchemaYamlSchema, type SchemaYaml, type Artifact, type ApplyPhase } from './types.js';
 
 export class SchemaValidationError extends Error {
   constructor(message: string) {
@@ -41,6 +41,9 @@ export function parseSchema(yamlContent: string): SchemaYaml {
   // Check for cycles
   validateNoCycles(schema.artifacts);
 
+  // Check instruction / instructionFile mutual exclusivity
+  validateInstructionExclusivity(schema.artifacts, schema.apply);
+
   return schema;
 }
 
@@ -74,6 +77,25 @@ function validateRequiresReferences(artifacts: Artifact[]): void {
   }
 }
 
+/**
+ * Validates that instruction and instructionFile are mutually exclusive.
+ * An artifact (or apply phase) cannot have both fields at the same time.
+ */
+function validateInstructionExclusivity(artifacts: Artifact[], apply?: ApplyPhase): void {
+  for (const artifact of artifacts) {
+    if (artifact.instruction && artifact.instructionFile) {
+      throw new SchemaValidationError(
+        `Artifact '${artifact.id}' cannot have both 'instruction' and 'instructionFile'`
+      );
+    }
+  }
+  if (apply?.instruction && apply?.instructionFile) {
+    throw new SchemaValidationError(
+      `Apply phase cannot have both 'instruction' and 'instructionFile'`
+    );
+  }
+}
+
 /**
  * Validates that there are no cyclic dependencies.
  * Uses DFS to detect cycles and reports the full cycle path.

src/core/artifact-graph/types.ts

@@ -7,6 +7,9 @@ export const ArtifactSchema = z.object({
   description: z.string(),
   template: z.string().min(1, { error: 'template field is required' }),
   instruction: z.string().optional(),
+  // External instruction file (relative to schema's instructions/ directory).
+  // Mutually exclusive with instruction — validated in parseSchema().
+  instructionFile: z.string().optional(),
   requires: z.array(z.string()).default([]),
 });
 
@@ -18,6 +21,9 @@ export const ApplyPhaseSchema = z.object({
   tracks: z.string().nullable().optional(),
   // Custom guidance for the apply phase
   instruction: z.string().optional(),
+  // External instruction file for apply phase (relative to schema's instructions/ directory).
+  // Mutually exclusive with instruction — validated in parseSchema().
+  instructionFile: z.string().optional(),
 });
 
 // Full schema YAML structure

test/commands/artifact-workflow.test.ts

@@ -318,8 +318,10 @@ describe('artifact-workflow CLI commands', () => {
 
       const json = JSON.parse(result.stdout);
       expect(json.proposal).toBeDefined();
-      expect(json.proposal.path).toContain('proposal.md');
-      expect(json.proposal.source).toBe('package');
+      expect(json.proposal.template.path).toContain('proposal.md');
+      expect(json.proposal.template.source).toBe('package');
+      // spec-driven schema uses inline instruction, so no instructionFile
+      expect(json.proposal.instructionFile).toBeUndefined();
     });
 
     it('errors for unknown schema', async () => {