@clawplays/ospec-cli 0.3.10 → 1.0.0

package/README.md

@@ -23,13 +23,13 @@
 
 The official OSpec CLI package is `@clawplays/ospec-cli`, and the official command is `ospec`. OSpec supports spec-driven development (SDD) and document-driven development for AI coding agents and CLI workflows.
 
-OSpec.ai is the official project site. `OSpec`, `ospec`, `ospec.ai`, `ospec ai`, `ospecai`, and `ospec-ai` all point to the same official project and CLI.
-
 <p align="center">
   <a href="docs/prompt-guide.md">Prompt Guide</a> |
   <a href="docs/usage.md">Usage</a> |
   <a href="docs/project-overview.md">Overview</a> |
   <a href="docs/installation.md">Installation</a> |
+  <a href="docs/external-plugins.md">External Plugins</a> |
+  <a href="docs/plugin-release.md">Plugin Release</a> |
   <a href="https://github.com/clawplays/ospec/issues">Issues</a>
 </p>
 
@@ -91,8 +91,10 @@ CLI notes:
 - `--architecture`: short architecture description
 - `--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`
+- CLI language resolution order: explicit `--document-language` -> persisted project language in `.skillrc` -> existing project docs / managed `for-ai/*` guidance / 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`
+- new projects initialized by `ospec init` default to the nested layout: root `.skillrc` and `README.md`, with OSpec-managed files under `.ospec/`
+- CLI commands still accept shorthand like `changes/active/<change-name>`, but the physical path in nested projects is `.ospec/changes/active/<change-name>`
 - 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
 
@@ -154,7 +156,8 @@ Archive notes:
 - run your project-specific deploy, test, and QA flow first
 - use `ospec verify` to confirm the active change is ready
 - use `ospec finalize` to rebuild indexes and archive the accepted change
-- new projects archive under `changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>`; existing flat archives are reorganized by `ospec update`
+- new nested projects archive under `.ospec/changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>`; CLI shorthand under `changes/archived/...` still works
+- existing flat archives are reorganized by `ospec update`
 
 </details>
 
@@ -167,6 +170,11 @@ ospec update
 ```
 
 `ospec update` also migrates legacy root-level `build-index-auto.cjs` / `build-index-auto.js` tooling into `.ospec/tools/build-index-auto.cjs` and refreshes OSpec-managed hook entrypoints to use the new location.
+It also repairs older OSpec projects that still have an OSpec footprint but are missing newer core runtime directories, refreshes managed skills and archive layout metadata, and syncs project assets for already-enabled plugins.
+When an already-enabled plugin has a newer compatible npm package version available, `ospec update` upgrades that global plugin package automatically and prints the version transition.
+It does not upgrade the CLI itself, and it does not enable plugins or migrate active / queued changes automatically.
+It also does not switch a classic project layout to nested automatically.
+If you want to convert an older classic project to the new layout, run `ospec layout migrate --to nested` explicitly.
 
 ## How The OSpec Workflow Works
 
@@ -181,10 +189,11 @@ ospec update
 │  2. INIT TO CHANGE-READY                                       │
 │     ospec init                                                 │
 │     - .skillrc                                                 │
+│     - README.md                                                │
 │     - .ospec/                                                  │
-│     - changes/active + changes/archived                        │
-│     - root SKILL files and for-ai guidance                     │
-│     - docs/project/* baseline knowledge docs                   │
+│     - .ospec/changes/active + .ospec/changes/archived          │
+│     - .ospec/SKILL.md + .ospec/SKILL.index.json + .ospec/for-ai│
+│     - .ospec/docs/project/* baseline knowledge docs            │
 │     - reuse docs or fall back to placeholders                  │
 └─────────────────────────────────────────────────────────────────┘
                               │
@@ -214,7 +223,7 @@ ospec update
 
 | Concept | What It Means |
 |---------|---------------|
-| **Protocol Shell** | The minimum collaboration skeleton: `.skillrc`, `.ospec/`, `changes/`, root `SKILL.md`, `SKILL.index.json`, and `for-ai/` guidance. |
+| **Protocol Shell** | The minimum collaboration skeleton: root `.skillrc` and `README.md`, plus managed OSpec files under `.ospec/` for change state, SKILL docs, index state, `for-ai/` guidance, and project docs. |
 | **Project Knowledge Layer** | Explicit project context such as `docs/project/*`, layered skill files, and index state that AI can read consistently. |
 | **Active Change** | A dedicated execution container for one requirement, usually with `proposal.md`, `tasks.md`, `state.json`, `verification.md`, and `review.md`. |
 
@@ -226,67 +235,40 @@ ospec update
 - **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.
-- **Plugin workflow gates**: built-in plugin commands support Stitch design review and Checkpoint automation.
+- **Plugin workflow gates**: plugin commands support Stitch design review and Checkpoint automation through npm-installed official plugins.
 - **Skill management**: install and inspect OSpec skills for Codex and Claude Code.
 - **Standard closeout**: `finalize` verifies, rebuilds indexes, and archives the change before manual Git commit.
 
-## Plugin Features
-
-OSpec includes two optional plugins that extend the document-driven workflow with UI review and flow validation.
-
-### Stitch
+## Plugin Installation
 
-Use Stitch for page design review and preview collaboration, especially for landing pages, marketing pages, and UI-heavy changes.
-
-AI conversation:
+OSpec supports plugins for UI review and runtime validation.
+Keep the public flow simple:
 
 ```text
-OSpec, enable the Stitch plugin and connect using Codex/Gemini.
+$ospec open Stitch for this project.
+$ospec open Checkpoint for this project.
 ```
 
-Claude / Codex skill mode:
+In AI / `$ospec` flows, requests like "open Stitch" or "open Checkpoint" should be handled as: check whether the plugin is already installed globally, install only when missing, then enable it in the current project.
 
-```text
-$ospec enable the Stitch plugin and connect using Codex/Gemini.
-```
-
-<details>
-<summary>Command line</summary>
+Command line fallback:
 
 ```bash
+ospec plugins list
+ospec plugins install stitch
 ospec plugins enable stitch .
-```
-
-</details>
-
-### Checkpoint
-
-Use Checkpoint for app flow validation and automated checks, especially for submission flows, critical paths, and pre-acceptance runtime verification.
-
-AI conversation:
-
-```text
-OSpec, enable the Checkpoint plugin.
-```
-
-Claude / Codex skill mode:
-
-```text
-$ospec enable the Checkpoint plugin.
-```
-
-<details>
-<summary>Command line</summary>
-
-```bash
+ospec plugins install checkpoint
 ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000
 ```
 
-Notes:
+Official npm plugin packages:
 
-- `--base-url` points to the running app used by automated checks
+- `@clawplays/ospec-plugin-stitch`
+- `@clawplays/ospec-plugin-checkpoint`
 
-</details>
+After a plugin is enabled, its detailed setup docs are synced into `.ospec/plugins/<plugin>/docs/`.
+
+Maintainers can find plugin publishing and automation details in `docs/plugin-release.md`.
 
 ## Documentation
 
@@ -297,11 +279,8 @@ Notes:
 - [Project Overview](docs/project-overview.md)
 - [Installation](docs/installation.md)
 - [Skills Installation](docs/skills-installation.md)
-
-### Plugin Specs
-
-- [Stitch Plugin Spec](docs/stitch-plugin-spec.zh-CN.md)
-- [Checkpoint Plugin Spec](docs/checkpoint-plugin-spec.zh-CN.md)
+- [External Plugins](docs/external-plugins.md)
+- [Plugin Release](docs/plugin-release.md)
 
 ## Repository Structure
 

package/SKILL.md

@@ -198,6 +198,9 @@ ospec run status [path]
 ospec run step [path]
 ospec run resume [path]
 ospec run stop [path]
+ospec plugins available
+ospec plugins info <plugin>
+ospec plugins install <plugin>
 ospec plugins status [path]
 ospec plugins approve stitch [changes/active/<change>]
 ospec plugins reject stitch [changes/active/<change>]

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

@@ -18,7 +18,7 @@ tags: [ai, guide, ospec]
 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` فاعتبر مقاطع الإعداد فيه هي المصدر المعتمد
+7. إذا احتجت إلى تثبيت Stitch أو Checkpoint أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة أو تفعيل الإضافة، فاقرأ أولاً مواصفة الإضافة المحلية في المستودع المطابقة للغة وثائق المشروع، ولا تنتقل إلى لغة أخرى إلا إذا كان الملف المطابق غير موجود
 
 ## السلوك المطلوب
 
@@ -41,7 +41,7 @@ tags: [ai, guide, ospec]
 - إذا استخدم 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 الموثق فيه بدلاً من ابتكار إعداد بديل
+- عند تثبيت Stitch أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة، اقرأ أولاً مواصفة Stitch المحلية المطابقة للغة وثائق المشروع، ثم انسخ شكل إعداد 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` بعد التغييرات البرمجية المهمة

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

@@ -15,7 +15,7 @@ tags: [ai, protocol, ospec]
 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` فاعتبر مقاطع الإعداد فيه مرجعية
+8. إذا كنت تحتاج إلى تعديل إعدادات Stitch أو Checkpoint المتعلقة بـ provider أو MCP أو المصادقة أو التثبيت أو التفعيل، فاقرأ أولاً مواصفة الإضافة المحلية المطابقة للغة الوثائق المعتمدة للمشروع، ولا تنتقل إلى لغة أخرى إلا إذا كان الملف المطابق غير موجود
 
 ## القواعد الإلزامية
 

package/assets/for-ai/en-US/ai-guide.md

@@ -18,7 +18,7 @@ This document is the project-adopted AI guide copied from the OSpec mother spec.
 4. Read the relevant `SKILL.md` files
 5. Read the current change execution files
 6. If Stitch is enabled and the current change activates `stitch_design_review`, inspect `artifacts/stitch/approval.json` first
-7. If you need to handle Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup, read the repo-local Stitch spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, treat its config snippets as the source of truth
+7. If you need to handle Stitch or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement, read the repo-local localized plugin docs under `.ospec/plugins/<plugin>/docs/` first; if they are missing, install or enable the plugin to sync its docs before changing config
 
 ## Required Behavior
 
@@ -41,7 +41,7 @@ This document is the project-adopted AI guide copied from the OSpec mother spec.
 - If the project uses a custom runner and `token_env` is configured, confirm the matching environment variable is set before running
 - If the runner, Gemini CLI, Codex CLI, stitch MCP, or auth readiness is unclear, run `ospec plugins doctor stitch <project-path>` first
 - If `plugins doctor stitch` reports non-PASS for the selected provider checks, prompt the user to install the required CLI and complete the stitch MCP / API token setup in the matching user config
-- For Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup, read the repo-local Stitch spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, copy the documented Gemini / Codex config shape instead of inventing a `command` / `args` / `env` or stdio-proxy workaround just to satisfy doctor
+- For Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup, read `.ospec/plugins/stitch/docs/` first and follow the plugin's documented config shape instead of inventing a `command` / `args` / `env` or stdio-proxy workaround just to satisfy doctor
 - If the built-in `codex` provider succeeds on read-only calls but `create_project`, `generate_screen`, or `edit_screens` stalls locally, first verify the run actually uses `codex exec --dangerously-bypass-approvals-and-sandbox`
 - If the project explicitly overrides `.skillrc.plugins.stitch.runner` and Codex still performs Stitch writes, the custom runner / wrapper must also pass `--dangerously-bypass-approvals-and-sandbox`
 - Sync `SKILL.md` after meaningful code changes
@@ -54,37 +54,10 @@ This document is the project-adopted AI guide copied from the OSpec mother spec.
 - Workflow conventions: `docs/project/workflow-conventions.md`
 - Development guide: `docs/project/development-guide.md`
 
-## Stitch Provider Baseline
+## Stitch Provider Docs
 
-- When `docs/stitch-plugin-spec.zh-CN.md` exists in the repo, use its original config snippets first.
-- When the repo does not contain that spec and the built-in Stitch provider must be enabled, use these baselines.
-- `gemini`: edit `%USERPROFILE%/.gemini/settings.json` and use `mcpServers.stitch.httpUrl` plus `headers.X-Goog-Api-Key`.
-
-```json
-{
-  "mcpServers": {
-    "stitch": {
-      "httpUrl": "https://stitch.googleapis.com/mcp",
-      "headers": {
-        "X-Goog-Api-Key": "your-stitch-api-key"
-      }
-    }
-  }
-}
-```
-
-- `codex`: edit `%USERPROFILE%/.codex/config.toml` and use HTTP transport, the fixed Stitch MCP URL, and the `X-Goog-Api-Key` header.
-- The built-in `codex` adapter should launch Stitch write operations through `codex exec --dangerously-bypass-approvals-and-sandbox`; if a custom runner replaces it, that runner must provide the same write-bypass behavior.
-
-```toml
-[mcp_servers.stitch]
-type = "http"
-url = "https://stitch.googleapis.com/mcp"
-headers = { X-Goog-Api-Key = "your-stitch-api-key" }
-
-[mcp_servers.stitch.http_headers]
-X-Goog-Api-Key = "your-stitch-api-key"
-```
+- Provider, MCP, auth, and runner details live in `.ospec/plugins/stitch/docs/` after the Stitch plugin is installed and enabled for the project.
+- If those docs are missing, install or enable Stitch first so the plugin can sync its localized docs into the repository before changing config.
 
 ## Stitch Canonical Layout
 

package/assets/for-ai/en-US/execution-protocol.md

@@ -15,7 +15,7 @@ tags: [ai, protocol, ospec]
 5. `docs/project/workflow-conventions.md`
 6. The current change files: `proposal.md / tasks.md / state.json / verification.md`
 7. If `stitch_design_review` exists, read `artifacts/stitch/approval.json`
-8. If Stitch provider, MCP, or auth config must be changed, read the repo-local Stitch spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, treat its config snippets as authoritative
+8. If Stitch or Checkpoint provider, MCP, auth, install, or enable config must be changed, read the repo-local localized plugin docs under `.ospec/plugins/<plugin>/docs/` first; if they are missing, install or enable the plugin to sync its docs before changing config
 
 ## Mandatory Rules
 
@@ -36,7 +36,7 @@ tags: [ai, protocol, ospec]
 - Before running Stitch, assume the built-in `stitch` plugin uses the configured provider by default; only treat `.skillrc.plugins.stitch.runner` as authoritative when the project explicitly overrides it
 - If the project uses a custom runner and `token_env` is configured, confirm the matching environment variable is set
 - If the local Stitch bridge, Gemini CLI, Codex CLI, stitch MCP, or auth readiness is unclear, run `ospec plugins doctor stitch <project-path>` first
-- If `plugins doctor stitch` reveals provider, MCP, or auth issues, return to the repo-local Stitch spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, do not invent an alternate `command` / `args` / `env` or stdio-proxy config outside that spec
+- If `plugins doctor stitch` reveals provider, MCP, or auth issues, return to `.ospec/plugins/stitch/docs/` first; do not invent an alternate `command` / `args` / `env` or stdio-proxy config outside the plugin docs
 - If the built-in `codex` provider can complete read-only calls but `create_project`, `generate_screen`, or `edit_screens` stalls locally, first verify the run actually uses `codex exec --dangerously-bypass-approvals-and-sandbox`
 - If the project explicitly overrides `.skillrc.plugins.stitch.runner` and still uses Codex for Stitch writes, the custom runner / wrapper must also pass `--dangerously-bypass-approvals-and-sandbox`
 - If `stitch_design_review` is active and `approval.json.status != approved`, do not treat the change as ready for continued implementation, completion, or archive
@@ -47,12 +47,10 @@ tags: [ai, protocol, ospec]
 
 If the project rules differ from the mother spec, the project-adopted rules take precedence.
 
-## Stitch Provider Baseline
+## Stitch Provider Docs
 
-- If the project contains `docs/stitch-plugin-spec.zh-CN.md`, provider / MCP / auth config must follow that spec first.
-- If the project does not contain that spec and the built-in `gemini` provider is used, the baseline config is `%USERPROFILE%/.gemini/settings.json` with `mcpServers.stitch.httpUrl = "https://stitch.googleapis.com/mcp"` and `headers.X-Goog-Api-Key`.
-- If the project does not contain that spec and the built-in `codex` provider is used, the baseline config is `%USERPROFILE%/.codex/config.toml` with `[mcp_servers.stitch]`, `type = "http"`, `url = "https://stitch.googleapis.com/mcp"`, and `X-Goog-Api-Key` in `headers` or `[mcp_servers.stitch.http_headers]`.
-- The built-in `codex` provider should launch Stitch write operations with `--dangerously-bypass-approvals-and-sandbox`; if a custom runner replaces it, that runner must carry the same write-bypass behavior explicitly.
+- Provider / MCP / auth config must follow the localized Stitch plugin docs under `.ospec/plugins/stitch/docs/`.
+- If those docs are missing, install or enable Stitch first so the plugin can sync its localized docs into the repository before changing config.
 
 ## Stitch Theme Variant Prompt Contract
 

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

@@ -18,7 +18,7 @@ tags: [ai, guide, ospec]
 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` が存在する場合、その設定断片を正とみなす
+7. Stitch / Checkpoint のインストール、provider 切り替え、doctor 修復、MCP 設定、認証設定、またはプラグイン有効化が必要な場合は、先にプロジェクト文書言語に一致するリポジトリ内のローカライズ済みプラグイン仕様を読む。一致する言語ファイルがない場合のみ他言語版へフォールバックする
 
 ## 必須動作
 
@@ -41,7 +41,7 @@ tags: [ai, guide, ospec]
 - 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 の設定形をそのまま使い、回避目的の別設定を即興で作らない
+- Stitch のインストール、provider 切り替え、doctor 修復、MCP 設定、認証設定では、まずプロジェクト文書言語に一致するリポジトリ内のローカライズ済み Stitch 仕様を読む。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` を同期する

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

@@ -15,7 +15,7 @@ tags: [ai, protocol, ospec]
 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` が存在する場合、その設定断片を正とみなす
+8. Stitch / Checkpoint の provider、MCP、認証、インストール、または有効化設定を変更する必要がある場合は、先にプロジェクト文書言語に一致するリポジトリ内のローカライズ済みプラグイン仕様を読む。一致する言語ファイルがない場合のみ他言語版へフォールバックする
 
 ## 必須ルール
 
@@ -36,7 +36,7 @@ tags: [ai, protocol, ospec]
 - 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` がある場合、その仕様外の代替設定を作らない
+- `plugins doctor stitch` が provider、MCP、認証の問題を示した場合は、まずプロジェクト文書言語に一致するリポジトリ内のローカライズ済み Stitch 仕様に戻る。その仕様外の代替設定を作らない
 - 内蔵 `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 可能と扱わない

package/assets/for-ai/zh-CN/ai-guide.md

@@ -18,7 +18,7 @@ tags: [ai, guide, ospec]
 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`，必须以该文档中的配置片段为准
+7. 如果要处理 Stitch / Checkpoint 的安装、provider 切换、doctor 修复、MCP、认证配置或插件启用，先读取与项目文档语言一致的仓库内本地化插件规范；只有该语言文件缺失时，才回退到其他语言版本
 
 ## 必须遵守
 
@@ -39,7 +39,7 @@ tags: [ai, guide, ospec]
 - 如果项目使用自定义 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 配置片段，不得为了让 `doctor` 通过而自行拼接 `command` / `args` / `env` 或 stdio proxy 配置
+- 涉及 Stitch 安装、provider 切换、doctor 修复、MCP 或认证配置时，必须先读取与项目文档语言一致的仓库内本地化 Stitch 规范，直接采用其中的 Gemini / Codex 配置片段，不得为了让 `doctor` 通过而自行拼接 `command` / `args` / `env` 或 stdio proxy 配置
 - 如果内建 `codex` provider 下只读调用正常，但 `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`
@@ -60,7 +60,7 @@ tags: [ai, guide, ospec]
 
 ## Stitch Provider Baseline
 
-- 如果仓库里存在 `docs/stitch-plugin-spec.zh-CN.md`，优先使用文档中的原始配置片段。
+- 如果仓库里存在与项目文档语言一致的本地化 Stitch 规范，优先使用文档中的原始配置片段。
 - 如果仓库里没有这份规范，但需要启用内建 Stitch provider，默认基线如下。
 - `gemini`：修改 `%USERPROFILE%/.gemini/settings.json`，使用 `mcpServers.stitch.httpUrl` 和 `headers.X-Goog-Api-Key`。
 

package/assets/for-ai/zh-CN/execution-protocol.md

@@ -15,7 +15,7 @@ tags: [ai, protocol, ospec]
 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`，必须以该文档中的配置片段为准
+8. 如要处理 Stitch / Checkpoint 的 provider、MCP、认证、安装或启用配置，先读取与项目文档语言一致的仓库内本地化插件规范；只有该语言文件缺失时，才回退到其他语言版本
 
 ## 强制规则
 
@@ -34,7 +34,7 @@ tags: [ai, protocol, ospec]
 - 运行 Stitch 前，优先视为走内建 `stitch` 插件的已配置 provider；只有项目显式覆写 `.skillrc.plugins.stitch.runner` 时才按自定义 runner 处理
 - 如项目使用自定义 runner 且配置了 `token_env`，必须确认对应环境变量已设置
 - 若本地 Stitch bridge、Gemini CLI、Codex CLI、stitch MCP 或认证状态不明确，先执行 `ospec plugins doctor stitch <project-path>`
-- 若 `plugins doctor stitch` 暴露 provider / MCP / auth 问题，先回到仓库内 Stitch 规范修正配置；若存在 `docs/stitch-plugin-spec.zh-CN.md`，不得脱离该文档另造一套 `command` / `args` / `env` 或 stdio proxy 配置
+- 若 `plugins doctor stitch` 暴露 provider / MCP / auth 问题，先回到与项目文档语言一致的仓库内本地化 Stitch 规范修正配置；不得脱离该文档另造一套 `command` / `args` / `env` 或 stdio proxy 配置
 - 如果内建 `codex` provider 下只读调用正常，但 `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`，不得把 change 视为可继续实现、可完成或可归档
@@ -53,7 +53,7 @@ tags: [ai, protocol, ospec]
 
 ## Stitch Provider Baseline
 
-- 如果项目内存在 `docs/stitch-plugin-spec.zh-CN.md`，provider / MCP / auth 配置优先以该文档为准。
+- 如果项目内存在与项目文档语言一致的本地化 Stitch 规范，provider / MCP / auth 配置优先以该文档为准。
 - 如果项目内没有该文档，且走内建 `gemini` provider，默认配置基线是 `%USERPROFILE%/.gemini/settings.json` 中的 `mcpServers.stitch.httpUrl = "https://stitch.googleapis.com/mcp"`，并在 `headers` 中设置 `X-Goog-Api-Key`。
 - 如果项目内没有该文档，且走内建 `codex` provider，默认配置基线是 `%USERPROFILE%/.codex/config.toml` 中的 `[mcp_servers.stitch]`，要求 `type = "http"`、`url = "https://stitch.googleapis.com/mcp"`，并在 `headers` 或 `[mcp_servers.stitch.http_headers]` 中设置 `X-Goog-Api-Key`。
 - 内建 `codex` provider 的 Stitch 写操作默认应带 `--dangerously-bypass-approvals-and-sandbox`；若改用自定义 runner，则该放行参数也必须由自定义 runner 显式承担。

package/assets/global-skills/claude/ospec-change/SKILL.md

@@ -26,7 +26,9 @@ This skill is the single entry for the full change lifecycle inside an initializ
 2. `SKILL.index.json`
 3. `for-ai/ai-guide.md`
 4. `for-ai/execution-protocol.md`
-5. If Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read the repo-local Stitch plugin spec first. When `docs/stitch-plugin-spec.zh-CN.md` exists, treat it as the source of truth for the config shape.
+5. If Stitch or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement is involved, read the localized plugin docs under `.ospec/plugins/<plugin>/docs/` first. Before any install step, check `ospec plugins info <plugin>` or `ospec plugins installed`. If the plugin is already installed globally, reuse it and enable it in the current project instead of reinstalling it.
+6. Treat `ospec update [path]` as project-scoped. It repairs the current project and only upgrades plugins that are enabled in that project.
+7. Do not run `ospec plugins update --all` unless the user explicitly asks to update every installed plugin on the machine.
 6. If the user explicitly asks for queue behavior, inspect `changes/queued/` before creating new queue items.
 7. `changes/active/<change>/proposal.md`
 8. `changes/active/<change>/tasks.md`
@@ -57,10 +59,7 @@ When `.skillrc.plugins.stitch.enabled = true` and `.skillrc.plugins.stitch.capab
 - treat the built-in `stitch` plugin with the configured provider adapter as the default path unless `.skillrc.plugins.stitch.runner` is explicitly overridden
 - if a custom runner is configured and `token_env` is set but missing, stop and request configuration first
 - if runner readiness, provider CLI, stitch MCP, or auth readiness is unclear, use `ospec plugins doctor stitch <project-path>` before `ospec plugins run stitch <change-path>`
-- if Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read the repo-local Stitch plugin spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, use its documented Gemini / Codex config snippets instead of inventing `command` / `args` / `env` or stdio-proxy settings
-- if the repo-local Stitch spec is missing, use these built-in baselines instead of guessing:
-  - `gemini`: `%USERPROFILE%/.gemini/settings.json` -> `mcpServers.stitch.httpUrl = "https://stitch.googleapis.com/mcp"` and `headers.X-Goog-Api-Key`
-  - `codex`: `%USERPROFILE%/.codex/config.toml` -> `[mcp_servers.stitch]`, `type = "http"`, `url = "https://stitch.googleapis.com/mcp"`, and `X-Goog-Api-Key` in `headers` or `[mcp_servers.stitch.http_headers]`
+- if Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read `.ospec/plugins/stitch/docs/` first and follow the plugin's documented config snippets instead of inventing `command` / `args` / `env` or stdio-proxy settings
 - use `ospec plugins approve stitch <change-path>` or `ospec plugins reject stitch <change-path>` to record the review result
 
 ## Required Logic

package/assets/global-skills/codex/ospec-change/SKILL.md

@@ -27,7 +27,9 @@ This skill is the single entry for the full change lifecycle inside an initializ
 2. `SKILL.index.json`
 3. `for-ai/ai-guide.md`
 4. `for-ai/execution-protocol.md`
-5. If Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read the repo-local Stitch plugin spec first. When `docs/stitch-plugin-spec.zh-CN.md` exists, treat it as the source of truth for the config shape.
+5. If Stitch or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement is involved, read the localized plugin docs under `.ospec/plugins/<plugin>/docs/` first. Before any install step, check `ospec plugins info <plugin>` or `ospec plugins installed`. If the plugin is already installed globally, reuse it and enable it in the current project instead of reinstalling it.
+6. Treat `ospec update [path]` as project-scoped. It repairs the current project and only upgrades plugins that are enabled in that project.
+7. Do not run `ospec plugins update --all` unless the user explicitly asks to update every installed plugin on the machine.
 6. If the user explicitly asks for queue behavior, inspect `changes/queued/` before creating new queue items.
 7. `changes/active/<change>/proposal.md`
 8. `changes/active/<change>/tasks.md`
@@ -58,10 +60,7 @@ When `.skillrc.plugins.stitch.enabled = true` and `.skillrc.plugins.stitch.capab
 - treat the built-in `stitch` plugin with the configured provider adapter as the default path unless `.skillrc.plugins.stitch.runner` is explicitly overridden
 - if a custom runner is configured and `token_env` is set but missing, stop and request configuration first
 - if runner readiness, provider CLI, stitch MCP, or auth readiness is unclear, use `ospec plugins doctor stitch <project-path>` before `ospec plugins run stitch <change-path>`
-- if Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read the repo-local Stitch plugin spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, use its documented Gemini / Codex config snippets instead of inventing `command` / `args` / `env` or stdio-proxy settings
-- if the repo-local Stitch spec is missing, use these built-in baselines instead of guessing:
-  - `gemini`: `%USERPROFILE%/.gemini/settings.json` -> `mcpServers.stitch.httpUrl = "https://stitch.googleapis.com/mcp"` and `headers.X-Goog-Api-Key`
-  - `codex`: `%USERPROFILE%/.codex/config.toml` -> `[mcp_servers.stitch]`, `type = "http"`, `url = "https://stitch.googleapis.com/mcp"`, and `X-Goog-Api-Key` in `headers` or `[mcp_servers.stitch.http_headers]`
+- if Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup is involved, read `.ospec/plugins/stitch/docs/` first and follow the plugin's documented config snippets instead of inventing `command` / `args` / `env` or stdio-proxy settings
 - use `ospec plugins approve stitch <change-path>` or `ospec plugins reject stitch <change-path>` to record the review result
 
 ## Required Logic

package/assets/global-skills/codex/ospec-change/agents/openai.yaml

@@ -4,4 +4,4 @@ interface:
 
   short_description: "Create or advance a change"
 
-  default_prompt: "Use $ospec-change to create or advance a OSpec change. Read .skillrc, SKILL.index.json, and the current change files first. Default to one active change and do not enter queue mode unless the user explicitly asks to split work into multiple changes, create a queue, or execute a queue. When queue behavior is explicitly requested, derive an ordered kebab-case list of change names, use ospec queue add to create queued changes, and use ospec run manual-safe only when the user explicitly asks to run the queue. Keep protocol execution inside changes/active/<change> and do not confuse bootstrap with change creation. If Stitch is enabled and stitch_design_review is active, inspect artifacts/stitch/approval.json. For Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup, read the repo-local Stitch plugin spec first and use its documented config snippet instead of inventing a replacement. If that spec is missing, use these built-in baselines: Gemini uses %USERPROFILE%/.gemini/settings.json with mcpServers.stitch.httpUrl and headers.X-Goog-Api-Key; Codex uses %USERPROFILE%/.codex/config.toml with [mcp_servers.stitch], type=\"http\", url=\"https://stitch.googleapis.com/mcp\", and X-Goog-Api-Key in headers or [mcp_servers.stitch.http_headers]. If preview_url or submitted_at is empty, run ospec plugins run stitch <change-path> before asking for review."
+  default_prompt: "Use $ospec-change to create or advance a OSpec change. Read .skillrc, SKILL.index.json, and the current change files first. Default to one active change and do not enter queue mode unless the user explicitly asks to split work into multiple changes, create a queue, or execute a queue. When queue behavior is explicitly requested, derive an ordered kebab-case list of change names, use ospec queue add to create queued changes, and use ospec run manual-safe only when the user explicitly asks to run the queue. Keep protocol execution inside changes/active/<change> and do not confuse bootstrap with change creation. If Stitch is enabled and stitch_design_review is active, inspect artifacts/stitch/approval.json. Before any plugin install step, check `ospec plugins info <plugin>` or `ospec plugins installed`. If the plugin is already installed globally, reuse it and only enable it in the current project. Only run `ospec plugins install <plugin>` when the plugin is not installed yet or the user explicitly asks to reinstall or upgrade it. Treat `ospec update [path]` as project-scoped: it repairs the current project and only upgrades plugins that are enabled in that project. Do not run `ospec plugins update --all` unless the user explicitly asks to update every installed plugin on the machine. If plugin installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement is involved, read `.ospec/plugins/<plugin>/docs/` first; if those docs are missing, install or enable the plugin to sync them before changing config. If preview_url or submitted_at is empty, run ospec plugins run stitch <change-path> before asking for review."

package/assets/global-skills/codex/ospec-change/skill.yaml

@@ -16,4 +16,4 @@ interface:
 
   short_description: "Create or advance a change"
 
-  default_prompt: "Use $ospec-change to create or advance a OSpec change. Read .skillrc, SKILL.index.json, and the current change files first. Default to one active change and do not enter queue mode unless the user explicitly asks to split work into multiple changes, create a queue, or execute a queue. When queue behavior is explicitly requested, derive an ordered kebab-case list of change names, use ospec queue add to create queued changes, and use ospec run manual-safe only when the user explicitly asks to run the queue. Keep protocol execution inside changes/active/<change> and do not confuse bootstrap with change creation. If Stitch is enabled and stitch_design_review is active, inspect artifacts/stitch/approval.json. For Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup, read the repo-local Stitch plugin spec first and use its documented config snippet instead of inventing a replacement. If that spec is missing, use these built-in baselines: Gemini uses %USERPROFILE%/.gemini/settings.json with mcpServers.stitch.httpUrl and headers.X-Goog-Api-Key; Codex uses %USERPROFILE%/.codex/config.toml with [mcp_servers.stitch], type=\"http\", url=\"https://stitch.googleapis.com/mcp\", and X-Goog-Api-Key in headers or [mcp_servers.stitch.http_headers]. Reuse .skillrc.plugins.stitch.project.project_id when it already exists; if it is empty, treat the first successful Stitch run as the canonical project. If preview_url or submitted_at is empty, run ospec plugins run stitch <change-path> before asking for review."
+  default_prompt: "Use $ospec-change to create or advance a OSpec change. Read .skillrc, SKILL.index.json, and the current change files first. Default to one active change and do not enter queue mode unless the user explicitly asks to split work into multiple changes, create a queue, or execute a queue. When queue behavior is explicitly requested, derive an ordered kebab-case list of change names, use ospec queue add to create queued changes, and use ospec run manual-safe only when the user explicitly asks to run the queue. Keep protocol execution inside changes/active/<change> and do not confuse bootstrap with change creation. If Stitch is enabled and stitch_design_review is active, inspect artifacts/stitch/approval.json. Before any plugin install step, check `ospec plugins info <plugin>` or `ospec plugins installed`. If the plugin is already installed globally, reuse it and only enable it in the current project. Only run `ospec plugins install <plugin>` when the plugin is not installed yet or the user explicitly asks to reinstall or upgrade it. Treat `ospec update [path]` as project-scoped: it repairs the current project and only upgrades plugins that are enabled in that project. Do not run `ospec plugins update --all` unless the user explicitly asks to update every installed plugin on the machine. If plugin installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement is involved, read `.ospec/plugins/<plugin>/docs/` first; if those docs are missing, install or enable the plugin to sync them before changing config. Reuse .skillrc.plugins.stitch.project.project_id when it already exists; if it is empty, treat the first successful Stitch run as the canonical project. If preview_url or submitted_at is empty, run ospec plugins run stitch <change-path> before asking for review."

package/assets/plugins/registry.json

@@ -0,0 +1,47 @@
+{
+  "version": 1,
+  "plugins": [
+    {
+      "id": "checkpoint",
+      "packageName": "@clawplays/ospec-plugin-checkpoint",
+      "installRange": ">=1.0.0 <2.0.0",
+      "displayName": "Checkpoint",
+      "official": true,
+      "description": "Runtime review and flow validation for OSpec projects.",
+      "kinds": [
+        "runtime",
+        "skill",
+        "knowledge"
+      ],
+      "docs": {
+        "locales": {
+          "en-US": "plugins/checkpoint/docs/plugin.md",
+          "zh-CN": "plugins/checkpoint/docs/plugin.zh-CN.md",
+          "ja-JP": "plugins/checkpoint/docs/plugin.ja.md",
+          "ar": "plugins/checkpoint/docs/plugin.ar.md"
+        }
+      }
+    },
+    {
+      "id": "stitch",
+      "packageName": "@clawplays/ospec-plugin-stitch",
+      "installRange": ">=1.0.0 <2.0.0",
+      "displayName": "Stitch",
+      "official": true,
+      "description": "Page design review and preview collaboration for OSpec projects.",
+      "kinds": [
+        "runtime",
+        "skill",
+        "knowledge"
+      ],
+      "docs": {
+        "locales": {
+          "en-US": "plugins/stitch/docs/plugin.md",
+          "zh-CN": "plugins/stitch/docs/plugin.zh-CN.md",
+          "ja-JP": "plugins/stitch/docs/plugin.ja.md",
+          "ar": "plugins/stitch/docs/plugin.ar.md"
+        }
+      }
+    }
+  ]
+}

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

@@ -38,3 +38,9 @@ tags: [conventions, workflow, change, ospec]
 - يتم التحكم في تفعيل optional steps عبر `.skillrc.workflow`
 - يجب أن تبقى proposal flags متوافقة مع إعدادات workflow
 - يجب أن تظهر optional steps المفعلة في `tasks.md` و`verification.md`
+
+## Plugin Gates
+
+- يتم التحكم في قدرات الإضافات عبر `.skillrc.plugins`
+- عند التعامل مع تثبيت Stitch أو Checkpoint أو تبديل provider أو إصلاح doctor أو إعداد MCP أو المصادقة أو تفعيل الإضافة، يجب قراءة مواصفة الإضافة المحلية المطابقة للغة الوثائق المعتمدة للمشروع أولاً
+- لا يتم الرجوع إلى ملف مواصفة بلغة أخرى إلا إذا كان الملف المحلي لتلك اللغة غير موجود

package/assets/project-conventions/en-US/workflow-conventions.md

@@ -50,8 +50,7 @@ This document fixes the OSpec execution flow inside the project so requirements
 - `ospec plugins run stitch <change-path>` uses the configured Stitch provider adapter by default; if the project explicitly overrides `.skillrc.plugins.stitch.runner`, use the custom Stitch bridge / wrapper instead
 - For custom runners, use `token_env` when extra tokens are required; for the built-in Gemini adapter, auth is typically configured under `%USERPROFILE%/.gemini/settings.json` in `mcpServers.stitch`
 - Use `ospec plugins doctor stitch <project-path>` to validate the runner, provider CLI, stitch MCP, and auth-hint readiness
-- For Stitch installation, provider switching, doctor remediation, MCP setup, or auth setup, read the repo-local Stitch spec first; when `docs/stitch-plugin-spec.zh-CN.md` exists, use its config snippets instead of inventing an alternate setup just to satisfy the checks
-- If the repo does not contain a Stitch spec, use the built-in baselines instead: `gemini` edits `%USERPROFILE%/.gemini/settings.json` with `mcpServers.stitch.httpUrl` and `headers.X-Goog-Api-Key`; `codex` edits `%USERPROFILE%/.codex/config.toml` with `[mcp_servers.stitch]`, `type = "http"`, `url = "https://stitch.googleapis.com/mcp"`, and `X-Goog-Api-Key`
+- For Stitch or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement, read the localized plugin docs under `.ospec/plugins/<plugin>/docs/` first; if they are missing, install or enable the plugin to sync its docs before changing config
 - If the built-in `codex` provider succeeds on read-only calls but local write operations never reach `mcp_tool_call`, first verify the run actually uses `codex exec --dangerously-bypass-approvals-and-sandbox`
 - If the project overrides a custom Codex runner / wrapper, that custom execution path must also pass `--dangerously-bypass-approvals-and-sandbox`
 - When `approval.json.status` is not `approved`, do not claim the change has passed design review or is ready to archive

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

@@ -38,3 +38,9 @@ tags: [conventions, workflow, change, ospec]
 - optional step の有効化は `.skillrc.workflow` で管理する
 - proposal flags は workflow 設定と整合していなければならない
 - 有効化された optional step は `tasks.md` と `verification.md` に必ず出す
+
+## Plugin Gates
+
+- プラグイン機能は `.skillrc.plugins` で管理する
+- Stitch / Checkpoint のインストール、provider 切り替え、doctor 修復、MCP、認証設定、またはプラグイン有効化に関わる場合は、まずプロジェクト採用文書言語に一致するリポジトリ内のローカライズ済みプラグイン仕様を読む
+- その言語の仕様書が存在しない場合のみ、別言語の仕様書へフォールバックする

package/assets/project-conventions/zh-CN/workflow-conventions.md

@@ -47,7 +47,7 @@ tags: [conventions, workflow, change, ospec]
 - `ospec plugins run stitch <change-path>` 默认走已配置的 Stitch provider 适配器；如果项目显式覆写 `.skillrc.plugins.stitch.runner`，则走自定义 Stitch bridge / wrapper
 - 使用自定义 runner 时，可通过 `token_env` 约束额外 token；使用内建 Gemini 适配器时，通常应在 `%USERPROFILE%/.gemini/settings.json` 的 `mcpServers.stitch` 中配置认证信息
 - 可通过 `ospec plugins doctor stitch <project-path>` 检查 runner、provider CLI、stitch MCP 与认证提示状态
-- 涉及 Stitch 安装、provider 切换、doctor 修复、MCP 或认证配置时，先读取仓库内 Stitch 规范；若存在 `docs/stitch-plugin-spec.zh-CN.md`，必须以该文档中的配置片段为准，不得为通过检查而临时拼出另一套配置
+- 涉及 Stitch / Checkpoint 安装、provider 切换、doctor 修复、MCP、认证配置或插件启用时，先读取与项目文档语言一致的仓库内本地化插件规范；只有该语言文件缺失时，才回退到其他语言版本，不得为通过检查而临时拼出另一套配置
 - 如果仓库里没有 Stitch 规范文档，则使用内建基线：`gemini` 改 `%USERPROFILE%/.gemini/settings.json` 的 `mcpServers.stitch.httpUrl` 与 `headers.X-Goog-Api-Key`；`codex` 改 `%USERPROFILE%/.codex/config.toml` 的 `[mcp_servers.stitch]`，并设置 `type = "http"`、`url = "https://stitch.googleapis.com/mcp"`、`X-Goog-Api-Key`
 - 如果内建 `codex` provider 下只读调用正常，但写操作卡在本地未真正进入 `mcp_tool_call`，优先检查是否真正走了 `codex exec --dangerously-bypass-approvals-and-sandbox`
 - 如果项目覆写了自定义 Codex runner / wrapper，自定义运行链也必须显式带上 `--dangerously-bypass-approvals-and-sandbox`

package/dist/advanced/BatchOperations.d.ts

@@ -32,4 +32,4 @@ export declare class BatchOperations {
     }>;
     private matchesQuery;
 }
-export declare const batchOperations: BatchOperations;
+export declare const batchOperations: BatchOperations;