Skip to content

OpenSpec Integration

mcp-guide integrates with OpenSpec, an AI-native system for spec-driven development, providing automatic monitoring and command access for managing changes and specifications.

For more information on OpenSpec, visit https://openspec.dev

Overview

OpenSpec integration enables structured change management with automatic monitoring of project changes. The integration validates OpenSpec availability, tracks changes, and provides prompt commands for common operations.

Integration Behaviour

Validation and Shared CLI State

OpenSpec is enabled exclusively per project. When enabled, mcp-guide validates the project's OpenSpec configuration and tracks changes. CLI availability and version are shared machine-wide: an enabled project checks them when the global state is absent or older than 24 hours, then other enabled projects reuse that result.

The shared CLI check verifies that openspec is installed and records its version.

Project validation checks: - Confirms openspec/config.yaml exists (required by current OpenSpec versions) - Tests that openspec list executes successfully (even if no changes exist)

Session Monitoring

During each session, the integration: - Reuses the shared OpenSpec CLI availability and version result for up to 24 hours - Refreshes change list hourly or after agent makes OpenSpec changes - Caches responses to minimize redundant command execution

User Experience

The integration may seem verbose in some agents as it executes OpenSpec commands to maintain synchronisation. These commands are necessary for the integration to function correctly. Frequent use of guide tools and prompt commands helps keep OpenSpec and the MCP server synchronised.

OpenSpec Commands

When OpenSpec is enabled, additional OpenSpec commands become available. Some commands invoke the OpenSpec CLI directly (with response caching). Use guide://_help for the full command list, or guide://_help/openspec%2Finit and guide://_help/openspec%2Flist for help on specific OpenSpec commands.

guide://_openspec/init (:openspec/init) Initialise OpenSpec in the current project using the openspec command. This creates the required directory structure and openspec/config.yaml file.

guide://_openspec/propose (:openspec/propose; aliases: openspec/new, openspec/create) Initiate a new OpenSpec change by creating the change directory structure and proposal document. Emphasises dialogue with the user before writing documents. Optionally creates tasks.md for tracking implementation.

guide://_openspec/list (:openspec/list) List all OpenSpec changes in the project. Triggers a refresh of the change list from OpenSpec CLI.

guide://_openspec/show (:openspec/show) Show details for the current or a specific OpenSpec change, including proposal, tasks, and spec deltas.

guide://_openspec/validate (:openspec/validate) Validate the current or a specific OpenSpec change against schema requirements and structural rules.

guide://_openspec/status (:openspec/status) Get the completion status and percentage for an OpenSpec change based on completed tasks.

guide://_openspec/archive (:openspec/archive) Archive a completed OpenSpec change, moving it to the archive directory and optionally updating main specs.

guide://_openspec/schemas (:openspec/schemas) Discover available OpenSpec schemas in the project for creating new specifications.

Integration with the workflow feature flag

When both OpenSpec and workflow feature flags are enabled, they work together:

  • The workflow issue field typically specifies the OpenSpec change name (e.g., add-feature-x or add-feature-x/sub-spec)
  • mcp-guide provides its own versions of OpenSpec prompts:
  • guide://_workflow/implement - Equivalent to openspec-apply (with full project guidelines)
  • guide://_openspec/archive - Equivalent to openspec-archive
  • guide://_openspec/propose - Equivalent to openspec-propose

Otherwise, OpenSpec and workflow operate independently.

OpenSpec Template Context

When OpenSpec is enabled, OpenSpec information is available in content templates via {{openspec.*}} variables:

  • {{openspec.available}} - Boolean indicating if OpenSpec is available
  • {{openspec.version}} - OpenSpec version string
  • {{openspec.changes}} - Array of change objects with name, status, and task counts
  • {{openspec.show}} - Details of currently shown change
  • {{openspec.status}} - Status information for current change

Configuration

The openspec Feature Flag

This project-only feature flag enables OpenSpec integration:

Boolean: - false / absent: OpenSpec integration disabled (default) - true: Enable OpenSpec integration with automatic monitoring

When enabled, the OpenSpecTask runs periodically to monitor changes and maintain synchronisation with the OpenSpec CLI.