@clawplays/ospec-cli 0.1.1

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

@@ -0,0 +1,40 @@
+---
+name: project-skill-conventions
+title: SKILL Conventions
+tags: [conventions, skill, ospec]
+---
+
+# SKILL Conventions
+
+## Goal
+
+This file fixes the responsibility boundary of layered `SKILL.md` files so AI consistently locates context through the index and then reads the correct knowledge document.
+
+## Layered Structure
+
+- Root `SKILL.md`: project entry map
+- `docs/SKILL.md`: docs hub
+- `src/SKILL.md`: source map
+- `src/core/SKILL.md`: core platform layer
+- `src/modules/<module>/SKILL.md`: module knowledge unit
+- `tests/SKILL.md`: testing strategy and entry
+
+## Authoring Rules
+
+- `SKILL.md` documents current facts, not future plans
+- Module `SKILL.md` files should cover responsibility, structure, API, dependencies, and test expectations
+- When APIs or boundaries change, update the relevant `SKILL.md`
+- When a new module is created, add its module `SKILL.md`
+
+## Relationship To The Index
+
+- `SKILL.index.json` is for discovery, not for replacing `SKILL.md`
+- Rebuild the index after updating `SKILL.md`
+- AI should read the index first and the target `SKILL.md` second
+
+## Execution Requirement
+
+- Code-only changes without `SKILL.md` updates are not acceptable
+- Do not overload `SKILL.md` with design rationale that belongs in design docs
+- `SKILL.md` explains what exists now, design docs explain why it was designed that way
+

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

@@ -0,0 +1,70 @@
+---
+name: project-workflow-conventions
+title: Workflow Execution Conventions
+tags: [conventions, workflow, change, ospec]
+---
+
+# Workflow Execution Conventions
+
+## Goal
+
+This document fixes the OSpec execution flow inside the project so requirements move through planning, implementation, verification, and archive with consistent gates.
+
+## Standard Order
+
+1. Clarify project context and impact scope
+2. Create or update `proposal.md`
+3. Create or update `tasks.md`
+4. Advance implementation according to `state.json`
+5. Update the relevant `SKILL.md`
+6. Rebuild `SKILL.index.json`
+7. Complete `verification.md`
+8. Archive only after all gates pass
+
+## State Constraints
+
+- Use `state.json` as the execution status source of truth
+- `verification.md` does not replace `state.json`
+- If state files and execution files disagree, fix state first
+
+## Document Language
+
+- Keep `proposal.md`, `tasks.md`, `verification.md`, and `review.md` in the project-adopted document language
+- Product UI language may differ from the OSpec change-document language; do not infer one from the other
+- If a change was created in Chinese, continue updating it in Chinese unless project rules explicitly require a switch to English
+
+## Optional Steps
+
+- Optional-step activation is controlled by `.skillrc.workflow`
+- Proposal flags must remain compatible with the workflow configuration
+- Activated optional steps must appear in `tasks.md` and `verification.md`
+
+## Plugin Gates
+
+- Plugin capabilities are controlled by `.skillrc.plugins`
+- If the current change activates `stitch_design_review`, inspect `artifacts/stitch/approval.json` first
+- If `approval.json.preview_url` or `submitted_at` is empty, run `ospec plugins run stitch <change-path>` first to generate a preview and send the preview URL to the user for review
+- Treat `.skillrc.plugins.stitch.project.project_id` as the canonical Stitch project for the repository; all UI changes should reuse that same Stitch project
+- If the canonical Stitch project is still empty, the first successful `ospec plugins run stitch <change-path>` should save it into `.skillrc.plugins.stitch.project`, and later runs must reuse it
+- If Stitch returns a different project ID from the canonical one, treat that run as invalid instead of accepting the new project automatically
+- `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`
+- 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
+- Prefer `ospec plugins approve stitch <change-path>` or `ospec plugins reject stitch <change-path>` when recording review results
+
+## Archive Gates
+
+- Do not archive when docs are stale
+- Do not archive when the index is stale
+- Do not archive when optional steps have not passed
+- Do not archive when `verification.md` is incomplete
+
+## Execution Requirements
+
+- Any AI or human advancing a change must read `.skillrc`, `SKILL.index.json`, and the current change files first
+- Any completion claim must match the real file state instead of skipping gates through narration

package/assets/project-conventions/zh-CN/development-guide.md

@@ -0,0 +1,32 @@
+---
+name: project-development-guide
+title: 项目开发指南
+tags: [conventions, development, ospec]
+---
+
+# 项目开发指南
+
+## 目标
+
+本文件用于作为项目采用版的总开发指南，衔接项目规划、知识层、执行层和 AI 协作方式。
+
+## 开发基线
+
+- 项目级长期知识放在 `docs/project/`
+- 当前事实放在分层 `SKILL.md`
+- 需求执行放在 `changes/active/<change>/`
+- AI 执行入口放在 `for-ai/`
+
+## 推荐工作方式
+
+1. 先确认项目采用版规范
+2. 再看项目知识层和模块 `SKILL.md`
+3. 再进入当前 change
+4. 实现后同步文档和索引
+
+## 不应做的事
+
+- 不要让 AI 自行发明命名规范
+- 不要绕开 `changes/` 直接长期开发
+- 不要只改代码不改知识层文档
+

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

@@ -0,0 +1,51 @@
+---
+name: project-naming-conventions
+title: 项目命名规范
+tags: [conventions, naming, ospec]
+---
+
+# 项目命名规范
+
+## 目标
+
+本文件是从 OSpec 母版复制到项目中的采用版规范，用于固定项目内的命名方式，避免 AI 或人工在开发过程中临时发明命名风格。
+
+## 基本规则
+
+- 目录、模块、change 名称统一使用小写短横线
+- flags、optional steps 统一使用小写下划线
+- Markdown 协议文件名使用固定名称，不得自定义变体
+- API 文档文件名优先使用语义化短横线
+
+## change 命名
+
+- 使用 `changes/active/<change-name>/`
+- 示例：`add-token-refresh`
+- 避免使用日期、中文、空格、大写字母
+
+## 模块命名
+
+- 模块目录使用语义化英文短横线或单词
+- 示例：`src/modules/auth`、`src/modules/content`
+- 模块 `SKILL.md` 必须放在模块根目录
+
+## 文档命名
+
+- 项目级文档放在 `docs/project/`
+- 设计文档放在 `docs/design/`
+- 计划文档放在 `docs/planning/`
+- API 文档放在 `docs/api/`
+
+## 固定协议文件
+
+- `proposal.md`
+- `tasks.md`
+- `state.json`
+- `verification.md`
+- `review.md`
+
+## 执行要求
+
+- 新增目录、模块、change、flags 时，必须先检查本规范
+- 与本规范冲突时，应优先修正文档和实现，而不是继续扩散不一致命名
+

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

@@ -0,0 +1,40 @@
+---
+name: project-skill-conventions
+title: SKILL 编写规范
+tags: [conventions, skill, ospec]
+---
+
+# SKILL 编写规范
+
+## 目标
+
+本文件用于固定项目中分层 `SKILL.md` 的职责边界，确保 AI 始终先通过索引定位，再读取正确层级的知识文档。
+
+## 分层结构
+
+- 根 `SKILL.md`：项目总导航
+- `docs/SKILL.md`：文档中心导航
+- `src/SKILL.md`：源码结构地图
+- `src/core/SKILL.md`：核心基础层说明
+- `src/modules/<module>/SKILL.md`：模块知识单元
+- `tests/SKILL.md`：测试策略和入口
+
+## 编写要求
+
+- `SKILL.md` 必须描述当前事实，不写未来计划
+- 模块级 `SKILL.md` 应覆盖职责、结构、API、依赖、测试要求
+- 发生 API 或边界变化时，必须同步更新相关 `SKILL.md`
+- 新增模块时，必须补对应的模块 `SKILL.md`
+
+## 与索引的关系
+
+- `SKILL.index.json` 只负责定位，不替代 `SKILL.md`
+- 修改 `SKILL.md` 后，必须重建索引
+- AI 在改代码前应先读索引，再读目标 `SKILL.md`
+
+## 执行要求
+
+- 不允许只改代码不改 `SKILL.md`
+- 不允许把设计文档内容全部塞进 `SKILL.md`
+- `SKILL.md` 描述“现在是什么”，设计文档解释“为什么这样设计”
+

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

@@ -0,0 +1,74 @@
+---
+name: project-workflow-conventions
+title: 工作流执行规范
+tags: [conventions, workflow, change, ospec]
+---
+
+# 工作流执行规范
+
+## 目标
+
+本文档用于固定项目中的 OSpec 执行流程，确保需求从规划到实现、验证、归档都有统一步骤。
+
+## 标准顺序
+
+1. 明确项目上下文和影响范围
+2. 创建或更新 `proposal.md`
+3. 创建或更新 `tasks.md`
+4. 根据 `state.json` 推进实现
+5. 更新相关 `SKILL.md`
+6. 重建 `SKILL.index.json`
+7. 完成 `verification.md`
+8. 满足门禁后再归档
+
+## 状态约束
+
+- 以 `state.json` 为当前执行状态依据
+- `verification.md` 不能替代 `state.json`
+- 若状态文件与执行文件冲突，先修正状态再继续
+
+## 文档语言
+
+- 项目采用中文 protocol 时，`proposal.md`、`tasks.md`、`verification.md`、`review.md` 必须保持中文
+- 产品界面语言可以按业务使用英文，但不得把产品语言自动映射为 OSpec change 文档语言
+- 若当前 change 文档已用中文创建，后续更新必须延续中文，除非项目规则显式要求切换为英文
+
+## 可选步骤
+
+- 是否启用可选步骤，以 `.skillrc.workflow` 为准
+- proposal 中的 flags 必须与 workflow 配置兼容
+- 被激活的可选步骤必须进入 `tasks.md` 和 `verification.md`
+
+## 插件阻断
+
+- 是否启用插件能力，以 `.skillrc.plugins` 为准
+- 如果当前 change 激活了 `stitch_design_review`，必须先检查 `artifacts/stitch/approval.json`
+- 如果 `approval.json.preview_url` 为空或 `submitted_at` 为空，先执行 `ospec plugins run stitch <change-path>` 生成预览，再把预览地址发给用户验收
+- `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 规范文档，则使用内建基线：`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`
+- 当 `approval.json.status` 不是 `approved` 时，不得继续声称 change 已通过设计审核或可归档
+- 记录审批结果时，优先使用 `ospec plugins approve stitch <change-path>` 或 `ospec plugins reject stitch <change-path>`
+
+## 归档约束
+
+- 文档未同步时不得归档
+- 索引未重建时不得归档
+- 可选步骤未通过时不得归档
+- `verification.md` 未完成时不得归档
+
+## 执行要求
+
+- 任何 AI 或人工执行 change 时，都必须先读取 `.skillrc`、`SKILL.index.json` 和当前 change 文件
+- 任何 claim 必须以实际文件状态为准，不得凭口头描述跳过门禁
+
+## Stitch Canonical Project
+
+- 同一个仓库默认只维护一个 Stitch project，保存在 `.skillrc.plugins.stitch.project`。
+- 第一次成功执行 `ospec plugins run stitch <change-path>` 时，如果还没有 canonical project，应该把返回的 project ID 自动保存到 `.skillrc`。
+- 后续所有 UI change 都必须复用这个 canonical Stitch project，而不是为每个 change 新建一个新 project。
+- 如果 Stitch 返回了不同的 project ID，应视为异常结果，不能直接接受。