Fission-AI/OpenSpec

OpenSpec is a command-line tool that manages software specifications and change proposals through a structured, artifact-driven workflow. It provides a CLI for creating, validating, and archiving changes, while generating tailored commands and skills for a wide range of AI coding assistants. The system enforces strict schema validation and security hardening to ensure the integrity of specification artifacts and their dependencies.

27 changes.

This period focused on restructuring the CLI into a verb-noun command hierarchy and introducing native shell completions for Bash, Zsh, Fish, and PowerShell. The team also implemented core features for change management, including an archive command, delta-aware parsers, and Zod-based runtime validation, while significantly expanding test coverage and security hardening across the codebase.

22 changes.

This period focused on replacing the previous workspace model with a new Store subsystem for managing checkouts and introducing a centralized command-generation module to support a wide range of AI coding assistants. The work also included significant infrastructure updates, such as migrating the documentation site to Next.js and Fumadocs, and implementing privacy-first telemetry and enhanced CLI UI components.

A new executable script at bin/openspec.js has been added to serve as the command-line interface entry point. This script initializes the Node.js environment and delegates execution to the compiled CLI module located at dist/cli/index.js, enabling users to run the tool directly from the command line.

bin · high confidence

A new JsonConverter class has been introduced in the core converters module to transform spec and change files into JSON format. This component reads markdown content, utilizes existing MarkdownParser and ChangeParser instances to extract structured data, and outputs the result as formatted JSON with added source path metadata, enabling downstream systems to consume these artifacts in a standardized JSON structure.

src/core/converters · high confidence

The CLI now displays an animated ASCII-art welcome screen during the experimental artifact workflow setup. This screen features a side-by-side layout with an animated OpenSpec logo on the left and onboarding instructions on the right. The animation respects user accessibility preferences by automatically disabling motion for users with reduced-motion settings (detected via OS-level preferences on macOS and Linux, or the \OPENSPEC\_NO\_ANIMATION\ environment variable) and falls back to a static display if the terminal does not support it or is too narrow.

src/ui · high confidence

The command-generation system now supports a significantly wider range of AI coding assistants and IDEs. This update adds dedicated command adapters for Amazon Q, Antigravity, Auggie, Bob, Code Assistant, CodeBuddy, Command Code, CoStrict, Crush, Factory Droid, Gemini CLI, GitHub Copilot, iFlow, Junie, Kilo Code, Kiro, Lingma, Oh My Pi, Pi (pi.dev), Qoder, Trae, and ZCode, while also introducing adapters for Devin Desktop (renamed from Windsurf), Zoo Code (renamed from Roo Code), and updated adapters for Continue, OpenCode, and Qwen. Each adapter ensures commands are formatted and placed in the correct directory structure (e.g., .amazonq/prompts, .claude/commands, .gemini/commands) with the appropriate frontmatter or markdown headers required by the specific tool.

src/core/command-generation/adapters · high confidence

The CLI now collects anonymous usage statistics by default, tracking only the command name and version while explicitly excluding arguments, file paths, content, and IP addresses. This feature respects standard privacy signals, automatically disabling tracking when the DO\_NOT\_TRACK environment variable is set, when running in CI environments, or when the user explicitly opts out via the OPENSPEC\_TELEMETRY environment variable or the global config file. The implementation uses a lightweight, direct HTTP request to PostHog to avoid heavy SDK dependencies, and ensures that network errors or configuration issues do not disrupt the user experience.

src/telemetry · high confidence

The \openspec archive\ command is now available to finalize completed changes by applying delta-based spec updates, retiring empty capabilities, and cleaning up change directories. This feature includes a new validation system using Zod schemas for change metadata, a status policy engine to guide users through next steps, and improved handling of spec retirement when requirements are removed. The archive process respects existing configuration, handles cross-platform file operations safely, and provides clear feedback on validation results. Additionally, the system now supports project-level configuration via \openspec/config.yaml\ and introduces a completion tip system that guides users toward shell completions without requiring post-install scripts.

src/core · high confidence

The CLI now exposes a new set of commands under the \workflow\ namespace to manage artifact-driven changes: \status\ (including a new \--all\ flag for batch status of every active change), \instructions\ (to generate enriched instructions for creating or applying artifacts), \templates\ (to show resolved template paths for artifacts), \schemas\ (to list available workflow schemas), and \new change\ (to create a new change directory). This new workflow replaces the previous initiative and workspace concepts with a store-based root selection model, and the \new change\ command now warns users if an OpenSpec root is implicitly created because no \openspec/\ directory was found.

src/commands/workflow · high confidence

This change introduces the \src/core/artifact-graph\ module, which provides the foundational logic for managing artifact dependencies and workflow states. It includes an \ArtifactGraph\ class that computes topological build orders and determines ready/blocked artifacts based on schema definitions, ensuring deterministic ordering by schema declaration rather than alphabetical sorting. The module adds schema resolution logic that supports project-local, user-override, and package-builtin schemas, including handling for symlinked directories. It also introduces an instruction loader that generates context-aware instructions for artifacts, supporting templates, inline guidance, and glob-based output patterns with security hardening against path traversal and hostile inputs. Additionally, it provides utilities for detecting completed artifacts via file existence checks and validating schema integrity (duplicate IDs, invalid references, cycles).

src/core/artifact-graph · high confidence

The \src/core/store\ directory now contains the core implementation for the new Store system, replacing the previous workspaces and initiatives model. This includes the foundational registry and metadata logic (\foundation.ts\, \registry.ts\), Git-backed storage operations (\git.ts\, \operations.ts\), and a structured error handling system (\errors.ts\) that provides actionable diagnostics for invalid store IDs or registry states. Users can now register, list, and inspect stores, with the CLI enforcing strict validation on store IDs and preventing conflicts when multiple checkouts are registered.

src/core/store · high confidence

The CLI has been restructured to use a verb-noun command pattern (e.g., \openspec change show\, \openspec spec list\) replacing the previous noun-form commands. This change introduces new command implementations in \src/commands/\, including \ChangeCommand\ for managing change proposals (show, list, validate), \SpecCommand\ for programmatic access to specifications, and \ShowCommand\ as a unified entry point that delegates to the specific verb commands. The update also adds \CompletionCommand\ for managing shell completions (bash, zsh, fish, powershell), \ConfigCommand\ for global configuration management with improved editor handling, \ContextCommand\ for displaying working context and generating VS Code workspace files, \DoctorCommand\ for relationship health reporting, \FeedbackCommand\ for submitting user feedback via GitHub issues, and \SchemaCommand\ for schema management and validation. These commands share common utilities in \shared-gather.ts\ and \shared-output.ts\ for consistent error handling and JSON output formatting.

src/commands · high confidence

OpenSpec now includes built-in shell completions for Bash, Zsh, Fish, and PowerShell, providing dynamic suggestions for commands, flags, and item IDs (changes, specs, and schemas) directly in the terminal. The new \src/core/completions\ module introduces a command registry defining all CLI options, a completion provider with a 2-second cache to minimize file-system overhead, and shell-specific generators and installers that handle script generation and profile configuration. Users benefit from faster, context-aware tab completion without relying on external post-install scripts.

src/core/completions · high confidence

The website area now hosts the OpenSpec documentation site, built with Next.js and Fumadocs and configured as a static export for Cloudflare Pages. Documentation content is mechanically mirrored from the repository's \docs-lab\ directory into the site's \content/docs\ folder on every build, ensuring the site stays in sync with the source. The site includes a sidebar configuration (\docs.sync.config.mjs\), custom remark plugins for rendering FAQs as accordions, file steps, and GitHub-style alerts, and a routing Worker to mount the docs at \openspec.dev/docs\. The site is deployed automatically via Cloudflare Pages when \docs\ or \website\ files change.

website · high confidence

The \src/utils\ directory now includes new modules for managing change metadata and scaffolding. \change-metadata.ts\ introduces reading, writing, and validating \.openspec.yaml\ files, including schema validation and resolution logic. \change-utils.ts\ provides utilities for creating new changes with proper directory structures and metadata, including name validation and schema resolution. \nested-change.ts\ adds detection of changes nested in namespace folders under \changes/\. Additional utility modules include \command-references.ts\ for transforming command references to tool-specific formats, \interactive.ts\ for handling interactive prompts with non-interactive mode support, \file-system.ts\ for cross-platform file operations with security checks, \line-endings.ts\ for preserving file line endings, \item-discovery.ts\ for discovering changes and specs, \date.ts\ for local date formatting, \ci.ts\ for CI environment detection, \match.ts\ for fuzzy string matching, \requirement-diff.ts\ for computing requirement diffs, and \shell-detection.ts\ for detecting the user's shell for completion generation.

src/utils · high confidence

A new command-generation system has been introduced in src/core/command-generation, providing a centralized registry and tool-agnostic interfaces for generating command files across a wide range of AI coding assistants. The module includes a CommandAdapterRegistry that registers built-in adapters for tools such as Claude, Cursor, Devin, Amazon Q, Junie, Kiro, Trae, and many others, allowing users to generate commands tailored to their specific IDE. The generator handles tool-specific invocation styles (e.g., /opsx:apply vs /opsx-apply vs @opsx-apply) and file path conventions, while shared YAML helpers ensure consistent escaping of frontmatter values across all adapters.

src/core/command-generation · high confidence

The parser module now includes a dedicated \ChangeParser\ and \RequirementBlocks\ reader that process change specifications by extracting structured deltas (ADDED, MODIFIED, REMOVED, RENAMED) from spec files rather than relying solely on prose. This ensures that requirement changes are parsed consistently with the archive logic, correctly handling fenced code blocks, nested spec paths, and edge cases like bullet-form removals and non-canonical headers. The new readers also surface validation issues such as orphaned requirements, unpaired renames, and phantom requirements caused by divider headers, providing more accurate validation and reporting for change workflows.

src/core/parsers · high confidence

Added a suite of maintenance scripts to the \scripts/\ directory: \update-flake.sh\ automatically updates the \pnpmDeps\ hash in \flake.nix\ after dependency changes; \regen-parity-hashes.mjs\ recomputes and rewrites golden hashes in the skill-template parity test to prevent stale values after template edits; \generate-skillssh.mjs\ creates the static \skills.sh\ distribution by generating \SKILL.md\ files from templates; and \pack-version-check.mjs\ validates that the CLI \--version\ in a packed tarball matches \package.json\ before publishing. These tools are supported by shared helpers (\parity-hash-shared.mjs\, \skillssh-shared.mjs\) and documented in \scripts/README.md\.

scripts · high confidence

The website now includes new React components to enhance the documentation experience: a \FileSteps\ component that renders interactive, keyboard-navigable step-by-step file diffs with annotations, and a \Mermaid\ component for rendering diagrams with improved styling and fallback handling. Additionally, the MDX component registry has been updated to include these new components along with standard UI elements like Tabs and Accordions, and a new search dialog implementation using Fumadocs' static client has been added to enable site-wide documentation search.

website/components · high confidence

A new \searchable-multi-select\ prompt component has been added to the CLI interface, allowing users to filter and select multiple options via a search box. This component supports search aliases for better discoverability, displays selected items as chips, and includes robust handling for keyboard input, specifically fixing an issue where non-alphanumeric characters (such as punctuation) were previously ignored during typing.

src/prompts · high confidence

The \src/core/shared\ module has been introduced to centralize logic previously scattered across the \init\ and \update\ commands. This includes \allowed-tools.ts\, which defines the pre-approved \Bash(openspec:\*)\ tool set for generated skills; \skill-generation.ts\, which handles the creation of skill and command files with proper workflow filtering and template rendering; \skill-paths.ts\, which resolves the correct directory paths for AI tools that support skills; \tool-detection.ts\, which provides utilities for detecting tool configurations and checking if generated files are up to date; \skill-content-equivalence.ts\, which normalizes and compares skill content to detect real drift versus cosmetic differences like line endings; and \ide-restart.ts\, which provides shared guidance for restarting IDEs after configuration changes. These utilities form the foundation for the new skill and command generation capabilities.

src/core/shared · high confidence

Added dedicated installer classes for Bash, Zsh, Fish, and PowerShell to manage shell completion scripts. The Bash installer detects system-wide bash-completion directories and configures .bashrc using marker-based updates. The Zsh installer supports both Oh My Zsh (via $ZSH/$ZSH\_CUSTOM) and standard Zsh configurations, handling compinit setup. The Fish installer writes completions to the standard \~/.config/fish/completions/ directory. The PowerShell installer handles both Windows PowerShell 5.1 and PowerShell Core 7+, preserving file encoding (UTF-8/UTF-16 LE) and BOM when modifying profile scripts. All installers include backup functionality for existing files, permission checks before writing, and support for opt-in auto-configuration via the OPENSPEC\_NO\_AUTO\_CONFIG environment variable.

src/core/completions/generators, src/core/completions/installers · high confidence

The validation engine now enforces stricter quality checks on change metadata and spec content. Changes with tracked task files must include at least one checkbox; otherwise, a warning is issued because the tool cannot track progress. Task IDs must follow unambiguous numbering within their groups, and duplicate IDs are rejected. Additionally, the system now detects when a spec's Purpose section is still a placeholder (e.g., starting with 'TBD' or containing the auto-generated archive text) and warns the user to replace it with a meaningful description. These checks are implemented via new modules in \src/core/validation\ that integrate with the existing Zod-based schema validation.

src/core/validation · high confidence

The CLI and documentation website dependencies have been updated to address security vulnerabilities and modernize the stack. The CLI now uses @inquirer/core v12, @inquirer/prompts v8, commander v14, diff v9, and zod v4, with pnpm overrides applied to patch known advisories in brace-expansion, postcss, js-yaml, nanoid, and fflate. The website has been upgraded to Next.js 16.3.5, React 19.2.8, and Fumadocs 16.15.11, with overrides ensuring postcss and sharp are updated to secure versions.

(dependencies) · high confidence

The template system has been restructured from a flat set of config files into a modular, skill-based architecture. This change introduces a compatibility facade in \src/core/templates/index.ts\ that re-exports specific skill and command templates from dedicated workflow modules (e.g., \explore\, \new-change\, \apply-change\). It also adds \optional-workflow.ts\, which enables templates to conditionally include or exclude content based on the installed workflow profile (e.g., hiding references to workflows like \/opsx:continue\ if they are not part of the user's selected profile), ensuring generated files remain valid and relevant regardless of the configuration.

src/core/templates · high confidence

The monolithic skill template file has been refactored into distinct modules for each workflow (apply, archive, bulk-archive, continue, explore, feedback, and fast-forward). This change improves maintainability and clarity by isolating the instructions and logic for each specific workflow into its own file, making it easier to understand, update, and extend individual workflows without affecting others.

src/core/templates/workflows · high confidence

The CLI has been reorganized into a verb-noun structure (e.g., \openspec change show\, \openspec spec list\) replacing previous command layouts. This change introduces unified JSON output contracts for list and show commands, providing consistent fields like \id\, \title\, and status counts, while \show\ commands now support raw markdown passthrough and minimal JSON objects. The \--json\ flag behavior has been refined to ensure stdout remains a single valid JSON document by suppressing telemetry notices and completion tips during programmatic runs. Additionally, global options like \--no-color\ are now supported, and error handling ensures diagnostic fixes are printed to stderr even in JSON mode.

src/cli · high confidence

A new Cloudflare Worker and its routing configuration have been added to handle requests for the documentation site. This worker proxies traffic for paths like /docs, /api/search, and /openspec-pixel.svg from openspec.dev to the upstream OpenSpec Pages deployment (openspec-docs.pages.dev), ensuring that static assets and API endpoints are correctly forwarded and that redirects are rewritten to maintain the correct host.

website/cloudflare · high confidence

The schema definitions in src/core/schemas have been replaced with Zod schemas to enforce runtime validation for specification and change documents. This adds strict structural checks for specs (requiring a name, overview, and at least one requirement) and changes (requiring a name, why/what sections, and a bounded list of deltas). It also standardizes the internal representation of requirements and scenarios, ensuring that empty fields and invalid structures are caught early with specific error messages.

src/core/schemas · high confidence

This release introduces v1.13.2, which includes significant security hardening against hostile repository inputs and patches for fast-uri, postcss, and brace-expansion advisories. The update also resolves numerous behavioral issues: archive workflows now handle Windows EPERM errors and preserve file line endings (CRLF/LF) to prevent noisy diffs, while validation and status commands provide more accurate task counting and scenario reporting. Additionally, generated skills and commands are now aligned with the active profile, legacy cleanup preserves user files, and shell completions are installed via the Nix flake package.

(repo-wide) · high confidence

The website has been migrated to a new documentation site built on Fumadocs and the Next.js App Router. This change introduces a new layout and page structure for the documentation, including a dedicated docs layout, dynamic page rendering for MDX content, and a search API route. It also adds new API routes for generating LLM-readable text (llms.txt, llms-full.txt, and per-page llms.mdx), Open Graph images for social sharing, and standard SEO files like robots.txt and sitemap.xml. The home page now redirects to the documentation, reflecting the site's documentation-only focus.

website/app · high confidence

Added comprehensive tests for shell completion installers; Added test coverage for change metadata, naming, and utility functions; Added tests for change and spec command behaviors and security constraints; Added tests for command registry parity, completion provider caching, and validation report completions; Added tests for command-generation adapters, generator, and invocation logic; Added tests for core spec and change parsers; Added tests for documentation accuracy, build packaging, and CI script correctness; Added tests for searchable multi-select prompt keybindings; Added tests for shared core utilities and security hardening; Added tests for source-of-truth spec normalization; Added tests for store foundation, registry, and git probe hardening; Added tests for telemetry configuration and index logic; Added tests for template instruction correctness and guardrails; Added tests for the artifact-graph core module; Added tests for the welcome screen UI component; Added unit tests for shell completion generators; Expanded end-to-end test coverage for CLI validation and store workflows; Expanded test coverage for CLI commands and workflow logic; Expanded test coverage for core archive, tool detection, and CLI behaviors; New test helpers for CLI execution, file-system snapshots, and OpenSpec fixtures.

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 52 → 60 (+8.8)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.16) — scores are not directly comparable.

• Code Health 72 → 65 (-6.3)
• Architecture 88 (new)
• Maturity 75 → 86 (+10.4)
• Readiness 30 → 54 (+23.9)
• Security 74 → 80 (+6.4)
• Accessibility 69 (new)
• Performance 60 (new)

• Change coupling: archive-change.ts ↔ bulk-archive-change.ts (src/core/templates/workflows/archive-change.ts)
• Change coupling: config.ts ↔ index.ts (src/core/config.ts)
• Change coupling: index.ts ↔ config.ts (src/core/command-generation/adapters/index.ts)
• Change coupling: index.ts ↔ registry.ts (src/core/command-generation/adapters/index.ts)
• Change coupling: index.ts ↔ update.ts (src/core/templates/index.ts)
• Change coupling: init.ts ↔ index.ts (src/core/init.ts)
• Dimension evaluation failed
• High CVE: [GHSA redacted] (pnpm-lock.yaml)
• Hotspot: src/commands/workflow/shared.ts (src/commands/workflow/shared.ts)
• No automated tests
• No exposed public API
• No tests found
• Rotate the exposed credentials — git history can't be un-committed
• Secret: generic-api-key (src/telemetry/index.ts)
• Test reliability not included

• ArchiveCommand.run (cognitive 537) (src/core/archive.ts)
• ArchiveCommand.run (cyclomatic 163) (src/core/archive.ts)
• ChangeCommand.collectSpecDiffs (cognitive 26) (src/commands/change.ts)
• ChangeCommand.enrichDeltasWithDiffs (cognitive 18) (src/commands/change.ts)
• ChangeCommand.list (cognitive 21) (src/commands/change.ts)
• ChangeCommand.printDiffText (cognitive 37) (src/commands/change.ts)
• ChangeCommand.printDiffText (cyclomatic 17) (src/commands/change.ts)
• ChangeCommand.show (cognitive 27) (src/commands/change.ts)
• ChangeCommand.validate (cognitive 27) (src/commands/change.ts)
• ClassTooLong: ArchiveCommand (src/core/archive.ts)
• ClassTooLong: InitCommand (src/core/init.ts)
• ClassTooLong: UpdateCommand (src/core/update.ts)
• ClassTooLong: ValidateCommand (src/commands/validate.ts)
• ClassTooLong: Validator (src/core/validation/validator.ts)
• CompletionCommand.installForShell (cognitive 34) (src/commands/completion.ts)
• CompletionCommand.installForShell (cyclomatic 21) (src/commands/completion.ts)
• Coverage not measured — JavaScript/TypeScript suite
• Documentation: no architecture or design documentation (docs/examples.md)
• FileSystemUtils.canonicalizePotentialPath (cognitive 19) (src/utils/file-system.ts)
• FileTooLong: cli/index.ts (src/cli/index.ts)
• …and 283 more

• 161 commits — 63 feature/other, 98 fixes

• src/core — 35 commits
• (root) — 25 commits
• test/core — 25 commits
• openspec/changes — 9 commits
• docs-lab/reference — 7 commits
• website/package.json — 6 commits
• src/commands — 5 commits
• .github/workflows — 4 commits
• docs/cli.md — 3 commits
• .github/dependabot.yml — 2 commits
• docs/community.md — 2 commits
• openspec/specs — 2 commits
• .changeset/archive-nontty-ansi.md — 1 commit
• .changeset/archive-preserves-fenced-blank-lines.md — 1 commit
• .changeset/bash-completion-uninstall-restores-bashrc.md — 1 commit
• .changeset/canonicalize-spec-eof.md — 1 commit
• .changeset/catchup-archive-requirements-blank-lines.md — 1 commit
• .changeset/config-edit-editor-arguments.md — 1 commit
• .changeset/continue-active-workflow-prompts.md — 1 commit
• .changeset/delta-accepts-every-list-marker.md — 1 commit

• fix: chore(changeset): add catch-up changesets for 6 untracked fixes (#1640)
• fix: chore(changeset): track Kilo Code and Continue fixes for 1.13.2 (#1964)
• fix: fix(antigravity): update skill and workflow paths from .agent to .agents (#830)
• fix: fix(apply): surface deferred scope instead of silently simplifying tasks (#1530)
• fix: fix(apply): warn when a change is ready to implement with no specs (#1783)
• fix: fix(archive): copy without staging when Windows EPERM blocks rename (#1926)
• fix: fix(archive): don't write ANSI escape codes to a redirected (non-TTY) stdout (#1603)
• fix: fix(archive): never dead-end a capability retirement (#1699)
• fix: fix(archive): preserve blank lines around ## Requirements when syncing specs (#1637)
• fix: fix(archive): preserve blank lines inside code fences (#1798)
• fix: fix(archive): preserve requirement order when renaming (#1712)
• fix: fix(archive): read a wrapped scenario bullet as one bullet (#1782)
• fix: fix(archive): refuse delta files the merge path never reads (#1870)
• fix: fix(archive): refuse requirement names differing only in case (#1864)
• fix: fix(archive): use schema-aware task progress in workflows (#1795)
• fix: fix(artifact-graph): support brace expansion and extglob output patterns (#1885)
• fix: fix(build): prepare npm git installs without pnpm (#792)
• fix: fix(bulk-archive): check the archive target before moving changeRoot (#1829)
• fix: fix(changes): report a change nested in a namespace folder (#1849)
• fix: fix(cli): reject missing roots for list and validate (#1612)
• …and 141 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Fission-AI/OpenSpec was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.