@fission-ai/openspec 0.20.0 → 0.22.0

package/dist/core/artifact-graph/instruction-loader.d.ts

@@ -21,6 +21,8 @@ export interface ChangeContext {
     changeName: string;
     /** Path to the change directory */
     changeDir: string;
+    /** Project root directory */
+    projectRoot: string;
 }
 /**
  * Enriched instructions for creating an artifact.
@@ -93,10 +95,11 @@ export interface ChangeStatus {
  *
  * @param schemaName - Schema name (e.g., "spec-driven")
  * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @param projectRoot - Optional project root for project-local schema resolution
  * @returns The template content
  * @throws TemplateLoadError if the template cannot be loaded
  */
-export declare function loadTemplate(schemaName: string, templatePath: string): string;
+export declare function loadTemplate(schemaName: string, templatePath: string, projectRoot?: string): string;
 /**
  * Loads change context combining graph and completion state.
  *
@@ -114,12 +117,18 @@ export declare function loadChangeContext(projectRoot: string, changeName: strin
 /**
  * Generates enriched instructions for creating an artifact.
  *
+ * Instruction injection order:
+ * 1. <context> - Project context from config (if present)
+ * 2. <rules> - Artifact-specific rules from config (if present)
+ * 3. <template> - Schema's template content
+ *
  * @param context - Change context
  * @param artifactId - Artifact ID to generate instructions for
+ * @param projectRoot - Project root directory (for reading config)
  * @returns Enriched artifact instructions
  * @throws Error if artifact not found
  */
-export declare function generateInstructions(context: ChangeContext, artifactId: string): ArtifactInstructions;
+export declare function generateInstructions(context: ChangeContext, artifactId: string, projectRoot?: string): ArtifactInstructions;
 /**
  * Formats the status of all artifacts in a change.
  *

package/dist/core/artifact-graph/instruction-loader.js

@@ -4,6 +4,9 @@ import { getSchemaDir, resolveSchema } from './resolver.js';
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
 import { resolveSchemaForChange } from '../../utils/change-metadata.js';
+import { readProjectConfig, validateConfigRules } from '../project-config.js';
+// Session-level cache for validation warnings (avoid repeating same warnings)
+const shownWarnings = new Set();
 /**
  * Error thrown when loading a template fails.
  */
@@ -20,11 +23,12 @@ export class TemplateLoadError extends Error {
  *
  * @param schemaName - Schema name (e.g., "spec-driven")
  * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @param projectRoot - Optional project root for project-local schema resolution
  * @returns The template content
  * @throws TemplateLoadError if the template cannot be loaded
  */
-export function loadTemplate(schemaName, templatePath) {
-    const schemaDir = getSchemaDir(schemaName);
+export function loadTemplate(schemaName, templatePath, projectRoot) {
+    const schemaDir = getSchemaDir(schemaName, projectRoot);
     if (!schemaDir) {
         throw new TemplateLoadError(`Schema '${schemaName}' not found`, templatePath);
     }
@@ -57,7 +61,7 @@ export function loadChangeContext(projectRoot, changeName, schemaName) {
     const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
     // Resolve schema: explicit > metadata > default
     const resolvedSchemaName = resolveSchemaForChange(changeDir, schemaName);
-    const schema = resolveSchema(resolvedSchemaName);
+    const schema = resolveSchema(resolvedSchemaName, projectRoot);
     const graph = ArtifactGraph.fromSchema(schema);
     const completed = detectCompleted(graph, changeDir);
     return {
@@ -66,24 +70,72 @@ export function loadChangeContext(projectRoot, changeName, schemaName) {
         schemaName: resolvedSchemaName,
         changeName,
         changeDir,
+        projectRoot,
     };
 }
 /**
  * Generates enriched instructions for creating an artifact.
  *
+ * Instruction injection order:
+ * 1. <context> - Project context from config (if present)
+ * 2. <rules> - Artifact-specific rules from config (if present)
+ * 3. <template> - Schema's template content
+ *
  * @param context - Change context
  * @param artifactId - Artifact ID to generate instructions for
+ * @param projectRoot - Project root directory (for reading config)
  * @returns Enriched artifact instructions
  * @throws Error if artifact not found
  */
-export function generateInstructions(context, artifactId) {
+export function generateInstructions(context, artifactId, projectRoot) {
     const artifact = context.graph.getArtifact(artifactId);
     if (!artifact) {
         throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
     }
-    const template = loadTemplate(context.schemaName, artifact.template);
+    const templateContent = loadTemplate(context.schemaName, artifact.template, context.projectRoot);
     const dependencies = getDependencyInfo(artifact, context.graph, context.completed);
     const unlocks = getUnlockedArtifacts(context.graph, artifactId);
+    // Build enriched template with project config injections
+    let enrichedTemplate = '';
+    let projectConfig = null;
+    // Use projectRoot from context if not explicitly provided
+    const effectiveProjectRoot = projectRoot ?? context.projectRoot;
+    // Try to read project config
+    if (effectiveProjectRoot) {
+        try {
+            projectConfig = readProjectConfig(effectiveProjectRoot);
+        }
+        catch {
+            // If config read fails, continue without config
+        }
+    }
+    // Validate rules artifact IDs if config has rules (only once per session)
+    if (projectConfig?.rules) {
+        const validArtifactIds = new Set(context.graph.getAllArtifacts().map((a) => a.id));
+        const warnings = validateConfigRules(projectConfig.rules, validArtifactIds, context.schemaName);
+        // Show each unique warning only once per session
+        for (const warning of warnings) {
+            if (!shownWarnings.has(warning)) {
+                console.warn(warning);
+                shownWarnings.add(warning);
+            }
+        }
+    }
+    // 1. Add context (all artifacts)
+    if (projectConfig?.context) {
+        enrichedTemplate += `<context>\n${projectConfig.context}\n</context>\n\n`;
+    }
+    // 2. Add rules (only for matching artifact)
+    const rulesForArtifact = projectConfig?.rules?.[artifactId];
+    if (rulesForArtifact && rulesForArtifact.length > 0) {
+        enrichedTemplate += `<rules>\n`;
+        for (const rule of rulesForArtifact) {
+            enrichedTemplate += `- ${rule}\n`;
+        }
+        enrichedTemplate += `</rules>\n\n`;
+    }
+    // 3. Add original template (without wrapper - CLI handles XML structure)
+    enrichedTemplate += templateContent;
     return {
         changeName: context.changeName,
         artifactId: artifact.id,
@@ -92,7 +144,7 @@ export function generateInstructions(context, artifactId) {
         outputPath: artifact.generates,
         description: artifact.description,
         instruction: artifact.instruction,
-        template,
+        template: enrichedTemplate,
         dependencies,
         unlocks,
     };
@@ -131,7 +183,7 @@ function getUnlockedArtifacts(graph, artifactId) {
  */
 export function formatChangeStatus(context) {
     // Load schema to get apply phase configuration
-    const schema = resolveSchema(context.schemaName);
+    const schema = resolveSchema(context.schemaName, context.projectRoot);
     const applyRequires = schema.apply?.requires ?? schema.artifacts.map(a => a.id);
     const artifacts = context.graph.getAllArtifacts();
     const ready = new Set(context.graph.getNextArtifacts(context.completed));

package/dist/core/artifact-graph/resolver.d.ts

@@ -16,34 +16,52 @@ export declare function getPackageSchemasDir(): string;
  * Gets the user's schema override directory path.
  */
 export declare function getUserSchemasDir(): string;
+/**
+ * Gets the project-local schemas directory path.
+ * @param projectRoot - The project root directory
+ * @returns The path to the project's schemas directory
+ */
+export declare function getProjectSchemasDir(projectRoot: string): string;
 /**
  * Resolves a schema name to its directory path.
  *
- * Resolution order:
- * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
- * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/openspec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
  *
  * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  * @returns The path to the schema directory, or null if not found
  */
-export declare function getSchemaDir(name: string): string | null;
+export declare function getSchemaDir(name: string, projectRoot?: string): string | null;
 /**
  * Resolves a schema name to a SchemaYaml object.
  *
- * Resolution order:
- * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
- * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/openspec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
  *
  * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  * @returns The resolved schema object
  * @throws Error if schema is not found in any location
  */
-export declare function resolveSchema(name: string): SchemaYaml;
+export declare function resolveSchema(name: string, projectRoot?: string): SchemaYaml;
 /**
  * Lists all available schema names.
- * Combines user override and package built-in schemas.
+ * Combines project-local, user override, and package built-in schemas.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  */
-export declare function listSchemas(): string[];
+export declare function listSchemas(projectRoot?: string): string[];
 /**
  * Schema info with metadata (name, description, artifacts).
  */
@@ -51,11 +69,13 @@ export interface SchemaInfo {
     name: string;
     description: string;
     artifacts: string[];
-    source: 'package' | 'user';
+    source: 'project' | 'user' | 'package';
 }
 /**
  * Lists all available schemas with their descriptions and artifact lists.
  * Useful for agent skills to present schema selection to users.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  */
-export declare function listSchemasWithInfo(): SchemaInfo[];
+export declare function listSchemasWithInfo(projectRoot?: string): SchemaInfo[];
 //# sourceMappingURL=resolver.d.ts.map

package/dist/core/artifact-graph/resolver.js

@@ -31,24 +31,45 @@ export function getPackageSchemasDir() {
 export function getUserSchemasDir() {
     return path.join(getGlobalDataDir(), 'schemas');
 }
+/**
+ * Gets the project-local schemas directory path.
+ * @param projectRoot - The project root directory
+ * @returns The path to the project's schemas directory
+ */
+export function getProjectSchemasDir(projectRoot) {
+    return path.join(projectRoot, 'openspec', 'schemas');
+}
 /**
  * Resolves a schema name to its directory path.
  *
- * Resolution order:
- * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
- * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/openspec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
  *
  * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  * @returns The path to the schema directory, or null if not found
  */
-export function getSchemaDir(name) {
-    // 1. Check user override directory
+export function getSchemaDir(name, projectRoot) {
+    // 1. Check project-local directory (if projectRoot provided)
+    if (projectRoot) {
+        const projectDir = path.join(getProjectSchemasDir(projectRoot), name);
+        const projectSchemaPath = path.join(projectDir, 'schema.yaml');
+        if (fs.existsSync(projectSchemaPath)) {
+            return projectDir;
+        }
+    }
+    // 2. Check user override directory
     const userDir = path.join(getUserSchemasDir(), name);
     const userSchemaPath = path.join(userDir, 'schema.yaml');
     if (fs.existsSync(userSchemaPath)) {
         return userDir;
     }
-    // 2. Check package built-in directory
+    // 3. Check package built-in directory
     const packageDir = path.join(getPackageSchemasDir(), name);
     const packageSchemaPath = path.join(packageDir, 'schema.yaml');
     if (fs.existsSync(packageSchemaPath)) {
@@ -59,20 +80,25 @@ export function getSchemaDir(name) {
 /**
  * Resolves a schema name to a SchemaYaml object.
  *
- * Resolution order:
- * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
- * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ * Resolution order (when projectRoot is provided):
+ * 1. Project-local: <projectRoot>/openspec/schemas/<name>/schema.yaml
+ * 2. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 3. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * When projectRoot is not provided, only user override and package built-in are checked
+ * (backward compatible behavior).
  *
  * @param name - Schema name (e.g., "spec-driven")
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  * @returns The resolved schema object
  * @throws Error if schema is not found in any location
  */
-export function resolveSchema(name) {
+export function resolveSchema(name, projectRoot) {
     // Normalize name (remove .yaml extension if provided)
     const normalizedName = name.replace(/\.ya?ml$/, '');
-    const schemaDir = getSchemaDir(normalizedName);
+    const schemaDir = getSchemaDir(normalizedName, projectRoot);
     if (!schemaDir) {
-        const availableSchemas = listSchemas();
+        const availableSchemas = listSchemas(projectRoot);
         throw new Error(`Schema '${normalizedName}' not found. Available schemas: ${availableSchemas.join(', ')}`);
     }
     const schemaPath = path.join(schemaDir, 'schema.yaml');
@@ -98,9 +124,11 @@ export function resolveSchema(name) {
 }
 /**
  * Lists all available schema names.
- * Combines user override and package built-in schemas.
+ * Combines project-local, user override, and package built-in schemas.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  */
-export function listSchemas() {
+export function listSchemas(projectRoot) {
     const schemas = new Set();
     // Add package built-in schemas
     const packageDir = getPackageSchemasDir();
@@ -126,20 +154,62 @@ export function listSchemas() {
             }
         }
     }
+    // Add project-local schemas (if projectRoot provided)
+    if (projectRoot) {
+        const projectDir = getProjectSchemasDir(projectRoot);
+        if (fs.existsSync(projectDir)) {
+            for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
+                    if (fs.existsSync(schemaPath)) {
+                        schemas.add(entry.name);
+                    }
+                }
+            }
+        }
+    }
     return Array.from(schemas).sort();
 }
 /**
  * Lists all available schemas with their descriptions and artifact lists.
  * Useful for agent skills to present schema selection to users.
+ *
+ * @param projectRoot - Optional project root directory for project-local schema resolution
  */
-export function listSchemasWithInfo() {
+export function listSchemasWithInfo(projectRoot) {
     const schemas = [];
     const seenNames = new Set();
-    // Add user override schemas first (they take precedence)
+    // Add project-local schemas first (highest priority, if projectRoot provided)
+    if (projectRoot) {
+        const projectDir = getProjectSchemasDir(projectRoot);
+        if (fs.existsSync(projectDir)) {
+            for (const entry of fs.readdirSync(projectDir, { withFileTypes: true })) {
+                if (entry.isDirectory()) {
+                    const schemaPath = path.join(projectDir, entry.name, 'schema.yaml');
+                    if (fs.existsSync(schemaPath)) {
+                        try {
+                            const schema = parseSchema(fs.readFileSync(schemaPath, 'utf-8'));
+                            schemas.push({
+                                name: entry.name,
+                                description: schema.description || '',
+                                artifacts: schema.artifacts.map((a) => a.id),
+                                source: 'project',
+                            });
+                            seenNames.add(entry.name);
+                        }
+                        catch {
+                            // Skip invalid schemas
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Add user override schemas (if not overridden by project)
     const userDir = getUserSchemasDir();
     if (fs.existsSync(userDir)) {
         for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
-            if (entry.isDirectory()) {
+            if (entry.isDirectory() && !seenNames.has(entry.name)) {
                 const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
                 if (fs.existsSync(schemaPath)) {
                     try {
@@ -159,7 +229,7 @@ export function listSchemasWithInfo() {
             }
         }
     }
-    // Add package built-in schemas (if not overridden)
+    // Add package built-in schemas (if not overridden by project or user)
     const packageDir = getPackageSchemasDir();
     if (fs.existsSync(packageDir)) {
         for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {

package/dist/core/completions/command-registry.js

@@ -152,6 +152,18 @@ export const COMMAND_REGISTRY = [
             },
         ],
     },
+    {
+        name: 'feedback',
+        description: 'Submit feedback about OpenSpec',
+        acceptsPositional: true,
+        flags: [
+            {
+                name: 'body',
+                description: 'Detailed description for the feedback',
+                takesValue: true,
+            },
+        ],
+    },
     {
         name: 'change',
         description: 'Manage OpenSpec change proposals (deprecated)',
@@ -364,5 +376,81 @@ export const COMMAND_REGISTRY = [
             },
         ],
     },
+    {
+        name: 'schema',
+        description: 'Manage workflow schemas',
+        flags: [],
+        subcommands: [
+            {
+                name: 'which',
+                description: 'Show where a schema resolves from',
+                acceptsPositional: true,
+                positionalType: 'schema-name',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'all',
+                        description: 'List all schemas with their resolution sources',
+                    },
+                ],
+            },
+            {
+                name: 'validate',
+                description: 'Validate a schema structure and templates',
+                acceptsPositional: true,
+                positionalType: 'schema-name',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'verbose',
+                        description: 'Show detailed validation steps',
+                    },
+                ],
+            },
+            {
+                name: 'fork',
+                description: 'Copy an existing schema to project for customization',
+                acceptsPositional: true,
+                positionalType: 'schema-name',
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'force',
+                        description: 'Overwrite existing destination',
+                    },
+                ],
+            },
+            {
+                name: 'init',
+                description: 'Create a new project-local schema',
+                acceptsPositional: true,
+                flags: [
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'description',
+                        description: 'Schema description',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'artifacts',
+                        description: 'Comma-separated artifact IDs',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'default',
+                        description: 'Set as project default schema',
+                    },
+                    {
+                        name: 'no-default',
+                        description: 'Do not prompt to set as default',
+                    },
+                    {
+                        name: 'force',
+                        description: 'Overwrite existing schema',
+                    },
+                ],
+            },
+        ],
+    },
 ];
 //# sourceMappingURL=command-registry.js.map

package/dist/core/completions/types.d.ts

@@ -55,9 +55,10 @@ export interface CommandDefinition {
      * - 'change-or-spec-id': Complete with both changes and specs
      * - 'path': Complete with file paths
      * - 'shell': Complete with supported shell names
+     * - 'schema-name': Complete with available schema names
      * - undefined: No specific completion
      */
-    positionalType?: 'change-id' | 'spec-id' | 'change-or-spec-id' | 'path' | 'shell';
+    positionalType?: 'change-id' | 'spec-id' | 'change-or-spec-id' | 'path' | 'shell' | 'schema-name';
 }
 /**
  * Interface for shell-specific completion script generators

package/dist/core/config-prompts.d.ts

@@ -0,0 +1,36 @@
+import type { ProjectConfig } from './project-config.js';
+/**
+ * Check if an error is an ExitPromptError (user cancelled with Ctrl+C).
+ * Used instead of instanceof check since @inquirer modules use dynamic imports.
+ */
+export declare function isExitPromptError(error: unknown): boolean;
+/**
+ * Result of interactive config creation prompts.
+ */
+export interface ConfigPromptResult {
+    /** Whether to create config file */
+    createConfig: boolean;
+    /** Selected schema name */
+    schema?: string;
+    /** Project context (optional) */
+    context?: string;
+    /** Per-artifact rules (optional) */
+    rules?: Record<string, string[]>;
+}
+/**
+ * Prompt user to create project config interactively.
+ * Used by experimental setup command.
+ *
+ * @param projectRoot - Optional project root for project-local schema resolution
+ * @returns Config prompt result
+ * @throws ExitPromptError if user cancels (Ctrl+C)
+ */
+export declare function promptForConfig(projectRoot?: string): Promise<ConfigPromptResult>;
+/**
+ * Serialize config to YAML string with proper multi-line formatting.
+ *
+ * @param config - Partial config object (schema required, context/rules optional)
+ * @returns YAML string ready to write to file
+ */
+export declare function serializeConfig(config: Partial<ProjectConfig>): string;
+//# sourceMappingURL=config-prompts.d.ts.map