openspec-workflow-guide

name	openspec-workflow-guide
description	交互式工作流向导——检查环境、追踪进度、引导用户完成 openspec-workflow 全流程（propose→plan→execute→status/archive）。基于 Markdown 状态文件跨 session 恢复。
license	MIT
compatibility	Requires openspec CLI v1.3.1+, git 2.25+, CMake
metadata	{"author":"sisyphus","version":"2.3","generatedBy":"1.3.1","user-invocable":true}

OpenSpec 工作流交互指南

工作方式

本技能扮演交互式向导角色，遵循 planning-with-files 的设计理念：

• 所有状态持久化到 Markdown 文件（而非 JSON）
• 每个步骤用 Question 工具提供选项（最后一个选项是输入）
• 用户只能通过选择选项进行交互，不能指定参数
• 新 session 开始时自动检查并恢复进度

skill_use("openspec-workflow-guide")   # 无参数版本

---

状态文件

文件	位置	用途
workflow-state.md	项目根目录（git 版本控制）	主要状态文件，记录进度和变更信息
workflow-progress.md	项目根目录（git 版本控制）	操作日志，记录每一步执行结果

---

workflow-state.md 格式

# OpenSpec 工作流状态

## 元信息
- **版本**: 1
- **创建时间**: 2026-05-18T10:00:00+08:00
- **最后更新**: 2026-05-18T10:30:00+08:00

## 工作流进度

### 阶段完成情况

| 阶段 | 状态 | 完成时间 |
|------|------|---------|
| setup | ✅ 完成 | 2026-05-18T10:00:00+08:00 |
| propose | 🔄 进行中 | 2026-05-18T10:15:00+08:00 |
| plan | ⏳ 未开始 | — |
| execute | ⏳ 未开始 | — |
| status_archive | ⏳ 未开始 | — |
| cleanup | ⏳ 未开始 | — |

## 当前状态

- **当前阶段**: propose
- **当前步骤**: select_change

### Changes（支持多 change 并行）

| 变更名称 | Worktree | Artifacts状态 | 进度 |
|----------|----------|--------------|------|
| fix-ns-pollution | .zcf/fix-ns-pollution-wt | ✅ 已提交 | 0/3 |
| add-stream-pipes | — | ⏳ 未提交 | — |

- **活跃 Changes**: [fix-ns-pollution, add-stream-pipes]
- **当前焦点变更**: fix-ns-pollution
- **Worktree 映射**:
  - fix-ns-pollution → .zcf/fix-ns-pollution-wt (openspec/fix-ns-pollution)
  - add-stream-pipes → (未创建)

## 操作历史

| 时间 | 阶段 | 操作 | 结果 |
|------|------|------|------|
| 2026-05-18T10:00:00+08:00 | setup | env_check | ok |
| 2026-05-18T10:15:00+08:00 | propose | select_change | fix-ns-pollution |

---

workflow-progress.md 格式

# OpenSpec 工作流进度日志

## Session 信息
- **开始时间**: 2026-05-18T10:00:00+08:00
- **结束时间**: —
- **活跃 Changes**: fix-ns-pollution, add-stream-pipes

## 操作日志

### 2026-05-18T10:00:00+08:00 [setup / env_check]
**动作**: 检查环境
**结果**: ✅ openspec CLI 正常，git 工作区干净，build 目录存在

**下一步**: 进入 Propose 阶段

### 2026-05-18T10:15:00+08:00 [propose / create_change × 2]
**动作**: 创建多个 change
**结果**: ✅ fix-ns-pollution, add-stream-pipes 均已创建 artifacts

**下一步**: 决定是否为这些 change 创建 worktree（进入 Plan 阶段）

---

入口流程

每次调用 skill_use("openspec-workflow-guide") 时：

步骤 0：检查状态文件

STATE_FILE="workflow-state.md"
PROGRESS_FILE="workflow-progress.md"

if [ -f "$STATE_FILE" ]; then
    # 读取并展示当前状态
    echo "📂 发现已保存的进度"
    CURRENT_PHASE=$(awk '/\*\*当前阶段\*\*/{getline; gsub(/^\*\*|\*\*$/,""); print}' "$STATE_FILE")
    CHANGE=$(awk '/\*\*变更名称\*\*/{getline; gsub(/^\*\*|\*\*$/,""); print}' "$STATE_FILE")
    echo "   当前阶段: $CURRENT_PHASE"
    echo "   变更: ${CHANGE:-（无）}"
    echo ""
    # 展示阶段完成情况
    echo "已完成阶段:"
    grep "✅" "$STATE_FILE" | head -5
    echo ""
else
    echo "🆕 未发现已保存的进度，开始全新流程。"
    CURRENT_PHASE="setup"
fi

步骤 1：环境检查（setup 阶段）

执行环境检测，检查清单：

echo "🔍 环境检查..."
echo ""

# 1. openspec CLI
OPENSPEC_PATH=$(command -v openspec 2>/dev/null || echo "/home/ubuntu/.npm-global/bin/openspec")
if [ -x "$OPENSPEC_PATH" ]; then
    OPENSPEC_VER=$("$OPENSPEC_PATH" --version 2>/dev/null || echo "?")
    echo "✅ openspec CLI: $OPENSPEC_VER"
    OPENSPEC_OK=true
else
    echo "❌ openspec CLI 未找到"
    OPENSPEC_OK=false
fi

# 2. git 状态
GIT_CLEAN=$(git status --porcelain | wc -l)
if [ "$GIT_CLEAN" -eq 0 ]; then
    echo "✅ git 工作区干净"
else
    echo "⚠️  git 工作区有 $GIT_CLEAN 个未跟踪/修改文件"
fi

# 3. 当前分支
CURRENT_BRANCH=$(git branch --show-current)
echo "📌 当前分支: $CURRENT_BRANCH"

# 4. worktree 列表
echo "📂 Worktrees:"
git worktree list | sed 's/^/   /'

# 5. 构建目录
if [ -d "build" ]; then
    echo "✅ 构建目录存在 (build/)"
else
    echo "⚠️  构建目录不存在"
fi

# 6. 已有 change
ACTIVE=$(ls -d openspec/changes/*/ 2>/dev/null | grep -v archive/ | wc -l)
echo "📋 活跃 changes: $ACTIVE"

展示环境状态 + 选项：

使用 question 工具询问用户：

环境检查结果：

✅ openspec CLI: 1.3.1 (/home/ubuntu/.npm-global/bin/openspec)
✅ git 工作区干净
📌 当前分支: main
📂 Worktrees: (无)
✅ 构建目录存在
📋 活跃 changes: 0

当前状态: 未开始任何变更流程

请选择:
1. 继续 → 进入 Propose 阶段（扫描建议）
2. 修复 PATH（显示如何添加 openspec 到 PATH）
3. 重新检查（刷新环境状态）
i. 其他输入

步骤 2：进入对应阶段

根据当前阶段跳转到对应入口。

工作流状态恢复

当检测到已完成 setup 但有已创建的 worktree 时，自动判断当前状态：

# 检查是否有已创建的 worktree
WORKTREE_COUNT=$(git worktree list | grep "openspec/" | wc -l)

if [ "$WORKTREE_COUNT" -gt 0 ]; then
    echo ""
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo "📋 发现 $WORKTREE_COUNT 个 worktree 已就绪"
    echo ""
    echo "请选择:"
    echo "1. ✅ 进入 Execute 监控模式（监控所有 worktree 进度）"
    echo "2. 🔄 返回 Plan 阶段（查看或创建更多 worktree）"
    echo "3. ↩️ 返回 Propose 阶段（创建更多 change）"
    echo "i. 其他输入"
fi

---

阶段入口

阶段 1：setup — 环境检查

入口条件：首次调用或 state 文件不存在。

环境检测命令：

# openspec CLI 检测
OPENSPEC_PATH=$(command -v openspec 2>/dev/null || echo "/home/ubuntu/.npm-global/bin/openspec")

# git 状态
GIT_STATUS=$(git status --porcelain)

# 当前分支
CURRENT_BRANCH=$(git branch --show-current)

# worktree 列表
WORKTREE_LIST=$(git worktree list)

# 构建目录
BUILD_EXISTS=$([ -d "build" ] && echo "yes" || echo "no")

# 活跃 changes
ACTIVE_CHANGES=$(ls -d openspec/changes/*/ 2>/dev/null | grep -v archive/ | wc -l)

菜单选项：

环境检查完成。检测到：

  openspec CLI: ✅ 1.3.1
  git 工作区:  ✅ 干净
  当前分支:    main
  Worktrees:   无
  构建目录:    ✅ 存在
  活跃 changes: 0

请选择:
1. ✅ 继续 → 进入 Propose 阶段
2. 🔄 重新检查
i. 其他操作

---

阶段 2：propose — 扫描并创建 Change

入口条件：setup 已完成，且当前阶段为 propose。

行为：

本阶段所有扫描和创建逻辑委托给 openspec-workflow-propose 技能。 guide 作为交互式向导，展示提议技能的结果，让用户选择，然后调用提议技能的创建逻辑。

交互流程：

1. 扫描阶段：调用 openspec-workflow-propose 执行扫描，生成/更新 proposal-suggestions.md
2. 选择阶段：展示扫描结果（从 proposal-suggestions.md 读取），让用户选择
3. 创建阶段：用户选择后，调用 openspec-workflow-propose --create <name> 执行创建
4. 循环：创建后重新展示，用户可继续选或选「完成 Propose 阶段」

注意：guide 不直接调用 openspec new/openspec propose 命令。所有创建逻辑由 openspec-workflow-propose 技能处理。

显示与执行分离：

guide 负责显示扫描结果和接收用户选择，但创建操作通过调用 openspec-workflow-propose 技能完成。

# 展示当前活跃 changes
echo "📋 当前已创建的 Changes:"
ls -d openspec/changes/*/ 2>/dev/null | grep -v archive/ | while read dir; do
    name=$(basename "$dir")
    committed=$(git show HEAD:"openspec/changes/$name/.openspec.yaml" > /dev/null 2>&1 && echo "✅" || echo "⏳")
    echo "  - $name  [Artifacts: $committed]"
done

# 检查建议列表
if [ -f "proposal-suggestions.md" ]; then
    echo ""
    echo "📂 已有的建议列表 (proposal-suggestions.md)"
    cat proposal-suggestions.md
else
    echo ""
    echo "🆕 开始扫描..."
    skill_use("openspec-workflow-propose")
fi

用户选择后的处理：

当用户选择某个建议进行创建时，guide 调用 openspec-workflow-propose 执行创建：

if [ "$choice" = "1" ]; then
    # 创建 fix-ns-pollution
    skill_use("openspec-workflow-propose", "--create", "fix-ns-pollution")
elif [ "$choice" = "2" ]; then
    # 创建 add-stream-pipes
    skill_use("openspec-workflow-propose", "--create", "add-stream-pipes")
fi

建议列表选项（每次创建后重新展示）：

建议列表（来自 ADR 扫描 + 代码 TODO）：

🔴 高优先级
1. fix-ns-pollution  — 修复命名空间污染 (ADR-033, 3 个任务)
2. add-stream-pipes  — 实现 Stream 管道操作符 (ADR-022, 5 个任务)

🟡 中优先级
3. add-cdc-support   — 跨时钟域支持 (架构差距分析)

当前已创建: fix-ns-pollution ✅

请选择:
1. 创建 fix-ns-pollution（已存在的跳过）
2. 创建 add-stream-pipes
3. 创建 add-cdc-support
4. ✅ 完成 Propose 阶段 → 进入 Plan 阶段
5. 📋 查看所有已创建的 change 详情
i. 手动输入 change 名称

创建后重新进入此阶段：

每次创建完成后，重新检查建议列表 + 活跃 changes，重新展示选项菜单（循环）。

Propose 阶段完成条件：

用户选择「4. 完成 Propose 阶段」后，验证至少有一个 change 的 artifacts 已提交，然后推进到 plan。

---

阶段 3：plan — Commit + Worktree + 计划

入口条件：propose 已完成，且当前阶段为 plan。

前置说明：

每个 change 独立经历 plan→execute→archive。用户选择要处理的 change 后，为其创建 worktree 并生成计划。

行为：

1. 展示所有活跃 changes 的状态列表
2. 用户选择要处理的 change（或选「全部创建 worktree」）
3. 对选中的 change 执行 COMMIT GATE
4. 创建 branch + worktree
5. 在 worktree 内生成 Prometheus 计划
6. 更新 state 文件

展示所有活跃 changes 的状态：

echo "📋 所有活跃 Changes:"
echo ""
echo "| 变更 | Artifacts | Worktree | 计划文件 |"
echo "|-----|-----------|----------|---------|"
for name in $ACTIVE_CHANGES; do
    committed=$(git show HEAD:"openspec/changes/$name/.openspec.yaml" > /dev/null 2>&1 && echo "✅" || echo "⏳")
    wt_path=".zcf/${name}-wt"
    wt_exists=$([ -d "$wt_path" ] && git worktree list | grep -q "$wt_path" && echo "✅" || echo "❌")
    plan_exists=$([ -f "$wt_path/.sisyphus/plans/$name.md" ] 2>/dev/null && echo "✅" || echo "❌")
    echo "| $name | $committed | $wt_exists | $plan_exists |"
done

选择要处理的 change：

Plan 阶段

📋 活跃 Changes:
| 变更 | Artifacts | Worktree | 计划文件 |
|-----|-----------|----------|---------|
| fix-ns-pollution | ✅ | ❌ | ❌ |
| add-stream-pipes | ✅ | ❌ | ❌ |

请选择:
1. 为 fix-ns-pollution 创建 worktree + 生成计划
2. 为 add-stream-pipes 创建 worktree + 生成计划
3. 批量处理：全部为已提交的变化创建 worktree
4. 🔄 切换当前焦点变更（选择另一个变更作为焦点）
5. ↩️ 返回 Propose 阶段（创建更多 change）
i. 其他输入

选项 1/2 执行内容（以 fix-ns-pollution 为例）：

CHANGE_NAME="fix-ns-pollution"

# COMMIT GATE - 脏检测
if [ -n "$(git status --porcelain "openspec/changes/$CHANGE_NAME/")" ]; then
    echo "⚠️  检测到未提交的修改，提示用户提交或放弃"
fi

# COMMIT GATE - 是否已 commit
if ! git show HEAD:"openspec/changes/$CHANGE_NAME/.openspec.yaml" > /dev/null 2>&1; then
    echo "❌ Artifacts 尚未提交，请先提交"
    # 回到菜单
fi

# 创建 branch（如不存在）
if ! git branch --list "openspec/$CHANGE_NAME" | grep -q "openspec/$CHANGE_NAME"; then
    git branch "openspec/$CHANGE_NAME" HEAD
fi

# 创建 worktree（带目录冲突检测）
if [ -d ".zcf/${CHANGE_NAME}-wt" ]; then
    if git worktree list | grep -q ".zcf/${CHANGE_NAME}-wt"; then
        echo "⚠️  Worktree 已存在"
    else
        echo "❌ 目录冲突，请先清理: rm -rf .zcf/${CHANGE_NAME}-wt"
    fi
else
    git worktree add ".zcf/${CHANGE_NAME}-wt" "openspec/$CHANGE_NAME"
fi

echo "✅ Worktree 已创建: .zcf/${CHANGE_NAME}-wt"

Worktree 创建完成 → 进入执行模式选择：

${CHANGE_NAME} worktree 已就绪，请选择执行方式：

📋 ${CHANGE_NAME} 状态:
  Worktree: .zcf/${CHANGE_NAME}-wt
  计划文件: .sisyphus/plans/${CHANGE_NAME}.md ✅
  任务数: 3

请选择执行方式:
1. 🔒 在此 session 执行（阻塞）— 等待任务完成后返回
2. 🔓 分离执行（新终端）— 给出操作指引，立即返回
i. 其他输入

选项 1（阻塞执行）执行内容：

cd ".zcf/${CHANGE_NAME}-wt"
skill_use("openspec-workflow-execute")
cd /workspace/project/CppHDL
# execute 会阻塞直到所有任务完成
# 更新 state

选项 2（分离执行）输出指引：

echo ""
echo "🔓 分离执行指引"
echo ""
echo "为 ${CHANGE_NAME} 启动分离执行："
echo ""
echo "1. 在新终端中执行："
echo "   cd $(pwd)/.zcf/${CHANGE_NAME}-wt"
echo "   skill_use(\"openspec-workflow-execute\")"
echo ""
echo "2. execute 结果会自动写入 tasks.md"
echo ""
echo "3. 完成后，在此 session 运行 guide 查看最新进度"
echo ""
echo "当前状态：${CHANGE_NAME} 等待分离执行"

返回 Plan 前的检查 — 是否进入监控：

# 检查所有已创建 worktree 的数量
WORKTREE_COUNT=$(git worktree list | grep "openspec/" | wc -l)

if [ "$WORKTREE_COUNT" -gt 0 ]; then
    echo ""
    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
    echo "📋 发现 $WORKTREE_COUNT 个 worktree 已就绪"
    echo ""
    echo "请选择:"
    echo "1. ✅ 进入 Execute 监控模式（实时监控所有 worktree 进度）"
    echo "2. 🔄 继续返回 Plan 阶段（创建更多 worktree 或处理其他 change）"
    echo "i. 其他输入"
fi

---

阶段 4：execute — 监控与执行

定位：Execute 阶段是监控模式——读取 tasks.md 进度、显示所有 worktree 状态、提供执行入口。不是实际执行者。

前置检测（每次入口执行）：

# 读取所有 tasks.md 的实际进度，同步到 state
echo "📋 所有 Worktrees 实际进度:"

LAST_CHECK=$(date "+%Y-%m-%d %H:%M:%S")

for wt in $(git worktree list | grep "openspec/" | awk '{print $1}'); do
    branch=$(git worktree list | grep "$wt" | awk '{print $3}')
    name=$(echo "$branch" | sed 's|openspec/||')
    tasks_file="$wt/openspec/changes/$name/tasks.md"

    if [ -f "$tasks_file" ]; then
        total=$(grep -c "^- \[" "$tasks_file" 2>/dev/null || echo 0)
        done=$(grep -c "^- \[x\]" "$tasks_file" 2>/dev/null || echo 0)
        progress="${done}/${total}"
        # 读取 tasks.md 中是否有正在执行的任务（[~] 标记）
        running=$(grep "^- \[~\]" "$tasks_file" 2>/dev/null | wc -l)
    else
        progress="?"
    fi
    echo "  $name → $progress"
done

echo ""
echo "上次检测: $LAST_CHECK"

菜单选项：

Execute 阶段（监控模式）

📋 所有 Worktrees 状态:（实时读取 tasks.md）
| 变更 | Worktree | 进度 | 执行状态 |
|-----|----------|------|---------|
| fix-ns-pollution | .zcf/fix-ns-pollution-wt | 1/3 | 🔒 执行中 |
| add-stream-pipes | .zcf/add-stream-pipes-wt | 2/5 | 🔓 分离执行 |

上次检测: 2026-05-18 10:35:00

请选择:
1. 🔒 在此 session 执行 fix-ns-pollution（阻塞）
2. 🔓 分离执行 fix-ns-pollution（新终端）
3. 🔒 在此 session 执行 add-stream-pipes（阻塞）
4. 🔓 分离执行 add-stream-pipes（新终端）
5. 📋 查看任务列表（指定变更）
6. 🔧 运行构建验证（指定变更）
7. 🔄 刷新进度（重新读取所有 tasks.md）
8. ↩️ 返回 Plan 阶段（创建更多 worktree）
i. 其他输入

选项 7（刷新进度）执行内容：

# 重新读取所有 tasks.md 进度
echo "🔄 正在刷新进度..."
LAST_CHECK=$(date "+%Y-%m-%d %H:%M:%S")
# 重新显示表格
# 用户选择后继续循环

选项 1/3（阻塞执行）执行内容：

CHANGE_NAME="fix-ns-pollution"
WORKTREE_PATH=".zcf/${CHANGE_NAME}-wt"

cd "$WORKTREE_PATH"
skill_use("openspec-workflow-execute")
# 阻塞等待所有任务完成
cd /workspace/project/CppHDL

# 更新 state 进度
# （execute 已更新 tasks.md，这里读取同步到 state）

选项 2/4（分离执行）输出指引：

echo ""
echo "🔓 分离执行指引"
echo ""
echo "为 ${CHANGE_NAME} 启动分离执行："
echo ""
echo "1. 在新终端中执行："
echo "   cd $(pwd)/.zcf/${CHANGE_NAME}-wt"
echo "   skill_use(\"openspec-workflow-execute\")"
echo ""
echo "2. execute 结果会自动写入 tasks.md"
echo ""
echo "3. 完成后，在此 session 运行 guide 查看最新进度"
echo ""
echo "当前状态：${CHANGE_NAME} 🔓 分离执行中"

状态更新：将执行状态设为 🔓，下次入口时通过 tasks.md 同步实际进度。

监控说明：

• Guide 不执行任务，只监控
• 进度来自 tasks.md 的 grep -c "^- \[x\]"
• 执行状态列说明：
  • 🔒 执行中 — 此 session 正在阻塞执行
  • 🔓 分离执行 — 在新终端执行，不阻塞
  • ⏳ 等待 — 未开始
  • ✅ 完成 — 所有任务完成

---

阶段 5：status_archive — 状态检查与归档

入口条件：execute 已完成（所有 worktree 的任务都完成），或用户主动选择此阶段。

前置说明：

每个 change 独立归档。可以一次性归档所有已完成的 change，或逐个处理。

展示所有 change 状态：

Status 阶段

📋 所有 Changes 状态:
| 变更 | Worktree | 任务进度 | 状态 |
|-----|----------|---------|------|
| fix-ns-pollution | .zcf/fix-ns-pollution-wt | 3/3 ✅ | 可归档 |
| add-stream-pipes | .zcf/add-stream-pipes-wt | 2/5 🔄 | 进行中 |

请选择:
1. 归档 fix-ns-pollution（merge → archive → cleanup）
2. 归档 add-stream-pipes（需先完成所有任务）
3. 📊 全局概览（所有 change + worktree）
4. 🔍 详细检测（同步问题等）
5. ↩️ 返回 Execute 阶段
i. 其他输入

归档流程（选项 1/2）：

# 对选定的 change 执行归档
CHANGE_NAME="fix-ns-pollution"

# 1. merge worktree → main
cd ".zcf/${CHANGE_NAME}-wt"
git checkout main
git merge --ff-only "openspec/$CHANGE_NAME"

# 2. archive
openspec archive "$CHANGE_NAME" --yes

# 3. cleanup
git worktree remove ".zcf/${CHANGE_NAME}-wt"
git branch -d "openspec/$CHANGE_NAME"

cd /workspace/project/CppHDL

echo "✅ $CHANGE_NAME 已归档"

# ============================================================
# P0 FIX: 归档后检查是否还有其他 change 需要处理
# ============================================================
# 使用 awk 检查分支名（第二列）而非路径，避免路径含 openspec/ 的误匹配
REMAINING_WT=$(git worktree list | awk '$2 ~ /^openspec\// {print $1}' | wc -l)
if [ "$REMAINING_WT" -gt 0 ]; then
    echo ""
    echo "📋 还有 $REMAINING_WT 个 worktree 正在进行"
    echo ""
    echo "请选择:"
    echo "1. 继续处理其他 worktree（进入 Execute 阶段）"
    echo "2. 返回 Plan 阶段（为其他 change 创建 worktree）"
    echo "i. 其他输入"
else
    # 没有更多 worktree，检查 proposal-suggestions.md
    echo ""
    echo "📋 所有 worktree 已处理完毕"
    if [ -f "proposal-suggestions.md" ]; then
        REMAINING_SUGGESTIONS=$(grep -c "status: 待创建" "proposal-suggestions.md" 2>/dev/null || echo "0")
        if [ "$REMAINING_SUGGESTIONS" -gt 0 ]; then
            echo "⚠️  proposal-suggestions.md 中还有 $REMAINING_SUGGESTIONS 个未创建的 change"
            echo ""
            echo "请选择:"
            echo "1. 回到 Propose 阶段（创建更多 change）"
            echo "2. 进入 Plan 阶段（为已创建的 change 创建 worktree）"
            echo "3. 完成 workflow"
            echo "i. 其他输入"
        else
            echo "✅ 所有建议已处理完毕"
            echo "请选择:"
            echo "1. 进入 cleanup 阶段"
            echo "2. 完成 workflow"
            echo "i. 其他输入"
        fi
    else
        echo "✅ 无剩余建议"
        echo "请选择:"
        echo "1. 进入 cleanup 阶段"
        echo "2. 完成 workflow"
        echo "i. 其他输入"
    fi
fi

更新 state：从活跃 changes 列表移除已归档的 change。

---

阶段 6：cleanup — 测试清理

入口条件：所有活跃 changes 均已归档后，或用户主动选择。

菜单选项：

清理选项

📋 Worktrees: (列出所有剩余 worktree)
📋 Branches: (列出所有 openspec/* branches)

请选择:
1. 🧹 清理指定 worktree + branch
2. 🗑️ 清理所有 worktree + openspec/* branches
3. 📝 输出测试总结报告（所有 changes 的执行记录）
4. ↩️ 返回上一阶段
i. 其他输入

选项 1 执行：

请选择要清理的 worktree:
1. fix-ns-pollution (.zcf/fix-ns-pollution-wt)
2. add-stream-pipes (.zcf/add-stream-pipes-wt)

选项 2 执行：

# 清理所有 worktree
for wt in $(git worktree list | grep "openspec/" | awk '{print $1}'); do
    git worktree remove "$wt" 2>/dev/null || true
done

# 清理所有 openspec/* branches
git branch | grep "openspec/" | while read branch; do
    git branch -d "$branch" 2>/dev/null || true
done

# 清理状态文件
rm -f workflow-state.md workflow-progress.md

echo "✅ 所有 worktree 和 openspec/* branches 已清理"

---

状态更新

每次操作后，使用 Write 工具更新文件：

workflow-state.md 更新

每次操作后，更新 workflow-state.md。重点是 Changes 表格：

# OpenSpec 工作流状态

## 元信息
- **版本**: 1
- **创建时间**: 2026-05-18T10:00:00+08:00
- **最后更新**: 2026-05-18T10:30:00+08:00

## 工作流进度

### 阶段完成情况

| 阶段 | 状态 | 完成时间 |
|------|------|---------|
| setup | ✅ 完成 | 2026-05-18T10:00:00+08:00 |
| propose | 🔄 进行中 | — |
| plan | 🔄 进行中 | — |
| execute | ⏳ 未开始 | — |
| status_archive | ⏳ 未开始 | — |
| cleanup | ⏳ 未开始 | — |

## 当前状态

- **当前阶段**: plan
- **当前步骤**: worktree_created

### Changes（支持多 change 并行）

| 变更名称 | Worktree | Artifacts状态 | 进度 | 执行状态 |
|----------|----------|--------------|------|---------|
| fix-ns-pollution | .zcf/fix-ns-pollution-wt ✅ | ✅ 已提交 | 0/3 | ⏳ 等待执行 |
| add-stream-pipes | .zcf/add-stream-pipes-wt ✅ | ✅ 已提交 | 0/5 | ⏳ 等待执行 |

- **活跃 Changes**: [fix-ns-pollution, add-stream-pipes]
- **当前焦点变更**: fix-ns-pollution
- **Worktree 映射**:
  - fix-ns-pollution → .zcf/fix-ns-pollution-wt (openspec/fix-ns-pollution)
  - add-stream-pipes → .zcf/add-stream-pipes-wt (openspec/add-stream-pipes)
- **执行状态**:
  - 🔒 执行中 — 在此 session 阻塞执行
  - 🔓 分离执行 — 在新终端执行，不阻塞
  - ⏳ 等待执行 — 未开始
  - ✅ 完成 — 所有任务完成
- **每个变更独立推进**：每个 change 各自经历 plan→execute→archive，可并行进行

workflow-state.md 更新示例

# OpenSpec 工作流状态

## 元信息
- **版本**: 1
- **创建时间**: 2026-05-18T10:00:00+08:00
- **最后更新**: 2026-05-18T10:35:00+08:00

## 工作流进度

### 阶段完成情况

| 阶段 | 状态 | 完成时间 |
|------|------|---------|
| setup | ✅ 完成 | 2026-05-18T10:00:00+08:00 |
| propose | ✅ 完成 | 2026-05-18T10:10:00+08:00 |
| plan | 🔄 进行中 | — |
| execute | 🔄 进行中 | — |
| status_archive | ⏳ 未开始 | — |
| cleanup | ⏳ 未开始 | — |

## 当前状态

- **当前阶段**: execute
- **当前步骤**: monitoring

### Changes（支持多 change 并行）

| 变更名称 | Worktree | Artifacts状态 | 进度 | 执行状态 |
|----------|----------|--------------|------|---------|
| fix-ns-pollution | .zcf/fix-ns-pollution-wt ✅ | ✅ 已提交 | 1/3 | 🔒 执行中 |
| add-stream-pipes | .zcf/add-stream-pipes-wt ✅ | ✅ 已提交 | 0/5 | 🔓 等待分离执行 |

- **活跃 Changes**: [fix-ns-pollution, add-stream-pipes]
- **当前焦点变更**: fix-ns-pollution
- **Worktree 映射**:
  - fix-ns-pollution → .zcf/fix-ns-pollution-wt (openspec/fix-ns-pollution)
  - add-stream-pipes → .zcf/add-stream-pipes-wt (openspec/add-stream-pipes)
- **执行状态**:
  - 🔒 执行中 — 在此 session 阻塞执行
  - 🔓 分离执行 — 在新终端执行，不阻塞
  - ⏳ 等待执行 — 未开始
  - ✅ 完成 — 所有任务完成
- **每个变更独立推进**：每个 change 各自经历 plan→execute→archive，可并行进行

workflow-progress.md 更新示例

### 2026-05-18T10:35:00+08:00 [execute / separate_spawn]
**动作**: 为 add-stream-pipes 启动分离执行
**结果**: 🔓 分离执行指引已输出，等待在新终端执行

**下一步**: 继续监控 fix-ns-pollution 执行进度，或返回 Plan 创建更多 worktree

---

状态推进规则

重要说明：阶段（propose/plan/execute/status_archive）是全局阶段，表示整体向导进度。但每个 change 独立经历各自的 plan→execute→archive 流程。「当前焦点变更」表示用户当前正在操作的变更。

阶段完成条件	推进到
环境检测完成（openspec 可用 + build 存在）	propose
用户明确选择「完成 Propose 阶段」	plan
为焦点变更创建了 worktree + 计划文件	execute
任何时候都可以返回 plan 添加更多 worktree	plan
焦点变更的所有任务完成（tasks 全部 [x]）	status_archive
所有活跃 changes 均完成或归档	propose 或 cleanup

---

全局导航

每个菜单最后都包含：

...
请选择:
1. [阶段相关选项]
2. [阶段相关选项]
i. 其他输入（AI 会解释收到输入后如何处理）

通用导航项（出现在每个菜单）：

选项	含义
i	最后一项，接收用户自由输入。AI 收到后解释输入内容并执行相应操作，或引导用户回到适合的选项

---

错误处理

错误场景	响应
openspec CLI 不可用	提示安装，提供安装命令，选项 1 变为「修复后继续」
artifacts 未提交	展示具体未提交文件，提供「现在提交」选项
worktree 目录冲突	提示目录已存在，提供「清理后重试」选项
构建失败	记录到 progress.md，提供「查看错误详情」选项
plan 文件不存在	提示先生成计划，提供相应选项

---

使用方式

# 启动向导（唯一方式）
skill_use("openspec-workflow-guide")

无参数版本：不接受任何参数，每次调用从头开始检查状态并提供当前阶段合适的选项。