IDE Integration with SpecFact CLI

Status: ✅ AVAILABLE (v0.4.2+)
Last Updated: 2025-11-09

CLI-First Approach: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.

Important: SpecFact CLI does not provide built-in AI. IDE integration means SpecFact installs prompt templates and slash commands that your chosen IDE copilot can use to run SpecFact as part of a guided command chain.

Terminal Output: The CLI automatically detects embedded terminals (Cursor, VS Code) and CI/CD environments, adapts formatting automatically, and falls back to ASCII-safe rendering when the active terminal encoding cannot display UTF-8 symbols. See Troubleshooting for details.

Overview

SpecFact CLI supports IDE integration through prompt templates and grouped AI skills that work with various AI-assisted IDEs. These files are copied to IDE-specific locations and automatically registered by the IDE as slash commands or skills. The AI stays in your IDE; SpecFact remains the deterministic CLI the prompts call.

See real examples: Integration Showcases - 5 complete examples showing bugs fixed via IDE integrations

Supported IDEs:

✅ Cursor - .cursor/commands/
✅ VS Code / GitHub Copilot - .github/prompts/ + .vscode/settings.json
✅ Claude Code - .claude/commands/
✅ Claude Code Skills - .claude/skills/<skill>/SKILL.md
✅ Codex CLI - .codex/skills/<skill>/SKILL.md
✅ Mistral Vibe - .vibe/skills/<skill>/SKILL.md
✅ Gemini CLI - .gemini/commands/
✅ Qwen Code - .qwen/commands/
✅ opencode - .opencode/command/
✅ Windsurf - .windsurf/workflows/
✅ Kilo Code - .kilocode/workflows/
✅ Auggie - .augment/commands/
✅ Roo Code - .roo/commands/
✅ CodeBuddy - .codebuddy/commands/
✅ Amp - .agents/commands/
✅ Amazon Q Developer - .amazonq/prompts/

Quick Start

Step 1: Initialize IDE Integration

Run the specfact init command in your repository:

# Auto-detect IDE
specfact init

# Or specify IDE explicitly
specfact init ide --ide cursor
specfact init ide --ide vscode
specfact init ide --ide copilot
specfact init ide --ide codex

# Install required packages for contract enhancement
specfact init --install-deps

# Initialize for specific IDE and install dependencies
specfact init ide --ide cursor --install-deps

What it does:

Detects your IDE (or uses --ide flag)
Discovers prompt templates from installed workflow modules first, then copies them to the IDE-specific location
Creates/updates VS Code settings if needed
Makes slash commands or grouped AI skills available in your IDE
Optionally installs required packages for contract enhancement (if --install-deps is provided):
- beartype>=0.22.4 - Runtime type checking
- icontract>=2.7.1 - Design-by-contract decorators
- crosshair-tool>=0.0.97 - Contract exploration
- pytest>=8.4.2 - Testing framework

Step 2: Use Slash Commands in Your IDE

Once initialized, you can use slash commands directly in your IDE’s AI chat:

In Cursor / VS Code / Copilot:

# Core workflow commands (numbered for natural progression)
/specfact.01-import legacy-api --repo .
/specfact.02-plan init legacy-api
/specfact.02-plan add-feature --bundle legacy-api --key FEATURE-001 --title "User Auth"
/specfact.03-review legacy-api
/specfact.04-sdd legacy-api
/specfact.05-enforce legacy-api
/specfact.06-sync --adapter speckit --repo . --bidirectional
/specfact.07-contracts legacy-api --apply all-contracts  # Analyze, generate prompts, apply contracts sequentially

# Advanced commands
/specfact.compare --bundle legacy-api
/specfact.validate --repo .

The IDE automatically recognizes these commands and exposes the corresponding prompt templates. Those prompts then guide your AI copilot to call SpecFact commands.

How It Works

Prompt Templates

Slash-command targets use markdown prompt templates (not executable CLI commands). Skill-based targets use grouped SKILL.md files that collect several related workflows for one source/module. They:

Are owned by installed workflow modules - Bundle-specific prompts ship with their corresponding module packages
Get copied to IDE locations - specfact init ide discovers installed module resources and copies them to IDE-specific directories
Registered automatically - The IDE reads these files and makes them available as slash commands or skills
Fall back safely during transition - If no installed module prompt payloads are present yet, SpecFact can still use packaged core fallback resources
Provide enhanced prompts - Templates include detailed instructions for the AI assistant

Template Format

Each template follows this structure:

---
description: Command description for IDE display
---

## User Input

```text
$ARGUMENTS

Goal

Detailed instructions for the AI assistant…

Execution Steps

Parse arguments…
Execute command…
Generate output…

### IDE Registration

**How IDEs discover slash commands:**

- **VS Code / Copilot**: Reads `.github/prompts/*.prompt.md` files listed in `.vscode/settings.json` under `chat.promptFilesRecommendations`
- **Cursor**: Automatically discovers `.cursor/commands/*.md` files
- **Other IDEs**: Follow their respective discovery mechanisms

---

## Available Slash Commands

**Complete Reference**: [Prompts README](/prompts/) - Full slash commands reference with examples

**Workflow Guide**: [AI IDE Workflow Guide](/guides/ai-ide-workflow/) - Complete workflow from setup to validation

## Available Slash Commands

**Core Workflow Commands** (numbered for workflow ordering):

| Command | Description | CLI Equivalent |
|---------|-------------|----------------|
| `/specfact.01-import` | Import codebase into plan bundle | `specfact code import <bundle-name>` |
| `/specfact.02-plan` | Plan management (init, add-feature, add-story, update-idea, update-feature, update-story) | `specfact project snapshot --bundle <bundle-name>` |
| `/specfact.03-review` | Review plan and promote through stages | `specfact project devops-flow --stage develop --bundle <bundle-name>`, `specfact project health-check` |
| `/specfact.04-sdd` | Create SDD manifest from plan | `specfact project snapshot <bundle-name>` |
| `/specfact.05-enforce` | Validate SDD and contracts | `specfact govern enforce sdd <bundle-name>` |
| `/specfact.06-sync` | Sync with external tools or repository | `specfact project sync bridge --adapter <adapter>` |
| `/specfact.07-contracts` | Contract enhancement workflow: analyze → generate prompts → apply sequentially | `specfact code analyze contracts` (use your AI IDE skill `/specfact.07-contracts` for contract enhancement workflows) |

**Advanced Commands** (no numbering):

| Command | Description | CLI Equivalent |
|---------|-------------|----------------|
| `/specfact.compare` | Compare manual vs auto plans | `specfact project regenerate` |
| `/specfact.validate` | Run validation suite | `specfact code repro` |
| `/specfact.generate-contracts-prompt` | Generate AI IDE prompt for adding contracts | Use your AI IDE skill (`/specfact.07-contracts`) for contract enhancement workflows |

---

## Examples

### Example 1: Initialize for Cursor

```bash
# Run init in your repository
cd /path/to/my-project
specfact init ide --ide cursor

# Output:
# ✓ Initialization Complete
# Copied 5 template(s) to .cursor/commands/
#
# You can now use SpecFact slash commands in Cursor!
# Example: /specfact.01-import legacy-api --repo .

Now in Cursor:

Open Cursor AI chat
Type /specfact.01-import legacy-api --repo .
Cursor recognizes the command and provides enhanced prompts

Example 2: Initialize for VS Code / Copilot

# Run init in your repository
specfact init ide --ide vscode

# Output:
# ✓ Initialization Complete
# Copied 5 template(s) to .github/prompts/
# Updated VS Code settings: .vscode/settings.json

VS Code settings.json:

{
  "chat": {
    "promptFilesRecommendations": [
      ".github/prompts/specfact.01-import.prompt.md",
      ".github/prompts/specfact.02-plan.prompt.md",
      ".github/prompts/specfact.03-review.prompt.md",
      ".github/prompts/specfact.04-sdd.prompt.md",
      ".github/prompts/specfact.05-enforce.prompt.md",
      ".github/prompts/specfact.06-sync.prompt.md",
      ".github/prompts/specfact.07-contracts.prompt.md",
      ".github/prompts/specfact.compare.prompt.md",
      ".github/prompts/specfact.validate.prompt.md"
    ]
  }
}

Example 3: Update Templates

If you update SpecFact CLI, run init again to update templates:

# Re-run init to update templates (use --force to overwrite)
specfact init ide --ide cursor --force

Advanced Usage

Custom Template Locations

By default, templates are copied from SpecFact CLI’s package resources. To use custom templates:

Create your own templates in a custom location
Modify specfact init to use custom path (future feature)

IDE-Specific Customization

Different IDEs may require different template formats:

Markdown (Cursor, Claude, etc.): Direct .md files
TOML (Gemini, Qwen): Converted to TOML format automatically
VS Code: .prompt.md files with settings.json integration

The specfact init command handles all conversions automatically.

Troubleshooting

Slash Commands Not Showing in IDE

Issue: Commands don’t appear in IDE autocomplete

Solutions:

Verify files exist:

ls .cursor/commands/specfact-*.md  # For Cursor
ls .github/prompts/specfact-*.prompt.md  # For VS Code

Re-run init:
```
specfact init ide --ide cursor --force
```
Restart IDE: Some IDEs require restart to discover new commands

VS Code Settings Not Updated

Issue: VS Code settings.json not created or updated