@clawplays/ospec-cli 0.4.0 → 1.0.1

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,70 +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
-- Enabling the built-in Checkpoint runner automatically installs `playwright`, `pixelmatch`, and `pngjs` into the target project
-- If a user asks an AI assistant to enable Checkpoint, that install step must complete before the plugin should be considered successfully enabled
-- Disabling Checkpoint only turns off the plugin configuration; it does not uninstall those project dependencies
+- `@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
 
@@ -300,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.md)
-- [Checkpoint Plugin Spec](docs/checkpoint-plugin-spec.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/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 or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement, read the repo-local localized plugin spec that matches the project document language first; only fall back when that language-specific file is missing
+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 localized Stitch spec first; 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 the repo contains a localized Stitch plugin spec that matches the project document language, 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 or Checkpoint provider, MCP, auth, install, or enable config must be changed, read the repo-local localized plugin spec that matches the project document language first; only fall back to another localized spec when the matching file is missing
+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 localized Stitch spec first; 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 a localized Stitch plugin spec matching the project document language, 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/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 or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement is involved, read the repo-local localized plugin spec that matches the project document language first. Only fall back to another localized spec when the matching file is missing.
+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 localized Stitch plugin spec first; 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 or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement is involved, read the repo-local localized plugin spec that matches the project document language first. Only fall back to another localized spec when the matching file is missing.
+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 localized Stitch plugin spec first; 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

@@ -4,8 +4,6 @@ title: OSpec Change
 
 description: Create or advance an active change inside a OSpec project while respecting workflow files and optional-step activation.
 
-version: 5.1.0
-
 author: OSpec Team
 
 license: MIT
@@ -16,4 +14,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/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 or Checkpoint installation, provider switching, doctor remediation, MCP setup, auth setup, or plugin enablement, read the repo-local plugin spec that matches the project's adopted document language first; only fall back to another localized spec when that language-specific file is missing
-- 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/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;

package/dist/advanced/BatchOperations.js

@@ -155,4 +155,4 @@ class BatchOperations {
     }
 }
 exports.BatchOperations = BatchOperations;
-exports.batchOperations = new BatchOperations();
+exports.batchOperations = new BatchOperations();

package/dist/advanced/CachingLayer.d.ts

@@ -1,6 +1,6 @@
 /**
- * 缓存层系统
- * 优化性能和减少磁盘访问
+ * Caching layer.
+ * Optimizes performance and reduces disk access.
  */
 export interface CacheEntry<T> {
     key: string;
@@ -15,31 +15,31 @@ export declare class CachingLayer<T = any> {
     private cleanupInterval?;
     constructor(maxSize?: number);
     /**
-     * 设置缓存值
+     * Set a cache value.
      */
     set(key: string, value: T, ttl?: number): void;
     /**
-     * 获取缓存值
+     * Get a cache value.
      */
     get(key: string): T | null;
     /**
-     * 检查键是否存在
+     * Check whether a key exists.
      */
     has(key: string): boolean;
     /**
-     * 删除缓存
+     * Delete a cache entry.
      */
     delete(key: string): boolean;
     /**
-     * 清空缓存
+     * Clear the cache.
      */
     clear(): void;
     /**
-     * 获取缓存大小
+     * Get cache size.
      */
     size(): number;
     /**
-     * 获取统计信息
+     * Get cache statistics.
      */
     getStats(): {
         hits: number;
@@ -50,16 +50,16 @@ export declare class CachingLayer<T = any> {
         maxSize: number;
     };
     /**
-     * 启动清理过期条目
+     * Start cleaning expired entries.
      */
     private startCleanup;
     /**
-     * 停止清理
+     * Stop cleanup.
      */
     stopCleanup(): void;
     /**
-     * 销毁缓存
+     * Dispose the cache.
      */
     destroy(): void;
 }
-export declare const cachingLayer: CachingLayer<any>;
+export declare const cachingLayer: CachingLayer<any>;

package/dist/advanced/CachingLayer.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
- * 缓存层系统
- * 优化性能和减少磁盘访问
+ * Caching layer.
+ * Optimizes performance and reduces disk access.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cachingLayer = exports.CachingLayer = void 0;
@@ -18,10 +18,10 @@ class CachingLayer {
         this.startCleanup();
     }
     /**
-     * 设置缓存值
+     * Set a cache value.
      */
     set(key, value, ttl) {
-        // 如果超过最大大小，移除最旧的条目
+        // Remove the oldest entry when the cache exceeds the maximum size.
         if (this.cache.size >= this.maxSize) {
             const oldestKey = Array.from(this.cache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp)[0]?.[0];
             if (oldestKey) {
@@ -38,7 +38,7 @@ class CachingLayer {
         this.cache.set(key, entry);
     }
     /**
-     * 获取缓存值
+     * Get a cache value.
      */
     get(key) {
         const entry = this.cache.get(key);
@@ -46,7 +46,7 @@ class CachingLayer {
             this.stats.misses++;
             return null;
         }
-        // 检查是否过期
+        // Check whether the entry has expired.
         if (entry.ttl && Date.now() - entry.timestamp > entry.ttl) {
             this.cache.delete(key);
             this.stats.misses++;
@@ -56,31 +56,31 @@ class CachingLayer {
         return entry.value;
     }
     /**
-     * 检查键是否存在
+     * Check whether a key exists.
      */
     has(key) {
         return this.get(key) !== null;
     }
     /**
-     * 删除缓存
+     * Delete a cache entry.
      */
     delete(key) {
         return this.cache.delete(key);
     }
     /**
-     * 清空缓存
+     * Clear the cache.
      */
     clear() {
         this.cache.clear();
     }
     /**
-     * 获取缓存大小
+     * Get cache size.
      */
     size() {
         return this.cache.size;
     }
     /**
-     * 获取统计信息
+     * Get cache statistics.
      */
     getStats() {
         const total = this.stats.hits + this.stats.misses;
@@ -95,7 +95,7 @@ class CachingLayer {
         };
     }
     /**
-     * 启动清理过期条目
+     * Start cleaning expired entries.
      */
     startCleanup() {
         this.cleanupInterval = setInterval(() => {
@@ -110,12 +110,12 @@ class CachingLayer {
             if (removed > 0) {
                 this.stats.evictions += removed;
             }
-        }, 60000); // 每分钟检查一次
+        }, 60000); // Check once per minute.
         // Do not keep unrelated CLI commands alive just because the cache module was imported.
         this.cleanupInterval.unref?.();
     }
     /**
-     * 停止清理
+     * Stop cleanup.
      */
     stopCleanup() {
         if (this.cleanupInterval) {
@@ -124,7 +124,7 @@ class CachingLayer {
         }
     }
     /**
-     * 销毁缓存
+     * Dispose the cache.
      */
     destroy() {
         this.stopCleanup();
@@ -132,4 +132,4 @@ class CachingLayer {
     }
 }
 exports.CachingLayer = CachingLayer;
-exports.cachingLayer = new CachingLayer();
+exports.cachingLayer = new CachingLayer();