specline 1.0.0 → 1.1.0

package/templates/.cursor/hooks/specline-session-start.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# specline-session-start.sh — sessionStart Hook
+# 新会话启动时检测活跃 pipeline 并注入上下文到 Agent 系统提示
+#
+# Input (stdin JSON):
+#   { "session_id": "...", "is_background_agent": bool, "composer_mode": "agent"|"ask"|"edit", ... }
+#
+# Output (stdout JSON):
+#   { "additional_context": "<pipeline 上下文>" }  或  {}（无活跃 pipeline）
+
+set -euo pipefail
+
+input=$(cat)
+
+# 跳过 background agent（子 Agent 不需要 pipeline 上下文）
+is_bg=$(echo "$input" | jq -r '.is_background_agent // false')
+if [ "$is_bg" = "true" ]; then
+  echo '{}'
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CHANGES_DIR="$PROJECT_ROOT/specline/changes"
+
+# 无 changes 目录 → 无 pipeline
+if [ ! -d "$CHANGES_DIR" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# 扫描活跃 pipeline（排除 archive/）
+active_pipelines=""
+pipeline_count=0
+first_change=""
+first_phase=""
+
+for state_file in "$CHANGES_DIR"/*/.pipeline-state.json; do
+  [ -f "$state_file" ] || continue
+
+  # 跳过 archive/
+  parent_dir=$(dirname "$state_file")
+  if echo "$parent_dir" | grep -q "/archive/"; then
+    continue
+  fi
+
+  change_name=$(jq -r '.change_name // "unknown"' "$state_file" 2>/dev/null)
+  phase=$(jq -r '.current_phase // "unknown"' "$state_file" 2>/dev/null)
+  status=$(jq -r ".phases.${phase}.status // \"unknown\"" "$state_file" 2>/dev/null)
+
+  # 跳过已完成/已归档的
+  if [ "$phase" = "archive" ] || [ "$status" = "completed" ]; then
+    continue
+  fi
+
+  # 收集活跃 pipeline 信息
+  if [ $pipeline_count -eq 0 ]; then
+    first_change="$change_name"
+    first_phase="$phase"
+  fi
+  pipeline_count=$((pipeline_count + 1))
+
+  # 构建任务进度信息
+  completed=$(jq -r '[.phases.coding.tasks[]? | select(.status == "completed")] | length' "$state_file" 2>/dev/null || echo "0")
+  total=$(jq -r '[.phases.coding.tasks[]?] | length' "$state_file" 2>/dev/null || echo "0")
+
+  active_pipelines="${active_pipelines}- **${change_name}**: ${phase} 阶段"
+  if [ "$total" != "0" ] && [ "$phase" = "coding" ]; then
+    active_pipelines="${active_pipelines} (${completed}/${total} 任务完成)"
+  fi
+  active_pipelines="${active_pipelines}\n"
+done
+
+# 无活跃 pipeline → 透明放行
+if [ $pipeline_count -eq 0 ]; then
+  echo '{}'
+  exit 0
+fi
+
+# 构建阶段约束说明
+phase_constraints() {
+  case "$1" in
+    spec)
+      echo "- 只能通过 specline-spec-creator / specline-spec-reviewer 子 Agent 工作"
+      echo "- 禁止编辑任何应用代码文件（.ts/.tsx/.py/.go 等）"
+      echo "- 规划文件生成后需运行 Spec Gate"
+      ;;
+    coding)
+      echo "- 编码必须通过子 Agent：specline-frontend-dev / specline-backend-dev"
+      echo "- 禁止直接编辑应用代码文件"
+      echo "- 每批次任务完成后运行 Build Gate"
+      echo "- 每个 Task 完成后更新 tasks.md 的 checkbox"
+      ;;
+    code_review)
+      echo "- 只能运行 specline-code-reviewer + Lint Gate"
+      echo "- 如需修复代码，通过子 Agent 完成"
+      ;;
+    test)
+      echo "- 运行测试 Gate 链：unit → integration → e2e"
+      echo "- 测试失败时通过 specline-test-runner 分析原因"
+      echo "- 代码修复通过子 Agent，测试修复通过 specline-test-writer"
+      ;;
+    *)
+      echo "- 遵循 specline-pipeline SKILL 的当前阶段约束"
+      ;;
+  esac
+}
+
+# 生成上下文
+constraints=$(phase_constraints "$first_phase")
+
+# 用 printf 构建 JSON，避免 heredoc 中的转义问题
+# 注意：additional_context 内容中的换行符和引号需要正确转义
+context_text=""
+context_text+="🚨 **Specline Pipeline 运行中**\n\n"
+if [ $pipeline_count -eq 1 ]; then
+  context_text+="**当前变更**: ${first_change}\n"
+  context_text+="**当前阶段**: ${first_phase}\n\n"
+else
+  context_text+="**活跃变更** (${pipeline_count} 个):\n${active_pipelines}\n"
+fi
+context_text+="**阶段约束**:\n${constraints}\n\n"
+context_text+="**重要**: 你是 Specline Pipeline 编排者。上述约束具有最高优先级，必须在每个操作前检查是否符合当前阶段要求。"
+
+# 转义 JSON 字符串
+escaped_context=$(echo -e "$context_text" | jq -Rs '.')
+
+cat << EOF
+{
+  "additional_context": ${escaped_context}
+}
+EOF
+
+exit 0

package/templates/.cursor/hooks.json

@@ -1,10 +1,31 @@
 {
   "version": 1,
   "hooks": {
+    "sessionStart": [
+      {
+        "command": ".cursor/hooks/specline-session-start.sh",
+        "timeout": 10
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": ".cursor/hooks/specline-phase-guard.sh",
+        "matcher": "Write|StrReplace|EditNotebook|Task|Delete",
+        "timeout": 5,
+        "failClosed": false
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": ".cursor/hooks/specline-reminder.sh",
+        "matcher": "Task|Write|StrReplace|Shell",
+        "timeout": 5
+      }
+    ],
     "subagentStart": [
       {
         "command": ".cursor/hooks/specline-agent-guard.sh",
-        "matcher": "specline-spec-creator|specline-spec-reviewer|specline-frontend-dev|specline-backend-dev|specline-code-reviewer|specline-test-writer|specline-test-runner",
+        "matcher": "specline-spec-creator|specline-spec-reviewer|specline-frontend-dev|specline-backend-dev|specline-config-dev|specline-code-reviewer|specline-config-reviewer|specline-test-writer|specline-test-runner",
         "failClosed": true
       }
     ],

package/templates/.cursor/skills/specline-apply-change/SKILL.md

@@ -13,6 +13,27 @@ Implement tasks from a Specline change.
 
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
+## 速览 (Layer 1)
+
+> **一句话**：实现 Specline change 中的编码任务。
+> **入口**：`/specline-apply-change [change-name]` 或直接说「继续实现」
+> **流程**：选 change → 读上下文 → 逐任务实现 → 标记完成
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
+
+**开始前请确认：**
+- [ ] Change 已选中（`/specline-pipeline --change <name>`）
+- [ ] 已读取 proposal.md（知道做什么）
+- [ ] 已读取 spec.md（知道需求和场景）
+- [ ] 已读取 design.md（知道技术决策）
+- [ ] 已读取 tasks.md（知道实现清单）
+
+## 详细步骤 — Happy Path (Layer 2)
+
 **Steps**
 
 1. **Select the change**
@@ -48,7 +69,7 @@ Implement tasks from a Specline change.
    - Progress: "N/M tasks complete"
    - Remaining tasks overview
 
-6. **Implement tasks (loop until done or blocked)**
+5. **Implement tasks (loop until done or blocked)**
 
    For each pending task:
    - Show which task is being worked on
@@ -63,7 +84,7 @@ Implement tasks from a Specline change.
    - Error or blocker encountered → report and wait for guidance
    - User interrupts
 
-7. **On completion or pause, show status**
+6. **On completion or pause, show status**
 
    Display:
    - Tasks completed this session
@@ -71,6 +92,10 @@ Implement tasks from a Specline change.
    - If all done: suggest archive
    - If paused: explain why and wait for guidance
 
+## 输出模板 & 高级话题 (Layer 3)
+
+### 输出模板
+
 **Output During Implementation**
 
 ```
@@ -122,7 +147,7 @@ All tasks complete! Ready to archive this change.
 What would you like to do?
 ```
 
-**Guardrails**
+### Guardrails
 - Keep going through tasks until done or blocked
 - Always read context files before starting (from the apply instructions output)
 - If task is ambiguous, pause and ask before implementing
@@ -131,10 +156,12 @@ What would you like to do?
 - Update task checkbox immediately after completing each task
 - Pause on errors, blockers, or unclear requirements - don't guess
 - Use contextFiles from CLI output, don't assume specific file names
+- **Hook blocked → no silent fallback**: If this skill is invoked because a coding subagent (specline-frontend-dev / specline-backend-dev) was blocked by a hook, you MUST first notify the user of the blocking cause and attempt diagnosis. Do not silently execute tasks that should have been handled by the blocked subagent. Reference the Hook Blocking Resolution Protocol in the specline-pipeline skill.
 
-**Fluid Workflow Integration**
-
-This skill supports the "actions on a change" model:
+### 暂停场景处理
 
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
+当实现过程中出现以下情况时，暂停并等待用户指引：
+- 任务描述不清晰 → 请求用户澄清
+- 实现中暴露出设计问题 → 建议更新 Artifact（proposal / spec / design / tasks）
+- 遇到错误或阻塞 → 报告具体问题并等待指导
+- 用户主动中断 → 记录当前进度，下次可从断点继续

package/templates/.cursor/skills/specline-archive-change/SKILL.md

@@ -9,11 +9,31 @@ metadata:
   generatedBy: "1.3.1"
 ---
 
-Archive a completed change in the experimental workflow.
+## TL;DR (Layer 1)
+
+> **一句话**：归档已完成的 Specline change。
+> **入口**：`/specline-archive-change [change-name]`
+> **流程**：选 change → 检查完成度 → Delta spec sync 决策 → 移动目录 → 完成
+
+### 归档前后目录结构变化
+
+```
+归档前 (活跃、可修改)              归档后 (只读、可追溯)
+
+specline/changes/                  specline/changes/
+├── my-change/          ──▶       ├── archive/
+│   ├── proposal.md               │   └── 2026-06-01-my-change/
+│   ├── design.md                 │       ├── proposal.md
+│   ├── tasks.md                  │       ├── design.md
+│   └── specs/                    │       ├── tasks.md
+                                  │       └── specs/
+```
 
 **Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
 
-**Steps**
+---
+
+## Steps (Layer 2 — Happy Path)
 
 1. **If no change name provided, prompt for selection**
 
@@ -52,6 +72,18 @@ Archive a completed change in the experimental workflow.
 
 4. **Assess delta spec sync state**
 
+   **决策流程：**
+
+   ```
+   Delta specs 存在？
+   ├── 否 → 直接归档
+   └── 是 → 比较 delta spec 与 main spec
+              ├── 无差异 → 「已同步」→ 直接归档
+              └── 有差异 → 展示变更摘要 → 询问用户
+                            ├── 同步 → 执行 sync → 归档
+                            └── 跳过 → 归档
+   ```
+
    Check for delta specs at `specline/changes/<name>/specs/`. If none exist, proceed without sync prompt.
 
    **If delta specs exist:**
@@ -91,7 +123,7 @@ Archive a completed change in the experimental workflow.
    - Whether specs were synced (if applicable)
    - Note about any warnings (incomplete artifacts/tasks)
 
-**Output On Success**
+### Output On Success
 
 ```
 ## Archive Complete
@@ -104,7 +136,10 @@ Archive a completed change in the experimental workflow.
 All artifacts complete. All tasks complete.
 ```
 
-**Guardrails**
+---
+
+## Guardrails (Layer 3 — 高级话题)
+
 - Always prompt for change selection if not provided
 - Use artifact graph (specline-pipeline-gate.sh artifacts --json) for completion checking
 - Don't block archive on warnings - just inform and confirm

package/templates/.cursor/skills/specline-explore/SKILL.md

@@ -9,6 +9,11 @@ metadata:
   generatedBy: "1.3.1"
 ---
 
+> **One-liner**: You're a thinking partner, not an implementer.
+> **What you can do**: Read code, draw diagrams, compare options, ask questions, challenge assumptions
+> **What you can't do**: Write implementation code
+> **Characteristic**: No fixed steps, no mandatory outputs — the thinking itself is the value
+
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
 **IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create Specline artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
@@ -19,12 +24,21 @@ Enter explore mode. Think deeply. Visualize freely. Follow the conversation wher
 
 ## The Stance
 
-- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
-- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
-- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
-- **Adaptive** - Follow interesting threads, pivot when new information emerges
-- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
-- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+**✅ DO:**
+- **Curious, not prescriptive** — Ask questions naturally, don't follow a script
+- **Open threads, not interrogations** — Surface multiple directions, let the user follow what resonates
+- **Visual** — Use ASCII diagrams liberally
+- **Adaptive** — Follow interesting threads, pivot when new information emerges
+- **Patient** — Don't rush to conclusions, let patterns emerge
+- **Grounded** — Explore the actual codebase, don't just theorize
+
+**❌ DON'T:**
+- **Don't implement** — Never write implementation code
+- **Don't follow a script** — No fixed workflow or mandatory outputs
+- **Don't rush to conclusions** — Thinking time is not task time
+- **Don't force structure** — Let patterns emerge naturally
+- **Don't auto-capture** — Offer to save insights, don't assume
+- **Don't cut exploration short** — Follow valuable tangents
 
 ---
 
@@ -77,7 +91,7 @@ Depending on what the user brings, you might:
 
 ## Specline Awareness
 
-You have full context of the OpenSpec system. Use it naturally, don't force it.
+You have full context of the Specline system. Use it naturally, don't force it.
 
 ### Check for context
 
@@ -132,17 +146,6 @@ If the user mentions a change or you detect one is relevant:
 
 ---
 
-## What You Don't Have To Do
-
-- Follow a script
-- Ask the same questions every time
-- Produce a specific artifact
-- Reach a conclusion
-- Stay on topic if a tangent is valuable
-- Be brief (this is thinking time)
-
----
-
 ## Handling Different Entry Points
 
 **User brings a vague idea:**