{"slug": "openspec-spec-driven-development-for-claude-code-and-codex", "title": "OpenSpec: spec-driven development for Claude Code and Codex", "summary": "Fission AI maintains OpenSpec, an MIT-licensed open-source tool that makes AI coding agents such as Claude Code and Codex write proposals, requirement specs, design docs and task lists before implementing code. The tool, at version 1.14.0 with roughly 71,000 GitHub stars as of October 5, 2026, installs its workflow as ordinary SKILL.md agent skills and stores specs and proposed changes as plain Markdown under an openspec/ directory. It requires Node.js 20.19.0 or later and is installed via npm or Homebrew.", "body_md": "OpenSpec is a free, open-source tool that makes your AI coding agent write down what it is going to build before it builds it. This tutorial covers the `/opsx:propose` workflow in Claude Code and Codex, and the hosted [OpenSpec Propose skill](https://skillgild.dev/skills/openspec-propose). Each change gets a short proposal, requirement specs, a design and a task list that you review first. Then the agent implements the tasks, and the agreed specs become the project's record of how the software should behave.\n\nIt is maintained by Fission AI under the MIT license. On October 5, 2026 the [GitHub repository](https://github.com/Fission-AI/OpenSpec) had about 71,000 stars and the current npm release was 1.14.0. This guide walks through the workflow, shows what `openspec init` actually creates, and explains where the [OpenSpec Propose](https://skillgild.dev/skills/openspec-propose) skill fits.\n\nAI agents are fast but drift when the requirements live only in chat history. OpenSpec adds a thin layer of Markdown files to your repository:\n\n`openspec/specs/` holds the current truth: requirements and scenarios for each part of the system.`openspec/changes/` holds proposed changes, one folder each, until they ship.`openspec/config.yaml` holds optional project rules, such as \"keep proposals under 500 words\".\nThe specs are plain Markdown, with no special syntax to learn. OpenSpec's [README](https://github.com/Fission-AI/OpenSpec#readme) describes the goal as agreeing on what to build \"before any code is written\". That planning step is called spec-driven development.\n\n`/opsx:explore` lets the agent read your code and weigh options before anything is written down.`/opsx:propose add-dark-mode` creates `openspec/changes/add-dark-mode/` with four artifacts: `proposal.md` (why and what), `specs/` (requirement changes), `design.md` (technical approach) and `tasks.md` (the checklist).`/opsx:apply` works through `/opsx:archive` moves the finished change into `openspec/changes/archive/` and merges its spec changes into OpenSpec calls itself \"fluid not rigid\": there are no phase gates, so you can update any artifact during apply.\n\nOpenSpec needs Node.js 20.19.0 or later. Install it globally with npm, or with Homebrew on macOS and Linux:\n\n```\nnpm install -g @fission-ai/openspec@latest\n# or\nbrew install openspec\n```\n\nThen initialize it inside your project. The `--tools` flag skips the interactive picker:\n\n```\ncd your-project\nopenspec init --tools claude,codex\n```\n\nWe ran exactly that on October 5, 2026, with OpenSpec 1.14.0, in an empty Git repository. This is the replayed output:\n\nThe run wrote these files:\n\n```\n.claude/\n  commands/opsx/   apply, archive, explore, propose, sync, update (.md)\n  skills/          openspec-apply-change, openspec-archive-change,\n                   openspec-explore, openspec-propose,\n                   openspec-sync-specs, openspec-update-change (SKILL.md each)\n.agents/skills/    the same 6 skills, for Codex\nopenspec/\n  config.yaml\n  specs/\n  changes/archive/\n```\n\nTwo things are worth knowing from that output. First, OpenSpec installs its workflow as ordinary agent skills, the same `SKILL.md` format covered in [how to install Claude Code skills](https://skillgild.dev/learn/install-claude-code-skills) and the [Codex skills guide](https://skillgild.dev/learn/install-codex-skills). Second, the default profile installs six workflows; six more (`new`, `continue`, `ff`, `bulk-archive`, `verify`, `onboard`) are added with `openspec config profile`.\n\nThe command is the same idea everywhere, but the spelling differs. `openspec init` prints the right form for the tools you chose.\n\n| Agent | Start a change | Source | \n|---|---|---|\n| Claude Code | `/opsx:propose \"your idea\"` | init output | \n| Codex CLI or IDE | `$openspec-propose \"your idea\"` | init output | \n| Codex desktop app | Pick openspec-propose under Skills in the sidebar | init output | \n| Cursor, GitHub Copilot | `/opsx-propose` | OpenSpec README | \n| Amazon Q | `@opsx-propose` | OpenSpec README | \n\nOpenSpec lists support for more than 30 tools. Check its [supported tools page](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md) for yours.\n\nA spec change is written as a delta: what is added, modified or removed. This example is from OpenSpec's own README, for a dark-mode change:\n\n``` js\n## ADDED Requirements\n\n### Requirement: Theme selection\n\nThe app SHALL let users switch between light and dark themes,\ndefaulting to the system preference.\n\n#### Scenario: User toggles dark mode\n\n- **WHEN** the user clicks the theme toggle\n- **THEN** the app switches to dark mode and persists the choice\n```\n\nEach requirement has at least one scenario in WHEN and THEN form, so a reviewer can check the behaviour without reading code. When you archive the change, this block is merged into the matching file in `openspec/specs/`.\n\nThe slash commands run inside your agent. The `openspec` CLI runs in your terminal and helps you inspect and check the files. These come from `openspec --help` in version 1.14.0:\n\n| Command | What it does | \n|---|---|\n| `openspec list` | Lists active changes; add `--specs` to list specs | \n| `openspec show <name>` | Shows one change or spec | \n| `openspec validate <name>` | Checks a change or spec for format problems | \n| `openspec status` | Shows which artifacts of a change are complete | \n| `openspec view` | Opens an interactive dashboard of specs and changes | \n| `openspec archive <name>` | Archives a finished change and updates the main specs | \n| `openspec update` | Refreshes agent instructions after you upgrade OpenSpec | \n\nRun `openspec validate` before you approve a proposal. It catches a missing scenario or a malformed requirement that is easy to miss by eye.\n\nThese are the three names that come up most for spec-driven development. The descriptions of the other two below are OpenSpec's own comparison from its README, so read them as one side's view and check each project before you choose.\n\n|  | OpenSpec | Spec Kit (GitHub) | Kiro (AWS) | \n|---|---|---|---|\n| What it is | CLI plus agent skills | Spec toolkit | IDE | \n| Works with | 30+ agents and editors | Several agents | Kiro's own IDE | \n| Process | No fixed phase gates | Phase-gated, more Markdown | Built into the IDE | \n| Setup | npm or Homebrew | Python | Install the IDE | \n| License | MIT | Open source | Commercial product | \n\nIf you already work in Claude Code or Codex, OpenSpec is the lightest to try because it installs into the agent you use. For how skills and tool servers differ in general, see [agent skills vs MCP servers](https://skillgild.dev/learn/agent-skills-vs-mcp).\n\n[OpenSpec Propose](https://skillgild.dev/skills/openspec-propose) on SkillGild packages the propose step as a hosted skill. It turns a feature request into an OpenSpec change before any code is written: proposal, delta specs, design and implementation tasks, grounded in the project's existing specs. Its source is the MIT-licensed [openspec-propose skill](https://github.com/Fission-AI/OpenSpec/tree/main/skills/openspec-propose) in the OpenSpec repository.\n\nUse it when you want the proposal workflow in an agent where you have not run `openspec init`, or across Claude Code, Codex, Cursor and Gemini CLI through one connection. Setup is in the [quickstart for AI agents](https://skillgild.dev/docs/quickstart-agents). If you already ran `openspec init` in a project, the local `openspec-propose` skill is already there and you do not need both.\n\nFor other skills that suit a coding workflow, see [Claude Code skills for developers](https://skillgild.dev/learn/claude-code-skills-for-developers) and the [development category](https://skillgild.dev/categories/development).\n\nUse it when:\n\nSkip it for one-line fixes and throwaway prototypes. The proposal costs a few minutes and a model call, and that only pays off when there is something to get wrong. OpenSpec's README also recommends high-reasoning models and a clean context window before you start implementing.\n\nYes. OpenSpec is open source under the MIT license and installs from npm or Homebrew. You still pay for the AI model your agent uses.\n\nYes. `openspec init --tools claude` installs six skills and six `/opsx:` slash commands into `.claude/`. Start a change with `/opsx:propose \"your idea\"`.\n\nYes. For Codex it installs skills into `.agents/skills/` and no slash commands. Start a change with `$openspec-propose \"your idea\"`.\n\nBoth put a spec before the code. OpenSpec describes itself as lighter and without fixed phase gates; Spec Kit, from GitHub, uses a more structured phase-by-phase process. Try both on a small change if the choice matters.\n\n*Originally published at [skillgild.dev](https://skillgild.dev/learn/openspec).*", "url": "https://wpnews.pro/news/openspec-spec-driven-development-for-claude-code-and-codex", "canonical_source": "https://dev.to/skillgild/openspec-spec-driven-development-for-claude-code-and-codex-4npf", "published_at": "2026-10-06 22:02:27+00:00", "updated_at": "2026-10-06 22:17:53.479443+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["Fission AI", "OpenSpec", "Claude Code", "Codex", "GitHub", "npm", "Homebrew", "Cursor"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/openspec-spec-driven-development-for-claude-code-and-codex", "markdown": "https://wpnews.pro/news/openspec-spec-driven-development-for-claude-code-and-codex.md", "text": "https://wpnews.pro/news/openspec-spec-driven-development-for-claude-code-and-codex.txt", "jsonld": "https://wpnews.pro/news/openspec-spec-driven-development-for-claude-code-and-codex.jsonld"}}