[!IMPORTANT] This package is a community-maintained fork of the official Fission-AI/OpenSpec project, with additional behavior and modifications that may differ from upstream. It is not an official OpenSpec release from Fission AI.

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

What's different in this fork?

This fork keeps the upstream OpenSpec workflow, but extends project config injection so workflow guidance can be customized beyond artifact generation.

• openspec/config.yaml context is injected into artifact instructions and also into the apply and archive workflow instruction surfaces.
• rules supports both artifact IDs and reserved workflow targets: apply and archive.
• rules.apply can guide implementation behavior, such as sub-agent usage, testing preferences, or repo-specific delivery rules.
• rules.archive can add post-archive guidance, such as documentation cleanup, knowledge base updates, or handoff steps.
• Archive guidance remains additive: this fork does not change archive readiness checks, warnings, or enforcement semantics.
• Existing artifact-scoped config continues to work, so older proposal / specs / design / tasks rules remain compatible.

Example:

schema: spec-driven

context: |
  Monorepo with pnpm workspaces.
  Prefer minimal, targeted changes.

rules:
  proposal:
    - Describe user-visible behavior first
  apply:
    - Use sub-agents only when the task clearly benefits from parallel work
  archive:
    - Update internal docs after archiving

See it in action

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.

Quick Start

Requires Node.js 20.19.0 or higher.

Install OpenSpec globally:

npm install -g openspec-plus

Then navigate to your project directory and initialize:

cd your-project
openspec init

Now tell your AI: /opsx:propose <what-you-want-to-build>

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.

[!NOTE] Not sure if your tool is supported? View the full list – we support 25+ tools and growing.

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

Docs

→ Getting Started: first steps → Workflows: combos and patterns → Commands: slash commands & skills → CLI: terminal reference → Supported Tools: tool integrations & install paths → Concepts: how it all fits → Multi-Language: multi-language support → Customization: make it yours

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 20+ 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 openspec-plus@latest

Refresh agent instructions

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

openspec update

Usage Notes

Model selection: OpenSpec works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 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

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: export OPENSPEC_TELEMETRY=0 or export DO_NOT_TRACK=1

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

License

MIT