@coralai/sps-cli 0.34.0 → 0.34.1

package/skills/sps-pipeline/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: sps-pipeline
+description: |
+  SPS pipeline management — create YAML configs, manage task cards, start/stop pipelines,
+  memory system, and monitor worker status. Use when asked to "create a pipeline", "set up a project",
+  "add tasks", "start the pipeline", "check pipeline status", or manage SPS workflow.
+  Proactively use when the user discusses project setup, task planning, or CI/CD automation. (🪸 Coral SPS)
+---
+
+# SPS Pipeline Management (v0.34.0)
+
+Manage the full lifecycle of SPS development pipelines: project setup, YAML configuration, task cards, memory system, and pipeline execution.
+
+## Interactive Pipeline Creation
+
+When the user asks to create a pipeline, set up a project, or configure YAML, follow this guided flow:
+
+### Step 1: Gather project info
+
+Ask the user:
+1. **项目名称** — 用于 SPS 内部标识（如 `my-app`）
+2. **代码仓库路径** — 本地路径（如 `~/projects/my-app`）
+3. **Git 远程仓库** — GitLab/GitHub 项目路径（如 `user/my-app`），留空则跳过
+4. **合并目标分支** — 默认 `main`
+5. **PM 后端** — `markdown`（本地文件，零配置）/ `plane` / `trello`
+
+### Step 2: Design the pipeline stages
+
+Ask the user:
+1. **你的开发流程有几个阶段？** 常见选择：
+   - **简单**（1 stage）：开发完直接 Done
+   - **标准**（2 stages）：开发 → 合并
+   - **完整**（3+ stages）：开发 → Code Review → 测试 → 合并
+2. **每个阶段用什么 Agent？** — `claude`（默认）/ `codex` / `gemini`
+3. **需要什么 skill profile？** — 如 `frontend`、`backend`、`phaser`（可选，留空用默认）
+4. **最大并发 Worker 数？** — 默认 `1`
+
+### Step 3: Generate and deploy
+
+Based on the answers:
+1. Run `sps project init <name>` if project doesn't exist
+2. Generate the pipeline YAML file at `<repo>/.sps/pipelines/project.yaml`
+3. Update project conf at `~/.coral/projects/<name>/conf`
+4. Run `sps doctor <name> --fix` to validate
+5. Show the user the generated YAML and explain each section
+
+### Pipeline YAML location
+
+The YAML file goes in the **project repository** (not ~/.coral/):
+```
+<project-repo>/
+└── .sps/
+    └── pipelines/
+        └── project.yaml    ← pipeline definition
+```
+
+`.sps/` should be in `.gitignore` (sps doctor --fix handles this automatically).
+
+### Example conversation
+
+User: "帮我创建一个新项目的 pipeline"
+
+Agent flow:
+1. Ask project name and repo path
+2. Ask how many stages they want
+3. Ask agent preference
+4. Generate YAML + conf
+5. Run doctor to validate
+6. Show next steps (add cards, start pipeline)
+
+---
+
+## Quick Reference
+
+### Project Setup
+
+```bash
+# Install SPS CLI
+npm install -g @coralai/sps-cli
+
+# Initial setup (creates directories, installs skills, configures credentials)
+sps setup
+
+# Initialize a new project
+sps project init <project-name>
+
+# Edit project config
+vim ~/.coral/projects/<project-name>/conf
+
+# Health check
+sps doctor <project-name> --fix
+```
+
+### Pipeline YAML Configuration
+
+Create `.sps/pipelines/<name>.yaml` in the project repo. Minimum viable config (1 stage):
+
+```yaml
+mode: project
+
+states:
+  backlog: Backlog
+  ready: Todo
+  done: Done
+
+stages:
+  - name: develop
+    trigger: "card_enters 'Todo'"
+    card_state: Inprogress
+    agent: claude
+    completion: git-evidence
+    on_complete: "move_card Done"
+```
+
+Multi-stage example (any number of stages):
+
+```yaml
+mode: project
+
+states:
+  backlog: Backlog
+  ready: Ready
+  done: Done
+
+stages:
+  - name: develop
+    trigger: "card_enters 'Ready'"
+    card_state: Active
+    agent: claude
+    profile: fullstack
+    completion: git-evidence
+    on_complete: "move_card CodeReview"
+    on_fail:
+      action: "label NEEDS-FIX"
+      comment: "Development worker failed."
+
+  - name: code-review
+    trigger: "card_enters 'CodeReview'"
+    card_state: CodeReview
+    agent: claude
+    profile: reviewer
+    completion: exit-code
+    on_complete: "move_card QA"
+
+  - name: integrate
+    trigger: "card_enters 'QA'"
+    card_state: QA
+    agent: claude
+    completion: fast-forward-merge
+    on_complete: "move_card Done"
+    queue: fifo
+```
+
+Only 3 fixed state roles required (backlog/ready/done). All intermediate states come from each stage's `card_state` and `on_complete`.
+
+### Pipeline Switching
+
+```bash
+sps pipeline list
+sps pipeline use <project> <pipeline-name>
+```
+
+### Card Management
+
+```bash
+sps card add <project> "Task title" --desc "Description"
+sps card dashboard <project>
+sps reset <project> <seq1> <seq2> ...
+```
+
+### Pipeline Execution
+
+```bash
+# Start continuous pipeline
+sps tick <project>
+# or: sps pipeline start <project>
+
+# Stop pipeline
+sps stop <project>
+
+# Check status
+sps status
+```
+
+### Worker Monitoring
+
+```bash
+sps worker ps <project>
+sps worker kill <project> <seq>
+sps worker dashboard <project>
+```
+
+### Memory System
+
+Three-layer persistent memory at `~/.coral/memory/`:
+
+```bash
+# View memory index
+sps memory list <project>
+
+# Generate memory context for prompt injection
+sps memory context <project>
+
+# Add memory entries
+sps memory add <project> --type convention --name "API naming" --body "Use camelCase"
+sps memory add <project> --type decision --name "Use PostgreSQL" --body "Concurrent writes needed"
+sps memory add <project> --type lesson --name "Migration order" --body "Schema first, then data"
+sps memory add <project> --type reference --name "Design docs" --body "figma.com/file/..."
+```
+
+Types: `convention` (no decay), `decision` (slow decay), `lesson` (30-day decay), `reference` (no decay).
+
+Workers receive memory in their prompt and can write new memories directly to `~/.coral/memory/projects/<name>/`.
+
+### Skill Management
+
+```bash
+sps skill sync
+```
+
+## Architecture
+
+```
+SchedulerEngine (orchestration)
+  → Backlog cards with AI-PIPELINE label → Ready
+
+StageEngine × N (execution, YAML-driven)
+  → Each stage: trigger → launch worker → completion → state transition
+  → First stage: creates branch + worktree
+  → Last stage: releases resources + cleans worktree
+
+MonitorEngine (monitoring)
+  → Heartbeat / stale detection across all stages
+```
+
+## Card State Flow
+
+Fully configurable. Only 3 fixed roles:
+
+```
+Backlog → Ready → [Stage 1] → [Stage 2] → ... → Done
+```
+
+## Key Config Fields (conf)
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `PROJECT_NAME` | Project identifier | `my-project` |
+| `PROJECT_DIR` | Repository path | `~/projects/my-project` |
+| `GITLAB_PROJECT` | Git remote project path | `user/repo` |
+| `GITLAB_MERGE_BRANCH` | Merge target branch | `main` |
+| `PM_TOOL` | PM backend | `plane` / `trello` / `markdown` |
+| `WORKER_TOOL` | Default AI agent | `claude` / `codex` |
+| `MAX_CONCURRENT_WORKERS` | Max parallel workers | `1-5` |
+
+## Card Labels
+
+| Label | Purpose |
+|-------|---------|
+| `AI-PIPELINE` | Marks card for pipeline processing (required) |
+| `skill:xxx` | Load specific skill profile for worker |
+| `conflict:xxx` | Conflict domain (same domain = serial execution) |
+| `NEEDS-FIX` | Worker failed, needs manual fix |
+| `BLOCKED` | External dependency blocking |
+
+## Troubleshooting
+
+```bash
+sps doctor <project> --fix
+sps logs <project>
+ls ~/.coral/projects/<project>/logs/acp-stderr-*.log
+sps reset <project> <seq>
+```

package/profiles/_template.md

@@ -1,48 +0,0 @@
----
-name: template
-description: Template for creating worker skill profiles
----
-
-# Role
-
-Define the worker's professional identity and primary expertise.
-Example: "You are a senior frontend engineer specializing in React and TypeScript."
-
-# Standards
-
-Non-negotiable coding standards and quality requirements.
-- Language-specific rules (strict mode, linting, formatting)
-- Architecture patterns to follow
-- Anti-patterns to avoid
-
-# Architecture
-
-Preferred architecture patterns and file organization.
-- Directory structure conventions
-- State management approach
-- Component/module patterns
-
-# Patterns
-
-Common code patterns with examples. Include real, copy-pasteable code.
-
-## Pattern Name
-```language
-// code example
-```
-
-# Testing
-
-Testing strategy, frameworks, and coverage requirements.
-- Test framework and assertion library
-- What to test (unit, integration, e2e)
-- Coverage target
-- Mocking strategy
-
-# Quality Metrics
-
-Measurable success criteria.
-- Performance targets
-- Bundle size limits
-- Accessibility scores
-- Coverage percentages

package/profiles/critic.md

@@ -1,35 +0,0 @@
----
-name: critic
-description: Devil's advocate for technical discussions — challenges assumptions, finds blind spots, argues alternative positions
----
-
-# Role
-
-You are a technical critic and devil's advocate. Your job is to challenge ideas, find weaknesses in arguments, and present strong counterarguments. You are NOT trying to be difficult — you are trying to make the final decision better by stress-testing it.
-
-# Standards
-
-- Challenge every assumption. If someone says "X is better", ask "better for whom? under what conditions?"
-- Provide specific counterarguments, not vague objections
-- Back up your critique with concrete examples, data points, or real-world failure cases
-- Acknowledge when an argument is strong — don't argue for the sake of arguing
-- Offer alternative approaches the original author may not have considered
-- Point out risks, edge cases, and failure modes
-- Consider operational complexity, not just technical elegance
-- Think about the 6-month and 2-year consequences, not just today
-
-# Anti-patterns (do NOT do these)
-
-- Do not agree with the original position to be polite
-- Do not make generic objections ("this might be complex") — be specific
-- Do not dismiss the original argument entirely — engage with it seriously
-- Do not propose solutions unless asked — focus on exposing problems
-- Do not repeat the original text back — add new perspectives
-
-# Output Format
-
-Write your critique in clear sections:
-1. What the original argument gets right (briefly)
-2. Key challenges and counterarguments (the bulk of your output)
-3. Risks and blind spots not addressed
-4. Alternative approaches worth considering