spec-start

当用户开始新的开发任务、需要启动完整 Spec 流程（需求对齐→探索→设计→实现→测试→收尾），或需要为一个新 Spec 创建协作上下文和 GitHub Flow 工作分支时使用。不要用于已有完成 Spec 的小迭代（用 spec-update）或项目首次初始化（用 spec-init）。

설치로 이동

저장소: HHU3637kr/skills
최근 소스 활동: 2026년 8월 28일 14:57
감지된 SKILL.md 언어: 중국어
스타: 144
포크: 20

설치 방법

기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.

npx skills add https://github.com/HHU3637kr/skills --skill spec-start

명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.

로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.

소스 파일 검토

설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.

SKILL.md

소스 지침 · 읽기 전용 미리보기

검색으로 돌아가기 설치로 돌아가기

SKILL.md

소스 지침 · 읽기 전용 미리보기

disable-model-invocation	true
name	spec-start
description	当用户开始新的开发任务、需要启动完整 Spec 流程（需求对齐→探索→设计→实现→测试→收尾），或需要为一个新 Spec 创建协作上下文和 GitHub Flow 工作分支时使用。不要用于已有完成 Spec 的小迭代（用 spec-update）或项目首次初始化（用 spec-init）。

Spec Start

核心原则

当前 Agent 即是 TeamLead：调用本 Skill 的 Agent 本身就承担 TeamLead 职责，无需创建额外的 TeamLead 角色
角色定义由 spec-init 持久化：spec-start 只加载和唤起项目级角色，不内联维护角色 prompt
本次 Spec 创建运行实例：角色线程/实例在当前 Spec 生命周期内尽量保持可恢复，跨 Spec 状态必须文件化
角色 vs Skill 区分：角色（spec-writer）是 Who，Skill（spec-write）是 How
TeamLead 统一协调：所有阶段转换、跨角色通信和用户确认节点均由 TeamLead（当前 Agent）主导
分支隔离：每个 Spec 默认从远程默认分支创建独立工作分支，禁止直接在默认分支上实现。默认分支名不写死——用 git symbolic-ref refs/remotes/origin/HEAD 读取（常见为 main 或 master）

前置检查

启动前检查项目是否已初始化：

ls spec/context/experience/index.md
ls .agents/roles/spec-explorer.md

如果 spec/ 目录或 .agents/roles/ 缺失，提示用户先执行 /spec-init 完成项目初始化。若是旧项目已初始化但缺少角色定义，可只补齐 spec-init 的项目级角色步骤。

同时检查 Git 状态：

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

如果不是 Git 仓库，询问用户是否继续无分支模式；如果工作区有无关改动，先让用户处理或使用 git worktree，不要直接切换到默认分支。

角色总览

角色	调用的 Skill	产出物	活跃阶段
TeamLead（当前 Agent）	`intent-confirmation`	`lead/team-context.md`	全程
spec-explorer	`spec-explore`	`explorer/exploration-report.html`	阶段二（前置）
spec-writer	`spec-write`	`writer/plan.html`	阶段二
spec-tester	`spec-test`	`tester/test-plan.html`, `tester/test-report.html`, `tester/artifacts/test-logs/`	阶段二 + 阶段四
spec-executor	`spec-execute`	`executor/summary.html`	阶段三
spec-debugger	`spec-debug`	`debugger/debug-xxx.html`, `debugger/debug-xxx-fix.html`	阶段三/四（按需）
spec-reviewer	`spec-review`	`reviewer/review.html`	阶段四后（`gated` 可选 / `autopilot` 强制）
spec-ender	`spec-end`	`ender/end-report.html`	阶段五

工作流程

步骤 1：澄清任务需求（理解 + 反问梳理 + 确认）

强制使用 intent-confirmation 的三步工作法，不能只做「是/否」确认：

理解转述：用可执行条目复述目标、默认假设、做/不做边界
反问梳理编码思路：用 OMP ask（或等价方式）就阻塞点反问，至少覆盖：
- 目标与验收标准
- 范围（模块 / 前后端 / 文档）
- 实现倾向（最小补丁 / 重构 / 先调研）
- Git 工作方式（新分支 / 当前分支 / 先不建分支）
- 是否完整 5 阶段，或已有 Spec 可跳转
  每问尽量带推荐默认，帮用户拍板而不是从零设计
收敛确认：输出「编码思路小结」（触点、步骤顺序、关键取舍、验收），用户确认后再往下

通过门禁后，把思路小结写入后续上下文（lead/team-context.md 备注或「下一步动作」），供 explorer/writer 使用，避免下游重猜需求。

步骤 2：创建 Spec 工作分支

需求对齐后，调用 /git-work 的“启动 Spec 分支”模式：

base_branch: <远程默认分支，由 `git symbolic-ref refs/remotes/origin/HEAD` 读取>
branch_name: <type>/spec-<YYYYMMDD-HHMM>-<ascii-slug>

分支类型按任务主意图选择：

新能力、新集成 → feat
Bug / 回归 / 安全修复 → fix
不改行为的重构 → refactor
独立测试、审计证据建设 → test
文档、规则、Skill 文案 → docs
依赖、配置、仓库维护 → chore

输出以下 Git 元数据，并在步骤 4 写入 lead/team-context.md：

git_branch: <branch-name>
base_branch: <实际读到的默认分支名>
pr_url:

如果用户确认无分支模式，记录 git_branch: none 到 lead/team-context.md，并在 next_action 或 Blockers 中说明原因。

步骤 3：创建 Spec 角色目录并加载项目级角色定义

TeamLead 在阶段二开始前创建当前 Spec 根目录和角色目录。Spec 根目录仍按工作类型分类，目录名仍使用 YYYYMMDD-HHMM-任务描述：

spec/<01-05分类>/<YYYYMMDD-HHMM-中文任务描述>/
├── rk-manifest.js          # 导航树清单，TeamLead 维护
├── lead/
├── explorer/
├── writer/
├── tester/
│   └── artifacts/
│       └── test-logs/
├── executor/
│   └── artifacts/          # 实现期测试证据，必须由测试运行自动产出
├── debugger/
├── reviewer/
├── updater/
└── ender/

角色产物必须写入各自目录：

归属	路径
TeamLead	`lead/team-context.md`
spec-explorer	`explorer/exploration-report.html`
spec-writer	`writer/plan.html`
spec-tester	`tester/test-plan.html`, `tester/test-report.html`, `tester/artifacts/test-logs/<run-id>/`
spec-executor	`executor/summary.html`, `executor/artifacts/`（实现期 RED/GREEN 证据，须由测试运行自动产出）
spec-debugger	`debugger/debug-xxx.html`, `debugger/debug-xxx-fix.html`
spec-reviewer	`reviewer/review.html`, `reviewer/update-xxx-review.html`
spec-update	`updater/update-xxx.html`, `updater/update-xxx-summary.html`
spec-ender	`ender/end-report.html`

根目录只作为当前 Spec 容器，不直接平铺角色产物。

导航树清单 `rk-manifest.js`

创建 Spec 根目录时一并生成，内容先只含账本一条：

window.RK_SPEC_TREE = {
  specDir: "spec/<分类>/<YYYYMMDD-HHMM-任务描述>",
  docs: [
    { role: "lead", path: "lead/team-context.md", title: "运行账本", type: "team-context" }
  ]
};

每次在「产物注册表」登记一份新报告，同步往 docs 追加一条（path 相对 Spec 根，type 用该报告的 rk:type）。由 TeamLead 单点维护——各角色并发写各自报告，manifest 若人人可改会互相覆盖。

漏更新的后果是可观察的：该报告的左侧导航渲染为空。契约与渲染细节见 html-report 的「导航树」节。

格式边界与功能等价：报告类产物统一是 HTML，按 html-report Skill 的固定骨架、共享样式和修订标记规范书写。 HTML 化不得丢功能——原 frontmatter 字段双轨保留（<head> 里 <meta name="rk:*"> 机器可读 + .rk-meta 人可读镜像，含 base_branch 与 pr_url），文档关联用 <link rel="rk-*">；关联产物双向维护（rk-links 正向 + rk-backlinks 反向）。运行账本可用 lead/team-context.md 或 lead/team-context.html：用 HTML 时复用 html-report 的样式与组件，但豁免修订标记——账本是高频追写的运行流水，不是定稿后修订的报告。 spec/context/ 下的经验/知识记忆文件保持 Markdown（exp-search 按文本检索）。不要用 Markdown 写报告。

修订与决策互相追溯：报告的「修订历史」表记文本变更，账本的「决策记录」记决策本身。源于实质取舍的修订，在修订历史「原因」列写决策编号（如「按 D-003（多实例部署需共享缓存）」）；纯笔误、措辞、补充直接写清原因，不编造编号。决策过程正文只留在账本，不复制进报告；修订历史表固定 5 列（修订/日期/修改人/改了什么/原因），不新增列。

步骤 4：创建本次 Spec Team Context

创建团队：spec-{YYYYMMDD-HHMM}-{任务简称}
团队说明：Spec 驱动开发: {任务描述}
加载角色定义：
- .agents/roles/spec-explorer.md
- .agents/roles/spec-writer.md
- .agents/roles/spec-tester.md
- .agents/roles/spec-executor.md
- .agents/roles/spec-debugger.md
- .agents/roles/spec-reviewer.md
- .agents/roles/spec-ender.md

优先使用当前运行环境的项目级 Agent / Subagent 能力：

OMP（Oh My Pi）：优先使用 .omp/agents/<role-id>.md，TeamLead 通过 task 工具 spawn 角色，角色间协作用 irc 子 Agent 通信；OMP 只发现 .omp/agents/，不读 .claude/.codex。spawn 使用 OMP 16.4+ batch schema：{ context, tasks: [{ name?, agent: "<role-id>", task: "..." }] }（字段是 task/name，不是 assignment/id）。若项目级 agent 未初始化，或仍使用窄 tools 白名单，先回到 spec-init 补齐（默认省略 tools 继承完整工具集；边界靠 .agents/roles rules）
Claude Code：优先使用 .claude/agents/<role-id>.md
Codex：优先使用 .codex/agents/<role-id>.toml，spawn 时使用 TOML name 字段（如 spec_explorer）
其他环境：使用 .agents/roles/<role-id>.md 的中立角色协议

Codex CLI 的 /agent 是活跃子 Agent 线程视图，不是项目 Agent 库视图；只有 TeamLead 明确 spawn 后，角色线程才会出现在 /agent 中。

如果运行环境支持恢复子 Agent 线程，TeamLead 记录每个角色的运行时 handle；后续多轮交互优先恢复同一角色线程。若运行环境没有团队/子代理能力，或角色线程不可恢复，由当前 Agent 按同一角色协议串行执行，并从已落盘文档重建上下文。

这两条路径对应账本的 execution 字段：swarm（角色产物一律由 spawn 的子 Agent 产出，主控只做编排）或 serial（当前 Agent 按七角色协议依次承担）。由 spec-swarm 启动时该字段已写好，本 Skill 照用；直接调用本 Skill 时默认 serial，能 spawn 也可自行采用 swarm。execution 与 mode 正交——swarm 不改变任何门禁的放行条件。

在当前 Spec 目录的 lead/team-context.md 记录本次运行实例状态。它只描述当前 Spec 的团队运行上下文，不替代项目级角色定义：

---
type: team-context
schema_version: 1
team_name: spec-{YYYYMMDD-HHMM}-{任务简称}
spec_dir: spec/<01-05分类>/<YYYYMMDD-HHMM-中文任务描述>
task_description: {任务描述}
status: running
phase: intent | exploration | spec-writing | implementation | testing | debugging | review | ending | archived
runtime: omp | claude-code | codex | generic
mode: gated | autopilot
execution: serial | swarm
git_branch: <branch-name 或 none>
base_branch: <远程默认分支，通常 main 或 master；读 `git symbolic-ref refs/remotes/origin/HEAD` 得到，不写死>
pr_url:
created_at: {ISO8601}
updated_at: {ISO8601}
---

# 团队运行账本

## 当前运行路径

| 步骤 | 阶段 | 负责角色 | 动作 | 状态 | 产物 | 门禁 | 更新时间 |
|------|------|----------|------|------|------|------|----------|
| 1 | intent | TeamLead | 需求对齐 | done/pending | lead/team-context.md | gate-1 | {ISO8601} |

## 任务进度

> 共享维护区：各角色只追加或更新自己负责的任务行。

| 任务号 | 负责角色 | 任务 | 状态 | 产物 | 完成时间 | 更新者 |
|--------|----------|------|------|------|----------|--------|
| T-001 | spec-explorer | 探索项目背景 | pending | explorer/exploration-report.html | | spec-explorer |

## 问题闭环记录

> 共享维护区：发现或解决问题的角色只追加或更新自己相关的问题行。
> 不只记 bug，任何影响推进的过程性问题都记：「分类」取 `bug` | `blocker` | `process` | `env` | `dependency` | `scope`。

| 问题号 | 分类 | 发现者 | 负责角色 | 问题 | 解决方案 | 关联产物 | 状态 | 更新者 |
|--------|------|--------|----------|------|----------|----------|------|--------|
| I-001 | bug | spec-tester | spec-debugger | 待记录 | 待记录 | debugger/debug-001.html / debugger/debug-001-fix.html | open | spec-tester/spec-debugger |
| I-002 | env | spec-executor | spec-executor | 待记录（如缺依赖、脚本报错、环境不一致） | 待记录 | executor/summary.html | open | spec-executor |

## 决策记录

> 共享维护区：任何角色遇到需要用户或角色拍板的岔路口，落一行。记录当时给了哪些选项、
> 选了什么、为什么、谁拍的板。被否决的选项不要删，它是复盘的关键上下文。
> 与「门禁决策」的区别：门禁决策只记阶段门禁通过/驳回；决策记录记每一个实质取舍及其理由。

| 决策号 | 阶段 | 提出者 | 议题 | 候选项 | 结论 | 理由 | 拍板者 | 决策时间 | 依据 |
|--------|------|--------|------|--------|------|------|--------|----------|------|
| D-001 | intent | TeamLead | 实现路径 | A 最小补丁 / B 抽公共层 | A | 改动面小、可回滚 | user | {ISO8601} | 用户原话「先别动架构」 |

## 角色运行句柄

| 角色 id | 适配层 | 运行时角色名 | agent_id | thread_id | session_id | 状态 | 续接方式 | 累计参与 Spec 数 | 最近产物 | 更新时间 |
|---------|--------|--------------|----------|-----------|------------|------|----------|------------------|----------|----------|
| spec-explorer | .claude/.codex/.agents | spec-explorer/spec_explorer | 运行时填写 | 运行时填写 | 运行时填写 | running \| idle \| parked \| aborted | hub-send \| respawn+rebuild | 1 |  | {ISO8601} |

## 产物注册表

| 产物 | 负责角色 | 状态 | 已确认 | 更新时间 |
|------|----------|------|--------|----------|
| writer/plan.html | spec-writer | pending | no | |

## 门禁决策

| 门禁 | 确认对象 | 决策 | 判定方式 | 决策时间 | 备注 |
|------|----------|------|----------|----------|------|
| gate-1 | 需求对齐 | pending | user \| self+evidence | | 判定方式为 `self+evidence` 时，备注必须给出证据指针 |

## 角色交接

| 来源角色 | 接收角色 | 交接原因 | 产物 | 状态 | 更新时间 |
|----------|----------|----------|------|------|----------|

## 修复循环预算

> 修复循环（spec-tester ↔ spec-debugger）的运行预算。值不写死在 Skill 中，
> 由 TeamLead 在进入阶段四修复循环前用 intent-confirmation 与用户确认后填入。
> 只跟踪两个上限：最大轮数、最大无进展轮数。

| 循环 | 最大轮数 | 最大无进展轮数 | 已用轮数 | 连续无进展 | 状态 | 用户已确认 | 更新时间 |
|------|----------|----------------|----------|------------|------|------------|----------|
| test-debug | 待确认 | 待确认 | 0 | 0 | not-started | no | |

- 「最大轮数」：本次修复循环最多允许 tester→debugger→tester 走多少轮（建议默认 3，用户可改）。
- 「最大无进展轮数」：连续多少轮没有新增进展就停止并升级给人（建议默认 2，用户可改）。
- 「已用轮数」/「连续无进展」：由 spec-debugger 和 spec-tester 在每轮重验后更新。
- 「状态」取值：`not-started` | `running` | `passed` | `stopped-budget` | `stopped-no-progress` | `escalated`。

## 开放问题与阻塞

| 编号 | 负责角色 | 问题或阻塞 | 状态 | 解决情况 |
|------|----------|------------|------|----------|

## 下一步动作

- 待记录 TeamLead 下一步动作。

记录规则：

TeamLead 维护 lead/team-context.md 的结构、frontmatter、「当前运行路径」、Git/PR 元数据、「角色运行句柄」、「产物注册表」、「门禁决策」、「角色交接」、「开放问题与阻塞」和「下一步动作」。
所有角色可共同维护「任务进度」：只追加或更新自己负责的任务行，完成产物后立即记录状态、产物、完成时间和更新者。
发现或解决问题的角色可共同维护「问题闭环记录」：只追加或更新自己发现/处理的问题行，记录分类、问题、解决方案摘要、关联产物、状态和更新者。不止 bug——阻塞、环境、依赖、流程、范围偏差等过程性问题都在此记录。
遇到需要拍板的取舍时，拍板的一方（用户决策由 TeamLead 代记）在「决策记录」追加一行：「候选项」记当时的选项（含被否决项）、「结论」记选了什么、「理由」记为什么、「拍板者」记 user 或角色 id、「依据」记可追溯的事实来源。这是「为什么当初这么定」的唯一权威来源。
「依据」列只接受三种形式：①文件路径 + 行号 ②命令 + 退出码 + 输出位置 ③用户原话引用。「根据经验」「通常做法」「这样更专业」不是依据——理由可以被生成，依据必须可追。autopilot 模式下这一列是审计轨的核心，缺失即视为该决策无据。
TeamLead 每次 spawn、resume、send message、stop 或 close 角色线程后更新 lead/team-context.md 的控制面信息。
TeamLead 每次阶段切换、用户确认、handoff、PR URL 变化后更新 lead/team-context.md，并在需要时校准共享完成流水。
lead/team-context.md 全部由 TeamLead 和各角色手动维护；不依赖任何自动记账机制。角色每产出一个产物、每解决一个问题、每做一次取舍，立即更新对应区块。
lead/team-context.md 是当前 Spec 的运行账本和 Git/PR 元数据权威来源；角色产物只链接它，不复制运行状态正文。
「当前运行路径」记录当前任务实际走过的流程路径；「任务进度」记录已经完成的任务；「问题闭环记录」记录谁发现问题、谁解决问题、解决产物在哪里；「决策记录」记录每一个实质取舍的选项、结论和理由。
除「任务进度」、「问题闭环记录」和「决策记录」外，非 TeamLead 角色不要直接修改其他区块；如需变更控制面信息，向 TeamLead 提交说明。
agent_id、thread_id、session_id 是运行时 handle，不是长期身份，但这不等于用完即弃：同一进程内它们是续接同一角色的唯一途径，必须实时记录。跨进程失效时，账本与落盘产物才是恢复路径。角色的长期身份来自项目级角色定义 + 账本「累计参与 Spec 数」，而不是 handle 本身。
OMP 运行时优先记录 task spawn 返回的 agent_id（agent://<id> 句柄）和子 Agent job id；角色间用 irc 协作时按角色 id（如 spec-tester）寻址，交接仍落盘到「角色交接」与「问题闭环记录」。
Claude Code 运行时优先记录 subagent agent_id 和对应 transcript/session 信息。
Codex 运行时优先记录 /agent 可见线程或当前 session handle；如 CLI 不暴露稳定 ID，记录 runtime agent name、当前 session 线索和最近产物路径。
不记录 token、API key、私有凭据或不可提交的本机绝对敏感路径。
不在 lead/team-context.md 复制 plan 正文、测试日志、debug 细节或长篇总结；只记录路径、状态、决策和简短摘要。
「状态」取 running（正在执行，可插话 steering）、idle（跑完但 session 仍挂载）、parked（空闲超时释放 session，但发消息即自动复活且上下文完整）、aborted（被取消或硬中断，终态不可复活）。「续接方式」相应取 hub-send（前三态）或 respawn+rebuild（aborted，重新 spawn 并从账本与产物重建上下文）。
续接同一角色只能发消息，不能重新 spawn：运行时按 name 分配 agent id，同名再 spawn 会得到 spec-writer-2 这样的全新零历史实例（影子角色）。spawn 时必须显式等于角色 id，否则会拿到随机生成名而失去可寻址性。

步骤 5：建立跨角色通信规则

续接规则：先查 lead/team-context.md 的「角色运行句柄」，再用运行时的 agent 列表核对实际状态。running/idle/parked 一律发消息续接同一角色（parked 收到消息自动复活，上下文完整），只有 aborted 才重新 spawn 并从落盘产物重建上下文。禁止用重新 spawn 代替续接——那会产生零历史的影子角色。

上游角色 → TeamLead：提交产物路径、结论、问题、建议下游角色
TeamLead → 下游角色：查账本句柄 → 核对状态 → 能续接就发消息给同一角色，aborted 才 respawn
下游角色 → TeamLead：返回产物路径和状态

角色可以在产物中声明建议接收方，但不假设运行环境支持直接 Agent-to-Agent 通信。例如，spec-tester 发现 bug 时向 TeamLead 提交 bug handoff，由 TeamLead 启动或恢复 spec-debugger；spec-debugger 修复完成后向 TeamLead 提交重新验证请求，由 TeamLead 启动或恢复 spec-tester。

步骤 6：启动阶段二（探索）

需求对齐、分支准备、角色定义加载和通信规则建立后，TeamLead 启动或恢复 spec-explorer，并传递任务描述、探索范围、Spec 目录和 Git 元数据。

完整协作时序

阶段一：需求对齐
  TeamLead → intent-confirmation
             （理解转述 → 反问梳理编码思路 → 收敛确认）
  用户确认编码思路小结
      ↓ 【门禁 1 通过】

GitHub Flow 准备
  TeamLead → git-work → 从远程默认分支创建 Spec 工作分支
  TeamLead → 记录 git_branch / base_branch / pr_url 到 lead/team-context.md

【团队初始化】
  TeamLead 加载 .agents/roles/ 的 7 个项目级角色定义
  TeamLead 按运行时能力创建或恢复本次 Spec 的角色实例
  TeamLead 记录可恢复的角色 handle 到 lead/team-context.md（如运行时支持）

阶段二：Spec 创建
  TeamLead → 启动/恢复 spec-explorer
  spec-explorer → explorer/exploration-report.html → TeamLead
  TeamLead → 启动/恢复 spec-writer，传递 explorer/exploration-report.html + lead/team-context.md
  TeamLead → 启动/恢复 spec-tester，传递 explorer/exploration-report.html 并进入测试计划阶段
  TeamLead 中转 spec-writer 与 spec-tester 的接口边界问题
  spec-writer → writer/plan.html 定稿 → TeamLead
  spec-tester → tester/test-plan.html 定稿 → TeamLead
  TeamLead → 用户确认 writer/plan.html + tester/test-plan.html
      ↓ 【门禁 2 通过】

阶段三：实现
  TeamLead → 启动/恢复 spec-executor
  spec-executor → executor/summary.html → TeamLead
  TeamLead → 用户确认 executor/summary.html
      ↓ 【门禁 3 通过】

阶段四：测试
  TeamLead → 启动/恢复 spec-tester 执行测试
  [如有 bug] spec-tester → bug handoff → TeamLead
             TeamLead → 用 intent-confirmation 与用户确认本次修复循环预算
                        （max_rounds 建议 3，max_no_progress_rounds 建议 2，用户可改）
                        → 写入 lead/team-context.md 的「修复循环预算」，status=running
             TeamLead → 启动/恢复 spec-debugger
             spec-debugger 修复 → 更新 rounds_used / no_progress_streak → TeamLead
             TeamLead → 启动/恢复 spec-tester 重新验证
             spec-tester 验证 → 更新「修复循环预算」进展信号
             [验证通过]「修复循环预算」status=passed → 继续
             [仍失败且未触上限] 回到 spec-debugger 下一轮
             [触发 max_rounds 或 max_no_progress_rounds]
                        → spec-tester/spec-debugger 停止，status=stopped-budget/stopped-no-progress
                        → TeamLead 升级给用户决定（继续加预算 / 改方案 / 暂停）
  spec-tester → tester/test-report.html → TeamLead
  TeamLead → 用户确认 tester/test-report.html
  [审查] gated 可选 / autopilot 强制：TeamLead → 启动/恢复 spec-reviewer
             spec-reviewer → reviewer/review.html → TeamLead
             gated 由用户确认；autopilot 下该报告即替代门禁 4 的用户确认
      ↓ 【门禁 4 通过】

阶段五：收尾
  TeamLead → 启动/恢复 spec-ender
  spec-ender → 向 TeamLead 请求多角色素材 + exp-reflect → 规范维护审查 → 询问用户归档
  spec-ender → git-work 提交、推送、创建 PR
  spec-ender → TeamLead，本次 Spec 团队实例结束，项目级角色定义保留

用户确认节点

节点	由谁发起	确认内容
需求对齐	TeamLead	目标/范围/验收 + 反问后的编码思路小结（非单纯「理解正确」）
分支准备	TeamLead	仅在工作区不干净、无 Git 仓库或需使用 worktree 时询问
Spec 审阅	TeamLead	`writer/plan.html` + `tester/test-plan.html`
实现确认	TeamLead	`executor/summary.html`
修复循环预算	TeamLead	进入修复循环前确认「最大轮数」和「最大无进展轮数」（带建议默认值，用户可改）
诊断确认	TeamLead	`debugger/debug-xxx.html`（如有）
测试报告确认	TeamLead	`tester/test-report.html`
修复循环升级	TeamLead	触发预算上限或连续无进展时，确认继续加预算 / 改方案 / 暂停
归档确认	spec-ender	是否归档 + 提交 + 推送 + 创建 PR

修复循环进展信号

进入阶段四的 spec-tester ↔ spec-debugger 修复循环时，TeamLead 维护 lead/team-context.md 的「修复循环预算」：

预算来自用户：「最大轮数」和「最大无进展轮数」不写死在 Skill 中。每次进入修复循环前，TeamLead 用 intent-confirmation 向用户确认，带建议默认值（3 轮 / 连续 2 轮无进展），用户可直接接受或改写。
每轮记账：spec-debugger 修复后、spec-tester 重验后，各自更新「已用轮数」和「连续无进展」。
进展的定义：一轮算"有进展"当且仅当出现以下至少一项——新增通过的测试用例、失败范围缩小、定位到此前未知的根因、产生新的可验证证据。仅写了新总结但上述都没有，记为"无进展"，「连续无进展」加一。
停止与升级：「已用轮数」达到「最大轮数」，或「连续无进展」达到「最大无进展轮数」时，停止循环并由 TeamLead 升级给用户，不自行无限重试。

后续动作

启动完成后确认：

团队协作上下文已成功建立
7 个项目级角色定义已加载（spec-explorer/writer/tester/executor/debugger/reviewer/ender）
已创建或确认当前 Spec 工作分支
阶段二（探索）已启动
用户已了解整体流程

常见陷阱

spec/ 目录不存在就启动（应先 spec-init）
跳过 git-work，直接在远程默认分支上开发
工作区有无关改动时切换分支
多个并发 Spec 共用同一个 working tree（应使用 git worktree）
在 spec-start 中重写角色定义，导致与 spec-init 持久化角色漂移
创建角色时混淆角色名（spec-writer）和 Skill 名（spec-write）
尝试创建 TeamLead 角色（当前 Agent 本身就是 TeamLead）
假设角色之间可以直接通信，绕过 TeamLead 中转
阶段转换时未等待用户确认就继续

disable-model-invocation	true
name	spec-start
description	当用户开始新的开发任务、需要启动完整 Spec 流程（需求对齐→探索→设计→实现→测试→收尾），或需要为一个新 Spec 创建协作上下文和 GitHub Flow 工作分支时使用。不要用于已有完成 Spec 的小迭代（用 spec-update）或项目首次初始化（用 spec-init）。

Spec Start

核心原则

当前 Agent 即是 TeamLead：调用本 Skill 的 Agent 本身就承担 TeamLead 职责，无需创建额外的 TeamLead 角色
角色定义由 spec-init 持久化：spec-start 只加载和唤起项目级角色，不内联维护角色 prompt
本次 Spec 创建运行实例：角色线程/实例在当前 Spec 生命周期内尽量保持可恢复，跨 Spec 状态必须文件化
角色 vs Skill 区分：角色（spec-writer）是 Who，Skill（spec-write）是 How
TeamLead 统一协调：所有阶段转换、跨角色通信和用户确认节点均由 TeamLead（当前 Agent）主导
分支隔离：每个 Spec 默认从远程默认分支创建独立工作分支，禁止直接在默认分支上实现。默认分支名不写死——用 git symbolic-ref refs/remotes/origin/HEAD 读取（常见为 main 或 master）

前置检查

启动前检查项目是否已初始化：

ls spec/context/experience/index.md
ls .agents/roles/spec-explorer.md

同时检查 Git 状态：

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

如果不是 Git 仓库，询问用户是否继续无分支模式；如果工作区有无关改动，先让用户处理或使用 git worktree，不要直接切换到默认分支。

角色总览

角色	调用的 Skill	产出物	活跃阶段
TeamLead（当前 Agent）	`intent-confirmation`	`lead/team-context.md`	全程
spec-explorer	`spec-explore`	`explorer/exploration-report.html`	阶段二（前置）
spec-writer	`spec-write`	`writer/plan.html`	阶段二
spec-tester	`spec-test`	`tester/test-plan.html`, `tester/test-report.html`, `tester/artifacts/test-logs/`	阶段二 + 阶段四
spec-executor	`spec-execute`	`executor/summary.html`	阶段三
spec-debugger	`spec-debug`	`debugger/debug-xxx.html`, `debugger/debug-xxx-fix.html`	阶段三/四（按需）
spec-reviewer	`spec-review`	`reviewer/review.html`	阶段四后（`gated` 可选 / `autopilot` 强制）
spec-ender	`spec-end`	`ender/end-report.html`	阶段五

工作流程

步骤 1：澄清任务需求（理解 + 反问梳理 + 确认）

强制使用 intent-confirmation 的三步工作法，不能只做「是/否」确认：

理解转述：用可执行条目复述目标、默认假设、做/不做边界
反问梳理编码思路：用 OMP ask（或等价方式）就阻塞点反问，至少覆盖：
- 目标与验收标准
- 范围（模块 / 前后端 / 文档）
- 实现倾向（最小补丁 / 重构 / 先调研）
- Git 工作方式（新分支 / 当前分支 / 先不建分支）
- 是否完整 5 阶段，或已有 Spec 可跳转
  每问尽量带推荐默认，帮用户拍板而不是从零设计
收敛确认：输出「编码思路小结」（触点、步骤顺序、关键取舍、验收），用户确认后再往下

通过门禁后，把思路小结写入后续上下文（lead/team-context.md 备注或「下一步动作」），供 explorer/writer 使用，避免下游重猜需求。

步骤 2：创建 Spec 工作分支

需求对齐后，调用 /git-work 的“启动 Spec 分支”模式：

base_branch: <远程默认分支，由 `git symbolic-ref refs/remotes/origin/HEAD` 读取>
branch_name: <type>/spec-<YYYYMMDD-HHMM>-<ascii-slug>

分支类型按任务主意图选择：

新能力、新集成 → feat
Bug / 回归 / 安全修复 → fix
不改行为的重构 → refactor
独立测试、审计证据建设 → test
文档、规则、Skill 文案 → docs
依赖、配置、仓库维护 → chore

输出以下 Git 元数据，并在步骤 4 写入 lead/team-context.md：

git_branch: <branch-name>
base_branch: <实际读到的默认分支名>
pr_url:

如果用户确认无分支模式，记录 git_branch: none 到 lead/team-context.md，并在 next_action 或 Blockers 中说明原因。

步骤 3：创建 Spec 角色目录并加载项目级角色定义

TeamLead 在阶段二开始前创建当前 Spec 根目录和角色目录。Spec 根目录仍按工作类型分类，目录名仍使用 YYYYMMDD-HHMM-任务描述：

spec/<01-05分类>/<YYYYMMDD-HHMM-中文任务描述>/
├── rk-manifest.js          # 导航树清单，TeamLead 维护
├── lead/
├── explorer/
├── writer/
├── tester/
│   └── artifacts/
│       └── test-logs/
├── executor/
│   └── artifacts/          # 实现期测试证据，必须由测试运行自动产出
├── debugger/
├── reviewer/
├── updater/
└── ender/

角色产物必须写入各自目录：

归属	路径
TeamLead	`lead/team-context.md`
spec-explorer	`explorer/exploration-report.html`
spec-writer	`writer/plan.html`
spec-tester	`tester/test-plan.html`, `tester/test-report.html`, `tester/artifacts/test-logs/<run-id>/`
spec-executor	`executor/summary.html`, `executor/artifacts/`（实现期 RED/GREEN 证据，须由测试运行自动产出）
spec-debugger	`debugger/debug-xxx.html`, `debugger/debug-xxx-fix.html`
spec-reviewer	`reviewer/review.html`, `reviewer/update-xxx-review.html`
spec-update	`updater/update-xxx.html`, `updater/update-xxx-summary.html`
spec-ender	`ender/end-report.html`

根目录只作为当前 Spec 容器，不直接平铺角色产物。

导航树清单 `rk-manifest.js`

创建 Spec 根目录时一并生成，内容先只含账本一条：

window.RK_SPEC_TREE = {
  specDir: "spec/<分类>/<YYYYMMDD-HHMM-任务描述>",
  docs: [
    { role: "lead", path: "lead/team-context.md", title: "运行账本", type: "team-context" }
  ]
};

漏更新的后果是可观察的：该报告的左侧导航渲染为空。契约与渲染细节见 html-report 的「导航树」节。

步骤 4：创建本次 Spec Team Context

创建团队：spec-{YYYYMMDD-HHMM}-{任务简称}
团队说明：Spec 驱动开发: {任务描述}
加载角色定义：
- .agents/roles/spec-explorer.md
- .agents/roles/spec-writer.md
- .agents/roles/spec-tester.md
- .agents/roles/spec-executor.md
- .agents/roles/spec-debugger.md
- .agents/roles/spec-reviewer.md
- .agents/roles/spec-ender.md

优先使用当前运行环境的项目级 Agent / Subagent 能力：

OMP（Oh My Pi）：优先使用 .omp/agents/<role-id>.md，TeamLead 通过 task 工具 spawn 角色，角色间协作用 irc 子 Agent 通信；OMP 只发现 .omp/agents/，不读 .claude/.codex。spawn 使用 OMP 16.4+ batch schema：{ context, tasks: [{ name?, agent: "<role-id>", task: "..." }] }（字段是 task/name，不是 assignment/id）。若项目级 agent 未初始化，或仍使用窄 tools 白名单，先回到 spec-init 补齐（默认省略 tools 继承完整工具集；边界靠 .agents/roles rules）
Claude Code：优先使用 .claude/agents/<role-id>.md
Codex：优先使用 .codex/agents/<role-id>.toml，spawn 时使用 TOML name 字段（如 spec_explorer）
其他环境：使用 .agents/roles/<role-id>.md 的中立角色协议

Codex CLI 的 /agent 是活跃子 Agent 线程视图，不是项目 Agent 库视图；只有 TeamLead 明确 spawn 后，角色线程才会出现在 /agent 中。

在当前 Spec 目录的 lead/team-context.md 记录本次运行实例状态。它只描述当前 Spec 的团队运行上下文，不替代项目级角色定义：

---
type: team-context
schema_version: 1
team_name: spec-{YYYYMMDD-HHMM}-{任务简称}
spec_dir: spec/<01-05分类>/<YYYYMMDD-HHMM-中文任务描述>
task_description: {任务描述}
status: running
phase: intent | exploration | spec-writing | implementation | testing | debugging | review | ending | archived
runtime: omp | claude-code | codex | generic
mode: gated | autopilot
execution: serial | swarm
git_branch: <branch-name 或 none>
base_branch: <远程默认分支，通常 main 或 master；读 `git symbolic-ref refs/remotes/origin/HEAD` 得到，不写死>
pr_url:
created_at: {ISO8601}
updated_at: {ISO8601}
---

# 团队运行账本

## 当前运行路径

| 步骤 | 阶段 | 负责角色 | 动作 | 状态 | 产物 | 门禁 | 更新时间 |
|------|------|----------|------|------|------|------|----------|
| 1 | intent | TeamLead | 需求对齐 | done/pending | lead/team-context.md | gate-1 | {ISO8601} |

## 任务进度

> 共享维护区：各角色只追加或更新自己负责的任务行。

| 任务号 | 负责角色 | 任务 | 状态 | 产物 | 完成时间 | 更新者 |
|--------|----------|------|------|------|----------|--------|
| T-001 | spec-explorer | 探索项目背景 | pending | explorer/exploration-report.html | | spec-explorer |

## 问题闭环记录

> 共享维护区：发现或解决问题的角色只追加或更新自己相关的问题行。
> 不只记 bug，任何影响推进的过程性问题都记：「分类」取 `bug` | `blocker` | `process` | `env` | `dependency` | `scope`。

| 问题号 | 分类 | 发现者 | 负责角色 | 问题 | 解决方案 | 关联产物 | 状态 | 更新者 |
|--------|------|--------|----------|------|----------|----------|------|--------|
| I-001 | bug | spec-tester | spec-debugger | 待记录 | 待记录 | debugger/debug-001.html / debugger/debug-001-fix.html | open | spec-tester/spec-debugger |
| I-002 | env | spec-executor | spec-executor | 待记录（如缺依赖、脚本报错、环境不一致） | 待记录 | executor/summary.html | open | spec-executor |

## 决策记录

> 共享维护区：任何角色遇到需要用户或角色拍板的岔路口，落一行。记录当时给了哪些选项、
> 选了什么、为什么、谁拍的板。被否决的选项不要删，它是复盘的关键上下文。
> 与「门禁决策」的区别：门禁决策只记阶段门禁通过/驳回；决策记录记每一个实质取舍及其理由。

| 决策号 | 阶段 | 提出者 | 议题 | 候选项 | 结论 | 理由 | 拍板者 | 决策时间 | 依据 |
|--------|------|--------|------|--------|------|------|--------|----------|------|
| D-001 | intent | TeamLead | 实现路径 | A 最小补丁 / B 抽公共层 | A | 改动面小、可回滚 | user | {ISO8601} | 用户原话「先别动架构」 |

## 角色运行句柄

| 角色 id | 适配层 | 运行时角色名 | agent_id | thread_id | session_id | 状态 | 续接方式 | 累计参与 Spec 数 | 最近产物 | 更新时间 |
|---------|--------|--------------|----------|-----------|------------|------|----------|------------------|----------|----------|
| spec-explorer | .claude/.codex/.agents | spec-explorer/spec_explorer | 运行时填写 | 运行时填写 | 运行时填写 | running \| idle \| parked \| aborted | hub-send \| respawn+rebuild | 1 |  | {ISO8601} |

## 产物注册表

| 产物 | 负责角色 | 状态 | 已确认 | 更新时间 |
|------|----------|------|--------|----------|
| writer/plan.html | spec-writer | pending | no | |

## 门禁决策

| 门禁 | 确认对象 | 决策 | 判定方式 | 决策时间 | 备注 |
|------|----------|------|----------|----------|------|
| gate-1 | 需求对齐 | pending | user \| self+evidence | | 判定方式为 `self+evidence` 时，备注必须给出证据指针 |

## 角色交接

| 来源角色 | 接收角色 | 交接原因 | 产物 | 状态 | 更新时间 |
|----------|----------|----------|------|------|----------|

## 修复循环预算

> 修复循环（spec-tester ↔ spec-debugger）的运行预算。值不写死在 Skill 中，
> 由 TeamLead 在进入阶段四修复循环前用 intent-confirmation 与用户确认后填入。
> 只跟踪两个上限：最大轮数、最大无进展轮数。

| 循环 | 最大轮数 | 最大无进展轮数 | 已用轮数 | 连续无进展 | 状态 | 用户已确认 | 更新时间 |
|------|----------|----------------|----------|------------|------|------------|----------|
| test-debug | 待确认 | 待确认 | 0 | 0 | not-started | no | |

- 「最大轮数」：本次修复循环最多允许 tester→debugger→tester 走多少轮（建议默认 3，用户可改）。
- 「最大无进展轮数」：连续多少轮没有新增进展就停止并升级给人（建议默认 2，用户可改）。
- 「已用轮数」/「连续无进展」：由 spec-debugger 和 spec-tester 在每轮重验后更新。
- 「状态」取值：`not-started` | `running` | `passed` | `stopped-budget` | `stopped-no-progress` | `escalated`。

## 开放问题与阻塞

| 编号 | 负责角色 | 问题或阻塞 | 状态 | 解决情况 |
|------|----------|------------|------|----------|

## 下一步动作

- 待记录 TeamLead 下一步动作。

记录规则：

TeamLead 维护 lead/team-context.md 的结构、frontmatter、「当前运行路径」、Git/PR 元数据、「角色运行句柄」、「产物注册表」、「门禁决策」、「角色交接」、「开放问题与阻塞」和「下一步动作」。
所有角色可共同维护「任务进度」：只追加或更新自己负责的任务行，完成产物后立即记录状态、产物、完成时间和更新者。
发现或解决问题的角色可共同维护「问题闭环记录」：只追加或更新自己发现/处理的问题行，记录分类、问题、解决方案摘要、关联产物、状态和更新者。不止 bug——阻塞、环境、依赖、流程、范围偏差等过程性问题都在此记录。
遇到需要拍板的取舍时，拍板的一方（用户决策由 TeamLead 代记）在「决策记录」追加一行：「候选项」记当时的选项（含被否决项）、「结论」记选了什么、「理由」记为什么、「拍板者」记 user 或角色 id、「依据」记可追溯的事实来源。这是「为什么当初这么定」的唯一权威来源。
「依据」列只接受三种形式：①文件路径 + 行号 ②命令 + 退出码 + 输出位置 ③用户原话引用。「根据经验」「通常做法」「这样更专业」不是依据——理由可以被生成，依据必须可追。autopilot 模式下这一列是审计轨的核心，缺失即视为该决策无据。
TeamLead 每次 spawn、resume、send message、stop 或 close 角色线程后更新 lead/team-context.md 的控制面信息。
TeamLead 每次阶段切换、用户确认、handoff、PR URL 变化后更新 lead/team-context.md，并在需要时校准共享完成流水。
lead/team-context.md 全部由 TeamLead 和各角色手动维护；不依赖任何自动记账机制。角色每产出一个产物、每解决一个问题、每做一次取舍，立即更新对应区块。
lead/team-context.md 是当前 Spec 的运行账本和 Git/PR 元数据权威来源；角色产物只链接它，不复制运行状态正文。
「当前运行路径」记录当前任务实际走过的流程路径；「任务进度」记录已经完成的任务；「问题闭环记录」记录谁发现问题、谁解决问题、解决产物在哪里；「决策记录」记录每一个实质取舍的选项、结论和理由。
除「任务进度」、「问题闭环记录」和「决策记录」外，非 TeamLead 角色不要直接修改其他区块；如需变更控制面信息，向 TeamLead 提交说明。
agent_id、thread_id、session_id 是运行时 handle，不是长期身份，但这不等于用完即弃：同一进程内它们是续接同一角色的唯一途径，必须实时记录。跨进程失效时，账本与落盘产物才是恢复路径。角色的长期身份来自项目级角色定义 + 账本「累计参与 Spec 数」，而不是 handle 本身。
OMP 运行时优先记录 task spawn 返回的 agent_id（agent://<id> 句柄）和子 Agent job id；角色间用 irc 协作时按角色 id（如 spec-tester）寻址，交接仍落盘到「角色交接」与「问题闭环记录」。
Claude Code 运行时优先记录 subagent agent_id 和对应 transcript/session 信息。
Codex 运行时优先记录 /agent 可见线程或当前 session handle；如 CLI 不暴露稳定 ID，记录 runtime agent name、当前 session 线索和最近产物路径。
不记录 token、API key、私有凭据或不可提交的本机绝对敏感路径。
不在 lead/team-context.md 复制 plan 正文、测试日志、debug 细节或长篇总结；只记录路径、状态、决策和简短摘要。
「状态」取 running（正在执行，可插话 steering）、idle（跑完但 session 仍挂载）、parked（空闲超时释放 session，但发消息即自动复活且上下文完整）、aborted（被取消或硬中断，终态不可复活）。「续接方式」相应取 hub-send（前三态）或 respawn+rebuild（aborted，重新 spawn 并从账本与产物重建上下文）。
续接同一角色只能发消息，不能重新 spawn：运行时按 name 分配 agent id，同名再 spawn 会得到 spec-writer-2 这样的全新零历史实例（影子角色）。spawn 时必须显式等于角色 id，否则会拿到随机生成名而失去可寻址性。

步骤 5：建立跨角色通信规则

上游角色 → TeamLead：提交产物路径、结论、问题、建议下游角色
TeamLead → 下游角色：查账本句柄 → 核对状态 → 能续接就发消息给同一角色，aborted 才 respawn
下游角色 → TeamLead：返回产物路径和状态

步骤 6：启动阶段二（探索）

需求对齐、分支准备、角色定义加载和通信规则建立后，TeamLead 启动或恢复 spec-explorer，并传递任务描述、探索范围、Spec 目录和 Git 元数据。

完整协作时序

阶段一：需求对齐
  TeamLead → intent-confirmation
             （理解转述 → 反问梳理编码思路 → 收敛确认）
  用户确认编码思路小结
      ↓ 【门禁 1 通过】

GitHub Flow 准备
  TeamLead → git-work → 从远程默认分支创建 Spec 工作分支
  TeamLead → 记录 git_branch / base_branch / pr_url 到 lead/team-context.md

【团队初始化】
  TeamLead 加载 .agents/roles/ 的 7 个项目级角色定义
  TeamLead 按运行时能力创建或恢复本次 Spec 的角色实例
  TeamLead 记录可恢复的角色 handle 到 lead/team-context.md（如运行时支持）

阶段二：Spec 创建
  TeamLead → 启动/恢复 spec-explorer
  spec-explorer → explorer/exploration-report.html → TeamLead
  TeamLead → 启动/恢复 spec-writer，传递 explorer/exploration-report.html + lead/team-context.md
  TeamLead → 启动/恢复 spec-tester，传递 explorer/exploration-report.html 并进入测试计划阶段
  TeamLead 中转 spec-writer 与 spec-tester 的接口边界问题
  spec-writer → writer/plan.html 定稿 → TeamLead
  spec-tester → tester/test-plan.html 定稿 → TeamLead
  TeamLead → 用户确认 writer/plan.html + tester/test-plan.html
      ↓ 【门禁 2 通过】

阶段三：实现
  TeamLead → 启动/恢复 spec-executor
  spec-executor → executor/summary.html → TeamLead
  TeamLead → 用户确认 executor/summary.html
      ↓ 【门禁 3 通过】

阶段四：测试
  TeamLead → 启动/恢复 spec-tester 执行测试
  [如有 bug] spec-tester → bug handoff → TeamLead
             TeamLead → 用 intent-confirmation 与用户确认本次修复循环预算
                        （max_rounds 建议 3，max_no_progress_rounds 建议 2，用户可改）
                        → 写入 lead/team-context.md 的「修复循环预算」，status=running
             TeamLead → 启动/恢复 spec-debugger
             spec-debugger 修复 → 更新 rounds_used / no_progress_streak → TeamLead
             TeamLead → 启动/恢复 spec-tester 重新验证
             spec-tester 验证 → 更新「修复循环预算」进展信号
             [验证通过]「修复循环预算」status=passed → 继续
             [仍失败且未触上限] 回到 spec-debugger 下一轮
             [触发 max_rounds 或 max_no_progress_rounds]
                        → spec-tester/spec-debugger 停止，status=stopped-budget/stopped-no-progress
                        → TeamLead 升级给用户决定（继续加预算 / 改方案 / 暂停）
  spec-tester → tester/test-report.html → TeamLead
  TeamLead → 用户确认 tester/test-report.html
  [审查] gated 可选 / autopilot 强制：TeamLead → 启动/恢复 spec-reviewer
             spec-reviewer → reviewer/review.html → TeamLead
             gated 由用户确认；autopilot 下该报告即替代门禁 4 的用户确认
      ↓ 【门禁 4 通过】

阶段五：收尾
  TeamLead → 启动/恢复 spec-ender
  spec-ender → 向 TeamLead 请求多角色素材 + exp-reflect → 规范维护审查 → 询问用户归档
  spec-ender → git-work 提交、推送、创建 PR
  spec-ender → TeamLead，本次 Spec 团队实例结束，项目级角色定义保留

用户确认节点

节点	由谁发起	确认内容
需求对齐	TeamLead	目标/范围/验收 + 反问后的编码思路小结（非单纯「理解正确」）
分支准备	TeamLead	仅在工作区不干净、无 Git 仓库或需使用 worktree 时询问
Spec 审阅	TeamLead	`writer/plan.html` + `tester/test-plan.html`
实现确认	TeamLead	`executor/summary.html`
修复循环预算	TeamLead	进入修复循环前确认「最大轮数」和「最大无进展轮数」（带建议默认值，用户可改）
诊断确认	TeamLead	`debugger/debug-xxx.html`（如有）
测试报告确认	TeamLead	`tester/test-report.html`
修复循环升级	TeamLead	触发预算上限或连续无进展时，确认继续加预算 / 改方案 / 暂停
归档确认	spec-ender	是否归档 + 提交 + 推送 + 创建 PR

修复循环进展信号

进入阶段四的 spec-tester ↔ spec-debugger 修复循环时，TeamLead 维护 lead/team-context.md 的「修复循环预算」：

预算来自用户：「最大轮数」和「最大无进展轮数」不写死在 Skill 中。每次进入修复循环前，TeamLead 用 intent-confirmation 向用户确认，带建议默认值（3 轮 / 连续 2 轮无进展），用户可直接接受或改写。
每轮记账：spec-debugger 修复后、spec-tester 重验后，各自更新「已用轮数」和「连续无进展」。
进展的定义：一轮算"有进展"当且仅当出现以下至少一项——新增通过的测试用例、失败范围缩小、定位到此前未知的根因、产生新的可验证证据。仅写了新总结但上述都没有，记为"无进展"，「连续无进展」加一。
停止与升级：「已用轮数」达到「最大轮数」，或「连续无进展」达到「最大无进展轮数」时，停止循环并由 TeamLead 升级给用户，不自行无限重试。

后续动作

启动完成后确认：

团队协作上下文已成功建立
7 个项目级角色定义已加载（spec-explorer/writer/tester/executor/debugger/reviewer/ender）
已创建或确认当前 Spec 工作分支
阶段二（探索）已启动
用户已了解整体流程

常见陷阱

spec/ 目录不存在就启动（应先 spec-init）
跳过 git-work，直接在远程默认分支上开发
工作区有无关改动时切换分支
多个并发 Spec 共用同一个 working tree（应使用 git worktree）
在 spec-start 中重写角色定义，导致与 spec-init 持久化角色漂移
创建角色时混淆角色名（spec-writer）和 Skill 名（spec-write）
尝试创建 TeamLead 角色（当前 Agent 本身就是 TeamLead）
假设角色之间可以直接通信，绕过 TeamLead 中转
阶段转换时未等待用户确认就继续

name

spec-start

소스 정보

설치 방법

소스 파일 검토

이 저장소의 다른 Skills

Spec Start

核心原则

前置检查

角色总览

工作流程

步骤 1：澄清任务需求（理解 + 反问梳理 + 确认）

步骤 2：创建 Spec 工作分支

步骤 3：创建 Spec 角色目录并加载项目级角色定义

导航树清单 rk-manifest.js

步骤 4：创建本次 Spec Team Context

步骤 5：建立跨角色通信规则

步骤 6：启动阶段二（探索）

完整协作时序

用户确认节点

修复循环进展信号

后续动作

常见陷阱

이 저장소의 다른 Skills

Spec Start

核心原则

前置检查

角色总览

工作流程

步骤 1：澄清任务需求（理解 + 反问梳理 + 确认）

步骤 2：创建 Spec 工作分支

步骤 3：创建 Spec 角色目录并加载项目级角色定义

导航树清单 rk-manifest.js

步骤 4：创建本次 Spec Team Context

步骤 5：建立跨角色通信规则

步骤 6：启动阶段二（探索）

完整协作时序

用户确认节点

修复循环进展信号

后续动作

常见陷阱

导航树清单 `rk-manifest.js`

导航树清单 `rk-manifest.js`