@coralai/sps-cli 0.58.35 → 0.58.37

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

@@ -0,0 +1,69 @@
+# Card State Machine, Lifecycle & Labels
+
+卡片状态机、机器管理的生命周期命令、以及完整标签词表。建卡命令与验收清单写法在主 SKILL.md。
+
+## 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)
+
+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.
+
+## 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。
+
+## 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 |

package/skills/sps-pipeline/references/console-and-wiki.md

@@ -0,0 +1,53 @@
+# Web Console & Wiki
+
+## 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)
+```
+
+Console listens on `127.0.0.1:4311` by default; opens browser auto. Single-instance
+guard via `~/.coral/console.lock`.
+
+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)
+
+## 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
+```

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

@@ -0,0 +1,83 @@
+# Operations: Lifecycle Commands, Worker Control, Logs & Troubleshooting
+
+流水线生命周期命令全集、worker 控制、日志、排障。启动流水线的**核心纪律**(非阻塞)在主 SKILL.md。
+
+## Pipeline lifecycle commands
+
+> 🔴 **启动流水线: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)
+```
+
+## 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.

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

@@ -0,0 +1,84 @@
+# Pipeline YAML Reference
+
+**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.

package/skills/sps-pipeline/references/setup-and-config.md

@@ -0,0 +1,80 @@
+# Setup & Config Reference
+
+首次安装、`sps setup` 做了什么、项目建出来的目录结构、以及 conf 全字段参考。
+
+## First-time setup
+
+```bash
+npm install -g @coralai/sps-cli      # latest
+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.
+
+Re-run safe: `sps setup --force` keeps existing values as defaults.
+
+**No separate console config** — Console reads `~/.coral/env` + per-project conf.
+
+## What a project looks like on disk
+
+```
+~/.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
+
+## 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 / 有不过自动插修正卡。见主 SKILL.md「验收清单」 |
+| `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).

package/skills/visual-rubric/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: visual-rubric
 description: 审核视觉评分卡——按"当前任务该看到什么"分阶段评判游戏截图,避免对早期框架任务强求"实战可玩"导致死循环。
+category: review
 audience: reviewer
-tags: [reviewer, visual]
+tags: [game]
 ---
 
 # 视觉评分卡(游戏类,截图评审专用)