@coralai/sps-cli 0.65.17 → 0.65.19

package/skills/prompt-writer/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: prompt-writer
+description: 把用户一句话的需求扩写成专业、结构化、可复用的提示词(prompt)。按任务类型自动选提示框架(RTF/CO-STAR/RISEN/工具专用),套用少而精的提示技术,产出带 {{变量}} 模板便于复用。
+category: meta
+metadata:
+  origin: bundled
+tags:
+  - ai
+  - docs
+whenToUse: 当用户只有一句较模糊的任务意图，但希望产出可直接保存/复用的高质量提示词时选它；典型表述如“帮我写一个用于XXX的prompt”“把这个需求整理成结构化提示词”“生成可复用的提示模板，并预留变量位”。
+insteadUse: 如果需求是创建/整理一个技能本身，而不是生成单个可复用提示词，应改用 skill-creator。
+---
+
+# Prompt Writer
+
+把用户模糊的意图,扩写成一条**专业、结构清晰、可复用**的提示词。
+(方法论吸收自 prompt-master,MIT,github.com/nidhinjs/prompt-master。)
+
+## 🔴 铁律:一次性生成,不问用户
+
+本功能是**后台一次性生成**,**不能和用户来回**。信息不全时**绝不提问**——**推断最可能的上下文**,把会变的部分留成 `{{变量}}` 占位。宁可多留一个变量,也不要停下来问。
+
+## 产出契约(务必遵守)
+
+在**当前目录**写一个文件 `PROMPT.md`,格式:
+
+```
+---
+name: <kebab-case 短名>
+description: <一句话说清这个提示词干什么>
+tags: [<相关标签>]
+---
+<提示词正文>
+```
+
+- `name`:kebab-case(小写字母/数字/连字符),简短达意。
+- 正文:用 `{{变量}}` 作为填充位(如 `{{language}}`、`{{code}}`、`{{目标受众}}`),让提示词可复用。
+- **只写 `PROMPT.md` 这一个文件**,不要写别的。
+
+## 第一步:判任务类型 → 自动选框架
+
+先看这条提示词**是给谁/什么工具用的**,挑最贴的框架当骨架(拿不准用 RTF 打底):
+
+| 场景 | 框架 | 结构 |
+|---|---|---|
+| 通用任务 / 角色 | **RTF** | Role 角色 · Task 任务 · Format 输出格式 |
+| 内容/文案(有受众、有语气) | **CO-STAR** | Context 背景 · Objective 目标 · Style 风格 · Tone 语气 · Audience 受众 · Response 输出 |
+| 多步骤 / 复杂目标 | **RISEN** | Role · Instructions 指令 · Steps 步骤 · End goal 终点 · Narrowing 边界收窄 |
+| 给编码 IDE / coding agent | **File-Scope** | 明确文件/目录范围 · 约束 · **不许碰的** · 验收标准 |
+| 给图像生成 | **Visual Descriptor** | 主体 · 风格 · 构图 · 光线 · 细节 · 负向(不要什么) |
+| 给自主 agent | **ReAct + Stop** | 思考-行动循环 · 可用工具 · **明确停止条件** |
+
+## 第二步:套提示技术(少而精,别堆)
+
+- **角色赋予**:开头给清晰身份("你是一名资深 {{领域}} 专家")。
+- **Few-shot**:难用文字讲清的,给 1–2 个「输入→输出」示例锚定,胜过一堆形容词。
+- **XML/标签分块**:多段输入时用 `<context>` / `<task>` / `<constraints>` 分开,防模型混淆。
+- **Grounding 锚点**:给事实/判据锚点,压幻觉("**只基于**给定的 `{{输入}}`,不要编造")。
+- **Chain-of-Thought**:**仅推理型**任务加"先分步思考再给结论";简单任务别加(白烧 token)。
+
+## 第三步:token 审计(每个词都 load-bearing)
+
+- 把空泛词翻成可执行指令("写得专业点" → 具体要求)。
+- 删重复、礼貌套话、无信息量的修饰。
+- **最好的提示词不是最长的,是每个词都在起作用的。**
+
+## 骨架(无论用哪个框架,这几件都要有)
+
+1. **角色/目标**:模型是谁、要达成什么。
+2. **上下文/输入**:用 `{{变量}}` 占位需要填的输入。
+3. **明确任务与约束**:做什么、**不做什么**、边界。
+4. **输出格式**:期望的结构/长度/风格(需要时给例子)。
+5. **判据**(可选,但显著提质):什么算做好。
+
+## 原则
+
+- **具体 > 空泛**:把模糊意图翻译成可执行指令。
+- **可复用**:会变的抽成 `{{变量}}`;别把一次性具体值写死。
+- **精炼**:每句都为效果服务。
+- **贴合意图**:紧扣用户需求,不擅自扩大范围。
+- **框架服务于任务**:框架是骨架不是枷锁,任务简单就别硬套六段式。

package/skills/sps/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: sps
+description: Use the Coral SPS CLI (@coralai/sps-cli v0.58+) as an AI Agent harness and automated development pipeline. Two modes — Harness (sps agent) for zero-config agent interaction with multi-turn chat, hooks, MCP, and daemon persistence; Pipeline (sps pipeline / sps tick) for fully automated card-driven development workflow.
+category: platform
+---
+
+# SPS
+
+Use SPS as the primary deterministic execution layer for coding workflow operations.
+
+## Core rule
+
+SPS has two modes:
+- **Harness mode** (`sps agent`): zero-config agent interaction — one-shot, multi-turn chat, persistent daemon sessions, hooks, MCP
+- **Pipeline mode** (`sps pipeline`): automated card-driven development workflow with PM + Git integration
+
+Use the global `sps` command to interact with agents or manage workflow state. Do not bypass SPS with ad hoc shell logic unless SPS clearly lacks the capability.
+
+## Harness mode quick reference
+
+```bash
+sps agent "<prompt>"                              # one-shot
+sps agent --chat                                  # multi-turn (daemon-backed)
+sps agent --hook "npm test" "<prompt>"            # auto-fix loop
+sps agent --mcp postgres "<prompt>"               # MCP tools
+sps agent --attach --name backend                 # read-only view
+sps agent --json "<prompt>"                       # JSON output
+sps agent status / close / list / add / daemon    # management
+```
+
+The worker agent is **Claude only** (Codex/Gemini worker backends were removed in v0.38). Requires the `claude` CLI on PATH plus Claude auth (`~/.claude` login or `ANTHROPIC_API_KEY`).
+
+## Pipeline mode quick reference
+
+```bash
+sps pipeline start <project>       # or: sps tick <project>
+sps pipeline stop/status/reset
+sps pipeline workers/board/logs
+```
+
+## Configuration-safety rule
+
+Before running any command that creates or overwrites project/global configuration, confirm with Boss first.
+
+This explicitly includes:
+- `sps setup`
+- `sps project init <project>`
+- any doctor/fix or recovery action that will write missing config or rewrite project configuration
+
+## Concurrency-change rule
+
+When Boss asks to change a project's worker concurrency, update and verify all of the following together:
+- `~/.coral/projects/<project>/conf`: change `MAX_CONCURRENT_WORKERS` to the new worker slot ceiling
+- `~/.coral/projects/<project>/conf`: if Boss expects one tick cycle to fill those slots immediately, change `MAX_ACTIONS_PER_TICK` to the same value (or another explicit launch budget)
+- runtime verification: confirm `~/.coral/projects/<project>/runtime/state.json` and `sps status <project> --json` show the expected worker slot count
+
+Important distinction:
+- `MAX_CONCURRENT_WORKERS` = maximum concurrent worker slots for the project
+- `MAX_ACTIONS_PER_TICK` = how many launches a single tick cycle is allowed to perform
+
+On SPS CLI `0.18.12+`, legacy `state.json` files auto-expand missing worker slots on read after `MAX_CONCURRENT_WORKERS` increases. On older versions, upgrading SPS is recommended before debugging “why do I still only have worker-1?” symptoms.
+
+---
+
+## 1. Initialize a project
+
+First confirm configuration rules with Boss, then:
+
+1. Ensure the business repo is cloned:
+   ```bash
+   git clone <repo-url> ~/projects/<project>/
+   ```
+
+2. Initialize SPS project directory:
+   ```bash
+   sps project init <project>
+   ```
+
+3. Edit project configuration:
+   ```bash
+   vim ~/.coral/projects/<project>/conf
+   # Fill in: PROJECT_NAME, PROJECT_DIR, GITLAB_PROJECT, GITLAB_PROJECT_ID,
+   #          WORKER_MODEL, MAX_CONCURRENT_WORKERS, etc.
+   # PM_TOOL defaults to markdown (cards stored under ~/.coral/projects/<name>/cards/)
+   ```
+
+   If you are changing concurrency after the project is already running:
+   ```bash
+   # Upper bound of simultaneous workers
+   export MAX_CONCURRENT_WORKERS=3
+
+   # Per-tick launch budget; raise this too if one tick should start 3 workers
+   export MAX_ACTIONS_PER_TICK=3
+   ```
+
+4. Run health check and auto-fix:
+   ```bash
+   sps doctor <project> --fix
+   # Validates config, creates missing dirs, generates CLAUDE.md, initializes state.json
+   ```
+
+5. (Optional) Customize `CLAUDE.md` in the repo root with project-specific coding standards
+
+**PM backend**: `PM_TOOL` defaults to `markdown` — cards live as files under `~/.coral/projects/<project>/cards/`. No external PM service to provision. (Plane/Trello backends were removed in v0.42.)
+
+---
+
+## 2. Create task cards
+
+**创建卡片（单步，用 `--skill` 直接写进卡片）：**
+
+```bash
+sps card add <project> "<title>" ["description"] [--skill a,b] [--draft] [--json]
+# → 自动加 AI-PIPELINE 标签；--skill 把技能写进卡片 frontmatter
+# → 默认入 Backlog（立即可跑）；--draft 才入 Planning（草稿，等手动派发）
+```
+
+**Agent 建卡时用 `--skill` 一步带上技能。** 判定规则:
+
+| 任务描述关键词 | `--skill` 值 |
+|--------------|-----------|
+| "设计架构"、"技术方案"、"选型"、"ADR" | `architect` |
+| "页面"、"组件"、"UI"、"前端"、"样式" | `frontend` |
+| "API"、"接口"、"数据库"、"migration"、"后端" | `backend` |
+| "全栈"、"完整功能"、"含前后端" | `fullstack` |
+| "原型"、"MVP"、"验证"、"快速搭建" | `prototyper` |
+| "review"、"审查"、"代码质量"、"优化代码" | `reviewer` |
+| "安全"、"漏洞"、"加固"、"审计" | `security` |
+| "文档"、"README"、"PRD"、"API 文档" | `writer` |
+| "性能"、"优化"、"慢"、"benchmark" | `optimizer` |
+| 无法判定 / 通用任务 | `senior` |
+
+**示例：**
+```bash
+# 架构设计任务
+sps card add proj "Design authentication system architecture" "OAuth 2.0 + JWT, design ADR and API contracts" --skill architect
+
+# 后端开发任务
+sps card add proj "Implement user registration API" "POST /api/users with email validation and bcrypt" --skill backend
+
+# 代码审查任务
+sps card add proj "Review and optimize order module" "Audit order processing code for N+1 queries and security issues" --skill reviewer
+```
+
+> 如需事后给已建的卡加标签，语法是 `sps pm label add <project> <seq> <label>`（`sps pm addLabel` 命令不存在)。
+
+### 2.1 Title rules
+
+Card title becomes part of the git branch name: `ai-card-<seq>-<title-slug>`.
+
+**Requirements:**
+- Use imperative verb: "Implement ...", "Add ...", "Fix ...", "Refactor ..."
+- Keep short (under 60 characters) — branch names get unwieldy otherwise
+- Be specific about the scope — Worker uses the title as task identity
+- English recommended (branch names with CJK characters work but may cause issues in some tools)
+
+**Good examples:**
+```bash
+sps card add proj "Implement JWT login endpoint"
+sps card add proj "Add order CRUD API with pagination"
+sps card add proj "Fix memory leak in WebSocket handler"
+sps card add proj "Refactor database layer to repository pattern"
+```
+
+**Bad examples:**
+```bash
+sps card add proj "Login"                    # Too vague, Worker won't know scope
+sps card add proj "Do the backend stuff"     # Not actionable
+sps card add proj "Implement login, signup, logout, profile, and settings"  # Too many things
+```
+
+### 2.2 Description rules
+
+The description flows **directly** into the Worker's task prompt (`.sps/task_prompt.txt`). It is the **primary specification** the Worker follows to implement the task. Writing a clear description is critical to Worker output quality.
+
+**Structure template:**
+```
+What: [One sentence summary of what to implement]
+
+Requirements:
+- [Concrete requirement 1]
+- [Concrete requirement 2]
+- [Concrete requirement 3]
+
+Technical constraints:
+- [Framework/library to use]
+- [API format or protocol]
+- [Performance or compatibility requirements]
+
+Acceptance criteria:
+- [Verifiable condition 1]
+- [Verifiable condition 2]
+
+Reference:
+- [Relevant file paths, API docs, or examples]
+```
+
+**Good description example:**
+```bash
+sps card add proj "Implement JWT login endpoint" \
+  "What: REST API endpoint for user authentication with JWT tokens.
+
+Requirements:
+- POST /api/auth/login accepts {email, password}
+- Returns {accessToken, refreshToken, expiresIn}
+- Access token expires in 15 minutes, refresh token in 7 days
+- Hash passwords with bcrypt (cost factor 12)
+- Rate limit: 5 attempts per minute per IP
+
+Technical constraints:
+- Use Express.js router in src/routes/auth.ts
+- Use existing User model in src/models/User.ts
+- Follow project error response format: {error: string, code: number}
+
+Acceptance criteria:
+- Valid credentials return 200 with tokens
+- Invalid credentials return 401
+- Missing fields return 400 with validation errors
+- Rate limiting returns 429 after threshold"
+```
+
+**Bad description example:**
+```bash
+sps card add proj "Add login" "Make a login page"
+# Too vague — Worker will guess at everything: framework, API shape, auth method
+```
+
+**Key principles:**
+- Worker is an AI agent executing in isolation — it has no context beyond the prompt
+- The description is the Worker's **only** source of task requirements
+- Be explicit about what to build, where to put it, and how to verify it
+- Include file paths if you want changes in specific locations
+- Include API shapes if you want specific request/response formats
+- When in doubt, over-specify rather than under-specify
+
+### 2.3 Label system
+
+标签体系(自动标签 / Skills / conflict 域标签 / 辅助状态标签)见 `references/labels.md`。
+
+### 2.4 Task decomposition principles
+
+Each card = one Worker session = one feature branch = one merge.
+
+**Right granularity:**
+- One card per logical feature or fix (1-4 hours of human work)
+- Worker should be able to complete the task in a single session
+- Changes should be self-contained and independently mergeable
+
+**Too large (split into multiple cards):**
+- "Build the entire backend" → split by API resource or module
+- "Refactor + add feature + fix bug" → three separate cards
+- Changes spanning 10+ files across unrelated modules
+
+**Too small (merge into one card):**
+- "Add import statement" — combine with the feature that needs it
+- "Fix typo in variable name" — combine with related code changes
+
+**Ordering with dependencies:**
+```bash
+# Create cards in dependency order — cards execute by seq order:
+sps card add proj "Set up database schema" "..." --skill backend    # seq 1
+sps card add proj "Implement User model" "..." --skill backend       # seq 2
+sps card add proj "Add auth endpoints" "..." --skill backend         # seq 3
+
+# Executed in seq order (1, 2, 3).
+# Each subsequent Worker inherits merged code from previous tasks.
+```
+
+### 2.5 Execution order management
+
+Cards execute in **seq order** by default — 建卡按依赖顺序即可，通常无需手动干预。
+
+```bash
+# Advanced: the queue pointer file ~/.coral/projects/<project>/pipeline_order.json
+# still exists (used internally), but sps card add no longer writes it as a
+# side-effect (since v0.51.9) — cards run by seq. Normally no manual edits needed.
+```
+
+### 2.6 State transitions
+
+| Transition | Triggered by | What happens |
+|-----------|-------------|--------------|
+| → Backlog | `sps card add` (default) | Card created, ready to run |
+| → Planning | `sps card add --draft` | Card created as draft, awaits dispatch |
+| Planning → Backlog | SchedulerEngine | Promotes draft cards once entry conditions met |
+| Backlog → Todo | ExecutionEngine | Feature branch + worktree created |
+| Todo → Inprogress | ExecutionEngine | Worker slot allocated, process launched |
+| Inprogress → Done | CompletionJudge + PostActions | Code merged, PM updated, slot released |
+
+**Manual transitions** (for recovery only):
+```bash
+sps pm move <project> <seq> <target-state>
+sps pm comment <project> <seq> "Reason for manual move"
+```
+
+---
+
+## 3. Run the workflow
+
+### Standard flow (recommended)
+
+```bash
+# Pre-flight
+sps doctor <project> --fix        # Health check first
+
+# Start pipeline (continuous mode, auto-exits when done)
+sps tick <project>
+
+# Monitor in separate terminal
+sps worker dashboard <project>
+```
+
+其余运行细节(Multi-project、JSON output mode、Tick cycle internals、State machine、SmartArrange)见 `references/workflow-internals.md`。
+
+---
+
+## Read before acting
+
+When you need command details or exact operating behavior, read:
+- `references/cli-quick-reference.md` — all commands with options
+- `references/operation-playbooks.md` — step-by-step procedures
+- `references/diagnostic-sequence.md` — diagnosis decision tree
+- `references/failure-patterns.md` — common failures and fixes
+
+## Key operating rules
+
+- Always pass the explicit project name
+- `sps` is globally installed; do not assume skill-local wrappers or legacy entry scripts
+- Prefer `sps doctor <project> --json` or `sps monitor tick <project> --json` as the first structured read when the workflow looks unhealthy
+- For multi-project work, use one `sps tick` process with multiple projects
+- Do not mutate PM state directly through provider-specific scripts if SPS has an equivalent command
+- Treat `sps tick` as the main loop; use subcommands for targeted inspection or intervention
+- When diagnosis points to configuration creation or repair, stop and confirm with Boss before writing config
+- When creating cards, add `--skill <type>` for specialized tasks
+
+## References
+
+渐进披露:主文件保留热路径 SOP,细节按需读 `references/`。
+
+- `references/preflight-and-setup.md` — §0 环境自检(CLI / env / 项目目录 / worker 工具)
+- `references/labels.md` — §2.3 标签体系(自动 / Skills / conflict / 辅助状态)
+- `references/workflow-internals.md` — §3 运行细节(多项目 / JSON / tick 周期 / 状态机 / SmartArrange)
+- `references/monitoring.md` — §4 监控 worker(状态 / dashboard / 确认 / 日志 / PM 状态)
+- `references/skills.md` — §5 Worker skills(注入顺序 / 管理 / 结构 / 内置 skill)
+- `references/mr-and-recovery.md` — §6/§8–§11 MR 合并流 / 恢复原则 / rules 文件 / 知识传递 / 附加接口
+- `references/troubleshooting.md` — §7 故障排查(诊断序列 / 常见问题 / 手动恢复 / 检查命令)

package/skills/sps/references/cli-quick-reference.md

@@ -0,0 +1,172 @@
+# SPS CLI Quick Reference (v0.58+)
+
+## Global options
+
+All commands support:
+- `--json` — structured JSON output
+- `--dry-run` — preview without executing
+- `--help` — show help
+- `--version` — show version number
+
+## Pre-flight checks
+
+```bash
+which sps                                  # Check installation
+sps --version                              # Check version (need 0.58+)
+npm install -g @coralai/sps-cli            # Install or update
+test -f ~/.coral/env && echo OK           # Check global config exists
+source ~/.coral/env                       # Load credentials into shell
+```
+
+## Setup and configuration
+
+```bash
+sps setup [--force]                        # Global environment wizard (preserves existing values)
+sps project init <project>                 # Initialize project management directory
+sps project doctor <project>               # Project health check (alias of sps doctor)
+sps status [--json]                        # Show running status of all projects
+sps doctor <project> [--fix] [--json]      # Health check (--fix auto-repair + generate CLAUDE.md)
+sps doctor <project> [--reset-state] [--skip-remote]  # Reset runtime state / skip GitLab API checks
+```
+
+## Card management
+
+```bash
+sps card add <project> "<title>" ["desc"] [--skill a,b] [--draft] [--json]
+                                           # Create card (default → Backlog, --draft → Planning);
+                                           # --skill writes skills into the card; AI-PIPELINE label auto-added
+sps card dashboard <project>               # Card board
+sps card mark-started <project> <seq>      # Mark started (used by Claude UserPromptSubmit hook)
+sps card mark-complete <project> <seq>     # Mark complete (used by Claude Stop hook)
+sps pm scan <project> [state]              # View card list (optional state filter)
+sps pm move <project> <seq> <state>        # Manual state transition
+sps pm comment <project> <seq> "<text>"    # Add comment to card
+sps pm label add|remove <project> <seq> <label>          # Add/remove a card label
+sps pm checklist create <project> <seq> "item1" "item2"  # Create checklist
+sps pm checklist list <project> <seq>      # View checklist
+sps pm checklist check <project> <seq> <item-id>         # Check item
+sps pm checklist uncheck <project> <seq> <item-id>       # Uncheck item
+```
+
+## Pipeline execution
+
+```bash
+sps tick <project> [project2 ...]          # Continuous run (auto-exit when done)
+sps tick <project> --json                  # Continuous run, JSON output (for cron)
+sps pipeline start|stop|status <project>   # Pipeline management (start = sps tick)
+sps pipeline board|workers|logs <project>  # Board / worker dashboard / logs shortcuts
+sps pipeline list|run|use <...>            # Custom pipelines
+sps scheduler tick <project> [--json]      # Planning → Backlog only (draft promotion)
+sps pipeline tick <project> [--json]       # Backlog → Todo → Inprogress only
+sps qa tick <project> [--json]             # QA closeout only
+sps monitor tick <project> [--json]        # Anomaly detection only
+sps smartarrange status|approve <project>  # SmartArrange (agent-drafted task list → approve → auto pipeline)
+sps reset <project> [--all] [--card N,N]   # Reset card state + clean worktree/branch for re-run
+sps stop <project> [--all]                 # Stop running tick process
+```
+
+## Worker management
+
+```bash
+sps worker ps <project>                    # Worker process status
+sps worker kill <project> <seq>            # Terminate a worker
+sps worker launch <project> <seq>          # Manual launch for specific card
+sps worker launch <project> <seq> --dry-run  # Preview launch
+sps worker dashboard [project ...]         # Real-time TUI (all projects, :=respond)
+sps worker dashboard --once                # Single snapshot
+sps worker dashboard --json                # JSON output
+```
+
+## Skills
+
+```bash
+sps skill list                             # List user-level skills + per-project link status
+sps skill add <name>                       # Symlink a skill into the current project
+sps skill remove <name>                    # Remove a skill from the current project
+sps skill sync [--force]                   # bundled → ~/.coral/skills/, then → ~/.claude/skills/
+```
+
+## Interfaces (console / graph / memory)
+
+```bash
+sps console [--port N] [--no-open] [--kill]  # Local web UI (board, chat, logs)
+sps graph build|sync|status                 # Build/refresh the project code graph
+sps graph explore <keyword>                 # Entry point + related symbols + call chains (token-cheap)
+sps graph impact <symbol>                   # What a change to a symbol affects
+sps memory list|search|add|ingest|context <project>  # Per-project memory (agentmemory)
+```
+
+## ACP session management
+
+```bash
+sps acp ensure <project> <slot> [tool]    # Create/reuse persistent session
+sps acp run <project> <slot> "<prompt>"   # Start a run on session
+sps acp status <project> [slot]           # Session/run status
+sps acp pending <project>                 # List pending confirmations
+sps acp respond <project> <slot> "<reply>"  # Send response to confirmation
+sps acp stop <project> <slot>             # Stop session
+```
+
+## Log viewing
+
+```bash
+sps logs [project]                         # Real-time log viewer (pm2-style)
+sps logs <project> --err                   # Error logs only
+sps logs <project> --lines <N>             # Last N lines
+sps logs <project> --no-follow             # Print and exit
+```
+
+## State machine
+
+```
+[Planning] → Backlog → Todo → Inprogress → Done
+  草稿卡     创建分支   创建worktree  AI编码    merge+释放
+  等派发     排队等待   分配Worker    执行任务   自动完成
+```
+
+`sps card add` 默认入 Backlog；`--draft` 才入 Planning（草稿，Scheduler 提升）。
+
+## Auxiliary labels
+
+| Label | Meaning |
+|-------|---------|
+| `AI-PIPELINE` | Card managed by SPS pipeline |
+| `BLOCKED` | Blocked by external dependency |
+| `NEEDS-FIX` | Worker or CI failure |
+| `WAITING-CONFIRMATION` | Worker awaiting destructive action approval |
+| `CONFLICT` | Merge conflict |
+| `STALE-RUNTIME` | Worker runtime anomaly |
+| `conflict:<domain>` | Conflict domain (same-domain cards don't run in parallel) |
+
+Skills are set at card-add time via `sps card add … --skill <name>` (written into the card, loaded from `~/.coral/skills/<name>/SKILL.md`), not via a manual label.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Business failure |
+| 2 | Argument error |
+| 3 | External dependency unavailable |
+
+## Key config files
+
+| File | Purpose |
+|------|---------|
+| `~/.coral/env` | Global credentials (GitLab, Matrix) |
+| `~/.coral/skills/<name>/SKILL.md` | Worker skill definitions (bundled by `sps setup`) |
+| `~/.coral/projects/<project>/conf` | Project configuration (shell script format) |
+| `~/.coral/projects/<project>/cards/` | Markdown PM cards (default backend) |
+| `~/.coral/projects/<project>/runtime/state.json` | Runtime state (worker slots, active cards) |
+| `~/.coral/projects/<project>/pipeline_order.json` | Queue pointer file (internal; cards run by seq — no manual edits needed) |
+| `~/.coral/projects/<project>/runtime/tick.lock` | Tick mutual exclusion lock |
+
+## Environment variables (runtime)
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `SPS_MANAGER_MAX_WORKERS` | 30 | Global worker limit across all projects |
+| `SPS_MANAGER_STAGGER_MS` | 5000 | Delay between worker starts |
+| `SPS_MANAGER_MAX_MEMORY_PERCENT` | 80 | Memory threshold for worker launch |
+| `SPS_DASHBOARD_INTERVAL` | 3000 | Dashboard refresh interval (ms) |
+| `DEBUG` | — | Enable debug logging |