How to Set Up a Development Environment for OpenSpec: Complete Setup Guide

To set up a development environment for OpenSpec, install Node.js ≥20.19 and pnpm, clone the Fission-AI/OpenSpec repository, run pnpm install and pnpm run build, then launch the CLI via node bin/openspec.js.

OpenSpec is a TypeScript-based CLI tool maintained by Fission-AI that requires a modern Node.js runtime and specific build steps to compile source code from the src/ directory into the executable dist/ folder. Whether you are contributing to the core codebase or extending functionality for AI-driven spec workflows, following the official setup ensures compatibility with the Vitest test suite and the containerized development workflow.

Prerequisites for OpenSpec Development

Before cloning the repository, verify your system meets the baseline requirements defined in package.json → engines.

Required tools:

• Node.js ≥20.19.0 – The runtime minimum specified in the engine constraints. Verify with node --version.
• pnpm – The default package manager used in scripts throughout the repository. Enable it via Corepack: corepack enable && corepack prepare pnpm@latest --activate.
• Git – Any recent release for cloning and version control.
• Docker + VS Code (optional) – For the containerized workflow defined in .devcontainer/devcontainer.json.

While npm, yarn, and bun are supported alternatives, all subsequent commands use pnpm for consistency with the project's internal tooling.

Clone the Repository and Install Dependencies

Start by cloning the repository and entering the project directory:

git clone https://github.com/Fission-AI/OpenSpec.git
cd OpenSpec

Install dependencies using pnpm:

pnpm install

This command triggers the postinstall hook configured in scripts/postinstall.js, which configures telemetry settings and validates the Node.js version meets the ≥20.19 requirement.

Build the TypeScript Source

OpenSpec ships with TypeScript source in src/ that must be compiled before execution. Run the build script defined in package.json:

pnpm run build

The build process (orchestrated by build.js) compiles all TypeScript files into the dist/ directory and prepares the bin/openspec.js entry point. The tsconfig.json file governs compiler options during this step.

Run the CLI Locally

Validate your development environment by executing the CLI locally:

pnpm run dev:cli

This npm script builds the project and immediately launches the interactive CLI. Alternatively, after a successful build, run the binary directly:

node bin/openspec.js --help

You should see the help output listing available /opsx: slash commands and sub-commands. This bin/openspec.js file is the same entry point referenced when installing the package globally via npm install -g @fission-ai/openspec.

Execute the Test Suite

Confirm your environment matches CI expectations by running the Vitest-powered test suite:

pnpm test          # Run all tests once

pnpm test:watch    # Watch mode for iterative development

pnpm test:coverage # Generate coverage reports

Tests reside in the test/ directory, covering both unit logic (such as vocabulary-sweep.test.ts) and end-to-end CLI scenarios in cli-e2e/. Successful execution proves that Node.js, pnpm, and the compiled dist/ artifacts are functioning correctly.

Optional: Use the VS Code DevContainer

For a reproducible, isolated environment, use the included DevContainer configuration found at .devcontainer/devcontainer.json.

Setup steps:

1. Open the repository folder in VS Code.
2. When prompted, select "Reopen in Container" or run the command Remote-Containers: Reopen Folder in Container.

The container automatically provisions Node.js 20, pnpm, Git, and the GitHub CLI. It executes pnpm install via the postCreateCommand, ensuring the environment is ready immediately upon startup. This approach eliminates "works on my machine" issues by matching the Linux-based CI runner environment.

Summary

• Install Node.js ≥20.19 and enable pnpm via Corepack to meet engine requirements specified in package.json.
• Clone the Fission-AI/OpenSpec repository and run pnpm install, which executes scripts/postinstall.js for telemetry setup.
• Build the TypeScript source with pnpm run build to populate the dist/ directory.
• Run the CLI locally using pnpm run dev:cli or node bin/openspec.js to verify functionality.
• Test your setup with pnpm test to ensure compatibility with the Vitest suite.
• Containerize your workflow using the VS Code DevContainer for a fully reproducible Linux environment.

Frequently Asked Questions

What Node.js version is required for OpenSpec development?

OpenSpec requires Node.js ≥20.19.0 as specified in the engines field of package.json. The scripts/postinstall.js hook validates this version during installation and will warn if your runtime is outdated.

Can I use npm or yarn instead of pnpm?

Yes, though pnpm is the default package manager used in the project's scripts. You can substitute pnpm with npm or yarn in most commands (e.g., npm install instead of pnpm install), but the Corepack-enabled pnpm workflow is the officially tested path for contributors.

How do I run OpenSpec without installing it globally?

After building the project with pnpm run build, execute the local binary directly: node bin/openspec.js --help. Alternatively, use pnpm run dev:cli to build and launch in one command. This avoids polluting your global npm packages while developing.

What is the purpose of the .devcontainer directory?

The .devcontainer/devcontainer.json file defines a Docker-based development environment for VS Code that includes Node.js 20, pnpm, Git, and the GitHub CLI. Opening the repository in this container ensures a clean, reproducible setup identical to the CI environment, eliminating dependency conflicts across different host machines.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}