9 Practical Use Cases for OpenSpec: From Ideation to Production

OpenSpec is a lightweight, spec-driven framework that sits between human developers and AI coding assistants, enabling agreement-driven development through a structured workflow of exploration, proposal, implementation, and archiving.

OpenSpec, developed by Fission-AI/OpenSpec, introduces a spec-first architecture that separates agreement from implementation. By maintaining a source of truth in openspec/specs/ and tracking proposed work in openspec/changes/, the framework supports AI-assisted development across diverse scenarios—from experimental ideation to enterprise CI/CD pipelines.

Core Architecture Overview

Before diving into specific scenarios, understanding OpenSpec's dual-folder structure clarifies how these use cases function.

The Spec-First Philosophy

The openspec/specs/ directory serves as the immutable source of truth for your codebase. According to the documentation in docs/overview.md, this folder contains the current specifications that define what your system does, independent of how it is implemented.

The Change Lifecycle

Parallel to the specs folder, openspec/changes/ contains transient work-in-progress. Each feature receives its own subdirectory (e.g., openspec/changes/add-dark-mode/) containing proposal.md, specs/delta.md, design.md, and tasks.md. This separation enables the /opsx:* slash commands to manage the lifecycle from proposal to archive.

Primary Use Cases for OpenSpec

Exploratory Ideation with /opsx:explore

When you have a vague concept but need structured options before committing resources, the /opsx:explore command analyzes your existing codebase and proposes concrete solutions. As documented in docs/explore.md, this command delivers implementation plans without creating persistent artifacts, allowing you to iterate on ideas without polluting your spec history.

Feature Proposals via /opsx:propose

Convert clear requirements into tracked development work using /opsx:propose <feature-name>. This command, detailed in docs/opsx.md, generates a complete change folder containing:

• proposal.md – Business justification and scope
• specs/delta.md – Required specification changes
• design.md – Technical architecture
• tasks.md – Implementation checklist

Automated Implementation with /opsx:apply

Once specifications are agreed upon, /opsx:apply executes the tasks defined in your change folder. As implemented in the workflow described in docs/workflows.md, this command updates your codebase incrementally, marking completed tasks in tasks.md while maintaining synchronization between implementation and specification.

Archiving and Truth-Synchronization using /opsx:archive

Completed features require integration back into the canonical specs. The /opsx:archive command merges delta specifications from openspec/changes/<feature>/specs/ into openspec/specs/, then moves the entire change folder to openspec/changes/archive/. This process, explained in docs/overview.md#archiving-folds-the-change-back-into-the-truth, ensures your source of truth remains current while preserving historical context.

Brownfield Adoption in Existing Codebases

For teams with large, pre-existing codebases, OpenSpec supports incremental adoption without requiring full re-documentation. The docs/existing-projects.md guide demonstrates how to begin with a single delta spec in openspec/changes/, allowing you to add specifications only where active development occurs, rather than retrofitting entire legacy systems.

CI/CD Automation and Pipeline Integration

OpenSpec integrates into non-interactive pipelines through CLI options documented in docs/cli.md. The --no-interactive flag enables openspec init and openspec update to run in automated environments. The cli-init specification explicitly mentions CI/CD use cases, allowing the framework to participate in build processes, automated testing, and deployment verification without human intervention.

Multi-Language Artifact Generation

Teams operating across linguistic boundaries can configure OpenSpec to output specifications, documentation, and code snippets in languages other than English. The docs/multi-language.md configuration guide covers localization settings that affect artifact generation throughout the /opsx:* workflow.

Cross-Team Collaboration via Shared Stores

For organizations managing multiple repositories, the shared store architecture (currently in beta) enables coordination across team boundaries. As described in docs/stores-beta/user-guide.md, a dedicated store repository can host centralized specs and changes, allowing cross-repo planning and review while maintaining the core openspec/specs/ and openspec/changes/ structure.

Custom Workflow Extensions

OpenSpec adapts to internal processes through its customization layer. The docs/customization.md documentation outlines how to implement custom schemas, plugins, and agents, extending the base /opsx:* command set to fit specific organizational requirements or toolchain integrations.

Getting Started: A Practical Example

Implementing OpenSpec in your repository follows a straightforward initialization pattern:

# Install the CLI (Node 20+ required)

npm install -g @fission-ai/openspec@latest

# Initialize OpenSpec in your project

cd my-project
openspec init

After initialization, explore an idea without committing to implementation:

# In your AI chat window:

/opsx:explore

When ready to formalize a feature:

# Propose a concrete feature (e.g., dark-mode toggle)

/opsx:propose add-dark-mode

This creates the following structure:

openspec/
├─ specs/
│   └─ ui/
│       └─ dark-mode.md          # delta spec added by proposal

└─ changes/
    └─ add-dark-mode/
        ├─ proposal.md
        ├─ specs/
        │   └─ delta.md
        ├─ design.md
        └─ tasks.md

Execute and finalize:

# Let the AI implement the change

/opsx:apply

# Archive completed work

/opsx:archive

Summary

• OpenSpec enables agreement-before-execution development through its spec-first architecture.
• The /opsx:explore command supports ideation without artifact pollution, while /opsx:propose formalizes features into tracked change folders.
• Implementation occurs via /opsx:apply and concludes with /opsx:archive merging deltas into openspec/specs/.
• Brownfield projects can adopt OpenSpec incrementally without full re-documentation.
• CI/CD integration uses --no-interactive flags for pipeline automation.
• Enterprise features include multi-language output and shared store architectures for cross-team collaboration.

Frequently Asked Questions

How does OpenSpec handle existing codebases without comprehensive documentation?

OpenSpec supports brownfield adoption through incremental specification. Rather than requiring full documentation upfront, you initialize the framework and create delta specs only for active features in openspec/changes/. As documented in docs/existing-projects.md, this approach lets teams benefit from spec-driven development without retrofitting legacy systems retroactively.

Can OpenSpec integrate with existing CI/CD pipelines?

Yes. The CLI supports non-interactive modes via flags like --no-interactive, enabling openspec init and openspec update to run in automated pipelines. The docs/cli.md reference explicitly documents CI/CD use cases, allowing the framework to participate in build processes, testing stages, and deployment verification without manual intervention.

What is the difference between /opsx:explore and /opsx:propose?

/opsx:explore is a transient, conversation-only command that analyzes your codebase and presents implementation options without creating files. /opsx:propose, conversely, generates persistent artifacts in openspec/changes/<feature>/, including proposal.md, delta specs, and task lists, formally tracking the work for implementation and archival.

How does the shared store beta feature work for distributed teams?

The shared store architecture allows multiple repositories to reference a centralized spec repository. According to docs/stores-beta/user-guide.md, teams can host canonical specs and active changes in a dedicated store repo, enabling cross-repository planning and review while maintaining the core openspec/specs/ and openspec/changes/ folder structure in each consuming project.

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