The most loved spec framework.

Our philosophy:

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

Tip

New workflow now available! We've rebuilt OpenSpec with a new artifact-guided workflow.

Run /opsx:propose "your idea" to get started. → Learn more here

Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions.

See it in action

You: /opsx:explore
AI:  What would you like to explore?
You: I want dark mode but I'm not sure how to do it cleanly.
AI:  Let me look at your styling setup...
     Cleanest path here: CSS variables + a small theme context,
     with system-preference detection. No new dependencies. Scope it?
You: Yes, let's do it.

You: /opsx:propose add-dark-mode
AI:  Created openspec/changes/add-dark-mode/
     ✓ 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!

You: /opsx:apply
AI:  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!

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

What do the specs actually look like?

Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the specs/ folder created above:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Your AI writes these; you review the plan before any code is written.

OpenSpec is built with OpenSpec — browse this repo's live specs and in-flight changes for real examples at scale.

OpenSpec Dashboard

Why teams adopt OpenSpec

Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.

Stores are the answer — planning in a repo of its own. The same openspec/ shape you already know (specs and changes), shared by git push like anything else. One source of truth your whole team and every coding agent can read, across every repo.

• Cross-repo features — one change, one plan, even when the code lands in three repos.
• Shared requirements — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
• Plan before code — capture the plan in the store now; the code repos catch up later.

Stores are in beta. Start with the Stores User Guide.

Quick Start

Requires Node.js 20.19.0 or higher.

Install OpenSpec globally:

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

Then navigate to your project directory and initialize:

cd your-project
openspec init

Want your AI to do it? Paste the setup prompt into your coding assistant — it installs the CLI, runs openspec init, and verifies the result.

Now talk to your AI:

• Not sure what to build yet? Start with /opsx:explore, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. (Explore guide)
• Already know what you want? Go straight to /opsx:propose <what-you-want-to-build>.

Both are in the default profile. If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.

/opsx:propose is the canonical name; your tool may spell it /opsx-propose (Cursor, GitHub Copilot), @opsx-propose (Amazon Q) or $openspec-propose (Codex). openspec init prints the right form for the tools you picked — see How To Invoke.

Note

Not sure if your tool is supported? View the full list – we support 30+ tools and growing.

Also works with pnpm, yarn, bun, and nix. See installation options.

Docs

Start here: the Documentation Home maps everything. New to OpenSpec? Read Getting Started, then How Commands Work (where you actually type /opsx:propose).

→ Getting Started: first steps
→ Explore First: think it through with /opsx:explore before you commit
→ How Commands Work: where slash commands run vs the CLI
→ Core Concepts at a Glance: the whole mental model, one page
→ Examples & Recipes: real changes, start to finish
→ Workflows: combos and patterns
→ Existing Projects: adopt OpenSpec on a brownfield codebase
→ Editing a Change: update artifacts, go back, reconcile manual edits
→ Commands: slash commands & skills
→ CLI: terminal reference
→ Stores: plan in a separate repo, shared across your team (beta)
→ Supported Tools: tool integrations & install paths
→ Concepts: how it all fits
→ Multi-Language: multi-language support
→ Customization: make it yours
→ FAQ · Troubleshooting · Glossary: quick help

Community schemas

Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how github/spec-kit's community extension catalog handles tool integrations.

→ Browse the catalog in the customization docs.

Why OpenSpec?

AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.

• Agree before you build — human and AI align on specs before code gets written
• Stay organized — each change gets its own folder with proposal, specs, design, and tasks
• Work fluidly — update any artifact anytime, no rigid phase gates
• Use your tools — works with 30+ AI assistants via slash commands

How we compare

vs. Spec Kit (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.

vs. Kiro (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.

vs. nothing — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.

Updating OpenSpec

Upgrade the package

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

Refresh agent instructions

Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:

openspec update

Plugins

OpenSpec supports a plugin system for extending lifecycle hooks, gate types, and schemas without modifying core.

Quick Start

1. Create a plugin directory with a manifest:

openspec/plugins/my-plugin/
  plugin.yaml
  hooks/
    my-hook.md

2. Define plugin.yaml:

name: my-plugin
version: 1.0.0
description: My custom lifecycle hooks
openspec: ">=1.2.0"

hooks:
  archive.post:
    - id: notify
      handler:
        type: command
        run: "echo 'Archived ${OPENSPEC_CHANGE_NAME}'"

3. Enable in openspec/config.yaml:

schema: spec-driven
plugins:
  - my-plugin

4. Verify: openspec plugin list

Plugin Manifest (plugin.yaml)

Field	Type	Required	Description
name	string	Yes	Plugin name
version	string	Yes	Semver version
description	string	No	Brief description
openspec	string	No	Compatible OpenSpec version range (e.g., ">=1.2.0")
schemas	string[]	No	Schema names bundled in schemas/ subdirectory
config	object	No	Config schema (category → field → {type, required, default})
hooks	object	No	Lifecycle hooks by hook point
gates	GateDefinition[]	No	Custom gate types for schema apply.gates
skill_overlays	object	No	Content to inject into generated skills/commands per workflow

Hook Points

Hook Point	When	Use Case
propose.pre	Before proposal creation	Pre-checks
propose.post	After proposal creation	Notifications
apply.pre	Before apply phase	Git branch creation, env setup
apply.post	After all tasks complete	Cleanup, notifications
archive.pre	Before archive operation	Validation, blocking checks
archive.post	After archive completes	Obsidian sync, git cleanup

Handler Types

Hooks and gates support three handler types:

• command — Execute a shell command. Exit code 0 = success.
• prompt — Output a markdown prompt for the AI agent to execute.
• both — Run a command first, then output a prompt with {{command_output}}.

hooks:
  archive.post:
    # Shell command (deterministic)
    - id: git-cleanup
      handler:
        type: command
        run: "git branch -d feature/${OPENSPEC_CHANGE_NAME}"
        ignore_failure: true

    # AI prompt (judgment-based)
    - id: obsidian-sync
      handler:
        type: prompt
        file: hooks/obsidian-sync.md

Environment Variables

Command handlers receive these environment variables:

Variable	Description
OPENSPEC_CHANGE_NAME	Change name
OPENSPEC_CHANGE_DIR	Absolute path to change directory
OPENSPEC_SCHEMA	Schema name
OPENSPEC_PROJECT_ROOT	Absolute path to project root
OPENSPEC_PHASE	Current phase (propose, apply, archive)
OPENSPEC_HOOK_POINT	Hook point (e.g., archive.post)
OPENSPEC_ARCHIVE_DIR	Archive destination (archive.post only)

Plugin config values are available as OPENSPEC_PLUGIN_CONFIG_{CATEGORY}_{FIELD}.

Plugin Config

Plugins can declare configuration requirements. Users provide values in config.yaml:

# plugin.yaml
config:
  obsidian:
    vault:
      type: string
      required: true
    target_pattern:
      type: string
      default: "modules/{module}"

# config.yaml
plugins:
  - my-plugin
plugin_config:
  my-plugin:
    obsidian:
      vault: "my-specs"

Skill Overlays

Plugins can inject content into generated skill and command files. When openspec update runs, overlay content is appended to the corresponding workflow's output.

# plugin.yaml
skill_overlays:
  apply:
    append: overlays/apply-orchestration.md
  explore:
    append: overlays/explore-research.md

Create the overlay files in your plugin directory:

my-plugin/
  plugin.yaml
  overlays/
    apply-orchestration.md    # Appended to the apply skill/command
    explore-research.md       # Appended to the explore skill/command

After openspec update --force, the generated skill files include the overlay content. Multiple plugins' overlays are appended in whitelist order. Missing overlay files produce a warning but don't block generation.

Currently only append is supported. Future versions may add prepend and replace_section.

Plugin-Provided Schemas and Gates

Plugins can bundle schemas in a schemas/ subdirectory and custom gate types. See openspec plugin info <name> for details on any installed plugin.

Resolution Order

Plugins resolve from three locations (highest priority first):

1. Project-local: openspec/plugins/<name>/
2. User-global: ~/.local/share/openspec/plugins/<name>/
3. Package built-in: <openspec-package>/plugins/<name>/

Only plugins listed in config.yaml's plugins array are loaded. Order in the array determines hook execution order.

CLI Commands

openspec plugin list          # Show all available plugins
openspec plugin list --json   # Machine-readable output
openspec plugin info <name>   # Detailed plugin information

Orchestration

OpenSpec supports parallel execution hints via --subagents and --teams flags. The CLI declares WHAT can be parallel; the AI harness decides HOW.

Flags

openspec instructions apply --change my-change --subagents --json
openspec instructions apply --change my-change --teams --json

Flags are mutually exclusive and available on all openspec instructions <phase> commands.

Plugin Orchestration Declaration

Plugins declare parallel capabilities on gates and hooks:

# plugin.yaml
gates:
  - id: claude-review
    handler:
      type: prompt
      file: gates/claude-review.md
    orchestration:
      parallel_with: ["codex-review"]   # Can run alongside codex-review
      preferred_mode: teams              # Suggest teams mode

  - id: codex-review
    handler:
      type: prompt
      file: gates/codex-review.md
    orchestration:
      parallel_with: ["claude-review"]   # Bidirectional declaration required
      preferred_mode: teams

Both sides must declare parallel_with (bidirectional). Unidirectional declarations emit a warning and default to sequential.

Schema Orchestration Override

Schemas can override plugin declarations at the project level:

# schema.yaml
apply:
  orchestration:
    parallel_groups:
      - gates: ["claude-review", "codex-review"]
        parallel: true
        mode: teams
        synthesis: require-both-pass    # Both must pass

Two-Layer Resolution

User flag (--teams)  →  mode only, doesn't force parallel grouping
         ↓
Schema orchestration →  final decision on parallel groups + synthesis
         ↓
Plugin declaration   →  default capabilities (parallel_with)
         ↓
Default              →  sequential execution

Schema always wins. Plugin is the default when schema is silent.

Task Group Parallelism

Tasks in tasks.md are grouped by ## N. section headers:

• Intra-group: Tasks within a group run in parallel (parallel: true)
• Inter-group: Sequential by default (group N depends on N-1)
• Explicit parallel: Add <!-- parallel-with: 1 --> in a section header to override

Domain tags [domain: backend] enable --teams assignment to specialized agents.

Gate Result Persistence

Gate results are written to .gates/ in the change directory (gitignored):

openspec/changes/my-change/
└── .gates/
    ├── claude-review.json
    ├── codex-review.json
    └── synthesis.json

Synthesis Strategies

Strategy	Behavior
require-both-pass	All gates in the group must pass
any-pass	At least one gate must pass
majority	More than half must pass

Usage Notes

Model selection: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.

Context hygiene: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.

Contributing

Small fixes — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.

Larger changes — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.

When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.

AI-generated code is welcome — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").

Development

• Install dependencies: pnpm install
• Build: pnpm run build
• Test: pnpm test
• Develop CLI locally: pnpm run dev or pnpm run dev:cli
• Conventional commits (one-line): type(scope): subject

Other

Telemetry

OpenSpec collects anonymous usage stats.

We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.

Opt-out (any one is enough):

• openspec config set telemetry.enabled false (global config; unset means on)
• export OPENSPEC_TELEMETRY=0 or export DO_NOT_TRACK=1 (env overrides config)

Maintainers & Advisors

See MAINTAINERS.md for the list of core maintainers and advisors who help guide the project.

License

MIT