relay-kit 0.2.0

package/docs/SKILLS_INSTALLATION.md

@@ -0,0 +1,243 @@
+# Skills 安装与同步策略
+
+## 1. 核心结论
+
+`relay-kit` 采用 **项目级 Skills 默认安装，用户级 Skills 可选安装** 的策略。
+
+原因：
+
+1. 项目级 Skills 跟项目绑定，适合版本管理；
+2. 不污染用户所有项目；
+3. 不同项目可以有不同的 relay 工作流；
+4. 适合团队协作和作品集展示；
+5. 后续可通过 `relay sync --skills` 更新。
+
+## 2. 不同工具的 Skills 目录
+
+不同 AI Coding 工具的自动扫描目录不同，不能假设 `.agents/skills/` 被所有工具识别。
+
+### Claude Code
+
+项目级：
+
+```text
+.claude/skills/<skill-name>/SKILL.md
+```
+
+用户级：
+
+```text
+~/.claude/skills/<skill-name>/SKILL.md
+```
+
+### Codex
+
+项目级：
+
+```text
+.agents/skills/<skill-name>/SKILL.md
+```
+
+用户级：
+
+```text
+~/.agents/skills/<skill-name>/SKILL.md
+```
+
+## 3. relay-kit 管理副本
+
+无论用户选择哪些工具，`relay init` 都应该生成 relay-kit 自己的管理副本：
+
+```text
+.relay/
+  skills/
+    relay-planner/
+      SKILL.md
+    relay-delegator/
+      SKILL.md
+    relay-escalation/
+      SKILL.md
+    relay-reviewer/
+      SKILL.md
+```
+
+它的作用：
+
+```text
+1. 作为 relay-kit 的源副本；
+2. 方便 relay sync 统一更新；
+3. 方便项目自己保留一份完整工作流；
+4. 不依赖某个具体 AI 工具的扫描目录。
+```
+
+## 4. 默认安装目标
+
+`relay init` 默认建议安装：
+
+```text
+[✓] .relay/skills   relay-kit 管理副本，必选
+[✓] .claude/skills        Claude Code 项目级 Skills
+[✓] .agents/skills        Codex 项目级 Skills
+[ ] ~/.claude/skills      Claude Code 用户级 Skills
+[ ] ~/.agents/skills      Codex 用户级 Skills
+```
+
+默认不安装用户级，除非用户明确选择。
+
+## 5. MVP 默认安装哪些 Skills
+
+MVP 默认安装 4 个：
+
+```text
+relay-planner
+relay-delegator
+relay-escalation
+relay-reviewer
+```
+
+可选安装：
+
+```text
+relay-lane-planner
+relay-docs
+```
+
+## 6. relay init 交互设计
+
+```text
+请选择要同步 Skills 的目标：
+
+[✓] .relay/skills   relay-kit 管理副本，必选
+[✓] .claude/skills        Claude Code 项目级，推荐
+[✓] .agents/skills        Codex 项目级，推荐
+[ ] ~/.claude/skills      Claude Code 用户级，高级选项
+[ ] ~/.agents/skills      Codex 用户级，高级选项
+```
+
+如果用户不使用某个工具，可以取消对应目标。
+
+## 7. 目录生成示例
+
+```text
+your-project/
+  .relay/
+    skills/
+      relay-planner/SKILL.md
+      relay-delegator/SKILL.md
+      relay-escalation/SKILL.md
+      relay-reviewer/SKILL.md
+
+  .claude/
+    skills/
+      relay-planner/SKILL.md
+      relay-delegator/SKILL.md
+      relay-escalation/SKILL.md
+      relay-reviewer/SKILL.md
+
+  .agents/
+    skills/
+      relay-planner/SKILL.md
+      relay-delegator/SKILL.md
+      relay-escalation/SKILL.md
+      relay-reviewer/SKILL.md
+```
+
+## 8. sync 命令设计
+
+### 同步所有项目级 Skills
+
+```bash
+relay sync --skills
+```
+
+默认从：
+
+```text
+.relay/skills/
+```
+
+同步到当前项目已启用的目标：
+
+```text
+.claude/skills/
+.agents/skills/
+```
+
+### 指定目标
+
+```bash
+relay sync --skills --target claude
+relay sync --skills --target codex
+relay sync --skills --target all
+```
+
+### 指定作用域
+
+```bash
+relay sync --skills --target claude --scope project
+relay sync --skills --target claude --scope user
+relay sync --skills --target all --scope project
+relay sync --skills --target all --scope user
+```
+
+## 9. 配置字段
+
+`.relay/config.json` 增加：
+
+```json
+{
+  "skills": {
+    "install": {
+      "manager": true,
+      "claudeProject": true,
+      "codexProject": true,
+      "claudeUser": false,
+      "codexUser": false
+    },
+    "enabled": [
+      "relay-planner",
+      "relay-delegator",
+      "relay-escalation",
+      "relay-reviewer"
+    ],
+    "optional": [
+      "relay-lane-planner",
+      "relay-docs"
+    ]
+  }
+}
+```
+
+## 10. Git 提交建议
+
+建议提交：
+
+```text
+.relay/skills/
+.claude/skills/
+.agents/skills/
+```
+
+如果团队不希望提交工具目录，可以只提交：
+
+```text
+.relay/skills/
+```
+
+然后让每个成员本地运行：
+
+```bash
+relay sync --skills
+```
+
+## 11. 最终规则
+
+```text
+1. .relay/skills 是 relay-kit 管理副本，默认必装。
+2. .claude/skills 是 Claude Code 项目级实际识别目录。
+3. .agents/skills 是 Codex 项目级实际识别目录。
+4. 不使用 .codex/skills 作为默认目录。
+5. 默认安装项目级，不默认安装用户级。
+6. 用户级通过 relay sync --skills --scope user 手动开启。
+7. sync 负责把管理副本同步到具体工具目录。
+```

package/docs/SMOKE_TESTS.md

@@ -0,0 +1,137 @@
+# v0.1 alpha 冒烟测试
+
+本文档用于在发布前或本地安装后验证 `relay-kit` 的最小真实项目流程。所有临时项目都应创建在仓库外，避免把 smoke-test 产物提交进发布包。
+
+## 前置准备
+
+在 `relay-kit` 仓库中构建并链接 CLI：
+
+```bash
+pnpm install
+pnpm build
+npm link
+relay --help
+```
+
+试用完成后清理全局 link：
+
+```bash
+npm unlink -g relay-kit
+```
+
+也可以使用 tarball 试用：
+
+```bash
+pnpm build
+npm pack
+npm install -g ./relay-kit-0.1.0.tgz
+relay --help
+```
+
+## simple 项目流程
+
+创建仓库外临时项目：
+
+```bash
+mkdir relay-smoke-simple
+cd relay-smoke-simple
+npm init -y
+mkdir src
+echo "console.log('hello relay')" > src/index.js
+```
+
+运行 relay 流程：
+
+```bash
+relay init --mode simple
+relay start --title "验证 alpha simple 流程" --scope "src/**" --blocked-scope "不要修改 package metadata"
+relay ask
+relay review
+relay doctor
+```
+
+预期生成：
+
+```text
+.relay/config.json
+.relay/state.json
+.relay/skills/relay-planner/SKILL.md
+.claude/skills/relay-delegator/SKILL.md
+.agents/skills/relay-reviewer/SKILL.md
+docs/agent-handoffs/runs/<run-id>/lanes/main/EXECUTOR_TASK.md
+docs/agent-handoffs/runs/<run-id>/lanes/main/ASK_ADVISOR.md
+docs/agent-handoffs/runs/<run-id>/lanes/main/REVIEW_REQUEST.md
+AGENTS.md
+```
+
+常见失败：
+
+- `relay ask` 提示没有 current run：先运行 `relay start`。
+- `relay init` 提示已初始化：确认是否要使用 `relay init --force` 重写 relay-kit 管理文件。
+- `relay ask --run build` 提示没有 build 命令：先在目标项目 `package.json` 中添加 `scripts.build`。
+
+## OpenSpec 项目流程
+
+创建仓库外临时项目和最小 OpenSpec change：
+
+```bash
+mkdir relay-smoke-openspec
+cd relay-smoke-openspec
+npm init -y
+mkdir -p openspec/changes/add-demo
+echo "## Why\n\n验证 OpenSpec handoff。" > openspec/changes/add-demo/proposal.md
+echo "## Context\n\n最小设计。" > openspec/changes/add-demo/design.md
+echo "- [ ] 1.1 验证 relay start 可以读取 change。" > openspec/changes/add-demo/tasks.md
+```
+
+运行 relay 流程：
+
+```bash
+relay init --mode openspec
+relay start --change add-demo --title "执行 add-demo"
+relay ask
+relay review
+relay doctor
+```
+
+预期生成：
+
+```text
+.relay/config.json
+.relay/state.json
+docs/agent-handoffs/runs/<run-id>/lanes/main/EXECUTOR_TASK.md
+docs/agent-handoffs/runs/<run-id>/lanes/main/ASK_ADVISOR.md
+docs/agent-handoffs/runs/<run-id>/lanes/main/REVIEW_REQUEST.md
+```
+
+`EXECUTOR_TASK.md` 应包含 `OpenSpec Change: add-demo`，并包含 `proposal.md`、`design.md`、`tasks.md` 的上下文摘要。relay-kit 只生成 handoff，不替代 `/opsx:apply`。
+
+## 发布包验证
+
+发布前按顺序运行：
+
+```bash
+pnpm build
+pnpm test
+npm pack
+npm publish --dry-run
+```
+
+检查 tarball 必须包含：
+
+```text
+package/dist/
+package/templates/
+package/skills/
+package/README.md
+```
+
+检查 tarball 不应包含：
+
+```text
+package/node_modules/
+package/tests/
+package/.env
+package/.env.*
+package/openspec/changes/
+```

package/docs/USAGE_FLOW.md

@@ -0,0 +1,116 @@
+# 使用流程
+
+## 1. 第一次接入项目
+
+```bash
+relay init
+```
+
+如果没有 OpenSpec，会让用户选择：
+
+```text
+1. Simple 模式：不使用 OpenSpec
+2. OpenSpec 模式：已有 OpenSpec，接入即可
+3. 引导初始化 OpenSpec：只提示/确认，不静默安装
+```
+
+初始化后生成：
+
+```text
+.relay/
+  config.json
+  state.json
+  skills/
+
+docs/
+  agent-handoffs/
+    runs/
+
+AGENTS.md
+```
+
+## 2. 规划功能
+
+对聪明模型说：
+
+```text
+用 relay-planner 帮我规划「本地项目存储」功能。
+请判断是否需要 OpenSpec，明确目标、范围、非目标，并拆成 tasks。
+```
+
+如果是中大型功能，建议输出：
+
+```text
+openspec/changes/add-local-project-storage/
+  proposal.md
+  design.md
+  tasks.md
+```
+
+## 3. 委派给小模型
+
+对聪明模型说：
+
+```text
+用 relay-delegator 把当前 OpenSpec change 的第 1-2 项交给 OpenCode。
+```
+
+Skill 底层调用或建议：
+
+```bash
+relay start
+```
+
+生成：
+
+```text
+docs/agent-handoffs/runs/<run-id>/lanes/main/EXECUTOR_TASK.md
+```
+
+把 `EXECUTOR_TASK.md` 交给 OpenCode。
+
+## 4. 小模型卡住
+
+```bash
+relay ask
+```
+
+生成 `ASK_ADVISOR.md`，交给聪明模型：
+
+```text
+用 relay-escalation 分析这个 ASK_ADVISOR，输出 ADVISOR_DECISION。
+```
+
+## 5. 顾问给出决策后继续
+
+保存顾问回复为 `ADVISOR_DECISION.md`，运行：
+
+```bash
+relay resume
+```
+
+生成 `RESUME_PROMPT.md`，交给 OpenCode 继续。
+
+## 6. 完成后 Review
+
+```bash
+relay review
+```
+
+生成 `REVIEW_REQUEST.md`，交给聪明模型：
+
+```text
+用 relay-reviewer review 当前实现。
+不要直接改代码，先输出 REVIEW_REPORT。
+```
+
+## 7. 最简心智模型
+
+```text
+planner：规划
+delegator：委派
+executor：执行
+escalation：卡住求助
+resume：继续执行
+reviewer：审查
+```

package/docs/V0_1_ALPHA_RELEASE.md

@@ -0,0 +1,59 @@
+# v0.1 alpha 发布准备记录
+
+本文档记录 `prepare-v0-1-alpha-release` 的发布前检查结论。它不是正式 release note；正式公开发布前仍应根据实际仓库地址、npm registry 状态和最终验证结果更新。
+
+## package.json 结论
+
+- `name`: `relay-kit`，符合包名和 CLI 定位。
+- `version`: `0.1.0`，符合 alpha 试用阶段。
+- `description`: `Skills-first, CLI-assisted AI programming relay workflow toolkit.`，准确描述工具定位。
+- `bin.relay`: `dist/cli.js`，符合 npm bin 入口和构建产物路径。
+- `files`: 包含 `dist`、`skills`、`templates`、`README.md`，以及精选的 `docs/` 文件（CLI_SPEC、FINAL_DESIGN、OPENSPEC_INTEGRATION、RUN_LANE_DESIGN、SKILLS_INSTALLATION、SMOKE_TESTS、USAGE_FLOW、V0_1_ALPHA_RELEASE）。排除了开发期内部文档（ROADMAP、DEVELOPMENT_TASKS、IMPLEMENTATION_PROMPTS、PACKAGE_STRUCTURE）。
+- `scripts`: 包含 `build` 和 `test`，满足发布前本地验证。
+- `license`: `MIT`。
+- `repository`: v0.1 alpha 暂时留空；正式公开发布前再补充真实仓库 URL。
+
+## 发布包内容策略
+
+必须发布：
+
+```text
+dist
+templates
+skills
+README.md
+docs
+```
+
+其中 `docs` 暂时保留，因为 alpha 用户需要查看设计、Skills 安装和冒烟测试说明。
+
+不得发布：
+
+```text
+node_modules
+tests
+.env
+.env.*
+openspec/changes
+```
+
+## 验证结果
+
+已完成验证：
+
+- `pnpm build`: 通过，`dist/cli.js` 重新生成，首行保留 `#!/usr/bin/env node`。
+- `pnpm test`: 通过，27 个 node:test 子测试全部通过。
+- `npm pack`: 通过，生成 `relay-kit-0.1.0.tgz`，tarball 共 32 个文件。
+- tarball 必要内容检查：包含 `package/dist`、`package/templates`、`package/skills`、`package/README.md`。
+- tarball 排除内容检查：未包含 `node_modules`、`tests`、`.env`、`.env.*`、`openspec/changes`。
+- `npm publish --dry-run`: 通过；当前 registry 为 `https://registry.npmmirror.com`，npm 提示 dry-run 发布需要登录，但退出码为 0，未发现包内容错误。
+- `npm link`: 通过。
+- `relay --help`: 通过，能展示 `init`、`start`、`ask`、`resume`、`review`、`doctor`、`sync` 命令。
+- simple 临时项目流程：通过，验证了 `relay init --mode simple`、`relay start`、`relay ask`、`relay review`、`relay doctor`，并确认生成项目级 Skills 与 handoff 文件。
+- OpenSpec 临时项目流程：通过，验证了 `relay init --mode openspec`、`relay start --change add-demo`、`relay ask`、`relay review`、`relay doctor`，并确认 `EXECUTOR_TASK.md` 包含 `OpenSpec Change: add-demo`。
+
+验证后已清理临时项目、全局 npm link 和本地 tarball。
+
+## 边界确认
+
+本次发布准备不新增 lane 并行功能，不新增 GUI，不自动调用模型 API，不改变 `relay init/start/ask/resume/review/doctor/sync --skills` 主流程设计，也不发布正式 1.0。

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "relay-kit",
+  "version": "0.2.0",
+  "description": "Skills-first, CLI-assisted AI programming relay workflow toolkit.",
+  "types": "./dist/cli.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wloops/relay-kit.git"
+  },
+  "type": "module",
+  "bin": {
+    "relay": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs/CLI_SPEC.md",
+    "docs/FINAL_DESIGN.md",
+    "docs/OPENSPEC_INTEGRATION.md",
+    "docs/RUN_LANE_DESIGN.md",
+    "docs/SKILLS_INSTALLATION.md",
+    "docs/SMOKE_TESTS.md",
+    "docs/USAGE_FLOW.md",
+    "docs/V0_1_ALPHA_RELEASE.md",
+    "CHANGELOG.md",
+    "skills",
+    "templates",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "cli",
+    "relay",
+    "workflow"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts"
+  }
+}

package/skills/relay-delegator/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: relay-delegator
+description: 内部 skill，由 planner 自动衔接触发，将任务委派给 Executor。不应由用户直接调用。
+---
+
+
+# relay-delegator
+
+你是 Relay 委派顾问（内部衔接，由 planner 自动触发）。
+
+## 核心规则
+
+1. 不要自己实现代码。
+2. 生成有边界的执行指令。
+3. 始终指定允许范围和禁止范围。
+4. 始终提及升级规则。
+5. 如果存在 OpenSpec，引用 proposal/design/tasks。
+6. 如果不存在 OpenSpec，使用 simple 模式。
+
+## 输出格式
+
+# EXECUTOR_TASK
+
+## Role
+你是执行者（Executor）。
+
+## Task
+
+## Source
+
+## Read First
+
+## Allowed Scope
+
+## Blocked Scope
+
+## Requirements
+
+## Escalation Rule
+
+## Verification
+
+## Completion Report Format

package/skills/relay-docs/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: relay-docs
+description: 预留 skill。当用户需要汇总进度、更新 PROGRESS.md、CHANGELOG、决策日志或将 AI 工作流历史转为项目文档时使用。
+---
+
+
+# relay-docs
+
+预留 skill，用于文档和进度跟踪。
+
+## 目标文件
+- PROGRESS.md
+- CHANGELOG.md
+- DECISION_LOG.md
+- README updates
+- Portfolio highlights

package/skills/relay-escalation/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: relay-escalation
+description: 内部 skill，当 Executor 生成 ASK_ADVISOR.md 后自动衔接触发。产出 ADVISOR_DECISION。不应由用户直接调用。
+---
+
+
+# relay-escalation
+
+你是 Relay 升级顾问（内部衔接，由 runner 自动触发），不是执行者（Executor）。
+
+## 决策类型
+
+- CONTINUE — 继续执行
+- PATCH — 最小修补
+- REPLAN — 重新规划
+- STOP — 停止
+- ASK_OWNER — 询问负责人
+
+## 核心规则
+
+1. 不要重写大量代码。
+2. 不要扩大范围。
+3. 优先选择最小的安全修复。
+4. 如果需要产品判断，返回 ASK_OWNER。
+5. 如果任务设计有误，返回 REPLAN。
+6. 如果实现路径有危险，返回 STOP。
+7. 始终提供一份给 Executor 的提示。
+
+## 输出格式
+
+# ADVISOR_DECISION
+
+## Decision Type
+
+## Root Cause
+
+## What Not To Do
+
+## Recommended Path
+
+## Minimal Change Scope
+
+## Execution Steps
+
+## Verification
+
+## Prompt For Executor