Feature: MCP Server Integration and Gemini Extension Support

.github/workflows/ci.yml

@@ -145,6 +145,9 @@ jobs:
       - name: Lint
         run: pnpm lint
 
+      - name: Check extension version sync
+        run: node scripts/check-extension-version.mjs
+
       - name: Check for build artifacts
         run: |
           if [ ! -d "dist" ]; then
@@ -156,6 +159,9 @@ jobs:
             exit 1
           fi
 
+      - name: Verify MCP server help
+        run: node bin/openspec.js serve --help
+
   validate-changesets:
     name: Validate Changesets
     runs-on: ubuntu-latest

.github/workflows/release-prepare.yml

@@ -51,6 +51,7 @@ jobs:
         with:
           title: 'chore(release): version packages'
           createGithubReleases: true
+          version: pnpm run ci:version
           # Use CI-specific release script: relies on version PR having been merged
           # so package.json already contains the bumped version.
           publish: pnpm run release:ci

GEMINI.md

@@ -0,0 +1,148 @@
+# OpenSpec Extension for Gemini CLI
+
+OpenSpec is an AI-native system for spec-driven development. It helps developers and AI agents maintain a shared understanding of project requirements and technical designs through a structured workflow.
+
+This extension provides native integration via the Model Context Protocol (MCP), enabling a **zero-install workflow** where agents can manage OpenSpec without requiring the global `openspec` npm package.
+
+## MCP Capabilities
+
+### Tools
+- `openspec_init`: Initialize or extend OpenSpec in the current project.
+- `openspec_update`: Refresh instruction files and slash commands.
+- `openspec_view`: Get dashboard data for specs and changes.
+- `openspec_create_change`: Scaffold a new OpenSpec change directory.
+- `openspec_list_changes`: List active change proposals.
+- `openspec_list_specs`: List current specifications.
+- `openspec_show_change`: Show details of a change (JSON/Markdown).
+- `openspec_show_spec`: Show details of a specification (JSON/Markdown).
+- `openspec_validate_change`: Validate a change proposal against schema rules.
+- `openspec_archive_change`: Archive a completed change and update main specs.
+
+### Resources
+- `openspec://changes/{name}/proposal`: Access the proposal.md content.
+- `openspec://changes/{name}/tasks`: Access the tasks.md content.
+- `openspec://specs/{id}`: Access the spec.md content for a capability.
+
+### Prompts
+- `openspec_proposal`: Context and steps for scaffolding a new change.
+- `openspec_apply`: Instructions for implementing an approved change.
+- `openspec_archive`: Workflow for archiving a completed change.
+
+## Zero-Install Usage
+
+If you have this extension added to your Gemini CLI, you can start using OpenSpec immediately in any directory by asking:
+
+> "Initialize OpenSpec in this project"
+
+The agent will use `openspec_init` to scaffold the necessary files. No local or global installation of `@fission-ai/openspec` is required for AI-driven workflows.
+
+## Prerequisites
+
+This extension requires the Gemini CLI. The OpenSpec MCP server is bundled with the extension.
+
+**Auto-Initialization Instruction**:
+When the user starts a session or tries to use OpenSpec:
+1.  **Check for CLI**: Run `openspec --version`.
+    -   If found, use `openspec` for all commands.
+    -   If missing, **automatically attempt to install it globally** by running:
+        ```bash
+        npm install -g "@fission-ai/openspec"
+        ```
+    -   If the installation fails or the user cancels the tool call, fall back to:
+        ```bash
+        npx "@fission-ai/openspec"
+        ```
+        or
+        ```bash
+        pnpm dlx "@fission-ai/openspec"
+        ```
+2.  **Check for Slash Commands**: Verify if `.gemini/commands/openspec/` exists and contains `proposal.toml`, `apply.toml`, and `archive.toml`.
+    -   If missing, **automatically generate them** using the logic defined in the "Maintenance: Slash Command Synchronization" section below.
+    -   Inform the user: "OpenSpec slash commands have been generated. You may need to restart the CLI to see them."
+3.  **Check for Project Initialization**: Verify if the `openspec/` directory exists in the project root.
+    -   If missing, automatically run `openspec init` to scaffold the project structure.
+4.  **Populate Project Context**:
+    -   **Trigger**: When `openspec init` completes and suggests "Populate your project context", you MUST perform this immediately.
+    -   **Action**: Read `openspec/project.md`, analyze project config (`package.json`, etc.), and fill in the details. **Do not** ask the user to do this manually.
+
+## Core Mandates for Gemini Agents
+
+- **Specs are Truth**: Always read `openspec/specs/` to understand the current state of a capability.
+- **Changes are Proposals**: All modifications to behavior or requirements MUST start as a proposal in `openspec/changes/`.
+- **Minimize Confirmations**: Do not ask for permission for low-risk read operations or standard project scaffolding if the user's intent is clear. Assume consent for actions explicitly requested.
+- **Three-Stage Workflow**:
+    1. **Stage 1: Creating Changes**: Scaffold `proposal.md`, `tasks.md`, and spec deltas. Validate with `openspec validate <id> --strict`.
+    2. **Stage 2: Implementing Changes**: Follow `tasks.md` sequentially.
+    3. **Stage 3: Archiving Changes**: Move completed changes to `archive/` using `openspec archive <id>`.
+
+## Essential CLI Commands
+
+When working in an OpenSpec-enabled project, you can use these commands:
+
+- `openspec list`: Show active changes.
+- `openspec list --specs`: Show existing capabilities.
+- `openspec show <id>`: View details of a change or spec.
+- `openspec validate <id>`: Validate a change against the project's specs.
+- `openspec init`: Initialize OpenSpec in a new project.
+- `openspec update`: Update instruction files (like `AGENTS.md`).
+
+## Directory Structure
+
+- `openspec/project.md`: Project-specific conventions and tech stack.
+- `openspec/specs/`: Current requirements and scenarios (the "truth").
+- `openspec/changes/`: Pending proposals and implementation tasks.
+
+## Writing Specs
+
+Requirements must be normative (SHALL/MUST). Every requirement MUST have at least one scenario using the following format:
+
+```markdown
+#### Scenario: Name
+- **WHEN** action or condition
+- **THEN** expected result
+```
+
+For more detailed instructions, refer to `openspec/AGENTS.md`.
+
+## Maintenance: Slash Command Synchronization
+
+The slash commands for this extension (`.gemini/commands/openspec/*.toml`) are generated artifacts. The single source of truth for their content is `src/core/templates/prompts.ts`.
+
+**Instruction**: When `src/core/templates/prompts.ts` is modified, or when asked to "update slash commands", you MUST regenerate the TOML files in `.gemini/commands/openspec/` using the following logic:
+
+1.  **Read** `src/core/templates/prompts.ts` to extract the exported constants.
+2.  **Construct** the prompt body for each command by joining the relevant constants with `\n\n`:
+    -   **proposal**: `PROPOSAL_GUARDRAILS` + `PROPOSAL_STEPS` + `PROPOSAL_REFERENCES`
+    -   **apply**: `BASE_GUARDRAILS` + `APPLY_STEPS` + `APPLY_REFERENCES`
+    -   **archive**: `BASE_GUARDRAILS` + `ARCHIVE_STEPS` + `ARCHIVE_REFERENCES`
+3.  **Generate** the TOML files with the following structure (preserving the `<!-- OPENSPEC:START -->` markers inside the prompt string):
+
+    **File**: `.gemini/commands/openspec/proposal.toml`
+    ```toml
+    description = "Scaffold a new OpenSpec change and validate strictly."
+    prompt = """
+    <!-- OPENSPEC:START -->
+    {PROPOSAL_BODY}
+    <!-- OPENSPEC:END -->
+    """
+    ```
+
+    **File**: `.gemini/commands/openspec/apply.toml`
+    ```toml
+    description = "Implement an approved OpenSpec change and keep tasks in sync."
+    prompt = """
+    <!-- OPENSPEC:START -->
+    {APPLY_BODY}
+    <!-- OPENSPEC:END -->
+    """
+    ```
+
+    **File**: `.gemini/commands/openspec/archive.toml`
+    ```toml
+    description = "Archive a deployed OpenSpec change and update specs."
+    prompt = """
+    <!-- OPENSPEC:START -->
+    {ARCHIVE_BODY}
+    <!-- OPENSPEC:END -->
+    """
+    ```

README.md

@@ -85,7 +85,28 @@ See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
 4. Archive the change to merge the approved updates back into the source-of-truth specs.
 ```
 
-## Getting Started
+## Integration Modes
+
+OpenSpec supports two primary integration modes for AI agents:
+
+1.  **Native MCP (Recommended)**: Use OpenSpec as an MCP server (e.g., via the Gemini CLI extension). This enables a **zero-install workflow** where agents can manage OpenSpec without requiring the npm package to be installed in the environment. Add it to your MCP host (like Claude Desktop) using this snippet:
+
+    ```json
+    {
+      "mcpServers": {
+        "openspec": {
+          "command": "npx",
+          "args": ["-y", "@fission-ai/openspec@latest", "serve"]
+        }
+      }
+    }
+    ```
+
+2.  **CLI Wrapper**: Agents call the `openspec` command-line tool directly. This requires the `@fission-ai/openspec` package to be installed globally or locally.
+
+---
+
+## 🚀 Quick Start
 
 ### Supported AI Tools
 
@@ -108,7 +129,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
 | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
-| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
+| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (Native Extension available) |
 | **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
 | **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
 | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
@@ -133,6 +154,22 @@ These tools automatically read workflow instructions from `openspec/AGENTS.md`.
 
 </details>
 
+### Gemini CLI Extension (Native)
+
+OpenSpec is available as a native extension for the [Gemini CLI](https://geminicli.com). This provides deep contextual awareness and native slash commands without manual configuration.
+
+**Install the extension:**
+```bash
+gemini extensions install https://github.com/Fission-AI/OpenSpec
+```
+
+**Benefits:**
+- **Zero Configuration**: Automatically sets up `/openspec` slash commands.
+- **Native Context**: Gemini becomes "OpenSpec-aware" instantly.
+- **Auto-Maintenance**: The agent can self-repair its command definitions from the source of truth.
+
+*Note: You still need the [OpenSpec CLI](#step-1-install-the-cli-globally) installed globally for the agent to perform operations.*
+
 ### Install & Initialize
 
 #### Prerequisites

gemini-extension.json

@@ -0,0 +1,14 @@
+{
+  "name": "openspec",
+  "version": "0.18.0",
+  "contextFileName": "GEMINI.md",
+  "mcpServers": {
+    "openspec": {
+      "command": "node",
+      "args": [
+        "bin/openspec.js",
+        "serve"
+      ]
+    }
+  }
+}

openspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.md

@@ -0,0 +1,18 @@
+# Add Gemini CLI Extension Support
+
+## Goal
+Transform the OpenSpec repository into a valid Gemini CLI extension to enhance the development experience for users employing the Gemini CLI.
+
+## Motivation
+Integrating with Gemini CLI allows us to provide deep, project-specific context and potentially custom tools directly to the AI agent. This "eases the integration path" by making the agent "OpenSpec-aware" out of the box when this extension is installed or linked.
+
+## Proposed Solution
+1.  **Extension Manifest**: Create a `gemini-extension.json` file in the project root. This file defines the extension metadata and points to the context file.
+2.  **Context File**: Create a `GEMINI.md` file in the project root. This file will contain high-level instructions, architectural overviews, and usage guides for OpenSpec, tailored for the Gemini agent. It should reference or inline key parts of `AGENTS.md` and `openspec/project.md`.
+3.  **Unified Prompts**: Extract core slash command prompts into a shared `src/core/templates/prompts.ts` file. This ensures that all agent integrations (Claude, Cursor, Gemini, etc.) use the same underlying instructions.
+4.  **Native Slash Commands**: Create native Gemini CLI slash command files (`.toml`) in `.gemini/commands/openspec/` that consume the unified prompts. This allows users to trigger OpenSpec workflows directly via `/openspec:proposal`, etc.
+
+## Benefits
+- **Contextual Awareness**: Gemini CLI will automatically understand OpenSpec commands (`openspec init`, `openspec change`, etc.) and conventions without manual prompting.
+- **Standardization**: Ensures that the AI assistant follows the project's specific coding and contribution guidelines.
+- **Extensibility**: Lay the groundwork for future MCP server integrations (e.g., tools to automatically validate specs or scaffold changes).

openspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+### Requirement: Slash Command Safety
+All generated slash command templates SHALL include safety guardrails.
+
+#### Scenario: CLI Availability Check
+- **WHEN** generating slash commands for any tool
+- **THEN** the template SHALL include an instruction to verify the `openspec` CLI is installed and available in the environment
+- **AND** guide the user to install it via `npm install -g @fission-ai/openspec` if missing

openspec/changes/archive/2025-12-21-add-gemini-extension-support/tasks.md

@@ -0,0 +1,8 @@
+- [x] Create `gemini-extension.json` in the project root @file:gemini-extension.json
+- [x] Create `GEMINI.md` in the project root with OpenSpec context @file:GEMINI.md
+- [x] Extract slash command prompts to a shared location for unified usage across agents
+- [x] Configure `GEMINI.md` to auto-generate slash commands from shared prompts
+- [x] Document CLI installation prerequisites in `GEMINI.md` and shared prompts
+- [x] Add maintenance instructions to `GEMINI.md` for syncing slash commands from `prompts.ts`
+- [x] Update `README.md` with Gemini CLI Extension installation and benefits
+- [x] Verify the extension can be linked locally using `gemini extensions link .` (Manual verification)

openspec/changes/archive/2026-01-12-add-mcp-server/proposal.md

@@ -0,0 +1,29 @@
+# Proposal: Add MCP Server Support
+
+## Context
+Currently, OpenSpec integrates with AI agents via CLI commands and static configuration files (slash commands). While effective, this requires manual setup for some agents and lacks the rich interactivity offered by the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+## Goal
+Implement a native MCP server within the OpenSpec CLI using modern tools (e.g., `fastmcp` or `@modelcontextprotocol/sdk`). This will:
+1.  Allow any MCP-compliant agent (Claude Desktop, Gemini CLI, etc.) to discover and use OpenSpec tools and resources without custom configuration files.
+2.  Enable the Gemini CLI extension to be a thin wrapper around this native MCP server.
+3. Align the project structure with modern standards by moving `openspec/` to `.openspec/` during initialization.
+
+## Migration Path
+To support existing users, the CLI will include an automatic migration flow:
+- **Detection**: `openspec init` (or a dedicated `openspec migrate` command) will detect legacy `openspec/` directories.
+- **Auto-rename**: Prompt the user to rename `openspec/` to `.openspec/`.
+- **Instruction Refresh**: Automatically run `openspec update` after the rename to ensure all assistant instructions point to the new location.
+- **Backward Compatibility**: The CLI will continue to look for `openspec/` if `.openspec/` is missing, but will issue a deprecation warning.
+
+## Solution
+1.  **Add `openspec serve` command**: Starts the MCP server over stdio.
+2.  **Use Modern MCP Tools**: Leverage libraries like `fastmcp` or the official SDK to simplify server implementation and type safety.
+3.  **Expose Tools**: Convert existing CLI commands (`list`, `show`, `validate`, `archive`) into MCP tools.
+4.  **Expose Resources**: Provide direct read access to specs and changes via `openspec://` URIs.
+5.  **Expose Prompts**: Serve the standard proposal/apply/archive prompts via `prompts/list`.
+6. **Migrate Directory**: Update `init` to scaffold in `.openspec/` instead of `openspec/`.
+7. **Gemini Extension**: Create the `gemini-extension.json` manifest to register this MCP server capability.
+8. **CI Validation**: Add a CI check to ensure `gemini-extension.json` version stays in sync with `package.json`.
+
+This "modernizes" the integration, making it cleaner, more robust, and easier to maintain.

openspec/changes/archive/2026-01-12-add-mcp-server/specs/ci-sync/spec.md

@@ -0,0 +1,17 @@
+# Delta for ci-sync
+
+## ADDED Requirements
+### Requirement: Extension Version Synchronization
+The system SHALL ensure that the version in `gemini-extension.json` matches the version in `package.json` during the CI process.
+
+#### Scenario: Version mismatch in CI
+- **GIVEN** `package.json` has version `0.18.0`
+- **AND** `gemini-extension.json` has version `0.17.0`
+- **WHEN** the CI pipeline runs
+- **THEN** the version check step SHALL fail
+- **AND** report the mismatch to the logs
+
+#### Scenario: Version match in CI
+- **GIVEN** both files have version `0.18.0`
+- **WHEN** the CI pipeline runs
+- **THEN** the version check step SHALL pass

openspec/changes/archive/2026-01-12-add-mcp-server/specs/cli-init/spec.md

@@ -0,0 +1,29 @@
+# Delta for cli-init
+
+## MODIFIED Requirements
+### Requirement: Directory Creation
+The command SHALL create the complete OpenSpec directory structure in a hidden directory `.openspec/` to reduce clutter.
+
+#### Scenario: Creating OpenSpec structure
+- **WHEN** `openspec init` is executed
+- **THEN** create the following directory structure:
+```
+.openspec/
+├── project.md
+├── AGENTS.md
+├── specs/
+└── changes/
+    └── archive/
+```
+
+## ADDED Requirements
+### Requirement: Legacy Migration
+The `init` command SHALL detect legacy `openspec/` directories and offer to migrate them to `.openspec/`.
+
+#### Scenario: Migrating legacy directory
+- **GIVEN** a project with an existing `openspec/` directory
+- **AND** no `.openspec/` directory exists
+- **WHEN** executing `openspec init`
+- **THEN** prompt the user: "Detected legacy 'openspec/' directory. Would you like to migrate it to '.openspec/'?"
+- **AND** if confirmed, rename the directory
+- **AND** update all managed AI instructions to point to the new location

openspec/changes/archive/2026-01-12-add-mcp-server/specs/cli-spec/spec.md

@@ -0,0 +1,10 @@
+# Delta for cli-spec
+
+## ADDED Requirements
+### Requirement: Serve Command
+The system SHALL provide a `serve` command to start the Model Context Protocol (MCP) server.
+
+#### Scenario: Start MCP Server
+- **WHEN** executing `openspec serve`
+- **THEN** start the MCP server using stdio transport
+- **AND** keep the process alive to handle requests