@fission-ai/openspec 1.3.0 → 1.4.0

package/dist/utils/change-metadata.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'yaml';
-import { ChangeMetadataSchema } from '../core/artifact-graph/types.js';
+import { ChangeMetadataSchema } from '../core/change-metadata/index.js';
 import { listSchemas } from '../core/artifact-graph/resolver.js';
 import { readProjectConfig } from '../core/project-config.js';
 const METADATA_FILENAME = '.openspec.yaml';
@@ -114,24 +114,18 @@ export function readChangeMetadata(changeDir, projectRoot) {
  * @param explicitSchema - Optional explicit schema override
  * @returns The resolved schema name
  */
-export function resolveSchemaForChange(changeDir, explicitSchema) {
+export function resolveSchemaForChange(changeDir, explicitSchema, projectRootOverride, options = {}) {
     // Derive project root from changeDir (changeDir is typically projectRoot/openspec/changes/change-name)
-    const projectRoot = path.resolve(changeDir, '../../..');
+    const projectRoot = projectRootOverride ?? path.resolve(changeDir, '../../..');
     // 1. Explicit override wins
     if (explicitSchema) {
         return explicitSchema;
     }
-    // 2. Try reading from metadata
-    try {
-        const metadata = readChangeMetadata(changeDir, projectRoot);
-        if (metadata?.schema) {
-            return metadata.schema;
-        }
-    }
-    catch {
-        // If metadata read fails, continue to next option
+    const metadata = options.metadata !== undefined ? options.metadata : readChangeMetadata(changeDir, projectRoot);
+    if (metadata?.schema) {
+        return metadata.schema;
     }
-    // 3. Try reading from project config
+    // 3. Try reading from project config when metadata is absent.
     try {
         const config = readProjectConfig(projectRoot);
         if (config?.schema) {

package/dist/utils/change-utils.d.ts

@@ -1,9 +1,16 @@
+import type { ChangeMetadata } from '../core/change-metadata/index.js';
 /**
  * Options for creating a change.
  */
 export interface CreateChangeOptions {
     /** The workflow schema to use (default: 'spec-driven') */
     schema?: string;
+    /** Default schema to use when no explicit schema or project config is present */
+    defaultSchema?: string;
+    /** Directory that should contain the change directories */
+    changesDir?: string;
+    /** Additional metadata to persist in the change's .openspec.yaml */
+    metadata?: Partial<Pick<ChangeMetadata, 'goal' | 'affected_areas' | 'initiative'>>;
 }
 /**
  * Result of creating a change.
@@ -11,6 +18,8 @@ export interface CreateChangeOptions {
 export interface CreateChangeResult {
     /** The schema that was actually used (resolved from options, config, or default) */
     schema: string;
+    /** Absolute path to the created change directory */
+    changeDir: string;
 }
 /**
  * Result of validating a change name.

package/dist/utils/change-utils.js

@@ -84,7 +84,8 @@ export async function createChange(projectRoot, name, options = {}) {
     if (!validation.valid) {
         throw new Error(validation.error);
     }
-    // Determine schema: explicit option → project config → hardcoded default
+    const defaultSchema = options.defaultSchema ?? DEFAULT_SCHEMA;
+    // Determine schema: explicit option → project config → supplied default
     let schemaName;
     if (options.schema) {
         schemaName = options.schema;
@@ -93,17 +94,17 @@ export async function createChange(projectRoot, name, options = {}) {
         // Try to read from project config
         try {
             const config = readProjectConfig(projectRoot);
-            schemaName = config?.schema ?? DEFAULT_SCHEMA;
+            schemaName = config?.schema ?? defaultSchema;
         }
         catch {
             // If config read fails, use default
-            schemaName = DEFAULT_SCHEMA;
+            schemaName = defaultSchema;
         }
     }
     // Validate the resolved schema
     validateSchemaName(schemaName, projectRoot);
     // Build the change directory path
-    const changeDir = path.join(projectRoot, 'openspec', 'changes', name);
+    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}`);
@@ -115,7 +116,8 @@ export async function createChange(projectRoot, name, options = {}) {
     writeChangeMetadata(changeDir, {
         schema: schemaName,
         created: today,
+        ...options.metadata,
     }, projectRoot);
-    return { schema: schemaName };
+    return { schema: schemaName, changeDir };
 }
 //# sourceMappingURL=change-utils.js.map

package/dist/utils/file-system.d.ts

@@ -4,6 +4,11 @@ export declare class FileSystemUtils {
      * Essential for cross-platform compatibility with glob libraries like fast-glob.
      */
     static toPosixPath(p: string): string;
+    /**
+     * Returns a canonical absolute path when the target exists.
+     * Falls back to path.resolve() so callers can still produce a stable absolute path.
+     */
+    static canonicalizeExistingPath(targetPath: string): string;
     private static isWindowsBasePath;
     private static normalizeSegments;
     static joinPath(basePath: string, ...segments: string[]): string;

package/dist/utils/file-system.js

@@ -1,5 +1,7 @@
-import { promises as fs, constants as fsConstants } from 'fs';
+import * as nodeFs from 'fs';
 import path from 'path';
+const fs = nodeFs.promises;
+const { constants: fsConstants } = nodeFs;
 function isMarkerOnOwnLine(content, markerIndex, markerLength) {
     let leftIndex = markerIndex - 1;
     while (leftIndex >= 0 && content[leftIndex] !== '\n') {
@@ -37,6 +39,24 @@ export class FileSystemUtils {
     static toPosixPath(p) {
         return p.replace(/\\/g, '/');
     }
+    /**
+     * Returns a canonical absolute path when the target exists.
+     * Falls back to path.resolve() so callers can still produce a stable absolute path.
+     */
+    static canonicalizeExistingPath(targetPath) {
+        try {
+            // Prefer the native resolver so Windows short-path aliases are expanded.
+            return nodeFs.realpathSync.native(targetPath);
+        }
+        catch {
+            try {
+                return nodeFs.realpathSync(targetPath);
+            }
+            catch {
+                return path.resolve(targetPath);
+            }
+        }
+    }
     static isWindowsBasePath(basePath) {
         return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -56,6 +56,7 @@
     "@inquirer/prompts": "^7.8.0",
     "chalk": "^5.5.0",
     "commander": "^14.0.0",
+    "cross-spawn": "7.0.6",
     "fast-glob": "^3.3.3",
     "ora": "^8.2.0",
     "posthog-node": "^5.20.0",

package/schemas/workspace-planning/schema.yaml

@@ -0,0 +1,72 @@
+name: workspace-planning
+version: 1
+description: Workspace planning workflow for cross-area changes
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Shared workspace proposal with the product goal, scope, affected areas, and impact
+    template: proposal.md
+    instruction: |
+      Create the workspace-level proposal that captures the shared product goal once.
+
+      Sections:
+      - **Why**: Explain the product goal or problem in 1-2 concise paragraphs.
+      - **What Changes**: List the cross-area behavior, workflow, or capability changes.
+      - **Affected Areas**: Name known affected areas using registered workspace link names where applicable. If scope is still being explored, say what remains unresolved.
+      - **Capabilities**: Identify workspace-scoped capabilities that need specs. Area-specific requirements should later live under `specs/<area-or-repo>/<capability>/spec.md`.
+      - **Impact**: Summarize user-facing impact, planning impact, and likely implementation homes without creating repo-local artifacts.
+
+      Keep linked repos and folders as exploration context until an explicit implementation workflow selects an affected area.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Workspace-scoped specs organized by affected area and capability
+    template: spec.md
+    instruction: |
+      Create workspace-scoped specification files that define WHAT should change.
+
+      Use `specs/<area-or-repo>/<capability>/spec.md` for area-specific requirements. The first path segment should be a registered workspace link name when a registered area owns the requirement. If the area is unresolved, use an exploratory area name and make the unresolved question explicit in the requirement or scenario.
+
+      These specs are planning artifacts under the workspace change root. Do not create repo-local spec files in linked repos during workspace planning.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New workspace-scoped behavior.
+      - **MODIFIED Requirements**: Changed behavior; include the full updated requirement.
+      - **REMOVED Requirements**: Deprecated behavior with Reason and Migration.
+      - **RENAMED Requirements**: Name changes only; use FROM:/TO: format.
+
+      Each requirement must use SHALL/MUST language and include at least one `#### Scenario:` block.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Cross-area technical design and coordination decisions
+    template: design.md
+    instruction: |
+      Create the cross-area design document for workspace planning.
+
+      Focus on decisions that affect multiple areas, handoffs between areas, shared constraints, sequencing risks, and how the workspace plan should stay the source of truth. Avoid line-by-line implementation details and do not instruct agents to edit linked repos until an explicit implementation workflow provides an allowed edit root.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Coordination checklist for workspace planning and later affected-area implementation
+    template: tasks.md
+    instruction: |
+      Create the workspace coordination task list.
+
+      Group tasks by phase or affected area as useful. Each actionable item must be a checkbox using `- [ ]`. When implementation tasks are area-specific, name the affected area and keep the task at planning granularity until a later implementation workflow selects an allowed edit root.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read the workspace planning context from status and instructions output before applying.
+    Select an affected area and confirm an allowed edit root before making implementation edits.
+    Until an explicit implementation context is available, treat linked repos and folders as read-only exploration context.

package/schemas/workspace-planning/templates/design.md

@@ -0,0 +1,33 @@
+## Context
+
+Summarize the workspace planning context, relevant linked areas, and constraints.
+
+## Goals / Non-Goals
+
+**Goals:**
+-
+
+**Non-Goals:**
+- Creating repo-local implementation artifacts before an affected area is selected.
+
+## Decisions
+
+### Decision: <title>
+
+<decision and rationale>
+
+Alternative considered: <alternative and why it was not chosen>
+
+## Risks / Trade-offs
+
+- <risk> -> <mitigation>
+
+## Coordination Notes
+
+- Affected areas:
+- Open handoffs:
+- Implementation entry criteria:
+
+## Open Questions
+
+-

package/schemas/workspace-planning/templates/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+Describe the shared product goal, problem, or opportunity that makes this workspace-level change worth planning.
+
+## What Changes
+
+-
+
+## Affected Areas
+
+- Known:
+- Unresolved:
+
+## Capabilities
+
+### New Capabilities
+
+-
+
+### Modified Capabilities
+
+-
+
+## Impact
+
+- Workspace planning:
+- Linked repos or folders:
+- User-facing behavior:

package/schemas/workspace-planning/templates/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: <workspace requirement name>
+The workspace plan SHALL describe the required behavior and affected area without creating repo-local artifacts during planning.
+
+#### Scenario: <scenario name>
+- **GIVEN** <context>
+- **WHEN** <action>
+- **THEN** <observable result>

package/schemas/workspace-planning/templates/tasks.md

@@ -0,0 +1,15 @@
+## 1. Workspace Planning
+
+- [ ] 1.1 Confirm the shared product goal and unresolved scope questions.
+- [ ] 1.2 Identify affected areas using registered workspace link names where applicable.
+- [ ] 1.3 Review workspace-scoped specs and design before selecting implementation areas.
+
+## 2. Affected Area Implementation
+
+- [ ] 2.1 Select an affected area and confirm its allowed edit root before implementation.
+- [ ] 2.2 Create or update repo-local implementation artifacts only after the area is selected.
+
+## 3. Verification
+
+- [ ] 3.1 Verify workspace planning artifacts remain the source of truth.
+- [ ] 3.2 Record manual acceptance evidence and follow-up fixes.