@coralai/sps-cli 0.58.35 → 0.58.37

package/skills/sps-pipeline/SKILL.md

@@ -1,62 +1,37 @@
 ---
 name: sps-pipeline
-description: |
+description: >
   SPS pipeline & project management — set up projects, configure YAML pipelines, manage
-  task cards, drive worker lifecycle, run web console, monitor health. Use when the user
-  asks to "create a pipeline", "set up a project", "add tasks", "start the pipeline",
-  "open console", "check status", or anything in the SPS workflow. (🪸 Coral SPS)
+  task cards, drive worker lifecycle, run web console. Use when the user asks to "create a
+  pipeline", "set up a project", "add tasks", "start the pipeline", "open console", "check
+  status", or anything in the SPS workflow. (🪸 Coral SPS)
+category: platform
 ---
 
-# SPS Pipeline (v0.51.x — Single-Worker Card Pipeline + Web Console + Wiki)
+# SPS Pipeline
 
 SPS drives an AI worker through task cards. **One worker, one card at a time, serial
 execution.** Each card walks one or more YAML-defined stages (e.g. `develop → review →
-Done`); failure halts until the user resolves it. v0.50 added a 4-layer service
-architecture; v0.51 added per-project Wiki knowledge base injection.
+Done`); failure halts until the user resolves it.
+
+This file is the operating SOP (create project · manage cards · run the pipeline).
+Deeper reference material lives in `references/` — see the index at the bottom.
 
 ## Two ways to operate
 
 | Mode | Command | Use when |
 |---|---|---|
-| **Web Console** (preferred) | `sps console` | Daily work — kanban, logs, worker dashboard, project create, conf editor, pipeline editor, chat with agent, all in one UI |
-| **CLI** | `sps tick / card / worker / wiki / …` | Scripting, troubleshooting, headless servers |
-
-Console listens on `127.0.0.1:4311` by default; opens browser auto. Single-instance
-guard via `~/.coral/console.lock`.
-
----
-
-## 1. First-time setup
-
-```bash
-npm install -g @coralai/sps-cli      # latest (currently 0.51.x)
-sps setup                            # ⭐ MUST RUN: interactive wizard
-```
-
-`sps setup` does:
-1. Creates `~/.coral/` directory tree (`projects/`, `memory/user/`, `memory/agents/`).
-2. Copies bundled skills → `~/.coral/skills/`.
-3. Interactively writes `~/.coral/env` (Git remote token, Matrix credentials, etc.).
-4. Symlinks user skills → `~/.coral/.claude/skills/` and `~/.claude/skills/`.
-5. Installs `@agentclientprotocol/claude-agent-acp` globally if missing.
+| **Web Console** (preferred) | `sps console` | Daily work — kanban, logs, worker dashboard, project create, conf/pipeline editor, chat with agent |
+| **CLI** | `sps tick / card / worker / …` | Scripting, troubleshooting, headless servers |
 
-Re-run safe: `sps setup --force` keeps existing values as defaults.
+First time on a machine? Run `sps setup` once — see `references/setup-and-config.md`.
 
-**No separate console config**. Console reads `~/.coral/env` + per-project conf.
-
----
+## Create a project
 
-## 2. Create a project
+**Console (recommended):** `sps console` → `/projects/new` → fill form (git toggle,
+清单验收 toggle, wiki toggle, merge branch…) → submit.
 
-### Option A — Console (recommended)
-Open `sps console` → `/projects/new` → fill form → submit. Form provides:
-- Project name + repo path
-- Git toggle (worker commits + pushes? off for non-code projects)
-- **清单验收 toggle**: 开启 → conf 写 `SPS_REVIEW="on"`,每卡完成后独立 reviewer 按检查清单逐条验收
-- **Wiki toggle** (v0.51+): scaffolds `wiki/` + writes `WIKI_ENABLED=true` to conf
-- Merge branch, max workers, ACK timeout, Matrix room
-
-### Option B — CLI
+**CLI:**
 ```bash
 # 人在终端:交互式向导(含「启用清单验收? (y/N)」一问)
 sps project init <name>
@@ -69,462 +44,90 @@ sps project init <name> --dir <目录> --yes [--no-git] [--review] [--mode smart
 
 > **⭐ 建项目时务必确认「要不要开清单验收」**:开了(`SPS_REVIEW=on`)才会在每卡完成后派独立 agent
 > 按卡内 `## 检查清单` 逐条审核(不过自动插修正卡)。你(对话 agent)通过 `create_project` 建项目前,
-> **必须先问用户要不要开**,再据答传 `enableReview`。见第 5 节「验收清单」的写法规范。
-
-### What gets created
-
-```
-~/.coral/projects/<name>/
-├── conf                      # your active settings (private, mode 600)
-├── conf.example              # full reference with comments (read-only docs)
-├── pipelines/
-│   ├── project.yaml          # default 1-stage pipeline (develop → Done)
-│   └── sample.yaml.example   # heavily-commented YAML reference
-├── pipeline_order.json       # active pipeline pointer
-├── runtime/
-│   ├── state.json            # worker slot + active card state (machine-managed)
-│   └── tick.lock             # lock file
-├── logs/                     # per-tick logs
-├── pm_meta/                  # markdown card backend metadata
-└── cards/                    # state subdirs created on first use
-    └── seq.txt
-```
-
-Plus, in the **target repo** (PROJECT_DIR):
-- `.claude/CLAUDE.md` — worker rules + (if wiki=on) wiki SOP block
-- `.claude/skills/` — symlinked from `~/.coral/skills/`
-- `.claude/settings.local.json` — Claude Code local config
-- `wiki/` (if wiki=on) — knowledge base scaffold
-- `ATTRIBUTION.md` (if wiki=on) — borrows declaration
-
----
-
-## 3. Pipeline YAML
-
-**Location**: `~/.coral/projects/<name>/pipelines/project.yaml`
-
-**Single source of truth** for stages, profiles, transitions. Edit this file (or in
-console at `/projects/<name>` pipeline editor) to customize.
-
-### Critical YAML rules
-
-1. **`mode: project`** — orchestrate cards through states. (`mode: steps` is for
-   one-shot custom pipelines via `sps pipeline run <name>`.)
-2. **`on_complete` of each stage points to the next stage's target state.** No
-   skipping, no looping.
-3. **Last stage's `on_complete: "move_card Done"`.**
-4. **Don't write `agent:` field** — it's accepted for back-compat but ignored.
-   Claude (via ACP) is the only supported worker as of v0.38.0.
-5. **Single worker, serial execution** — set `MAX_CONCURRENT_WORKERS` in conf if
-   you want >1 slot reserved, but cards still run one at a time.
-6. **Failure halts pipeline** by default (`on_fail.halt: true`). Worker labels card
-   `NEEDS-FIX`; user must resolve before next card runs.
-
-### Templates
-
-**Simple (1 stage):**
-```yaml
-mode: project
-git: true
-stages:
-  - name: develop
-    on_complete: "move_card Done"
-    on_fail:
-      action: "label NEEDS-FIX"
-      halt: true
-```
-
-**With review (2 stages):**
-```yaml
-mode: project
-git: true
-stages:
-  - name: develop
-    profile: fullstack
-    on_complete: "move_card Review"
-    on_fail: { action: "label NEEDS-FIX", halt: true }
-  - name: review
-    profile: reviewer
-    on_complete: "move_card Done"
-    on_fail: { action: "label REVIEW-FAILED", halt: true }
-```
-
-**Non-git (data / docs project):**
-```yaml
-mode: project
-git: false
-stages:
-  - name: process
-    profile: tax-worker
-    on_complete: "move_card Done"
-    on_fail: { action: "label PROCESS-FAILED", halt: true }
-```
-
-### YAML field reference
-
-| Field | Required | Notes |
-|---|---|---|
-| `mode` | yes | `project` (state machine) or `steps` (one-shot, run via `sps pipeline run`) |
-| `git` | no | `true` (default) — worker commits + pushes / `false` — no git ops |
-| `stages` | yes | Array |
-| `stages[].name` | yes | Unique within file |
-| `stages[].profile` | no | Skill profile (e.g. `fullstack` / `reviewer` / `tax-worker`); falls back to `DEFAULT_WORKER_SKILLS` in conf |
-| `stages[].on_complete` | yes | `"move_card <NextState>"` |
-| `stages[].on_fail.action` | no | `"label NEEDS-FIX"` etc. |
-| `stages[].on_fail.halt` | no | default `true` |
-| `stages[].on_fail.comment` | no | Comment text |
-| `stages[].timeout` | no | `30s` / `5m` / `2h` (rare) |
-
-`trigger` and `card_state` are auto-derived per stage from the position. Don't set
-manually.
-
-### Custom pipelines (mode: steps)
-
-For one-shot scripted runs (e.g. canary deploy, bulk ingest), use `mode: steps` and
-invoke via `sps pipeline run <pipeline-name> "<prompt>"`. Out of scope for normal
-card pipelines; see `sample.yaml.example` for syntax.
+> **必须先问用户要不要开**,再据答传 `enableReview`。清单写法见下方「验收清单」。
 
----
-
-## 4. Card state machine
-
-```
-v0.51.9 起：
-
-Backlog → Todo → Inprogress → [QA / Review] → Done
-   ↑↓
-Planning（用户手动暂存；不自动派发）
-                                  ↓ fail
-                            NEEDS-FIX (halt)
-```
-
-Default states (configurable in YAML `pm.card_states`):
-- **Planning** — v0.51.10+：人工暂存 / 草稿。**console "新卡片" 表单**默认入此状态；用户拖到 Backlog 才会跑。
-- **Backlog** — **`sps card add`（CLI / agent）**默认入此状态；StageEngine 抢卡执行。
-- **Todo** — StageEngine 已 prep（建分支 / worktree），下次 tick 派 worker
-- **Inprogress** — worker active
-- **QA** (or **Review**) — code complete, awaiting human/auto verification
-- **Done** — finished
-- **Canceled** — folded into Done view (rare state)
+项目目录结构、`sps setup` 细节、conf 全字段 → `references/setup-and-config.md`。
+Pipeline YAML(stages / profile / on_complete)配置 → `references/pipeline-yaml.md`。
 
-Engines walk this graph each tick. The **active stage** writes a per-slot marker
-file at `~/.coral/projects/<p>/runtime/worker-<slot>-current.json` (v0.50.21+).
-Stop hook reads this to detect which card the worker just finished.
+## Card management
 
----
-
-## 5. Card management
-
-### Where new cards land — depends on caller (v0.51.10+)
-
-| 调用方 | 默认入场 state | 行为 |
-|---|---|---|
-| **`sps card add`** (CLI / Worker / agent) | **Backlog** | 下次 tick 立即被 StageEngine 抢卡跑 |
-| **Console "新卡片" 表单** | **Planning** | 暂存；用户在看板拖到 Backlog 才会跑 |
-| **`POST /api/projects/<p>/cards`** 直接调 API | **Planning** | 默认人工语义；body 传 `initialState: 'Backlog'` 立即跑 |
-
-**Agent 调 `sps card add` → 卡进 Backlog → 自动跑。** 这是 SPS 的主路径。Worker 在某个卡里需要"派生子任务"时用 `sps card add`，子任务会被下一个 tick 自动 pickup。
+**Agent 调 `sps card add` → 卡进 Backlog → 自动跑。** 这是 SPS 的主路径。Worker 在某卡里需要
+派生子任务时也用它,子任务被下一个 tick 自动 pickup。
 
 ```bash
 # Agent / Worker 主路径 — 直接进 Backlog 自动跑
 sps card add <project> "Title" "Description"
 sps card add <project> "T" "D" --skill python,backend
 
-# 带验收清单（审核点）—— 见下方「验收清单」小节
+# 带验收清单(审核点)—— 见下方「验收清单」
 sps card add <project> "实现登录" "描述…" --checklist "点1;点2;点3"
 
-# 插队 / 修正卡 —— 建 Backlog + 优先跑（PRIORITY），排到其它排队卡之前
+# 插队 / 修正卡 —— 建 Backlog + 优先跑(PRIORITY),排到其它排队卡之前
 sps card insert <project> "先修这个" "描述…"
 
-# 想暂存（让用户审核 / 自己稍后拖派发）
+# 暂存(让用户审核 / 自己稍后拖派发)—— 卡进 Planning,等手动拖到 Backlog
 sps card add <project> "Title" "Description" --draft
-                                  # → 卡进 Planning，等手动拖到 Backlog
+
+# 看板
+sps card dashboard <project>       # CLI table;console: /board?project=<name>
 ```
 
-### 验收清单（审核点）—— 建卡时写，决定这张卡「怎样算做完」
+卡片状态机、机器管理的生命周期命令(mark-started / reset)、完整标签词表 → `references/cards.md`。
 
-**这是建卡 agent 的一等职责。** 开了 `SPS_REVIEW=on` 的项目：卡带 `## 检查清单` = **开审核**（per-card 开关，无清单就不审）。worker 干完后，一个**独立第三方 reviewer**（OpenAI 角色，去相关盲点）会**对着真实项目产物逐条核验**这份清单：
+### 验收清单(审核点)—— 建卡时写,决定这张卡「怎样算做完」
+
+**这是建卡 agent 的一等职责。** 开了 `SPS_REVIEW=on` 的项目:卡带 `## 检查清单` = **开审核**
+(per-card 开关,无清单就不审)。worker 干完后,一个**独立第三方 reviewer**(OpenAI 角色,去相关盲点)
+会**对着真实项目产物逐条核验**这份清单:
 
 - **全过** → 卡留 Done。
-- **有不过** → 自动 `card insert` 一张**修正卡**（优先跑、无清单）让下一轮 worker 先修；本卡照常 Done。
-- **修正卡无清单 → 不再触发审核** → 不会无限打回（结构性终止）。
+- **有不过** → 自动 `card insert` 一张**修正卡**(优先跑、无清单)让下一轮 worker 先修;本卡照常 Done。
+- **修正卡无清单 → 不再触发审核** → 不会无限打回(结构性终止)。
 
-所以清单 = 这张卡的**验收标准**，由**你（建卡的 agent）在建卡时写**：
+所以清单 = 这张卡的**验收标准**,由**你(建卡的 agent)在建卡时写**:
 
 ```bash
 sps card add <project> "实现登录" "描述…" --checklist "点1;点2;点3"
-#                                         分隔符：;  ／  ；  ／  换行
+#                                         分隔符:;  ／  ；  ／  换行
 ```
 
-**怎么写好每一条**（reviewer 只读代码、不跑程序、看真实文件——写得能被**静态核验**才有用）：
+**怎么写好每一条**(reviewer 只读代码、不跑程序、看真实文件——写得能被**静态核验**才有用):
 
-1. **一条一件事**，能明确判过/不过。别把多件事塞一条。
-2. **落到可核验的产物**：某文件/函数/组件存在、实现了某行为、某配置/文案就位；尽量给「去哪看」。
-3. **客观判据**：pass 标准写死（「有 X 且做到 Y」），不用「够好/合理/流畅/好玩」这类主观词。
-4. **运行时项给静态替身或标注**：真跑才知道的（手感/动画/音效），写成代码层可验的替身（「受伤时 `hp -= dmg` 且 UI 绑定 hp」），或标 `[需运行时]`（reviewer 会保守判 fail）。
-5. **数量克制**：3–7 条，覆盖「这卡算做完」的关键面，不穷举、不凑数。
-6. **与卡的 skill 对齐**：卡指定了 skill（SOP）时，验收点体现该 SOP 的硬要求（reviewer 也会加载同一 SOP 对照）。
-7. **用户可见 > 内部实现**（纯重构卡除外）。
+1. **一条一件事**,能明确判过/不过。别把多件事塞一条。
+2. **落到可核验的产物**:某文件/函数/组件存在、实现了某行为、某配置/文案就位;尽量给「去哪看」。
+3. **客观判据**:pass 标准写死(「有 X 且做到 Y」),不用「够好/合理/流畅/好玩」这类主观词。
+4. **运行时项给静态替身或标注**:真跑才知道的(手感/动画/音效),写成代码层可验的替身(「受伤时 `hp -= dmg` 且 UI 绑定 hp」),或标 `[需运行时]`(reviewer 会保守判 fail)。
+5. **数量克制**:3–7 条,覆盖「这卡算做完」的关键面,不穷举、不凑数。
+6. **与卡的 skill 对齐**:卡指定了 skill(SOP)时,验收点体现该 SOP 的硬要求(reviewer 也会加载同一 SOP 对照)。
+7. **用户可见 > 内部实现**(纯重构卡除外)。
 
-| ❌ 空泛（reviewer 没法判） | ✅ 可核验 |
+| ❌ 空泛(reviewer 没法判) | ✅ 可核验 |
 |---|---|
-| 登录功能好用 | `login()` 对空用户名/密码返回明确错误文案（非崩溃/非静默） |
-| 游戏好玩 | `[需运行时]` 点开始进入战斗；静态替身：`StartButton.onClick` 绑定 `scene.load('battle')` |
-| 性能好 | 长列表用虚拟滚动（`react-window`），一次渲染项数 ≤ 可视区 |
-
-> 清单写空泛 = 审核白做。**这一步的质量决定整条审核链的价值**——宁可少写几条可验的，也别堆一堆没法判的。
-
-### View
-
-```bash
-sps card dashboard <project>       # CLI table
-                                   # console: /board?project=<name>
-```
-
-### Lifecycle (machine-managed, but you can intervene)
-
-```bash
-sps card mark-started <p> <seq>    # called by Claude Code UserPromptSubmit hook
-sps card mark-complete <p> <seq>   # called by Claude Code Stop hook
-sps reset <p>                      # reset all non-Done
-sps reset <p> --card 5,6,7         # reset specific seq
-sps reset <p> --all                # full reset incl. Done
-```
-
-注：`sps reset` 把卡退回 **Planning**（不是 Backlog） — 重置 = 退回人工控制，需手动拖回 Backlog 才会再跑。这是 v0.51.9 起的语义。
-
-### Card label vocabulary
-
-| Label | Meaning | Who sets |
-|---|---|---|
-| `AI-PIPELINE` | "SPS pipeline 卡" 的标记（v0.51.9+ 不再触发任何自动行为，仅识别） | `sps card add` 自动加 |
-| `PRIORITY` | 插队 —— 抢卡时排到同队列其它卡之前 | `sps card insert` / reviewer 插修正卡 |
-| `REVIEWED` | 该卡验收清单已被 reviewer 审过（幂等，不重审） | ReviewEngine（`SPS_REVIEW=on`） |
-| `STARTED-<stage>` | ACK signal — Claude received the prompt | UserPromptSubmit hook |
-| `COMPLETED-<stage>` | Worker finished a stage | Stop hook |
-| `CLAIMED` | StageEngine reserved a worker slot | Engine |
-| `NEEDS-FIX` | Worker failed; pipeline halted | Engine |
-| `BLOCKED` | External dep; pipeline skips | User |
-| `WAITING-CONFIRMATION` | Worker waiting on user input | Engine |
-| `STALE-RUNTIME` | Inprogress > timeout | MonitorEngine |
-| `ACK-TIMEOUT` | Claude never ACK'd within `WORKER_ACK_TIMEOUT_S` | MonitorEngine |
-| `skill:<name>` | Force-load specific skill | User on card |
-| `conflict:<domain>` | Serial-with-others-in-same-domain | User |
+| 登录功能好用 | `login()` 对空用户名/密码返回明确错误文案(非崩溃/非静默) |
+| 游戏好玩 | `[需运行时]` 点开始进入战斗;静态替身:`StartButton.onClick` 绑定 `scene.load('battle')` |
+| 性能好 | 长列表用虚拟滚动(`react-window`),一次渲染项数 ≤ 可视区 |
 
----
+> 清单写空泛 = 审核白做。**这一步的质量决定整条审核链的价值**——宁可少写几条可验的,也别堆一堆没法判的。
 
-## 6. Pipeline lifecycle commands
+## Run the pipeline
 
 > 🔴 **启动流水线:agent 一律用 `sps pipeline start`(非阻塞,后台起,瞬间返回)。**
 > **绝不要跑 `sps tick`**——那是**前台无限循环**,会把你的终端/回合永久卡死。
 
 ```bash
-# ✅ 启动(非阻塞,后台跑,瞬回)—— agent / 脚本用这个
-sps pipeline start <project>       # detached 后台起 tick,立即返回 pid;看日志:sps logs <p> --no-follow
-# ⚠️ 前台跟着看(阻塞,只给人在终端用,agent 别用)
-sps tick <project>                 # foreground 无限循环 — Ctrl+C to stop
-sps pipeline stop <project>        # graceful stop
-sps stop <project>                 # CLI alias for stop
-sps stop --all                     # stop all running ticks
-
-# Status
-sps status                         # all projects
-sps pipeline status                # alias
-sps doctor <project>               # health check
-sps doctor <project> --fix         # auto-repair drift
-
-# One-off ticks (each engine separately, useful for cron / debugging)
-sps scheduler tick <p>             # v0.51.9 起为 no-op（dormant，保留接口）
-sps pipeline tick <p>              # full StageEngine pass
-sps qa tick <p>                    # QA → Done finalization
-sps monitor tick <p>               # health probe (ACK timeout, stale runtime)
-sps pm scan <p>                    # rebuild card index from disk
-```
-
-### Worker control
-
-```bash
-sps worker ps <project>            # list slots + PIDs
-sps worker dashboard <project>     # rich UI (also in console)
-sps worker kill <project> <seq>    # SIGKILL one slot
-sps worker launch <project> <seq>  # manual spawn (debugging)
-```
-
-### Logs
-
-```bash
-sps logs <project>                 # follow mode (default)
-sps logs <project> --err           # stderr only
-sps logs <project> --lines 50 --no-follow
-                                   # console: /logs?project=<name> (live SSE)
-```
-
----
-
-## 7. Web Console (`sps console`)
-
-Single binary launches the web UI:
-
-```bash
-sps console                        # opens http://127.0.0.1:4311
-sps console --port 5000
-sps console --no-open
-sps console --kill                 # stop running console
-sps console --dev                  # vite dev server (development)
-```
-
-Pages:
-- `/projects` — list, summary cards
-- `/projects/new` — create project (with Wiki toggle, v0.51)
-- `/projects/<n>` — pipeline editor + conf editor + delete
-- `/board` — kanban (with **per-column scrolling**, v0.51.1+)
-- `/workers` — aggregate worker dashboard (all projects)
-- `/logs` — live SSE log viewer
-- `/skills` — user-level skill management
-- `/system` — global settings, daemon status
-- `/chat` — agent chat (multi-session, persistent)
-
----
-
-## 8. Wiki (auto-injected into Worker prompts)
-
-> **记忆系统重构中**:本地记忆(旧 `sps-memory` skill + `sps memory` CLI)已在 v2 重构里移除;新工具(`memory_*` / `sps memory recall/save`)上线后补。见 `docs/design/memory-v2.md`。
-
-**Wiki** (`wiki-update` skill) — structured project knowledge: modules, concepts, decisions, lessons.
-
-| | Wiki |
-|---|---|
-| Path | `<repo>/wiki/` (per-project, in repo) |
-| Schema | 5 page types with zod-validated frontmatter |
-| Cross-link | `[[type/Title]]` wikilinks |
-| Auto-inject | `wikiRead` 5-layer → prompt's `wikiContext` section (only when `WIKI_ENABLED=true`) |
-
-Enable Wiki at create time for structured knowledge accumulation.
-
-CLI helpers:
-```bash
-sps wiki init <p>                  # scaffold (auto when WIKI_ENABLED=true)
-sps wiki update <p>                # source diff
-sps wiki update <p> --finalize     # flush manifest after pages written
-sps wiki check <p>                 # lint
-sps wiki read <p> "<query>"        # preview prompt injection
-sps wiki list/get/add/status       # browse / inspect
+sps pipeline start <project>       # ✅ detached 后台起,立即返回 pid;看日志 sps logs <p> --no-follow
+sps pipeline stop <project>        # graceful stop(alias: sps stop <project> / sps stop --all)
+sps status                         # all projects(alias: sps pipeline status)
+sps doctor <project> --fix         # health check + auto-repair drift
 ```
 
----
-
-## 9. Conf reference (essentials)
-
-Live at `~/.coral/projects/<name>/conf` (shell `export VAR="value"` syntax).
-
-| Field | Default | Notes |
-|---|---|---|
-| `PROJECT_NAME` | (required) | Internal id |
-| `PROJECT_DIR` | (required) | Repo absolute path |
-| `GITLAB_PROJECT` | — | `user/repo` (optional, for GitLab API) |
-| `GITLAB_MERGE_BRANCH` | `main` | Worker pushes here |
-| `PM_TOOL` | `markdown` | **Only `markdown` supported as of v0.42.0**. Plane/Trello removed. Cards live in `~/.coral/projects/<n>/cards/<state>/<seq>.md` |
-| `PIPELINE_LABEL` | `AI-PIPELINE` | Marker label auto-added by `sps card add` — identifies SPS-managed cards. v0.51.9+ 不再触发自动状态提升（卡按入场 state 决定是否跑） |
-| `MR_MODE` | `none` | `none` (push direct) / `create` (open MR; needs `GITLAB_PROJECT_ID`) |
-| `WORKER_TRANSPORT` | `acp-sdk` | Fixed; do not change |
-| `MAX_CONCURRENT_WORKERS` | `1` | Slot count; cards still serial within a project |
-| `MAX_ACTIONS_PER_TICK` | `3` | New tasks claimable per tick |
-| `INPROGRESS_TIMEOUT_HOURS` | `2` | After this, MonitorEngine flags STALE-RUNTIME |
-| `WORKER_ACK_TIMEOUT_S` | `300` | Wait for STARTED-<stage> label after dispatch (5min, raised in v0.50.24) |
-| `WORKER_ACK_MAX_RETRIES` | `1` | ACK timeout retry count |
-| `MONITOR_AUTO_QA` | `true` | Auto-advance to QA on stale runtime |
-| `SPS_REVIEW` | unset (off) | `on` 开清单验收：卡带 `## 检查清单` → worker 完成后独立 reviewer 逐条审 → 全过留 Done / 有不过自动插修正卡。见第 5 节「验收清单」 |
-| `CONFLICT_DEFAULT` | `serial` | Fallback for cards without `conflict:` label |
-| `MATRIX_ROOM_ID` | — | Project-level Matrix override |
-| `WORKTREE_DIR` | `~/.coral/worktrees/<p>` | Worker scratch space |
-| `DEFAULT_WORKER_SKILLS` | — | Comma-separated skill list when no `profile:` and no `card.skills` |
-| `ENABLE_MEMORY` | `true` | Set `false` to skip memory write instructions in prompt |
-| **`WIKI_ENABLED`** | unset (off) | **v0.51+**: `true` enables wiki context injection + reminder block |
-| `COMPLETION_SIGNAL` | `done` | Word the Stop hook listens for |
-
-Full reference: `~/.coral/projects/<n>/conf.example` (auto-generated, comment-rich).
-
----
-
-## 10. Architecture (4-layer, v0.50+)
-
-```
-Delivery (commands/, console/routes/)
-  → execute* / HTTP routes; thin
-Service (services/)
-  → ProjectService / ChatService / PipelineService / SkillService — Result<T> + DomainEvent
-Domain (engines/)
-  → SchedulerEngine / StageEngine / MonitorEngine / EventHandler
-Infrastructure (manager/, providers/, daemon/)
-  → WorkerManager (single worker), ACPWorkerRuntime, sessionDaemon
-```
-
-### Engines
-
-- **SchedulerEngine** — v0.51.9 起 dormant（卡 add 直接进 Backlog，无需提升）
-- **StageEngine** — drives card through stages; builds prompt (skill + projectRules
-  + memory + **wikiContext** + task description + **wikiUpdateReminder**); kicks
-  Worker via ACP
-- **MonitorEngine** — ACK timeout detection, stale runtime, auto-QA promotion
-- **CloseoutEngine / EventHandler** — finalize completed cards
-
-### Single worker is intentional
+Worker 控制、日志、逐引擎 one-off tick、排障 → `references/operations.md`。
 
-v0.37.2 deleted multi-worker concurrency code by design. Don't propose "add a
-parallel mode" — the architecture relies on serial execution for state coherence.
-For higher throughput, run multiple projects in parallel (each its own tick loop).
-
----
-
-## 11. Troubleshooting
-
-```bash
-sps doctor <project> --fix         # ★ first thing to try
-sps logs <project> --err           # stderr / errors
-sps reset <project> --card <seq>   # nuke a stuck card
-sps reset <project> --all          # full project reset (worktrees, branches, state)
-
-# Worker / daemon issues
-sps worker ps <project>
-sps agent daemon status            # is the chat daemon up?
-sps agent daemon stop && sps agent daemon start    # restart daemon (clears stale cwd)
-
-# Wiki issues (v0.51+)
-sps wiki check <project>           # lint
-sps wiki status <project>          # source / manifest / pages diff
-```
-
-Common issues:
-
-- **Pipeline halted with NEEDS-FIX** — open the failed card, fix the issue, remove
-  the label. Console makes this 2 clicks.
-- **Worker not starting** — `sps worker ps`, then check `sps logs --err`. Often
-  Claude API key missing or `claude-agent-acp` adapter not installed (`sps setup`
-  reinstalls it).
-- **Cards stuck in Planning (v0.51.9+)** — Planning 是人工暂存。**Console 表单建卡默认到这里**，需手动拖到 Backlog 派发。Agent / `sps card add` 默认进 Backlog 自动跑（不会卡在 Planning）。
-- **ACK timeout on every card** — Claude cold-start is slow with many skills/memory
-  files. Raise `WORKER_ACK_TIMEOUT_S` in conf (default 300s as of v0.50.24).
-- **Console shows stale data** — SSE may have dropped; reload page; if persistent,
-  `sps console --kill && sps console`.
-- **Wiki context not injecting** — verify `WIKI_ENABLED=true` in conf and
-  `wiki/WIKI.md` exists. StageEngine logs a warning if conf says yes but scaffold
-  is missing.
-
----
-
-## 12. Skill ↔ project linkage
-
-User-level skills live in `~/.coral/skills/`. To use one in a specific project:
-
-```bash
-sps skill list                             # what's available + project status
-sps skill add <name> --project <p>         # symlink into <repo>/.claude/skills/
-sps skill remove <name> --project <p>
-sps skill freeze <name> --project <p>      # symlink → real copy (allow project edits)
-sps skill unfreeze <name> --project <p>    # back to symlink
-sps skill sync                             # ① bundled (npm pkg) → ~/.coral/skills/
-                                           # ② ~/.coral/skills/ → ~/.claude/skills/
-```
+## References
 
-**After upgrading sps-cli**, run `sps skill sync` to pick up new bundled skills
-(e.g. `wiki-update` added in v0.51.0).
+- `references/setup-and-config.md` — 首次安装、项目目录结构、conf 全字段
+- `references/pipeline-yaml.md` — pipeline YAML(stages / profile / transitions)
+- `references/cards.md` — 卡片状态机、生命周期命令、标签词表
+- `references/operations.md` — 生命周期命令全集、worker 控制、日志、排障
+- `references/console-and-wiki.md` — Web Console 页面、Wiki 知识库
+- `references/architecture.md` — 4 层架构、engines、skill ↔ project 关联

package/skills/sps-pipeline/references/architecture.md

@@ -0,0 +1,46 @@
+# Architecture & Skill Linkage
+
+## Architecture (4-layer, v0.50+)
+
+```
+Delivery (commands/, console/routes/)
+  → execute* / HTTP routes; thin
+Service (services/)
+  → ProjectService / ChatService / PipelineService / SkillService — Result<T> + DomainEvent
+Domain (engines/)
+  → SchedulerEngine / StageEngine / MonitorEngine / EventHandler
+Infrastructure (manager/, providers/, daemon/)
+  → WorkerManager (single worker), ACPWorkerRuntime, sessionDaemon
+```
+
+### Engines
+
+- **SchedulerEngine** — v0.51.9 起 dormant（卡 add 直接进 Backlog，无需提升）
+- **StageEngine** — drives card through stages; builds prompt (skill + projectRules
+  + memory + **wikiContext** + task description + **wikiUpdateReminder**); kicks
+  Worker via ACP
+- **MonitorEngine** — ACK timeout detection, stale runtime, auto-QA promotion
+- **CloseoutEngine / EventHandler** — finalize completed cards
+
+### Single worker is intentional
+
+v0.37.2 deleted multi-worker concurrency code by design. Don't propose "add a
+parallel mode" — the architecture relies on serial execution for state coherence.
+For higher throughput, run multiple projects in parallel (each its own tick loop).
+
+## Skill ↔ project linkage
+
+User-level skills live in `~/.coral/skills/`. To use one in a specific project:
+
+```bash
+sps skill list                             # what's available + project status
+sps skill add <name> --project <p>         # symlink into <repo>/.claude/skills/
+sps skill remove <name> --project <p>
+sps skill freeze <name> --project <p>      # symlink → real copy (allow project edits)
+sps skill unfreeze <name> --project <p>    # back to symlink
+sps skill sync                             # ① bundled (npm pkg) → ~/.coral/skills/
+                                           # ② ~/.coral/skills/ → ~/.claude/skills/
+```
+
+**After upgrading sps-cli**, run `sps skill sync` to pick up new bundled skills
+(e.g. `wiki-update` added in v0.51.0).