OpenSpec Examples & Use Cases

See real-world examples of how OpenSpec helps teams build better software with AI coding assistants. From simple features to complex refactoring, these examples demonstrate the power of spec-driven development.

Example 1: Adding Dark Mode

A complete workflow for adding a dark mode feature to a web application.

Step 1: Create the Change

You: /opsx:new add-dark-mode

AI Response:

Created openspec/changes/add-dark-mode/
Ready to create: proposal

Step 2: Generate Planning Documents

You: /opsx:ff  # "fast-forward"

AI Response:

✓ proposal.md — why we're doing this, what's changing
✓ specs/ — requirements and scenarios
✓ design.md — technical approach
✓ tasks.md — implementation checklist
Ready for implementation!

Step 3: Review the Proposal

The proposal document includes:

  • Why dark mode is needed (user requests, accessibility)
  • What's changing (theme system, CSS variables, toggle component)
  • Scope and boundaries

Step 4: Review Specs

The specs folder contains:

  • Functional requirements (toggle behavior, persistence)
  • Non-functional requirements (performance, accessibility)
  • User scenarios and edge cases

Step 5: Review Design

The design document outlines:

  • Technical approach (CSS variables, React Context)
  • Architecture decisions
  • Implementation strategy

Step 6: Implement

You: /opsx:apply

AI Response:

Implementing tasks...
✓ 1.1 Add theme context provider
✓ 1.2 Create toggle component
✓ 2.1 Add CSS variables
✓ 2.2 Wire up localStorage
All tasks complete!

Step 7: Archive

You: /opsx:archive

AI Response:

Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
Specs updated. Ready for the next feature.

Example 2: API Integration

Adding a new API integration with proper error handling and testing.

Use Case

Integrate a payment processing API into an e-commerce application.

OpenSpec Workflow

  1. /opsx:new integrate-payment-api - Create proposal
  2. /opsx:ff - Generate specs covering API endpoints, error handling, retry logic, and security
  3. Review design document for authentication strategy and data flow
  4. /opsx:apply - Implement with proper error handling and logging
  5. /opsx:archive - Archive and update system specs

Benefits

  • Clear API contract defined before implementation
  • Error scenarios documented and handled
  • Security considerations addressed upfront
  • Specs serve as documentation for future developers

Example 3: Refactoring Legacy Code

Using OpenSpec to safely refactor a complex legacy module.

Use Case

Refactor a monolithic authentication module into a modular, testable system.

OpenSpec Workflow

  1. /opsx:new refactor-auth-module - Document current behavior
  2. /opsx:ff - Create specs that preserve all existing functionality
  3. Design document outlines new architecture while maintaining backward compatibility
  4. Tasks broken down into safe, incremental steps
  5. /opsx:apply - Implement with tests at each step
  6. /opsx:archive - Update system architecture docs

Benefits

  • No functionality lost during refactoring
  • Clear migration path documented
  • Team alignment on new architecture
  • Specs ensure backward compatibility

Example 4: Feature Flag Implementation

Adding a feature flag system for gradual rollouts.

Use Case

Implement a feature flag system to enable gradual feature rollouts and A/B testing.

OpenSpec Workflow

  1. /opsx:new add-feature-flags - Propose feature flag system
  2. /opsx:ff - Specs cover flag storage, evaluation, and management UI
  3. Design document outlines flag service architecture
  4. /opsx:apply - Implement flag service and admin interface
  5. /opsx:archive - Document flag system in main specs

Best Practices from Examples

  • Start with clear proposals - Define why and what before how
  • Review before implementing - Always review specs and design before applying
  • Break down complex changes - Use tasks.md to create manageable steps
  • Document decisions - Design documents capture architectural decisions
  • Archive completed work - Keep specs updated and maintain project history

Get Started

Ready to try OpenSpec with your own project?

  1. Follow the getting started guide
  2. Start with a small feature to learn the workflow
  3. Gradually apply OpenSpec to larger changes
  4. Share your examples with the community!