OpenSpec

التثبيت ​

المتطلبات الأساسية ​

  • Node.js 20.19.0 أو أعلى — تحقق من نسختك: node --version

التثبيت باستخدام مساعد الذكاء الاصطناعي الخاص بك ​

أتفضل ألا تقوم بذلك يدوياً؟ انسخ الأمر التالي وألصقه في أي مساعد ترميز يمكنه تشغيل أوامر shell — مثل Claude Code، Codex، Cursor، Gemini CLI، Copilot، وغيرها من الأدوات المدعومة. يقوم هذا الأمر بتثبيت واجهة سطر الأوامر (CLI)، وتهيئة هذا المشروع، وإعلامك بما تم فعله بالفعل.

الخطوات اليدوية أدناه هي المرجع الأساسي — الأمر السابق يقوم بتنفيذها نيابةً عنك. إذا توقف المساعد وسلمك شيئاً، فهذا مقصود: فهو يطلب التأكيد قبل أي إجراء مميز ولا يقوم أبداً بتعديل ملفات بدء التشغيل الخاصة بـ shell. أكمل تلك الأجزاء بنفسك باستخدام مديري الحزم وقسم استكشاف الأخطاء.

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).

لا يوجد أي جزء خاص بجهة معينة في هذا الأمر: إنه تعليمات واضحة بالإضافة إلى نفس الأوامر الموثقة في هذه الصفحة. يعمل على أنظمة macOS و Linux و Windows، ويتوقف عمداً بدلاً من الارتجال عندما تتطلب خطوة ما إذنك. يحتاج مساعدك أن يكون قادراً على تشغيل أوامر shell — بعض تكاملات بيئات التطوير لا تستطيع ذلك.

مديرو الحزم ​

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 والإصدارات الأحدث (Berry) بإزالة الأمر global. في هذه الإصدارات، قم بتثبيت OpenSpec باستخدام npm أو pnpm أو bun بدلاً من ذلك — لا تحتاج واجهة سطر الأوامر العامة إلى مشاركة مدير حزم مشروعك.

deno ​

يواجه Deno أحياناً مشاكل في تحليل الوسم @latest، ولكن يمكننا تحديد إصدار معين أثناء التثبيت الأولي. إذا حدث ذلك، يمكنك محاولة استبدال الوسم @latest بالإصدار، مثل @^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
# أو
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

ملاحظة: إذا كانت أوامرك الفرعية تشغل أدوات خارجية، مثل تحرير الإعدادات، أو إرسال الملاحظات، أو فتح مساحة العمل، فقد تحتاج إلى صلاحية محددة --allow-run=<program>.

bun ​

يستطيع Bun تثبيت OpenSpec بشكل عام، ولكن OpenSpec يعمل حالياً على Node.js. ما زلت بحاجة إلى Node.js 20.19.0 أو أعلى متاحة في PATH.

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

Nix ​

تشغيل OpenSpec مباشرة بدون تثبيت:

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

أو التثبيت إلى ملفك الشخصي:

bash
nix profile install github:Fission-AI/OpenSpec

أو أضف إلى بيئة التطوير في 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 ];
    };
  };
}

التحقق من التثبيت ​

bash
openspec --version

التحديث ​

قم بترقية الحزمة، ثم قم بتحديث الملفات المُنشأة في كل مشروع:

bash
npm install -g @fission-ai/openspec@latest   # أو ما يعادله في pnpm/yarn/bun
openspec update                              # شغله داخل كل مشروع

يقوم الأمر openspec update بإعادة إنشاء ملفات المهارات والأوامر للأدوات التي قمت بتهيئتها، مما يضمن بقاء أوامر slash الخاصة بك متوافقة مع الإصدار المثبت. كما يتحقق مما إذا كان هناك إصدار أحدث من CLI تم نشره ويعرض الترقية، لأن الترقية هي ما يجعل سير العمل الجديد متاحاً في المقام الأول — راجع مرجع CLI.

إلغاء التثبيت ​

لا يوجد أمر openspec uninstall، لأن OpenSpec مجرد حزمة عامة بالإضافة إلى بعض الملفات في مشروعك. إزالته تتطلب بضع خطوات يدوية، ولا يمس أي شيء هنا شيفرتك المصدرية.

1. إزالة الحزمة العامة:

bash
npm uninstall -g @fission-ai/openspec   # أو: pnpm rm -g / yarn global remove / bun rm -g

2. إزالة OpenSpec من مشروع (اختياري). احذف المجلد openspec/ إذا لم تعد ترغب في المواصفات والتغييرات الموجودة فيه:

bash
rm -rf openspec/

فكر جيداً قبل القيام بذلك: المجلدان openspec/specs/ و openspec/changes/archive/ هما سجل لكيفية تصرف النظام وسبب تغييره. إذا كنت قد ترغب في هذا السجل، احتفظ بالمجلد (أو احتفظ به في git) حتى بعد إلغاء التثبيت.

3. إزالة الملفات التي تم إنشاؤها لأدوات الذكاء الاصطناعي (اختياري). يقوم OpenSpec بكتابة ملفات المهارات والأوامر في مجلدات خاصة بكل أداة مثل .claude/skills/openspec-*/ و .cursor/commands/opsx-* وهكذا. احذف ملفات المهارات openspec-* والأوامر opsx-* لأي أدوات قمت بتهيئتها. مسارات هذه الملفات الدقيقة لكل أداة مذكورة في الأدوات المدعومة.

إذا كانت لديك أيضاً كتل علامات OpenSpec في ملفات مثل CLAUDE.md أو AGENTS.md، فقم بإزالة تلك الكتل يدوياً؛ المحتوى الخاص بك في هذه الملفات يبقى لك.

الخطوات التالية ​

بعد التثبيت، قم بتهيئة OpenSpec في مشروعك:

bash
cd your-project
openspec init

راجع بدء الاستخدام للحصول على شرح كامل.