@fission-ai/openspec 1.7.0 → 1.8.0

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

@@ -9,6 +9,8 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 ${STORE_SELECTION_GUIDANCE}
 
+\`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve the full path from each delta spec when resolving its main spec.
+
 **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**
@@ -42,8 +44,10 @@ ${STORE_SELECTION_GUIDANCE}
    instructions or writing a main spec.
 
    Sync every path in \`existingOutputPaths\` unless the caller narrowed the set.
-   A caller narrows it by naming an explicit list of delta spec paths to sync —
-   archive does this inline, and a user can too ("only sync the billing delta").
+   A caller narrows it by naming an explicit list of complete entries from
+   \`existingOutputPaths\` — copy those absolute values verbatim. Archive does
+   this inline, and a user can too (for example, by selecting the entry ending
+   in \`/specs/billing/invoices/spec.md\`).
    Then sync only the named paths and leave the remaining delta specs untouched:
    bulk archive excludes a delta whose implementation it could not find, and
    syncing it anyway would write a main spec the caller deliberately withheld.
@@ -83,7 +87,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    a. **Read the delta spec** to understand the intended changes
 
-   b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability>/spec.md\` (may not exist yet)
+   b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` (may not exist yet)
 
    c. **Apply changes intelligently**:
 
@@ -94,13 +98,35 @@ ${STORE_SELECTION_GUIDANCE}
       **MODIFIED Requirements:**
       - Find the requirement in main spec
       - Apply the changes - this can be:
-        - Adding new scenarios (don't need to copy existing ones)
+        - Adding new scenarios the main spec does not have yet
         - Modifying existing scenarios
         - Changing the requirement description
       - Preserve scenarios/content not mentioned in the delta
 
       **REMOVED Requirements:**
       - Remove the entire requirement block from main spec
+      - Retiring the capability. Delete the whole \`spec.md\` - and the directory once
+        nothing else is left in it - only when ALL of these hold:
+        1. removing the requirements *this run* left no requirement blocks;
+        2. the rest of the spec is well-formed (it still has a \`## Purpose\`);
+        3. the main spec was not already empty before this sync - if you removed
+           nothing, change nothing;
+        4. every other nonblank line in the whole file is accounted for as the
+           title, Purpose, Requirements header, or a canonical requirement's
+           statement, scenarios, or fenced examples;
+        5. the change's \`.openspec.yaml\` declares \`retire_capabilities: true\`;
+        6. the \`spec.md\` resolves inside the real specs root (do not follow a
+           capability-directory symlink to delete an external file).
+        If removing the selected requirements would leave no requirement blocks and
+        any retirement condition is not satisfied, do not modify the main spec. Stop
+        the sync for that capability, report the blocking condition, and tell the user
+        how to resolve it. Never write or leave an empty \`## Requirements\` section.
+        When only the marker is missing, say that too - it is the one thing the user
+        can add to make the retirement go through.
+      - Deleting the file also deletes its \`## Purpose\`; any other section blocks
+        retirement. Name Purpose when you report the retirement. Include a pasteable
+        \`git checkout\` only when the spec lived in the caller's checkout;
+        otherwise give checkout-scoped recovery guidance.
 
       **RENAMED Requirements:**
       - Find the FROM requirement, rename to TO
@@ -110,19 +136,26 @@ ${STORE_SELECTION_GUIDANCE}
         (this is what \`openspec archive\` does; it warns and moves on)
 
    d. **Create new main spec** if capability doesn't exist yet:
-      - Create \`<planningHome.root>/openspec/specs/<capability>/spec.md\`
+      - Create \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`
       - Add Purpose section: copy the delta's \`## Purpose\` body verbatim when it has one
         (this is what \`openspec archive\` does); only write a brief TBD placeholder when it does not
       - Add Requirements section with the ADDED requirements
       - Follow the **Main Spec Format Reference** below
 
-5. **Show summary**
+5. **Validate updated main specs**
+
+   Run \`openspec validate --specs\` with the same selected-root flags used earlier.
+   If validation fails, report the problems and do not claim the sync succeeded.
+
+6. **Show summary**
 
    After applying all changes, summarize:
    - Which capabilities were updated
    - What changes were made (requirements added/modified/removed/renamed)
    - Any new main spec left with a TBD Purpose placeholder, so it gets written
      now rather than lingering
+   - Any capability retired, naming the deleted \`spec.md\`, its Purpose, and
+     either a pasteable \`git checkout\` or checkout-scoped recovery guidance
 
 **Delta Spec Format Reference**
 
@@ -143,6 +176,12 @@ The system SHALL do something new.
 ## MODIFIED Requirements
 
 ### Requirement: Existing Feature
+The system SHALL keep doing the existing thing, now also handling A.
+
+#### Scenario: Scenario the main spec already has
+- **WHEN** user does X
+- **THEN** system does Y
+
 #### Scenario: New scenario to add
 - **WHEN** user does A
 - **THEN** system does B
@@ -179,9 +218,9 @@ The system SHALL do something new.
 
 **Key Principle: Intelligent Merging**
 
-Unlike programmatic merging, you can apply **partial updates**:
-- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
-- The delta represents *intent*, not a wholesale replacement
+Unlike programmatic merging, you merge rather than overwrite:
+- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. \`openspec validate\` and \`openspec archive\` both reject one that drops a scenario the main spec still has.
+- Keep anything the delta does not mention, in the main spec's existing order
 - Use your judgment to merge changes sensibly
 
 **Output On Success**
@@ -231,6 +270,8 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 ${STORE_SELECTION_GUIDANCE}
 
+\`<capability-path>\` is the spec directory relative to \`specs/\` (for example, \`user-auth\` or \`identity/user-auth\`). Preserve the full path from each delta spec when resolving its main spec.
+
 **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**
@@ -264,8 +305,10 @@ ${STORE_SELECTION_GUIDANCE}
    instructions or writing a main spec.
 
    Sync every path in \`existingOutputPaths\` unless the caller narrowed the set.
-   A caller narrows it by naming an explicit list of delta spec paths to sync —
-   archive does this inline, and a user can too ("only sync the billing delta").
+   A caller narrows it by naming an explicit list of complete entries from
+   \`existingOutputPaths\` — copy those absolute values verbatim. Archive does
+   this inline, and a user can too (for example, by selecting the entry ending
+   in \`/specs/billing/invoices/spec.md\`).
    Then sync only the named paths and leave the remaining delta specs untouched:
    bulk archive excludes a delta whose implementation it could not find, and
    syncing it anyway would write a main spec the caller deliberately withheld.
@@ -305,7 +348,7 @@ ${STORE_SELECTION_GUIDANCE}
 
    a. **Read the delta spec** to understand the intended changes
 
-   b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability>/spec.md\` (may not exist yet)
+   b. **Read the main spec** at \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\` (may not exist yet)
 
    c. **Apply changes intelligently**:
 
@@ -316,13 +359,35 @@ ${STORE_SELECTION_GUIDANCE}
       **MODIFIED Requirements:**
       - Find the requirement in main spec
       - Apply the changes - this can be:
-        - Adding new scenarios (don't need to copy existing ones)
+        - Adding new scenarios the main spec does not have yet
         - Modifying existing scenarios
         - Changing the requirement description
       - Preserve scenarios/content not mentioned in the delta
 
       **REMOVED Requirements:**
       - Remove the entire requirement block from main spec
+      - Retiring the capability. Delete the whole \`spec.md\` - and the directory once
+        nothing else is left in it - only when ALL of these hold:
+        1. removing the requirements *this run* left no requirement blocks;
+        2. the rest of the spec is well-formed (it still has a \`## Purpose\`);
+        3. the main spec was not already empty before this sync - if you removed
+           nothing, change nothing;
+        4. every other nonblank line in the whole file is accounted for as the
+           title, Purpose, Requirements header, or a canonical requirement's
+           statement, scenarios, or fenced examples;
+        5. the change's \`.openspec.yaml\` declares \`retire_capabilities: true\`;
+        6. the \`spec.md\` resolves inside the real specs root (do not follow a
+           capability-directory symlink to delete an external file).
+        If removing the selected requirements would leave no requirement blocks and
+        any retirement condition is not satisfied, do not modify the main spec. Stop
+        the sync for that capability, report the blocking condition, and tell the user
+        how to resolve it. Never write or leave an empty \`## Requirements\` section.
+        When only the marker is missing, say that too - it is the one thing the user
+        can add to make the retirement go through.
+      - Deleting the file also deletes its \`## Purpose\`; any other section blocks
+        retirement. Name Purpose when you report the retirement. Include a pasteable
+        \`git checkout\` only when the spec lived in the caller's checkout;
+        otherwise give checkout-scoped recovery guidance.
 
       **RENAMED Requirements:**
       - Find the FROM requirement, rename to TO
@@ -332,19 +397,26 @@ ${STORE_SELECTION_GUIDANCE}
         (this is what \`openspec archive\` does; it warns and moves on)
 
    d. **Create new main spec** if capability doesn't exist yet:
-      - Create \`<planningHome.root>/openspec/specs/<capability>/spec.md\`
+      - Create \`<planningHome.root>/openspec/specs/<capability-path>/spec.md\`
       - Add Purpose section: copy the delta's \`## Purpose\` body verbatim when it has one
         (this is what \`openspec archive\` does); only write a brief TBD placeholder when it does not
       - Add Requirements section with the ADDED requirements
       - Follow the **Main Spec Format Reference** below
 
-5. **Show summary**
+5. **Validate updated main specs**
+
+   Run \`openspec validate --specs\` with the same selected-root flags used earlier.
+   If validation fails, report the problems and do not claim the sync succeeded.
+
+6. **Show summary**
 
    After applying all changes, summarize:
    - Which capabilities were updated
    - What changes were made (requirements added/modified/removed/renamed)
    - Any new main spec left with a TBD Purpose placeholder, so it gets written
      now rather than lingering
+   - Any capability retired, naming the deleted \`spec.md\`, its Purpose, and
+     either a pasteable \`git checkout\` or checkout-scoped recovery guidance
 
 **Delta Spec Format Reference**
 
@@ -365,6 +437,12 @@ The system SHALL do something new.
 ## MODIFIED Requirements
 
 ### Requirement: Existing Feature
+The system SHALL keep doing the existing thing, now also handling A.
+
+#### Scenario: Scenario the main spec already has
+- **WHEN** user does X
+- **THEN** system does Y
+
 #### Scenario: New scenario to add
 - **WHEN** user does A
 - **THEN** system does B
@@ -401,9 +479,9 @@ The system SHALL do something new.
 
 **Key Principle: Intelligent Merging**
 
-Unlike programmatic merging, you can apply **partial updates**:
-- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
-- The delta represents *intent*, not a wholesale replacement
+Unlike programmatic merging, you merge rather than overwrite:
+- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. \`openspec validate\` and \`openspec archive\` both reject one that drops a scenario the main spec still has.
+- Keep anything the delta does not mention, in the main spec's existing order
 - Use your judgment to merge changes sensibly
 
 **Output On Success**

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

@@ -9,6 +9,8 @@ ${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.
 
+\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+
 **Steps**
 
 1. **Select the change**
@@ -35,7 +37,7 @@ ${STORE_SELECTION_GUIDANCE}
    Parse the JSON to understand current state. The response includes:
    - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
    - \`artifacts\`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
-   - \`isComplete\`: Boolean indicating if all artifacts are complete
+   - \`isPlanningComplete\`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as \`isComplete\`.
    - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
@@ -58,7 +60,7 @@ ${STORE_SELECTION_GUIDANCE}
    - If the user rejects a revision, do not write it - leave that artifact unchanged.
    - When a substantial rewrite is needed, get that artifact's rules and template first:
      \`\`\`bash
-     openspec instructions <artifact-id> --change "<name>" --json
+     openspec instructions "<artifact-id>" --change "<name>" --json
      \`\`\`
 
 6. **Point to the next step (guidance only - NEVER act on it)**
@@ -79,8 +81,7 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).
-- \`/opsx:continue\` and \`/opsx:new\` may not be installed (core profile). When suggesting one that is unavailable, point to the CLI instead: \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions <artifact-id> --change "<name>" --json\` explains how to create it.`,
+- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -98,6 +99,8 @@ ${STORE_SELECTION_GUIDANCE}
 
 **Input**: Optionally specify a change name after \`/opsx:update\` (e.g., \`/opsx:update add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
+\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
+
 **Steps**
 
 1. **Select the change**
@@ -124,7 +127,7 @@ ${STORE_SELECTION_GUIDANCE}
    Parse the JSON to understand current state. The response includes:
    - \`schemaName\`: The workflow schema being used (e.g., "spec-driven")
    - \`artifacts\`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
-   - \`isComplete\`: Boolean indicating if all artifacts are complete
+   - \`isPlanningComplete\`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as \`isComplete\`.
    - \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`actionContext\`: path and scope context. Use these instead of assuming repo-local paths.
 
    The artifact ids and paths come from the active schema - do NOT assume them, and do NOT branch on hardcoded artifact names. Custom schemas must work unchanged.
@@ -147,7 +150,7 @@ ${STORE_SELECTION_GUIDANCE}
    - If the user rejects a revision, do not write it - leave that artifact unchanged.
    - When a substantial rewrite is needed, get that artifact's rules and template first:
      \`\`\`bash
-     openspec instructions <artifact-id> --change "<name>" --json
+     openspec instructions "<artifact-id>" --change "<name>" --json
      \`\`\`
 
 6. **Point to the next step (guidance only - NEVER act on it)**
@@ -168,8 +171,7 @@ After each invocation, show:
 - Edit only the concrete files in \`existingOutputPaths\`; never write to a glob \`resolvedOutputPath\`.
 - Do not advance the build frontier: no new artifacts, no new files under glob artifacts - that is \`/opsx:continue\`'s job.
 - Confirm every edit with the user before writing.
-- If the request changes the change's *intent* rather than refining it, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic).
-- \`/opsx:continue\` and \`/opsx:new\` may not be installed (core profile). When suggesting one that is unavailable, point to the CLI instead: \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions <artifact-id> --change "<name>" --json\` explains how to create it.`
+- If the request changes the change's *intent* rather than refining it, first verify whether the expanded-profile \`/opsx:new\` workflow is available. If it is, recommend starting fresh with \`/opsx:new\` (the "Update vs. Start Fresh" heuristic). If it is unavailable, ask for a distinct unused change name and recommend \`openspec new change "<new-change-name>"\` instead.`
     };
 }
 //# sourceMappingURL=update-change.js.map

package/dist/core/update.d.ts

@@ -28,6 +28,7 @@ export declare class UpdateCommand {
      * @param projectPath - Path to the project root containing the openspec directory
      */
     execute(projectPath: string): Promise<void>;
+    private syncCopilotCloudFiles;
     /**
      * Display message when all tools are up to date.
      */

package/dist/core/update.js

@@ -13,7 +13,7 @@ import { FileSystemUtils } from '../utils/file-system.js';
 import { getSkillReferenceTransformer, getTransformerForTool, transformToSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
-import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, } from './shared/index.js';
+import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, hasGlobalSkillTarget, resolveToolSkillsDir, toolSupportsSkills, } from './shared/index.js';
 import { detectLegacyArtifacts, cleanupLegacyArtifacts, formatDeferredGlobalPromptSummary, formatCleanupSummary, formatDetectionSummary, getLegacyGlobalPromptMatches, getLegacyWorkflowIdsForTool, getToolsFromLegacyArtifacts, omitGlobalLegacyPromptFiles, pickGlobalLegacyPromptFiles, } from './legacy-cleanup.js';
 import { isInteractive } from '../utils/interactive.js';
 import { getGlobalConfig } from './global-config.js';
@@ -23,6 +23,8 @@ import { getAvailableTools } from './available-tools.js';
 import { WORKFLOW_TO_SKILL_DIR, getConfiguredToolsForProfileSync, getToolsNeedingProfileSync, } from './profile-sync-drift.js';
 import { scanInstalledWorkflows as scanInstalledWorkflowsShared, migrateIfNeeded as migrateIfNeededShared, findLegacyToolMigrations, migrateLegacyToolDirs, describeLegacyMigration, legacyMigrationNotice, keptInPlaceNotice, hasMovableContent, } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
+import { writeSharedSkillTarget } from './shared-skill-target.js';
+import { includesGitHubCopilot, writeCopilotCloudFiles, removeCopilotCloudFiles, isCopilotCloudEnabled, readCopilotCloudOptIn, findUnmanagedCloudFiles } from './github-copilot/cloud-agent.js';
 const require = createRequire(import.meta.url);
 const { version: OPENSPEC_VERSION } = require('../../package.json');
 /**
@@ -80,6 +82,7 @@ export class UpdateCommand {
         const { newlyConfiguredTools, workflowOverrides: legacyWorkflowOverrides, deferredGlobalCleanup, } = legacyUpgrade;
         // 5. Find configured tools
         const configuredTools = getConfiguredToolsForProfileSync(resolvedProjectPath);
+        const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
         if (configuredTools.length === 0 && newlyConfiguredTools.length === 0) {
             if (deferredGlobalCleanup) {
                 await this.performDeferredGlobalPromptCleanup(resolvedProjectPath, deferredGlobalCleanup);
@@ -94,6 +97,7 @@ export class UpdateCommand {
                 }
                 return;
             }
+            await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
             console.log(chalk.yellow('No configured tools found.'));
             console.log(chalk.dim('Run "openspec init" to set up tools.'));
             return;
@@ -107,7 +111,13 @@ export class UpdateCommand {
         const statusByTool = new Map(toolStatuses.map((status) => [status.toolId, status]));
         // 7. Smart update detection
         const toolsNeedingVersionUpdate = toolStatuses
-            .filter((s) => s.needsUpdate)
+            .filter((s) => {
+            if (!s.needsUpdate || delivery !== 'commands') {
+                return s.needsUpdate;
+            }
+            const tool = AI_TOOLS.find((candidate) => candidate.value === s.toolId);
+            return !tool || !hasGlobalSkillTarget(tool);
+        })
             .map((s) => s.toolId);
         const toolsNeedingConfigSync = getToolsNeedingProfileSync(resolvedProjectPath, desiredWorkflows, delivery, configuredTools);
         const toolsToUpdateSet = new Set([
@@ -121,6 +131,7 @@ export class UpdateCommand {
             }
             // All tools are up to date
             this.displayUpToDateMessage(toolStatuses);
+            await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
             // Still check for new tool directories and extra workflows
             this.detectNewTools(resolvedProjectPath, configuredTools);
             this.displayExtraWorkflowsNote(resolvedProjectPath, configuredTools, desiredWorkflows);
@@ -153,11 +164,12 @@ export class UpdateCommand {
         let removedDeselectedSkillCount = 0;
         for (const toolId of toolsToUpdate) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
-            if (!tool?.skillsDir)
+            if (!tool || !toolSupportsSkills(tool))
                 continue;
             const spinner = ora(`Updating ${tool.name}...`).start();
             try {
-                const skillsDir = path.join(resolvedProjectPath, tool.skillsDir, 'skills');
+                const skillsDir = resolveToolSkillsDir(resolvedProjectPath, tool);
+                const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : resolvedProjectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
                 const toolWorkflows = legacyWorkflowOverrides[tool.value] ?? desiredWorkflows;
@@ -170,13 +182,18 @@ export class UpdateCommand {
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
-                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsDir, toolWorkflows);
+                    writeSharedSkillTarget(resolvedProjectPath, tool.value);
+                    removedDeselectedSkillCount += await this.removeUnselectedSkillDirs(skillsRoot, skillsDir, toolWorkflows);
                 }
                 // Delete skill directories if delivery is commands-only
-                if (shouldRemoveSkillsForTool(tool.value, delivery)) {
-                    removedSkillCount += await this.removeSkillDirs(skillsDir);
+                if (shouldRemoveSkillsForTool(tool.value, delivery) && !hasGlobalSkillTarget(tool)) {
+                    removedSkillCount += await this.removeSkillDirs(skillsRoot, skillsDir);
+                    // Persist the selected owner even when commands-only delivery leaves
+                    // this target with no generated skills.
+                    writeSharedSkillTarget(resolvedProjectPath, tool.value);
                     // A tool with no command adapter now has zero OpenSpec artifacts;
                     // say so like init does, rather than deleting its skills silently
                     // and letting tool detection re-suggest an init that would also
@@ -191,7 +208,7 @@ export class UpdateCommand {
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
-                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(resolvedProjectPath, cmd.path);
+                            const commandFile = FileSystemUtils.resolveProjectArtifactPath(resolvedProjectPath, cmd.path);
                             await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
                         }
                         removedDeselectedCommandCount += await this.removeUnselectedCommandFiles(resolvedProjectPath, toolId, toolWorkflows);
@@ -206,6 +223,12 @@ export class UpdateCommand {
                 }
                 spinner.succeed(`Updated ${tool.name}`);
                 updatedTools.push(tool.name);
+                for (const migration of migrateLegacyToolDirs(resolvedProjectPath, [tool.value], 'after-generation')) {
+                    if (hasMovableContent(migration)) {
+                        console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                    }
+                    this.reportKeptInPlace(migration);
+                }
             }
             catch (error) {
                 spinner.fail(`Failed to update ${tool.name}`);
@@ -282,7 +305,7 @@ export class UpdateCommand {
             }
             console.log(`Learn more: ${chalk.cyan('https://github.com/Fission-AI/OpenSpec')}`);
         }
-        const configuredAndNewTools = [...new Set([...configuredTools, ...newlyConfiguredTools])];
+        await this.syncCopilotCloudFiles(resolvedProjectPath, configuredAndNewTools);
         // 13. Detect new tool directories not currently configured
         this.detectNewTools(resolvedProjectPath, configuredAndNewTools);
         // 14. Display note about extra workflows not in profile
@@ -296,6 +319,51 @@ export class UpdateCommand {
         }
         console.log();
         console.log(chalk.dim('Restart your IDE for changes to take effect.'));
+        if (failedTools.length > 0) {
+            throw new Error(`OpenSpec update failed for: ${failedTools.map((tool) => tool.name).join(', ')}`);
+        }
+    }
+    async syncCopilotCloudFiles(projectPath, configuredTools) {
+        try {
+            if (includesGitHubCopilot(configuredTools)) {
+                // Cloud files are opt-in (see cloud-agent.ts). `update` never prompts,
+                // so it only refreshes files the user has already opted into (via
+                // `openspec init` or a `githubCopilot.cloudAgent: true` config), or that
+                // a pre-opt-in project already has. Opting in is a deliberate init/config
+                // step, never a silent side effect of running update.
+                if (await isCopilotCloudEnabled(projectPath)) {
+                    await writeCopilotCloudFiles(projectPath);
+                    const collisions = await findUnmanagedCloudFiles(projectPath);
+                    if (collisions.length > 0) {
+                        console.log(chalk.dim(`Left your existing ${collisions.join(' and ')} untouched — add the OpenSpec ` +
+                            `install step by hand so the Copilot cloud agent can run openspec.`));
+                    }
+                    return;
+                }
+                // Explicit opt-out (githubCopilot.cloudAgent: false) means "not here":
+                // remove any managed files a prior opt-in left behind (customized files
+                // are preserved). If the user simply never decided, stay quiet unless
+                // we're at an interactive terminal, where a one-line hint aids discovery.
+                if (readCopilotCloudOptIn(projectPath) === false) {
+                    const removed = await removeCopilotCloudFiles(projectPath);
+                    if (removed > 0) {
+                        console.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (opted out of cloud files)`));
+                    }
+                }
+                else if (isInteractive()) {
+                    console.log(chalk.dim("GitHub Copilot cloud coding-agent files are available (opt-in). Enable with 'openspec init --copilot-cloud'."));
+                }
+                return;
+            }
+            const removed = await removeCopilotCloudFiles(projectPath);
+            if (removed > 0) {
+                console.log(chalk.dim(`Removed: ${removed} Copilot cloud agent file(s) (github-copilot not configured)`));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Warning: failed to sync Copilot cloud agent files: ${message}`);
+        }
     }
     /**
      * Display message when all tools are up to date.
@@ -387,18 +455,19 @@ export class UpdateCommand {
      * Removes skill directories for workflows when delivery changed to commands-only.
      * Returns the number of directories removed.
      */
-    async removeSkillDirs(skillsDir) {
+    async removeSkillDirs(skillsRoot, skillsDir) {
         let removed = 0;
         for (const workflow of ALL_WORKFLOWS) {
             const dirName = WORKFLOW_TO_SKILL_DIR[workflow];
             if (!dirName)
                 continue;
             const skillDir = path.join(skillsDir, dirName);
+            if (!fs.existsSync(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                if (fs.existsSync(skillDir)) {
-                    await fs.promises.rm(skillDir, { recursive: true, force: true });
-                    removed++;
-                }
+                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                removed++;
             }
             catch {
                 // Ignore errors
@@ -410,7 +479,7 @@ export class UpdateCommand {
      * Removes skill directories for workflows that are no longer selected in the active profile.
      * Returns the number of directories removed.
      */
-    async removeUnselectedSkillDirs(skillsDir, desiredWorkflows) {
+    async removeUnselectedSkillDirs(skillsRoot, skillsDir, desiredWorkflows) {
         const desiredSet = new Set(desiredWorkflows);
         let removed = 0;
         for (const workflow of ALL_WORKFLOWS) {
@@ -420,11 +489,12 @@ export class UpdateCommand {
             if (!dirName)
                 continue;
             const skillDir = path.join(skillsDir, dirName);
+            if (!fs.existsSync(skillDir))
+                continue;
+            FileSystemUtils.assertPathWithin(skillsRoot, skillDir);
             try {
-                if (fs.existsSync(skillDir)) {
-                    await fs.promises.rm(skillDir, { recursive: true, force: true });
-                    removed++;
-                }
+                await fs.promises.rm(skillDir, { recursive: true, force: true });
+                removed++;
             }
             catch {
                 // Ignore errors
@@ -443,7 +513,7 @@ export class UpdateCommand {
             return 0;
         for (const workflow of ALL_WORKFLOWS) {
             const cmdPath = adapter.getFilePath(workflow);
-            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
                 if (fs.existsSync(fullPath)) {
                     await fs.promises.unlink(fullPath);
@@ -470,7 +540,7 @@ export class UpdateCommand {
             if (desiredSet.has(workflow))
                 continue;
             const cmdPath = adapter.getFilePath(workflow);
-            const fullPath = path.isAbsolute(cmdPath) ? cmdPath : path.join(projectPath, cmdPath);
+            const fullPath = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmdPath);
             try {
                 if (fs.existsSync(fullPath)) {
                     await fs.promises.unlink(fullPath);
@@ -721,11 +791,12 @@ export class UpdateCommand {
         const workflowOverrides = {};
         for (const toolId of selectedTools) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
-            if (!tool?.skillsDir)
+            if (!tool || !toolSupportsSkills(tool))
                 continue;
             const spinner = ora(`Setting up ${tool.name}...`).start();
             try {
-                const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
+                const skillsDir = resolveToolSkillsDir(projectPath, tool);
+                const skillsRoot = hasGlobalSkillTarget(tool) ? skillsDir : projectPath;
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
                 const toolWorkflows = (tool.value === 'codex' && inferredCodexWorkflows.length > 0
@@ -743,8 +814,10 @@ export class UpdateCommand {
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         const transformer = getTransformerForTool(tool.value, delivery, resolveCommandSurfaceCapability(tool.value), resolveCommandInvocation(tool.value));
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
+                        FileSystemUtils.assertPathWithin(skillsRoot, skillFile);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
+                    writeSharedSkillTarget(projectPath, tool.value);
                 }
                 // Create commands when delivery includes commands
                 if (shouldGenerateCommands) {
@@ -752,13 +825,19 @@ export class UpdateCommand {
                     if (adapter) {
                         const generatedCommands = generateCommands(commandContents, adapter);
                         for (const cmd of generatedCommands) {
-                            const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectPath, cmd.path);
+                            const commandFile = FileSystemUtils.resolveProjectArtifactPath(projectPath, cmd.path);
                             await FileSystemUtils.writeFile(commandFile, cmd.fileContent);
                         }
                     }
                 }
                 spinner.succeed(`Setup complete for ${tool.name}`);
                 newlyConfigured.push(toolId);
+                for (const migration of migrateLegacyToolDirs(projectPath, [tool.value], 'after-generation')) {
+                    if (hasMovableContent(migration)) {
+                        console.log(chalk.dim(`Migrated ${describeLegacyMigration(migration)}: ${migration.from} → ${migration.to}`));
+                    }
+                    this.reportKeptInPlace(migration);
+                }
             }
             catch (error) {
                 spinner.fail(`Failed to set up ${tool.name}`);