@fission-ai/openspec 1.4.1 → 1.5.0

package/dist/core/store/registry.d.ts

@@ -0,0 +1,58 @@
+import { type StoreBackendConfig, type StoreGitBackendConfig, type StorePathOptions, type StoreRegistryEntry, type StoreRegistryState } from './foundation.js';
+export interface RegisterStoreInput extends StorePathOptions {
+    id: string;
+    localPath: string;
+    remote?: string;
+    branch?: string;
+    cwd?: string;
+}
+export interface ResolveRegisteredStoreInput extends StorePathOptions {
+    id: string;
+}
+export interface GetRegisteredStoreInput extends ResolveRegisteredStoreInput {
+    expectedBackend?: StoreGitBackendConfig;
+}
+export interface UnregisterStoreInput extends StorePathOptions {
+    id: string;
+    expectedBackend?: StoreGitBackendConfig;
+    beforeCommit?: (entry: RegisteredStoreEntry) => Promise<void>;
+}
+export type ListRegisteredStoresOptions = StorePathOptions;
+export interface RegisteredStoreEntry extends StoreRegistryEntry {
+    storeRoot: string;
+}
+export interface ResolvedStore {
+    id: string;
+    storeRoot: string;
+    backend: StoreGitBackendConfig;
+}
+export interface StoreRegistrationCommit extends ResolvedStore {
+    metadataCreated: boolean;
+    registryUpdated: boolean;
+    alreadyRegistered: boolean;
+}
+export interface CommitStoreRegistrationInput extends StorePathOptions {
+    id: string;
+    backend: StoreGitBackendConfig;
+    writeMetadataIfMissing: boolean;
+}
+export declare function getStoreRootForBackend(backend: StoreBackendConfig): string;
+export declare function assertNoRegisteredStoreConflict(registry: StoreRegistryState | null, id: string, backend: StoreGitBackendConfig): void;
+export declare function commitStoreRegistration(input: CommitStoreRegistrationInput): Promise<StoreRegistrationCommit>;
+export declare function registerStore(input: RegisterStoreInput): Promise<ResolvedStore>;
+export interface RegistrySnapshot {
+    /** null = the registry is unreadable; [] = empty or absent. */
+    entries: StoreRegistryEntry[] | null;
+    unreadable: boolean;
+}
+/**
+ * One registry read serving every consumer in a command.
+ */
+export declare function readRegistrySnapshot(options?: {
+    globalDataDir?: string;
+}): Promise<RegistrySnapshot>;
+export declare function listRegisteredStores(options?: ListRegisteredStoresOptions): Promise<RegisteredStoreEntry[]>;
+export declare function getRegisteredStore(input: GetRegisteredStoreInput): Promise<RegisteredStoreEntry>;
+export declare function unregisterStoreRegistration(input: UnregisterStoreInput): Promise<RegisteredStoreEntry>;
+export declare function resolveRegisteredStore(input: ResolveRegisteredStoreInput): Promise<ResolvedStore>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/store/registry.js

@@ -0,0 +1,275 @@
+import * as fs from 'node:fs/promises';
+import { getStoreMetadataPath, getStoreMetadataDir, listStoreRegistryEntries, readStoreRegistryState, readOptionalStoreMetadataState, resolveGitStoreBackendConfig, updateStoreRegistryState, validateStoreId, writeStoreMetadataState, } from './foundation.js';
+import { StoreError } from './errors.js';
+import * as path from 'node:path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export function getStoreRootForBackend(backend) {
+    switch (backend.type) {
+        case 'git':
+            return backend.local_path;
+    }
+}
+function normalizePathForComparison(targetPath) {
+    try {
+        return FileSystemUtils.canonicalizeExistingPath(targetPath);
+    }
+    catch {
+        // Nonexistent (e.g. stale) paths still deserve a resolved compare;
+        // aligns with the operations.ts sibling fallback.
+        return path.resolve(targetPath);
+    }
+}
+export function assertNoRegisteredStoreConflict(registry, id, backend) {
+    const nextPath = normalizePathForComparison(getStoreRootForBackend(backend));
+    for (const entry of listStoreRegistryEntries(registry ?? { version: 1, stores: {} })) {
+        const entryPath = normalizePathForComparison(getStoreRootForBackend(entry.backend));
+        if (entry.id === id && entryPath === nextPath) {
+            continue;
+        }
+        if (entry.id === id) {
+            throw new StoreError(`Store '${id}' is already registered at ${getStoreRootForBackend(entry.backend)}. One checkout per store id is supported on this machine.`, 'store_id_conflict', {
+                target: 'store.id',
+                fix: `Use the existing registration, or run openspec store unregister ${id} first to switch this id to a different checkout.`,
+            });
+        }
+        if (entryPath === nextPath) {
+            throw new StoreError(`Store path is already registered as '${entry.id}'.`, 'store_path_conflict', {
+                target: 'store.root',
+                fix: `Use the existing '${entry.id}' registration or choose a different path.`,
+            });
+        }
+    }
+}
+function withRegisteredStore(registry, id, backend) {
+    assertNoRegisteredStoreConflict(registry, id, backend);
+    const stores = {
+        ...(registry?.stores ?? {}),
+        [id]: {
+            backend,
+        },
+    };
+    return {
+        version: 1,
+        stores: Object.fromEntries(Object.entries(stores).sort(([leftId], [rightId]) => leftId.localeCompare(rightId))),
+    };
+}
+function getRegisteredStoreOrThrow(registry, id) {
+    const entry = registry?.stores[id];
+    if (!entry) {
+        throw new StoreError(`Unknown store '${id}'`, 'store_not_found', {
+            target: 'store.id',
+            fix: 'Run openspec store list to see registered stores.',
+        });
+    }
+    return {
+        id,
+        backend: entry.backend,
+    };
+}
+/** Same checkout: type, canonical path, and branch — remote excluded. */
+function sameCheckout(actual, expected) {
+    return (actual.type === expected.type &&
+        normalizePathForComparison(actual.local_path) ===
+            normalizePathForComparison(expected.local_path) &&
+        actual.branch === expected.branch);
+}
+function storeBackendsMatch(actual, expected) {
+    return sameCheckout(actual, expected) && actual.remote === expected.remote;
+}
+function assertExpectedRegisteredBackend(id, actual, expected) {
+    if (!expected || storeBackendsMatch(actual, expected))
+        return;
+    throw new StoreError(`Store '${id}' changed before cleanup completed.`, 'store_registry_changed', {
+        target: 'store.registry',
+        fix: 'Retry the cleanup command after reviewing the current store registration.',
+    });
+}
+function withoutRegisteredStore(registry, id, expectedBackend) {
+    const removed = getRegisteredStoreOrThrow(registry, id);
+    assertExpectedRegisteredBackend(id, removed.backend, expectedBackend);
+    const stores = { ...(registry?.stores ?? {}) };
+    delete stores[id];
+    return {
+        removed,
+        next: {
+            version: 1,
+            stores: Object.fromEntries(Object.entries(stores).sort(([leftId], [rightId]) => leftId.localeCompare(rightId))),
+        },
+    };
+}
+async function ensureStoreMetadata(storeRoot, id, options) {
+    const metadata = await readOptionalStoreMetadataState(storeRoot);
+    if (!metadata) {
+        if (!options.writeIfMissing) {
+            throw new StoreError(`Registered store '${id}' is missing metadata at ${getStoreMetadataPath(storeRoot)}`, 'store_metadata_missing', {
+                target: 'store.metadata',
+                fix: `Create ${getStoreMetadataPath(storeRoot)} or rerun "openspec store register <path>".`,
+            });
+        }
+        await writeStoreMetadataState(storeRoot, {
+            version: 1,
+            id,
+        });
+        return true;
+    }
+    if (metadata.id !== id) {
+        throw new StoreError(`Store metadata id '${metadata.id}' does not match registered id '${id}'`, 'store_metadata_id_mismatch', {
+            target: 'store.metadata',
+            fix: 'Repair the local registry or store metadata so the ids match.',
+        });
+    }
+    return false;
+}
+export async function commitStoreRegistration(input) {
+    const id = validateStoreId(input.id);
+    const backend = input.backend;
+    const storeRoot = getStoreRootForBackend(backend);
+    let metadataCreated = false;
+    let isRerun = false;
+    let registryUpdated = false;
+    try {
+        metadataCreated = await ensureStoreMetadata(storeRoot, id, {
+            writeIfMissing: input.writeMetadataIfMissing,
+        });
+        const registry = await readStoreRegistryState({
+            globalDataDir: input.globalDataDir,
+        });
+        const existing = registry?.stores[id];
+        const existingBackend = existing?.backend;
+        // Same checkout = a rerun for an already-registered store (the 1.3
+        // reporting contract), whether or not the observed remote changed;
+        // only a remote change needs the registry write (the refresh).
+        isRerun = existingBackend !== undefined && sameCheckout(existingBackend, backend);
+        const upToDate = isRerun && existingBackend !== undefined && storeBackendsMatch(existingBackend, backend);
+        if (!upToDate) {
+            await updateStoreRegistryState((registry) => withRegisteredStore(registry, id, backend), { globalDataDir: input.globalDataDir });
+            registryUpdated = true;
+        }
+    }
+    catch (error) {
+        if (metadataCreated) {
+            // A concurrent registration may have read our metadata as
+            // pre-existing and committed against it - never delete metadata a
+            // committed registry entry depends on.
+            const current = await readStoreRegistryState({
+                globalDataDir: input.globalDataDir,
+            }).catch(() => null);
+            if (!current?.stores[id]) {
+                await fs.rm(getStoreMetadataPath(storeRoot), { force: true });
+                await fs.rmdir(getStoreMetadataDir(storeRoot)).catch(() => undefined);
+            }
+        }
+        throw error;
+    }
+    return {
+        id,
+        storeRoot,
+        backend,
+        metadataCreated,
+        registryUpdated,
+        alreadyRegistered: isRerun,
+    };
+}
+export async function registerStore(input) {
+    const id = validateStoreId(input.id);
+    const backend = await resolveGitStoreBackendConfig({
+        localPath: input.localPath,
+        ...(input.remote !== undefined ? { remote: input.remote } : {}),
+        ...(input.branch !== undefined ? { branch: input.branch } : {}),
+    }, input.cwd);
+    const storeRoot = getStoreRootForBackend(backend);
+    const committed = await commitStoreRegistration({
+        id,
+        backend,
+        writeMetadataIfMissing: true,
+        ...(input.globalDataDir ? { globalDataDir: input.globalDataDir } : {}),
+    });
+    return {
+        id: committed.id,
+        storeRoot: committed.storeRoot,
+        backend: committed.backend,
+    };
+}
+/**
+ * One registry read serving every consumer in a command.
+ */
+export async function readRegistrySnapshot(options = {}) {
+    try {
+        const registry = await readStoreRegistryState(options);
+        return {
+            entries: registry ? listStoreRegistryEntries(registry) : [],
+            unreadable: false,
+        };
+    }
+    catch {
+        return { entries: null, unreadable: true };
+    }
+}
+export async function listRegisteredStores(options = {}) {
+    const registry = await readStoreRegistryState(options);
+    if (!registry) {
+        return [];
+    }
+    return listStoreRegistryEntries(registry).map((entry) => ({
+        ...entry,
+        storeRoot: getStoreRootForBackend(entry.backend),
+    }));
+}
+export async function getRegisteredStore(input) {
+    const id = validateStoreId(input.id);
+    const registry = await readStoreRegistryState({
+        globalDataDir: input.globalDataDir,
+    });
+    const entry = getRegisteredStoreOrThrow(registry, id);
+    assertExpectedRegisteredBackend(id, entry.backend, input.expectedBackend);
+    return {
+        ...entry,
+        storeRoot: getStoreRootForBackend(entry.backend),
+    };
+}
+export async function unregisterStoreRegistration(input) {
+    const id = validateStoreId(input.id);
+    let removed;
+    await updateStoreRegistryState(async (registry) => {
+        const result = withoutRegisteredStore(registry, id, input.expectedBackend);
+        const removedEntry = {
+            ...result.removed,
+            storeRoot: getStoreRootForBackend(result.removed.backend),
+        };
+        await input.beforeCommit?.(removedEntry);
+        removed = result.removed;
+        return result.next;
+    }, { globalDataDir: input.globalDataDir });
+    if (!removed) {
+        throw new StoreError(`Unknown store '${id}'`, 'store_not_found', {
+            target: 'store.id',
+            fix: 'Run openspec store list to see registered stores.',
+        });
+    }
+    return {
+        ...removed,
+        storeRoot: getStoreRootForBackend(removed.backend),
+    };
+}
+export async function resolveRegisteredStore(input) {
+    const id = validateStoreId(input.id);
+    const registry = await readStoreRegistryState({
+        globalDataDir: input.globalDataDir,
+    });
+    if (!registry) {
+        throw new StoreError('No store registry found', 'no_store_registry', {
+            target: 'store.id',
+            fix: 'Register a store with openspec store register <path>, then select it with --store <id>.',
+        });
+    }
+    const entry = getRegisteredStoreOrThrow(registry, id);
+    const backend = entry.backend;
+    const storeRoot = getStoreRootForBackend(backend);
+    await ensureStoreMetadata(storeRoot, id, { writeIfMissing: false });
+    return {
+        id,
+        storeRoot,
+        backend,
+    };
+}
+//# sourceMappingURL=registry.js.map

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

@@ -1,9 +1,12 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getApplyChangeSkillTemplate() {
     return {
         name: 'openspec-apply-change',
         description: 'Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.',
         instructions: `Implement tasks from an OpenSpec change.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -43,8 +46,6 @@ 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 every file path listed under \`contextFiles\` from the apply instructions output.
@@ -163,6 +164,8 @@ export function getOpsxApplyCommandTemplate() {
         tags: ['workflow', 'artifacts', 'experimental'],
         content: `Implement tasks from an OpenSpec change.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name (e.g., \`/opsx:apply add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -202,8 +205,6 @@ 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 every file path listed under \`contextFiles\` from the apply instructions output.

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

@@ -1,9 +1,12 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getArchiveChangeSkillTemplate() {
     return {
         name: 'openspec-archive-change',
         description: 'Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.',
         instructions: `Archive a completed change in the experimental workflow.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -26,8 +29,6 @@ export function getArchiveChangeSkillTemplate() {
    - \`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
@@ -121,6 +122,8 @@ export function getOpsxArchiveCommandTemplate() {
         tags: ['workflow', 'archive', 'experimental'],
         content: `Archive a completed change in the experimental workflow.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name after \`/opsx:archive\` (e.g., \`/opsx:archive add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -143,8 +146,6 @@ export function getOpsxArchiveCommandTemplate() {
    - \`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

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

@@ -1,3 +1,4 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getBulkArchiveChangeSkillTemplate() {
     return {
         name: 'openspec-bulk-archive-change',
@@ -6,6 +7,8 @@ export function getBulkArchiveChangeSkillTemplate() {
 
 This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: None required (prompts for selection)
 
 **Steps**
@@ -33,8 +36,6 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
       - Parse \`schemaName\`, \`artifacts\`, \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`
       - Note which artifacts are \`done\` vs other states
 
-      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"
@@ -254,6 +255,8 @@ export function getOpsxBulkArchiveCommandTemplate() {
 
 This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: None required (prompts for selection)
 
 **Steps**
@@ -281,8 +284,6 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
       - Parse \`schemaName\`, \`artifacts\`, \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`
       - Note which artifacts are \`done\` vs other states
 
-      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"

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

@@ -1,9 +1,12 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getContinueChangeSkillTemplate() {
     return {
         name: 'openspec-continue-change',
         description: 'Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow.',
         instructions: `Continue working on a change by creating the next artifact.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -61,7 +64,7 @@ export function getContinueChangeSkillTemplate() {
      - 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 \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and workspace planning context
+     - Write to the \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and the change's context
    - Show what was created and what's now unlocked
    - STOP after creating ONE artifact
 
@@ -123,6 +126,8 @@ export function getOpsxContinueCommandTemplate() {
         tags: ['workflow', 'artifacts', 'experimental'],
         content: `Continue working on a change by creating the next artifact.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name after \`/opsx:continue\` (e.g., \`/opsx:continue add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -180,7 +185,7 @@ export function getOpsxContinueCommandTemplate() {
      - 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 \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and workspace planning context
+     - Write to the \`resolvedOutputPath\` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and the change's context
    - Show what was created and what's now unlocked
    - STOP after creating ONE artifact
 

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

@@ -1,3 +1,4 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getExploreSkillTemplate() {
     return {
         name: 'openspec-explore',
@@ -8,6 +9,8 @@ export function getExploreSkillTemplate() {
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
+${STORE_SELECTION_GUIDANCE}
+
 ---
 
 ## The Stance
@@ -295,6 +298,8 @@ export function getOpsxExploreCommandTemplate() {
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The argument after \`/opsx:explore\` is whatever the user wants to think about. Could be:
 - A vague idea: "real-time collaboration"
 - A specific problem: "the auth system is getting unwieldy"

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

@@ -1,9 +1,12 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getFfChangeSkillTemplate() {
     return {
         name: 'openspec-ff-change',
         description: 'Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.',
         instructions: `Fast-forward through artifact creation - generate everything needed to start implementation in one go.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
 **Steps**
@@ -106,6 +109,8 @@ export function getOpsxFfCommandTemplate() {
         tags: ['workflow', 'artifacts', 'experimental'],
         content: `Fast-forward through artifact creation - generate everything needed to start implementation.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The argument after \`/opsx:ff\` is the change name (kebab-case), OR a description of what the user wants to build.
 
 **Steps**

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

@@ -1,9 +1,12 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getNewChangeSkillTemplate() {
     return {
         name: 'openspec-new-change',
         description: 'Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.',
         instructions: `Start a new change using the experimental artifact-driven approach.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
 **Steps**
@@ -78,6 +81,8 @@ export function getOpsxNewCommandTemplate() {
         tags: ['workflow', 'artifacts', 'experimental'],
         content: `Start a new change using the experimental artifact-driven approach.
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The argument after \`/opsx:new\` is the change name (kebab-case), OR a description of what the user wants to build.
 
 **Steps**

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

@@ -1,3 +1,4 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getOnboardSkillTemplate() {
     return {
         name: 'openspec-onboard',
@@ -11,6 +12,8 @@ export function getOnboardSkillTemplate() {
 function getOnboardInstructions() {
     return `Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
 
+${STORE_SELECTION_GUIDANCE}
+
 ---
 
 ## Preflight
@@ -269,7 +272,7 @@ For a small task like this, we might only need one spec file.
 **DO:** Resolve where the spec file should be created:
 \`\`\`bash
 openspec instructions specs --change "<name>" --json
-# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and workspace planning context.
+# Use resolvedOutputPath from the JSON. If it is a glob, choose the concrete file path using the schema instruction and the change's context.
 \`\`\`
 
 Draft the spec content:

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

@@ -1,3 +1,4 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getOpsxProposeSkillTemplate() {
     return {
         name: 'openspec-propose',
@@ -13,6 +14,8 @@ When ready to implement, run /opsx:apply
 
 ---
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
 
 **Steps**
@@ -124,6 +127,8 @@ When ready to implement, run /opsx:apply
 
 ---
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: The argument after \`/opsx:propose\` is the change name (kebab-case), OR a description of what the user wants to build.
 
 **Steps**

package/dist/core/templates/workflows/store-selection.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared store-selection guidance for skill template workflows.
+ *
+ * Interpolated into every workflow's instructions so generated skills
+ * consistently teach how to target a registered store with `--store <id>`.
+ */
+export declare const STORE_SELECTION_GUIDANCE = "**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run `openspec store list --json` to discover registered store ids, then pass `--store <id>` on the commands that read or write specs and changes (`new change`, `status`, `instructions`, `list`, `show`, `validate`, `archive`, `doctor`, `context`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local `openspec/` root.";
+//# sourceMappingURL=store-selection.d.ts.map

package/dist/core/templates/workflows/store-selection.js

@@ -0,0 +1,8 @@
+/**
+ * Shared store-selection guidance for skill template workflows.
+ *
+ * Interpolated into every workflow's instructions so generated skills
+ * consistently teach how to target a registered store with `--store <id>`.
+ */
+export const STORE_SELECTION_GUIDANCE = `**Store selection:** If the user names a store (a store is a standalone OpenSpec repo registered on this machine) or the work lives in one, run \`openspec store list --json\` to discover registered store ids, then pass \`--store <id>\` on the commands that read or write specs and changes (\`new change\`, \`status\`, \`instructions\`, \`list\`, \`show\`, \`validate\`, \`archive\`, \`doctor\`, \`context\`). Other commands do not take the flag. Hints printed by commands already carry the flag; keep it on follow-ups. Without a store, commands act on the nearest local \`openspec/\` root.`;
+//# sourceMappingURL=store-selection.js.map

package/dist/core/templates/workflows/sync-specs.js

@@ -1,3 +1,4 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
 export function getSyncSpecsSkillTemplate() {
     return {
         name: 'openspec-sync-specs',
@@ -6,6 +7,8 @@ export function getSyncSpecsSkillTemplate() {
 
 This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -25,8 +28,6 @@ This is an **agent-driven** operation - you will read delta specs and directly e
    openspec status --change "<name>" --json
    \`\`\`
 
-   If status reports \`actionContext.mode: "workspace-planning"\`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
-
 3. **Find delta specs**
 
    Use \`artifactPaths.specs.existingOutputPaths\` from the status JSON as the list of delta spec files.
@@ -153,6 +154,8 @@ export function getOpsxSyncCommandTemplate() {
 
 This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
 
+${STORE_SELECTION_GUIDANCE}
+
 **Input**: Optionally specify a change name after \`/opsx:sync\` (e.g., \`/opsx:sync add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
 **Steps**
@@ -172,8 +175,6 @@ This is an **agent-driven** operation - you will read delta specs and directly e
    openspec status --change "<name>" --json
    \`\`\`
 
-   If status reports \`actionContext.mode: "workspace-planning"\`, explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.
-
 3. **Find delta specs**
 
    Use \`artifactPaths.specs.existingOutputPaths\` from the status JSON as the list of delta spec files.