@clawplays/ospec-cli 0.1.1

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

@@ -0,0 +1,64 @@
+---
+name: project-execution-protocol
+title: Execution Protocol
+tags: [ai, protocol, ospec]
+---
+
+# AI Execution Protocol
+
+## Read First Every Time You Enter A Project
+
+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. 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
+
+## Mandatory Rules
+
+- Keep `proposal.md`, `tasks.md`, `verification.md`, and `review.md` in the project-adopted document language
+- Do not rewrite change docs into English just because the product UI, site locale, or requirement text is English-first
+- If the current change docs are already Chinese, continue in Chinese unless the project rules explicitly require an English switch
+- Do not skip proposal/tasks and jump straight into implementation
+- Use `state.json` as the execution status source of truth
+- Activated optional steps must appear in `tasks.md` and `verification.md`
+- If `stitch_design_review` is active and `approval.json.preview_url` or `submitted_at` is empty, run `ospec plugins run stitch <change-path>` first to submit a design preview
+- Stitch design review must enforce one canonical layout per route; non-canonical screens under the same route must be explicitly marked as `archive / old / exploration`
+- For `light/dark` theme variants, keep the same canonical layout and only transform the visual theme; do not reorder modules, regroup sections, move CTAs, or alter navigation structure
+- If the matching page already exists, prefer `edit existing screen` or `duplicate existing canonical screen and derive a theme variant`
+- Every Stitch delivery must output `screen mapping` with at least the route, canonical dark/light screen ids, derived relationship, and archived screen ids
+- Old, exploratory, and replaced screens must not remain beside canonical screens as peer main pages
+- If `.skillrc.plugins.stitch.project.project_id` exists, reuse that exact Stitch project ID and do not create a separate Stitch project for this change
+- If the canonical Stitch project is still empty, the first successful Stitch submission becomes the canonical project for the repository
+- 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 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
+- If canonical selection, theme pairing, screen mapping, or duplicate cleanup is missing, do not treat the design review as passed
+- Do not treat the work as complete when `SKILL.md` and the index are out of sync
+
+## Project-Adopted Rules First
+
+If the project rules differ from the mother spec, the project-adopted rules take precedence.
+
+## Stitch Provider Baseline
+
+- 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.
+
+## Stitch Theme Variant Prompt Contract
+
+- For `light/dark` theme variants, prompts must explicitly include:
+  - `Use the existing canonical screen as the base`
+  - `Keep the same layout structure`
+  - `Do not reorder modules`
+  - `Do not create a different composition`
+  - `Only transform the visual theme`

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

@@ -0,0 +1,102 @@
+---
+name: project-ai-guide
+title: AI Guide
+tags: [ai, guide, ospec]
+---
+
+# AI 开发指南
+
+## 目标
+
+本文档是从 OSpec 母版复制到项目中的采用版 AI 指南。AI 必须优先遵循项目内采用版规则，而不是回到母版仓库重新自由发挥。
+
+## Working Order
+
+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`，必须以该文档中的配置片段为准
+
+## 必须遵守
+
+- 文档语言按项目 adopted protocol 执行；如果项目采用中文协议，则 `proposal.md`、`tasks.md`、`verification.md`、`review.md` 必须保持中文
+- 产品界面文案、站点默认语言或 “English-first” 业务策略，不得自动推导为 change 文档应改成英文
+- 若当前 change 已存在中文内容，后续更新必须延续中文，除非项目规则显式声明文档语言切换为英文
+- 先按索引定位，再读目标知识文件
+- 先看项目采用版规范，再进入实现
+- 如果 `stitch_design_review` 已激活且 `approval.json.preview_url` 为空或 `submitted_at` 为空，先执行 `ospec plugins run stitch <change-path>` 生成预览，再把预览地址发给用户验收
+- 如果 `stitch_design_review` 已激活且 `approval.json.status != approved`，先停在设计审核门禁
+- Stitch 页面评审必须遵守“一 route 一套 canonical layout”；不得让同一路由同时存在多个未标记用途的主 layout
+- 如需补齐 `light/dark`，必须基于同一 canonical screen 做主题变体；不得重排模块、改信息架构、改 CTA 位置或生成新的不同构图
+- 项目中已存在对应页面时，优先 `edit existing screen` 或 `duplicate existing canonical screen and derive a theme variant`
+- 每次 Stitch 交付都必须给出 `screen mapping`，至少包含 route、canonical dark/light screen id、是否由另一主题派生、归档 screen ids
+- 旧稿、探索稿、被替换 screen 必须归档或重命名，不能继续与 canonical screen 并列为主页面
+- 如果缺失 canonical 说明、theme pairing、screen mapping，或仍存在未归档重复 screen，不得把该 review 视为完成
+- `ospec plugins run stitch <change-path>` 默认会走已配置的 Stitch provider 适配器；只有在项目显式覆写 `.skillrc.plugins.stitch.runner` 时才走自定义 runner
+- 如果项目使用自定义 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 配置
+- 如果内建 `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`
+- 必要时重建 `SKILL.index.json`
+
+## 项目采用版优先
+
+- 命名规范：`docs/project/naming-conventions.md`
+- SKILL 规范：`docs/project/skill-conventions.md`
+- 工作流规范：`docs/project/workflow-conventions.md`
+- 项目开发指南：`docs/project/development-guide.md`
+
+## Stitch Canonical Project
+
+- 如 `.skillrc.plugins.stitch.project.project_id` 已存在，必须复用该 Stitch project。
+- 如该字段为空，把第一次成功的 Stitch 运行结果视为仓库 canonical project，并在后续 change 中持续复用。
+- 不要为单个 change 新建新的 Stitch project，除非用户明确要求。
+
+## Stitch Provider Baseline
+
+- 如果仓库里存在 `docs/stitch-plugin-spec.zh-CN.md`，优先使用文档中的原始配置片段。
+- 如果仓库里没有这份规范，但需要启用内建 Stitch provider，默认基线如下。
+- `gemini`：修改 `%USERPROFILE%/.gemini/settings.json`，使用 `mcpServers.stitch.httpUrl` 和 `headers.X-Goog-Api-Key`。
+
+```json
+{
+  "mcpServers": {
+    "stitch": {
+      "httpUrl": "https://stitch.googleapis.com/mcp",
+      "headers": {
+        "X-Goog-Api-Key": "your-stitch-api-key"
+      }
+    }
+  }
+}
+```
+
+- `codex`：修改 `%USERPROFILE%/.codex/config.toml`，使用 HTTP transport、固定 Stitch MCP URL，以及 `X-Goog-Api-Key` header。
+- `codex` 内建适配器默认应通过 `codex exec --dangerously-bypass-approvals-and-sandbox` 发起 Stitch 写操作；如果项目改用自定义 runner，该放行参数也必须由自定义 runner 承担。
+
+```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"
+```
+
+## Stitch Canonical Layout
+
+- 每个业务 route 只能有一个 canonical layout。
+- `Light` 和 `Dark` 必须是一对 theme variants，而不是两个不同 layout。
+- 涉及 theme variant 的 prompt 必须明确包含：
+  - `Use the existing canonical screen as the base`
+  - `Keep the same layout structure`
+  - `Do not reorder modules`
+  - `Do not create a different composition`
+  - `Only transform the visual theme`

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

@@ -0,0 +1,68 @@
+---
+name: project-execution-protocol
+title: Execution Protocol
+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`，必须以该文档中的配置片段为准
+
+## 强制规则
+
+- 项目 adopted protocol 为中文时，`proposal.md`、`tasks.md`、`verification.md`、`review.md` 必须保持中文
+- 不得因为页面文案是英文、产品默认语言是英文或需求写有 “English-first” 就把 change 文档改写成英文
+- 若当前 change 文档已经是中文，后续续写、修订和补充必须继续使用中文，除非项目规则显式要求切换
+- 不得跳过 proposal/tasks 直接进入实现
+- 必须以 `state.json` 作为执行状态依据
+- 被激活的可选步骤必须进入 `tasks.md` 和 `verification.md`
+- 如果 `stitch_design_review` 已激活且 `approval.json.preview_url` 为空或 `submitted_at` 为空，先运行 `ospec plugins run stitch <change-path>` 提交设计预览
+- Stitch 设计评审必须遵守“一 route 一套 canonical layout”；同一路由下的非 canonical screen 必须明确标记为 `archive / old / exploration`
+- 如需 `light/dark` 主题变体，必须基于同一 canonical layout 做视觉主题转换；不得重排模块、改 section grouping、改 CTA placement、改 navigation structure
+- 如果项目中已经存在对应页面，必须优先 `edit existing screen` 或 `duplicate existing canonical screen and derive a theme variant`
+- 每次 Stitch 交付必须输出 `screen mapping`，至少包含 route、canonical dark/light screen id、derived 关系、archived screen ids
+- 旧稿、探索稿、被替换 screen 不得与 canonical screen 混放为同级主页面
+- 运行 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 配置
+- 如果内建 `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 视为可继续实现、可完成或可归档
+- 如果缺失 canonical 说明、theme pairing 说明、screen mapping，或仍存在未归档重复 screen，不得把 change 视为已通过设计审核
+- `SKILL.md` 与索引未同步时不得视为完成
+
+## 项目采用版优先
+
+如果项目内规范与母版规范存在差异，应以项目内采用版为准。
+
+## Stitch Canonical Project
+
+- 读取 `.skillrc.plugins.stitch.project.project_id` 作为仓库级固定 Stitch project ID。
+- 如果该字段为空，第一次成功的 Stitch 提交会成为 canonical project。
+- 如果后续运行返回了不同的 project ID，必须停止并提示异常，不能直接写入审批结果。
+
+## Stitch Provider Baseline
+
+- 如果项目内存在 `docs/stitch-plugin-spec.zh-CN.md`，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 显式承担。
+
+## Stitch Theme Variant Prompt Contract
+
+- 涉及 `light/dark` 主题变体时，prompt 必须明确包含：
+  - `Use the existing canonical screen as the base`
+  - `Keep the same layout structure`
+  - `Do not reorder modules`
+  - `Do not create a different composition`
+  - `Only transform the visual theme`

package/assets/git-hooks/post-merge

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+if [ -f "build-index-auto.cjs" ]; then
+  OSPEC_BUILD_INDEX_SCRIPT="build-index-auto.cjs"
+elif [ -f "build-index-auto.js" ]; then
+  OSPEC_BUILD_INDEX_SCRIPT="build-index-auto.js"
+else
+  echo "[ospec] build-index-auto.cjs not found, skip hook check"
+  exit 0
+fi
+
+node "$OSPEC_BUILD_INDEX_SCRIPT" hook-check post-merge

package/assets/git-hooks/pre-commit

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+if [ -f "build-index-auto.cjs" ]; then
+  OSPEC_BUILD_INDEX_SCRIPT="build-index-auto.cjs"
+elif [ -f "build-index-auto.js" ]; then
+  OSPEC_BUILD_INDEX_SCRIPT="build-index-auto.js"
+else
+  echo "[ospec] build-index-auto.cjs not found, skip hook check"
+  exit 0
+fi
+
+node "$OSPEC_BUILD_INDEX_SCRIPT" hook-check pre-commit

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

@@ -0,0 +1,116 @@
+---
+name: ospec-change
+description: Create or advance an active change inside an OSpec project, from requirement intake through verification and finalize.
+---
+
+# OSpec Change
+
+Use this skill when the user says things like "use ospec change to do a requirement".
+
+## Scope
+
+This skill is the single entry for the full change lifecycle inside an initialized OSpec project:
+- requirement intake
+- change naming or matching
+- explicit queue planning when the user asks for queue behavior
+- proposal and task refinement
+- implementation guidance
+- progress tracking
+- verification
+- archive readiness check
+- finalize closeout
+
+## Read Order
+
+1. `.skillrc`
+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.
+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`
+9. `changes/active/<change>/state.json`
+10. `changes/active/<change>/verification.md`
+11. `changes/active/<change>/review.md`
+
+## Language
+
+- Follow the project-adopted document language from `for-ai/` and existing change docs.
+- Keep Chinese projects in Chinese unless the repo explicitly adopts English.
+
+## Plugin Gates
+
+After reading `.skillrc`, inspect enabled plugins before advancing the change.
+
+### Stitch
+
+When `.skillrc.plugins.stitch.enabled = true` and `.skillrc.plugins.stitch.capabilities.page_design_review.enabled = true`:
+
+- determine whether the current change activates `stitch_design_review` from proposal `flags` and `tasks.md` / `verification.md` `optional_steps`
+- if activated, read `changes/active/<change>/artifacts/stitch/approval.json`
+- if `approval.json.preview_url` or `submitted_at` is empty, run `ospec plugins run stitch <change-path>` before asking the user to review the design
+- if `.skillrc.plugins.stitch.project.project_id` is already configured, reuse that exact Stitch project instead of creating a new project
+- if `.skillrc.plugins.stitch.project.project_id` is empty, treat the first successful Stitch run as the canonical project and keep using it for later changes
+- treat missing approval or `status != approved` as a blocking gate
+- do not claim the change can continue implementation closeout or archive readiness until Stitch approval is complete
+- 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]`
+- use `ospec plugins approve stitch <change-path>` or `ospec plugins reject stitch <change-path>` to record the review result
+
+## Required Logic
+
+1. Inspect repository state first when posture is unclear.
+2. If the repo is not initialized, stop at initialization guidance instead of forcing a change.
+3. If the request is a new requirement, derive a concise kebab-case change name and create it.
+4. If the matching active change already exists, continue it instead of duplicating it.
+5. Default to one active change unless the user explicitly asks to split work into multiple changes, create a queue, or execute a queue.
+6. When queue behavior is explicitly requested, derive an ordered list of concise kebab-case change names. Each name should represent one execution unit, not a mixed bundle.
+7. For explicit queue planning, present the queue as an ordered list first. Use `ospec queue add ...` to create queued changes and `ospec run ...` only when the user explicitly asks to run the queue.
+8. Treat `changes/active/<change>/` as the execution container.
+9. Keep `proposal.md`, `tasks.md`, `state.json`, `verification.md`, and `review.md` aligned with actual execution and with the project's established document language.
+10. Use OSpec closeout commands instead of inventing a parallel process.
+11. Apply plugin gates from `.skillrc` before advancing a change.
+12. If `stitch_design_review` is activated, inspect the Stitch approval artifact before continuing execution.
+13. If the Stitch preview has not been submitted yet, run `ospec plugins run stitch <change-path>` before asking for design review.
+14. If Stitch approval is missing or not approved, stop at the review gate instead of treating the change as ready.
+
+## Commands
+
+```bash
+ospec status [path]
+ospec new <change-name> [path]
+ospec changes status [path]
+ospec queue status [path]
+ospec queue add <change-name> [path]
+ospec queue activate <change-name> [path]
+ospec queue next [path]
+ospec run start [path] --profile manual-safe
+ospec run step [path]
+ospec run status [path]
+ospec plugins status [path]
+ospec plugins doctor stitch [path]
+ospec plugins run stitch [changes/active/<change>]
+ospec plugins approve stitch [changes/active/<change>]
+ospec plugins reject stitch [changes/active/<change>]
+ospec progress [changes/active/<change>]
+ospec verify [changes/active/<change>]
+ospec archive [changes/active/<change>] --check
+ospec finalize [changes/active/<change>]
+```
+
+## Guardrails
+
+- Do not assume dashboard workflows exist.
+- Do not refer to `basic` or `full` structure levels.
+- Do not confuse repository initialization with change execution.
+- Do not enter queue mode unless the user explicitly asks for queue behavior.
+- Do not turn an ordinary single requirement into multiple queued changes unless the user explicitly asks to split it.
+- Do not continue past an active Stitch review gate when approval is missing or not approved.
+- Do not claim completion until implementation, verification notes, and closeout status are aligned.
+- If real project tests exist, run or recommend them separately from `ospec verify`.

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

@@ -0,0 +1,117 @@
+---
+name: ospec-change
+description: Create or advance an active change inside an OSpec project, from requirement intake through verification and finalize.
+tags: [ospec, cli, workflow]
+---
+
+# OSpec Change
+
+Use this skill when the user says things like "use ospec change to do a requirement".
+
+## Scope
+
+This skill is the single entry for the full change lifecycle inside an initialized OSpec project:
+- requirement intake
+- change naming or matching
+- explicit queue planning when the user asks for queue behavior
+- proposal and task refinement
+- implementation guidance
+- progress tracking
+- verification
+- archive readiness check
+- finalize closeout
+
+## Read Order
+
+1. `.skillrc`
+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.
+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`
+9. `changes/active/<change>/state.json`
+10. `changes/active/<change>/verification.md`
+11. `changes/active/<change>/review.md`
+
+## Language
+
+- Follow the project-adopted document language from `for-ai/` and existing change docs.
+- Keep Chinese projects in Chinese unless the repo explicitly adopts English.
+
+## Plugin Gates
+
+After reading `.skillrc`, inspect enabled plugins before advancing the change.
+
+### Stitch
+
+When `.skillrc.plugins.stitch.enabled = true` and `.skillrc.plugins.stitch.capabilities.page_design_review.enabled = true`:
+
+- determine whether the current change activates `stitch_design_review` from proposal `flags` and `tasks.md` / `verification.md` `optional_steps`
+- if activated, read `changes/active/<change>/artifacts/stitch/approval.json`
+- if `approval.json.preview_url` or `submitted_at` is empty, run `ospec plugins run stitch <change-path>` before asking the user to review the design
+- if `.skillrc.plugins.stitch.project.project_id` is already configured, reuse that exact Stitch project instead of creating a new project
+- if `.skillrc.plugins.stitch.project.project_id` is empty, treat the first successful Stitch run as the canonical project and keep using it for later changes
+- treat missing approval or `status != approved` as a blocking gate
+- do not claim the change can continue implementation closeout or archive readiness until Stitch approval is complete
+- 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]`
+- use `ospec plugins approve stitch <change-path>` or `ospec plugins reject stitch <change-path>` to record the review result
+
+## Required Logic
+
+1. Inspect repository state first when posture is unclear.
+2. If the repo is not initialized, stop at initialization guidance instead of forcing a change.
+3. If the request is a new requirement, derive a concise kebab-case change name and create it.
+4. If the matching active change already exists, continue it instead of duplicating it.
+5. Default to one active change unless the user explicitly asks to split work into multiple changes, create a queue, or execute a queue.
+6. When queue behavior is explicitly requested, derive an ordered list of concise kebab-case change names. Each name should represent one execution unit, not a mixed bundle.
+7. For explicit queue planning, present the queue as an ordered list first. Use `ospec queue add ...` to create queued changes and `ospec run ...` only when the user explicitly asks to run the queue.
+8. Treat `changes/active/<change>/` as the execution container.
+9. Keep `proposal.md`, `tasks.md`, `state.json`, `verification.md`, and `review.md` aligned with actual execution and with the project's established document language.
+10. Use OSpec closeout commands instead of inventing a parallel process.
+11. Apply plugin gates from `.skillrc` before advancing a change.
+12. If `stitch_design_review` is activated, inspect the Stitch approval artifact before continuing execution.
+13. If the Stitch preview has not been submitted yet, run `ospec plugins run stitch <change-path>` before asking for design review.
+14. If Stitch approval is missing or not approved, stop at the review gate instead of treating the change as ready.
+
+## Commands
+
+```bash
+ospec status [path]
+ospec new <change-name> [path]
+ospec changes status [path]
+ospec queue status [path]
+ospec queue add <change-name> [path]
+ospec queue activate <change-name> [path]
+ospec queue next [path]
+ospec run start [path] --profile manual-safe
+ospec run step [path]
+ospec run status [path]
+ospec plugins status [path]
+ospec plugins doctor stitch [path]
+ospec plugins run stitch [changes/active/<change>]
+ospec plugins approve stitch [changes/active/<change>]
+ospec plugins reject stitch [changes/active/<change>]
+ospec progress [changes/active/<change>]
+ospec verify [changes/active/<change>]
+ospec archive [changes/active/<change>] --check
+ospec finalize [changes/active/<change>]
+```
+
+## Guardrails
+
+- Do not assume dashboard workflows exist.
+- Do not refer to `basic` or `full` structure levels.
+- Do not confuse repository initialization with change execution.
+- Do not enter queue mode unless the user explicitly asks for queue behavior.
+- Do not turn an ordinary single requirement into multiple queued changes unless the user explicitly asks to split it.
+- Do not continue past an active Stitch review gate when approval is missing or not approved.
+- Do not claim completion until implementation, verification notes, and closeout status are aligned.
+- If real project tests exist, run or recommend them separately from `ospec verify`.

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

@@ -0,0 +1,7 @@
+interface:
+
+  display_name: "OSpec Change"
+
+  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."

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

@@ -0,0 +1,19 @@
+name: ospec-change
+
+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
+
+interface:
+
+  display_name: "OSpec Change"
+
+  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."

package/assets/project-conventions/en-US/development-guide.md

@@ -0,0 +1,32 @@
+---
+name: project-development-guide
+title: Project Development Guide
+tags: [conventions, development, ospec]
+---
+
+# Project Development Guide
+
+## Goal
+
+This file is the project-adopted development guide that connects project planning, the knowledge layer, the execution layer, and AI collaboration rules.
+
+## Baseline
+
+- Long-lived project knowledge lives in `docs/project/`
+- Current facts live in layered `SKILL.md`
+- Change execution lives in `changes/active/<change>/`
+- AI execution entry points live in `for-ai/`
+
+## Recommended Flow
+
+1. Confirm the project-adopted conventions
+2. Read the project knowledge layer and relevant `SKILL.md`
+3. Enter the active change
+4. Sync docs and the index after implementation
+
+## Avoid
+
+- Do not let AI invent naming conventions on the fly
+- Do not bypass `changes/` for long-running work
+- Do not update code without updating the knowledge layer
+

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

@@ -0,0 +1,51 @@
+---
+name: project-naming-conventions
+title: Project Naming Conventions
+tags: [conventions, naming, ospec]
+---
+
+# Naming Conventions
+
+## Goal
+
+This file is the project-adopted copy of the OSpec mother spec. It fixes naming rules inside the project so AI and humans do not invent naming patterns ad hoc.
+
+## Core Rules
+
+- Directories, modules, and change names use lowercase kebab-case
+- Flags and optional steps use lowercase snake_case
+- Workflow protocol files keep their fixed filenames
+- API docs use semantic kebab-case names
+
+## Change Names
+
+- Use `changes/active/<change-name>/`
+- Example: `add-token-refresh`
+- Avoid dates, spaces, uppercase names, and non-semantic labels
+
+## Module Names
+
+- Module directories use semantic English names
+- Example: `src/modules/auth`, `src/modules/content`
+- Each module keeps its `SKILL.md` at the module root
+
+## Document Names
+
+- Project docs live in `docs/project/`
+- Design docs live in `docs/design/`
+- Planning docs live in `docs/planning/`
+- API docs live in `docs/api/`
+
+## Fixed Protocol Files
+
+- `proposal.md`
+- `tasks.md`
+- `state.json`
+- `verification.md`
+- `review.md`
+
+## Execution Requirement
+
+- Check this file before adding a new directory, module, change, or workflow flag
+- If implementation diverges from this file, bring the code and docs back into alignment first
+