Markdown artifacts put a review step before generated code
OpenSpec gives an AI coding session a durable shape. A proposal records why a change exists, specifications state requirements and scenarios, a design explains the approach, and a task list says what must be done. The agent writes those files for developer review. After implementation, the archive command folds the accepted change into the main specifications. Everything stays in the repository as Markdown rather than inside one vendor's chat log.
That is useful when a prompt such as "add dark mode" leaves too many decisions unstated. The example turns it into a requirement with a concrete user action and expected result. OpenSpec supports more than 30 coding tools, with invocation syntax adapted to each client. Codex uses a skill-style command while Claude Code uses a slash command. Another developer or agent can inspect the same record later.
A six-artifact workflow costs more attention than one prompt
The process adds ceremony on purpose. Explore, propose, apply, and archive are the default path, while an expanded profile adds commands for creating, continuing, fast-forwarding, verifying, onboarding, and bulk archiving changes. A small typo does not need all of that. A cross-cutting feature may benefit from every step. The judgment cannot be outsourced to the CLI, and a team that approves generated plans without reading them has only moved the rubber stamp earlier.
OpenSpec is most persuasive on a brownfield repository where requirements otherwise scatter across tickets, chats, and code comments. The files can be reviewed in a pull request and changed as understanding improves. The README describes the workflow as iterative rather than a fixed waterfall. It also asks larger contributions to include a proposal, showing the method on a codebase with about 110,305 source lines.
What happened when we ran it
Our sandbox installed 285 pnpm packages in 16 seconds, occupying 111 MB on disk. The build completed in 18 seconds. Vitest then reported 4,211 passed and 0 failed in 121 seconds. We ran commit e5e350d in an unprivileged container with 3 CPUs, 8 GB of RAM, Node.js 22, and no secrets. Those results cover repository setup and automated checks, not whether an AI produces a good specification.
The checkout contained 1,157 files and roughly 110,305 lines of source across a workspace monorepo. We found 3 CI workflow files and a tests directory, but no Dockerfile. That fits a globally installed Node command-line tool rather than a resident service. The clean result lowers the cost of evaluating the project, while the 121-second suite is more than a token smoke check.
Node 20.19 and one update command are the practical requirements
The published path needs Node.js 20.19.0 or newer. Installation is one global npm command, followed by openspec init inside a project. The initializer asks which coding tools should receive instructions and prints the invocation syntax they understand. OpenSpec itself does not ask for an API credential, though the selected coding assistant has its own requirements. pnpm, yarn, Bun, and Nix paths are documented.
Package upgrades and project guidance are separate. Installing the newest CLI does not rewrite instructions already placed in a repository; openspec update does that. Forgetting the second command can leave collaborators on new CLI code with old agent directions. Version 1.10.0 removed install scripts, moved the first-run telemetry notice to standard error, and required generated tasks to name an observable completion check.
Stores can coordinate repositories, but the feature is still beta
Stores put the openspec planning tree in a separate repository. A platform team can own shared requirements there while application repositories refer to them read-only. One feature can carry a common proposal and task plan even if implementation spans an API, a web client, and a shared library. Git provides distribution and review instead of a separate planning database.
The README labels stores as beta. Issue 1714 describes problems around per-checkout resolution, separate specs and changes roots, and archive locking when Git worktrees are involved. Teams considering stores as the main reason to adopt OpenSpec should reproduce their branching and worktree habits first. The single-repository workflow is the safer initial rollout.
Validation checks structure, while people still judge the requirement
OpenSpec can validate its expected artifact shape and requirement language, including headings and SHALL or MUST terms that remain in English when generated artifacts use another language. It does not promise an automated editor for ambiguity, consistency, or EARS conformance. Issue 1720 requests that quality gate. A structurally valid specification can still encode the wrong product decision or omit an edge case.
The project collects anonymous command names and its version by default. The README says it excludes arguments, paths, content, and personal data, and disables collection in CI. Users can turn it off in configuration or with OPENSPEC_TELEMETRY=0 or DO_NOT_TRACK=1. Teams with a strict policy should put that setting into developer setup.
Same-day activity supports adoption, not blind trust
GitHub showed 66,348 stars, 193 combined open issues and pull requests, and a last push on August 26, 2026. Release 1.10.0 arrived on August 19. The queue includes proposals for stronger validation and fixes to default schema selection. That is an active project with a busy surface area.
OpenSpec earns a trial because the local cost is low and the discipline is visible in ordinary files. The 16-second install and 4,211 passing tests remove most setup doubt. If developers read, challenge, and edit the artifacts, the workflow can prevent expensive misunderstandings. If they treat generated specifications as another box to tick, the repository gains folders without gaining clarity.