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

GEMINI.md

@@ -0,0 +1,134 @@
+# 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).
+
+## MCP Capabilities
+
+### Tools
+- `openspec_list_changes`: List active change proposals.
+- `openspec_list_specs`: List current specifications.
+- `openspec_show_change`: Show details of a change (JSON/Markdown).
+- `openspec_validate_change`: Validate a change proposal against schema rules.
+
+### 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.
+
+## Prerequisites
+
+This extension requires the OpenSpec CLI.
+
+**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

@@ -103,7 +103,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 +128,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": {
+    "default": {
+      "command": "node",
+      "args": [
+        "bin/openspec.js",
+        "serve"
+      ]
+    }
+  }
+}

openspec/changes/agent-only-mcp-workflow/proposal.md

@@ -0,0 +1,31 @@
+# Proposal: Transition to Pure MCP-Driven Workflow
+
+## Why
+Currently, using OpenSpec with AI agents often requires the OpenSpec CLI to be installed in the environment where the agent is running. This creates adoption friction and dependency management overhead. By leveraging the Model Context Protocol (MCP), we can package all OpenSpec logic into a self-contained server that the Gemini CLI (or any MCP client) can run as a plugin. This allows agents to manage the entire OpenSpec lifecycle—from initialization to archiving—using native tools, without requiring the user to install the npm package globally or locally in their production environment.
+
+## What Changes
+1.  **Architecture Principles (Core-First)**:
+    *   **Logic Isolation**: All business logic (file I/O, parsing, validation logic) SHALL reside in `src/core/`.
+    *   **Presentation De-coupling**: Code in `src/core/` SHALL NOT use CLI-specific libraries (`ora`, `chalk`) or direct `console.log`. It SHALL return structured data or throw errors.
+    *   **Thin Wrappers**: `src/cli/` and `src/mcp/` SHALL be thin adapters that call `src/core/` and handle their respective output formats (terminal UI for CLI, JSON-RPC for MCP).
+2.  **Shared Core Implementation**:
+    *   Refactor CLI command handlers to delegate to these isolated core functions.
+3.  **Full MCP Parity**:
+    *   Implement MCP equivalents for ALL remaining CLI commands.
+4.  **CI and Build Stability**:
+    *   Update CI to verify that both the CLI binary and the MCP server start correctly and share the same core logic.
+
+## Impact
+-   **Architecture Cleanliness**: Enforces separation between presentation (CLI/MCP) and logic (Core).
+-   **Full Parity**: Ensures agents have the exact same "superpowers" as users on the command line.
+-   **Continuous Reliability**: CI ensures that refactoring for MCP parity never breaks the legacy CLI experience.
+
+## Impact
+-   **Architecture Cleanliness**: Enforces separation between presentation (CLI/MCP) and logic (Core).
+-   **Flexibility**: Users can choose between CLI, MCP, or both.
+-   **Adoption**: Significantly lowers the barrier for entry by allowing agents to "self-initialize" via MCP.
+
+## Impact
+-   **Zero-Install Adoption**: Users only need to add the Gemini extension; no separate CLI installation is required for AI-driven workflows.
+-   **Consistent Agent Experience**: Agents interact with a structured API (MCP) rather than parsing CLI output or managing shell command strings.
+-   **Future-Proofing**: Aligns OpenSpec with the emerging "plugin" architecture of modern AI coding assistants.

openspec/changes/agent-only-mcp-workflow/specs/mcp-server/spec.md

@@ -0,0 +1,34 @@
+# Delta for mcp-server
+
+## ADDED Requirements
+### Requirement: Shared Core Implementation
+The MCP server and the CLI SHALL share the same underlying business logic implementation for all operations.
+
+#### Scenario: Consistency between CLI and MCP
+- **WHEN** an operation (e.g., init, list, archive) is performed via CLI
+- **AND** the same operation is performed via MCP
+- **THEN** both SHALL yield consistent results by calling the same core functions.
+
+### Requirement: Project Initialization Tool
+The MCP server SHALL provide a tool `openspec_init` to initialize the OpenSpec structure.
+
+#### Scenario: Initializing project via MCP
+- **WHEN** the `openspec_init` tool is called
+- **THEN** execute the shared `runInit` logic
+- **AND** return a structured summary of created items.
+
+### Requirement: Change Creation Tool
+The MCP server SHALL provide a tool `openspec_create_change` to scaffold a new change directory.
+
+#### Scenario: Creating a new change via MCP
+- **WHEN** the `openspec_create_change` tool is called with `name`
+- **THEN** execute the shared `runCreateChange` logic
+- **AND** return the paths of created files.
+
+### Requirement: MCP-First Instructions
+The MCP server SHALL provide prompts that prioritize MCP tools while maintaining CLI references as a secondary option for human readability.
+
+#### Scenario: Guidance in MCP prompts
+- **WHEN** an agent retrieves a prompt via MCP
+- **THEN** the instructions SHALL explicitly list MCP tool calls as the primary action (e.g., "Use openspec_list_changes to view state")
+- **AND** the instructions MAY provide the CLI equivalent for reference.

openspec/changes/agent-only-mcp-workflow/tasks.md

@@ -0,0 +1,29 @@
+# Tasks: Implementation of Pure MCP-Driven Workflow
+
+## 1. Core Logic Isolation
+- [ ] 1.1 Audit `src/core/` for `ora`, `chalk`, and `console.log` usage.
+- [ ] 1.2 Refactor `src/core/init.ts` to be a pure function returning initialization results.
+- [ ] 1.3 Refactor `src/core/update.ts` to return update statistics instead of logging.
+- [ ] 1.4 Refactor `src/core/archive.ts` to return archival reports.
+- [ ] 1.5 Extract dashboard data logic from `src/core/view.ts` into a pure data provider.
+- [ ] 1.6 Refactor experimental tools to follow the data-in/data-out pattern.
+
+## 2. Interface Implementation (CLI & MCP)
+- [ ] 2.1 Update CLI handlers in `src/commands/` to handle UI (spinners, colors) based on core data.
+- [ ] 2.2 Implement MCP tools in `src/mcp/tools.ts` using the same core data.
+- [ ] 2.3 Ensure full feature parity for all 12+ OpenSpec commands.
+
+## 3. Build & CI Validation
+- [ ] 3.1 Verify `bin/openspec.js` works as a standalone CLI after refactoring.
+- [ ] 3.2 Update `.github/workflows/ci.yml` to include a check that `openspec serve` is functional (e.g., exit code 0 on help).
+- [ ] 3.3 Ensure `pnpm run build` covers all new entry points.
+
+## 4. Documentation
+- [ ] 4.1 Update `src/mcp/prompts.ts` to use MCP tool names.
+- [ ] 4.2 Update `GEMINI.md` and `README.md`.
+
+## 3. Verification
+- [ ] 3.1 Verify `openspec_init` works via an MCP client (e.g., Gemini CLI) in a fresh directory.
+- [ ] 3.2 Verify `openspec_update` refreshes files correctly.
+- [ ] 3.3 Verify `openspec_create_change` scaffolds a new change directory.
+- [ ] 3.4 Ensure the CLI remains functional for users who prefer it.

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.