OpenSpec

OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. No API keys required.

🎯 Why OpenSpec?

AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.

Key outcomes:

• Human and AI stakeholders agree on specs before work begins
• Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable
• Shared visibility into what's proposed, active, or archived
• Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else

🌟 What's New in v1.8.0

🚀 OPSX Workflow - The New Standard

OPSX is now the default workflow for OpenSpec. It's a fluid, iterative approach that replaces rigid phases with flexible actions you can take anytime.

Key improvements:

• Schema-driven: Edit schema.yaml and templates/*.md to customize workflows without code changes
• Fluid actions: Create, implement, update, archive — do any of them anytime
• Hackable: Experiment with instructions, test granularly, customize workflows
• Team-ready: Create workflows that match how your team actually works

# Quick start with OPSX
openspec init
# Then in your AI chat:
/opsx:explore      # Think through ideas
/opsx:propose      # Create change with planning artifacts
/opsx:apply        # Implement tasks
/opsx:archive      # Archive when done

🆕 New AI Tool Integrations

• Atlassian Rovo Dev CLI support (--tools rovodev)
• MiniMax Code as a global skills-only tool target
• Enhanced GitHub Copilot integration with opt-in cloud coding agent files
• Improved Codex skills now use the shared .agents directory

� New Plan Artifact

• Mandatory planning artifact with implementation guidance
• Code maps showing files to create, modify, and delete
• Implementation order with sequenced steps
• Test plans covering unit, integration, and manual testing
• Risk assessment with mitigation strategies
• Dependency chain: specs → design → plan → tasks

🔧 Enhanced Features

• OPSX Modify Command (experimental): /opsx:modify for revising planning artifacts before implementation
• Dependency propagation: Automatic updates to dependent artifacts when modifying
• Conflict detection: Identifies conflicts with manual edits before modification
• Modification history: Tracks all artifact changes with timestamps

�🔧 Enhanced Features

• Capability retirement: Automatically retire capabilities when changes remove their last requirements
• Multi-language validation: openspec validate now treats English SHALL/MUST as guidance in normal mode
• Better task progress: Counts indented sub-tasks and provides more accurate progress tracking
• Improved archive guidance: Better error messages and flag suggestions for non-interactive environments

📚 How It Works

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

1. Draft a change proposal that captures the spec updates you want
2. Review the proposal with your AI assistant until everyone agrees
3. Implement tasks that reference the agreed specs
4. Archive the change to merge the approved updates back into the source-of-truth specs

🚀 Getting Started

Prerequisites

• Node.js >= 20.19.0 - Check your version with node --version

Step 1: Install the CLI globally

Option A: Using npm

npm install -g @codewalla_india/openspec@latest

Verify installation:

openspec --version

Option B: Using Nix (NixOS and Nix package manager)

nix run github:codewalla-engineering/openspec-upstream-sync -- init

Or install to your profile:

nix profile install github:codewalla-engineering/openspec-upstream-sync

Step 2: Initialize OpenSpec in your project

cd your-project
openspec init

This creates:

• openspec/ directory for your specs and changes
• AI tool integration files (slash commands or skills)
• Optional project configuration (openspec/config.yaml)

Step 3: Start using OpenSpec

In your AI assistant's chat:

# Explore an idea (recommended first step)
/opsx:explore

# Create a new change
/opsx:propose add-dark-mode

# Implement the tasks
/opsx:apply

# Archive when complete
/opsx:archive

🛠️ Supported AI Tools

OpenSpec integrates with 30+ AI coding assistants. Here are the most popular:

Native Slash Commands

These tools have built-in OpenSpec commands:

| Tool | Commands | |------|----------| | Claude Code | /openspec:proposal, /openspec:apply, /openspec:archive | | Cursor | /openspec-proposal, /openspec-apply, /openspec:archive | | GitHub Copilot | /openspec-proposal, /openspec-apply, /openspec-archive | | Windsurf | /openspec-proposal, /openspec-apply, /openspec-archive | | Continue | /openspec-proposal, /openspec-apply, /openspec-archive | | Cline | Workflows in .clinerules/workflows/ directory | | Codex | /openspec-proposal, /openspec-apply, /openspec-archive (auto-installed) |

AGENTS.md Compatible

These tools automatically read workflow instructions from openspec/AGENTS.md:

| Tools | |-------| | Amp • Jules • Others |

For the complete list of supported tools, see Supported Tools.

📖 Documentation

Start Here

• Getting Started - Install, initialize, and run your first change
• OPSX Workflow - The new fluid, schema-driven workflow
• How Commands Work - Where to type slash commands vs terminal commands

Core Concepts

• Core Concepts at a Glance - The mental model on one page
• Concepts - In-depth explanation of specs, changes, artifacts
• Glossary - Every term defined in one place

Day-to-Day Usage

• Workflows - Common patterns and when to reach for each command
• Examples & Recipes - Full walkthroughs of real changes
• Writing Good Specs - What strong requirements look like
• Reviewing Changes - The two-minute review pass
• Commands Reference - Complete reference for all OPSX commands including /opsx:modify

Advanced

• Customization - Project config, custom schemas, shared context
• Multi-Language - Generate artifacts in other languages
• Stores (beta) - Plan across repos and teams

Help

• FAQ - Quick answers to common questions
• Troubleshooting - Concrete fixes for concrete failures
• Migration Guide - Moving from legacy workflow to OPSX

🔄 Migration from Legacy Workflow

If you're using the old OpenSpec workflow, the Migration Guide explains what changed and how to transition. Your existing work is safe — the migration is non-destructive.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines. The most valuable contributions are:

• Documentation improvements
• Bug fixes
• New AI tool integrations
• Workflow enhancements

📄 License

MIT License - see LICENSE file for details

🆘 Support

• Discord: discord.gg/YctCnvvshC for questions, ideas, and help
• GitHub Issues: github.com/codewalla-engineering/openspec-upstream-sync/issues for bugs and feature requests
• Feedback: Run openspec feedback "your message" to send feedback directly from your terminal

🌟 Acknowledgments

Built with ❤️ for the AI-assisted development community. Special thanks to all contributors who make OpenSpec better every day.

⚡ Powered by OPSX Workflow — the future of spec-driven development