Function createChange

src/utils/change-utils.ts:121–190

(
  projectRoot: string,
  name: string,
  options: CreateChangeOptions = {}
)

 * console.log(result.schema) // 'my-workflow'
 */
export async function createChange(
  projectRoot: string,
  name: string,
  options: CreateChangeOptions = {}
): Promise<CreateChangeResult> {
  // Validate the name first
  const validation = validateChangeName(name);
  if (!validation.valid) {
    throw new Error(validation.error);
  }

  const defaultSchema = options.defaultSchema ?? DEFAULT_SCHEMA;

  // Determine schema: explicit option → project config → supplied default
  let schemaName: string;
  if (options.schema) {
    schemaName = options.schema;
  } else {
    // Try to read from project config
    try {
      const config = readProjectConfig(projectRoot);
      schemaName = config?.schema ?? defaultSchema;
    } catch {
      // If config read fails, use default
      schemaName = defaultSchema;
    }
  }

  // Validate the resolved schema
  validateSchemaName(schemaName, projectRoot);

  // Build the change directory path
  const changeDir = path.join(options.changesDir ?? path.join(projectRoot, 'openspec', 'changes'), name);

  // Check if change already exists
  if (await FileSystemUtils.directoryExists(changeDir)) {
    throw new Error(`Change '${name}' already exists at ${changeDir}`);
  }

  // Creating a change may scaffold or complete the root itself (an
  // implicit root, or a config-only/incomplete clone). Never leave a
  // half-root behind that doctor immediately calls unhealthy: ensure
  // specs/ and changes/archive/ exist, and write a config only when
  // none exists. The config records the PROJECT default schema, never
  // a one-change --schema override.
  const openspecDir = path.join(projectRoot, 'openspec');

  // Create the directory (including parent directories if needed)
  await FileSystemUtils.createDirectory(changeDir);
  await FileSystemUtils.createDirectory(path.join(openspecDir, 'specs'));
  await FileSystemUtils.createDirectory(path.join(openspecDir, 'changes', 'archive'));
  const configPath = path.join(openspecDir, 'config.yaml');
  const configYmlPath = path.join(openspecDir, 'config.yml');
  if (
    !(await FileSystemUtils.fileExists(configPath)) &&
    !(await FileSystemUtils.fileExists(configYmlPath))
  ) {
    await FileSystemUtils.writeFile(configPath, `schema: ${defaultSchema}\n`);