AI IDE Workflow Guide

Complete guide to using SpecFact CLI with AI IDEs (Cursor, VS Code + Copilot, Claude Code, etc.)

Overview

SpecFact CLI integrates with AI-assisted IDEs through slash commands that enable a seamless workflow: SpecFact finds gaps -> AI IDE helps apply changes -> SpecFact validates. This guide explains the complete workflow from setup to validation.

SpecFact CLI itself does not contain built-in AI. The AI lives in your IDE of choice. SpecFact provides prompt templates and deterministic commands so that copilot-driven work stays grounded in the CLI workflow.

Key Benefits:

✅ You control the AI - Use your preferred AI model
✅ SpecFact validates - Ensure AI-generated code meets contracts
✅ No lock-in - Works with any AI IDE
✅ CLI-first - Works offline, no account required

Setup Process

Step 1: Initialize IDE Integration

Run the init ide 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

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

What it does:

Detects your IDE (or uses --ide flag)
Copies prompt templates from installed bundle modules (or an optional dev checkout under resources/prompts/) to the IDE-specific location
Creates/updates IDE settings if needed
Makes slash commands available in your IDE
Optionally installs required packages (beartype, icontract, crosshair-tool, pytest)

Related: IDE Integration Guide - Complete setup instructions

Available Slash Commands

Once initialized, the following slash commands are available in your IDE:

Core Workflow Commands

Slash Command	Purpose	Equivalent CLI Command
`/specfact.01-import`	Import from codebase	`specfact code import`
`/specfact.02-plan`	Plan management	`specfact project snapshot`
`/specfact.03-review`	Review plan	`specfact project snapshot`
`/specfact.04-sdd`	Create SDD manifest	`specfact govern enforce sdd`
`/specfact.05-enforce`	SDD enforcement	`specfact govern enforce sdd`
`/specfact.06-sync`	Sync operations	`specfact project sync bridge`
`/specfact.07-contracts`	Contract management	See AI IDE skill `/specfact.07-contracts`

Advanced Commands

Slash Command	Purpose	Equivalent CLI Command
`/specfact.compare`	Compare plans	`specfact project devops-flow --stage plan --action compare`
`/specfact.validate`	Validation suite	`specfact code repro`
`/specfact.backlog-refine`	Backlog refinement (AI IDE interactive loop, provided by the backlog bundle)	`specfact backlog refine github \\| ado`

For an end-to-end tutorial on backlog refine with your AI IDE (story quality, underspecification, DoR, custom templates), see Tutorial: Backlog Refine with AI IDE.

Complete Workflow: Prompt Generation → AI IDE → Validation Loop

Workflow Overview

graph TD
    A[SpecFact Analysis] -->|Find Gaps| B[Generate Prompt]
    B -->|Copy to IDE| C[AI IDE]
    C -->|Generate Fix| D[Apply Changes]
    D -->|SpecFact Validate| E[Validation]
    E -->|Pass| F[Complete]
    E -->|Fail| B

Step-by-Step Workflow

1. Run SpecFact Analysis

# Import from codebase
specfact code import my-project --repo .

# Run validation to find gaps
specfact code repro --verbose

2. Generate AI-Ready Prompt

# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows
# Use your AI IDE skill (/specfact.07-contracts) for fix and test prompt workflows

3. Use AI IDE to Apply Fixes

In Cursor / VS Code / Copilot:

Open the generated prompt file
Copy the prompt content
Paste into AI IDE chat
AI generates the fix
Review and apply the changes

Example:

# After generating prompt
cat .specfact/prompts/fix-prompt-GAP-001.md

# Copy content to AI IDE chat
# AI generates fix
# Apply changes to code

4. Validate with SpecFact

# Run validation
specfact code repro --verbose

# Validate spec compliance
specfact spec validate --bundle my-project

# Enforce SDD compliance
specfact govern enforce sdd --bundle my-project

5. Iterate if Needed

If validation fails, return to step 2 and generate a new prompt for the remaining issues.

Integration with Command Chains

The AI IDE workflow integrates with several command chains:

AI-Assisted Code Enhancement Chain

Workflow: /specfact.07-contracts (AI IDE skill) → spec validate → repro

Test Generation from Specifications Chain

Workflow: /specfact.07-contracts (AI IDE skill) → spec generate-tests → pytest

Gap Discovery & Fixing Chain

Workflow: repro --verbose → /specfact.07-contracts (AI IDE skill) → enforce sdd

Related: Gap Discovery & Fixing Chain

Example: Complete AI IDE Workflow

Scenario: Add Contracts to Existing Code

# 1. Analyze codebase
specfact code import legacy-api --repo .

# 2. Find gaps
specfact code repro --verbose

# 3. Use AI IDE skill for contract enhancement
# Use your AI IDE skill (/specfact.07-contracts) for contract enhancement workflows
# /specfact.07-contracts legacy-api FEATURE-001

# 4. Validate
specfact spec validate --bundle legacy-api
specfact code repro --verbose
specfact govern enforce sdd --bundle legacy-api

Supported IDEs

SpecFact CLI supports the following AI IDEs:

✅ Cursor - .cursor/commands/
✅ VS Code / GitHub Copilot - .github/prompts/ + .vscode/settings.json
✅ Claude Code - .claude/commands/
✅ 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/

Troubleshooting

Slash Commands Not Showing

Issue: Slash commands don’t appear in IDE

Solution:

# Re-initialize with force
specfact init ide --ide cursor --force

AI-Generated Code Fails Validation

Issue: AI-generated code doesn’t pass SpecFact validation