|
| 1 | +--- |
| 2 | +"@fission-ai/openspec": major |
| 3 | +--- |
| 4 | + |
| 5 | +## OpenSpec 1.0 — The OPSX Release |
| 6 | + |
| 7 | +The workflow has been rebuilt from the ground up. OPSX replaces the old phase-locked `/openspec:*` commands with an action-based system where AI understands what artifacts exist, what's ready to create, and what each action unlocks. |
| 8 | + |
| 9 | +### Breaking Changes |
| 10 | + |
| 11 | +- **Old commands removed** — `/openspec:proposal`, `/openspec:apply`, and `/openspec:archive` no longer exist |
| 12 | +- **Config files removed** — Tool-specific instruction files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `project.md`) are no longer generated |
| 13 | +- **Migration** — Run `openspec init` to upgrade. Legacy artifacts are detected and cleaned up with confirmation. |
| 14 | + |
| 15 | +### From Static Prompts to Dynamic Instructions |
| 16 | + |
| 17 | +**Before:** AI received the same static instructions every time, regardless of project state. |
| 18 | + |
| 19 | +**Now:** Instructions are dynamically assembled from three layers: |
| 20 | +1. **Context** — Project background from `config.yaml` (tech stack, conventions) |
| 21 | +2. **Rules** — Artifact-specific constraints (e.g., "propose spike tasks for unknowns") |
| 22 | +3. **Template** — The actual structure for the output file |
| 23 | + |
| 24 | +AI queries the CLI for real-time state: which artifacts exist, what's ready to create, what dependencies are satisfied, and what each action unlocks. |
| 25 | + |
| 26 | +### From Phase-Locked to Action-Based |
| 27 | + |
| 28 | +**Before:** Linear workflow — proposal → apply → archive. Couldn't easily go back or iterate. |
| 29 | + |
| 30 | +**Now:** Flexible actions on a change. Edit any artifact anytime. The artifact graph tracks state automatically. |
| 31 | + |
| 32 | +| Command | What it does | |
| 33 | +|---------|--------------| |
| 34 | +| `/opsx:explore` | Think through ideas before committing to a change | |
| 35 | +| `/opsx:new` | Start a new change | |
| 36 | +| `/opsx:continue` | Create one artifact at a time (step-through) | |
| 37 | +| `/opsx:ff` | Create all planning artifacts at once (fast-forward) | |
| 38 | +| `/opsx:apply` | Implement tasks | |
| 39 | +| `/opsx:verify` | Validate implementation matches artifacts | |
| 40 | +| `/opsx:sync` | Sync delta specs to main specs | |
| 41 | +| `/opsx:archive` | Archive completed change | |
| 42 | +| `/opsx:bulk-archive` | Archive multiple changes with conflict detection | |
| 43 | +| `/opsx:onboard` | Guided 15-minute walkthrough of complete workflow | |
| 44 | + |
| 45 | +### From Text Merging to Semantic Spec Syncing |
| 46 | + |
| 47 | +**Before:** Spec updates required manual merging or wholesale file replacement. |
| 48 | + |
| 49 | +**Now:** Delta specs use semantic markers that AI understands: |
| 50 | +- `## ADDED Requirements` — New requirements to add |
| 51 | +- `## MODIFIED Requirements` — Partial updates (add scenario without copying existing ones) |
| 52 | +- `## REMOVED Requirements` — Delete with reason and migration notes |
| 53 | +- `## RENAMED Requirements` — Rename preserving content |
| 54 | + |
| 55 | +Archive parses these at the requirement level, not brittle header matching. |
| 56 | + |
| 57 | +### From Scattered Files to Agent Skills |
| 58 | + |
| 59 | +**Before:** 8+ config files at project root + slash commands scattered across 21 tool-specific locations with different formats. |
| 60 | + |
| 61 | +**Now:** Single `.claude/skills/` directory with YAML-fronted markdown files. Auto-detected by Claude Code, Cursor, Windsurf. Cross-editor compatible. |
| 62 | + |
| 63 | +### New Features |
| 64 | + |
| 65 | +- **Onboarding skill** — `/opsx:onboard` walks new users through their first complete change with codebase-aware task suggestions and step-by-step narration (11 phases, ~15 minutes) |
| 66 | + |
| 67 | +- **21 AI tools supported** — Claude Code, Cursor, Windsurf, Continue, Gemini CLI, GitHub Copilot, Amazon Q, Cline, RooCode, Kilo Code, Auggie, CodeBuddy, Qoder, Qwen, CoStrict, Crush, Factory, OpenCode, Antigravity, iFlow, and Codex |
| 68 | + |
| 69 | +- **Interactive setup** — `openspec init` shows animated welcome screen and searchable multi-select for choosing tools. Pre-selects already-configured tools for easy refresh. |
| 70 | + |
| 71 | +- **Customizable schemas** — Define custom artifact workflows in `openspec/schemas/` without touching package code. Teams can share workflows via version control. |
| 72 | + |
| 73 | +### Bug Fixes |
| 74 | + |
| 75 | +- Fixed Claude Code YAML parsing failure when command names contained colons |
| 76 | +- Fixed task file parsing to handle trailing whitespace on checkbox lines |
| 77 | +- Fixed JSON instruction output to separate context/rules from template — AI was copying constraint blocks into artifact files |
| 78 | + |
| 79 | +### Documentation |
| 80 | + |
| 81 | +- New getting-started guide, CLI reference, concepts documentation |
| 82 | +- Removed misleading "edit mid-flight and continue" claims that weren't implemented |
| 83 | +- Added migration guide for upgrading from pre-OPSX versions |
0 commit comments