@fission-ai/openspec 1.3.0 → 1.4.0

package/dist/core/planning-home.js

@@ -0,0 +1,108 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getWorkspaceChangesDir, readWorkspaceViewStateSync, workspaceStateFileExistsSync, } from './workspace/index.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+const REPO_DEFAULT_SCHEMA = 'spec-driven';
+const WORKSPACE_DEFAULT_SCHEMA = 'workspace-planning';
+function pathExistsAsDirectory(candidatePath) {
+    try {
+        return fs.statSync(candidatePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function getSearchStartDirectory(startPath) {
+    const resolved = path.resolve(startPath);
+    try {
+        const stats = fs.statSync(resolved);
+        const searchStart = stats.isDirectory() ? resolved : path.dirname(resolved);
+        return FileSystemUtils.canonicalizeExistingPath(searchStart);
+    }
+    catch {
+        return resolved;
+    }
+}
+function findNearestAncestor(startPath, predicate) {
+    let currentDir = getSearchStartDirectory(startPath);
+    while (true) {
+        if (predicate(currentDir)) {
+            return FileSystemUtils.canonicalizeExistingPath(currentDir);
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+export function findWorkspacePlanningRootSync(startPath = process.cwd()) {
+    return findNearestAncestor(startPath, workspaceStateFileExistsSync);
+}
+export function findRepoPlanningRootSync(startPath = process.cwd()) {
+    return findNearestAncestor(startPath, (dirPath) => pathExistsAsDirectory(path.join(dirPath, 'openspec')));
+}
+function isSameOrDescendant(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function countPathSegments(candidatePath) {
+    return path.resolve(candidatePath).split(path.sep).filter(Boolean).length;
+}
+function isWindowsLikePath(candidatePath) {
+    return /^[A-Za-z]:[\\/]/.test(candidatePath) || candidatePath.startsWith('\\\\');
+}
+function relativePlanningPath(fromPath, toPath) {
+    if (isWindowsLikePath(fromPath) || isWindowsLikePath(toPath)) {
+        return path.win32.relative(path.win32.normalize(fromPath), path.win32.normalize(toPath));
+    }
+    return path.posix.relative(fromPath.replace(/\\/g, '/'), toPath.replace(/\\/g, '/'));
+}
+function workspacePlanningHome(workspaceRoot) {
+    const viewState = readWorkspaceViewStateSync(workspaceRoot);
+    return {
+        kind: 'workspace',
+        root: workspaceRoot,
+        changesDir: getWorkspaceChangesDir(workspaceRoot),
+        defaultSchema: WORKSPACE_DEFAULT_SCHEMA,
+        workspace: {
+            name: viewState?.name ?? path.basename(workspaceRoot),
+            links: Object.keys(viewState?.links ?? {}).sort((a, b) => a.localeCompare(b)),
+        },
+    };
+}
+function repoPlanningHome(repoRoot) {
+    return {
+        kind: 'repo',
+        root: repoRoot,
+        changesDir: path.join(repoRoot, 'openspec', 'changes'),
+        defaultSchema: REPO_DEFAULT_SCHEMA,
+    };
+}
+export function resolveCurrentPlanningHomeSync(options = {}) {
+    const startPath = options.startPath ?? process.cwd();
+    const searchStart = getSearchStartDirectory(startPath);
+    const workspaceRoot = findWorkspacePlanningRootSync(searchStart);
+    const repoRoot = findRepoPlanningRootSync(searchStart);
+    if (workspaceRoot && isSameOrDescendant(workspaceRoot, searchStart)) {
+        if (!repoRoot || countPathSegments(workspaceRoot) >= countPathSegments(repoRoot)) {
+            return workspacePlanningHome(workspaceRoot);
+        }
+    }
+    if (repoRoot) {
+        return repoPlanningHome(repoRoot);
+    }
+    if (options.allowImplicitRepoRoot === false) {
+        throw new Error('No OpenSpec planning home found from the current directory.');
+    }
+    return repoPlanningHome(FileSystemUtils.canonicalizeExistingPath(searchStart));
+}
+export function getChangeDir(planningHome, changeName) {
+    return FileSystemUtils.joinPath(planningHome.changesDir, changeName);
+}
+export function formatChangeLocation(planningHome, changeName) {
+    const changeDir = getChangeDir(planningHome, changeName);
+    const relative = relativePlanningPath(planningHome.root, changeDir);
+    return relative.length > 0 ? relative : changeDir;
+}
+//# sourceMappingURL=planning-home.js.map

package/dist/core/profiles.d.ts

@@ -9,7 +9,7 @@ import type { Profile } from './global-config.js';
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "archive"];
+export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "sync", "archive"];
 /**
  * All available workflows in the system.
  */

package/dist/core/profiles.js

@@ -8,7 +8,7 @@
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'archive'];
+export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'sync', 'archive'];
 /**
  * All available workflows in the system.
  */

package/dist/core/specs-apply.js

@@ -8,6 +8,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import chalk from 'chalk';
 import { extractRequirementsSection, parseDeltaSpec, normalizeRequirementName, } from './parsers/requirement-blocks.js';
+import { findMainSpecStructureIssues } from './parsers/spec-structure.js';
 import { Validator } from './validation/validator.js';
 // -----------------------------------------------------------------------------
 // Public API
@@ -153,6 +154,13 @@ export async function buildUpdatedSpec(update, changeName) {
         isNewSpec = true;
         targetContent = buildSpecSkeleton(specName, changeName);
     }
+    const structureIssues = findMainSpecStructureIssues(targetContent);
+    if (structureIssues.length > 0) {
+        const details = structureIssues
+            .map(issue => `line ${issue.line}: ${issue.message}`)
+            .join('\n');
+        throw new Error(`${specName}: target spec is structurally invalid and cannot be updated until fixed:\n${details}`);
+    }
     // Extract requirements section and build name->block map
     const parts = extractRequirementsSection(targetContent);
     const nameToBlock = new Map();
@@ -203,7 +211,7 @@ export async function buildUpdatedSpec(update, changeName) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - not found`);
         }
         // Replace block with provided raw (ensure header line matches key)
-        const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/);
+        const modHeaderMatch = mod.raw.split('\n')[0].match(/^###\s*Requirement:\s*(.+)\s*$/i);
         if (!modHeaderMatch || normalizeRequirementName(modHeaderMatch[1]) !== key) {
             throw new Error(`${specName} MODIFIED failed for header "### Requirement: ${mod.name}" - header mismatch in content`);
         }

package/dist/core/templates/workflows/apply-change.js

@@ -23,6 +23,7 @@ export function getApplyChangeSkillTemplate() {
    \`\`\`
    Parse the JSON to understand:
    - \`schemaName\`: The workflow being used (e.g., "spec-driven")
+   - \`planningHome\`, \`changeRoot\`, and \`actionContext\`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -32,7 +33,7 @@ export function getApplyChangeSkillTemplate() {
    \`\`\`
 
    This returns:
-   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
    - Progress (total, complete, remaining)
    - Task list with status
    - Dynamic instruction based on current state
@@ -42,9 +43,11 @@ export function getApplyChangeSkillTemplate() {
    - If \`state: "all_done"\`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports \`actionContext.mode: "workspace-planning"\` and \`allowedEditRoots\` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
-   Read the files listed in \`contextFiles\` from the apply instructions output.
+   Read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
    - **spec-driven**: proposal, specs, design, tasks
    - Other schemas: follow the contextFiles from CLI output
@@ -179,6 +182,7 @@ export function getOpsxApplyCommandTemplate() {
    \`\`\`
    Parse the JSON to understand:
    - \`schemaName\`: The workflow being used (e.g., "spec-driven")
+   - \`planningHome\`, \`changeRoot\`, and \`actionContext\`: planning scope and edit constraints
    - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
 
 3. **Get apply instructions**
@@ -188,7 +192,7 @@ export function getOpsxApplyCommandTemplate() {
    \`\`\`
 
    This returns:
-   - Context file paths (varies by schema)
+   - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema)
    - Progress (total, complete, remaining)
    - Task list with status
    - Dynamic instruction based on current state
@@ -198,9 +202,11 @@ export function getOpsxApplyCommandTemplate() {
    - If \`state: "all_done"\`: congratulate, suggest archive
    - Otherwise: proceed to implementation
 
+   **Workspace guard:** If status JSON reports \`actionContext.mode: "workspace-planning"\` and \`allowedEditRoots\` is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.
+
 4. **Read context files**
 
-   Read the files listed in \`contextFiles\` from the apply instructions output.
+   Read every file path listed under \`contextFiles\` from the apply instructions output.
    The files depend on the schema being used:
    - **spec-driven**: proposal, specs, design, tasks
    - Other schemas: follow the contextFiles from CLI output

package/dist/core/templates/workflows/archive-change.js

@@ -23,8 +23,11 @@ export function getArchiveChangeSkillTemplate() {
 
    Parse the JSON to understand:
    - \`schemaName\`: The workflow being used
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context
    - \`artifacts\`: List of artifacts with their status (\`done\` or other)
 
+   If status reports \`actionContext.mode: "workspace-planning"\`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not \`done\`:**
    - Display warning listing incomplete artifacts
    - Use **AskUserQuestion tool** to confirm user wants to proceed
@@ -45,7 +48,7 @@ export function getArchiveChangeSkillTemplate() {
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at \`openspec/changes/<name>/specs/\`. If none exist, proceed without sync prompt.
+   Use \`artifactPaths.specs.existingOutputPaths\` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at \`openspec/specs/<capability>/spec.md\`
@@ -60,19 +63,19 @@ export function getArchiveChangeSkillTemplate() {
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an \`archive\` directory under \`planningHome.changesDir\` if it doesn't exist:
    \`\`\`bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    \`\`\`
 
    Generate target name using current date: \`YYYY-MM-DD-<change-name>\`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move \`changeRoot\` to the archive directory
 
    \`\`\`bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    \`\`\`
 
 6. **Display summary**
@@ -91,7 +94,7 @@ export function getArchiveChangeSkillTemplate() {
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from \`planningHome.changesDir\`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
 
 All artifacts complete. All tasks complete.
@@ -137,8 +140,11 @@ export function getOpsxArchiveCommandTemplate() {
 
    Parse the JSON to understand:
    - \`schemaName\`: The workflow being used
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context
    - \`artifacts\`: List of artifacts with their status (\`done\` or other)
 
+   If status reports \`actionContext.mode: "workspace-planning"\`, explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.
+
    **If any artifacts are not \`done\`:**
    - Display warning listing incomplete artifacts
    - Prompt user for confirmation to continue
@@ -159,7 +165,7 @@ export function getOpsxArchiveCommandTemplate() {
 
 4. **Assess delta spec sync state**
 
-   Check for delta specs at \`openspec/changes/<name>/specs/\`. If none exist, proceed without sync prompt.
+   Use \`artifactPaths.specs.existingOutputPaths\` from status JSON to check for delta specs. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
    - Compare each delta spec with its corresponding main spec at \`openspec/specs/<capability>/spec.md\`
@@ -174,19 +180,19 @@ export function getOpsxArchiveCommandTemplate() {
 
 5. **Perform the archive**
 
-   Create the archive directory if it doesn't exist:
+   Create an \`archive\` directory under \`planningHome.changesDir\` if it doesn't exist:
    \`\`\`bash
-   mkdir -p openspec/changes/archive
+   mkdir -p "<planningHome.changesDir>/archive"
    \`\`\`
 
    Generate target name using current date: \`YYYY-MM-DD-<change-name>\`
 
    **Check if target already exists:**
    - If yes: Fail with error, suggest renaming existing archive or using different date
-   - If no: Move the change directory to archive
+   - If no: Move \`changeRoot\` to the archive directory
 
    \`\`\`bash
-   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
    \`\`\`
 
 6. **Display summary**
@@ -205,7 +211,7 @@ export function getOpsxArchiveCommandTemplate() {
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from \`planningHome.changesDir\`/YYYY-MM-DD-<name>/
 **Specs:** ✓ Synced to main specs
 
 All artifacts complete. All tasks complete.
@@ -218,7 +224,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from \`planningHome.changesDir\`/YYYY-MM-DD-<name>/
 **Specs:** No delta specs
 
 All artifacts complete. All tasks complete.
@@ -231,7 +237,7 @@ All artifacts complete. All tasks complete.
 
 **Change:** <change-name>
 **Schema:** <schema-name>
-**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Archived to:** the archive path derived from \`planningHome.changesDir\`/YYYY-MM-DD-<name>/
 **Specs:** Sync skipped (user chose to skip)
 
 **Warnings:**
@@ -248,7 +254,7 @@ Review the archive if this was not intentional.
 ## Archive Failed
 
 **Change:** <change-name>
-**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Target:** the archive path derived from \`planningHome.changesDir\`/YYYY-MM-DD-<name>/
 
 Target archive directory already exists.
 

package/dist/core/templates/workflows/bulk-archive-change.js

@@ -30,14 +30,16 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    For each selected change, collect:
 
    a. **Artifact status** - Run \`openspec status --change "<name>" --json\`
-      - Parse \`schemaName\` and \`artifacts\` list
+      - Parse \`schemaName\`, \`artifacts\`, \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`
       - Note which artifacts are \`done\` vs other states
 
-   b. **Task completion** - Read \`openspec/changes/<name>/tasks.md\`
+      If any selected change reports \`actionContext.mode: "workspace-planning"\`, explain that workspace bulk archive is not supported in this slice and STOP before syncing specs or moving changes. Do not fall back to repo-local paths or edit linked repos.
+
+   b. **Task completion** - Read \`artifactPaths.tasks.existingOutputPaths\` from status JSON
       - Count \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
       - If no tasks file exists, note as "No tasks"
 
-   c. **Delta specs** - Check \`openspec/changes/<name>/specs/\` directory
+   c. **Delta specs** - Check \`artifactPaths.specs.existingOutputPaths\` from status JSON
       - List which capability specs exist
       - For each, extract requirement names (lines matching \`### Requirement: <name>\`)
 
@@ -120,8 +122,8 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
    b. **Perform the archive**:
       \`\`\`bash
-      mkdir -p openspec/changes/archive
-      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      mkdir -p "<planningHome.changesDir>/archive"
+      mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
       \`\`\`
 
    c. **Track outcome** for each change:
@@ -276,14 +278,16 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    For each selected change, collect:
 
    a. **Artifact status** - Run \`openspec status --change "<name>" --json\`
-      - Parse \`schemaName\` and \`artifacts\` list
+      - Parse \`schemaName\`, \`artifacts\`, \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`
       - Note which artifacts are \`done\` vs other states
 
-   b. **Task completion** - Read \`openspec/changes/<name>/tasks.md\`
+      If any selected change reports \`actionContext.mode: "workspace-planning"\`, explain that workspace bulk archive is not supported in this slice and STOP before syncing specs or moving changes. Do not fall back to repo-local paths or edit linked repos.
+
+   b. **Task completion** - Read \`artifactPaths.tasks.existingOutputPaths\` from status JSON
       - Count \`- [ ]\` (incomplete) vs \`- [x]\` (complete)
       - If no tasks file exists, note as "No tasks"
 
-   c. **Delta specs** - Check \`openspec/changes/<name>/specs/\` directory
+   c. **Delta specs** - Check \`artifactPaths.specs.existingOutputPaths\` from status JSON
       - List which capability specs exist
       - For each, extract requirement names (lines matching \`### Requirement: <name>\`)
 
@@ -366,8 +370,8 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
 
    b. **Perform the archive**:
       \`\`\`bash
-      mkdir -p openspec/changes/archive
-      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      mkdir -p "<planningHome.changesDir>/archive"
+      mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
       \`\`\`
 
    c. **Track outcome** for each change:

package/dist/core/templates/workflows/continue-change.js

@@ -30,6 +30,7 @@ export function getContinueChangeSkillTemplate() {
    - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
    - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked")
    - \`isComplete\`: Boolean indicating if all artifacts are complete
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
 3. **Act based on status**:
 
@@ -54,13 +55,13 @@ export function getContinueChangeSkillTemplate() {
      - \`rules\`: Artifact-specific rules (constraints for you - do NOT include in output)
      - \`template\`: The structure to use for your output file
      - \`instruction\`: Schema-specific guidance
-     - \`outputPath\`: Where to write the artifact
+     - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
      - \`dependencies\`: Completed artifacts to read for context
    - **Create the artifact file**:
      - Read any completed dependency files for context
      - Use \`template\` as the structure - fill in its sections
      - Apply \`context\` and \`rules\` as constraints when writing - but do NOT copy them into the file
-     - Write to the output path specified in instructions
+     - Write to the \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and workspace planning context
    - Show what was created and what's now unlocked
    - STOP after creating ONE artifact
 
@@ -148,6 +149,7 @@ export function getOpsxContinueCommandTemplate() {
    - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
    - \`artifacts\`: Array of artifacts with their status ("done", "ready", "blocked")
    - \`isComplete\`: Boolean indicating if all artifacts are complete
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
 3. **Act based on status**:
 
@@ -172,13 +174,13 @@ export function getOpsxContinueCommandTemplate() {
      - \`rules\`: Artifact-specific rules (constraints for you - do NOT include in output)
      - \`template\`: The structure to use for your output file
      - \`instruction\`: Schema-specific guidance
-     - \`outputPath\`: Where to write the artifact
+     - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
      - \`dependencies\`: Completed artifacts to read for context
    - **Create the artifact file**:
      - Read any completed dependency files for context
      - Use \`template\` as the structure - fill in its sections
      - Apply \`context\` and \`rules\` as constraints when writing - but do NOT copy them into the file
-     - Write to the output path specified in instructions
+     - Write to the \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and workspace planning context
    - Show what was created and what's now unlocked
    - STOP after creating ONE artifact
 

package/dist/core/templates/workflows/explore.js

@@ -95,11 +95,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - \`openspec/changes/<name>/proposal.md\`
-   - \`openspec/changes/<name>/design.md\`
-   - \`openspec/changes/<name>/tasks.md\`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run \`openspec status --change "<name>" --json\`.
+   - Use \`changeRoot\`, \`artifactPaths\`, and \`actionContext\` from the status JSON.
+   - Read existing files from \`artifactPaths.<artifact>.existingOutputPaths\`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."
@@ -392,11 +391,10 @@ Think freely. When insights crystallize, you might offer:
 
 If the user mentions a change or you detect one is relevant:
 
-1. **Read existing artifacts for context**
-   - \`openspec/changes/<name>/proposal.md\`
-   - \`openspec/changes/<name>/design.md\`
-   - \`openspec/changes/<name>/tasks.md\`
-   - etc.
+1. **Resolve and read existing artifacts for context**
+   - Run \`openspec status --change "<name>" --json\`.
+   - Use \`changeRoot\`, \`artifactPaths\`, and \`actionContext\` from the status JSON.
+   - Read existing files from \`artifactPaths.<artifact>.existingOutputPaths\`.
 
 2. **Reference them naturally in conversation**
    - "Your design mentions using Redis, but we just realized SQLite fits better..."

package/dist/core/templates/workflows/ff-change.js

@@ -21,7 +21,7 @@ export function getFfChangeSkillTemplate() {
    \`\`\`bash
    openspec new change "<name>"
    \`\`\`
-   This creates a scaffolded change at \`openspec/changes/<name>/\`.
+   This creates a scaffolded change in the planning home resolved by the CLI.
 
 3. **Get the artifact build order**
    \`\`\`bash
@@ -30,6 +30,7 @@ export function getFfChangeSkillTemplate() {
    Parse the JSON to get:
    - \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`)
    - \`artifacts\`: list of all artifacts with their status and dependencies
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -47,10 +48,10 @@ export function getFfChangeSkillTemplate() {
         - \`rules\`: Artifact-specific rules (constraints for you - do NOT include in output)
         - \`template\`: The structure to use for your output file
         - \`instruction\`: Schema-specific guidance for this artifact type
-        - \`outputPath\`: Where to write the artifact
+        - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
         - \`dependencies\`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using \`template\` as the structure
+      - Create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
       - Show brief progress: "✓ Created <artifact-id>"
 
@@ -122,7 +123,7 @@ export function getOpsxFfCommandTemplate() {
    \`\`\`bash
    openspec new change "<name>"
    \`\`\`
-   This creates a scaffolded change at \`openspec/changes/<name>/\`.
+   This creates a scaffolded change in the planning home resolved by the CLI.
 
 3. **Get the artifact build order**
    \`\`\`bash
@@ -131,6 +132,7 @@ export function getOpsxFfCommandTemplate() {
    Parse the JSON to get:
    - \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`)
    - \`artifacts\`: list of all artifacts with their status and dependencies
+   - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
 4. **Create artifacts in sequence until apply-ready**
 
@@ -148,10 +150,10 @@ export function getOpsxFfCommandTemplate() {
         - \`rules\`: Artifact-specific rules (constraints for you - do NOT include in output)
         - \`template\`: The structure to use for your output file
         - \`instruction\`: Schema-specific guidance for this artifact type
-        - \`outputPath\`: Where to write the artifact
+        - \`resolvedOutputPath\`: Resolved path or pattern to write the artifact
         - \`dependencies\`: Completed artifacts to read for context
       - Read any completed dependency files for context
-      - Create the artifact file using \`template\` as the structure
+      - Create the artifact file using \`template\` as the structure and write it to \`resolvedOutputPath\`
       - Apply \`context\` and \`rules\` as constraints - but do NOT copy them into the file
       - Show brief progress: "✓ Created <artifact-id>"
 

package/dist/core/templates/workflows/new-change.js

@@ -32,13 +32,13 @@ export function getNewChangeSkillTemplate() {
    openspec new change "<name>"
    \`\`\`
    Add \`--schema <name>\` only if the user requested a specific workflow.
-   This creates a scaffolded change at \`openspec/changes/<name>/\` with the selected schema.
+   This creates a scaffolded change in the planning home resolved by the CLI.
 
 4. **Show the artifact status**
    \`\`\`bash
-   openspec status --change "<name>"
+   openspec status --change "<name>" --json
    \`\`\`
-   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+   Use the returned \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`nextSteps\` instead of assuming repo-local paths.
 
 5. **Get instructions for the first artifact**
    The first artifact depends on the schema (e.g., \`proposal\` for spec-driven).
@@ -106,13 +106,13 @@ export function getOpsxNewCommandTemplate() {
    openspec new change "<name>"
    \`\`\`
    Add \`--schema <name>\` only if the user requested a specific workflow.
-   This creates a scaffolded change at \`openspec/changes/<name>/\` with the selected schema.
+   This creates a scaffolded change in the planning home resolved by the CLI.
 
 4. **Show the artifact status**
    \`\`\`bash
-   openspec status --change "<name>"
+   openspec status --change "<name>" --json
    \`\`\`
-   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+   Use the returned \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`nextSteps\` instead of assuming repo-local paths.
 
 5. **Get instructions for the first artifact**
    The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".