feat(gemini): add native extension support and unified prompts #384
Conversation
- Add gemini-extension.json and GEMINI.md for native Gemini CLI integration - Extract slash command prompts to src/core/templates/prompts.ts for unified agent usage - Configure dynamic slash command generation and maintenance in GEMINI.md - Update README.md with Gemini extension installation guides and benefits - Add OpenSpec change proposal and spec deltas for the integration - Refactor templates and update existing tests to match improved prompt wording
📝 WalkthroughWalkthroughAdds native Gemini CLI extension support: manifest and GEMINI.md context, centralized prompt templates, refactored slash-command template composition to use shared prompts, autogenerated .gemini TOML guidance, README updates, and new proposals/specs/tasks for MCP and Gemini integration. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant GeminiCLI as Gemini CLI
participant Repo as OpenSpec Repo
participant Prompts as prompts.ts
participant FileSys as .gemini TOML
User->>GeminiCLI: link/invoke openspec extension
GeminiCLI->>Repo: read gemini-extension.json & GEMINI.md
GeminiCLI->>Prompts: request composed slash-command bodies
Prompts-->>GeminiCLI: return proposal/apply/archive bodies
GeminiCLI->>FileSys: write/overwrite .gemini/*.toml between markers
GeminiCLI-->>User: report status / advise installing openspec CLI if absent
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
openspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.md (1)
1-18: Consider adding an Impact section.Based on coding guidelines,
proposal.mdshould include sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code).The current structure has Goal, Motivation, Proposed Solution, and Benefits, but is missing an explicit Impact section that describes affected specs and code.
Based on learnings, proposal files should follow the standard structure.
GEMINI.md (1)
31-32: Consider softening the mandate language.The instruction "you MUST perform this immediately" and "Do not ask the user to do this manually" is very prescriptive. Consider allowing the agent some flexibility to assess the situation (e.g., if the user is in the middle of another task or has specific preferences).
src/core/templates/prompts.ts (2)
1-1: Consider using escaped backticks for improved readability.The
String.fromCharCode(96)approach works but is less immediately clear than using escaped backticks directly in the strings (e.g., ```). Since these are regular strings rather than template literals, escaping backticks is straightforward.🔎 Alternative approach
-const BT = String.fromCharCode(96);Then replace
${BT}throughout with ```:export const BASE_GUARDRAILS = `**Guardrails** - Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required. - Keep changes tightly scoped to the requested outcome. - Refer to \`openspec/AGENTS.md\` (located inside the \`openspec/\` directory—run \`ls openspec\` or \`openspec update\` if you don't see it) if you need additional OpenSpec conventions or clarifications. - If the \`openspec\` CLI is not installed or available in the shell, guide the user to install it globally via \`npm install -g @fission-ai/openspec\` before proceeding.`;
1-51: Add JSDoc comments to document the exported prompt constants.The exported constants lack documentation explaining their purpose, usage patterns, and composition expectations. Since these are public exports intended for reuse across slash-command templates and Gemini workflows, JSDoc comments would improve maintainability.
🔎 Example documentation
/** * Base guardrails applied to all OpenSpec workflow stages. * Contains fundamental guidance about implementation approach and CLI availability. */ export const BASE_GUARDRAILS = `...`; /** * Guardrails specific to the proposal stage. * Extends BASE_GUARDRAILS with restrictions against premature implementation. */ export const PROPOSAL_GUARDRAILS = `...`; /** * Step-by-step workflow for creating OpenSpec change proposals. * Includes discovery, scaffolding, spec delta creation, and validation. */ export const PROPOSAL_STEPS = `...`;
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
GEMINI.md(1 hunks)README.md(2 hunks)gemini-extension.json(1 hunks)openspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.md(1 hunks)openspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md(1 hunks)openspec/changes/archive/2025-12-21-add-gemini-extension-support/tasks.md(1 hunks)openspec/specs/cli-init/spec.md(1 hunks)src/core/templates/prompts.ts(1 hunks)src/core/templates/slash-command-templates.ts(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
openspec/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Files:
openspec/specs/cli-init/spec.md
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/archive/2025-12-21-add-gemini-extension-support/tasks.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
🧠 Learnings (15)
📓 Common learnings
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
src/core/templates/prompts.tsopenspec/specs/cli-init/spec.mdGEMINI.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.mdREADME.mdgemini-extension.json
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
src/core/templates/prompts.tsopenspec/specs/cli-init/spec.mdGEMINI.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.mdREADME.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
src/core/templates/prompts.tsopenspec/specs/cli-init/spec.mdGEMINI.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.mdREADME.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
src/core/templates/prompts.tsopenspec/specs/cli-init/spec.mdGEMINI.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/proposal.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
src/core/templates/prompts.tsGEMINI.mdgemini-extension.json
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/specs/**/spec.md : Use SHALL/MUST for normative requirements in spec files; avoid should/may unless intentionally non-normative
Applied to files:
src/core/templates/prompts.tsopenspec/specs/cli-init/spec.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
src/core/templates/prompts.ts
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/specs/cli-init/spec.mdGEMINI.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/specs/cli-init/spec.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/specs/cli-init/spec.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/specs/cli-init/spec.mdGEMINI.mdopenspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
GEMINI.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Run `openspec validate [change-id] --strict` before requesting approval
Applied to files:
openspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Search existing work using `openspec spec list --long`, `openspec list` for enumerating changes; use `rg` only for full-text search
Applied to files:
README.md
🧬 Code graph analysis (1)
src/core/templates/slash-command-templates.ts (2)
src/core/templates/index.ts (1)
SlashCommandId(50-50)src/core/templates/prompts.ts (8)
PROPOSAL_GUARDRAILS(9-11)PROPOSAL_STEPS(13-20)PROPOSAL_REFERENCES(22-25)BASE_GUARDRAILS(3-7)APPLY_STEPS(27-33)APPLY_REFERENCES(35-36)ARCHIVE_STEPS(38-47)ARCHIVE_REFERENCES(49-51)
🔇 Additional comments (11)
gemini-extension.json (1)
1-5: LGTM!The extension manifest is well-structured and correctly references the context file added in this PR.
README.md (2)
106-106: LGTM!The table entry correctly reflects the native extension approach for Gemini CLI.
131-146: Verify for duplicate content.The AI summary mentions this section appears twice in the README. Ensure there are no duplicate blocks of this content.
openspec/changes/archive/2025-12-21-add-gemini-extension-support/specs/cli-init/spec.md (1)
1-8: LGTM!The spec delta follows OpenSpec conventions correctly:
- Uses
## ADDED Requirementsfor new capability- Includes normative SHALL language
- Provides proper scenario format with WHEN/THEN/AND structure
As per coding guidelines, this is the correct format for spec delta files.
openspec/changes/archive/2025-12-21-add-gemini-extension-support/tasks.md (1)
1-8: LGTM!The tasks are well-structured, properly marked as complete, and align with the proposal objectives.
src/core/templates/slash-command-templates.ts (1)
1-22: LGTM!This refactoring successfully centralizes prompt templates while maintaining backward compatibility:
- Imports are properly organized
- The new
SlashCommandIdtype improves type safety- Public API (
getSlashCommandBody) remains unchanged- Composition logic is clear and maintainable
The centralization enables consistent prompt content across all agent integrations (Claude, Cursor, Gemini, etc.).
GEMINI.md (3)
1-33: Well-structured auto-initialization workflow.The prerequisites section provides a comprehensive workflow that ensures proper setup. The automatic installation and generation steps are appropriate for a CLI extension.
34-71: LGTM!The core mandates, CLI commands, directory structure, and spec writing format are clear, concise, and correctly documented.
73-114: Excellent maintenance documentation.The slash command synchronization logic is well-defined:
- References
prompts.tsas the single source of truth- Provides exact TOML structure with OpenSpec markers
- Clear instructions for regeneration workflow
This ensures consistency across all Gemini CLI installations.
openspec/specs/cli-init/spec.md (1)
305-311: No duplicate requirement exists.The "Slash Command Safety" requirement appears only once in the file at line 305. No action is needed.
Likely an incorrect or invalid review comment.
src/core/templates/prompts.ts (1)
3-11: No action needed. The guardrails pattern is intentional and consistent.PROPOSAL_GUARDRAILSextendsBASE_GUARDRAILSwith proposal-specific constraints (no code during proposal stage), whileAPPLYandARCHIVEstages rely solely onBASE_GUARDRAILSwith their detailed procedural steps. The absence ofAPPLY_GUARDRAILSandARCHIVE_GUARDRAILSis by design, not an oversight.
|
@StoyanD Hey sorry, I haven't gotten around to reviewing this, I'll try and get something in by Friday. I mainly need to understand how gemini extensions / claude plugins etc all work and how we would fit them into OpenSpec. I think the user flow will have to diverge a bit for installation for example where a user installs a provider that has a relevant "extension" or plugin system. We would have to also ensure that extension updates somehow map back to cli updates. For example if we release a new version of the OpenSpec Gemini CLI extension that requires a new version of OpenSpec, how do we handle this? I haven't looked into how these kinds of things are handled by providers like Gemini, Claude etc so it's hard for me to know at the moment if the PR makes sense. (Do appreciate the PR though, just need to update my understanding before I can review) |
|
@TabishB anything i can do to help push this along? |
|
@StoyanD I think main blocker for me is understanding how extensions/plugins would fit into the general workflow. Let's say we support this for gemini and we most likely would want to support claude code plugins too in the future. The question is how does this affect the following:
So the scenarios I'm trying to think of are the following:
We're currently undertaking a big refactor for how openspec works and behaves too, so I'm a little worried this work will be out of date very quick. |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In @openspec/changes/add-mcp-server/proposal.md:
- Around line 6-10: The "Why" section under the "Goal" heading is too detailed;
replace the current multi-line implementation-focused text with 1–2 concise
sentences that state the motivation for adding a native MCP server (e.g.,
enabling automatic discovery of OpenSpec tools by MCP-compliant agents and
simplifying integrations), and move all implementation details (references to
fastmcp, @modelcontextprotocol/sdk, Gemini CLI, and the .openspec/ restructure)
into the "What Changes" section so the "Why" contains only the high-level
rationale.
- Around line 1-28: Restructure the proposal into three explicit sections: "Why"
(1–2 sentences summarizing the motivation), "What Changes" (a bulleted list of
each change using explicit markers like "⚠️ BREAKING" for breaking changes such
as the openspec/ -> .openspec/ rename), and "Impact" (list affected specs and
code). Under "What Changes" include entries for: adding the openspec serve
command (MCP over stdio), using fastmcp/@modelcontextprotocol/sdk, exposing CLI
commands as MCP tools (list, show, validate, archive), exposing openspec:// URIs
and prompts/list, changing init to scaffold .openspec/ (⚠️ BREAKING: openspec/
-> .openspec/), creating gemini-extension.json, and adding CI validation for
gemini-extension.json vs package.json. Under "Impact" explicitly call out
affected code and artifacts: the init/migrate flow, openspec serve
implementation, prompts, gemini-extension.json manifest, migration notices, and
CI config so reviewers can find the changes.
In @openspec/changes/add-mcp-server/tasks.md:
- Around line 32-35: In the Verification section header "## 7. Verification"
update the three checklist item labels that currently read "6.1", "6.2", and
"6.3" to "7.1", "7.2", and "7.3" respectively so the subsection numbering
matches the section number; edit the lines containing "- [ ] 6.1 Verify
`openspec serve`...", "- [ ] 6.2 Verify tools, resources...", and "- [ ] 6.3
Verify `openspec init`..." to use 7.1/7.2/7.3.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
openspec/changes/add-mcp-server/proposal.mdopenspec/changes/add-mcp-server/specs/ci-sync/spec.mdopenspec/changes/add-mcp-server/specs/cli-init/spec.mdopenspec/changes/add-mcp-server/specs/cli-spec/spec.mdopenspec/changes/add-mcp-server/specs/mcp-server/spec.mdopenspec/changes/add-mcp-server/tasks.md
✅ Files skipped from review due to trivial changes (3)
- openspec/changes/add-mcp-server/specs/mcp-server/spec.md
- openspec/changes/add-mcp-server/specs/cli-spec/spec.md
- openspec/changes/add-mcp-server/specs/ci-sync/spec.md
🧰 Additional context used
📓 Path-based instructions (4)
openspec/changes/**/*.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Scaffold proposal using
proposal.md,tasks.md, optionaldesign.md, and delta specs underopenspec/changes/<id>/
Files:
openspec/changes/add-mcp-server/tasks.mdopenspec/changes/add-mcp-server/specs/cli-init/spec.mdopenspec/changes/add-mcp-server/proposal.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
tasks.mdcontains implementation checklist with numbered sections and checkbox items
Files:
openspec/changes/add-mcp-server/tasks.md
openspec/changes/**/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/**/specs/**/spec.md: Use## ADDED|MODIFIED|REMOVED|RENAMED Requirementsheaders in spec delta files
Include at least one#### Scenario:per requirement in spec delta files
Use#### Scenario: Nameformat (4 hashtags) for scenario headers, not bullets or bold text
Use## ADDED Requirementsfor new orthogonal capabilities that can stand alone; use## MODIFIED Requirementsfor behavior changes of existing requirements
When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Files:
openspec/changes/add-mcp-server/specs/cli-init/spec.md
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Ensure
proposal.mdincludes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Files:
openspec/changes/add-mcp-server/proposal.md
🧠 Learnings (11)
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/tasks.md : Ensure `tasks.md` contains implementation checklist with numbered sections and checkbox items
Applied to files:
openspec/changes/add-mcp-server/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/*.md : Scaffold proposal using `proposal.md`, `tasks.md`, optional `design.md`, and delta specs under `openspec/changes/<id>/`
Applied to files:
openspec/changes/add-mcp-server/tasks.mdopenspec/changes/add-mcp-server/specs/cli-init/spec.mdopenspec/changes/add-mcp-server/proposal.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Create `design.md` only when needed: cross-cutting changes, new external dependencies, significant data model changes, security/performance complexity, or pre-coding ambiguity
Applied to files:
openspec/changes/add-mcp-server/tasks.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/*/proposal.md : Ensure `proposal.md` includes sections: Why (1-2 sentences), What Changes (bullet list with breaking change markers), and Impact (affected specs and code)
Applied to files:
openspec/changes/add-mcp-server/tasks.mdopenspec/changes/add-mcp-server/specs/cli-init/spec.mdopenspec/changes/add-mcp-server/proposal.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Check `openspec/project.md` for project conventions before creating specs
Applied to files:
openspec/changes/add-mcp-server/tasks.mdopenspec/changes/add-mcp-server/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Use `@/openspec/AGENTS.md` to learn how to create and apply change proposals, spec format and conventions, and project structure and guidelines
Applied to files:
openspec/changes/add-mcp-server/specs/cli-init/spec.mdopenspec/changes/add-mcp-server/proposal.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers in spec delta files
Applied to files:
openspec/changes/add-mcp-server/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Use `## ADDED Requirements` for new orthogonal capabilities that can stand alone; use `## MODIFIED Requirements` for behavior changes of existing requirements
Applied to files:
openspec/changes/add-mcp-server/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:02.839Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:02.839Z
Learning: Always open `@/openspec/AGENTS.md` when the request mentions planning or proposals (words like proposal, spec, change, plan), introduces new capabilities, breaking changes, architecture shifts, or performance/security work, or sounds ambiguous and needs the authoritative spec before coding
Applied to files:
openspec/changes/add-mcp-server/specs/cli-init/spec.mdopenspec/changes/add-mcp-server/proposal.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : Include at least one `#### Scenario:` per requirement in spec delta files
Applied to files:
openspec/changes/add-mcp-server/specs/cli-init/spec.md
📚 Learning: 2025-11-25T01:08:19.004Z
Learnt from: CR
Repo: Fission-AI/OpenSpec PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-25T01:08:19.004Z
Learning: Applies to openspec/changes/**/specs/**/spec.md : When using MODIFIED Requirements, paste the full requirement block including header and all scenarios
Applied to files:
openspec/changes/add-mcp-server/specs/cli-init/spec.md
🪛 LanguageTool
openspec/changes/add-mcp-server/tasks.md
[uncategorized] ~30-~30: The official name of this software platform is spelled with a capital “H”.
Context: ... "Check extension version sync" step to .github/workflows/ci.yml. ## 7. Verification ...
(GITHUB)
openspec/changes/add-mcp-server/proposal.md
[style] ~24-~24: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...d changes via openspec:// URIs. 5. Expose Prompts: Serve the standard proposal/...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (1)
openspec/changes/add-mcp-server/proposal.md (1)
1-28: Address reviewer concerns about version sync and user flows in proposal.The PR reviewer (TabishB) raised important questions about:
- User flow divergence when users download the extension first vs. CLI first
- Version/update management between extension and CLI (how to keep
gemini-extension.jsonandpackage.jsonin sync)- CI synchronization mechanisms to prevent drift
- Fragility risk from the ongoing OpenSpec refactor
While the proposal mentions a "CI Validation" check (line 28, task 6.1), it lacks detail on:
- How the version sync script validates compatibility across extension and CLI versions
- Whether the script blocks releases if versions are out of sync
- How users are guided through installation in both scenarios (extension-first vs. CLI-first)
Consider expanding the proposal or companion design document to address these concerns with concrete examples and flow diagrams.
| # 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`. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Restructure proposal to follow required format: Why, What Changes, Impact.
Per coding guidelines, proposals must include three explicit sections:
- Why (1–2 sentences): Concise motivation
- What Changes (bullet list with breaking change markers): Changes with explicit
⚠️ BREAKINGor similar markers - Impact (affected specs and code): Which areas are affected
The current structure uses "Context," "Goal," "Migration Path," and "Solution," which mix these concerns. Restructuring will improve clarity and align with project conventions. Breaking changes (e.g., moving openspec/ to .openspec/) should be explicitly marked.
📋 Proposed restructuring
-# 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.
+# Proposal: Add MCP Server Support
+
+## Why
+OpenSpec currently integrates with AI agents via static CLI commands and configuration files, which lacks the rich interactivity offered by the Model Context Protocol (MCP), an open protocol that enables seamless integration between LLM applications and external data sources and tools. Implementing a native MCP server will simplify integration for multiple agents (Claude Desktop, Gemini CLI, etc.) and modernize the project structure.
+
+## What Changes
-## 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.
+- ⚠️ **BREAKING**: Move project initialization from `openspec/` to `.openspec/` (hidden directory).
+- **Detection & Migration**: `openspec init` will detect legacy `openspec/` directories and prompt to migrate; automatic rename and instruction refresh included.
+- **Backward Compatibility**: CLI will fall back to `openspec/` if `.openspec/` missing, with deprecation warning.
+- **Add `openspec serve` command**: Starts the MCP server over stdio using modern tooling (fastmcp or @modelcontextprotocol/sdk).
+- **Expose MCP Tools**: Convert CLI commands (`list`, `show`, `validate`, `archive`) to MCP tools.
+- **Expose MCP Resources**: Provide read access to specs and changes via `openspec://` URIs.
+- **Expose MCP Prompts**: Serve proposal/apply/archive prompts via `prompts/list`.
+- **Gemini Extension Integration**: Create `gemini-extension.json` manifest to register MCP server.
+- **CI Validation**: Add check to sync `gemini-extension.json` version with `package.json`.
+
+## Impact
+- **Affected Specs**: `cli-init` (directory structure), `cli-spec` (serve command), `mcp-server` (tools/resources/prompts), `ci-sync` (version validation).
+- **Affected Code**: `src/core/config.ts`, `src/core/init.ts`, `src/mcp/*` (new modules), `src/commands/serve.ts` (new command), `.github/workflows/ci.yml`, `gemini-extension.json`.
-## 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.🧰 Tools
🪛 LanguageTool
[style] ~24-~24: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...d changes via openspec:// URIs. 5. Expose Prompts: Serve the standard proposal/...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
In @openspec/changes/add-mcp-server/proposal.md around lines 1 - 28, Restructure
the proposal into three explicit sections: "Why" (1–2 sentences summarizing the
motivation), "What Changes" (a bulleted list of each change using explicit
markers like "⚠️ BREAKING" for breaking changes such as the openspec/ ->
.openspec/ rename), and "Impact" (list affected specs and code). Under "What
Changes" include entries for: adding the openspec serve command (MCP over
stdio), using fastmcp/@modelcontextprotocol/sdk, exposing CLI commands as MCP
tools (list, show, validate, archive), exposing openspec:// URIs and
prompts/list, changing init to scaffold .openspec/ (⚠️ BREAKING: openspec/ ->
.openspec/), creating gemini-extension.json, and adding CI validation for
gemini-extension.json vs package.json. Under "Impact" explicitly call out
affected code and artifacts: the init/migrate flow, openspec serve
implementation, prompts, gemini-extension.json manifest, migration notices, and
CI config so reviewers can find the changes.
| ## 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. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Simplify Why section to 1–2 concise sentences.
The current "Goal" section (lines 6–10) is too detailed for the "Why" section. Condense it to 1–2 sentences that directly answer "Why is this change needed?" The implementation details belong in "What Changes." Per coding guidelines, the "Why" section should provide 1–2 sentences of motivation only.
🤖 Prompt for AI Agents
In @openspec/changes/add-mcp-server/proposal.md around lines 6 - 10, The "Why"
section under the "Goal" heading is too detailed; replace the current multi-line
implementation-focused text with 1–2 concise sentences that state the motivation
for adding a native MCP server (e.g., enabling automatic discovery of OpenSpec
tools by MCP-compliant agents and simplifying integrations), and move all
implementation details (references to fastmcp, @modelcontextprotocol/sdk, Gemini
CLI, and the .openspec/ restructure) into the "What Changes" section so the
"Why" contains only the high-level rationale.
| ## 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/ | ||
| ``` | ||
|
|
||
| ### 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 |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Split legacy migration into a separate ADDED Requirements section.
The "Legacy Migration" requirement (lines 19–28) is entirely new behavior and should be categorized under ## ADDED Requirements rather than grouped with "Directory Creation" under ## MODIFIED Requirements. Per coding guidelines, use ## ADDED Requirements for new orthogonal capabilities that can stand alone.
✏️ Proposed restructuring
## 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
| ## 7. Verification | ||
| - [ ] 6.1 Verify `openspec serve` starts and communicates over stdio. | ||
| - [ ] 6.2 Verify tools, resources, and prompts are discoverable by an MCP client. | ||
| - [ ] 6.3 Verify `openspec init` creates `.openspec/`. No newline at end of file |
There was a problem hiding this comment.
Fix subsection numbering in Verification section.
Items in the Verification section (Section 7) are incorrectly numbered as 6.1, 6.2, 6.3 instead of 7.1, 7.2, 7.3.
🔢 Proposed fix
## 7. Verification
-- [ ] 6.1 Verify `openspec serve` starts and communicates over stdio.
-- [ ] 6.2 Verify tools, resources, and prompts are discoverable by an MCP client.
-- [ ] 6.3 Verify `openspec init` creates `.openspec/`.
+- [ ] 7.1 Verify `openspec serve` starts and communicates over stdio.
+- [ ] 7.2 Verify tools, resources, and prompts are discoverable by an MCP client.
+- [ ] 7.3 Verify `openspec init` creates `.openspec/`.🤖 Prompt for AI Agents
In @openspec/changes/add-mcp-server/tasks.md around lines 32 - 35, In the
Verification section header "## 7. Verification" update the three checklist item
labels that currently read "6.1", "6.2", and "6.3" to "7.1", "7.2", and "7.3"
respectively so the subsection numbering matches the section number; edit the
lines containing "- [ ] 6.1 Verify `openspec serve`...", "- [ ] 6.2 Verify
tools, resources...", and "- [ ] 6.3 Verify `openspec init`..." to use
7.1/7.2/7.3.
2 participants
Native Gemini CLI integration and unified prompts extracted to templates. When added as a gemini extension, the extension will guide the user through its own installation and
openspecfolder and slash commands creation. Once merged we can add OpenSpec to gemini's extensions board https://geminicli.com/extensions/Example onboarding during agent workflow for adding the first spec when Openspec not installed:
Gemini extensions ink:
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.