@coralai/sps-cli 0.57.14 → 0.58.0

package/project-template/.claude/CLAUDE.md

@@ -0,0 +1,81 @@
+# Project Rules (Claude Code Worker)
+
+<!--
+  This file is auto-generated by `sps project init` / `sps doctor --fix`.
+  Edit it to add project-specific rules. SPS will not overwrite it once it exists.
+-->
+
+## Scope
+
+- Work only in the current project directory.
+- Do NOT read or modify files outside this directory.
+- Do NOT explore `~/.coral/projects/...` or other system paths.
+
+## Reading code (token-efficient — prefer this)
+
+This project may have a **code graph**. When it does, use it INSTEAD of reading
+files one-by-one — one query returns the relevant symbols, their source, and
+call paths, which is far cheaper in tokens than grepping and reading whole files.
+Run these from the project root (your cwd):
+
+- `sps graph explore <keywords>` — entry points + related symbols + source + call paths for an area
+- `sps graph node <symbol>` — one symbol's definition + its callers/callees
+- `sps graph query <name>` — find symbols by name
+- `sps graph callers <symbol>` / `sps graph impact <symbol>` — who calls it / what a change affects
+
+Fall back to reading files directly only when the graph is missing what you need
+(or `sps graph status` shows it isn't built).
+
+## SPS Pipeline Context
+
+This project is driven by SPS (Smart Pipeline System). Each card is a task.
+When you are launched as a worker, two env vars identify your stable context:
+
+- `$SPS_PROJECT` — project name (stable across card reuse)
+- `$SPS_WORKER_SLOT` — worker slot name (stable across card reuse)
+
+Per-card information (card id, stage name, title) is **not** in env. POSIX
+freezes env at spawn, so any per-card value would go stale once the claude
+process is reused for the next card. If you need the current card info,
+read the marker file or use the `sps` CLI:
+
+- Marker file: `~/.coral/projects/$SPS_PROJECT/runtime/worker-$SPS_WORKER_SLOT-current.json`
+- CLI: `sps card dashboard $SPS_PROJECT` (or the command your task prompt already passed to you)
+
+## Card lifecycle labels (for reference — all managed automatically)
+
+Each card moves through these labels during its pipeline run:
+
+- `AI-PIPELINE` — added at `sps card add`; the pipeline admission mark
+- `CLAIMED` — added when SPS claims a worker slot for this card
+- `STARTED-<stage>` — added automatically on each prompt submit via the
+  **UserPromptSubmit** hook. This is the "ACK signal" that proves Claude
+  received the prompt. If this label doesn't appear within
+  `WORKER_ACK_TIMEOUT_S` seconds after dispatch, SPS's MonitorEngine flags
+  `ACK-TIMEOUT` and StageEngine kills the worker + retries.
+- `COMPLETED-<stage>` — added on turn end via the **Stop hook**. Tells SPS
+  to advance the card to the next stage (or Done).
+
+You do NOT need to manually update card state, move the card between
+columns, or commit on behalf of the pipeline. The hooks do it all.
+
+**Honesty note**: If you declare "done" without actually implementing the
+work, the pipeline will still advance (the Stop hook fires regardless). The
+user relies on your honesty here.
+
+## Memory
+
+- Claude's **auto memory** is enabled and stored under
+  `~/.coral/projects/$SPS_PROJECT/memory/`. You write to `MEMORY.md` there
+  to persist knowledge across sessions.
+- Use `sps memory add $SPS_PROJECT --type ...` to write structured SPS memories
+  (conventions, decisions, lessons) for the human to curate.
+
+## Git (if the project uses git)
+
+- Claude handles all git operations itself (commit, push, etc.).
+- SPS does NOT intervene in git workflows or conflict resolution.
+
+## Project-specific rules
+
+<!-- Add your own conventions, architecture notes, and constraints below. -->

package/project-template/.claude/hooks/start.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# SPS Pipeline Worker — UserPromptSubmit hook (v0.42.0+)
+#
+# Triggered synchronously before Claude processes each prompt. Used by SPS
+# to label the card with STARTED-<stage> — this is the "ACK signal" that
+# proves Claude received the prompt. Also injects skill hints based on the
+# card's `skills` field (or legacy skill:* labels).
+#
+# Phase 2 is user-customizable: add audit logging, request rate limiting,
+# prompt enrichment, etc. without touching Phase 1.
+#
+# Env vars (stable across claude process reuse):
+#   SPS_PROJECT       Project name
+#   SPS_WORKER_SLOT   Worker slot name
+#
+# Per-card info (card id, stage, title) is NOT in env — POSIX env freezes at
+# spawn. Hook scripts must read the marker file instead. Phase 1 does this
+# automatically via `sps hook user-prompt-submit`.
+
+set -e
+
+# ─── Phase 1: SPS official action (do NOT remove) ────────────────────
+# Reads marker file → addLabel STARTED-<stage> + emit skill hints.
+sps hook user-prompt-submit
+
+# ─── Phase 2: User-customizable actions (edit as needed) ────────────
+
+# Example: audit log of every prompt submission.
+# if [ -n "$SPS_PROJECT" ] && [ -n "$SPS_WORKER_SLOT" ]; then
+#   echo "$(date): prompt submitted to $SPS_PROJECT/$SPS_WORKER_SLOT" \
+#     >> "$CLAUDE_PROJECT_DIR/.sps/user-prompts.log"
+# fi
+
+# Example: rate limiting (block if too many prompts in a window).
+# count=$(find "$CLAUDE_PROJECT_DIR/.sps" -name 'last-prompt-*' -mmin -1 | wc -l)
+# if [ "$count" -gt 30 ]; then
+#   echo '{"decision":"block","reason":"rate limit exceeded (>30 prompts/min)"}'
+#   exit 0
+# fi
+
+# Example: prompt-to-Slack mirror for team visibility.
+# curl -sfX POST "$SLACK_WEBHOOK" -d "{\"text\":\"[$SPS_PROJECT] new prompt\"}"
+
+exit 0

package/project-template/.claude/hooks/stop.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# SPS Pipeline Worker — Stop hook
+#
+# Triggered when Claude finishes its current turn. The pipeline depends on
+# Phase 1 to advance card state. Phase 2+ is user-customizable.
+#
+# Env vars (set by SPS worker at spawn time, frozen for the process lifetime):
+#   SPS_PROJECT       Project name (stable across card reuse)
+#   SPS_WORKER_SLOT   Worker slot name (stable across card reuse)
+#
+# These two env vars form the index to locate the per-slot marker file:
+#   ~/.coral/projects/$SPS_PROJECT/runtime/worker-$SPS_WORKER_SLOT-current.json
+#
+# Per-card info (card id, stage name, card title) is intentionally NOT in env.
+# POSIX freezes env at spawn; when the claude process is reused for the next
+# card, any per-card env would go stale. Always read the marker file (or use
+# `sps` CLI) to get current card information.
+#
+# Claude-native env also available:
+#   CLAUDE_PROJECT_DIR, CLAUDE_SESSION_ID
+
+set -e
+
+# ─── Phase 1: SPS official action (do NOT remove) ────────────────────
+# Mark the card complete so pipeline can advance state.
+# We call mark-complete WITHOUT a seq — the command reads the per-slot
+# current-card marker file (written by the worker manager on each dispatch)
+# to get the authoritative current card. This is the only way to be correct
+# when the same claude process handles multiple cards in sequence.
+if [ -n "$SPS_PROJECT" ] && [ -n "$SPS_WORKER_SLOT" ]; then
+  # 绝不让 mark-complete 失败阻塞 stop:Stop hook 非零退出会被 claude 当成"别停、继续",
+  # 导致 worker 被无限重戳("Acknowledged." 死循环)。失败仅记 stderr(MonitorEngine 有超时兜底)。
+  sps card mark-complete "$SPS_PROJECT" || echo "[stop.sh] mark-complete non-fatal failure — allowing stop" >&2
+fi
+
+# ─── Phase 2: User-customizable actions (edit as needed) ────────────
+
+# Example: record the session transcript location for later audit.
+# if [ -n "$CLAUDE_SESSION_ID" ] && [ -n "$SPS_CARD_ID" ]; then
+#   echo "$CLAUDE_SESSION_ID" >> "$CLAUDE_PROJECT_DIR/.sps/session-log.txt"
+# fi
+
+# Example: third-party knowledge base capture.
+# if command -v your-kb-cli &>/dev/null; then
+#   your-kb-cli capture --project "$SPS_PROJECT" --session "$CLAUDE_SESSION_ID"
+# fi
+
+# Example: notify on completion.
+# sps notify matrix "[$SPS_PROJECT] seq $SPS_CARD_ID ($SPS_STAGE) done"
+
+# Example: post-task CI trigger.
+# curl -sfX POST "$CI_WEBHOOK" -d "{\"project\":\"$SPS_PROJECT\",\"card\":\"$SPS_CARD_ID\"}"
+
+exit 0

package/project-template/.claude/settings.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/start.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  },
+  "companyAnnouncements": [
+    "🔧 SPS Pipeline Worker — completion is declared via Stop hook \u2192 COMPLETED-<stage> label"
+  ]
+}

package/project-template/.claude/settings.local.json.template

@@ -0,0 +1,3 @@
+{
+  "autoMemoryDirectory": "~/.coral/projects/__PROJECT__/memory"
+}

package/project-template/README.md

@@ -0,0 +1,10 @@
+# Project Template
+
+This folder is copied into `~/.coral/projects/<project-name>/` for each new pipeline-managed project.
+
+Contents:
+- `conf` — project-specific configuration
+- `deploy.sh` — optional project-local deploy entrypoint
+- `batch_scheduler.sh` — project-local Planning → Backlog scheduler
+- `logs/` — runtime logs
+- `pm_meta/` — local PM metadata store (used especially for Plane)

package/project-template/batch_scheduler.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# batch_scheduler.sh — project-local cron entry point
+# Delegates to the SPS CLI tick command.
+set -euo pipefail
+
+PROJECT_NAME="$(basename "$(cd "$(dirname "$0")" && pwd)")"
+
+exec sps tick "$PROJECT_NAME" "$@"

package/project-template/conf.template

@@ -0,0 +1,61 @@
+# ── 项目基础信息 ─────────────────────────────────────────────────
+export PROJECT_NAME="__PROJECT_NAME__"
+
+# ── 路径配置（可选，不设置则使用默认值）───────────────────────────
+# 业务代码仓库目录（默认: ~/projects/<project>）
+# export PROJECT_DIR="$HOME/projects/__PROJECT_NAME__"
+# Worker worktree 根目录（默认: ~/.coral/worktrees/）
+# export WORKTREE_DIR="$HOME/.coral/worktrees"
+
+# ── GitLab（项目特有）──────────────────────────────────────────
+# GITLAB_URL / GITLAB_TOKEN 从全局 ~/.coral/env 继承，此处不重复
+export GITLAB_PROJECT="__GITLAB_PROJECT__"
+# GITLAB_PROJECT_ID 可选 — 留空则通过 GITLAB_PROJECT 路径自动查询
+# export GITLAB_PROJECT_ID=""
+export GITLAB_MERGE_BRANCH="develop"
+
+# ── PM Backend ───────────────────────────────────────────────────
+export PM_TOOL="plane"
+
+# ── Trello（PM_TOOL=trello 时填写）───────────────────────────────
+# TRELLO_API_KEY / TRELLO_TOKEN 从全局 ~/.coral/env 继承
+# export TRELLO_BOARD_ID=""
+# export TRELLO_LIST_PLANNING=""
+# export TRELLO_LIST_BACKLOG=""
+# export TRELLO_LIST_TODO=""
+# export TRELLO_LIST_INPROGRESS=""
+# export TRELLO_LIST_QA=""
+# export TRELLO_LIST_DONE=""
+# export TRELLO_ACCOUNT=""
+
+# ── Plane（PM_TOOL=plane 时填写）────────────────────────────────
+# PLANE_URL / PLANE_API_KEY / PLANE_WORKSPACE_SLUG 从全局 ~/.coral/env 继承
+export PLANE_PROJECT_ID="__PLANE_PROJECT_ID__"
+export PLANE_STATE_PLANNING="__PLANE_STATE_PLANNING__"
+export PLANE_STATE_BACKLOG="__PLANE_STATE_BACKLOG__"
+export PLANE_STATE_TODO="__PLANE_STATE_TODO__"
+export PLANE_STATE_INPROGRESS="__PLANE_STATE_INPROGRESS__"
+export PLANE_STATE_QA="__PLANE_STATE_QA__"
+export PLANE_STATE_DONE="__PLANE_STATE_DONE__"
+
+# ── Pipeline ─────────────────────────────────────────────────────
+export PIPELINE_LABEL="AI-PIPELINE"
+export MR_MODE="none"
+
+# ── Worker / Agent ───────────────────────────────────────────────
+# claude is the only supported CLI; no selector exposed.
+export MAX_CONCURRENT_WORKERS=3
+# export MAX_ACTIONS_PER_TICK=1
+# export WORKER_RESTART_LIMIT=2
+# export DEFAULT_WORKER_SKILLS="senior"
+
+# ── 超时与策略（可选，以下为默认值）──────────────────────────────
+# export INPROGRESS_TIMEOUT_HOURS=8
+# export MONITOR_AUTO_QA=false
+# export CONFLICT_DEFAULT=serial
+# export TICK_LOCK_TIMEOUT_MINUTES=30
+
+# ── 通知（项目特有 — 不同项目可发不同房间）──────────────────────
+# MATRIX_HOMESERVER / MATRIX_ACCESS_TOKEN 从全局 ~/.coral/env 继承
+# 如果项目需要发到特定房间，设置 MATRIX_ROOM_ID：
+# export MATRIX_ROOM_ID=""

package/project-template/deploy.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+echo "Deployment not configured for ${PROJECT_NAME:-unknown-project}"