relay-kit 0.3.0 → 0.3.1

package/docs/CLI_SPEC.md

@@ -1,94 +1,164 @@
 # CLI 规格
 
-## 1. MVP 命令
+## 1. 全部命令
 
 ```bash
 relay init
+relay openspec <action>
 relay start
 relay ask
 relay resume
 relay review
 relay doctor
+relay sync
 ```
 
 ## 2. relay init
 
-初始化当前项目。
+初始化当前项目，交互式选择 simple / openspec 模式。
 
 ```bash
 relay init
 relay init --mode simple
 relay init --mode openspec
+relay init --mode openspec --openspec-sync use_relay
 relay init --with-openspec
 relay init --yes
 relay init --force
-relay init --skills claude,codex
-relay init --skills-manager-only
 ```
 
-行为：检测项目、检测 OpenSpec、选择模式、生成配置、创建 handoff 目录、注入 AGENTS.md、导出 Skills。
+行为：
+- 无 `openspec/` 时弹出菜单选择模式
+- OpenSpec 模式自动创建 `openspec/` 目录结构
+- 检测到外部 `openspec` CLI 时提供选项
+- 生成配置、状态、handoff 目录、AGENTS.md 注入、安装 Skills/OpenSpec 文件
 
-## 3. relay start
+## 3. relay openspec（内置 OpenSpec CLI）
 
-开始一个任务，生成 `EXECUTOR_TASK.md`。
+### relay openspec new-change
+
+```bash
+relay openspec new-change <name>
+relay openspec new-change <name> --schema spec-driven
+```
+
+创建 `openspec/changes/<name>/` 目录和 `.openspec.yaml`。
+
+### relay openspec status
+
+```bash
+relay openspec status --change <name>
+relay openspec status --change <name> --json
+```
+
+输出 artifact 完成状态（proposal / specs / design / tasks 各自 done/ready/blocked）。
+
+### relay openspec list
+
+```bash
+relay openspec list
+relay openspec list --json
+```
+
+列出所有活跃 changes（排除 archive/）。
+
+### relay openspec instructions
+
+```bash
+relay openspec instructions <artifactId> --change <name>
+relay openspec instructions <artifactId> --change <name> --json
+```
+
+输出指定 artifact 的创建指引，包含 context、rules、template、instruction、outputPath、dependencies。
+
+### relay openspec apply-instructions
+
+```bash
+relay openspec apply-instructions --change <name>
+relay openspec apply-instructions --change <name> --json
+```
+
+输出 apply 执行上下文：contextFiles 映射、任务进度（total/complete/remaining）、state（ready/blocked/all_done）。
+
+### relay openspec archive
+
+```bash
+relay openspec archive <name>
+```
+
+归档 change 到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。
+
+### relay openspec schemas
+
+```bash
+relay openspec schemas
+```
+
+列出可用 workflow schema 及其 artifact 列表。
+
+## 4. relay start
+
+开始一次 handoff run，生成 `EXECUTOR_TASK.md`。
 
 ```bash
 relay start
-relay start --change add-local-project-storage --tasks "1-2" --copy
-relay start --title "优化人工确认页面 UI" --scope "src/pages/HumanConfirm.tsx,src/components/**" --copy
-relay start --lane ui --tasks "3-4" --copy
+relay start --change add-local-project-storage --title "实现本地存储"
+relay start --title "优化 UI" --scope "src/pages/**" --blocked-scope "不要改 API"
+relay start --copy
 ```
 
-无参数时走交互式选择。
+OpenSpec 模式下自动读取 change 的 proposal/design/tasks 并注入到 handoff 文件。
 
-## 4. relay ask
+## 5. relay ask
 
-卡住时生成 `ASK_ADVISOR.md`。
+Executor 卡住时生成 `ASK_ADVISOR.md`。
 
 ```bash
 relay ask
 relay ask --run build
-relay ask --lane ui --copy
-relay ask --change add-local-project-storage --copy
+relay ask --run test
+relay ask --copy
 ```
 
-收集：git status、git diff、OpenSpec、构建/测试错误、当前 Executor task。
+收集：git status / diff、OpenSpec 上下文、构建/测试错误、当前 task。默认只收集现有上下文，传递 `--run` 才会执行命令。
 
-## 5. relay resume
+## 6. relay resume
 
-顾问回复后生成继续执行提示。
+读取 Advisor 决策并生成 `RESUME_PROMPT.md`。
 
 ```bash
 relay resume
-relay resume --from clipboard
-relay resume --lane ui --copy
+relay resume --from ./ADVISOR_DECISION.md
+relay resume --copy
 ```
 
-读取 `ADVISOR_DECISION.md`，输出 `RESUME_PROMPT.md`。
+## 7. relay review
 
-## 6. relay review
-
-生成 Review 请求。
+生成 `REVIEW_REQUEST.md`。
 
 ```bash
 relay review
-relay review --lane ui --copy
-relay review --run current --copy
+relay review --copy
 ```
 
-输出 `REVIEW_REQUEST.md`。
+收集当前任务、OpenSpec 上下文、受限 git diff。
 
-## 7. relay doctor
+## 8. relay doctor
 
-检查：config、AGENTS.md、skills、handoff 目录、OpenSpec、package scripts、current run/lane、未处理 ASK/DECISION。
+诊断项目接入状态：配置、AGENTS.md 注入块、Skills 目录、handoff 目录、OpenSpec 状态、package scripts、当前 run/lane。
 
+```bash
+relay doctor
+```
 
-## 9. relay sync --skills
+## 9. relay sync
 
-同步 relay Skills。
+同步 relay-kit 管理的资源。
 
 ```bash
-relay sync --skills
+relay sync --skills                    # 同步 relay Skills
+relay sync --openspec                  # 同步 OpenSpec 命令/Skill 文件
+relay sync --all                       # 全量同步
 relay sync --skills --target claude
 relay sync --skills --target codex
 relay sync --skills --target all --scope project
@@ -97,25 +167,10 @@ relay sync --skills --dry-run
 relay sync --skills --force
 ```
 
-默认从：
-
-```text
-.relay/skills/
-```
-
-同步到项目级目标：
-
-```text
-.claude/skills/
-.agents/skills/
-```
-
 规则：
-
-1. 默认只同步当前项目配置启用的项目级目标；
-2. 用户级目录只在显式传入 `--scope user` 时写入；
-3. Codex 目标使用 `.agents/skills` 或 `~/.agents/skills`，不使用 `.codex/skills`；
-4. 默认不覆盖疑似被用户修改过的目标 Skill；
-5. `--force` 允许覆盖冲突文件；
-6. `--dry-run` 只输出同步计划，不写入文件或同步状态；
-7. 命令输出同步报告，包含目标、文件动作和汇总结果。
+1. 默认只同步当前项目配置启用的项目级目标
+2. 用户级目录只在显式传入 `--scope user` 时写入
+3. Codex 目标使用 `.agents/skills`，不使用 `.codex/skills`
+4. 默认不覆盖疑似被用户修改过的目标 Skill
+5. `--force` 允许覆盖冲突文件
+6. `--dry-run` 只输出同步计划，不写入文件

package/docs/FINAL_DESIGN.md

@@ -73,12 +73,14 @@ Relay Review
 CLI 是底层能力，不要求用户记复杂参数。
 
 ```bash
-relay init      # 初始化项目
-relay start     # 开始任务，生成 EXECUTOR_TASK.md
-relay ask       # 卡住时生成 ASK_ADVISOR.md
-relay resume    # 顾问回复后生成继续执行提示
-relay review    # 完成后生成 REVIEW_REQUEST.md
-relay doctor    # 检查接入状态
+relay init          # 初始化项目（交互式选择 simple/openspec 模式）
+relay openspec      # 内置 OpenSpec CLI（new-change / status / list / instructions / archive）
+relay start         # 开始任务，生成 EXECUTOR_TASK.md
+relay ask           # 卡住时生成 ASK_ADVISOR.md
+relay resume        # 顾问回复后生成继续执行提示
+relay review        # 完成后生成 REVIEW_REQUEST.md
+relay doctor        # 检查接入状态
+relay sync          # 同步 Skills 和 OpenSpec 文件
 ```
 
 ### 4.4 Handoff 文件层
@@ -94,12 +96,13 @@ REVIEW_REQUEST.md
 REVIEW_REPORT.md
 ```
 
-### 4.5 OpenSpec 适配层
+### 4.5 OpenSpec 层（v0.3.0 起内置）
 
-- 没有 OpenSpec：simple 模式；
-- 检测到 OpenSpec：启用 openspec 模式；
-- 用户选择“引导初始化”：只提示和确认，不静默安装；
-- 不替代 `/opsx:apply`，只负责任务交接与求助。
+- relay-kit v0.3.0 起**内置 OpenSpec 实现**，零外部依赖；
+- `relay openspec` 子命令组提供完整 CLI：new-change / status / list / instructions / apply-instructions / archive / schemas；
+- `relay init --mode openspec` 自动创建 `openspec/` 目录结构；
+- 检测到外部 `openspec` CLI 时提供共存选项；
+- relay-kit 作为独立分叉维护，可按需合并上游优化或自主微调。
 
 ## 5. 最重要的边界
 
@@ -109,12 +112,11 @@ REVIEW_REPORT.md
 2. 不自动写业务代码；
 3. 不自动提交 git；
 4. 不替代 OpenCode / Claude Code；
-5. 不强制安装 OpenSpec；
-6. 不静默初始化 OpenSpec；
-7. MVP 不做 GUI；
-8. MVP 不做真正自动多 Agent 调度。
+5. 不强制安装外部 OpenSpec（已内置）；
+6. MVP 不做 GUI；
+7. MVP 不做真正自动多 Agent 调度。
 
-它做的是：初始化规则、生成任务交接材料、收集求助上下文、规范 Relay 输出、生成 Review 请求、让流程跨项目复用。
+它做的是：初始化规则、管理 OpenSpec change 生命周期、生成任务交接材料、收集求助上下文、规范 Relay 输出、生成 Review 请求、让流程跨项目复用。
 
 ## 6. Skills 安装策略
 

package/docs/OPENSPEC_INTEGRATION.md

@@ -1,52 +1,82 @@
-# OpenSpec 集成策略
+# OpenSpec 集成架构
 
-## 1. 基本原则
+## 1. v0.3.0 起：内置实现
 
-`relay-kit` 不替代 OpenSpec。
+relay-kit v0.3.0 起**不再依赖外部 `openspec` CLI**。所有 OpenSpec 功能由 relay-kit 内置实现：
 
 ```text
-OpenSpec 管任务定义
-relay-kit 管任务交接、求助、Review
+relay-kit CLI
+├── relay init              → 一键创建 openspec/ + .relay/
+├── relay openspec *        → 内置 OpenSpec CLI（零外部依赖）
+├── relay start --change    → 读取 OpenSpec change 生成 EXECUTOR_TASK
+├── relay sync --openspec   → 同步 OpenSpec 命令/Skill 文件
+└── relay sync --all        → 全量同步（Skills + OpenSpec）
 ```
 
-## 2. 没有 OpenSpec 时
+## 2. 架构角色
 
-`relay init` 提供选择：Simple 模式、OpenSpec 模式、引导初始化 OpenSpec。
+```text
+OpenSpec 的工作由 relay-kit 接管：
+  - 定义「做什么」→ schema + artifacts（proposal / specs / design / tasks）
+  - 跟踪「做了多少」→ status / task progress
+  - 归档「做完了」→ archive + spec merge
+
+relay-kit 的工作流层：
+  - 规划 → /relay:plan → 输出 PLAN_REPORT
+  - 交付 → relay start → EXECUTOR_TASK.md
+  - 执行 → /relay:run → 小步实现，卡住升级
+  - 求助 → relay ask → ASK_ADVISOR.md
+  - 审查 → relay review → REVIEW_REQUEST.md
+```
 
-默认不安装、不初始化。
+## 3. 内置 Schema
 
-## 3. 有 OpenSpec 时
+relay-kit 内置 `spec-driven` schema（唯一实际使用的 schema），artifact 流：
 
-检测到：
+```
+proposal ──→ specs ──→ tasks
+    │                      ↑
+    └──────→ design ───────┘
 
-```text
-openspec/
-  project.md
-  changes/
+apply.requires: [tasks]
+apply.tracks: tasks.md
 ```
 
-启用：
+Schema 定义在 `src/core/schema.ts`，支持轻量扩展框架。
 
-```json
-{
-  "mode": "openspec",
-  "includeOpenSpec": true
-}
-```
+## 4. 与外部 openspec CLI 共存
+
+如果系统已有外部 `openspec` CLI（如 `@fission-ai/openspec`）：
 
-`relay start` 会读取 proposal/design/tasks。
+- `relay init` 检测到后提供选项：使用内置 / 使用外部 / 跳过
+- `--openspec-sync use_relay` 强制使用内置
+- 内置实现完全兼容 OpenSpec 文件格式（proposal.md / design.md / tasks.md / delta spec）
 
-## 4. 和 /opsx:apply 的关系
+## 5. 用户项目中的文件
 
-不冲突。
+relay-kit 分发的 OpenSpec 文件（`relay sync --openspec` 安装）：
 
 ```text
-/opsx:apply = OpenSpec 原生执行
-relay start = 生成给 Executor 的任务交接说明，不执行代码
-relay ask = 卡住时整理求助包
-relay review = 完成后整理 Review 请求
+.opencode/commands/opsx-*.md        # OpenCode 命令
+.opencode/skills/openspec-*/        # OpenCode Skills
+.claude/commands/opsx/*.md          # Claude Code 命令
+.claude/skills/openspec-*/          # Claude Code Skills
+.codex/skills/openspec-*/           # Codex Skills
 ```
 
-## 5. Change 策略
+这些文件内部调用 `relay openspec` 而非外部 `openspec` CLI。
+
+## 6. 更新机制
+
+用户更新 relay-kit 后：
+
+```bash
+npm update -g relay-kit
+relay sync --all     # 全量更新 Skills + OpenSpec 文件
+```
+
+relay-kit 作为 OpenSpec 实现的**独立分叉**维护，可按需从上游合并指令优化，也可自主微调。
+
+## 7. 与 /opsx:* 命令的关系
 
-可以先规划多个 change，但一次只激活和执行一个 change。追求效率时，在一个 change 内拆 lane。
+`/opsx:propose`、`/opsx:apply`、`/opsx:archive`、`/opsx:explore` 命令由 relay-kit 分发，内部调用 `relay openspec` 子命令，完全自包含。

package/docs/SKILLS_INSTALLATION.md

@@ -10,7 +10,9 @@
 2. 不污染用户所有项目；
 3. 不同项目可以有不同的 relay 工作流；
 4. 适合团队协作和作品集展示；
-5. 后续可通过 `relay sync --skills` 更新。
+5. 后续可通过 `relay sync` 更新。
+
+`relay init` 在 OpenSpec 模式下还会额外安装 **OpenSpec 命令/Skill 文件**（`.opencode/`、`.claude/commands/opsx/`、`.codex/skills/openspec-*/`），与 relay Skills 一起管理。
 
 ## 2. 不同工具的 Skills 目录
 
@@ -18,12 +20,21 @@
 
 ### Claude Code
 
-项目级：
+项目级 Skills：
 
 ```text
 .claude/skills/<skill-name>/SKILL.md
 ```
 
+OpenSpec 命令：
+
+```text
+.claude/commands/opsx/propose.md
+.claude/commands/opsx/apply.md
+.claude/commands/opsx/archive.md
+.claude/commands/opsx/explore.md
+```
+
 用户级：
 
 ```text
@@ -32,18 +43,33 @@
 
 ### Codex
 
-项目级：
+项目级 Skills：
 
 ```text
 .agents/skills/<skill-name>/SKILL.md
 ```
 
+OpenSpec Skills：
+
+```text
+.codex/skills/openspec-*/SKILL.md
+```
+
 用户级：
 
 ```text
 ~/.agents/skills/<skill-name>/SKILL.md
 ```
 
+### OpenCode
+
+项目级：
+
+```text
+.opencode/commands/opsx-*.md
+.opencode/skills/openspec-*/SKILL.md
+```
+
 ## 3. relay-kit 管理副本
 
 无论用户选择哪些工具，`relay init` 都应该生成 relay-kit 自己的管理副本：
@@ -150,6 +176,22 @@ your-project/
 relay sync --skills
 ```
 
+### 同步 OpenSpec 文件
+
+```bash
+relay sync --openspec
+```
+
+同步 `.opencode/`、`.claude/commands/opsx/`、`.codex/skills/openspec-*/` 到项目。
+
+### 全量同步
+
+```bash
+relay sync --all
+```
+
+等于 `--skills` + `--openspec`。
+
 默认从：
 
 ```text
@@ -227,7 +269,7 @@ relay sync --skills --target all --scope user
 然后让每个成员本地运行：
 
 ```bash
-relay sync --skills
+relay sync --all
 ```
 
 ## 11. 最终规则

package/docs/USAGE_FLOW.md

@@ -6,82 +6,63 @@
 relay init
 ```
 
-如果没有 OpenSpec，会让用户选择：
-
-```text
-1. Simple 模式：不使用 OpenSpec
-2. OpenSpec 模式：已有 OpenSpec，接入即可
-3. 引导初始化 OpenSpec：只提示/确认，不静默安装
-```
+无 `openspec/` 时弹出交互菜单选择模式。选择 OpenSpec 后自动创建目录结构并安装全套文件。
 
 初始化后生成：
 
-```text
-.relay/
-  config.json
-  state.json
-  skills/
-
-docs/
-  agent-handoffs/
-    runs/
-
-AGENTS.md
+```
+.relay/          # 配置 + 状态 + Skills
+. relayignore   # 上下文忽略规则
+.opencode/      # OpenCode 的 OpenSpec 命令/Skill
+.claude/        # Claude Code 的 OpenSpec 命令 + Skills
+.codex/         # Codex 的 OpenSpec Skills
+.agents/        # Codex 的 relay Skills
+openspec/       # OpenSpec 规范目录
+AGENTS.md       # relay-kit 执行规则注入
 ```
 
 ## 2. 规划功能
 
-对聪明模型说：
+对 Advisor（聪明模型）说：
 
-```text
+```
 用 relay-planner 帮我规划「本地项目存储」功能。
-请判断是否需要 OpenSpec，明确目标、范围、非目标，并拆成 tasks。
+判断是否需要 OpenSpec，明确目标、范围、非目标，并拆成 tasks。
 ```
 
-如果是中大型功能，建议输出：
+得到 `PLAN_REPORT` 后，如果推荐 OpenSpec 模式：
 
-```text
-openspec/changes/add-local-project-storage/
-  proposal.md
-  design.md
-  tasks.md
+```bash
+relay openspec new-change add-local-storage
 ```
 
-## 3. 委派给小模型
-
-对聪明模型说：
-
-```text
-用 relay-delegator 把当前 OpenSpec change 的第 1-2 项交给 OpenCode。
-```
+然后在 AI 工具中运行 `/opsx:propose add-local-storage` 生成完整制品。
 
-Skill 底层调用或建议：
+## 3. 委派给 Executor
 
 ```bash
-relay start
+relay start --change add-local-storage --title "实现本地项目存储"
 ```
 
-生成：
+生成 `EXECUTOR_TASK.md`，交给 Executor：
 
-```text
-docs/agent-handoffs/runs/<run-id>/lanes/main/EXECUTOR_TASK.md
+```
+用 /relay:run 执行当前任务。
 ```
 
-把 `EXECUTOR_TASK.md` 交给 OpenCode。
-
-## 4. 小模型卡住
+## 4. Executor 卡住
 
 ```bash
 relay ask
 ```
 
-生成 `ASK_ADVISOR.md`，交给聪明模型：
+生成 `ASK_ADVISOR.md`，交给 Advisor：
 
-```text
+```
 用 relay-escalation 分析这个 ASK_ADVISOR，输出 ADVISOR_DECISION。
 ```
 
-## 5. 顾问给出决策后继续
+## 5. Advisor 决策后继续
 
 保存顾问回复为 `ADVISOR_DECISION.md`，运行：
 
@@ -89,7 +70,7 @@ relay ask
 relay resume
 ```
 
-生成 `RESUME_PROMPT.md`，交给 OpenCode 继续。
+生成 `RESUME_PROMPT.md`，交给 Executor 继续。
 
 ## 6. 完成后 Review
 
@@ -97,20 +78,28 @@ relay resume
 relay review
 ```
 
-生成 `REVIEW_REQUEST.md`，交给聪明模型：
+生成 `REVIEW_REQUEST.md`，交给 Advisor：
 
-```text
-用 relay-reviewer review 当前实现。
-不要直接改代码，先输出 REVIEW_REPORT。
+```
+用 relay-reviewer review 当前实现。先输出 REVIEW_REPORT。
 ```
 
-## 7. 最简心智模型
+## 7. 更新 relay-kit
 
-```text
-planner：规划
-delegator：委派
-executor：执行
-escalation：卡住求助
-resume：继续执行
-reviewer：审查
+```bash
+npm update -g relay-kit
+cd your-project
+relay sync --all    # 全量更新 Skills + OpenSpec 文件
+```
+
+## 8. 最简心智模型
+
+```
+planner    → 规划
+delegator  → 委派成 EXECUTOR_TASK
+executor   → 小步执行，卡住求助
+escalation → Advisor 决策
+resume     → 拿决策继续
+reviewer   → 审查 + 裁决
+openspec   → 管理 change 生命周期
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-kit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Skills-first, CLI-assisted AI programming relay workflow toolkit.",
   "types": "./dist/cli.d.ts",
   "repository": {
@@ -27,7 +27,8 @@
     ".opencode",
     ".claude",
     ".codex",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ],
   "scripts": {
     "dev": "tsx src/cli.ts",