OpenSpec

Cài đặt ​

Điều kiện tiên quyết ​

  • Node.js 20.19.0 trở lên — Kiểm tra phiên bản của bạn: node --version

Cài đặt với trợ lý AI ​

Không muốn làm thủ công? Dán đoạn prompt bên dưới vào bất kỳ trợ lý lập trình nào có thể chạy lệnh shell — Claude Code, Codex, Cursor, Gemini CLI, Copilot và các công cụ được hỗ trợ khác. Nó sẽ cài đặt CLI, khởi tạo dự án này và báo cáo lại những gì đã thực sự xảy ra.

Các bước thủ công bên dưới là nguồn thông tin chính xác — prompt chỉ đơn giản là chạy chúng thay bạn. Nếu trợ lý của bạn dừng lại và trả lại một số thông tin, đó là do thiết kế: nó hỏi trước khi thực hiện bất kỳ hành động nào yêu cầu quyền cao và không bao giờ chỉnh sửa các tệp khởi động shell của bạn. Hãy hoàn thành những phần còn lại bằng cách sử dụng Package Managers và Troubleshooting.

text
Install OpenSpec in this project and set it up for me. Follow these steps in
order, and stop where a step tells you to stop.

1. RUNTIME. Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If
   Node is missing or older, say so and stop — don't install Node, switch
   versions, or reconfigure my version manager for me.

2. INSTALL. Use whichever package manager is already on my PATH, preferring npm:
     npm install -g @fission-ai/openspec@latest
     pnpm add -g @fission-ai/openspec@latest
     bun add -g @fission-ai/openspec@latest
     yarn global add @fission-ai/openspec@latest   (Yarn 1.x only)
   Don't pick based on this project's lockfile — a global install has nothing to
   do with how this repo's own dependencies are installed. If none of those four
   is available, stop and tell me — don't improvise an install. (If I'm on Nix,
   point me at the Nix section of the OpenSpec installation docs instead.)
   Show me the exact command and let me confirm before you run it; this installs
   software outside the project, and I may want a different package manager to
   own it.
   Stop and ask me again if the install needs sudo or admin rights, fails with a
   permissions error, or reports that its global bin directory is missing or
   unconfigured. Never edit my shell startup files (.bashrc, .zshrc, .profile,
   fish, PowerShell profile), and never run a setup command that edits them for
   me — show me the change and let me make it.

3. PATH. Run `openspec --version`. If the command isn't found, it may just be
   missing from this shell: tell me where the package manager installed it and
   how to add that directory to PATH for my shell and OS, then stop until I
   confirm. If it prints an older version than the one the install just
   reported, an earlier copy is shadowing it on PATH — tell me both versions
   instead of continuing. If I use a version manager, say so rather than editing
   PATH around it: with nvm or fnm the CLI is tied to the Node version that was
   active when you installed it, and with asdf or volta a shim may need
   regenerating.

4. INITIALIZE. Ask me which AI coding tool or tools I use and map each to an id
   from `openspec init --help` (Copilot is `github-copilot`, Zoo Code is
   `roocode`). `--tools` takes a comma-separated list, so name all of them.
   `openspec init --tools <ids>` deletes leftovers from older OpenSpec versions
   automatically, without asking — including `opsx-*.md` prompt files in my home
   directory (Codex keeps them in ~/.codex/prompts). Before you run it, look for
   those: `.../commands/openspec/` folders, OpenSpec marker blocks in files like
   CLAUDE.md or AGENTS.md, and home-directory `opsx-*.md` prompts. List whatever
   you find and wait for my go-ahead; if you find nothing, say so and carry on
   without asking. An existing `openspec/` folder is not a problem — init
   refreshes it and leaves my specs and changes alone.
   Confirm I'm in the right folder too: init creates `openspec/` wherever it
   runs, including inside a monorepo package.
   Then run: openspec init --tools <ids>

5. REPORT. Don't assume what should exist — tell me what init actually printed:
   how many skills and/or commands it created and where, the config file line,
   any "Setup required" note, and what to restart or reload. Some tools are
   skills-only and correctly create zero command files, so missing commands is
   not a failure on its own. If init said nothing was generated, relay the fix
   it suggested instead of retrying. Finish by telling me how to invoke OpenSpec
   in my tool, and take the exact spelling from the files init created rather
   than from its summary line: the punctuation differs per tool (/opsx:propose
   in some, /opsx-propose in others, @opsx-propose in Amazon Q), and tools that
   get skills instead of commands are invoked by skill name (/openspec-propose,
   or $openspec-propose in Codex, or /skill:openspec-propose in Kimi Code).

Không có nội dung nào trong prompt mang tính độc quyền theo nhà cung cấp: đây là hướng dẫn chung kèm theo cùng các lệnh được tài liệu hóa trên trang này. Nó hoạt động trên macOS, Linux và Windows, và cố tình dừng lại thay vì tự ý thực hiện khi một bước cần sự cho phép của bạn. Trợ lý của bạn cần có khả năng chạy lệnh shell — một vài tích hợp IDE thì không.

Package Managers ​

npm ​

bash
npm install -g @fission-ai/openspec@latest

pnpm ​

bash
pnpm add -g @fission-ai/openspec@latest

yarn ​

bash
yarn global add @fission-ai/openspec@latest

Yarn 2 trở lên (Berry) đã xóa lệnh global. Trên các phiên bản đó, hãy cài đặt OpenSpec bằng npm, pnpm hoặc bun thay thế — một CLI toàn cục không cần chia sẻ package manager của dự án.

deno ​

Deno đôi khi gặp vấn đề khi phân tích thẻ @latest, nhưng chúng ta có thể chỉ định phiên bản cụ thể khi cài đặt ban đầu. Nếu điều đó xảy ra, bạn có thể thử thay đổi thẻ @latest bằng phiên bản, ví dụ @^1.3.1

bash
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest
# hoặc
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@^1.3.1

Lưu ý: Nếu các lệnh phụ của bạn khởi chạy các công cụ bên ngoài, như chỉnh sửa cấu hình, gửi phản hồi hoặc mở workspace, bạn có thể cần thêm scoped --allow-run=<program>.

bun ​

Bun có thể cài đặt OpenSpec ở chế độ toàn cục, nhưng hiện tại OpenSpec chạy trên Node.js. Bạn vẫn cần Node.js 20.19.0 trở lên có sẵn trong PATH.

bash
bun add -g @fission-ai/openspec@latest

Nix ​

Chạy trực tiếp OpenSpec mà không cần cài đặt:

bash
nix run github:Fission-AI/OpenSpec -- init

Hoặc cài đặt vào profile của bạn:

bash
nix profile install github:Fission-AI/OpenSpec

Hoặc thêm vào môi trường phát triển của bạn trong flake.nix:

nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:Fission-AI/OpenSpec";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

Xác minh cài đặt ​

bash
openspec --version

Cập nhật ​

Nâng cấp gói, sau đó làm mới các tệp đã tạo cho mỗi dự án:

bash
npm install -g @fission-ai/openspec@latest   # hoặc tương đương pnpm/yarn/bun
openspec update                              # chạy bên trong mỗi dự án

openspec update sẽ tạo lại các tệp kỹ năng (skills) và lệnh (commands) cho các công cụ bạn đã cấu hình, để các lệnh slash của bạn luôn cập nhật với phiên bản đã cài đặt. Nó cũng kiểm tra xem có phiên bản CLI mới hơn nào được xuất bản hay không và đề xuất nâng cấp, vì việc nâng cấp là yếu tố giúp các quy trình làm việc mới khả dụng ngay từ đầu — xem CLI Reference.

Gỡ cài đặt ​

Không có lệnh openspec uninstall, vì OpenSpec chỉ là một gói toàn cục cộng với một số tệp trong dự án của bạn. Việc gỡ bỏ nó gồm một vài bước thủ công và không có gì trong quá trình này tác động đến mã nguồn của bạn.

1. Xóa gói toàn cục:

bash
npm uninstall -g @fission-ai/openspec   # hoặc: pnpm rm -g / yarn global remove / bun rm -g

2. Xóa OpenSpec khỏi dự án (tùy chọn). Xóa thư mục openspec/ nếu bạn không còn muốn giữ các spec và thay đổi của nó:

bash
rm -rf openspec/

Hãy suy nghĩ kỹ trước khi làm điều này: openspec/specs/ và openspec/changes/archive/ là hồ sơ ghi lại cách hệ thống hoạt động và lý do tại sao nó thay đổi. Nếu bạn có thể muốn giữ lịch sử đó, hãy giữ lại thư mục (hoặc giữ nó trong git) ngay cả sau khi đã gỡ cài đặt.

3. Xóa các tệp công cụ AI đã tạo (tùy chọn). OpenSpec ghi các tệp kỹ năng và lệnh vào các thư mục riêng cho từng công cụ như .claude/skills/openspec-*/, .cursor/commands/opsx-*, v.v. Hãy xóa các kỹ năng openspec-* và lệnh opsx-* dành cho các công cụ bạn đã cấu hình. Các đường dẫn chính xác cho từng công cụ được liệt kê trong Supported Tools.

Nếu bạn cũng có các khối đánh dấu (marker blocks) của OpenSpec trong các tệp như CLAUDE.md hoặc AGENTS.md, hãy xóa các khối đó bằng tay; nội dung của bạn trong các tệp đó vẫn thuộc về bạn.

Các bước tiếp theo ​

Sau khi cài đặt, hãy khởi tạo OpenSpec trong dự án của bạn:

bash
cd your-project
openspec init

Xem Getting Started để biết hướng dẫn chi tiết.