@coralai/sps-cli 0.18.0 → 0.18.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +520 -501
  2. package/dist/commands/setup.d.ts.map +1 -1
  3. package/dist/commands/setup.js +108 -73
  4. package/dist/commands/setup.js.map +1 -1
  5. package/dist/commands/status.d.ts +2 -0
  6. package/dist/commands/status.d.ts.map +1 -0
  7. package/dist/commands/status.js +127 -0
  8. package/dist/commands/status.js.map +1 -0
  9. package/dist/main.js +7 -0
  10. package/dist/main.js.map +1 -1
  11. package/package.json +1 -1
package/README.md CHANGED
@@ -1,281 +1,286 @@
1
- # SPS CLI — AI 驱动的全自动开发流水线
1
+ # SPS CLI — AI-Driven Fully Automated Development Pipeline
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@coralai/sps-cli)](https://www.npmjs.com/package/@coralai/sps-cli)
4
4
 
5
- SPS（Smart Pipeline System）是一套 AI Agent 驱动的全自动开发流水线 CLI 工具。从任务卡片创建到代码合并，全程无人值守。
5
+ [中文文档 / Chinese Documentation](https://git.wymsn.com/coral/jarvis-skills/-/blob/main/coding-work-flow/workflow-cli/README-CN.md)
6
+
7
+ **v0.18.0**
8
+
9
+ SPS (Smart Pipeline System) is a fully automated development pipeline CLI tool driven by AI Agents. From task card creation to code merging, the entire process runs unattended.
6
10
 
7
11
  ```
8
- 创建卡片 → 启动 pipeline → AI 自动编码 → 自动合并到目标分支 → 通知完成
12
+ Create cards -> Start pipeline -> AI auto-codes -> Auto-merge to target branch -> Notify completion
9
13
  ```
10
14
 
11
- ## 目录
15
+ ## Table of Contents
12
16
 
13
- - [安装](#安装)
14
- - [前置条件](#前置条件)
15
- - [快速开始](#快速开始)
16
- - [状态机](#状态机)
17
- - [命令参考](#命令参考)
17
+ - [Installation](#installation)
18
+ - [Prerequisites](#prerequisites)
19
+ - [Quick Start](#quick-start)
20
+ - [State Machine](#state-machine)
21
+ - [Command Reference](#command-reference)
18
22
  - [sps setup](#sps-setup)
19
23
  - [sps project init](#sps-project-init)
20
24
  - [sps doctor](#sps-doctor)
21
25
  - [sps card add](#sps-card-add)
22
26
  - [sps tick](#sps-tick)
27
+ - [sps status](#sps-status)
23
28
  - [sps scheduler tick](#sps-scheduler-tick)
24
29
  - [sps pipeline tick](#sps-pipeline-tick)
25
30
  - [sps worker](#sps-worker)
26
31
  - [sps pm](#sps-pm)
27
32
  - [sps qa tick](#sps-qa-tick)
28
33
  - [sps monitor tick](#sps-monitor-tick)
29
- - [Worker 规则文件](#worker-规则文件)
30
- - [项目配置](#项目配置)
31
- - [多项目并行](#多项目并行)
32
- - [架构概览](#架构概览)
33
- - [目录结构](#目录结构)
34
+ - [Worker Rule Files](#worker-rule-files)
35
+ - [Project Configuration](#project-configuration)
36
+ - [Multi-Project Parallel Execution](#multi-project-parallel-execution)
37
+ - [Architecture Overview](#architecture-overview)
38
+ - [Directory Structure](#directory-structure)
34
39
 
35
40
  ---
36
41
 
37
- ## 安装
42
+ ## Installation
38
43
 
39
44
  ```bash
40
45
  npm install -g @coralai/sps-cli
41
46
  ```
42
47
 
43
- 本地开发：
48
+ Local development:
44
49
 
45
50
  ```bash
46
51
  cd coding-work-flow/workflow-cli
47
52
  npm run build
48
- # 或使用 tsx 直接运行
53
+ # Or run directly with tsx
49
54
  npx tsx src/main.ts --help
50
55
  ```
51
56
 
52
- ## 前置条件
57
+ ## Prerequisites
53
58
 
54
- | 依赖 | 最低版本 | 说明 |
55
- |------|---------|------|
56
- | Node.js | 18+ | CLI 运行环境 |
57
- | git | 2.x | 分支与 worktree 管理 |
58
- | Claude Code CLI 或 Codex CLI | 最新 | AI Worker |
59
- | tmux | 3.x | 仅 `WORKER_MODE=interactive` 时需要 |
59
+ | Dependency | Minimum Version | Description |
60
+ |------------|----------------|-------------|
61
+ | Node.js | 18+ | CLI runtime |
62
+ | git | 2.x | Branch and worktree management |
63
+ | Claude Code CLI or Codex CLI | Latest | AI Worker |
64
+ | tmux | 3.x | Only required for `WORKER_MODE=interactive` |
60
65
 
61
- ## 快速开始
66
+ ## Quick Start
62
67
 
63
68
  ```bash
64
- # 1. 全局环境初始化（首次使用，配置 GitLab/PM/通知凭据）
69
+ # 1. Global environment initialization (first-time setup, configure GitLab/PM/notification credentials)
65
70
  sps setup
66
71
 
67
- # 2. 克隆业务仓库（前置条件）
72
+ # 2. Clone your project repository (prerequisite)
68
73
  git clone git@gitlab.example.com:team/my-project.git ~/projects/my-project
69
74
 
70
- # 3. 初始化 SPS 项目管理目录
75
+ # 3. Initialize SPS project management directory
71
76
  sps project init my-project
72
77
 
73
- # 4. 编辑项目配置
78
+ # 4. Edit project configuration
74
79
  vim ~/.coral/projects/my-project/conf
75
80
 
76
- # 5. 健康检查 + 自动修复（生成 CLAUDE.md、AGENTS.md、初始化 state.json 等）
81
+ # 5. Health check + auto-fix (generates CLAUDE.md, AGENTS.md, initializes state.json, etc.)
77
82
  sps doctor my-project --fix
78
83
 
79
- # 6.（可选）编辑 Worker 规则，加入项目特有的编码规范
84
+ # 6. (Optional) Edit Worker rules to add project-specific coding standards
80
85
  vim ~/projects/my-project/CLAUDE.md
81
86
 
82
- # 7. 创建任务卡片
83
- sps card add my-project "实现用户登录" "JWT 登录接口"
84
- sps card add my-project "实现订单系统" "CRUD API + 分页"
87
+ # 7. Create task cards
88
+ sps card add my-project "Implement user login" "JWT authentication endpoint"
89
+ sps card add my-project "Implement order system" "CRUD API + pagination"
85
90
 
86
- # 8. 启动 pipeline（全自动，所有卡片完成后自动退出）
91
+ # 8. Start pipeline (fully automated, exits when all cards are complete)
87
92
  sps tick my-project
88
93
 
89
- # 9.（可选）实时监控 Worker 运行状态
94
+ # 9. (Optional) Monitor Worker status in real time
90
95
  sps worker dashboard
91
96
  ```
92
97
 
93
98
  ---
94
99
 
95
- ## 状态机
100
+ ## State Machine
96
101
 
97
- 每张任务卡片按以下状态机流转，全程由 SPS 自动驱动：
102
+ Each task card progresses through the following state machine, fully driven by SPS:
98
103
 
99
- ### MR_MODE=none（默认，推荐）
104
+ ### MR_MODE=none (Default, Recommended)
100
105
 
101
- Worker 完成编码后直接合并到目标分支，跳过 MR/CI/QA 环节：
106
+ After completing coding, the Worker merges directly to the target branch, skipping MR/CI/QA stages:
102
107
 
103
108
  ```
104
- Planning → Backlog → Todo → Inprogress → Done
109
+ Planning -> Backlog -> Todo -> Inprogress -> Done
105
110
  ```
106
111
 
107
- | 阶段 | 触发引擎 | 操作 |
108
- |------|---------|------|
109
- | Planning → Backlog | SchedulerEngine | 选卡入队，检查准入条件 |
110
- | Backlog → Todo | ExecutionEngine | 创建分支、创建 worktree、生成 `.sps/merge.sh` |
111
- | Todo → Inprogress | ExecutionEngine | 分配 Worker slot、构建任务上下文、启动 AI Worker |
112
- | Inprogress → Done | ExecutionEngine | 检测 Worker 完成（代码已合并到目标分支）、释放资源、清理 worktree |
112
+ | Phase | Trigger Engine | Action |
113
+ |-------|---------------|--------|
114
+ | Planning -> Backlog | SchedulerEngine | Select card for queue, check admission criteria |
115
+ | Backlog -> Todo | ExecutionEngine | Create branch, create worktree, generate `.sps/merge.sh` |
116
+ | Todo -> Inprogress | ExecutionEngine | Assign Worker slot, build task context, launch AI Worker |
117
+ | Inprogress -> Done | ExecutionEngine | Detect Worker completion (code merged to target branch), release resources, clean up worktree |
113
118
 
114
- Worker 执行的最后一步是运行 `bash .sps/merge.sh`，该脚本自动将 feature branch rebase 并合并到目标分支。
119
+ The Worker's final step is running `bash .sps/merge.sh`, which automatically rebases and merges the feature branch into the target branch.
115
120
 
116
- ### MR_MODE=create（可选）
121
+ ### MR_MODE=create (Optional)
117
122
 
118
- Worker 完成编码后创建 MR，任务即完成。MR 审核由后续流程处理（待开发）：
123
+ After completing coding, the Worker creates an MR. The task is then considered complete. MR review is handled by subsequent processes (under development):
119
124
 
120
125
  ```
121
- Planning → Backlog → Todo → Inprogress → Done（MR 已创建）
126
+ Planning -> Backlog -> Todo -> Inprogress -> Done (MR created)
122
127
  ```
123
128
 
124
- | 阶段 | 触发引擎 | 操作 |
125
- |------|---------|------|
126
- | Inprogress → Done | ExecutionEngine | 检测 Worker 完成（MR 已创建）、释放资源、清理 worktree |
129
+ | Phase | Trigger Engine | Action |
130
+ |-------|---------------|--------|
131
+ | Inprogress -> Done | ExecutionEngine | Detect Worker completion (MR created), release resources, clean up worktree |
127
132
 
128
- ### 辅助状态标签
133
+ ### Auxiliary Status Labels
129
134
 
130
- 卡片可能被标记以下标签，表示需要特殊处理：
135
+ Cards may be tagged with the following labels, indicating special handling is needed:
131
136
 
132
- | 标签 | 含义 | 处理方式 |
133
- |------|------|---------|
134
- | `BLOCKED` | 被外部依赖阻塞 | 跳过，等待人工处理 |
135
- | `NEEDS-FIX` | Worker 失败或 CI 失败 | 自动修复或人工介入 |
136
- | `WAITING-CONFIRMATION` | Worker 等待破坏性操作确认 | 通知人工确认 |
137
- | `CONFLICT` | 合并冲突 | Worker 自动解冲突或人工处理 |
138
- | `STALE-RUNTIME` | Worker 运行时异常 | MonitorEngine 清理 |
137
+ | Label | Meaning | Handling |
138
+ |-------|---------|----------|
139
+ | `BLOCKED` | Blocked by external dependency | Skipped, awaiting manual intervention |
140
+ | `NEEDS-FIX` | Worker failure or CI failure | Auto-fix or manual intervention |
141
+ | `WAITING-CONFIRMATION` | Worker awaiting destructive operation confirmation | Notify for manual confirmation |
142
+ | `CONFLICT` | Merge conflict | Worker auto-resolves or manual handling |
143
+ | `STALE-RUNTIME` | Worker runtime anomaly | MonitorEngine cleanup |
139
144
 
140
145
  ---
141
146
 
142
- ## 命令参考
147
+ ## Command Reference
143
148
 
144
- ### 全局选项
149
+ ### Global Options
145
150
 
146
- 所有命令均支持：
151
+ All commands support:
147
152
 
148
- | 选项 | 说明 |
149
- |------|------|
150
- | `--json` | 输出结构化 JSON（供脚本/cron 消费） |
151
- | `--dry-run` | 预览操作，不实际执行 |
152
- | `--help` | 显示帮助 |
153
- | `--version` | 显示版本号 |
153
+ | Option | Description |
154
+ |--------|-------------|
155
+ | `--json` | Output structured JSON (for script/cron consumption) |
156
+ | `--dry-run` | Preview actions without executing |
157
+ | `--help` | Show help |
158
+ | `--version` | Show version number |
154
159
 
155
- ### 退出码
160
+ ### Exit Codes
156
161
 
157
- | 退出码 | 含义 |
158
- |-------|------|
159
- | `0` | 成功 |
160
- | `1` | 业务失败 / 校验失败 |
161
- | `2` | 参数错误 |
162
- | `3` | 外部依赖不可用（GitLab / PM / Worker） |
162
+ | Exit Code | Meaning |
163
+ |-----------|---------|
164
+ | `0` | Success |
165
+ | `1` | Business failure / validation failure |
166
+ | `2` | Argument error |
167
+ | `3` | External dependency unavailable (GitLab / PM / Worker) |
163
168
 
164
169
  ---
165
170
 
166
171
  ### sps setup
167
172
 
168
- 全局环境初始化向导，配置各外部系统凭据。
173
+ Global environment initialization wizard for configuring external system credentials. Preserves existing values by showing current configuration as defaults -- press Enter to keep the current value.
169
174
 
170
175
  ```bash
171
176
  sps setup [--force]
172
177
  ```
173
178
 
174
- **交互式配置项：**
179
+ **Interactive configuration items:**
175
180
 
176
- - GitLab：`GITLAB_URL`、`GITLAB_TOKEN`、`GITLAB_SSH_HOST`、`GITLAB_SSH_PORT`
177
- - Plane：`PLANE_URL`、`PLANE_API_KEY`、`PLANE_WORKSPACE_SLUG`
178
- - Trello：`TRELLO_API_KEY`、`TRELLO_TOKEN`
179
- - Matrix：`MATRIX_HOMESERVER`、`MATRIX_TOKEN`、`MATRIX_ROOM_ID`
181
+ - GitLab: `GITLAB_URL`, `GITLAB_TOKEN`, `GITLAB_SSH_HOST`, `GITLAB_SSH_PORT`
182
+ - Plane: `PLANE_URL`, `PLANE_API_KEY`, `PLANE_WORKSPACE_SLUG`
183
+ - Trello: `TRELLO_API_KEY`, `TRELLO_TOKEN`
184
+ - Matrix: `MATRIX_HOMESERVER`, `MATRIX_TOKEN`, `MATRIX_ROOM_ID`
180
185
 
181
- 凭据写入 `~/.coral/env`（权限 0600），所有项目共享。
186
+ Credentials are stored in `~/.coral/env` (permissions 0600), shared across all projects.
182
187
 
183
- | 选项 | 说明 |
184
- |------|------|
185
- | `--force` | 覆盖已有的 `~/.coral/env` |
188
+ | Option | Description |
189
+ |--------|-------------|
190
+ | `--force` | Overwrite existing `~/.coral/env` |
186
191
 
187
192
  ---
188
193
 
189
194
  ### sps project init
190
195
 
191
- 初始化 SPS 项目管理目录。
196
+ Initialize an SPS project management directory.
192
197
 
193
198
  ```bash
194
199
  sps project init <project> [--force]
195
200
  ```
196
201
 
197
- **创建的目录结构：**
202
+ **Created directory structure:**
198
203
 
199
204
  ```
200
205
  ~/.coral/projects/<project>/
201
- ├── conf # 项目配置文件（从模板生成）
202
- ├── logs/ # 日志目录
203
- ├── pm_meta/ # PM 元数据缓存
204
- ├── runtime/ # 运行时状态
205
- ├── pipeline_order.json # 卡片执行顺序
206
- ├── batch_scheduler.sh # cron 兼容入口脚本
207
- └── deploy.sh # 部署脚本模板
206
+ ├── conf # Project configuration file (generated from template)
207
+ ├── logs/ # Log directory
208
+ ├── pm_meta/ # PM metadata cache
209
+ ├── runtime/ # Runtime state
210
+ ├── pipeline_order.json # Card execution order
211
+ ├── batch_scheduler.sh # cron-compatible entry script
212
+ └── deploy.sh # Deployment script template
208
213
  ```
209
214
 
210
- | 选项 | 说明 |
211
- |------|------|
212
- | `--force` | 覆盖模板文件（conf 不会被覆盖） |
215
+ | Option | Description |
216
+ |--------|-------------|
217
+ | `--force` | Overwrite template files (conf will not be overwritten) |
213
218
 
214
- **示例：**
219
+ **Example:**
215
220
 
216
221
  ```bash
217
222
  sps project init accounting-agent
218
- # → 生成 ~/.coral/projects/accounting-agent/
219
- # → 下一步：编辑 conf 填入配置值
223
+ # -> Creates ~/.coral/projects/accounting-agent/
224
+ # -> Next step: edit conf to fill in configuration values
220
225
  ```
221
226
 
222
227
  ---
223
228
 
224
229
  ### sps doctor
225
230
 
226
- 项目健康检查与自动修复。
231
+ Project health check and auto-repair.
227
232
 
228
233
  ```bash
229
234
  sps doctor <project> [--fix] [--json] [--skip-remote]
230
235
  ```
231
236
 
232
- 等价于 `sps project doctor <project>`。
233
-
234
- **检查项：**
235
-
236
- | 检查项 | 说明 | --fix |
237
- |-------|------|-------|
238
- | global-env | `~/.coral/env` 是否存在 | — |
239
- | global-env-vars | GITLAB_URL / GITLAB_TOKEN 是否已加载 | — |
240
- | conf-load | 配置文件是否可加载 | — |
241
- | conf-fields | 必填字段是否完整 | — |
242
- | instance-dir / logs-dir / runtime-dir / pm-meta-dir | 目录结构 | 创建缺失目录 |
243
- | repo-dir | 业务仓库是否存在且为 git 仓库 | — |
244
- | gitignore-sps | `.sps/` 是否在 .gitignore 中 | 追加 |
245
- | worker-rules | CLAUDE.md / AGENTS.md 是否存在于仓库根目录 | 生成并提交（含 .gitignore） |
246
- | skill-profiles | DEFAULT_WORKER_SKILLS 指定的 profile 文件是否存在 | — |
247
- | state-json | 运行时状态文件是否有效 | 初始化 |
248
- | pipeline-order | 执行顺序文件是否存在 | 创建空 |
249
- | conf-cli-fields | CLI 所需的 Provider 字段映射是否完整（仅 Plane） | 追加映射 |
250
- | gitlab | GitLab API 连通性 | — |
251
- | plane | Plane API 连通性（仅 PM_TOOL=plane） | — |
252
- | pm-states / pm-lists | PM 状态/列表 UUID 是否有效 | 自动创建 + 写入 conf |
253
- | worker-tool | Claude Code / Codex CLI 是否在 PATH 中 | — |
254
- | tmux | tmux 是否可用（仅 WORKER_MODE=interactive） | — |
255
-
256
- | 选项 | 说明 |
257
- |------|------|
258
- | `--fix` | 自动修复可修复的问题（创建目录、生成文件、初始化状态） |
259
- | `--json` | 输出 JSON 格式的检查结果 |
260
- | `--skip-remote` | 跳过远程连通性检查（GitLab/Plane） |
261
-
262
- **示例：**
237
+ Equivalent to `sps project doctor <project>`.
238
+
239
+ **Checks:**
240
+
241
+ | Check | Description | --fix |
242
+ |-------|-------------|-------|
243
+ | global-env | Whether `~/.coral/env` exists | -- |
244
+ | global-env-vars | Whether GITLAB_URL / GITLAB_TOKEN are loaded | -- |
245
+ | conf-load | Whether configuration file can be loaded | -- |
246
+ | conf-fields | Whether all required fields are present | -- |
247
+ | instance-dir / logs-dir / runtime-dir / pm-meta-dir | Directory structure | Create missing directories |
248
+ | repo-dir | Whether project repo exists and is a git repository | -- |
249
+ | gitignore-sps | Whether `.sps/` is in .gitignore | Append |
250
+ | worker-rules | Whether CLAUDE.md / AGENTS.md exist in repo root | Generate and commit (including .gitignore) |
251
+ | skill-profiles | Whether profile files specified by DEFAULT_WORKER_SKILLS exist | -- |
252
+ | state-json | Whether runtime state file is valid | Initialize |
253
+ | pipeline-order | Whether execution order file exists | Create empty |
254
+ | conf-cli-fields | Whether CLI-required Provider field mappings are complete (Plane only) | Append mappings |
255
+ | gitlab | GitLab API connectivity | -- |
256
+ | plane | Plane API connectivity (PM_TOOL=plane only) | -- |
257
+ | pm-states / pm-lists | Whether PM state/list UUIDs are valid | Auto-create + write to conf |
258
+ | worker-tool | Whether Claude Code / Codex CLI is in PATH | -- |
259
+ | tmux | Whether tmux is available (WORKER_MODE=interactive only) | -- |
260
+
261
+ | Option | Description |
262
+ |--------|-------------|
263
+ | `--fix` | Auto-fix repairable issues (create directories, generate files, initialize state) |
264
+ | `--json` | Output check results in JSON format |
265
+ | `--skip-remote` | Skip remote connectivity checks (GitLab/Plane) |
266
+
267
+ **Example:**
263
268
 
264
269
  ```bash
265
- # 检查 + 自动修复
270
+ # Check + auto-fix
266
271
  sps doctor my-project --fix
267
- # ✓ global-env /home/user/.coral/env
268
- # ✓ global-env-vars GITLAB_URL and GITLAB_TOKEN set
269
- # ✓ conf-load Loaded ~/.coral/projects/my-project/conf
270
- # ✓ conf-fields All required fields present
271
- # ✓ repo-dir /home/user/projects/my-project
272
- # ✓ gitignore-sps .sps/ in .gitignore
273
- # ✓ worker-rules Generated and committed: CLAUDE.md, AGENTS.md
274
- # ✓ skill-profiles DEFAULT_WORKER_SKILLS="senior" — all profiles found
275
- # ✓ state-json Initialized with 3 worker slots
276
- # - tmux Not required (WORKER_MODE=print)
277
-
278
- # JSON 输出
272
+ # ok global-env /home/user/.coral/env
273
+ # ok global-env-vars GITLAB_URL and GITLAB_TOKEN set
274
+ # ok conf-load Loaded ~/.coral/projects/my-project/conf
275
+ # ok conf-fields All required fields present
276
+ # ok repo-dir /home/user/projects/my-project
277
+ # ok gitignore-sps .sps/ in .gitignore
278
+ # ok worker-rules Generated and committed: CLAUDE.md, AGENTS.md
279
+ # ok skill-profiles DEFAULT_WORKER_SKILLS="senior" -- all profiles found
280
+ # ok state-json Initialized with 3 worker slots
281
+ # - tmux Not required (WORKER_MODE=print)
282
+
283
+ # JSON output
279
284
  sps doctor my-project --json
280
285
  ```
281
286
 
@@ -283,112 +288,112 @@ sps doctor my-project --json
283
288
 
284
289
  ### sps card add
285
290
 
286
- 创建任务卡片。
291
+ Create a task card.
287
292
 
288
293
  ```bash
289
294
  sps card add <project> "<title>" ["description"]
290
295
  ```
291
296
 
292
- 卡片创建在 Planning 状态，自动添加 `AI-PIPELINE` 标签，并追加到 `pipeline_order.json` 中。
297
+ Cards are created in the Planning state, automatically tagged with `AI-PIPELINE`, and appended to `pipeline_order.json`.
293
298
 
294
- 创建后需要打一个 `skill:` 标签，指定 Worker 的专业技能（见下方标签说明）。
299
+ After creation, add a `skill:` label to specify the Worker's expertise (see label descriptions below).
295
300
 
296
- | 选项 | 说明 |
297
- |------|------|
298
- | `--json` | 输出 JSON 格式的创建结果 |
301
+ | Option | Description |
302
+ |--------|-------------|
303
+ | `--json` | Output creation result in JSON format |
299
304
 
300
- **示例：**
305
+ **Example:**
301
306
 
302
307
  ```bash
303
- # 创建卡片 + 打 skill 标签
304
- sps card add my-project "实现用户登录" "使用 JWT 的认证接口"
308
+ # Create cards + add skill labels
309
+ sps card add my-project "Implement user login" "JWT authentication endpoint"
305
310
  sps pm addLabel my-project 1 "skill:backend"
306
311
 
307
- sps card add my-project "实现订单列表" "CRUD API + 分页查询"
312
+ sps card add my-project "Implement order list" "CRUD API + pagination"
308
313
  sps pm addLabel my-project 2 "skill:backend"
309
314
 
310
- sps card add my-project "写 API 文档" "用户和订单接口文档"
315
+ sps card add my-project "Write API documentation" "User and order endpoint docs"
311
316
  sps pm addLabel my-project 3 "skill:writer"
312
317
  ```
313
318
 
314
- #### Skill 标签
319
+ #### Skill Labels
315
320
 
316
- 每张卡片打 **一个** `skill:` 标签，Pipeline 自动加载对应的 Worker skill profile 注入 prompt：
321
+ Each card should have **one** `skill:` label. The Pipeline automatically loads the corresponding Worker skill profile and injects it into the prompt:
317
322
 
318
- | 标签 | Worker 角色 | 交付物 |
319
- |------|------------|--------|
320
- | `skill:architect` | 架构设计 | ADR、设计文档、目录结构 |
321
- | `skill:frontend` | 前端开发 | 组件、页面、前端测试 |
322
- | `skill:backend` | 后端开发 | API、DB migration、后端测试 |
323
- | `skill:fullstack` | 全栈开发 | 前后端 + DB 一体化 |
324
- | `skill:prototyper` | 快速原型 | 可运行的 MVP |
325
- | `skill:reviewer` | 代码审查 | Review 报告 + 修复 commit |
326
- | `skill:security` | 安全审计 | 审计报告 + 漏洞修复 |
327
- | `skill:writer` | 技术文档 | README、API 文档、PRD |
328
- | `skill:optimizer` | 性能优化 | Benchmark 报告 + 优化 commit |
329
- | `skill:senior` | 通用（兜底） | 高质量通用实现 |
323
+ | Label | Worker Role | Deliverables |
324
+ |-------|------------|--------------|
325
+ | `skill:architect` | Architecture design | ADR, design docs, directory structure |
326
+ | `skill:frontend` | Frontend development | Components, pages, frontend tests |
327
+ | `skill:backend` | Backend development | API, DB migration, backend tests |
328
+ | `skill:fullstack` | Full-stack development | Frontend + backend + DB integrated |
329
+ | `skill:prototyper` | Rapid prototyping | Runnable MVP |
330
+ | `skill:reviewer` | Code review | Review report + fix commits |
331
+ | `skill:security` | Security audit | Audit report + vulnerability fixes |
332
+ | `skill:writer` | Technical writing | README, API docs, PRD |
333
+ | `skill:optimizer` | Performance optimization | Benchmark report + optimization commits |
334
+ | `skill:senior` | General purpose (fallback) | High-quality general implementation |
330
335
 
331
- Profile 文件位于 `~/jarvis-skills/skills/worker-profiles/<name>.md`。无标签时 fallback 到项目 conf 中的 `DEFAULT_WORKER_SKILLS`。
336
+ Profile files are located at `~/.coral/profiles/<name>.md`. When no label is present, it falls back to the project conf's `DEFAULT_WORKER_SKILLS`.
332
337
 
333
338
  ---
334
339
 
335
340
  ### sps tick
336
341
 
337
- 统一主循环——编排全部引擎，依次执行 scheduler → qa → pipeline → monitor。
342
+ Unified main loop -- orchestrates all engines, executing scheduler -> qa -> pipeline -> monitor in sequence.
338
343
 
339
344
  ```bash
340
345
  sps tick <project> [project2] [project3] ... [--once] [--json] [--dry-run]
341
346
  ```
342
347
 
343
- **执行顺序（每轮 tick）：**
348
+ **Execution order (per tick cycle):**
344
349
 
345
- 1. **scheduler tick** — Planning → Backlog（选卡入队）
346
- 2. **qa tick** — QA → merge → Done（优先释放 Worker slot）
347
- 3. **pipeline tick** — Backlog → Todo → Inprogress（准备环境 + 启动 Worker）
348
- 4. **monitor tick** — 异常巡检与对齐
350
+ 1. **scheduler tick** -- Planning -> Backlog (select cards for queue)
351
+ 2. **qa tick** -- QA -> merge -> Done (prioritize freeing Worker slots)
352
+ 3. **pipeline tick** -- Backlog -> Todo -> Inprogress (prepare environment + launch Worker)
353
+ 4. **monitor tick** -- Anomaly inspection and alignment
349
354
 
350
- **运行模式：**
355
+ **Run modes:**
351
356
 
352
- | 模式 | 行为 |
353
- |------|------|
354
- | 持续模式（默认） | 每 30 秒循环一次，所有卡片完成后自动退出 |
355
- | 单次模式（`--once`） | 执行一轮 tick 后立即退出 |
357
+ | Mode | Behavior |
358
+ |------|----------|
359
+ | Continuous (default) | Cycles every 30 seconds, auto-exits when all cards are complete |
360
+ | Single-run (`--once`) | Executes one tick cycle then exits immediately |
356
361
 
357
- **并发互斥：**
362
+ **Concurrency mutex:**
358
363
 
359
- 同一项目同一时刻只允许一个 `tick` 实例运行。通过 `runtime/tick.lock`（PID + 时间戳）实现互斥，超过 `TICK_LOCK_TIMEOUT_MINUTES`（默认 30 分钟）视为死锁可强制接管。
364
+ Only one `tick` instance is allowed per project at any time. Mutex is implemented via `runtime/tick.lock` (PID + timestamp). Locks exceeding `TICK_LOCK_TIMEOUT_MINUTES` (default 30 minutes) are considered deadlocked and can be forcibly taken over.
360
365
 
361
- **失败分类：**
366
+ **Failure classification:**
362
367
 
363
- | 类型 | 行为 | 示例 |
364
- |------|------|------|
365
- | 致命失败 | 短路整个 tick | conf 损坏、PM 不可用 |
366
- | 降级继续 | 后续步骤有限运行 | scheduler 失败 → pipeline 不启动新卡 |
367
- | 非关键失败 | 记录后继续 | 通知发送失败 |
368
+ | Type | Behavior | Example |
369
+ |------|----------|---------|
370
+ | Fatal failure | Short-circuits the entire tick | Corrupted conf, PM unavailable |
371
+ | Degraded continuation | Subsequent steps run with limitations | Scheduler failure -> pipeline won't launch new cards |
372
+ | Non-critical failure | Logged and continued | Notification send failure |
368
373
 
369
- | 选项 | 说明 |
370
- |------|------|
371
- | `--once` | 单次执行后退出 |
372
- | `--json` | 输出 JSON 格式的聚合结果 |
373
- | `--dry-run` | 预览操作，不实际执行 |
374
+ | Option | Description |
375
+ |--------|-------------|
376
+ | `--once` | Exit after single execution |
377
+ | `--json` | Output aggregated results in JSON format |
378
+ | `--dry-run` | Preview actions without executing |
374
379
 
375
- **示例：**
380
+ **Example:**
376
381
 
377
382
  ```bash
378
- # 单项目持续运行
383
+ # Single project continuous run
379
384
  sps tick my-project
380
385
 
381
- # 多项目同时管理
386
+ # Multi-project simultaneous management
382
387
  sps tick project-a project-b project-c
383
388
 
384
- # 单次执行 + JSON 输出（适合 cron）
389
+ # Single execution + JSON output (suitable for cron)
385
390
  sps tick my-project --once --json
386
391
 
387
- # 预览模式
392
+ # Preview mode
388
393
  sps tick my-project --once --dry-run
389
394
  ```
390
395
 
391
- **JSON 输出格式：**
396
+ **JSON output format:**
392
397
 
393
398
  ```json
394
399
  {
@@ -397,29 +402,43 @@ sps tick my-project --once --dry-run
397
402
  "status": "ok",
398
403
  "exitCode": 0,
399
404
  "steps": [
400
- { "step": "scheduler", "status": "ok", "actions": [...] },
401
- { "step": "qa", "status": "ok", "actions": [...] },
402
- { "step": "pipeline", "status": "ok", "actions": [...] },
403
- { "step": "monitor", "status": "ok", "checks": [...] }
405
+ { "step": "scheduler", "status": "ok", "actions": ["..."] },
406
+ { "step": "qa", "status": "ok", "actions": ["..."] },
407
+ { "step": "pipeline", "status": "ok", "actions": ["..."] },
408
+ { "step": "monitor", "status": "ok", "checks": ["..."] }
404
409
  ]
405
410
  }
406
411
  ```
407
412
 
408
413
  ---
409
414
 
415
+ ### sps status
416
+
417
+ Show running status of all projects.
418
+
419
+ ```bash
420
+ sps status [--json]
421
+ ```
422
+
423
+ | Option | Description |
424
+ |--------|-------------|
425
+ | `--json` | Output structured JSON |
426
+
427
+ ---
428
+
410
429
  ### sps scheduler tick
411
430
 
412
- 手动执行编排步骤：Planning → Backlog。
431
+ Manually execute the scheduling step: Planning -> Backlog.
413
432
 
414
433
  ```bash
415
434
  sps scheduler tick <project> [--json] [--dry-run]
416
435
  ```
417
436
 
418
- - 读取 `pipeline_order.json` 确定卡片优先级
419
- - 检查准入条件（Worker 可用性、冲突域等）
420
- - 将符合条件的卡片从 Planning 推入 Backlog
437
+ - Reads `pipeline_order.json` to determine card priority
438
+ - Checks admission criteria (Worker availability, conflict domains, etc.)
439
+ - Moves eligible cards from Planning to Backlog
421
440
 
422
- **示例：**
441
+ **Example:**
423
442
 
424
443
  ```bash
425
444
  sps scheduler tick my-project
@@ -430,23 +449,23 @@ sps scheduler tick my-project --dry-run
430
449
 
431
450
  ### sps pipeline tick
432
451
 
433
- 手动执行执行链：Backlog → Todo → Inprogress。
452
+ Manually execute the execution chain: Backlog -> Todo -> Inprogress.
434
453
 
435
454
  ```bash
436
455
  sps pipeline tick <project> [--json] [--dry-run]
437
456
  ```
438
457
 
439
- **内部步骤：**
458
+ **Internal steps:**
440
459
 
441
- 1. **检查 Inprogress 卡片** — 检测 Worker 完成状态，MR_MODE=none 直接推入 Done，MR_MODE=create 确认 MR 后推入 Done
442
- 2. **处理 Backlog 卡片** — 创建分支 + 创建 worktree + 生成 `.sps/merge.sh` → 推入 Todo
443
- 3. **处理 Todo 卡片** — 分配 Worker slot + 构建任务上下文 + 启动 Worker → 推入 Inprogress
460
+ 1. **Check Inprogress cards** -- Detect Worker completion status. MR_MODE=none pushes directly to Done; MR_MODE=create confirms MR then pushes to Done
461
+ 2. **Process Backlog cards** -- Create branch + create worktree + generate `.sps/merge.sh` -> push to Todo
462
+ 3. **Process Todo cards** -- Assign Worker slot + build task context + launch Worker -> push to Inprogress
444
463
 
445
- 受 `MAX_ACTIONS_PER_TICK` 限制（默认 1），防止单轮 tick 同时启动过多 Worker。多个 Worker 启动之间有间隔（print 模式 2 秒，interactive 模式 10 秒）。
464
+ Limited by `MAX_ACTIONS_PER_TICK` (default 1) to prevent launching too many Workers in a single tick cycle. There is a delay between multiple Worker launches (2 seconds in print mode, 10 seconds in interactive mode).
446
465
 
447
- 带有 `BLOCKED`、`NEEDS-FIX`、`CONFLICT`、`WAITING-CONFIRMATION`、`STALE-RUNTIME` 标签的卡片会被跳过。
466
+ Cards with `BLOCKED`, `NEEDS-FIX`, `CONFLICT`, `WAITING-CONFIRMATION`, or `STALE-RUNTIME` labels are skipped.
448
467
 
449
- **示例：**
468
+ **Example:**
450
469
 
451
470
  ```bash
452
471
  sps pipeline tick my-project
@@ -457,68 +476,68 @@ sps pipeline tick my-project --json
457
476
 
458
477
  ### sps worker
459
478
 
460
- Worker 生命周期管理。
479
+ Worker lifecycle management.
461
480
 
462
481
  #### sps worker launch
463
482
 
464
- 手动启动单个 Worker。
483
+ Manually launch a single Worker.
465
484
 
466
485
  ```bash
467
486
  sps worker launch <project> <seq> [--json] [--dry-run]
468
487
  ```
469
488
 
470
- 如果卡片在 Backlog 状态，会自动先执行 prepare（创建分支 + worktree），然后启动 Worker。
489
+ If the card is in Backlog state, it will automatically execute prepare first (create branch + worktree), then launch the Worker.
471
490
 
472
- **启动流程：**
491
+ **Launch process:**
473
492
 
474
- 1. 分配空闲 Worker slot
475
- 2. 写入 `.sps/task_prompt.txt` 到 worktree
476
- 3. 启动 Worker 进程
477
- 4. 卡片推入 Inprogress
493
+ 1. Assign an available Worker slot
494
+ 2. Write `.sps/task_prompt.txt` to the worktree
495
+ 3. Launch Worker process
496
+ 4. Push card to Inprogress
478
497
 
479
- **Worker 执行模式（`WORKER_MODE`）：**
498
+ **Worker execution modes (`WORKER_MODE`):**
480
499
 
481
- | 模式 | 默认 | 说明 |
482
- |------|------|------|
483
- | `print` | **是** | 一次性执行，进程退出 = 任务完成，不依赖 tmux |
484
- | `interactive` | 否 | 传统 tmux TUI 交互模式（降级方案） |
500
+ | Mode | Default | Description |
501
+ |------|---------|-------------|
502
+ | `print` | **Yes** | One-shot execution, process exit = task complete, no tmux dependency |
503
+ | `interactive` | No | Traditional tmux TUI interactive mode (fallback) |
485
504
 
486
- **Print 模式（推荐）：**
505
+ **Print mode (recommended):**
487
506
 
488
- Worker 以子进程方式运行，prompt 通过 stdin 传入，输出写入 JSONL 文件：
507
+ The Worker runs as a subprocess, prompt is passed via stdin, output is written to a JSONL file:
489
508
 
490
509
  ```
491
510
  Claude: claude -p --output-format stream-json --dangerously-skip-permissions
492
511
  Codex: codex exec - --json --dangerously-bypass-approvals-and-sandbox
493
512
  ```
494
513
 
495
- 核心优势：
496
- - **不会卡住** — 无 TUI 交互，进程退出即完成
497
- - **不需要确认** — 权限参数跳过所有确认弹窗
498
- - **上下文延续** — 通过 `--resume <sessionId>` 实现跨任务上下文复用（命中 prompt cache，节省 token）
499
- - **不依赖 tmux** — 纯进程管理，适合 CI/CD 环境
514
+ Key advantages:
515
+ - **Never gets stuck** -- No TUI interaction, process exit means completion
516
+ - **No confirmation needed** -- Permission flags skip all confirmation dialogs
517
+ - **Context continuation** -- Via `--resume <sessionId>` for cross-task context reuse (hits prompt cache, saves tokens)
518
+ - **No tmux dependency** -- Pure process management, suitable for CI/CD environments
500
519
 
501
- **Session Resume 链：**
520
+ **Session Resume chain:**
502
521
 
503
- 同一 worktree 上的多次任务（初始实现 → CI 修复 → 冲突解决）共享同一个 session：
522
+ Multiple tasks on the same worktree (initial implementation -> CI fix -> conflict resolution) share the same session:
504
523
 
505
524
  ```
506
- 任务1: claude -p "实现功能" → session_id_1（存入 state.json）
507
- CI修复: claude -p "修复CI" --resume sid → 继承任务1的完整上下文
508
- 冲突: claude -p "解冲突" --resume sid → 继承所有历史上下文
525
+ Task 1: claude -p "Implement feature" -> session_id_1 (stored in state.json)
526
+ CI fix: claude -p "Fix CI" --resume sid -> Inherits full context from task 1
527
+ Conflict: claude -p "Resolve conflict" --resume sid -> Inherits all historical context
509
528
  ```
510
529
 
511
- **Interactive 模式（降级方案）：**
530
+ **Interactive mode (fallback):**
512
531
 
513
- 设置 `WORKER_MODE=interactive` 回退到 tmux 交互模式。此模式下复用策略：
532
+ Set `WORKER_MODE=interactive` to fall back to tmux interactive mode. Reuse strategy in this mode:
514
533
 
515
- | 场景 | 行为 |
516
- |------|------|
517
- | Session 存在 + Claude 运行中 | 复用：`/clear` + `cd worktree` |
518
- | Session 存在 + Claude 未运行 | 复用 session：`cd` + 启动 Claude |
519
- | 无 session | 创建新 session + 启动 Claude |
534
+ | Scenario | Behavior |
535
+ |----------|----------|
536
+ | Session exists + Claude running | Reuse: `/clear` + `cd worktree` |
537
+ | Session exists + Claude not running | Reuse session: `cd` + launch Claude |
538
+ | No session | Create new session + launch Claude |
520
539
 
521
- **示例：**
540
+ **Example:**
522
541
 
523
542
  ```bash
524
543
  sps worker launch my-project 24
@@ -527,43 +546,43 @@ sps worker launch my-project 24 --dry-run
527
546
 
528
547
  #### sps worker dashboard
529
548
 
530
- 实时监控所有 Worker 运行状态的仪表盘。
549
+ Real-time dashboard for monitoring all Worker running states.
531
550
 
532
551
  ```bash
533
552
  sps worker dashboard [project1] [project2] ... [--once] [--json]
534
553
  ```
535
554
 
536
- | 选项 | 说明 |
537
- |------|------|
538
- | （无参数） | 自动发现 `~/.coral/projects/` 下所有项目 |
539
- | `--once` | 输出一次快照后退出（不进入实时模式） |
540
- | `--json` | 输出 JSON 格式（所有项目、所有 Worker slot 状态 + 输出预览） |
555
+ | Option | Description |
556
+ |--------|-------------|
557
+ | (no arguments) | Auto-discovers all projects under `~/.coral/projects/` |
558
+ | `--once` | Output a single snapshot then exit (no real-time mode) |
559
+ | `--json` | Output in JSON format (all projects, all Worker slot states + output preview) |
541
560
 
542
- **实时模式：**
561
+ **Real-time mode:**
543
562
 
544
- - 默认每 3 秒刷新（可通过 `SPS_DASHBOARD_INTERVAL` 环境变量调整）
545
- - 按 `q` 退出，按 `r` 强制刷新
546
- - 使用 alternate screen buffer（不污染终端 scrollback）
547
- - 自适应网格布局，每个 Worker 一个面板
548
- - Print 模式面板显示：PID、exit code、JSONL 渲染后的可读输出
549
- - Interactive 模式面板显示：tmux pane 实时输出
563
+ - Refreshes every 3 seconds by default (adjustable via `SPS_DASHBOARD_INTERVAL` environment variable)
564
+ - Press `q` to quit, press `r` to force refresh
565
+ - Uses alternate screen buffer (does not pollute terminal scrollback)
566
+ - Adaptive grid layout, one panel per Worker
567
+ - Print mode panels show: PID, exit code, JSONL-rendered human-readable output
568
+ - Interactive mode panels show: tmux pane live output
550
569
 
551
- **示例：**
570
+ **Example:**
552
571
 
553
572
  ```bash
554
- # 监控所有项目
573
+ # Monitor all projects
555
574
  sps worker dashboard
556
575
 
557
- # 监控指定项目
576
+ # Monitor specific projects
558
577
  sps worker dashboard my-project
559
578
 
560
- # 单次快照
579
+ # Single snapshot
561
580
  sps worker dashboard --once
562
581
 
563
- # JSON 输出（供脚本消费）
582
+ # JSON output (for script consumption)
564
583
  sps worker dashboard --json
565
584
 
566
- # 自定义刷新间隔
585
+ # Custom refresh interval
567
586
  SPS_DASHBOARD_INTERVAL=5000 sps worker dashboard
568
587
  ```
569
588
 
@@ -571,38 +590,38 @@ SPS_DASHBOARD_INTERVAL=5000 sps worker dashboard
571
590
 
572
591
  ### sps pm
573
592
 
574
- PM 后端操作。
593
+ PM backend operations.
575
594
 
576
595
  #### sps pm scan
577
596
 
578
- 查看卡片列表。
597
+ View card list.
579
598
 
580
599
  ```bash
581
600
  sps pm scan <project> [state]
582
601
  ```
583
602
 
584
- 不指定 `state` 时列出所有卡片。
603
+ Lists all cards when `state` is not specified.
585
604
 
586
- **示例：**
605
+ **Example:**
587
606
 
588
607
  ```bash
589
- # 查看所有卡片
608
+ # View all cards
590
609
  sps pm scan my-project
591
610
 
592
- # 按状态筛选
611
+ # Filter by state
593
612
  sps pm scan my-project Inprogress
594
613
  sps pm scan my-project Planning
595
614
  ```
596
615
 
597
616
  #### sps pm move
598
617
 
599
- 手动移动卡片状态。
618
+ Manually move a card's state.
600
619
 
601
620
  ```bash
602
621
  sps pm move <project> <seq> <state>
603
622
  ```
604
623
 
605
- **示例：**
624
+ **Example:**
606
625
 
607
626
  ```bash
608
627
  sps pm move my-project 24 QA
@@ -611,38 +630,38 @@ sps pm move my-project 25 Done
611
630
 
612
631
  #### sps pm comment
613
632
 
614
- 给卡片添加评论。
633
+ Add a comment to a card.
615
634
 
616
635
  ```bash
617
636
  sps pm comment <project> <seq> "<text>"
618
637
  ```
619
638
 
620
- **示例：**
639
+ **Example:**
621
640
 
622
641
  ```bash
623
- sps pm comment my-project 24 "CI 已通过，等待 review"
642
+ sps pm comment my-project 24 "CI passed, awaiting review"
624
643
  ```
625
644
 
626
645
  #### sps pm checklist
627
646
 
628
- 管理卡片的检查清单。
647
+ Manage card checklists.
629
648
 
630
649
  ```bash
631
- # 创建清单
650
+ # Create checklist
632
651
  sps pm checklist create <project> <seq> "item1" "item2" "item3"
633
652
 
634
- # 查看清单
653
+ # View checklist
635
654
  sps pm checklist list <project> <seq>
636
655
 
637
- # 勾选/取消勾选
656
+ # Check/uncheck items
638
657
  sps pm checklist check <project> <seq> <item-id>
639
658
  sps pm checklist uncheck <project> <seq> <item-id>
640
659
  ```
641
660
 
642
- **示例：**
661
+ **Example:**
643
662
 
644
663
  ```bash
645
- sps pm checklist create my-project 24 "单元测试" "集成测试" "代码审查"
664
+ sps pm checklist create my-project 24 "Unit tests" "Integration tests" "Code review"
646
665
  sps pm checklist list my-project 24
647
666
  sps pm checklist check my-project 24 item-001
648
667
  ```
@@ -651,27 +670,27 @@ sps pm checklist check my-project 24 item-001
651
670
 
652
671
  ### sps qa tick
653
672
 
654
- QA 闭环与 worktree 清理。
673
+ QA close-out and worktree cleanup.
655
674
 
656
675
  ```bash
657
676
  sps qa tick <project> [--json]
658
677
  ```
659
678
 
660
- **MR_MODE=none 时：** QA 阶段主要负责 worktree 清理。Worker 完成后由 ExecutionEngine 直接推入 Done。
679
+ **When MR_MODE=none:** The QA phase primarily handles worktree cleanup. After Worker completion, the ExecutionEngine pushes directly to Done.
661
680
 
662
- **MR_MODE=create 时：** QA 作为遗留兼容路径，处理到达 QA 状态的卡片（自动创建 MR 或标记 `NEEDS-FIX`）。
681
+ **When MR_MODE=create:** QA serves as a legacy compatibility path, processing cards that reach QA state (auto-creates MR or tags `NEEDS-FIX`).
663
682
 
664
- **Worktree 自动清理：**
683
+ **Automatic worktree cleanup:**
665
684
 
666
- 每轮 qa tick 结束后，自动处理 `state.worktreeCleanup` 队列中的待清理项：
685
+ After each qa tick cycle, items in the `state.worktreeCleanup` queue are automatically processed:
667
686
 
668
- 1. `git worktree remove --force <path>` — 删除 worktree 目录
669
- 2. `git branch -d <branch>` — 删除已合并的本地分支
670
- 3. `git worktree prune` — 清理残留引用
687
+ 1. `git worktree remove --force <path>` -- Remove worktree directory
688
+ 2. `git branch -d <branch>` -- Delete merged local branch
689
+ 3. `git worktree prune` -- Clean up residual references
671
690
 
672
- 清理失败的条目保留在队列中，下轮 tick 自动重试。
691
+ Failed cleanup entries remain in the queue and are automatically retried in the next tick cycle.
673
692
 
674
- **示例：**
693
+ **Example:**
675
694
 
676
695
  ```bash
677
696
  sps qa tick my-project
@@ -682,23 +701,23 @@ sps qa tick my-project --json
682
701
 
683
702
  ### sps monitor tick
684
703
 
685
- 手动执行异常检测与健康巡检。
704
+ Manually execute anomaly detection and health inspection.
686
705
 
687
706
  ```bash
688
707
  sps monitor tick <project> [--json]
689
708
  ```
690
709
 
691
- **巡检项：**
710
+ **Inspection items:**
692
711
 
693
- | 检查 | 说明 |
694
- |------|------|
695
- | 孤儿 slot 清理 | 进程/tmux session 已死但 slot 仍标记 active |
696
- | 超时检测 | Inprogress 超过 `INPROGRESS_TIMEOUT_HOURS` |
697
- | 等待确认检测 | Worker 等待用户确认（仅 interactive 模式；print 模式无确认） |
698
- | 阻塞检测 | Worker 遇到 error/fatal/stuck 等（仅 interactive 模式） |
699
- | 状态对齐 | PM 状态与 runtime 状态是否一致 |
712
+ | Check | Description |
713
+ |-------|-------------|
714
+ | Orphan slot cleanup | Process/tmux session is dead but slot is still marked active |
715
+ | Timeout detection | Inprogress exceeds `INPROGRESS_TIMEOUT_HOURS` |
716
+ | Awaiting confirmation detection | Worker waiting for user confirmation (interactive mode only; print mode has no confirmations) |
717
+ | Block detection | Worker encountering error/fatal/stuck (interactive mode only) |
718
+ | State alignment | Whether PM state and runtime state are consistent |
700
719
 
701
- **示例：**
720
+ **Example:**
702
721
 
703
722
  ```bash
704
723
  sps monitor tick my-project
@@ -707,130 +726,130 @@ sps monitor tick my-project --json
707
726
 
708
727
  ---
709
728
 
710
- ## Worker 规则文件
729
+ ## Worker Rule Files
711
730
 
712
- `sps doctor --fix` 会在业务仓库根目录生成以下文件并自动提交：
731
+ `sps doctor --fix` generates the following files in the project repository root and auto-commits them:
713
732
 
714
- | 文件 | 用途 | 提交到 git |
715
- |------|------|-----------|
716
- | `CLAUDE.md` | Claude Code Worker 的项目规则 | 是 |
717
- | `AGENTS.md` | Codex Worker 的项目规则 | 是 |
718
- | `.sps/task_prompt.txt` | 每次任务的具体描述（每个 worktree 独立生成） | 否（.gitignore） |
719
- | `.sps/merge.sh` | 合并脚本（MR_MODE=none 时做 git merge，MR_MODE=create 时调 GitLab API 创建 MR） | 否（.gitignore） |
720
- | `docs/DECISIONS.md` | 项目知识库——架构决策和技术选择 | 是（Worker 自动维护） |
721
- | `docs/CHANGELOG.md` | 项目知识库——变更记录 | 是（Worker 自动维护） |
733
+ | File | Purpose | Committed to git |
734
+ |------|---------|-----------------|
735
+ | `CLAUDE.md` | Project rules for Claude Code Worker | Yes |
736
+ | `AGENTS.md` | Project rules for Codex Worker | Yes |
737
+ | `.sps/task_prompt.txt` | Specific task description per assignment (generated independently in each worktree) | No (.gitignore) |
738
+ | `.sps/merge.sh` | Merge script (git merge for MR_MODE=none, GitLab API MR creation for MR_MODE=create) | No (.gitignore) |
739
+ | `docs/DECISIONS.md` | Project knowledge base -- architecture decisions and technical choices | Yes (Worker auto-maintained) |
740
+ | `docs/CHANGELOG.md` | Project knowledge base -- change log | Yes (Worker auto-maintained) |
722
741
 
723
- **Skill Profile 注入（v0.16+）：**
742
+ **Skill Profile injection (v0.16+):**
724
743
 
725
- | 文件 | 用途 |
726
- |------|------|
727
- | `~/jarvis-skills/skills/worker-profiles/<name>.md` | 通过 `skill:<name>` 标签加载到 Worker prompt |
744
+ | File | Purpose |
745
+ |------|---------|
746
+ | `~/.coral/profiles/<name>.md` | Loaded into Worker prompt via `skill:<name>` label |
728
747
 
729
- Prompt 组装顺序：Skill Profile → CLAUDE.md/AGENTS.md → DECISIONS.md/CHANGELOG.md → 任务描述
748
+ Prompt assembly order: Skill Profile -> CLAUDE.md/AGENTS.md -> DECISIONS.md/CHANGELOG.md -> Task description
730
749
 
731
- ### 工作原理
750
+ ### How It Works
732
751
 
733
- 1. `CLAUDE.md` 和 `AGENTS.md` 提交到仓库主分支
734
- 2. 创建 git worktree 时自动继承这些文件
735
- 3. Worker 启动时读取 CLAUDE.md 了解项目规则（interactive 模式自动发现；print 模式在 cwd 中自动加载）
736
- 4. 任务特有信息（seq、分支名、描述）写入 `.sps/task_prompt.txt`，通过 stdin 传给 Worker（print 模式）或通过 tmux paste 传入（interactive 模式）
737
- 5. `.sps/merge.sh` 在每个 worktree 中自动生成，Worker 在 push 后运行此脚本完成合并或 MR 创建
752
+ 1. `CLAUDE.md` and `AGENTS.md` are committed to the repository's main branch
753
+ 2. When creating a git worktree, these files are automatically inherited
754
+ 3. On startup, the Worker reads CLAUDE.md to understand project rules (auto-discovered in interactive mode; auto-loaded from cwd in print mode)
755
+ 4. Task-specific information (seq, branch name, description) is written to `.sps/task_prompt.txt`, passed to the Worker via stdin (print mode) or tmux paste (interactive mode)
756
+ 5. `.sps/merge.sh` is auto-generated in each worktree. After pushing, the Worker runs this script to complete the merge or MR creation
738
757
 
739
- ### 项目知识库
758
+ ### Project Knowledge Base
740
759
 
741
- 每个 Worker 在任务 prompt 中被要求：
760
+ Each Worker is instructed in the task prompt to:
742
761
 
743
- - **开始前**：阅读 `docs/DECISIONS.md` 和 `docs/CHANGELOG.md`，了解前序任务的决策和变更
744
- - **完成后**：将自己的架构决策追加到 `docs/DECISIONS.md`，变更摘要追加到 `docs/CHANGELOG.md`
762
+ - **Before starting**: Read `docs/DECISIONS.md` and `docs/CHANGELOG.md` to understand decisions and changes from preceding tasks
763
+ - **After completion**: Append their architecture decisions to `docs/DECISIONS.md` and change summaries to `docs/CHANGELOG.md`
745
764
 
746
- 这些文件随代码一起合并到目标分支，下一个 Worker 创建 worktree 时自动继承，实现跨任务的知识传递。
765
+ These files are merged with the code into the target branch. The next Worker inherits them when creating a worktree, enabling cross-task knowledge transfer.
747
766
 
748
- ### 自定义项目规则
767
+ ### Customizing Project Rules
749
768
 
750
- 生成的 CLAUDE.md 包含"Project-Specific Rules"占位区，你可以在此添加：
769
+ The generated CLAUDE.md includes a "Project-Specific Rules" placeholder section where you can add:
751
770
 
752
771
  ```markdown
753
772
  ## Project-Specific Rules
754
- - 语言：TypeScript strict mode
755
- - 测试框架：vitest，覆盖率 80%+
756
- - 架构：src/modules/<domain>/ 目录结构
757
- - Linting：eslint + prettier，提交前必须通过
773
+ - Language: TypeScript strict mode
774
+ - Test framework: vitest, coverage 80%+
775
+ - Architecture: src/modules/<domain>/ directory structure
776
+ - Linting: eslint + prettier, must pass before commit
758
777
  ```
759
778
 
760
- SPS 不会覆盖已存在的 CLAUDE.md / AGENTS.md。
779
+ SPS will not overwrite existing CLAUDE.md / AGENTS.md files.
761
780
 
762
781
  ---
763
782
 
764
- ## 项目配置
783
+ ## Project Configuration
765
784
 
766
- 配置分两层：
785
+ Configuration is split into two layers:
767
786
 
768
- | 文件 | 作用域 | 说明 |
769
- |------|-------|------|
770
- | `~/.coral/env` | 全局 | 所有项目共享的凭据（GitLab token、PM API key 等） |
771
- | `~/.coral/projects/<project>/conf` | 项目级 | 项目特有配置（仓库、分支、Worker 参数等） |
787
+ | File | Scope | Description |
788
+ |------|-------|-------------|
789
+ | `~/.coral/env` | Global | Credentials shared across all projects (GitLab token, PM API key, etc.) |
790
+ | `~/.coral/projects/<project>/conf` | Project | Project-specific configuration (repository, branch, Worker parameters, etc.) |
772
791
 
773
- 项目 conf 可以引用全局变量（如 `${PLANE_URL}`）。
792
+ Project conf can reference global variables (e.g., `${PLANE_URL}`).
774
793
 
775
- ### 配置字段一览
794
+ ### Configuration Field Reference
776
795
 
777
- #### 项目基础
796
+ #### Project Basics
778
797
 
779
- | 字段 | 必填 | 默认值 | 说明 |
780
- |------|------|-------|------|
781
- | `PROJECT_NAME` | 是 | — | 项目名称 |
782
- | `PROJECT_DISPLAY` | 否 | PROJECT_NAME | 显示名称 |
783
- | `PROJECT_DIR` | 否 | `~/projects/<project>` | 业务仓库路径 |
798
+ | Field | Required | Default | Description |
799
+ |-------|----------|---------|-------------|
800
+ | `PROJECT_NAME` | Yes | -- | Project name |
801
+ | `PROJECT_DISPLAY` | No | PROJECT_NAME | Display name |
802
+ | `PROJECT_DIR` | No | `~/projects/<project>` | Project repository path |
784
803
 
785
804
  #### GitLab
786
805
 
787
- | 字段 | 必填 | 默认值 | 说明 |
788
- |------|------|-------|------|
789
- | `GITLAB_PROJECT` | 是 | — | GitLab 项目路径（如 `group/repo`） |
790
- | `GITLAB_PROJECT_ID` | 是 | — | GitLab 项目数字 ID |
791
- | `GITLAB_MERGE_BRANCH` | 是 | `develop` | MR 目标分支 |
792
- | `GITLAB_RELEASE_BRANCH` | 否 | `main` | 发布分支 |
806
+ | Field | Required | Default | Description |
807
+ |-------|----------|---------|-------------|
808
+ | `GITLAB_PROJECT` | Yes | -- | GitLab project path (e.g., `group/repo`) |
809
+ | `GITLAB_PROJECT_ID` | Yes | -- | GitLab project numeric ID |
810
+ | `GITLAB_MERGE_BRANCH` | Yes | `develop` | MR target branch |
811
+ | `GITLAB_RELEASE_BRANCH` | No | `main` | Release branch |
793
812
 
794
- #### PM 后端
813
+ #### PM Backend
795
814
 
796
- | 字段 | 必填 | 默认值 | 说明 |
797
- |------|------|-------|------|
798
- | `PM_TOOL` | 否 | `trello` | PM 后端类型：`plane` / `trello` / `markdown` |
799
- | `PIPELINE_LABEL` | 否 | `AI-PIPELINE` | Pipeline 卡片标签 |
800
- | `MR_MODE` | 否 | `none` | 合并模式：`none`（直接合并到目标分支） / `create`（创建 MR，审核流程待开发） |
815
+ | Field | Required | Default | Description |
816
+ |-------|----------|---------|-------------|
817
+ | `PM_TOOL` | No | `trello` | PM backend type: `plane` / `trello` / `markdown` |
818
+ | `PIPELINE_LABEL` | No | `AI-PIPELINE` | Pipeline card label |
819
+ | `MR_MODE` | No | `none` | Merge mode: `none` (direct merge to target branch) / `create` (create MR, review flow under development) |
801
820
 
802
821
  #### Worker
803
822
 
804
- | 字段 | 必填 | 默认值 | 说明 |
805
- |------|------|-------|------|
806
- | `WORKER_TOOL` | 否 | `claude` | Worker 类型：`claude` / `codex` |
807
- | `WORKER_MODE` | 否 | `print` | 执行模式：`print`（一次性进程） / `interactive`（tmux TUI） |
808
- | `MAX_CONCURRENT_WORKERS` | 否 | `3` | 最大并行 Worker 数 |
809
- | `WORKER_RESTART_LIMIT` | 否 | `2` | Worker 死亡后最大重启次数 |
810
- | `AUTOFIX_ATTEMPTS` | 否 | `2` | CI 失败自动修复尝试次数 |
811
- | `WORKER_SESSION_REUSE` | 否 | `true` | 是否复用 tmux session（仅 interactive 模式） |
812
- | `MAX_ACTIONS_PER_TICK` | 否 | `1` | 每轮 tick 最大操作数 |
813
-
814
- #### 超时与策略
815
-
816
- | 字段 | 必填 | 默认值 | 说明 |
817
- |------|------|-------|------|
818
- | `INPROGRESS_TIMEOUT_HOURS` | 否 | `8` | Inprogress 超时小时数 |
819
- | `MONITOR_AUTO_QA` | 否 | `false` | Monitor 是否自动将完成的卡推入 QA |
820
- | `CONFLICT_DEFAULT` | 否 | `serial` | 冲突域默认策略：`serial` / `parallel` |
821
- | `TICK_LOCK_TIMEOUT_MINUTES` | 否 | `30` | tick 锁超时分钟数 |
822
- | `NEEDS_FIX_MAX_RETRIES` | 否 | `3` | NEEDS-FIX 最大重试次数 |
823
- | `WORKTREE_RETAIN_HOURS` | 否 | `24` | worktree 保留小时数 |
824
-
825
- #### 路径与部署
826
-
827
- | 字段 | 必填 | 默认值 | 说明 |
828
- |------|------|-------|------|
829
- | `WORKTREE_DIR` | 否 | `~/.coral/worktrees/` | worktree 根目录 |
830
- | `DEPLOY_ENABLED` | 否 | `false` | 是否启用自动部署 |
831
- | `DEPLOY_SCRIPT` | 否 | — | 部署脚本路径 |
832
-
833
- ### 配置示例
823
+ | Field | Required | Default | Description |
824
+ |-------|----------|---------|-------------|
825
+ | `WORKER_TOOL` | No | `claude` | Worker type: `claude` / `codex` |
826
+ | `WORKER_MODE` | No | `print` | Execution mode: `print` (one-shot process) / `interactive` (tmux TUI) |
827
+ | `MAX_CONCURRENT_WORKERS` | No | `3` | Maximum parallel Workers |
828
+ | `WORKER_RESTART_LIMIT` | No | `2` | Maximum restart count after Worker death |
829
+ | `AUTOFIX_ATTEMPTS` | No | `2` | CI failure auto-fix attempt count |
830
+ | `WORKER_SESSION_REUSE` | No | `true` | Whether to reuse tmux sessions (interactive mode only) |
831
+ | `MAX_ACTIONS_PER_TICK` | No | `1` | Maximum actions per tick cycle |
832
+
833
+ #### Timeouts and Policies
834
+
835
+ | Field | Required | Default | Description |
836
+ |-------|----------|---------|-------------|
837
+ | `INPROGRESS_TIMEOUT_HOURS` | No | `8` | Inprogress timeout in hours |
838
+ | `MONITOR_AUTO_QA` | No | `false` | Whether Monitor auto-pushes completed cards to QA |
839
+ | `CONFLICT_DEFAULT` | No | `serial` | Default conflict domain strategy: `serial` / `parallel` |
840
+ | `TICK_LOCK_TIMEOUT_MINUTES` | No | `30` | Tick lock timeout in minutes |
841
+ | `NEEDS_FIX_MAX_RETRIES` | No | `3` | Maximum NEEDS-FIX retry count |
842
+ | `WORKTREE_RETAIN_HOURS` | No | `24` | Worktree retention in hours |
843
+
844
+ #### Paths and Deployment
845
+
846
+ | Field | Required | Default | Description |
847
+ |-------|----------|---------|-------------|
848
+ | `WORKTREE_DIR` | No | `~/.coral/worktrees/` | Worktree root directory |
849
+ | `DEPLOY_ENABLED` | No | `false` | Whether to enable auto-deployment |
850
+ | `DEPLOY_SCRIPT` | No | -- | Deployment script path |
851
+
852
+ ### Configuration Example
834
853
 
835
854
  ```bash
836
855
  # ~/.coral/projects/my-project/conf
@@ -844,86 +863,86 @@ GITLAB_PROJECT="team/my-project"
844
863
  GITLAB_PROJECT_ID="42"
845
864
  GITLAB_MERGE_BRANCH="develop"
846
865
 
847
- # PM（使用全局 .coral/env 中的变量）
866
+ # PM (uses variables from global ~/.coral/env)
848
867
  PM_TOOL="plane"
849
868
  PLANE_API_URL="${PLANE_URL}"
850
869
  PLANE_PROJECT_ID="project-uuid-here"
851
870
 
852
871
  # Worker
853
872
  WORKER_TOOL="claude"
854
- WORKER_MODE="print" # print（推荐）或 interactive（tmux 降级）
873
+ WORKER_MODE="print" # print (recommended) or interactive (tmux fallback)
855
874
  MAX_CONCURRENT_WORKERS=3
856
875
  MAX_ACTIONS_PER_TICK=1
857
876
 
858
- # 合并模式
859
- MR_MODE="none" # none（直接合并）或 create（创建 MR）
877
+ # Merge mode
878
+ MR_MODE="none" # none (direct merge) or create (create MR)
860
879
  ```
861
880
 
862
881
  ---
863
882
 
864
- ## 多项目并行
883
+ ## Multi-Project Parallel Execution
865
884
 
866
- SPS 支持单进程同时管理多个项目：
885
+ SPS supports managing multiple projects simultaneously in a single process:
867
886
 
868
887
  ```bash
869
888
  sps tick project-a project-b project-c
870
889
  ```
871
890
 
872
- 每个项目完全隔离：
873
- - 独立的 ProjectContext、Provider 实例、Engine 实例
874
- - 独立的 tick.lock（互不阻塞）
875
- - 独立的 state.json（Worker slot 不混淆）
876
- - 一个项目出错不影响其他项目
891
+ Each project is fully isolated:
892
+ - Independent ProjectContext, Provider instances, Engine instances
893
+ - Independent tick.lock (non-blocking between projects)
894
+ - Independent state.json (Worker slots are not mixed)
895
+ - Errors in one project do not affect others
877
896
 
878
- 多 Worker 并行配置：
897
+ Multi-Worker parallel configuration:
879
898
 
880
899
  ```bash
881
- # 在项目 conf 中设置
900
+ # Set in project conf
882
901
  MAX_CONCURRENT_WORKERS=3
883
902
  CONFLICT_DEFAULT=parallel
884
903
  ```
885
904
 
886
905
  ---
887
906
 
888
- ## 架构概览
907
+ ## Architecture Overview
889
908
 
890
- ### 四层架构
909
+ ### Four-Layer Architecture
891
910
 
892
911
  ```
893
- Layer 3 Commands + Engines CLI 命令 + 状态机引擎
894
- Layer 2 Providers 具体后端实现
895
- Layer 1 Interfaces 抽象接口
896
- Layer 0 Core Runtime 配置、路径、状态、锁、日志
912
+ Layer 3 Commands + Engines CLI commands + state machine engines
913
+ Layer 2 Providers Concrete backend implementations
914
+ Layer 1 Interfaces Abstract interfaces
915
+ Layer 0 Core Runtime Configuration, paths, state, locks, logging
897
916
  ```
898
917
 
899
- ### 支持的后端
918
+ ### Supported Backends
900
919
 
901
- | 类型 | Provider | 接口 |
902
- |------|----------|------|
903
- | PM 后端 | Plane CE / Trello / Markdown | TaskBackend |
904
- | 代码托管 | GitLab | RepoBackend |
920
+ | Type | Provider | Interface |
921
+ |------|----------|-----------|
922
+ | PM Backend | Plane CE / Trello / Markdown | TaskBackend |
923
+ | Code Hosting | GitLab | RepoBackend |
905
924
  | AI Worker (print) | ClaudePrintProvider / CodexExecProvider | WorkerProvider |
906
925
  | AI Worker (interactive) | ClaudeTmuxProvider / CodexTmuxProvider | WorkerProvider |
907
- | 通知 | Matrix | Notifier |
926
+ | Notifications | Matrix | Notifier |
908
927
 
909
- ### 引擎
928
+ ### Engines
910
929
 
911
- | 引擎 | 职责 |
912
- |------|------|
913
- | SchedulerEngine | Planning → Backlog（选卡、排序、准入检查） |
914
- | ExecutionEngine | Backlog → Todo → Inprogress → Done（准备环境、启动 Worker、检测完成、释放资源） |
915
- | CloseoutEngine | worktree 清理（MR_MODE=create 时兼容处理 QA 卡片） |
916
- | MonitorEngine | 异常检测（孤儿清理、超时、阻塞、状态对齐、死亡 Worker 完成检测） |
930
+ | Engine | Responsibility |
931
+ |--------|---------------|
932
+ | SchedulerEngine | Planning -> Backlog (card selection, sorting, admission checks) |
933
+ | ExecutionEngine | Backlog -> Todo -> Inprogress -> Done (prepare environment, launch Worker, detect completion, release resources) |
934
+ | CloseoutEngine | Worktree cleanup (legacy QA card handling when MR_MODE=create) |
935
+ | MonitorEngine | Anomaly detection (orphan cleanup, timeouts, blocks, state alignment, dead Worker completion detection) |
917
936
 
918
937
  ---
919
938
 
920
- ## 目录结构
939
+ ## Directory Structure
921
940
 
922
941
  ```
923
942
  workflow-cli/
924
943
  ├── src/
925
- │ ├── main.ts # CLI 入口、命令路由
926
- │ ├── commands/ # 命令实现
944
+ │ ├── main.ts # CLI entry point, command routing
945
+ │ ├── commands/ # Command implementations
927
946
  │ │ ├── setup.ts # sps setup
928
947
  │ │ ├── projectInit.ts # sps project init
929
948
  │ │ ├── doctor.ts # sps doctor
@@ -936,45 +955,45 @@ workflow-cli/
936
955
  │ │ ├── pmCommand.ts # sps pm *
937
956
  │ │ ├── qaTick.ts # sps qa tick
938
957
  │ │ └── monitorTick.ts # sps monitor tick
939
- │ ├── core/ # 核心运行时
940
- │ │ ├── config.ts # 配置加载（shell conf 解析）
958
+ │ ├── core/ # Core runtime
959
+ │ │ ├── config.ts # Configuration loading (shell conf parsing)
941
960
  │ │ ├── context.ts # ProjectContext
942
- │ │ ├── paths.ts # 路径解析
943
- │ │ ├── state.ts # 运行时状态（state.json）
944
- │ │ ├── lock.ts # tick 锁
945
- │ │ ├── logger.ts # 日志 + 结构化事件
946
- │ │ └── queue.ts # Pipeline 队列
947
- │ ├── engines/ # 状态机引擎
948
- │ │ ├── SchedulerEngine.ts # 选卡入队
949
- │ │ ├── ExecutionEngine.ts # 执行链
950
- │ │ ├── CloseoutEngine.ts # QA 闭环
951
- │ │ └── MonitorEngine.ts # 异常检测
952
- │ ├── manager/ # Worker 进程管理模块（v0.16.0）
953
- │ │ ├── supervisor.ts # fd 重定向 spawn, child handle, exit 回调
954
- │ │ ├── completion-judge.ts # git 产出检查, marker/keyword 检测
961
+ │ │ ├── paths.ts # Path resolution
962
+ │ │ ├── state.ts # Runtime state (state.json)
963
+ │ │ ├── lock.ts # Tick lock
964
+ │ │ ├── logger.ts # Logging + structured events
965
+ │ │ └── queue.ts # Pipeline queue
966
+ │ ├── engines/ # State machine engines
967
+ │ │ ├── SchedulerEngine.ts # Card selection and queuing
968
+ │ │ ├── ExecutionEngine.ts # Execution chain
969
+ │ │ ├── CloseoutEngine.ts # QA close-out
970
+ │ │ └── MonitorEngine.ts # Anomaly detection
971
+ │ ├── manager/ # Worker process management module (v0.16.0)
972
+ │ │ ├── supervisor.ts # fd-redirected spawn, child handle, exit callbacks
973
+ │ │ ├── completion-judge.ts # git output checks, marker/keyword detection
955
974
  │ │ ├── post-actions.ts # merge + PM update + slot release + notify
956
- │ │ ├── pm-client.ts # 轻量 PM 操作 (Plane/Trello/Markdown)
957
- │ │ ├── resource-limiter.ts # 全局 worker 数上限 + 内存检查
958
- │ │ └── recovery.ts # tick 重启后 PID 扫描恢复
959
- │ ├── interfaces/ # 抽象接口
960
- │ │ ├── TaskBackend.ts # PM 后端接口
961
- │ │ ├── WorkerProvider.ts # Worker 接口
962
- │ │ ├── RepoBackend.ts # 代码仓库接口
963
- │ │ ├── Notifier.ts # 通知接口
964
- │ │ └── HookProvider.ts # Hook 接口
965
- │ ├── models/ # 类型定义
966
- │ │ └── types.ts # Card, CommandResult, WorkerStatus 等
967
- │ └── providers/ # 具体实现
968
- │ ├── registry.ts # Provider 工厂（按 WORKER_MODE × WORKER_TOOL 路由）
975
+ │ │ ├── pm-client.ts # Lightweight PM operations (Plane/Trello/Markdown)
976
+ │ │ ├── resource-limiter.ts # Global worker count cap + memory checks
977
+ │ │ └── recovery.ts # Post-restart PID scan recovery
978
+ │ ├── interfaces/ # Abstract interfaces
979
+ │ │ ├── TaskBackend.ts # PM backend interface
980
+ │ │ ├── WorkerProvider.ts # Worker interface
981
+ │ │ ├── RepoBackend.ts # Code repository interface
982
+ │ │ ├── Notifier.ts # Notification interface
983
+ │ │ └── HookProvider.ts # Hook interface
984
+ │ ├── models/ # Type definitions
985
+ │ │ └── types.ts # Card, CommandResult, WorkerStatus, etc.
986
+ │ └── providers/ # Concrete implementations
987
+ │ ├── registry.ts # Provider factory (routes by WORKER_MODE x WORKER_TOOL)
969
988
  │ ├── PlaneTaskBackend.ts
970
989
  │ ├── TrelloTaskBackend.ts
971
990
  │ ├── MarkdownTaskBackend.ts
972
- │ ├── ClaudePrintProvider.ts # claude -p 一次性执行（默认）
973
- │ ├── CodexExecProvider.ts # codex exec 一次性执行（默认）
974
- │ ├── ClaudeTmuxProvider.ts # tmux 交互模式（降级方案）
975
- │ ├── CodexTmuxProvider.ts # tmux 交互模式（降级方案）
976
- │ ├── outputParser.ts # JSONL 输出解析、进程管理工具
977
- │ ├── streamRenderer.ts # JSONL → 人类可读文本（Dashboard 用）
991
+ │ ├── ClaudePrintProvider.ts # claude -p one-shot execution (default)
992
+ │ ├── CodexExecProvider.ts # codex exec one-shot execution (default)
993
+ │ ├── ClaudeTmuxProvider.ts # tmux interactive mode (fallback)
994
+ │ ├── CodexTmuxProvider.ts # tmux interactive mode (fallback)
995
+ │ ├── outputParser.ts # JSONL output parsing, process management utilities
996
+ │ ├── streamRenderer.ts # JSONL -> human-readable text (for Dashboard)
978
997
  │ ├── GitLabRepoBackend.ts
979
998
  │ └── MatrixNotifier.ts
980
999
  ├── package.json
@@ -983,50 +1002,50 @@ workflow-cli/
983
1002
 
984
1003
  ---
985
1004
 
986
- ## Manager 模块 (v0.16.0)
1005
+ ## Manager Module (v0.16.0)
987
1006
 
988
- v0.16.0 新增 `src/manager/` 目录，将 Worker 进程管理从 Engine 中解耦为独立模块，作为 tick 内部模块运行（非独立守护进程）。
1007
+ v0.16.0 introduced the `src/manager/` directory, decoupling Worker process management from Engines into independent modules that run as internal tick modules (not standalone daemons).
989
1008
 
990
- | 模块 | 行数 | 职责 |
991
- |------|------|------|
992
- | `supervisor.ts` | 288 | fd 重定向 spawn（OS 级保证 output 写入），持有 child handle，exit 回调触发后置流程，三层环境变量合并（系统→全局凭据→项目配置） |
993
- | `completion-judge.ts` | 110 | git 产出检查（分支是否已推送/已合并），auto-push，marker 文件检测，完成关键词匹配 |
994
- | `post-actions.ts` | 412 | Worker 退出后完整后置链：merge → PM 状态更新 → slot 释放 → 通知 |
995
- | `pm-client.ts` | 294 | 轻量 PM 操作封装，支持 Plane/Trello/Markdown 三种后端 |
996
- | `resource-limiter.ts` | 103 | 全局 worker 数上限检查 + 内存检查 + 启动间隔控制 |
997
- | `recovery.ts` | 205 | tick 重启后通过 PID 扫描恢复 orphan worker 进程 |
1009
+ | Module | Lines | Responsibility |
1010
+ |--------|-------|---------------|
1011
+ | `supervisor.ts` | 288 | fd-redirected spawn (OS-level guaranteed output writing), holds child handle, exit callback triggers post-processing, three-layer env var merging (system -> global credentials -> project config) |
1012
+ | `completion-judge.ts` | 110 | git output checks (branch pushed/merged), auto-push, marker file detection, completion keyword matching |
1013
+ | `post-actions.ts` | 412 | Complete post-Worker-exit chain: merge -> PM state update -> slot release -> notify |
1014
+ | `pm-client.ts` | 294 | Lightweight PM operation wrapper, supports Plane/Trello/Markdown backends |
1015
+ | `resource-limiter.ts` | 103 | Global worker count cap check + memory check + launch interval control |
1016
+ | `recovery.ts` | 205 | Post-tick-restart PID scan to recover orphan worker processes |
998
1017
 
999
- **改造效果：**
1000
- - ExecutionEngine 从 1219 行缩减至 916 行（删除 attemptResume, completeAndRelease）
1001
- - MonitorEngine 从 974 行缩减至 750 行（删除直接 PID/tmux 检测）
1002
- - tick.ts 新增约 80 行（初始化共享 Manager 模块，启动时执行 Recovery）
1018
+ **Refactoring results:**
1019
+ - ExecutionEngine reduced from 1219 to 916 lines (removed attemptResume, completeAndRelease)
1020
+ - MonitorEngine reduced from 974 to 750 lines (removed direct PID/tmux detection)
1021
+ - tick.ts added ~80 lines (initialize shared Manager modules, run Recovery on startup)
1003
1022
 
1004
1023
  ---
1005
1024
 
1006
- ## 标签技能注入 (v0.16.0)
1025
+ ## Label-Driven Skill Injection (v0.16.0)
1007
1026
 
1008
- 通过 PM 卡片标签驱动 Worker 专业能力注入，无需修改代码即可为不同任务定制 Worker 行为。
1027
+ Worker expertise is injected via PM card labels, allowing customization of Worker behavior for different tasks without code changes.
1009
1028
 
1010
- **机制：**
1011
- - PM 卡片添加 `skill:xxx` 标签 → 自动加载 `skills/worker-profiles/xxx.md` 到 Worker prompt
1012
- - 支持多个 `skill:` 标签叠加注入
1013
- - 项目可通过 `DEFAULT_WORKER_SKILLS` 配置默认技能，卡片标签可覆盖项目默认
1029
+ **Mechanism:**
1030
+ - Adding a `skill:xxx` label to a PM card -> automatically loads `~/.coral/profiles/xxx.md` into the Worker prompt
1031
+ - Multiple `skill:` labels can be stacked for combined injection
1032
+ - Projects can configure default skills via `DEFAULT_WORKER_SKILLS`; card labels override project defaults
1014
1033
 
1015
- **Prompt 组装顺序：**
1016
- 1. Skill Profiles（技能模板）
1017
- 2. Project Rules（CLAUDE.md / AGENTS.md）
1018
- 3. Project Knowledge（docs/DECISIONS.md, docs/CHANGELOG.md）
1019
- 4. Task（.sps/task_prompt.txt）
1034
+ **Prompt assembly order:**
1035
+ 1. Skill Profiles (skill templates)
1036
+ 2. Project Rules (CLAUDE.md / AGENTS.md)
1037
+ 3. Project Knowledge (docs/DECISIONS.md, docs/CHANGELOG.md)
1038
+ 4. Task (.sps/task_prompt.txt)
1020
1039
 
1021
- **内置技能模板：**
1040
+ **Built-in skill templates:**
1022
1041
 
1023
- | 文件 | 用途 |
1024
- |------|------|
1025
- | `skills/worker-profiles/_template.md` | 创建新技能的模板 |
1026
- | `skills/worker-profiles/typescript.md` | TypeScript 项目编码规范 |
1027
- | `skills/worker-profiles/phaser.md` | Phaser 游戏框架开发指南 |
1042
+ | File | Purpose |
1043
+ |------|---------|
1044
+ | `~/.coral/profiles/_template.md` | Template for creating new skills |
1045
+ | `~/.coral/profiles/typescript.md` | TypeScript project coding standards |
1046
+ | `~/.coral/profiles/phaser.md` | Phaser game framework development guide |
1028
1047
 
1029
- **新增技能零代码：** 只需创建 md 文件到 `skills/worker-profiles/` 目录，然后在 PM 卡片上添加对应的 `skill:xxx` 标签即可。
1048
+ **Adding new skills requires zero code:** Simply create an md file in `~/.coral/profiles/` directory, then add the corresponding `skill:xxx` label to the PM card.
1030
1049
 
1031
1050
  ---
1032
1051