@clawplays/ospec-cli 0.3.2 → 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/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: ospec
+description: Document-driven OSpec workflow for AI-assisted development with change-ready initialization, execution, validation, and archive readiness.
+tags: [cli, workflow, automation, typescript, ospec, bootstrap]
+---
+
+# OSpec CLI
+
+Document-driven OSpec workflow for AI-assisted development with change-ready initialization, execution, validation, archiving, and docs maintenance.
+
+## Default Entry
+
+When the user says something short like:
+
+- `使用 ospec 初始化项目`
+- `使用 ospec 初始化这个目录`
+- `use ospec to initialize this directory`
+- `use ospec to initialize this repo`
+
+expand it internally as:
+
+1. initialize the repository with `ospec init` so it ends in a change-ready state
+2. if project context is missing and the AI can ask follow-up questions, ask one concise question for project summary or tech stack
+3. if the user declines or the flow is CLI-only, continue with placeholder project docs
+4. create the first change only when explicitly requested
+
+Do not force the user to repeat those steps manually when the request is already clear.
+
+Treat plain project-init intent as enough to trigger this flow. Do not require the user to restate the guardrails in a longer prompt.
+
+## Mandatory Init Execution
+
+When the user asks to initialize a directory, do not freehand the initialization flow.
+
+If the user intent is simply to initialize the project or current directory, treat that as a request for this mandatory flow.
+
+Use this exact behavior:
+
+1. run `ospec init [path]` when the directory is uninitialized or not yet change-ready
+2. if AI assistance is available and the repository lacks usable project context, ask one concise follow-up for summary or tech stack before init when helpful
+3. verify the actual filesystem result before claiming initialization is complete
+4. stop before `ospec new` unless the user explicitly asks to create a change
+
+Never replace `ospec init` with manual directory creation or a hand-written approximation.
+
+Do not say initialization is complete unless the managed protocol-shell assets and baseline project knowledge docs actually exist on disk.
+
+Required checks after `ospec init`:
+
+- `.skillrc`
+- `.ospec/`
+- `changes/active/`
+- `changes/archived/`
+- `SKILL.md`
+- `SKILL.index.json`
+- `build-index-auto.cjs`
+- `for-ai/ai-guide.md`
+- `for-ai/execution-protocol.md`
+- `for-ai/naming-conventions.md`
+- `for-ai/skill-conventions.md`
+- `for-ai/workflow-conventions.md`
+- `for-ai/development-guide.md`
+- `docs/project/overview.md`
+- `docs/project/tech-stack.md`
+- `docs/project/architecture.md`
+- `docs/project/module-map.md`
+- `docs/project/api-overview.md`
+
+During plain init, do not report `docs/SKILL.md`, `src/SKILL.md`, `tests/SKILL.md`, or business scaffold as if they were part of change-ready completion.
+
+## Prompt Profiles
+
+Use these prompt styles as the preferred mental model.
+
+### 1. Minimal Prompt
+
+Use when the user already trusts OSpec defaults.
+
+```text
+Use ospec to initialize this project.
+```
+
+### 2. Standard Prompt
+
+Use when you want short prompts and still want OSpec to finish initialization properly.
+
+```text
+Use ospec to initialize this project according to current OSpec rules.
+```
+
+### 3. Guided Init Prompt
+
+Use when you want the AI to gather missing context before initialization if needed.
+
+```text
+Use ospec to initialize this project. If project context is missing, ask me for a short summary or tech stack first. If I skip it, continue with placeholder docs.
+```
+
+### 4. Docs Maintenance Prompt
+
+Use when the repository is already initialized and the project knowledge layer needs a refresh or repair pass.
+
+```text
+Use ospec to refresh or repair the project knowledge layer for this directory. Do not create a change yet.
+```
+
+### 5. Change-Creation Prompt
+
+Use when the user is explicitly ready to move into execution.
+
+```text
+Use ospec to create and advance a change for this requirement. Respect the current project state and do not create queue work unless I ask for it.
+```
+
+### 6. Queue Prompt
+
+Use when the user explicitly wants multiple changes queued instead of one normal active change.
+
+```text
+Use ospec to break this TODO into multiple changes, create a queue, show the queue first, and do not run it yet.
+```
+
+### 7. Queue-Run Prompt
+
+Use when the user explicitly wants queue execution, not the normal single-change flow.
+
+```text
+Use ospec to create a change queue and execute it explicitly with ospec run manual-safe.
+```
+
+## Anti-Drift Rules
+
+Always keep these rules:
+
+- `ospec init` should leave the repository in a change-ready state
+- AI-assisted init may ask one concise follow-up question for missing summary or tech stack; if the user declines, continue with placeholder docs
+- `ospec docs generate` refreshes, repairs, or backfills project knowledge docs after initialization
+- when the user asks to initialize, execute the CLI init command and verify the protocol-shell files and `docs/project/*` files on disk before declaring success
+- do not assume the project is a web or Next.js project unless the repository or user makes that explicit
+- do not apply business scaffold during plain init or docs maintenance
+- do not generate `docs/project/bootstrap-summary.md`
+- do not create the first change automatically unless the user explicitly asks to create a change
+- do not enter queue mode unless the user explicitly asks for queue behavior
+- treat planning defaults as guidance, not as init-time templates
+- use the CLI commands for verification, archiving, and targeted inspection instead of ad-hoc filesystem edits
+
+## What The CLI Manages
+
+This CLI now covers:
+
+- change-ready initialization
+- project knowledge maintenance
+- layered skill files
+- execution-layer change workflow
+- planning defaults for proposal and task setup
+- explicit business scaffold generation when that scope is requested
+- Codex and Claude Code skill install and sync checks
+
+## Canonical Execution Files
+
+Treat these as the source of truth for active delivery work:
+
+- `.skillrc`
+- `docs/project/overview.md`
+- `docs/project/tech-stack.md`
+- `docs/project/architecture.md`
+- `changes/active/<change>/proposal.md`
+- `changes/active/<change>/tasks.md`
+- `changes/active/<change>/state.json`
+- `changes/active/<change>/verification.md`
+
+## Plugin Gates
+
+Before advancing an active change:
+
+- read `.skillrc.plugins` to detect enabled blocking plugins
+- if the current change activates `stitch_design_review`, inspect `changes/active/<change>/artifacts/stitch/approval.json`
+- when Stitch approval is missing or `status != approved`, treat the change as blocked and do not claim it is ready to continue or archive
+
+Do not fall back to the old `features/...` layout unless the target repository really still uses it.
+
+## Commands To Prefer
+
+```bash
+ospec status [path]
+ospec init [path]
+ospec init [path] --summary "..." --tech-stack node,react
+ospec docs generate [path]
+ospec new <change-name> [path]
+ospec docs status [path]
+ospec skills status [path]
+ospec changes status [path]
+ospec queue status [path]
+ospec queue add <change-name> [path]
+ospec queue next [path]
+ospec run start [path] --profile manual-safe
+ospec run status [path]
+ospec run step [path]
+ospec run resume [path]
+ospec run stop [path]
+ospec plugins status [path]
+ospec plugins approve stitch [changes/active/<change>]
+ospec plugins reject stitch [changes/active/<change>]
+ospec index check [path]
+ospec index build [path]
+ospec workflow show
+ospec workflow list-flags
+ospec progress [changes/active/<change>]
+ospec verify [changes/active/<change>]
+ospec archive [changes/active/<change>]
+ospec archive [changes/active/<change>] --check
+ospec finalize [changes/active/<change>]
+ospec skill status ospec
+ospec skill install ospec
+ospec skill status ospec-change
+ospec skill install ospec-change
+ospec skill status-claude ospec
+ospec skill install-claude ospec
+ospec skill status-claude ospec-change
+ospec skill install-claude ospec-change
+```
+
+Managed auto-sync targets for global install, `ospec init`, and `ospec update` are:
+
+- `ospec`
+- `ospec-change`
+
+Additional packaged skills remain available for explicit install, for example:
+
+```bash
+ospec skill install ospec-init
+ospec skill install-claude ospec-init
+```
+
+Preferred execution order for a new directory:
+
+```bash
+ospec init [path]
+ospec new <change-name> [path]
+ospec verify [changes/active/<change>]
+ospec finalize [changes/active/<change>]
+```
+
+Use `ospec docs generate [path]` later when you need a docs-only maintenance pass.
+
+Use `ospec status [path]` separately when you want an explicit troubleshooting snapshot.
+
+For completed changes, archive before commit. Use `ospec archive [changes/active/<change>]` to execute the archive and `--check` only when you want a readiness preview without moving files.
+
+For the normal closeout path, prefer `ospec finalize [changes/active/<change>]`. It should verify completeness, rebuild the index, archive the change, and leave Git commit as a separate manual step.
+
+## Project-Type Rules
+
+If the repository type is unclear:
+
+- inspect the real directory only when needed for troubleshooting or context gathering
+- let initialization stay stack-agnostic
+- allow the project to stay minimal except for OSpec-managed assets and baseline project docs
+- let later skills or explicit project-knowledge steps shape the actual stack
+
+This is important because valid OSpec projects include:
+
+- web applications
+- CLI tools
+- Unity projects
+- Godot projects
+- desktop apps
+- service backends
+- protocol-only repositories
+
+## Verification Discipline
+
+Before saying work is complete:
+
+1. verify the relevant active change
+2. confirm docs, skills, and index state if project knowledge changed
+3. keep `SKILL.index.json` current after meaningful skill updates
+4. treat `SKILL.index.json` section offsets as LF-normalized so Windows CRLF and Linux LF checkouts do not drift

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OSpec"
+  short_description: "Inspect, initialize, and operate OSpec projects"
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: use ospec init so the repository ends in change-ready state, reuse existing project docs when available, ask one concise follow-up for missing summary or tech stack in AI-assisted flows, fall back to placeholder docs when the user skips that context, do not assume a web template when the project type is unclear, do not create the first change automatically, and use ospec status or ospec changes status only when you need an explicit summary."

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` الهدف