环境初始化与恢复检测

本 skill 是迭代执行流水线的第一个子 skill，负责准备执行环境。 支持 Linux / macOS (Bash) 和 Windows (PowerShell) 双平台。 执行流程分为三个阶段，按顺序进行：

阶段 1: 信息检查 ─→ 阶段 2: 恢复检测 ─→ 阶段 3: 新流程初始化
                           │
                           └─ 检测到已有状态 → 执行恢复流程（不进入阶段 3）

Windows 首次运行：需先设置 UTF-8 编码：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

阶段 1: 信息检查

依次完成三项检查，任一失败则终止并告知用户。

1.1 确认本地 Git 项目

验证当前目录是一个有效的 git 仓库：

Linux / macOS (Bash):

git rev-parse --is-inside-work-tree

Windows (PowerShell):

git rev-parse --is-inside-work-tree

失败时终止，告知用户"当前目录不是 git 仓库，请在项目根目录下执行"。

同时采集项目基础信息供后续使用：

Linux / macOS (Bash):

MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
MAIN_BRANCH=${MAIN_BRANCH:-master}
PROJECT_PATH=$(git remote get-url origin | sed 's/.*://;s/\.git$//')

Windows (PowerShell):

$MAIN_BRANCH = (git symbolic-ref refs/remotes/origin/HEAD 2>$null) -replace '^refs/remotes/origin/',''
if (-not $MAIN_BRANCH) { $MAIN_BRANCH = 'master' }
$PROJECT_PATH = (git remote get-url origin) -replace '.*:','' -replace '\.git$',''

1.2 获取迭代信息

需要两个参数来调用 TAPD MCP iterations_get。参数确定前，先检查 project.json 是否存在：

workspace_id — 按以下优先级确定：

1. 用户消息中显式指定 → 直接使用
2. 项目根目录 project.json 中的 workspace_id → 读取并告知用户
3. 以上均无 → 询问用户输入

iteration_id — 按以下优先级确定：

1. 用户消息中显式指定 → 直接使用
2. 以上无 → 询问用户输入（无默认值，必须提供）

两个参数就绪后，调用 TAPD MCP 获取迭代详情：

调用 TAPD MCP: iterations_get
参数: workspace_id, id=iteration_id
返回: 迭代名称、起止时间等信息

调用失败时终止，提示用户检查 TAPD MCP 连接或参数是否正确。

1.3 解析迭代分支名称

从迭代名称中name提取版本号作为分支名。迭代名称规范为 iteration-vMAJOR.MINOR.x。

解析规则：提取 v 开头的版本部分作为分支名和目录名。

Linux / macOS (Bash):

VERSION=$(echo "${ITERATION_NAME}" | grep -oP 'v[\d.]+x?' || echo "${ITERATION_NAME}")

Windows (PowerShell):

$VERSION = if ($ITERATION_NAME -match 'v[\d.]+x?') { $Matches[0] } else { $ITERATION_NAME }

如果迭代名称不符合 iteration-vMAJOR.MINOR.x 规范，使用完整迭代名称作为 VERSION， 并提示用户确认。

补充信息采集

在信息检查阶段还需采集以下辅助信息：

owner（当前用户）：

1. 用户消息中显式指定 → 直接使用
2. project.json 中的 owner → 读取使用
3. 以上均无 → 询问用户

agent_tool（Agent 工具）： 从用户消息中提取工具名称（如"使用 claude 工具"→ claude），未指定时默认为 agent。

阶段 2: 恢复检测

检查 specs/${VERSION}/iteration-state.json 是否已存在。

不存在状态文件 → 进入阶段 3

状态文件不存在说明是全新迭代，直接进入阶段 3（新流程初始化）。

存在状态文件 → 执行恢复逻辑

读取已有的 iteration-state.json，根据状态决定后续动作：

恢复流程的详细规则参见 references/recovery.md，核心逻辑为：

1. 展示当前进度摘要（已完成/进行中/未开始的需求数）
2. 检查状态一致性
3. 按 sequence 顺序找到第一个未完成需求，根据其 phase 跳转对应子 skill
4. 如用户消息已表达继续意图（"帮我继续"、"接着做"），视为已确认直接恢复

注意：走恢复流程时不进入阶段 3，恢复完成后直接告知编排层从哪个子 skill 继续。

阶段 3: 新流程初始化

仅在阶段 2 确认无已有状态（或用户要求重新开始）时执行。

3.1 创建迭代分支

从主分支创建新的版本分支并推送到远程：

Linux / macOS (Bash):

git checkout -b "${VERSION}" "${MAIN_BRANCH}"
git push -u origin "${VERSION}"

Windows (PowerShell):

git checkout -b $VERSION $MAIN_BRANCH
git push -u origin $VERSION

如果分支已存在（如远程已有同名分支），切换到该分支而非报错：

Linux / macOS (Bash):

git checkout "${VERSION}" 2>/dev/null || git checkout -b "${VERSION}" "${MAIN_BRANCH}"
git push -u origin "${VERSION}" 2>/dev/null || true

Windows (PowerShell):

git checkout $VERSION 2>$null
if ($LASTEXITCODE -ne 0) { git checkout -b $VERSION $MAIN_BRANCH }
git push -u origin $VERSION 2>$null

3.2 创建迭代目录

Linux / macOS (Bash):

mkdir -p "specs/${VERSION}"

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "specs\$VERSION" | Out-Null

3.3 创建 iteration-state.json

在迭代目录下写入初始状态文件 specs/${VERSION}/iteration-state.json：

{
  "iteration_id": "<从 1.2 获取>",
  "workspace_id": "<从 1.2 确定>",
  "iteration_name": "<从 1.2 获取的迭代名称>",
  "owner": "<补充信息采集确定>",
  "project_path": "<从 1.1 采集>",
  "iter_branch": "<从 1.3 采集 VERSION>",
  "agent_tool": "<补充信息采集确定，默认 agent>",
  "patch": 0,
  "started_at": "<当前时间 ISO 8601>",
  "end_at": "",
  "status": "initialized",
  "all_parents": [],
  "selected_story": "",
  "stories": {},
  "sequence": []
}

all_parents，selected_story，stories 和 sequence 在本阶段留空，由 tapd-iteration-analysis 负责填充。

产出

本 skill 完成后，保证以下条件成立：

完成后告知编排层下一步进入哪个子 skill：

• 新流程 → tapd-iteration-analysis
• 恢复流程 → 由 references/recovery.md 映射表决定