OpenSpec v1.12.0: what the scaffold proves, and what it cannot

OpenSpec can populate a new project directory with assistant-facing skill files, a configuration file and empty specification and change directories. In an empty ARM64 Linux directory, its v1.12.0 source commit created eleven files for a selected Codex integration, then rejected an empty change as invalid. That is a repeatable observation about an initializer. It is not evidence that Codex discovers the generated skills, drafts a specification, or implements a feature.

Reproduce the scaffold from a resolved commit

git init -q
env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 init --tools codex --profile core --no-animation
env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 new change inspect-change
env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 status --change inspect-change
env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 validate inspect-change --json
git status --short

Fission-AI published the v1.12.0 release on 3 September 2026.[1] The Git tag v1.12.0 is a lightweight reference that points directly at commit e062b9572be933564ba3899d059377dfa1393e32, so unlike an annotated tag there is no separate tag object to forge; the pointed-to commit itself carries a valid GPG signature from GitHub’s own committer identity.[2][3] The command above pins the npm package at version 1.12.0 and records its resolved integrity hash, which fixes the exact published artefact used here; it does not turn the scaffold into a supply-chain audit. OPENSPEC_TELEMETRY=0 opts the run out of the CLI’s anonymous usage collection, which the project states covers only command names and version, never arguments, paths or content.[1]

Selected captured output

$ git init -q
exit=0
$ env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 init --tools codex --profile core --no-animation
- Creating OpenSpec structure...
▌ OpenSpec structure created
- Setting up Codex...
✔ Setup complete for Codex
OpenSpec Setup Complete
Created: Codex
6 skills in .agents/
Commands skipped for: codex (uses skills)
Config: openspec/config.yaml (schema: spec-driven)
Getting started:
  Start your first change: $openspec-propose "your idea"
Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues
exit=0
$ env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 new change inspect-change
- Creating change 'inspect-change' with schema 'spec-driven'...
Created change 'inspect-change' at openspec/changes/inspect-change/
Schema: spec-driven
Next: openspec status --change inspect-change
exit=0
$ env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 status --change inspect-change
- Loading change status...
Change: inspect-change
Schema: spec-driven
Change root: /tmp/openspec-demo/openspec/changes/inspect-change
Progress: 0/4 artifacts complete
[ ] proposal
[-] specs (blocked by: proposal)
[-] design (blocked by: proposal)
[-] tasks (blocked by: specs, design)
exit=0
$ env OPENSPEC_TELEMETRY=0 npx --yes @fission-ai/openspec@1.12.0 validate inspect-change --json
{
  "items": [
    {
      "id": "inspect-change",
      "type": "change",
      "valid": false,
      "issues": [
        {
          "level": "ERROR",
          "path": "file",
          "message": "Change must have at least one delta. No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. If this change intentionally modifies no specs (pure refactor, tooling, docs), set \"skip_specs: true\" in the change's .openspec.yaml instead. Tip: run \"openspec change show <change-id> --json --deltas-only\" to inspect parsed deltas."
        }
      ],
      "durationMs": 59
    }
  ],
  "summary": {
    "totals": {
      "items": 1,
      "passed": 0,
      "failed": 1
    },
    "byType": {
      "change": {
        "items": 1,
        "passed": 0,
        "failed": 1
      }
    }
  },
  "version": "1.0",
  "root": {
    "path": "/tmp/openspec-demo",
    "source": "nearest"
  }
}
exit=1
$ git status --short
?? .agents/
?? openspec/
exit=0

That is the retained stdout and stderr of every command above, in order, with each exit code as reported by the shell, trimmed by one trailing blank line for display. Environment and method. Raspberry Pi ARM64, Linux 6.12.47+rpt-rpi-v8, Node v26.5.1 and npm 11.17.0. The command ran once, in a new empty directory, at 2026-09-06T13:19:14Z. No Codex CLI was installed on the host; the init --tools codex flag only selects which assistant’s skill files to generate, and generation does not require that assistant to be present. The resulting tree was inventoried after each step, and its files are hashed in the private verification record. No agent prompt, generated specification, implementation, test suite or acceptance check was run.

What the initializer placed on disk

The commit-scoped run created eleven regular files: six SKILL.md files under .agents/skills, one small marker file in that same directory, one openspec/config.yaml, two empty-directory markers, and one change-metadata file after new change. It did not create a Git commit; git status --short reported every generated path as untracked. The .gitkeep markers in the empty directories make those directories trackable if a user adds them, which is the release notes’ own description of that mechanism; it is not the same as the CLI adding anything to the index.[1]

The local tree matches the narrow role described by the project documentation. OpenSpec calls its approach spec-driven development and documents a schema that names four planning artefacts in dependency order: a proposal, delta specifications, a design and a task list, with specifications and design both depending only on the proposal and tasks depending on both.[4] The captured initializer output also names a later Codex step, $openspec-propose. Neither the schema description nor that printed hint proves that a particular Codex installation discovers the generated skills or produces a correct change.

OpenSpec's two repository locations: openspec/specs holds the current behavioural record, and an active change folder holds a proposal, delta specs, design and tasks. Archiving merges the change's deltas into specs. A footer notes that propose, apply, update, sync and archive are actions that can run in any order, not fixed phases. — A documentation-based sketch of OpenSpec’s repository layout. Archiving is the only depicted action; it is not a claim about assistant behaviour.

The validate command’s rejection of the empty change is a second useful negative result beyond scaffolding: a change directory with no delta specification is not treated as a valid modification, so creating the folder is not the same as proposing a change.

The runtime boundary

The initializer’s success and an assistant integration’s runtime behaviour are separate states. This run generated skill files for Codex without ever invoking Codex. A currently open issue reports that in Claude Code 2.1.119, none of the generated /opsx:* commands appeared in that editor’s slash-command menu after installation, with the reporter’s environment recorded as OpenSpec CLI 1.3.1 on Windows 11 with a custom profile.[5] That report is not evidence of a current general defect in 1.12.0 for every tool, but it is a reason not to treat a scaffold inventory as a discoverability test, and the project’s own tool-compatibility documentation independently confirms that different assistants receive different delivery mechanisms: Codex receives skills only and no command files at all under any profile, which is exactly what this run’s output shows.[6]

A separate current report concerns a different runtime boundary: openspec update can report every configured tool as up to date even when a generated command file has been hand-edited or truncated, because the freshness check reads a version marker in the associated skill file rather than the command file’s own content, with update --force named as the recovery path.[7] The linked pull request was still open and unmerged when its record was retrieved on 6 September 2026.[8] That issue’s own reproduction uses a tool with generated command files; the Codex setup used above generated none, so on the mechanism the issue describes that setup would not be affected, though the issue itself makes no claim about Codex. Both reports describe scoped, version- and configuration-specific behaviour, not a benchmark of 1.12.0 as a whole. The practical limit they share is still useful: initialization, a specific editor’s command discovery, and a later update call are separate things to verify, and a clean scaffold on one host does not settle any of them.

What OpenSpec documents, and what a team still owns

OpenSpec’s schema system separates a default spec-driven workflow from project-specific customization: a schema declares the artefacts and their dependencies, project configuration can inject shared context and per-artefact rules, and a team can fork or write its own schema when the default shape does not fit.[9][10] Community-maintained schemas exist as separate repositories with their own release cadence; the project states plainly that listing one does not mean it has been audited or endorsed.[10] That structure lets a team vary its process without replacing every template, and it creates the same review boundary as any dependency a team pulls in without vetting.

For an existing codebase, the project’s own guidance is not to document what already exists. Its stated position is that a team writes specifications only for the slice a change actually touches, so specifications start nearly empty and accumulate one archived change at a time rather than requiring an upfront full-system description.[11] The project’s separate reviewing guide sets out what a human is expected to check before implementation starts: whether the proposal matches the intent asked for, whether each requirement has a scenario that actually exercises it, and whether the task list maps back to those requirements, with a second pass after implementation.[12]

None of that removes the reviewer’s job. A team still decides which artefacts a given change actually needs, which generated files to keep under version control, and how a resulting change is tested before it is trusted.

Limits of this observation

This run does not compare coding agents, measure productivity, assess schema or extension safety, or establish behaviour beyond one empty ARM64 Linux target with the Codex integration and the core profile. It does not test a brownfield repository, an openspec update refresh, assistant-side skill discovery inside a real editor, prompt handling, generated code, security review, or a test result. It also does not evaluate any tool other than Codex; the runtime-boundary reports above concern Claude Code and a hand-edited command file, neither of which this reproduction exercised.

The observed result is therefore precise but small: the npm-published 1.12.0 release, resolved to a signed commit at e062b9572be933564ba3899d059377dfa1393e32, produced the recorded eleven-file scaffold with the stated flags on this host, and its own validate command correctly rejected an empty change. A useful adoption test begins after that point, with a real assistant session inside the target editor and independently checked acceptance criteria.