@clawplays/ospec-cli 0.3.3 → 0.3.4

package/README.md

@@ -74,7 +74,10 @@ CLI notes:
 - `--summary`: project overview text written into the generated docs
 - `--tech-stack`: comma-separated stack list such as `node,react,postgres`
 - `--architecture`: short architecture description
-- `--document-language`: generated doc language, usually `en-US` or `zh-CN`
+- `--document-language`: generated doc language, choose from `en-US`, `zh-CN`, `ja-JP`, or `ar`
+- AI-first language resolution order: explicit language request in the conversation -> current conversation language -> persisted project language in `.skillrc`
+- CLI language resolution order: explicit `--document-language` -> persisted project language in `.skillrc` -> existing project docs / `for-ai/*` / asset manifest -> fallback `en-US`
+- OSpec persists the chosen project document language in `.skillrc` and reuses it for `for-ai` guidance, `ospec new`, and `ospec update`
 - if you pass these values, OSpec uses them directly when generating project docs
 - if you do not pass them, OSpec reuses existing docs when possible and otherwise creates placeholder docs first
 
@@ -195,6 +198,7 @@ Archive notes:
 
 - **Change-ready initialization**: `ospec init` creates the protocol shell and baseline project knowledge docs in one pass.
 - **Guided initialization**: AI-assisted init can ask once for missing summary or tech stack; direct CLI init falls back to placeholder docs when context is missing.
+- **Stable project language**: the chosen document language is stored in `.skillrc` so later guidance and generated change docs stay consistent unless you explicitly change it.
 - **Docs maintenance**: `ospec docs generate` refreshes or repairs project knowledge docs when you need it later.
 - **Tracked requirement execution**: each change can keep proposal, tasks, state, verification, and review files aligned.
 - **Queue helpers**: `queue` and `run` support explicit multi-change execution when one active change is not enough.

package/assets/for-ai/ar/ai-guide.md

@@ -0,0 +1,55 @@
+---
+name: project-ai-guide
+title: دليل الذكاء الاصطناعي
+tags: [ai, guide, ospec]
+---
+
+# دليل الذكاء الاصطناعي
+
+## الهدف
+
+هذه الوثيقة هي النسخة المعتمدة داخل المشروع من مواصفة OSpec الأم. يجب على الذكاء الاصطناعي اتباع القواعد المعتمدة داخل المشروع أولاً بدلاً من الارتجال انطلاقاً من المستودع الأم.
+
+## ترتيب العمل
+
+1. اقرأ `.skillrc`
+2. اقرأ `SKILL.index.json`
+3. اقرأ القواعد المعتمدة للمشروع تحت `docs/project/`
+4. اقرأ ملفات `SKILL.md` ذات الصلة
+5. اقرأ ملفات التنفيذ الخاصة بالتغيير الحالي
+6. إذا كان Stitch مفعلاً وكان التغيير الحالي يفعّل `stitch_design_review`، فافحص `artifacts/stitch/approval.json` أولاً
+7. إذا احتجت إلى تثبيت Stitch أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة، فاقرأ مواصفة Stitch المحلية في المستودع أولاً. وعندما يوجد `docs/stitch-plugin-spec.zh-CN.md` فاعتبر مقاطع الإعداد فيه هي المصدر المعتمد
+
+## السلوك المطلوب
+
+- حافظ على `proposal.md` و`tasks.md` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
+- لا تستنتج لغة وثائق change من لغة واجهة المنتج أو locale الموقع أو من متطلب "الإنجليزية أولاً" فقط
+- إذا كان البروتوكول المعتمد للمشروع بالصينية أو كانت وثائق change الحالية بالصينية بالفعل، فاستمر بالصينية ما لم تغيّر قواعد المشروع ذلك صراحةً
+- استخدم الفهرس لتحديد موقع المعرفة قبل قراءة الملفات الهدف
+- اقرأ القواعد المعتمدة للمشروع قبل بدء التنفيذ
+- إذا كان `stitch_design_review` مفعلاً وكان `approval.json.preview_url` أو `submitted_at` فارغاً، فشغّل أولاً `ospec plugins run stitch <change-path>` لتوليد preview ثم أرسل الرابط للمستخدم
+- إذا كانت `.skillrc.plugins.stitch.project.project_id` مضبوطة مسبقاً، فيجب إعادة استخدام مشروع Stitch نفسه وعدم إنشاء مشروع جديد
+- إذا كانت `.skillrc.plugins.stitch.project.project_id` فارغة، فاعتبر أول تشغيل ناجح لـ Stitch هو المشروع canonical وأعد استخدامه لاحقاً
+- إذا كان `stitch_design_review` مفعلاً وكان `approval.json.status != approved` فتوقف عند بوابة مراجعة التصميم
+- يجب أن تفرض مراجعة صفحات Stitch تخطيطاً canonical واحداً لكل مسار أعمال
+- عند إنتاج `light/dark` اشتق النسختين من الشاشة canonical نفسها ولا تعِد ترتيب الوحدات أو تغيّر هيكل المعلومات أو تنقل CTA أو تنشئ تركيباً مختلفاً
+- إذا كانت الصفحة المطابقة موجودة بالفعل ففضّل `edit existing screen` أو `duplicate existing canonical screen and derive a theme variant`
+- يجب أن يتضمن كل تسليم Stitch ملف `screen mapping` يحتوي على route ومعرفات canonical dark/light وعلاقة الاشتقاق ومعرفات الشاشات المؤرشفة
+- يجب أرشفة أو إعادة تسمية الشاشات القديمة وشاشات الاستكشاف والشاشات المستبدلة بدلاً من تركها كصفحات رئيسية موازية للشاشة canonical
+- إذا كان اختيار canonical أو pairing للثيمات أو screen mapping أو تنظيف التكرارات ناقصاً فلا تعتبر المراجعة مكتملة
+- يستخدم `ospec plugins run stitch <change-path>` افتراضياً موائم Stitch provider المضبوط. استخدم runner مخصصاً فقط عند وجود override صريح في `.skillrc.plugins.stitch.runner`
+- إذا استخدم runner مخصص `token_env` فتأكد من ضبط متغير البيئة الموافق قبل التشغيل
+- إذا لم تتضح جاهزية runner أو Gemini CLI أو Codex CLI أو stitch MCP أو المصادقة، فشغّل أولاً `ospec plugins doctor stitch <project-path>`
+- إذا أظهر `plugins doctor stitch` نتيجة غير PASS لفحوص provider المحدد، فاطلب من المستخدم تثبيت CLI المطلوب وإكمال إعداد stitch MCP / API token
+- عند تثبيت Stitch أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة، اقرأ مواصفة Stitch المحلية أولاً. وعندما يوجد `docs/stitch-plugin-spec.zh-CN.md` فانسخ شكل إعداد Gemini / Codex الموثق فيه بدلاً من ابتكار إعداد بديل
+- إذا كان provider الداخلي `codex` ينجح في الاستدعاءات للقراءة فقط لكن `create_project` أو `generate_screen` أو `edit_screens` يتوقف محلياً، فتحقق أولاً من أن التشغيل يستخدم `codex exec --dangerously-bypass-approvals-and-sandbox`
+- إذا كان المشروع يبدّل `.skillrc.plugins.stitch.runner` صراحةً ومع ذلك يبقى Codex مسؤولاً عن كتابات Stitch، فيجب على runner / wrapper المخصص تمرير `--dangerously-bypass-approvals-and-sandbox` أيضاً
+- زامن `SKILL.md` بعد التغييرات البرمجية المهمة
+- أعد بناء `SKILL.index.json` عند الحاجة
+
+## أولوية قواعد المشروع
+
+- اتفاقيات التسمية: `docs/project/naming-conventions.md`
+- اتفاقيات SKILL: `docs/project/skill-conventions.md`
+- اتفاقيات سير العمل: `docs/project/workflow-conventions.md`
+- دليل التطوير: `docs/project/development-guide.md`

package/assets/for-ai/ar/execution-protocol.md

@@ -0,0 +1,44 @@
+---
+name: project-execution-protocol
+title: بروتوكول التنفيذ
+tags: [ai, protocol, ospec]
+---
+
+# بروتوكول تنفيذ الذكاء الاصطناعي
+
+## اقرأ هذا أولاً في كل مرة تدخل فيها إلى مشروع
+
+1. `.skillrc`
+2. `SKILL.index.json`
+3. `docs/project/naming-conventions.md`
+4. `docs/project/skill-conventions.md`
+5. `docs/project/workflow-conventions.md`
+6. ملفات change الحالية: `proposal.md / tasks.md / state.json / verification.md`
+7. إذا وُجد `stitch_design_review` فاقرأ `artifacts/stitch/approval.json`
+8. إذا كان يجب تعديل Stitch provider أو MCP أو إعدادات المصادقة، فاقرأ مواصفة Stitch المحلية أولاً. وعندما يوجد `docs/stitch-plugin-spec.zh-CN.md` فاعتبر مقاطع الإعداد فيه مرجعية
+
+## القواعد الإلزامية
+
+- حافظ على `proposal.md` و`tasks.md` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
+- لا تعِد كتابة وثائق change إلى الإنجليزية فقط لأن واجهة المنتج أو locale الموقع أو نص المتطلب يميل إلى الإنجليزية
+- إذا كانت وثائق change الحالية بالصينية بالفعل، فاستمر بالصينية ما لم تتطلب قواعد المشروع التحويل إلى الإنجليزية صراحةً
+- لا تتجاوز proposal/tasks وتنتقل مباشرة إلى التنفيذ
+- استخدم `state.json` كمصدر الحقيقة لحالة التنفيذ
+- يجب أن تظهر optional steps المفعلة في `tasks.md` و`verification.md`
+- إذا كان `stitch_design_review` مفعلاً وكان `approval.json.preview_url` أو `submitted_at` فارغاً، فشغّل أولاً `ospec plugins run stitch <change-path>` لإرسال preview
+- يجب أن تفرض مراجعة تصميم Stitch تخطيطاً canonical واحداً لكل route، ويجب تصنيف الشاشات غير canonical على أنها `archive / old / exploration`
+- في متغيرات الثيم `light/dark` حافظ على التخطيط canonical نفسه وحوّل الثيم البصري فقط من دون إعادة ترتيب الوحدات أو نقل CTA أو تغيير البنية
+- إذا كانت الصفحة المطابقة موجودة بالفعل ففضّل `edit existing screen` أو `duplicate existing canonical screen and derive a theme variant`
+- يجب أن يخرج كل تسليم Stitch `screen mapping` يتضمن route ومعرفات canonical dark/light وعلاقة الاشتقاق ومعرفات الشاشات المؤرشفة
+- يجب ألا تبقى الشاشات القديمة أو الاستكشافية أو المستبدلة بجوار الشاشات canonical كصفحات رئيسية موازية
+- إذا كانت `.skillrc.plugins.stitch.project.project_id` موجودة، فأعد استخدام معرف مشروع Stitch نفسه ولا تنشئ مشروعاً آخر لهذا التغيير
+- إذا كان مشروع Stitch canonical ما زال فارغاً، فإن أول إرسال ناجح لـ Stitch يصبح المشروع canonical للمستودع
+- قبل تشغيل Stitch افترض أن الإضافة الداخلية `stitch` تستخدم provider المضبوط افتراضياً؛ ولا تعتبر `.skillrc.plugins.stitch.runner` مرجعاً إلا إذا كان هناك override صريح
+- إذا كان المشروع يستخدم runner مخصصاً وكان `token_env` مضبوطاً، فتأكد من ضبط متغير البيئة الموافق
+- إذا كانت جاهزية Stitch bridge أو Gemini CLI أو Codex CLI أو stitch MCP أو المصادقة غير واضحة، فشغّل أولاً `ospec plugins doctor stitch <project-path>`
+- إذا كشف `plugins doctor stitch` عن مشكلات في provider أو MCP أو المصادقة، فارجع أولاً إلى مواصفة Stitch المحلية في المستودع ولا تبتكر إعدادات بديلة خارجها
+- إذا كان provider الداخلي `codex` يستطيع تنفيذ الاستدعاءات للقراءة فقط لكن `create_project` أو `generate_screen` أو `edit_screens` يتوقف محلياً، فتحقق أولاً من أن التشغيل يستخدم `codex exec --dangerously-bypass-approvals-and-sandbox`
+- إذا كان المشروع يبدّل `.skillrc.plugins.stitch.runner` صراحةً وما زال يستخدم Codex في كتابات Stitch، فيجب على runner / wrapper المخصص تمرير `--dangerously-bypass-approvals-and-sandbox`
+- إذا كان `stitch_design_review` مفعلاً وكان `approval.json.status != approved` فلا تعتبر التغيير جاهزاً للاستمرار أو الاكتمال أو الأرشفة
+- إذا كان اختيار canonical أو pairing للثيمات أو screen mapping أو تنظيف التكرارات ناقصاً فلا تعتبر مراجعة التصميم ناجحة
+- لا تعتبر العمل مكتملاً عندما تكون ملفات `SKILL.md` والفهرس غير متزامنة

package/assets/for-ai/ja-JP/ai-guide.md

@@ -0,0 +1,55 @@
+---
+name: project-ai-guide
+title: AI ガイド
+tags: [ai, guide, ospec]
+---
+
+# AI ガイド
+
+## 目的
+
+この文書は OSpec 母仕様からコピーされた、プロジェクト採用済みの AI ガイドです。AI は母リポジトリの規則を即興で当てはめるのではなく、まずこのプロジェクト採用ルールに従う必要があります。
+
+## 作業順序
+
+1. `.skillrc` を読む
+2. `SKILL.index.json` を読む
+3. `docs/project/` 配下のプロジェクト採用ルールを読む
+4. 関連する `SKILL.md` を読む
+5. 現在の change 実行ファイルを読む
+6. Stitch が有効で、現在の change が `stitch_design_review` を有効化している場合は、先に `artifacts/stitch/approval.json` を確認する
+7. Stitch のインストール、provider 切り替え、doctor 修復、MCP 設定、認証設定が必要な場合は、先にリポジトリ内の Stitch 仕様を読む。`docs/stitch-plugin-spec.zh-CN.md` が存在する場合、その設定断片を正とみなす
+
+## 必須動作
+
+- `proposal.md`、`tasks.md`、`verification.md`、`review.md` はプロジェクト採用の文書言語で維持する
+- 製品 UI、サイト locale、または「英語優先」という要件だけから change 文書言語を推測しない
+- プロジェクト採用プロトコルが中国語、または現在の change 文書がすでに中国語なら、明示的なルール変更がない限り change 文書は中国語のまま維持する
+- 目的の文書を読む前に、まず index を使って知識の所在を確認する
+- 実装作業前にプロジェクト採用ルールを読む
+- `stitch_design_review` が有効で `approval.json.preview_url` または `submitted_at` が空なら、まず `ospec plugins run stitch <change-path>` を実行して preview を生成し、その URL をユーザーに送る
+- `.skillrc.plugins.stitch.project.project_id` が既に設定されている場合は、その Stitch project を再利用し、新しい project を作成しない
+- `.skillrc.plugins.stitch.project.project_id` が空なら、最初に成功した Stitch 実行を canonical project として以後も再利用する
+- `stitch_design_review` が有効で `approval.json.status != approved` の間は、デザインレビューゲートで停止する
+- Stitch のページレビューでは、各業務ルートにつき canonical layout を 1 つだけ維持する
+- `light/dark` を作る場合は同じ canonical screen から派生し、モジュール順、情報設計、CTA の位置、構成を変えない
+- 対応するページが既にある場合は `edit existing screen` または `duplicate existing canonical screen and derive a theme variant` を優先する
+- すべての Stitch 成果物には、route、canonical dark/light screen id、派生関係、archived screen id を含む `screen mapping` が必要
+- 古い画面、探索案、置き換え済み画面は canonical 画面と並列の main page として残さず、archive または rename する
+- canonical 選定、theme pairing、screen mapping、重複整理が欠けている場合は、レビュー完了とみなさない
+- `ospec plugins run stitch <change-path>` は既定で設定済み provider adapter を使う。`.skillrc.plugins.stitch.runner` を明示的に上書きしている場合のみ custom runner を使う
+- custom runner で `token_env` を使う場合は、対応する環境変数が設定済みかを確認する
+- runner、Gemini CLI、Codex CLI、stitch MCP、認証準備が不明な場合は、まず `ospec plugins doctor stitch <project-path>` を実行する
+- `plugins doctor stitch` が選択 provider のチェックで PASS 以外を返したら、必要な CLI の導入と stitch MCP / API token 設定をユーザーに依頼する
+- Stitch のインストール、provider 切り替え、doctor 修復、MCP 設定、認証設定では、まずリポジトリ内の Stitch 仕様を読む。`docs/stitch-plugin-spec.zh-CN.md` が存在する場合は、Gemini / Codex の設定形をそのまま使い、回避目的の別設定を即興で作らない
+- 内蔵 `codex` provider が read-only 呼び出しでは成功するのに `create_project`、`generate_screen`、`edit_screens` が止まる場合は、`codex exec --dangerously-bypass-approvals-and-sandbox` が実際に使われているか確認する
+- プロジェクトが `.skillrc.plugins.stitch.runner` を明示的に上書きし、それでも Codex が Stitch 書き込みを担当する場合は、その custom runner / wrapper でも `--dangerously-bypass-approvals-and-sandbox` を渡す
+- 重要なコード変更後は `SKILL.md` を同期する
+- 必要に応じて `SKILL.index.json` を再生成する
+
+## プロジェクト採用ルール優先
+
+- 命名規約: `docs/project/naming-conventions.md`
+- SKILL 規約: `docs/project/skill-conventions.md`
+- ワークフロー規約: `docs/project/workflow-conventions.md`
+- 開発ガイド: `docs/project/development-guide.md`

package/assets/for-ai/ja-JP/execution-protocol.md

@@ -0,0 +1,44 @@
+---
+name: project-execution-protocol
+title: 実行プロトコル
+tags: [ai, protocol, ospec]
+---
+
+# AI 実行プロトコル
+
+## プロジェクトに入るたびに最初に読むもの
+
+1. `.skillrc`
+2. `SKILL.index.json`
+3. `docs/project/naming-conventions.md`
+4. `docs/project/skill-conventions.md`
+5. `docs/project/workflow-conventions.md`
+6. 現在の change ファイル: `proposal.md / tasks.md / state.json / verification.md`
+7. `stitch_design_review` がある場合は `artifacts/stitch/approval.json`
+8. Stitch provider、MCP、認証設定を変更する必要がある場合は、先にリポジトリ内の Stitch 仕様を読む。`docs/stitch-plugin-spec.zh-CN.md` が存在する場合、その設定断片を正とみなす
+
+## 必須ルール
+
+- `proposal.md`、`tasks.md`、`verification.md`、`review.md` はプロジェクト採用の文書言語で維持する
+- 製品 UI やサイト locale が英語中心でも、それだけを理由に change 文書を英語へ書き換えない
+- 現在の change 文書が既に中国語なら、プロジェクトルールが明示的に英語切り替えを要求しない限り中国語のまま続ける
+- proposal/tasks を飛ばして実装へ直行しない
+- 実行状態の正は `state.json` とする
+- 有効化された optional step は `tasks.md` と `verification.md` に出現していなければならない
+- `stitch_design_review` が有効で `approval.json.preview_url` または `submitted_at` が空なら、まず `ospec plugins run stitch <change-path>` を実行して preview を提出する
+- Stitch のデザインレビューでは、ルートごとに canonical layout を 1 つだけ維持する。非 canonical 画面は `archive / old / exploration` として明示する
+- `light/dark` の theme 変体では canonical layout を維持し、モジュール再配置、セクション再編、CTA 移動、ナビ構造変更をしない
+- 対応ページが既にある場合は `edit existing screen` または `duplicate existing canonical screen and derive a theme variant` を優先する
+- Stitch 成果物は route、canonical dark/light screen id、派生関係、archived screen id を含む `screen mapping` を必ず出力する
+- 古い画面、探索画面、置き換え済み画面を canonical 画面の横に main page として残さない
+- `.skillrc.plugins.stitch.project.project_id` が存在する場合は、その Stitch project を再利用し、この change 用に別 project を作成しない
+- canonical Stitch project がまだ空なら、最初に成功した Stitch 提出が canonical project になる
+- Stitch 実行前は、既定では設定済み provider が使われるとみなす。`.skillrc.plugins.stitch.runner` が明示的に上書きされている場合のみ custom runner を使う
+- custom runner で `token_env` を使う場合は、対応する環境変数が設定済みか確認する
+- ローカル Stitch bridge、Gemini CLI、Codex CLI、stitch MCP、認証準備が不明なら、まず `ospec plugins doctor stitch <project-path>` を実行する
+- `plugins doctor stitch` が provider、MCP、認証の問題を示した場合は、まずリポジトリ内 Stitch 仕様に戻る。`docs/stitch-plugin-spec.zh-CN.md` がある場合、その仕様外の代替設定を作らない
+- 内蔵 `codex` provider が read-only 呼び出しは完了できるのに `create_project`、`generate_screen`、`edit_screens` が止まる場合は、`codex exec --dangerously-bypass-approvals-and-sandbox` が使われているか確認する
+- プロジェクトが `.skillrc.plugins.stitch.runner` を明示的に上書きしつつ Codex で Stitch 書き込みを行う場合は、custom runner / wrapper でも `--dangerously-bypass-approvals-and-sandbox` を渡す
+- `stitch_design_review` が有効で `approval.json.status != approved` の間は、その change を継続実装、完了、archive 可能と扱わない
+- canonical 選定、theme pairing、screen mapping、重複整理が欠けている場合は、デザインレビュー通過とみなさない
+- `SKILL.md` と index がずれている状態を完了扱いしない

package/assets/project-conventions/ar/development-guide.md

@@ -0,0 +1,31 @@
+---
+name: project-development-guide
+title: دليل تطوير المشروع
+tags: [conventions, development, ospec]
+---
+
+# دليل تطوير المشروع
+
+## الهدف
+
+هذا الملف هو دليل التطوير المعتمد داخل المشروع الذي يربط بين تخطيط المشروع وطبقة المعرفة وطبقة التنفيذ وقواعد التعاون مع الذكاء الاصطناعي.
+
+## الخط الأساسي
+
+- تعيش معرفة المشروع طويلة الأمد في `docs/project/`
+- تعيش الحقائق الحالية في ملفات `SKILL.md` متعددة الطبقات
+- تعيش تنفيذات change في `changes/active/<change>/`
+- تعيش نقاط دخول تنفيذ الذكاء الاصطناعي في `for-ai/`
+
+## المسار الموصى به
+
+1. أكّد الاتفاقيات المعتمدة للمشروع
+2. اقرأ طبقة معرفة المشروع وملفات `SKILL.md` ذات الصلة
+3. ادخل إلى change النشط
+4. زامن الوثائق والفهرس بعد التنفيذ
+
+## تجنب
+
+- لا تدع الذكاء الاصطناعي يخترع اتفاقيات التسمية أثناء العمل
+- لا تتجاوز `changes/` في الأعمال طويلة الأمد
+- لا تحدّث الكود من دون تحديث طبقة المعرفة

package/assets/project-conventions/ar/naming-conventions.md

@@ -0,0 +1,37 @@
+---
+name: project-naming-conventions
+title: اتفاقيات تسمية المشروع
+tags: [conventions, naming, ospec]
+---
+
+# اتفاقيات التسمية
+
+## الهدف
+
+هذا الملف هو النسخة المعتمدة داخل المشروع من مواصفة OSpec الأم. وهو يثبت قواعد التسمية داخل المشروع حتى لا يخترع الذكاء الاصطناعي أو البشر أنماط تسمية عشوائية.
+
+## القواعد الأساسية
+
+- تستخدم أسماء الأدلة والوحدات وchanges صيغة kebab-case الصغيرة
+- تستخدم flags وoptional steps صيغة snake_case الصغيرة
+- تحتفظ ملفات بروتوكول workflow بأسمائها الثابتة
+- تستخدم وثائق API أسماء semantic بصيغة kebab-case
+
+## أسماء change
+
+- استخدم `changes/active/<change-name>/`
+- مثال: `add-token-refresh`
+- تجنب التواريخ والمسافات والأحرف الكبيرة والتسميات غير الدلالية
+
+## أسماء الوحدات
+
+- تستخدم أدلة الوحدات أسماء إنجليزية دلالية
+- مثال: `src/modules/auth`, `src/modules/content`
+- تحتفظ كل وحدة بملف `SKILL.md` في جذرها
+
+## أسماء الوثائق
+
+- وثائق المشروع في `docs/project/`
+- وثائق التصميم في `docs/design/`
+- وثائق التخطيط في `docs/planning/`
+- وثائق API في `docs/api/`

package/assets/project-conventions/ar/skill-conventions.md

@@ -0,0 +1,33 @@
+---
+name: project-skill-conventions
+title: اتفاقيات SKILL
+tags: [conventions, skill, ospec]
+---
+
+# اتفاقيات SKILL
+
+## الهدف
+
+يثبت هذا الملف حدود المسؤولية لملفات `SKILL.md` متعددة الطبقات حتى يتمكن الذكاء الاصطناعي من الوصول إلى السياق بشكل ثابت عبر الفهرس ثم قراءة وثيقة المعرفة الصحيحة.
+
+## البنية متعددة الطبقات
+
+- `SKILL.md` الجذري: خريطة دخول المشروع
+- `docs/SKILL.md`: مركز docs
+- `src/SKILL.md`: خريطة المصدر
+- `src/core/SKILL.md`: طبقة المنصة الأساسية
+- `src/modules/<module>/SKILL.md`: وحدة معرفة خاصة بالوحدة
+- `tests/SKILL.md`: استراتيجية الاختبارات ومدخلها
+
+## قواعد التحرير
+
+- توثق ملفات `SKILL.md` الحقائق الحالية لا الخطط المستقبلية
+- يجب أن تغطي ملفات `SKILL.md` الخاصة بالوحدات المسؤوليات والبنية وAPI والاعتماديات وتوقعات الاختبار
+- عند تغير API أو الحدود، حدّث ملف `SKILL.md` الموافق
+- عند إنشاء وحدة جديدة، أضف ملف `SKILL.md` الخاص بها
+
+## العلاقة مع الفهرس
+
+- `SKILL.index.json` للاكتشاف وليس بديلاً عن `SKILL.md`
+- أعد بناء الفهرس بعد تحديث `SKILL.md`
+- يجب على الذكاء الاصطناعي قراءة الفهرس أولاً ثم ملف `SKILL.md` الهدف

package/assets/project-conventions/ar/workflow-conventions.md

@@ -0,0 +1,40 @@
+---
+name: project-workflow-conventions
+title: اتفاقيات تنفيذ workflow
+tags: [conventions, workflow, change, ospec]
+---
+
+# اتفاقيات تنفيذ workflow
+
+## الهدف
+
+تثبت هذه الوثيقة مسار تنفيذ OSpec داخل المشروع حتى تنتقل المتطلبات عبر planning وimplementation وverification وarchive مع بوابات متسقة.
+
+## الترتيب القياسي
+
+1. توضيح سياق المشروع ونطاق التأثير
+2. إنشاء `proposal.md` أو تحديثه
+3. إنشاء `tasks.md` أو تحديثه
+4. دفع التنفيذ وفق `state.json`
+5. تحديث `SKILL.md` ذي الصلة
+6. إعادة بناء `SKILL.index.json`
+7. إكمال `verification.md`
+8. الأرشفة فقط بعد اجتياز جميع البوابات
+
+## قيود الحالة
+
+- استخدم `state.json` كمصدر الحقيقة لحالة التنفيذ
+- لا يستبدل `verification.md` ملف `state.json`
+- إذا اختلفت ملفات الحالة وملفات التنفيذ، أصلح الحالة أولاً
+
+## لغة الوثائق
+
+- حافظ على `proposal.md` و`tasks.md` و`verification.md` و`review.md` باللغة المعتمدة للمشروع
+- قد تختلف لغة واجهة المنتج عن لغة وثائق OSpec الخاصة بالchange؛ لا تستنتج إحداهما من الأخرى
+- إذا أُنشىء change بالصينية، فاستمر بالصينية ما لم تتطلب قواعد المشروع التحويل إلى الإنجليزية صراحةً
+
+## optional steps
+
+- يتم التحكم في تفعيل optional steps عبر `.skillrc.workflow`
+- يجب أن تبقى proposal flags متوافقة مع إعدادات workflow
+- يجب أن تظهر optional steps المفعلة في `tasks.md` و`verification.md`

package/assets/project-conventions/ja-JP/development-guide.md

@@ -0,0 +1,31 @@
+---
+name: project-development-guide
+title: プロジェクト開発ガイド
+tags: [conventions, development, ospec]
+---
+
+# プロジェクト開発ガイド
+
+## 目的
+
+このファイルは、プロジェクト計画、知識レイヤー、実行レイヤー、AI 協業ルールをつなぐ、プロジェクト採用済みの開発ガイドです。
+
+## ベースライン
+
+- 長期的なプロジェクト知識は `docs/project/` に置く
+- 現在の事実はレイヤー化された `SKILL.md` に置く
+- change 実行は `changes/active/<change>/` に置く
+- AI 実行の入口は `for-ai/` に置く
+
+## 推奨フロー
+
+1. プロジェクト採用規約を確認する
+2. プロジェクト知識レイヤーと関連 `SKILL.md` を読む
+3. active change に入る
+4. 実装後に文書と index を同期する
+
+## 避けること
+
+- AI にその場で命名規則を発明させない
+- 長期作業で `changes/` を迂回しない
+- 知識レイヤーを更新せずにコードだけ変えない

package/assets/project-conventions/ja-JP/naming-conventions.md

@@ -0,0 +1,45 @@
+---
+name: project-naming-conventions
+title: プロジェクト命名規約
+tags: [conventions, naming, ospec]
+---
+
+# 命名規約
+
+## 目的
+
+このファイルは OSpec 母仕様をプロジェクト内に取り込んだものです。AI と人間が場当たり的な命名を発明しないよう、プロジェクト内の命名規則を固定します。
+
+## 基本ルール
+
+- ディレクトリ、モジュール、change 名は小文字の kebab-case を使う
+- flags と optional steps は小文字の snake_case を使う
+- ワークフロープロトコルファイルは固定ファイル名を保つ
+- API 文書は意味のある kebab-case 名を使う
+
+## change 名
+
+- `changes/active/<change-name>/` を使う
+- 例: `add-token-refresh`
+- 日付、空白、大文字、意味の薄いラベルは避ける
+
+## モジュール名
+
+- モジュールディレクトリは意味のある英語名を使う
+- 例: `src/modules/auth`, `src/modules/content`
+- 各モジュールはルートに `SKILL.md` を置く
+
+## 文書名
+
+- プロジェクト文書は `docs/project/`
+- 設計文書は `docs/design/`
+- 計画文書は `docs/planning/`
+- API 文書は `docs/api/`
+
+## 固定プロトコルファイル
+
+- `proposal.md`
+- `tasks.md`
+- `state.json`
+- `verification.md`
+- `review.md`

package/assets/project-conventions/ja-JP/skill-conventions.md

@@ -0,0 +1,33 @@
+---
+name: project-skill-conventions
+title: SKILL 規約
+tags: [conventions, skill, ospec]
+---
+
+# SKILL 規約
+
+## 目的
+
+このファイルはレイヤー化された `SKILL.md` の責務境界を固定し、AI が index を使って正しい知識文書へ一貫して到達できるようにします。
+
+## レイヤー構造
+
+- ルート `SKILL.md`: プロジェクト入口マップ
+- `docs/SKILL.md`: docs ハブ
+- `src/SKILL.md`: ソースマップ
+- `src/core/SKILL.md`: コア基盤レイヤー
+- `src/modules/<module>/SKILL.md`: モジュール知識単位
+- `tests/SKILL.md`: テスト戦略と入口
+
+## 作成ルール
+
+- `SKILL.md` は将来計画ではなく現在の事実を記述する
+- モジュール `SKILL.md` は責務、構造、API、依存関係、テスト期待を扱う
+- API や境界が変わったら関連する `SKILL.md` を更新する
+- 新しいモジュールを作成したら、その `SKILL.md` を追加する
+
+## index との関係
+
+- `SKILL.index.json` は発見用であり、`SKILL.md` の代替ではない
+- `SKILL.md` 更新後は index を再生成する
+- AI はまず index を読み、その後に対象 `SKILL.md` を読む

package/assets/project-conventions/ja-JP/workflow-conventions.md

@@ -0,0 +1,40 @@
+---
+name: project-workflow-conventions
+title: ワークフロー実行規約
+tags: [conventions, workflow, change, ospec]
+---
+
+# ワークフロー実行規約
+
+## 目的
+
+この文書はプロジェクト内の OSpec 実行フローを固定し、要件が planning、implementation、verification、archive を一貫した gate で通過できるようにします。
+
+## 標準順序
+
+1. プロジェクト文脈と影響範囲を確認する
+2. `proposal.md` を作成または更新する
+3. `tasks.md` を作成または更新する
+4. `state.json` に従って実装を進める
+5. 関連する `SKILL.md` を更新する
+6. `SKILL.index.json` を再生成する
+7. `verification.md` を完了させる
+8. すべての gate 通過後にだけ archive する
+
+## 状態制約
+
+- 実行状態の正は `state.json` とする
+- `verification.md` は `state.json` の代わりにならない
+- 状態ファイルと実行ファイルが矛盾する場合は、まず状態を直す
+
+## 文書言語
+
+- `proposal.md`、`tasks.md`、`verification.md`、`review.md` はプロジェクト採用文書言語で維持する
+- 製品 UI 言語と OSpec change 文書言語は異なってよく、片方からもう片方を推測しない
+- change が中国語で作成されている場合は、プロジェクトルールが明示的に英語切り替えを要求しない限り中国語で継続する
+
+## optional steps
+
+- optional step の有効化は `.skillrc.workflow` で管理する
+- proposal flags は workflow 設定と整合していなければならない
+- 有効化された optional step は `tasks.md` と `verification.md` に必ず出す

package/dist/cli.js

@@ -224,10 +224,10 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.3.3';
+const CLI_VERSION = '0.3.4';
 
 function showInitUsage() {
-    console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language zh-CN|en-US]');
+    console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language en-US|zh-CN|ja-JP|ar]');
 }
 
 function parseInitCommandArgs(commandArgs) {

package/dist/commands/NewCommand.js

@@ -131,10 +131,10 @@ class NewCommand extends BaseCommand_1.BaseCommand {
         if (guideLanguage) {
             return guideLanguage;
         }
-        return 'zh-CN';
+        return 'en-US';
     }
     normalizeDocumentLanguage(input) {
-        return input === 'en-US' || input === 'zh-CN' ? input : null;
+        return input === 'en-US' || input === 'zh-CN' || input === 'ja-JP' || input === 'ar' ? input : null;
     }
     async readDocumentLanguageFromAssetManifest(targetDir) {
         const manifestPath = path.join(targetDir, '.ospec', 'asset-sources.json');
@@ -151,6 +151,12 @@ class NewCommand extends BaseCommand_1.BaseCommand {
             for (const targetRelativePath of ['for-ai/ai-guide.md', 'for-ai/execution-protocol.md']) {
                 const asset = assets.find(item => item?.targetRelativePath === targetRelativePath);
                 const sourceRelativePath = typeof asset?.sourceRelativePath === 'string' ? asset.sourceRelativePath : '';
+                if (sourceRelativePath.includes('/ar/')) {
+                    return 'ar';
+                }
+                if (sourceRelativePath.includes('/ja-JP/')) {
+                    return 'ja-JP';
+                }
                 if (sourceRelativePath.includes('/en-US/')) {
                     return 'en-US';
                 }
@@ -171,18 +177,43 @@ class NewCommand extends BaseCommand_1.BaseCommand {
         }
         try {
             const content = await services_1.services.fileService.readFile(aiGuidePath);
-            if (/[一-龥]/.test(content)) {
-                return 'zh-CN';
-            }
-            if (/[A-Za-z]/.test(content)) {
-                return 'en-US';
-            }
+            return this.detectDocumentLanguageFromText(content) || null;
         }
         catch {
             return null;
         }
         return null;
     }
+    detectDocumentLanguageFromText(content) {
+        if (typeof content !== 'string' || content.trim().length === 0) {
+            return null;
+        }
+        if (/[\u0600-\u06FF]/.test(content)) {
+            return 'ar';
+        }
+        if (/[ぁ-ゟ゠-ヿ]/.test(content)) {
+            return 'ja-JP';
+        }
+        if (this.isLikelyJapaneseKanjiContent(content)) {
+            return 'ja-JP';
+        }
+        if (/[一-龥]/.test(content)) {
+            return 'zh-CN';
+        }
+        if (/[A-Za-z]/.test(content)) {
+            return 'en-US';
+        }
+        return null;
+    }
+    isLikelyJapaneseKanjiContent(content) {
+        if (!/[一-龥]/.test(content)) {
+            return false;
+        }
+        if (/[々〆ヵヶ「」『』]/.test(content)) {
+            return true;
+        }
+        return /(一覧|詳細|設定|権限|検索|構成|変更|確認|対応|連携|承認|申請|手順|履歴|機能|実装|設計|運用|画面|帳票|組織|拠点|区分|種別|完了|開始|終了|表示|取得|追加|削除|更新|登録)/.test(content);
+    }
     async ensureChangeNameAvailable(targetDir, featureName) {
         const activeDir = PathUtils_1.PathUtils.getChangeDir(targetDir, constants_1.DIR_NAMES.ACTIVE, featureName);
         const queuedDir = PathUtils_1.PathUtils.getChangeDir(targetDir, constants_1.DIR_NAMES.QUEUED, featureName);

package/dist/core/types.d.ts

@@ -92,6 +92,7 @@ export interface CheckpointPluginConfig {
 export interface SkillrcConfig {
     version: string;
     mode: ProjectMode;
+    documentLanguage?: 'en-US' | 'zh-CN' | 'ja-JP' | 'ar';
     hooks: {
         'pre-commit': boolean;
         'post-merge': boolean;

package/dist/presets/ProjectPresets.d.ts

@@ -1,6 +1,6 @@
 import { ProjectMode } from '../core/types';
 export type ProjectPresetId = 'official-site' | 'nextjs-web';
-export type ProjectPresetDocumentLanguage = 'zh-CN' | 'en-US';
+export type ProjectPresetDocumentLanguage = 'zh-CN' | 'en-US' | 'ja-JP' | 'ar';
 export interface ProjectPresetFirstChangeSuggestion {
     name: string;
     background: string;
@@ -38,4 +38,4 @@ export declare const getLocalizedProjectPresetContent: (presetId: ProjectPresetI
 export declare const inferProjectPresetFromDescription: (description: string) => ProjectPresetDefinition | undefined;
 export declare const getProjectPresetFirstChangeSuggestion: (presetId: ProjectPresetId | null | undefined, language: ProjectPresetDocumentLanguage, projectName: string) => ProjectPresetFirstChangeSuggestion | null;
 export {};
-//# sourceMappingURL=ProjectPresets.d.ts.map
+//# sourceMappingURL=ProjectPresets.d.ts.map