feat(gemini): add native extension support and unified prompts

.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

@@ -40,6 +40,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

@@ -81,7 +81,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
 
@@ -103,7 +124,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/`) |
@@ -128,6 +149,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/add-mcp-tests/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-12

openspec/changes/add-mcp-tests/proposal.md

@@ -0,0 +1,27 @@
+# Proposal: Add MCP Server Test Coverage & Core Refactoring
+
+## Goal
+Add comprehensive test coverage for the MCP server and refactor CLI logic into Core to enable shared testing.
+
+## Motivation
+The MCP server currently lacks dedicated unit and integration tests. Furthermore, significant logic for `change` operations (list, show, validate) resides in `src/commands`, making it difficult to test independently or reuse in the MCP server.
+
+To ensure reliability and consistency between CLI and MCP, we need to:
+1.  Refactor `list`, `show`, and `validate` logic from `src/commands/change.ts` into `src/core`.
+2.  Add a robust test suite covering Core, MCP, and ensuring CLI integrations work.
+
+## Success Criteria
+### Refactoring
+- [ ] `ChangeCommand` logic in `src/commands/change.ts` refactored into pure functions in `src/core/change-logic.ts` (or similar).
+- [ ] CLI command updated to consume new core functions.
+- [ ] MCP server updated to consume new core functions (if not already).
+
+### Testing
+- [ ] **Core**: Unit tests for new `src/core` functions (create, list, show, validate).
+- [ ] **MCP**: Unit tests for `src/mcp/tools.ts`, `resources.ts`, `prompts.ts`.
+- [ ] **MCP**: Integration tests for `src/mcp/server.ts`.
+- [ ] **CLI**: Existing E2E tests pass or are updated to reflect refactoring.
+- [ ] `mcp-server` spec updated to include these requirements.
+
+### Cleanup
+- [ ] Remove unused imports across the codebase.

openspec/changes/add-mcp-tests/specs/mcp-server/spec.md

@@ -0,0 +1,26 @@
+# mcp-server Specification Deltas
+
+## ADDED Requirements
+
+### Requirement: Test Coverage
+The MCP server implementation SHALL have unit and integration tests.
+
+#### Scenario: Testing Tool Definitions
+- **WHEN** the test suite runs
+- **THEN** it SHALL verify that all exposed tools have correct names, descriptions, and schemas.
+
+#### Scenario: Testing Resource Resolution
+- **WHEN** the test suite runs
+- **THEN** it SHALL verify that `openspec://` URIs are correctly parsed and resolved to file paths.
+
+#### Scenario: Testing Prompt Content
+- **WHEN** the test suite runs
+- **THEN** it SHALL verify that prompts can be retrieved and contain expected placeholders.
+
+### Requirement: Testability of Core Logic
+The core logic used by the MCP server SHALL be testable independently of the CLI or MCP transport layer.
+
+#### Scenario: Unit Testing Core Functions
+- **WHEN** a core function (e.g., `runCreateChange`, `runListChanges`) is tested
+- **THEN** it SHALL be possible to invoke it without mocking CLI-specific objects (like `process` or `console` capture).
+- **AND** it SHALL return structured data rather than writing to stdout.

openspec/changes/add-mcp-tests/tasks.md

@@ -0,0 +1,29 @@
+# Implementation Tasks
+
+## Spec Updates
+- [ ] Update `openspec/specs/mcp-server/spec.md` to include test coverage and shared logic requirements.
+
+## Refactoring (CLI -> Core)
+- [ ] Refactor `getActiveChanges` from `src/commands/change.ts` to `src/core/change-logic.ts`.
+- [ ] Refactor `getChangeMarkdown` and `getChangeJson` (logic part) to `src/core/change-logic.ts`.
+- [ ] Refactor `validate` logic to `src/core/change-logic.ts` (or `validation-logic.ts`).
+- [ ] Update `src/commands/change.ts` to use the new core functions.
+
+## Testing
+### Core
+- [ ] Migrate and adapt existing tests from `test/core/commands/change-command.*` to `test/core/change-logic.test.ts`.
+- [ ] Ensure `test/commands/change.*` and `test/commands/validate.*` are updated to reflect the refactoring while preserving coverage.
+- [ ] Verify that `test/cli-e2e/basic.test.ts` still passes to ensure no regressions in CLI behavior.
+
+### MCP
+- [ ] Create `test/mcp` directory.
+- [ ] Create `test/mcp/tools.test.ts` to test tool definitions and execution.
+- [ ] Create `test/mcp/resources.test.ts` to test resource handling.
+- [ ] Create `test/mcp/prompts.test.ts` to test prompt generation.
+- [ ] Create `test/mcp/server.test.ts` to test server initialization and request handling.
+
+## Cleanup
+- [ ] Identify and remove unused imports across `src/` and `test/` using an automated tool or manual audit.
+
+## Verification
+- [ ] Verify all tests pass with `npm test`.

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)