fix: use correct scoped package name in changeset

* feat: add Amazon Q Developer CLI integration

- Add AmazonQSlashCommandConfigurator for .amazonq/prompts/ support
- Register Amazon Q in SlashCommandRegistry and AI_TOOLS config
- Generate slash commands compatible with Amazon Q CLI (@-syntax)
- Update README.md with Amazon Q Developer in tools table

* test: add Amazon Q Developer integration tests

- Add init tests for Amazon Q prompt file creation and configuration detection
- Add update tests for Amazon Q prompt refresh and missing file handling
- Follow same test patterns as GitHub Copilot integration
- Verify .amazonq/prompts/ directory structure and file content

---------

Co-authored-by: Brian Anderson <brian@popsofviolet.com>

.changeset/amazon-q-integration.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": minor
+---
+
+Add Amazon Q Developer CLI integration. OpenSpec now supports Amazon Q Developer with automatic prompt generation in `.amazonq/prompts/` directory, allowing you to use OpenSpec slash commands with Amazon Q's @-syntax.

CHANGELOG.md

@@ -1,5 +1,29 @@
 # @fission-ai/openspec
 
+## 0.10.0
+
+### Minor Changes
+
+- d7e0ce8: Improve init wizard Enter key behavior to allow proceeding through prompts more naturally
+
+## 0.9.2
+
+### Patch Changes
+
+- 2ae0484: Fix cross-platform path handling issues. This release includes fixes for joinPath behavior and slash command path resolution to ensure OpenSpec works correctly across all platforms.
+
+## 0.9.1
+
+### Patch Changes
+
+- 8210970: Fix OpenSpec not working on Windows when Codex integration is selected. This release includes fixes for cross-platform path handling and normalization to ensure OpenSpec works correctly on Windows systems.
+
+## 0.9.0
+
+### Minor Changes
+
+- efbbf3b: Add support for Codex and GitHub Copilot slash commands with YAML frontmatter and $ARGUMENTS
+
 ## Unreleased
 
 ### Minor Changes

README.md

@@ -97,6 +97,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
 | **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
 | **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
+| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
 
 Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
 

openspec/changes/add-codex-slash-command-support/proposal.md

@@ -1,13 +1,13 @@
 ## Why
-- Codex (the VS Code extension formerly known as Codeium Chat) exposes "slash commands" by reading Markdown prompt files from `~/.codex/prompts/`. Each file name becomes the `/command` users can run, with numbered placeholders (`$1`, `$2`, …) bound to the arguments they supply. The workflow screenshot shared by Kevin Kern ("Codex problem analyzer") shows the format OpenSpec should target so teams can invoke curated workflows straight from the chat palette.
+- Codex (the VS Code extension formerly known as Codeium Chat) exposes "slash commands" by reading Markdown prompt files from `~/.codex/prompts/`. Each file name becomes the `/command` users can run, with YAML frontmatter for metadata (`description`, `argument-hint`) and `$ARGUMENTS` to capture user input. The workflow screenshot shared by Kevin Kern ("Codex problem analyzer") shows the format OpenSpec should target so teams can invoke curated workflows straight from the chat palette.
 - Teams already rely on OpenSpec to manage the slash-command surface area for Claude, Cursor, OpenCode, Kilo Code, and Windsurf. Leaving Codex out forces them to manually copy/paste OpenSpec guardrails into `~/.codex/prompts/*.md`, which drifts quickly and undermines the "single source of truth" promise of the CLI.
 - Codex commands live outside the repository (under the user's home directory), so shipping an automated configurator that both scaffolds the prompts and keeps them refreshed via `openspec update` eliminates error-prone manual steps and keeps OpenSpec instructions synchronized across assistants.
 
 ## What Changes
 - Add Codex to the `openspec init` tool picker with the same "already configured" detection we use for other editors, wiring an implementation that writes managed Markdown prompts directly to Codex's global directory (`~/.codex/prompts` or `$CODEX_HOME/prompts`) with OpenSpec marker blocks.
-- Produce three Codex prompt files—`openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`—whose content mirrors the shared slash-command templates while adapting to Codex's numbered argument placeholders (e.g., `$1` for the change identifier or follow-up question text).
+- Produce three Codex prompt files—`openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`—whose content mirrors the shared slash-command templates while using YAML frontmatter (`description` and `argument-hint` fields) and `$ARGUMENTS` to capture all arguments as a single string (matching the GitHub Copilot pattern and official Codex specification).
 - Document Codex's global-only discovery and that OpenSpec writes prompts directly to `~/.codex/prompts` (or `$CODEX_HOME/prompts`).
-- Teach `openspec update` to refresh existing Codex prompts in-place (and only when they already exist) in the global directory.
+- Teach `openspec update` to refresh existing Codex prompts in-place (and only when they already exist) in the global directory, updating both frontmatter and body.
 - Document Codex support alongside other slash-command integrations and add regression coverage that exercises init/update behaviour against a temporary global prompts directory via `CODEX_HOME`.
 
 ## Impact

openspec/changes/update-cli-init-enter-selection/proposal.md

@@ -0,0 +1,14 @@
+## Why
+- Users frequently scroll to a tool and press Enter without toggling it, resulting in no configuration changes.
+- The current workflow deviates from common CLI expectations where Enter confirms the highlighted item.
+- Aligning behavior with user expectations reduces friction during onboarding.
+
+## What Changes
+- Update the init wizard so pressing Enter on a highlighted tool selects it before moving to the review step.
+- Adjust interactive instructions to clarify Enter selects the current tool and Space still toggles selections.
+- Refresh specs to capture the clarified behavior for the interactive menu.
+
+## Impact
+- Users who press Enter without toggling now configure the highlighted tool instead of exiting with no selections.
+- Spacebar multi-select support remains unchanged for power users.
+- Documentation better reflects how the wizard behaves.

openspec/changes/update-cli-init-enter-selection/specs/cli-init/spec.md

@@ -0,0 +1,10 @@
+## MODIFIED Requirements
+### Requirement: Interactive Mode
+The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
+#### Scenario: Displaying interactive menu
+- **WHEN** run in fresh or extend mode
+- **THEN** present a looping select menu that lets users toggle tools with Space and review selections with Enter
+- **AND** when Enter is pressed on a highlighted selectable tool that is not already selected, automatically add it to the selection before moving to review so the highlighted tool is configured
+- **AND** label already configured tools with "(already configured)" while keeping disabled options marked "coming soon"
+- **AND** change the prompt copy in extend mode to "Which AI tools would you like to add or refresh?"
+- **AND** display inline instructions clarifying that Space toggles tools and Enter selects the highlighted tool before reviewing selections

openspec/changes/update-cli-init-enter-selection/tasks.md

@@ -0,0 +1,8 @@
+## 1. Implementation
+- [x] Update the tool selection wizard to auto-select the highlighted tool when Enter is pressed without prior toggles.
+- [x] Refresh inline instructions copy so Enter behavior is clear.
+- [x] Adjust or add tests if needed to cover the new selection flow.
+
+## 2. Validation
+- [x] Run `pnpm run build`.
+- [x] Run `pnpm test` (or targeted suite) if applicable.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

src/core/config.ts

@@ -24,5 +24,6 @@ export const AI_TOOLS: AIToolOption[] = [
   { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf' },
   { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex' },
   { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot' },
+  { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer' },
   { name: 'AGENTS.md (works with Amp, VS Code, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
 ];

src/core/configurators/slash/amazon-q.ts

@@ -0,0 +1,51 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+
+const FILE_PATHS: Record<SlashCommandId, string> = {
+  proposal: '.amazonq/prompts/openspec-proposal.md',
+  apply: '.amazonq/prompts/openspec-apply.md',
+  archive: '.amazonq/prompts/openspec-archive.md'
+};
+
+const FRONTMATTER: Record<SlashCommandId, string> = {
+  proposal: `---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+
+The user has requested the following change proposal. Use the openspec instructions to create their change proposal.
+
+<UserRequest>
+  $ARGUMENTS
+</UserRequest>`,
+  apply: `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+
+The user wants to apply the following change. Use the openspec instructions to implement the approved change.
+
+<ChangeId>
+  $ARGUMENTS
+</ChangeId>`,
+  archive: `---
+description: Archive a deployed OpenSpec change and update specs.
+---
+
+The user wants to archive the following deployed change. Use the openspec instructions to archive the change and update specs.
+
+<ChangeId>
+  $ARGUMENTS
+</ChangeId>`
+};
+
+export class AmazonQSlashCommandConfigurator extends SlashCommandConfigurator {
+  readonly toolId = 'amazon-q';
+  readonly isAvailable = true;
+
+  protected getRelativePath(id: SlashCommandId): string {
+    return FILE_PATHS[id];
+  }
+
+  protected getFrontmatter(id: SlashCommandId): string {
+    return FRONTMATTER[id];
+  }
+}

src/core/configurators/slash/base.ts

@@ -1,4 +1,3 @@
-import path from 'path';
 import { FileSystemUtils } from '../../../utils/file-system.js';
 import { TemplateManager, SlashCommandId } from '../../templates/index.js';
 import { OPENSPEC_MARKERS } from '../../config.js';
@@ -28,7 +27,7 @@ export abstract class SlashCommandConfigurator {
 
     for (const target of this.getTargets()) {
       const body = TemplateManager.getSlashCommandBody(target.id).trim();
-      const filePath = path.join(projectPath, target.path);
+      const filePath = FileSystemUtils.joinPath(projectPath, target.path);
 
       if (await FileSystemUtils.fileExists(filePath)) {
         await this.updateBody(filePath, body);
@@ -53,7 +52,7 @@ export abstract class SlashCommandConfigurator {
     const updated: string[] = [];
 
     for (const target of this.getTargets()) {
-      const filePath = path.join(projectPath, target.path);
+      const filePath = FileSystemUtils.joinPath(projectPath, target.path);
       if (await FileSystemUtils.fileExists(filePath)) {
         const body = TemplateManager.getSlashCommandBody(target.id).trim();
         await this.updateBody(filePath, body);
@@ -71,7 +70,7 @@ export abstract class SlashCommandConfigurator {
   // to redirect to tool-specific locations (e.g., global directories).
   resolveAbsolutePath(projectPath: string, id: SlashCommandId): string {
     const rel = this.getRelativePath(id);
-    return path.join(projectPath, rel);
+    return FileSystemUtils.joinPath(projectPath, rel);
   }
 
   protected async updateBody(filePath: string, body: string): Promise<void> {

src/core/configurators/slash/codex.ts

@@ -5,6 +5,7 @@ import { SlashCommandId, TemplateManager } from "../../templates/index.js";
 import { FileSystemUtils } from "../../../utils/file-system.js";
 import { OPENSPEC_MARKERS } from "../../config.js";
 
+// Use POSIX-style paths for consistent logging across platforms.
 const FILE_PATHS: Record<SlashCommandId, string> = {
   proposal: ".codex/prompts/openspec-proposal.md",
   apply: ".codex/prompts/openspec-apply.md",
@@ -20,21 +21,36 @@ export class CodexSlashCommandConfigurator extends SlashCommandConfigurator {
   }
 
   protected getFrontmatter(id: SlashCommandId): string | undefined {
-    // Codex does not use YAML front matter. Provide a heading-style
-    // preface that captures the first numbered placeholder `$1`.
-    const headers: Record<SlashCommandId, string> = {
-      proposal: "Request: $1",
-      apply: "Change ID: $1",
-      archive: "Change ID: $1",
+    // Codex supports YAML frontmatter with description and argument-hint fields,
+    // plus $ARGUMENTS to capture all arguments as a single string.
+    const frontmatter: Record<SlashCommandId, string> = {
+      proposal: `---
+description: Scaffold a new OpenSpec change and validate strictly.
+argument-hint: request or feature description
+---
+
+$ARGUMENTS`,
+      apply: `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+argument-hint: change-id
+---
+
+$ARGUMENTS`,
+      archive: `---
+description: Archive a deployed OpenSpec change and update specs.
+argument-hint: change-id
+---
+
+$ARGUMENTS`,
     };
-    return headers[id];
+    return frontmatter[id];
   }
 
   private getGlobalPromptsDir(): string {
     const home = (process.env.CODEX_HOME && process.env.CODEX_HOME.trim())
       ? process.env.CODEX_HOME.trim()
-      : path.join(os.homedir(), ".codex");
-    return path.join(home, "prompts");
+      : FileSystemUtils.joinPath(os.homedir(), ".codex");
+    return FileSystemUtils.joinPath(home, "prompts");
   }
 
   // Codex discovers prompts globally. Generate directly in the global directory
@@ -44,16 +60,19 @@ export class CodexSlashCommandConfigurator extends SlashCommandConfigurator {
     for (const target of this.getTargets()) {
       const body = TemplateManager.getSlashCommandBody(target.id).trim();
       const promptsDir = this.getGlobalPromptsDir();
-      const filePath = path.join(promptsDir, path.basename(target.path));
+      const filePath = FileSystemUtils.joinPath(
+        promptsDir,
+        path.basename(target.path)
+      );
 
       await FileSystemUtils.createDirectory(path.dirname(filePath));
 
       if (await FileSystemUtils.fileExists(filePath)) {
-        await this.updateBody(filePath, body);
+        await this.updateFullFile(filePath, target.id, body);
       } else {
-        const header = this.getFrontmatter(target.id);
+        const frontmatter = this.getFrontmatter(target.id);
         const sections: string[] = [];
-        if (header) sections.push(header.trim());
+        if (frontmatter) sections.push(frontmatter.trim());
         sections.push(`${OPENSPEC_MARKERS.start}\n${body}\n${OPENSPEC_MARKERS.end}`);
         await FileSystemUtils.writeFile(filePath, sections.join("\n") + "\n");
       }
@@ -67,20 +86,41 @@ export class CodexSlashCommandConfigurator extends SlashCommandConfigurator {
     const updated: string[] = [];
     for (const target of this.getTargets()) {
       const promptsDir = this.getGlobalPromptsDir();
-      const filePath = path.join(promptsDir, path.basename(target.path));
+      const filePath = FileSystemUtils.joinPath(
+        promptsDir,
+        path.basename(target.path)
+      );
       if (await FileSystemUtils.fileExists(filePath)) {
         const body = TemplateManager.getSlashCommandBody(target.id).trim();
-        await this.updateBody(filePath, body);
+        await this.updateFullFile(filePath, target.id, body);
         updated.push(target.path);
       }
     }
     return updated;
   }
 
+  // Update both frontmatter and body in an existing file
+  private async updateFullFile(filePath: string, id: SlashCommandId, body: string): Promise<void> {
+    const content = await FileSystemUtils.readFile(filePath);
+    const startIndex = content.indexOf(OPENSPEC_MARKERS.start);
+
+    if (startIndex === -1) {
+      throw new Error(`Missing OpenSpec start marker in ${filePath}`);
+    }
+
+    // Replace everything before the start marker with the new frontmatter
+    const frontmatter = this.getFrontmatter(id);
+    const sections: string[] = [];
+    if (frontmatter) sections.push(frontmatter.trim());
+    sections.push(`${OPENSPEC_MARKERS.start}\n${body}\n${OPENSPEC_MARKERS.end}`);
+
+    await FileSystemUtils.writeFile(filePath, sections.join("\n") + "\n");
+  }
+
   // Resolve to the global prompts location for configuration detection
   resolveAbsolutePath(_projectPath: string, id: SlashCommandId): string {
     const promptsDir = this.getGlobalPromptsDir();
     const fileName = path.basename(FILE_PATHS[id]);
-    return path.join(promptsDir, fileName);
+    return FileSystemUtils.joinPath(promptsDir, fileName);
   }
 }

src/core/configurators/slash/registry.ts

@@ -6,6 +6,7 @@ import { KiloCodeSlashCommandConfigurator } from './kilocode.js';
 import { OpenCodeSlashCommandConfigurator } from './opencode.js';
 import { CodexSlashCommandConfigurator } from './codex.js';
 import { GitHubCopilotSlashCommandConfigurator } from './github-copilot.js';
+import { AmazonQSlashCommandConfigurator } from './amazon-q.js';
 
 export class SlashCommandRegistry {
   private static configurators: Map<string, SlashCommandConfigurator> = new Map();
@@ -18,6 +19,7 @@ export class SlashCommandRegistry {
     const opencode = new OpenCodeSlashCommandConfigurator();
     const codex = new CodexSlashCommandConfigurator();
     const githubCopilot = new GitHubCopilotSlashCommandConfigurator();
+    const amazonQ = new AmazonQSlashCommandConfigurator();
 
     this.configurators.set(claude.toolId, claude);
     this.configurators.set(cursor.toolId, cursor);
@@ -26,6 +28,7 @@ export class SlashCommandRegistry {
     this.configurators.set(opencode.toolId, opencode);
     this.configurators.set(codex.toolId, codex);
     this.configurators.set(githubCopilot.toolId, githubCopilot);
+    this.configurators.set(amazonQ.toolId, amazonQ);
   }
 
   static register(configurator: SlashCommandConfigurator): void {

src/core/init.ts

@@ -220,6 +220,16 @@ const toolSelectionWizard = createPrompt<string[], ToolWizardConfig>(
         }
 
         if (isEnterKey(key)) {
+          const current = config.choices[cursor];
+          if (
+            current &&
+            current.selectable &&
+            !selectedSet.has(current.value)
+          ) {
+            const next = new Set(selected);
+            next.add(current.value);
+            updateSelected(next);
+          }
           setStep('review');
           setError(null);
           return;
@@ -298,7 +308,7 @@ const toolSelectionWizard = createPrompt<string[], ToolWizardConfig>(
       lines.push(PALETTE.white(config.baseMessage));
       lines.push(
         PALETTE.midGray(
-          'Use ↑/↓ to move · Space to toggle · Enter to review selections.'
+          'Use ↑/↓ to move · Space to toggle · Enter selects highlighted tool and reviews.'
         )
       );
       lines.push('');

src/core/update.ts

@@ -106,9 +106,9 @@ export class UpdateCommand {
     }
 
     if (updatedSlashFiles.length > 0) {
-      summaryParts.push(
-        `Updated slash commands: ${updatedSlashFiles.join(', ')}`
-      );
+      // Normalize to forward slashes for cross-platform log consistency
+      const normalized = updatedSlashFiles.map((p) => p.replace(/\\/g, '/'));
+      summaryParts.push(`Updated slash commands: ${normalized.join(', ')}`);
     }
 
     const failedItems = [

src/utils/file-system.ts

@@ -42,6 +42,33 @@ function findMarkerIndex(
 }
 
 export class FileSystemUtils {
+  private static isWindowsBasePath(basePath: string): boolean {
+    return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
+  }
+
+  private static normalizeSegments(segments: string[]): string[] {
+    return segments
+      .flatMap((segment) => segment.split(/[\\/]+/u))
+      .filter((part) => part.length > 0);
+  }
+
+  static joinPath(basePath: string, ...segments: string[]): string {
+    const normalizedSegments = this.normalizeSegments(segments);
+
+    if (this.isWindowsBasePath(basePath)) {
+      const normalizedBasePath = path.win32.normalize(basePath);
+      return normalizedSegments.length
+        ? path.win32.join(normalizedBasePath, ...normalizedSegments)
+        : normalizedBasePath;
+    }
+
+    const posixBasePath = basePath.replace(/\\/g, '/');
+
+    return normalizedSegments.length
+      ? path.posix.join(posixBasePath, ...normalizedSegments)
+      : path.posix.normalize(posixBasePath);
+  }
+
   static async createDirectory(dirPath: string): Promise<void> {
     await fs.mkdir(dirPath, { recursive: true });
   }

test/core/init.test.ts

@@ -339,16 +339,22 @@ describe('InitCommand', () => {
       expect(await fileExists(archivePath)).toBe(true);
 
       const proposalContent = await fs.readFile(proposalPath, 'utf-8');
-      expect(proposalContent).toContain('Request: $1');
+      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+      expect(proposalContent).toContain('argument-hint: request or feature description');
+      expect(proposalContent).toContain('$ARGUMENTS');
       expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
       expect(proposalContent).toContain('**Guardrails**');
 
       const applyContent = await fs.readFile(applyPath, 'utf-8');
-      expect(applyContent).toContain('Change ID: $1');
+      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('argument-hint: change-id');
+      expect(applyContent).toContain('$ARGUMENTS');
       expect(applyContent).toContain('Work through tasks sequentially');
 
       const archiveContent = await fs.readFile(archivePath, 'utf-8');
-      expect(archiveContent).toContain('Change ID: $1');
+      expect(archiveContent).toContain('description: Archive a deployed OpenSpec change and update specs.');
+      expect(archiveContent).toContain('argument-hint: change-id');
+      expect(archiveContent).toContain('$ARGUMENTS');
       expect(archiveContent).toContain('openspec archive <id> --yes');
     });
 
@@ -564,6 +570,54 @@ describe('InitCommand', () => {
       );
       expect(githubCopilotChoice.configured).toBe(true);
     });
+
+    it('should create Amazon Q Developer prompt files with templates', async () => {
+      queueSelections('amazon-q', DONE);
+
+      await initCommand.execute(testDir);
+
+      const proposalPath = path.join(
+        testDir,
+        '.amazonq/prompts/openspec-proposal.md'
+      );
+      const applyPath = path.join(
+        testDir,
+        '.amazonq/prompts/openspec-apply.md'
+      );
+      const archivePath = path.join(
+        testDir,
+        '.amazonq/prompts/openspec-archive.md'
+      );
+
+      expect(await fileExists(proposalPath)).toBe(true);
+      expect(await fileExists(applyPath)).toBe(true);
+      expect(await fileExists(archivePath)).toBe(true);
+
+      const proposalContent = await fs.readFile(proposalPath, 'utf-8');
+      expect(proposalContent).toContain('---');
+      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
+      expect(proposalContent).toContain('$ARGUMENTS');
+      expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
+      expect(proposalContent).toContain('**Guardrails**');
+
+      const applyContent = await fs.readFile(applyPath, 'utf-8');
+      expect(applyContent).toContain('---');
+      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('$ARGUMENTS');
+      expect(applyContent).toContain('<!-- OPENSPEC:START -->');
+    });
+
+    it('should mark Amazon Q Developer as already configured during extend mode', async () => {
+      queueSelections('amazon-q', DONE, 'amazon-q', DONE);
+      await initCommand.execute(testDir);
+      await initCommand.execute(testDir);
+
+      const secondRunArgs = mockPrompt.mock.calls[1][0];
+      const amazonQChoice = secondRunArgs.choices.find(
+        (choice: any) => choice.value === 'amazon-q'
+      );
+      expect(amazonQChoice.configured).toBe(true);
+    });
   });
 
   describe('error handling', () => {

test/core/update.test.ts

@@ -262,7 +262,7 @@ Old body
       '.codex/prompts/openspec-apply.md'
     );
     await fs.mkdir(path.dirname(codexPath), { recursive: true });
-    const initialContent = `Change ID: $1\n<!-- OPENSPEC:START -->\nOld body\n<!-- OPENSPEC:END -->`;
+    const initialContent = `---\ndescription: Old description\nargument-hint: old-hint\n---\n\n$ARGUMENTS\n<!-- OPENSPEC:START -->\nOld body\n<!-- OPENSPEC:END -->`;
     await fs.writeFile(codexPath, initialContent);
 
     const consoleSpy = vi.spyOn(console, 'log');
@@ -270,9 +270,12 @@ Old body
     await updateCommand.execute(testDir);
 
     const updated = await fs.readFile(codexPath, 'utf-8');
-    expect(updated).toContain('Change ID: $1');
+    expect(updated).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+    expect(updated).toContain('argument-hint: change-id');
+    expect(updated).toContain('$ARGUMENTS');
     expect(updated).toContain('Work through tasks sequentially');
     expect(updated).not.toContain('Old body');
+    expect(updated).not.toContain('Old description');
 
     const [logMessage] = consoleSpy.mock.calls[0];
     expect(logMessage).toContain(
@@ -292,7 +295,7 @@ Old body
     await fs.mkdir(path.dirname(codexApply), { recursive: true });
     await fs.writeFile(
       codexApply,
-      'Change ID: $1\n<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->'
+      '---\ndescription: Old\nargument-hint: old\n---\n\n$ARGUMENTS\n<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->'
     );
 
     await updateCommand.execute(testDir);
@@ -374,6 +377,72 @@ Old body
     await expect(FileSystemUtils.fileExists(ghArchive)).resolves.toBe(false);
   });
 
+  it('should refresh existing Amazon Q Developer prompts', async () => {
+    const aqPath = path.join(
+      testDir,
+      '.amazonq/prompts/openspec-apply.md'
+    );
+    await fs.mkdir(path.dirname(aqPath), { recursive: true });
+    const initialContent = `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+
+The user wants to apply the following change. Use the openspec instructions to implement the approved change.
+
+<ChangeId>
+  $ARGUMENTS
+</ChangeId>
+<!-- OPENSPEC:START -->
+Old body
+<!-- OPENSPEC:END -->`;
+    await fs.writeFile(aqPath, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+
+    await updateCommand.execute(testDir);
+
+    const updatedContent = await fs.readFile(aqPath, 'utf-8');
+    expect(updatedContent).toContain('**Guardrails**');
+    expect(updatedContent).toContain('<!-- OPENSPEC:START -->');
+    expect(updatedContent).toContain('<!-- OPENSPEC:END -->');
+    expect(updatedContent).not.toContain('Old body');
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('.amazonq/prompts/openspec-apply.md')
+    );
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should not create missing Amazon Q Developer prompts on update', async () => {
+    const aqApply = path.join(
+      testDir,
+      '.amazonq/prompts/openspec-apply.md'
+    );
+
+    // Only create apply; leave proposal and archive missing
+    await fs.mkdir(path.dirname(aqApply), { recursive: true });
+    await fs.writeFile(
+      aqApply,
+      '---\ndescription: Old\n---\n\nThe user wants to apply the following change.\n\n<ChangeId>\n  $ARGUMENTS\n</ChangeId>\n<!-- OPENSPEC:START -->\nOld\n<!-- OPENSPEC:END -->'
+    );
+
+    await updateCommand.execute(testDir);
+
+    const aqProposal = path.join(
+      testDir,
+      '.amazonq/prompts/openspec-proposal.md'
+    );
+    const aqArchive = path.join(
+      testDir,
+      '.amazonq/prompts/openspec-archive.md'
+    );
+
+    // Confirm they weren't created by update
+    await expect(FileSystemUtils.fileExists(aqProposal)).resolves.toBe(false);
+    await expect(FileSystemUtils.fileExists(aqArchive)).resolves.toBe(false);
+  });
+
   it('should preserve Windsurf content outside markers during update', async () => {
     const wsPath = path.join(
       testDir,

test/utils/file-system.test.ts

@@ -160,4 +160,52 @@ describe('FileSystemUtils', () => {
       expect(hasPermission).toBe(true);
     });
   });
+
+  describe('joinPath', () => {
+    it('should join POSIX-style paths', () => {
+      const result = FileSystemUtils.joinPath(
+        '/tmp/project',
+        '.claude/commands/openspec/proposal.md'
+      );
+      expect(result).toBe('/tmp/project/.claude/commands/openspec/proposal.md');
+    });
+
+    it('should join Linux home directory paths', () => {
+      const result = FileSystemUtils.joinPath(
+        '/home/dev/workspace/openspec',
+        '.cursor/commands/install.md'
+      );
+      expect(result).toBe('/home/dev/workspace/openspec/.cursor/commands/install.md');
+    });
+
+    it('should join Windows drive-letter paths with backslashes', () => {
+      const result = FileSystemUtils.joinPath(
+        'C:\\Users\\dev\\project',
+        '.claude/commands/openspec/proposal.md'
+      );
+      expect(result).toBe(
+        'C:\\Users\\dev\\project\\.claude\\commands\\openspec\\proposal.md'
+      );
+    });
+
+    it('should join Windows paths that use forward slashes', () => {
+      const result = FileSystemUtils.joinPath(
+        'D:/workspace/app',
+        '.cursor/commands/openspec-apply.md'
+      );
+      expect(result).toBe(
+        'D:\\workspace\\app\\.cursor\\commands\\openspec-apply.md'
+      );
+    });
+
+    it('should join UNC-style Windows paths', () => {
+      const result = FileSystemUtils.joinPath(
+        '\\server\\share\\repo',
+        '.windsurf/workflows/openspec-archive.md'
+      );
+      expect(result).toBe(
+        '\\server\\share\\repo\\.windsurf\\workflows\\openspec-archive.md'
+      );
+    });
+  });
 });