Document Gemini CLI slash updates

* feat: add Gemini CLI support with TOML-based slash commands

- Add GeminiSlashCommandConfigurator for .gemini/commands/openspec/
- Register Gemini CLI in AI_TOOLS config and slash command registry
- Generate TOML files with description and prompt fields
- Add comprehensive test coverage for Gemini CLI integration
- Update README to list Gemini CLI under Native Slash Commands
- Remove Gemini CLI from AGENTS.md compatible list (now native)

Implements GitHub issue #248

* [add]

* feat: address PR feedback - remove changeset and add update test

- Remove .changeset/add-gemini-cli-support.md as requested by maintainer
- Add test for Gemini CLI TOML update/refresh path
- Test verifies that existing TOML files are properly updated when running init again

Addresses feedback from TabishB in PR #256

---------

Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>

README.md

@@ -97,6 +97,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **Cline** | Rules in `.clinerules/` directory (`.clinerules/openspec-*.md`) |
 | **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
 | **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
+| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
 | **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
 | **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
@@ -115,7 +116,7 @@ These tools automatically read workflow instructions from `openspec/AGENTS.md`.
 
 | Tools |
 |-------|
-| Amp • Jules • Gemini CLI • Others |
+| Amp • Jules • Others |
 
 ### Install & Initialize
 

openspec/specs/cli-init/spec.md

@@ -231,6 +231,13 @@ The init command SHALL generate slash command files for supported editors using
 - **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
 - **AND** each template includes instructions for the relevant OpenSpec workflow stage
 
+#### Scenario: Generating slash commands for Gemini CLI
+- **WHEN** the user selects Gemini CLI during initialization
+- **THEN** create `.gemini/commands/openspec/proposal.toml`, `.gemini/commands/openspec/apply.toml`, and `.gemini/commands/openspec/archive.toml`
+- **AND** populate each file as TOML that sets a stage-specific `description = "<summary>"` and a multi-line `prompt = """` block with the shared OpenSpec template
+- **AND** wrap the OpenSpec managed markers (`<!-- OPENSPEC:START -->` / `<!-- OPENSPEC:END -->`) inside the `prompt` value so `openspec update` can safely refresh the body between markers without touching the TOML framing
+- **AND** ensure the slash-command copy matches the existing proposal/apply/archive templates used by other tools
+
 ### Requirement: Non-Interactive Mode
 The command SHALL support non-interactive operation through command-line options for automation and CI/CD use cases.
 

openspec/specs/cli-update/spec.md

@@ -117,6 +117,12 @@ The update command SHALL refresh existing slash command files for configured too
 - **AND** update only the OpenSpec-managed block between markers
 - **AND** ensure templates include instructions for the relevant workflow stage
 
+#### Scenario: Updating slash commands for Gemini CLI
+- **WHEN** `.gemini/commands/openspec/` contains `proposal.toml`, `apply.toml`, and `archive.toml`
+- **THEN** refresh the body of each file using the shared proposal/apply/archive templates
+- **AND** replace only the content between `<!-- OPENSPEC:START -->` and `<!-- OPENSPEC:END -->` markers inside the `prompt = """` block so the TOML framing (`description`, `prompt`) stays intact
+- **AND** skip creating any missing `.toml` files during update; only pre-existing Gemini commands are refreshed
+
 #### Scenario: Missing slash command file
 - **WHEN** a tool lacks a slash command file
 - **THEN** do not create a new file during update

src/core/config.ts

@@ -25,6 +25,7 @@ export const AI_TOOLS: AIToolOption[] = [
   { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush' },
   { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor' },
   { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid' },
+  { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI' },
   { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode' },
   { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code' },
   { name: 'Qoder (CLI)', value: 'qoder', available: true, successLabel: 'Qoder' },

src/core/configurators/slash/gemini.ts

@@ -0,0 +1,83 @@
+import { FileSystemUtils } from '../../../utils/file-system.js';
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId, TemplateManager } from '../../templates/index.js';
+import { OPENSPEC_MARKERS } from '../../config.js';
+
+const FILE_PATHS: Record<SlashCommandId, string> = {
+  proposal: '.gemini/commands/openspec/proposal.toml',
+  apply: '.gemini/commands/openspec/apply.toml',
+  archive: '.gemini/commands/openspec/archive.toml'
+};
+
+const DESCRIPTIONS: Record<SlashCommandId, string> = {
+  proposal: 'Scaffold a new OpenSpec change and validate strictly.',
+  apply: 'Implement an approved OpenSpec change and keep tasks in sync.',
+  archive: 'Archive a deployed OpenSpec change and update specs.'
+};
+
+export class GeminiSlashCommandConfigurator extends SlashCommandConfigurator {
+  readonly toolId = 'gemini';
+  readonly isAvailable = true;
+
+  protected getRelativePath(id: SlashCommandId): string {
+    return FILE_PATHS[id];
+  }
+
+  protected getFrontmatter(_id: SlashCommandId): string | undefined {
+    // TOML doesn't use separate frontmatter - it's all in one structure
+    return undefined;
+  }
+
+  // Override to generate TOML format with markers inside the prompt field
+  async generateAll(projectPath: string, _openspecDir: string): Promise<string[]> {
+    const createdOrUpdated: string[] = [];
+
+    for (const target of this.getTargets()) {
+      const body = this.getBody(target.id);
+      const filePath = FileSystemUtils.joinPath(projectPath, target.path);
+
+      if (await FileSystemUtils.fileExists(filePath)) {
+        await this.updateBody(filePath, body);
+      } else {
+        const tomlContent = this.generateTOML(target.id, body);
+        await FileSystemUtils.writeFile(filePath, tomlContent);
+      }
+
+      createdOrUpdated.push(target.path);
+    }
+
+    return createdOrUpdated;
+  }
+
+  private generateTOML(id: SlashCommandId, body: string): string {
+    const description = DESCRIPTIONS[id];
+
+    // TOML format with triple-quoted string for multi-line prompt
+    // Markers are inside the prompt value
+    return `description = "${description}"
+
+prompt = """
+${OPENSPEC_MARKERS.start}
+${body}
+${OPENSPEC_MARKERS.end}
+"""
+`;
+  }
+
+  // Override updateBody to handle TOML format
+  protected async updateBody(filePath: string, body: string): Promise<void> {
+    const content = await FileSystemUtils.readFile(filePath);
+    const startIndex = content.indexOf(OPENSPEC_MARKERS.start);
+    const endIndex = content.indexOf(OPENSPEC_MARKERS.end);
+
+    if (startIndex === -1 || endIndex === -1 || endIndex <= startIndex) {
+      throw new Error(`Missing OpenSpec markers in ${filePath}`);
+    }
+
+    const before = content.slice(0, startIndex + OPENSPEC_MARKERS.start.length);
+    const after = content.slice(endIndex);
+    const updatedContent = `${before}\n${body}\n${after}`;
+
+    await FileSystemUtils.writeFile(filePath, updatedContent);
+  }
+}

src/core/configurators/slash/registry.ts

@@ -10,6 +10,7 @@ import { CodexSlashCommandConfigurator } from './codex.js';
 import { GitHubCopilotSlashCommandConfigurator } from './github-copilot.js';
 import { AmazonQSlashCommandConfigurator } from './amazon-q.js';
 import { FactorySlashCommandConfigurator } from './factory.js';
+import { GeminiSlashCommandConfigurator } from './gemini.js';
 import { AuggieSlashCommandConfigurator } from './auggie.js';
 import { ClineSlashCommandConfigurator } from './cline.js';
 import { CrushSlashCommandConfigurator } from './crush.js';
@@ -31,6 +32,7 @@ export class SlashCommandRegistry {
     const githubCopilot = new GitHubCopilotSlashCommandConfigurator();
     const amazonQ = new AmazonQSlashCommandConfigurator();
     const factory = new FactorySlashCommandConfigurator();
+    const gemini = new GeminiSlashCommandConfigurator();
     const auggie = new AuggieSlashCommandConfigurator();
     const cline = new ClineSlashCommandConfigurator();
     const crush = new CrushSlashCommandConfigurator();
@@ -48,6 +50,7 @@ export class SlashCommandRegistry {
     this.configurators.set(githubCopilot.toolId, githubCopilot);
     this.configurators.set(amazonQ.toolId, amazonQ);
     this.configurators.set(factory.toolId, factory);
+    this.configurators.set(gemini.toolId, gemini);
     this.configurators.set(auggie.toolId, auggie);
     this.configurators.set(cline.toolId, cline);
     this.configurators.set(crush.toolId, crush);

test/core/init.test.ts

@@ -305,6 +305,73 @@ describe('InitCommand', () => {
       expect(archiveContent).toContain('openspec list --specs');
     });
 
+    it('should create Gemini CLI TOML files when selected', async () => {
+      queueSelections('gemini', DONE);
+
+      await initCommand.execute(testDir);
+
+      const geminiProposal = path.join(
+        testDir,
+        '.gemini/commands/openspec/proposal.toml'
+      );
+      const geminiApply = path.join(
+        testDir,
+        '.gemini/commands/openspec/apply.toml'
+      );
+      const geminiArchive = path.join(
+        testDir,
+        '.gemini/commands/openspec/archive.toml'
+      );
+
+      expect(await fileExists(geminiProposal)).toBe(true);
+      expect(await fileExists(geminiApply)).toBe(true);
+      expect(await fileExists(geminiArchive)).toBe(true);
+
+      const proposalContent = await fs.readFile(geminiProposal, 'utf-8');
+      expect(proposalContent).toContain('description = "Scaffold a new OpenSpec change and validate strictly."');
+      expect(proposalContent).toContain('prompt = """');
+      expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
+      expect(proposalContent).toContain('**Guardrails**');
+      expect(proposalContent).toContain('<!-- OPENSPEC:END -->');
+
+      const applyContent = await fs.readFile(geminiApply, 'utf-8');
+      expect(applyContent).toContain('description = "Implement an approved OpenSpec change and keep tasks in sync."');
+      expect(applyContent).toContain('Work through tasks sequentially');
+
+      const archiveContent = await fs.readFile(geminiArchive, 'utf-8');
+      expect(archiveContent).toContain('description = "Archive a deployed OpenSpec change and update specs."');
+      expect(archiveContent).toContain('openspec archive <id>');
+    });
+
+    it('should update existing Gemini CLI TOML files with refreshed content', async () => {
+      queueSelections('gemini', DONE);
+
+      await initCommand.execute(testDir);
+
+      const geminiProposal = path.join(
+        testDir,
+        '.gemini/commands/openspec/proposal.toml'
+      );
+
+      // Modify the file to simulate user customization
+      const originalContent = await fs.readFile(geminiProposal, 'utf-8');
+      const modifiedContent = originalContent.replace(
+        '<!-- OPENSPEC:START -->',
+        '<!-- OPENSPEC:START -->\nCustom instruction added by user\n'
+      );
+      await fs.writeFile(geminiProposal, modifiedContent);
+
+      // Run init again to test update/refresh path
+      queueSelections('gemini', DONE);
+      await initCommand.execute(testDir);
+
+      const updatedContent = await fs.readFile(geminiProposal, 'utf-8');
+      expect(updatedContent).toContain('<!-- OPENSPEC:START -->');
+      expect(updatedContent).toContain('**Guardrails**');
+      expect(updatedContent).toContain('<!-- OPENSPEC:END -->');
+      expect(updatedContent).not.toContain('Custom instruction added by user');
+    });
+
     it('should create OpenCode slash command files with templates', async () => {
       queueSelections('opencode', DONE);
 

test/core/update.test.ts

@@ -588,6 +588,54 @@ Old body
     await expect(FileSystemUtils.fileExists(ghArchive)).resolves.toBe(false);
   });
 
+  it('should refresh existing Gemini CLI TOML files without creating new ones', async () => {
+    const geminiProposal = path.join(
+      testDir,
+      '.gemini/commands/openspec/proposal.toml'
+    );
+    await fs.mkdir(path.dirname(geminiProposal), { recursive: true });
+    const initialContent = `description = "Scaffold a new OpenSpec change and validate strictly."
+
+prompt = """
+<!-- OPENSPEC:START -->
+Old Gemini body
+<!-- OPENSPEC:END -->
+"""
+`;
+    await fs.writeFile(geminiProposal, initialContent);
+
+    const consoleSpy = vi.spyOn(console, 'log');
+
+    await updateCommand.execute(testDir);
+
+    const updated = await fs.readFile(geminiProposal, 'utf-8');
+    expect(updated).toContain('description = "Scaffold a new OpenSpec change and validate strictly."');
+    expect(updated).toContain('prompt = """');
+    expect(updated).toContain('<!-- OPENSPEC:START -->');
+    expect(updated).toContain('**Guardrails**');
+    expect(updated).toContain('<!-- OPENSPEC:END -->');
+    expect(updated).not.toContain('Old Gemini body');
+
+    const geminiApply = path.join(
+      testDir,
+      '.gemini/commands/openspec/apply.toml'
+    );
+    const geminiArchive = path.join(
+      testDir,
+      '.gemini/commands/openspec/archive.toml'
+    );
+
+    await expect(FileSystemUtils.fileExists(geminiApply)).resolves.toBe(false);
+    await expect(FileSystemUtils.fileExists(geminiArchive)).resolves.toBe(false);
+
+    const [logMessage] = consoleSpy.mock.calls[0];
+    expect(logMessage).toContain(
+      'Updated slash commands: .gemini/commands/openspec/proposal.toml'
+    );
+
+    consoleSpy.mockRestore();
+  });
+
   it('should refresh existing Factory slash commands', async () => {
     const factoryPath = path.join(
       testDir,