Install OpenSpec

Install OpenSpec

OpenSpec is a specification-driven development tool for managing proposals, specifications, and changes. It helps teams manage workflows in a structured manner, ensuring all changes are reviewed and verified. This guide will walk you through the OpenSpec installation process.

What is OpenSpec?

OpenSpec is a command-line tool specifically designed for managing proposals (Proposals) and specifications (Specifications) in the software development process. It provides a complete workflow including:

• Proposal Management: Create, review, and track feature proposals
• Specification Validation: Ensure code changes conform to predefined specifications
• Change Tracking: Record all reviewed change history
• Team Collaboration: Support multi-person collaborative development

Application in HagiCode Projects

In HagiCode projects, OpenSpec is used for:

1. Feature Development Management: All new features must go through the OpenSpec proposal process
2. Code Review: Ensure changes comply with project specifications
3. Documentation Synchronization: Maintain consistency between documentation and code implementation
4. Version Control Integration: Seamless integration with version control workflows

Prerequisites

Before installing OpenSpec, ensure your system meets the following requirements:

Node.js and npm

OpenSpec is distributed via npm and requires a Node.js environment. OpenSpec requires Node.js 18.0 or higher.

Verify Node.js installation:

node --version

Verify npm installation:

npm --version

If not installed or the version is too old, please refer to the related software installation instructions in the Installation Guide.

Installing OpenSpec

Version Requirements

This project requires using OpenSpec 1.0.0 or higher version range. All 1.x versions are supported to ensure compatibility with the project workflow.

OpenSpec is installed globally via npm, making it available from anywhere on your system.

Install Globally Using npm

Windows

Run in PowerShell or Command Prompt:

npm install -g @fission-ai/openspec@1

Windows Permission Issues

If you encounter permission errors during installation, run PowerShell or Command Prompt as an administrator.

macOS

Run in Terminal:

npm install -g @fission-ai/openspec@1

macOS Permission Issues

If you encounter EACCES permission errors, try:

sudo npm install -g @fission-ai/openspec@1

Or use nvm to manage Node.js versions and avoid permission issues.

Linux

Run in Terminal:

npm install -g @fission-ai/openspec@1

Linux Permission Issues

If you encounter EACCES permission errors, you can:

1. Use sudo: sudo npm install -g @fission-ai/openspec@1
2. Configure npm to use user directory:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Verify Installation

After installation, verify that OpenSpec is installed correctly and the version meets requirements:

openspec --version

If installed successfully, you will see a version number output, for example:

openspec/1.1.1 linux-x64 node-v18.17.0

Version Range

Please ensure the installed OpenSpec version is 1.0.0 or higher. The project has verified compatibility with version 1.1.1. It is recommended to use the latest compatible version to get new features.

Common Issues and Troubleshooting

Permission Errors

Issue: EACCES Permission Denied

Encountering permission errors when installing or running OpenSpec.

Solutions:

Windows

Run PowerShell or Command Prompt as administrator:

1. Right-click PowerShell or Command Prompt
2. Select “Run as administrator”
3. Re-run the installation command

macOS

Install using sudo:

sudo npm install -g @fission-ai/openspec@1

Or use nvm to manage Node.js and avoid global installation permission issues.

Linux

Solution 1: Use sudo

sudo npm install -g @fission-ai/openspec@1

Solution 2: Configure npm to use user directory

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @fission-ai/openspec@1

Network Issues

Issue: npm Installation Fails or is Very Slow

Unable to download OpenSpec from npm registry due to network reasons.

Solutions:

1. Use Domestic npm Mirror:

# Use Taobao mirror
npm config set registry https://registry.npmmirror.com

# Then reinstall
npm install -g @fission-ai/openspec@1

2. Restore Official Source (if needed):

npm config set registry https://registry.npmjs.org

3. Use cnpm (optional):

npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install -g @fission-ai/openspec@1

Tip

Users in mainland China are recommended to use the Taobao mirror, which can significantly improve download speed.

Version Compatibility Issues

Issue: OpenSpec Commands Run Abnormally or Report Errors

The installed OpenSpec version is incompatible with the current environment.

Solutions:

1. Check Node.js Version:

node --version

Ensure the version is 18.0 or higher. If the version is too low, please upgrade Node.js.

2. Check OpenSpec Version:

openspec --version

3. Reinstall Specific Version:

npm install -g @fission-ai/openspec@1

4. Clear npm Cache (if problem persists):

npm cache clean --force
npm install -g @fission-ai/openspec@1

Command Not Found

Issue: Typing openspec Command Shows “Command Not Found”

OpenSpec is installed but the system cannot find the command.

Solutions:

Windows

1. Confirm npm global installation path:

npm config get prefix

2. Add path to system PATH:
   • Open “System Properties” → “Advanced” → “Environment Variables”
   • Find Path in “System variables”
   • Add npm global path (usually C:\Users\<username>\AppData\Roaming\npm)
   • Restart command line window

macOS

1. Confirm npm global installation path:

npm config get prefix

2. Add path to PATH (in ~/.zshrc or ~/.bash_profile):

export PATH="$(npm config get prefix)/bin:$PATH"

3. Reload configuration:

source ~/.zshrc

Linux

1. Confirm npm global installation path:

npm config get prefix

2. Add path to PATH (in ~/.bashrc):

export PATH="$(npm config get prefix)/bin:$PATH"

3. Reload configuration:

source ~/.bashrc

Upgrading OpenSpec

Version Range

This project requires using OpenSpec 1.0.0 or higher version range. If you have version update requirements, please refer to the project documentation.

If you need to reinstall a specific version:

npm install -g @fission-ai/openspec@1

Uninstalling OpenSpec

If you need to uninstall OpenSpec:

Windows

npm uninstall -g @fission-ai/openspec

macOS

npm uninstall -g @fission-ai/openspec

Or use sudo:

sudo npm uninstall -g @fission-ai/openspec

Linux

npm uninstall -g @fission-ai/openspec

Or use sudo:

sudo npm uninstall -g @fission-ai/openspec

Next Steps

After OpenSpec installation is complete, you can continue with the following steps:

Create First Project Initialize your Hagicode project, configure basic settings, and start your AI-assisted development journey.

Create Conversation Session Start interacting with AI, experience read-only and edit dual modes, and let AI become your capable programming partner.

Create Proposal Session Learn about the proposal-driven development workflow and transform abstract ideas into structured implementation plans.

Tip

For more detailed OpenSpec usage guides, please refer to the OpenSpec Official Documentation.

Need More Help?

If you encounter issues not covered here:

1. Check OpenSpec GitHub Issues for similar problems
2. Visit OpenSpec Official Documentation for more information
3. Refer to related guides on the HagiCode documentation site for additional help