How to Integrate OpenSpec with Other AI Coding Tools

OpenSpec integrates with AI coding assistants through a declarative plugin architecture that generates skill and command files for each tool based on definitions in src/core/config.ts.

OpenSpec is a flexible framework designed to extend the capabilities of AI coding assistants. If you need to integrate OpenSpec with other tools, the system provides a plug-in architecture that supports dozens of assistants including Claude, Cursor, Gemini CLI, and GitHub Copilot through automatic detection and file generation.

Understanding the OpenSpec Integration Architecture

The integration operates through three declarative layers that map tool identifiers to file system artifacts. This architecture allows OpenSpec to automatically manage skill files and commands across multiple AI assistants without manual configuration.

Tool Definitions in config.ts

All supported assistants are enumerated in src/core/config.ts. Each entry in the AI_TOOLS configuration defines a tool ID, human-readable name, availability status, and the target directory where OpenSpec deposits skill and command files for that assistant. This central configuration acts as the single source of truth for which tools OpenSpec can interface with.

File Layout and Artifact Generation

When you run openspec init or openspec update, OpenSpec creates two distinct artifact types per selected tool:

• Skills: Markdown files describing the assistant's capabilities (e.g., openspec-propose), stored under <tool-dir>/skills/openspec-*/SKILL.md
• Commands: Slash-command or prompt files that the assistant invokes (e.g., opsx-propose), with locations varying by tool as documented in docs/supported-tools.md

Runtime Detection and Wiring

Each tool's detectionPaths field tells OpenSpec when a tool is present on the host system. When these paths exist, OpenSpec marks the tool as detected and writes the appropriate files, making the assistant immediately aware of the new commands and skills without requiring manual imports.

Step-by-Step Integration Process

Follow these steps to integrate OpenSpec with your preferred AI coding tools:

1. Select tools: Run openspec init --tools claude,cursor to generate skill and command skeletons for Claude Code and Cursor.
2. Choose a profile: Execute openspec config profile core to select the default workflow set (propose, explore, apply, sync, archive).
3. Apply changes: Use openspec update to write or overwrite per-tool files according to the selected profile and workflow flags.
4. CI/CD mode: Run openspec init --tools all --profile core for non-interactive setup in automated pipelines, or use --tools none to skip tool configuration entirely.

Initializing OpenSpec for Specific Tools

Use the openspec init command with specific flags to target individual assistants or groups:

# Initialise OpenSpec for a specific set of assistants

openspec init --tools claude,cursor

# Initialise for all supported assistants (useful for a dev box)

openspec init --tools all

# Skip tool configuration entirely (e.g., when only using the internal CLI)

openspec init --tools none

# Override the default profile and add a custom workflow

openspec config profile core
openspec config add-workflow new
openspec update

Once initialized, you can invoke the generated commands directly in your AI assistant. For example, in Claude Code:

/opsx-propose

CI/CD and Automated Integration

For automated pipelines, OpenSpec supports non-interactive configuration through command-line flags:

# Install only the skill layer for a subset of tools

openspec init --tools github-copilot,gemini --profile core

This mode ensures that build agents can provision OpenSpec capabilities without prompting for user input, using the declarative definitions in src/core/config.ts to determine file placement.

Extending OpenSpec for Custom Tools

Because the mapping of tool ID to file locations is declarative, adding a new assistant requires only two modifications:

1. Add a new entry to AI_TOOLS in src/core/config.ts specifying the tool ID, name, skill directory, and optional detection paths.
2. Extend the markdown table in docs/supported-tools.md with the new tool's skill and command path patterns.

You can also generate skill files manually for custom integrations:

// Example: create a custom skill for a new tool "myai"
import { writeFileSync } from 'fs';
const skillPath = '.myai/skills/openspec-propose/SKILL.md';
const skillContent = `# openspec-propose\n\nGenerate a proposal based on the current spec.`;

writeFileSync(skillPath, skillContent);

Key Integration Files

File	Purpose
src/core/config.ts	Central list of AI tool definitions (AI_TOOLS)
docs/supported-tools.md	Human-readable table of per-tool skill and command paths
docs/cli.md	Full CLI reference for init, update, and profile commands
docs/commands.md	Description of generated slash commands and skills
bin/openspec.js	Entry point for the openspec executable

Summary

• OpenSpec uses a declarative plug-in architecture defined in src/core/config.ts to manage integrations with AI coding assistants.
• The openspec init and openspec update commands automatically generate skills and commands in tool-specific directories based on the AI_TOOLS configuration.
• Detection paths automatically enable integrations when target tools are installed on the system, requiring no manual configuration.
• You can extend support to new assistants by adding entries to the AI_TOOLS array and updating docs/supported-tools.md with path patterns.

Frequently Asked Questions

What AI coding tools does OpenSpec support?

OpenSpec supports Claude, Cursor, Gemini CLI, GitHub Copilot, and others. The complete list is defined in src/core/config.ts, with per-tool file locations and path patterns documented in docs/supported-tools.md.

How does OpenSpec detect if a tool is installed?

Each tool entry includes a detectionPaths field that specifies file system paths unique to that assistant. When OpenSpec finds these paths on the host system, it marks the tool as available and generates the appropriate skill and command files automatically.

Can I use OpenSpec in CI/CD pipelines without interactive prompts?

Yes. Use the --tools flag with specific tool IDs (or all/none), combined with --profile to specify a workflow set. This enables non-interactive setup suitable for automated pipelines and containerized build environments.

How do I add support for a custom AI assistant not listed in the config?

Add a new entry to the AI_TOOLS array in src/core/config.ts specifying the tool ID, display name, skill directory, and optional detection paths. Then document the skill and command path patterns in docs/supported-tools.md to maintain the human-readable reference.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}