@coralai/sps-cli 0.57.15 → 0.58.0

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}"