R&K Flow - Spec 驱动式开发 Skills 体系

R&K Flow 是一套完整的 Spec 驱动式开发 Skills 体系，报告统一用 HTML 承载（固定样式 + 可追溯修订），用 Agent Teams 多角色协作架构 驱动开发流程。当前版本将开发拆分为 5 个阶段，由 7 个项目级专职角色分工协作，并通过每个 Spec 的 lead/team-context.md 保留运行账本、Git/PR 元数据、跨角色交接和问题闭环。

如果你对该工作流感兴趣,或者有疑问,欢迎加入我们的社群讨论

直接拉取本仓库到项目的 .agents/skills/，再把运行时目录软链接过去。不走 npm 分发，仓库即唯一分发源。

# 1. 拉取 Skills 到 .agents/skills/
git clone https://github.com/HHU3637kr/skills.git .agents/skills

# 2. 运行时目录软链接到 .agents/skills/（按需只建你在用的那一个）
ln -s ../.agents/skills .claude/skills
ln -s ../.agents/skills .codex/skills
ln -s ../.agents/skills .omp/skills

Windows（PowerShell，需管理员或开启开发者模式）：

git clone https://github.com/HHU3637kr/skills.git .agents\skills
New-Item -ItemType SymbolicLink -Path .claude\skills -Target ..\.agents\skills

后续更新直接在 .agents/skills/ 里 git pull，软链接的运行时目录自动同步，无需重装：

cd .agents/skills && git pull

[!tip] 为什么用软链接 单一副本、单一版本源。.claude / .codex / .omp 三套运行时共享同一份 Skills，git pull 一次全部生效，不会出现多份副本版本漂移。

然后在项目的 AGENTS.md 中添加入口导入。AGENTS.md 只作为项目身份和路由清单，详细规则、项目偏好和前端风格等长期约束放在 .agents/rules/：

@import .agents/rules/
@import .agents/skills/

Spec First - 一切从 Spec 开始

• 先设计，后实现
• 严格遵循 Spec，不添加额外功能
• 每个实现都可追溯到 Spec 文档
• 完整的开发过程记录为 HTML 报告，修改可追溯

Agent Teams - 多角色协作，各司其职

• TeamLead（当前 Agent）统一协调全局
• 7 个项目级专职角色：探索、设计、测试、实现、调试、审查、收尾
• 角色（Who）与 Skill（How）分离
• 5 阶段流程，每个阶段转换有用户确认门禁
• 通过 lead/team-context.md 记录运行路径、角色实例、产物、完成项、问题解决和 PR 状态

运行契约（Run Contract） - 先写刹车，再写循环

• 每个核心工作流 Skill 头部都有一张「运行契约」表：输入、权限、验证、停止、升级
• 把 Skill 当成有边界的循环单元，而不是一段无界的提示词；强调"什么时候停、什么时候交还给人"
• spec-test ↔ spec-debug 修复循环用 lead/team-context.md 的「修复循环预算」落实停止条件：max_rounds / max_no_progress_rounds 由用户进入循环前确认，触发上限即停止并升级
• 适用范围：7 个核心工作流 Skill + 3 个记忆管理 Skill（exp-search/exp-reflect/exp-write）；领域 Skill 不强制

┌───────────────────────────────────────────────────────────────────────────┐
│                    Spec 驱动式开发工作流 v2.7                              │
│                     Agent Teams 多角色协作架构                             │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  用户需求                                                                  │
│      ↓                                                                    │
│  ┌─────────────────────────────────────────────────────────┐              │
│  │ 阶段一：需求对齐                                         │              │
│  │ TeamLead + intent-confirmation → 用户确认                │              │
│  └────────────────────────┬────────────────────────────────┘              │
│      ↓ 【门禁 1：需求理解正确】                                             │
│  GitHub Flow：git-work 从 main 创建 Spec 工作分支                           │
│      ↓                                                                    │
│  ┌─────────────────────────────────────────────────────────┐              │
│  │ 阶段二：Spec 创建                                        │              │
│  │ spec-explorer → explorer/exploration-report.html          │              │
│  │ spec-writer ↔ spec-tester 协作讨论                        │              │
│  │ → writer/plan.html + tester/test-plan.html                │              │
│  └────────────────────────┬────────────────────────────────┘              │
│      ↓ 【门禁 2：设计方案 + 测试计划确认】                                   │
│  ┌─────────────────────────────────────────────────────────┐              │
│  │ 阶段三：实现                                              │              │
│  │ spec-executor → executor/summary.html                     │              │
│  └────────────────────────┬────────────────────────────────┘              │
│      ↓ 【门禁 3：实现确认】                                                │
│  ┌─────────────────────────────────────────────────────────┐              │
│  │ 阶段四：测试                                              │              │
│  │ spec-tester 执行测试 → tester/test-report.html            │              │
│  │ [如有 bug] spec-tester ↔ spec-debugger 修复闭环           │              │
│  └────────────────────────┬────────────────────────────────┘              │
│      ↓ 【门禁 4：测试报告确认】                                             │
│  ┌─────────────────────────────────────────────────────────┐              │
│  │ 阶段五：收尾                                              │              │
│  │ spec-reviewer 审查（gated 可选 / autopilot 强制）→ spec-ender │              │
│  │ → 规范维护审查 → 归档 → 推送 PR                            │              │
│  └─────────────────────────────────────────────────────────┘              │
│                                                                           │
├───────────────────────────────────────────────────────────────────────────┤
│                      双层互补记忆系统（复利工程）                             │
│  ┌─────────────────────────────────────────────────────────────────────┐  │
│  │                                                                     │  │
│  │  ┌─────────────────────────────────────────────────────────────┐    │  │
│  │  │  Auto Memory（自动层）— 运行时原生                            │    │  │
│  │  │  • 日常编码经验、调试技巧、项目模式                           │    │  │
│  │  │  • 运行时自主判断，零摩擦，覆盖 ~80% 轻量经验                 │    │  │
│  │  │  • 存储：由 Claude Code / Codex 等运行环境决定                │    │  │
│  │  └─────────────────────────────────────────────────────────────┘    │  │
│  │                                                                     │  │
│  │  ┌─────────────────────────────────────────────────────────────┐    │  │
│  │  │  exp-* 系统（显式层）— 项目级结构化记忆                       │    │  │
│  │  │                                                              │    │  │
│  │  │    ┌──────────┐      ┌──────────┐      ┌──────────┐         │    │  │
│  │  │    │ 经验记忆  │      │ 知识记忆  │      │ 程序记忆  │         │    │  │
│  │  │    │ 困境-策略 │      │ 项目理解  │      │   SOP    │         │    │  │
│  │  │    └────┬─────┘      └────┬─────┘      └────┬─────┘         │    │  │
│  │  │         └─────────────────┼─────────────────┘               │    │  │
│  │  │                           ↓                                  │    │  │
│  │  │  • 重大困境-策略对，Markdown 记忆库 + 索引检索              │    │  │
│  │  │  • 存储：spec/context/experience/ + knowledge/               │    │  │
│  │  └─────────────────────────────────────────────────────────────┘    │  │
│  │                                                                     │  │
│  │         开发前检索 ←─────────────→ 开发后分流沉淀                     │  │
│  │         (exp-search)               (exp-reflect)                    │  │
│  │         搜索两层记忆                重大→exp-write / 轻量→Auto Memory │  │
│  │                                                                     │  │
│  │         每次开发都利用历史经验，每次完成都沉淀新经验                    │  │
│  │                      知识形成复利，越用越快                            │  │
│  │                                                                     │  │
│  └─────────────────────────────────────────────────────────────────────┘  │
│                                                                           │
├───────────────────────────────────────────────────────────────────────────┤
│                         信息分层架构                                        │
│                                                                           │
│  AGENTS.md           → 项目身份 + 入口清单 + 路由（薄入口）                 │
│  .agents/roles/      → CLI 中立的项目级角色定义                              │
│  .claude/.codex/.omp → 运行时 Agent 适配                                     │
│  .agents/rules/      → 长期规则 + 项目偏好 + 前端风格（每文件 ≤ 20 行）      │
│  spec/*/*/lead/      → 每个 Spec 的 team-context 运行账本                    │
│  spec/context/       → 项目级结构化经验与知识（显式层）                       │
│  skills/             → 工作流程定义（精简核心 + references/ 按需加载）        │
│                                                                           │
└───────────────────────────────────────────────────────────────────────────┘

R&K Flow 文档中的“创建团队、创建角色、通知角色、请求用户确认”都是抽象协作动作，不是跨平台固定 API。项目初始化时会创建中立角色定义，运行时再由 OMP（Oh My Pi）、Claude Code、Codex 或其他 CLI 适配成自己的项目级 Agent / Subagent。

推荐运行时：OMP（Oh My Pi）。 R&K Flow 优先面向 OMP 设计、并在 OMP 上端到端验证；新项目若无特定约束，首选 OMP。原生 task spawn 对应角色层，落盘的 lead/team-context.md 承担账本与跨上下文恢复。OMP 16.4+ 适配要点：task 使用 { context, tasks: [{ name?, agent?, task }] }；.omp/agents/* 默认省略 tools 以继承完整启用工具集（避免窄白名单中断）；产品代码边界写在中立 role rules；model 按项目多模型策略可选配置。Claude Code、Codex 及其它 CLI 为受支持的备选适配，按各自能力降级。

如果运行环境提供子代理、消息或确认工具，可以映射到平台原生能力；如果没有，则按同一阶段顺序由单 Agent 串行执行。

spec-init 会创建中立角色定义，并按运行环境生成适配文件：

角色定义是项目级、可复用的；角色线程或子 Agent 实例是某次 Spec 运行中的临时 handle。跨 Spec 不依赖隐藏上下文，必须从落盘文档恢复。

每个 Spec 都有一个 TeamLead 维护的运行账本：

spec/<01-05分类>/<YYYYMMDD-HHMM-中文任务描述>/lead/team-context.md

lead/team-context.md 记录：

• 当前任务实际运行路径、阶段和门禁状态
• git_branch、base_branch、pr_url
• 角色 runtime handle（如 agent_id、thread_id、session_id）
• 产物注册表、跨角色 handoff、开放问题和下一步动作
• 共享完成区：「任务进度」
• 共享问题区：「问题闭环记录」（bug 与过程性问题，category 区分）
• 共享决策区：「决策记录」（每个实质取舍的选项、结论、理由）
• 修复循环预算区：「修复循环预算」（test-debug 循环的 max_rounds / max_no_progress_rounds / rounds_used / no_progress_streak）

维护边界：

• TeamLead 维护 frontmatter、当前运行路径、Git/PR 元数据、角色运行句柄、产物注册表、门禁决策、角色交接、开放问题与阻塞、下一步动作。
• 所有角色可共同维护「任务进度」，但只追加或更新自己负责的任务行。
• 发现或解决问题的角色可共同维护「问题闭环记录」，但只追加或更新自己相关的问题行；不止 bug，环境、依赖、阻塞、流程、范围偏差都记。
• 遇到需要拍板的取舍时，拍板方在「决策记录」追加一行；用户决策由 TeamLead 代记，保留被否决的选项和理由。
• 「修复循环预算」的上限值由用户在进入修复循环前通过 TeamLead 确认；rounds_used / no_progress_streak 由 spec-debugger 和 spec-tester 每轮更新，触发上限时停止循环并升级给用户。
• 账本全部手动维护：产物落盘、问题闭环、取舍拍板后立即更新对应区块，不依赖自动记账。

R&K Flow 把 GitHub Flow 作为 Spec 生命周期的一部分，而不是最后一步提交动作。

分支命名使用 <type>/spec-<YYYYMMDD-HHMM>-<ascii-slug>，例如 feat/spec-20260109-1430-evaluator-agent。多个 Spec 并发开发时使用 git worktree，每个 Spec 独占工作目录和分支。

R&K Flow 明确区分角色（Who）和 Skill（How）。角色是 Agent Teams 中的成员身份，Skill 是角色调用的工作流程。

项目首次使用时，调用 spec-init 检查/初始化 Git 仓库，并搭建完整项目骨架（AGENTS.md、.agents/rules/、.agents/skills/、.agents/roles/、spec/ 目录、记忆系统、HTML 报告资产），同时生成 OMP / Claude Code / Codex 等运行时适配文件。

每次开始新任务时，调用 spec-start 启动 Agent Teams：

创建分支：<type>/spec-{YYYYMMDD-HHMM}-{ascii-slug}
创建团队：spec-{YYYYMMDD-HHMM}-{任务简称}
团队说明：Spec 驱动开发: {任务描述}
创建目录：lead/ explorer/ writer/ tester/ executor/ debugger/ reviewer/ updater/ ender/
加载角色：spec-explorer / spec-writer / spec-tester / spec-executor / spec-debugger / spec-reviewer / spec-ender
创建账本：lead/team-context.md

当前 Agent 自动成为 TeamLead，无需创建额外的 TeamLead 角色。

阶段一：需求对齐
  TeamLead（当前 Agent）→ intent-confirmation → 用户确认
      ↓ 【门禁 1】

GitHub Flow 准备
  TeamLead → git-work → 从 main 创建 Spec 工作分支
  TeamLead → 创建角色目录与 lead/team-context.md
  TeamLead → 在 lead/team-context.md 记录 git_branch / base_branch / pr_url
      ↓

阶段二：Spec 创建
  TeamLead → spec-explorer 开始
  spec-explorer → explorer/exploration-report.html → TeamLead 中转给 spec-writer + spec-tester
  spec-writer ↔ spec-tester 协作讨论接口边界
  两者完成 → 通知 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 → spec-debugger → 修复 → 重新验证
  spec-tester → tester/test-report.html → 通知 TeamLead
  spec-reviewer → reviewer/review.html（gated 可选 / autopilot 强制）
  TeamLead → 门禁 4：gated 由用户确认 tester/test-report.html；autopilot 由 reviewer/review.html 替代该确认
      ↓ 【门禁 4】

阶段五：收尾
  TeamLead → spec-ender 开始
  spec-ender → ender/end-report.html + 多角色讨论 + exp-reflect → 规范维护审查 → 用户确认归档
  spec-ender → git-work 提交 + 推送 + 创建 PR
  spec-ender → 通知 TeamLead，Teams 进入待机

此外用户可在任意时刻主动调用 spec-review 进行详细审查

spec-tester 发现 bug
    ↓
通知 spec-debugger（含复现步骤）
    ↓
spec-debugger 诊断问题
    ↓
创建 debugger/debug-xxx.html（诊断文档）
    ↓
TeamLead 向用户确认诊断
    ↓
执行修复
    ↓
创建 debugger/debug-xxx-fix.html（修复总结）
    ↓
通知 spec-tester 重新验证
    ↓
spec-tester 验证通过 → 记录到 tester/test-report.html

⚠️ 为什么不直接修改 writer/plan.html？

writer/plan.html 是已经用户确认的设计文档，不应因为执行问题而被修改。通过创建 debug 文档：

• 保持设计的完整性和可追溯性
• 记录问题和修复历史，形成知识库
• 与 spec-update 区分（update 用于主动迭代，debug 用于被动修复）

适用场景：同一个活跃 Spec 在当前工作分支内需要小迭代、补充需求、修正方案或优化实现。若原 Spec 分支已合并/关闭，后续需求默认新建 Spec。

同一活跃 Spec 的需求/设计发生小变化（原 `writer/plan.html` + `executor/summary.html` 已存在）
    ↓
git-work 确认当前分支等于 lead/team-context.md 的 git_branch
    ↓
spec-update 创建 updater/update-xxx.html（放在原 Spec 的 updater/ 目录）
    ↓
用户确认更新方案
    ↓
spec-update 执行更新
    ↓
spec-update 创建 updater/update-xxx-summary.html
    ↓
spec-review 创建 reviewer/update-xxx-review.html + 用户确认
    ↓
exp-reflect 经验反思 + 规范维护审查
    ↓
git-work 提交 + 推送当前 Spec 分支；必要时创建/更新 PR
    ↓
完成（不归档，保留在原目录）

此外用户可在任意时刻主动调用 spec-review 进行详细审查

loop-design 不属于某个固定角色，也不在 Spec 执行链路上——它只产出 Loop 定义，不驱动执行。先由 intent-confirmation 把意图澄清清楚，再把重复任务设计成一个有边界的 Loop（运行契约 + 循环预算），产出的定义既可套用到 R&K Flow 内的 loop（如 spec-test ↔ spec-debug 修复循环），也可用于自定义 loop。

intent-confirmation（澄清意图）
        │  复用澄清结果
        ▼
loop-design（设计有边界的 Loop）
        │  产出 Loop 定义：运行契约 + 循环预算
        ▼
┌──────────────────────────────────────────┐
│ R&K Flow 内 loop                           │  例：spec-test ↔ spec-debug
│ （套用「修复循环预算」：最大轮数 /          │       修复循环
│   最大无进展轮数 触发即停并升级）           │
│ 或 自定义 loop                              │
└──────────────────────────────────────────┘
        ▲
        └─ loop-design 只产出定义，不直接驱动循环执行

spec/
├── 01-产品规划/          # PRD、路线图、需求拆解、用户流程、里程碑
├── 02-技术设计/          # 架构、数据模型、模块边界、技术选型、迁移方案
├── 03-能力交付/          # 新功能、新接口、新页面、新集成、新工作流
├── 04-系统改进/          # Bug、回归、性能/安全问题、配置依赖、无新能力的重构
├── 05-验证工程/          # 独立测试策略、回归验证、覆盖率提升、审计日志方案
├── 06-已归档/           # 已完成的 Spec（由 spec-end 移动）
└── context/             # 记忆系统（与 Spec 工作流一致）
    ├── experience/      # 经验记忆存储（显式层）
    │   ├── index.md     # 经验索引
    │   └── exp-xxx-标题.md  # 经验详情
    └── knowledge/       # 知识记忆存储（显式层）
        ├── index.md     # 知识索引
        └── know-xxx-标题.md  # 知识详情

运行时原生记忆                 # Auto Memory（自动层，由当前 CLI 管理）
    └── 具体位置由 Claude Code / Codex 等运行环境决定

每个 Spec 目录遵循以下命名规范：

spec/分类目录/YYYYMMDD-HHMM-任务描述/
├── lead/
│   └── team-context.md        # TeamLead 维护的运行账本与 Git/PR 元数据
├── explorer/
│   └── exploration-report.html # 探索报告（spec-explore 创建）
├── writer/
│   └── plan.html              # 设计方案（spec-write 创建）
├── tester/
│   ├── test-plan.html         # 测试计划（spec-test 创建）
│   ├── test-report.html       # 测试报告（spec-test 创建）
│   └── artifacts/
│       └── test-logs/         # 测试代码自动采集的日志/JSON/证据
├── executor/
│   └── summary.html           # 实现总结（spec-execute 创建）
├── debugger/
│   ├── debug-001.html         # 问题诊断（spec-debug 创建）
│   └── debug-001-fix.html     # 修复总结（spec-debug 创建）
├── reviewer/
│   ├── review.html            # 审查报告（gated 可选 / autopilot 必有，spec-review 创建）
│   └── update-001-review.html # 更新审查（同上）
├── updater/
│   ├── update-001.html        # 更新方案（spec-update 创建）
│   └── update-001-summary.html # 更新总结（spec-update 创建）
└── ender/
    └── end-report.html        # 收尾报告（spec-end 创建）

外层目录分类的是“这个 Spec 作为一件工作的主意图”；目录内部按角色目录保存生命周期产物，根目录不再平铺角色产物。03-能力交付 只用于新增用户可感知能力；修复、优化、重构、技术债默认优先考虑 04-系统改进；架构和数据模型优先考虑 02-技术设计；独立测试工作优先考虑 05-验证工程。同一活跃 Spec 分支内的小变化使用 spec-update 留在原目录；已合并/已关闭后的新需求默认新建 Spec。

R&K Flow 的报告类产物统一用 HTML 承载，格式契约见 html-report/SKILL.md。目标只有三条：阅读体验好、重点突出、反复修改可追溯。

9 类报告类产物一律 .html：

账本可用 Markdown 或 HTML；记忆库必须保持 Markdown：

tester/artifacts/test-logs/** 保持测试运行的原始格式，属于证据不是报告。

这是 HTML 报告最核心的能力。报告被反复修改是常态，但用户必须能看清两版之间改了什么。每轮修改四件事一起做：

1. 报告头修订号 +1（r1 → r2），同步 <meta name="rk:revision">
2. 「修订历史」表追加一行，写清改了什么、为什么、谁改的
3. 正文用语义标签标记，每个标记都带 data-rev="{本轮修订号}"
4. 原文永远保留在 <del> 里，不删除

<!-- 行内修订 -->
超时设为 <del class="rk-del" data-rev="2">30s</del>
         <ins class="rk-ins" data-rev="2">10s</ins>

<!-- 块级修订 -->
<p class="rk-removed" data-rev="2">删掉的整段旧方案。</p>
<p class="rk-added" data-rev="2">新增的整段新方案。</p>

rk-report.js 自动在 .rk-revbar 渲染三视图切换按钮，同一个文件三种读法：

修订历史表固定 5 列（修订 / 日期 / 修改人 / 改了什么 / 原因），与 lead/team-context.md 的「决策记录」互补：账本记「为什么这么定」（选项、结论、理由，编号 D-001），报告修订历史记「文本上改了什么」。修订源于实质取舍时，「原因」列引用决策编号，例如 按 D-003（多实例部署需共享缓存）；纯笔误、措辞、补充说明就直接写清原因，不编造编号。决策过程正文留在账本，不复制进报告。

原 YAML frontmatter 有两个作用，HTML 两个都保留，缺一不可。<head> 里逐字段写 <meta name="rk:*"> 供脚本和检索读取，<header class="rk-head"> 的 .rk-meta 镜像同样字段给人看：

<meta name="rk:type"        content="plan">
<meta name="rk:spec-dir"    content="spec/03-能力交付/20260109-1430-登录限流">
<meta name="rk:role"        content="spec-writer">
<meta name="rk:created"     content="2026-01-09">
<meta name="rk:updated"     content="2026-01-11">
<meta name="rk:revision"    content="2">
<meta name="rk:git-branch"  content="feat/spec-20260109-1430-login-throttle">
<meta name="rk:base-branch" content="main">
<meta name="rk:pr-url"      content="">
<meta name="rk:tags"        content="spec,plan">

原模板有几个 frontmatter 字段，HTML 就要有几个对应的 <meta> / <link>。不因为"HTML 里看不见"就删字段。 Git/PR 元数据仍以 lead/team-context.md 为准，报告只镜像不作为权威源。

关联的价值不只是能跳过去，还要能反查「谁引用了我」。报告末尾「关联产物」拆成两段：

<h2>关联产物</h2>
<h3>本报告引用</h3>
<ul class="rk-links">
  <li><a href="../writer/plan.html" data-rk-link="plan">设计方案</a></li>
  <li><a href="../lead/team-context.md" data-rk-link="ledger">运行账本</a></li>
</ul>
<h3>引用本报告</h3>
<ul class="rk-backlinks">
  <li><a href="../reviewer/review.html" data-rk-backlink="review">审查报告</a></li>
</ul>

规则：报告 A 引用 B 时，A 的 rk-links 加一条，同时 B 的 rk-backlinks 补一条；谁新建关联谁负责补对侧。对侧报告还没产出时先在自己的 rk-links 里标注「（待创建）」，等它产出再补反链。data-rk-link / data-rk-backlink 可被脚本提取，构成可查询的关联图谱。

<!-- 结论块：is-pass 绿 / is-fail 红 / 默认蓝，放在最前面 -->
<section class="rk-verdict is-pass">
  <div class="rk-verdict-label">测试结论</div>
  <p>42 项用例全部通过。</p>
</section>

<!-- 指标卡 -->
<div class="rk-kpis">
  <div class="rk-kpi is-pass"><div class="v">42</div><div class="k">通过</div></div>
  <div class="rk-kpi is-fail"><div class="v">1</div><div class="k">失败</div></div>
</div>

<!-- Callout：key 关键决策 / warn 注意 / risk 风险 / ok 通过 -->
<div class="rk-cal key"><div class="t">关键决策</div><p>选 A 方案，因为 B 会引入循环依赖。</p></div>

<!-- 代码位置引用 -->
<span class="rk-ref">src/auth/token.ts:88</span>

所有样式集中在 html-report/assets/rk-report.css，报告本身不写 <style> 也不写行内 style=。改一处样式，全部历史报告一起改版；换配色、调排版都不需要动任何报告文件。同理禁止外部 CDN 和网络字体——报告双击 file:// 打开就能完整阅读，断网、离线归档、打包发给别人都不掉样式。

本项目使用当前运行环境可用的确认方式实现用户确认工作流。每个阶段转换前都设有门禁节点，由 TeamLead 统一发起，确保用户始终掌控开发方向。

[!note] 平台映射 如果环境支持原生确认工具（如 AskUserQuestion），优先使用工具；如果不支持，TeamLead 直接向用户提问并等待明确回复。

确认目标：writer/plan.html 与 tester/test-plan.html 已创建完成，是否可以开始实现？
确认选项：
- 确认，开始实现
- 需要修改（请说明修改要求）

⚠️ 为什么需要 intent-confirmation？

当请求存在理解风险时，先确认用户意图，避免因理解偏差导致的无效工作。触发条件包括：

• 抽象需求：需求描述较为模糊（如"优化一下这个功能"）
• 设计决策：涉及架构变更或设计选择
• 多义表达：用户表达可能有多种理解
• 大范围影响：任务影响范围较大

用户：我需要实现一个专业评价 Agent

TeamLead（当前 Agent）：
调用 spec-start，建立协作上下文 "spec-20260109-1430-专业评价Agent"
使用 intent-confirmation 与用户对齐需求...
调用 git-work，从 main 创建分支 feat/spec-20260109-1430-evaluator-agent
创建角色目录和 lead/team-context.md...
加载 7 个项目级角色...

TeamLead → spec-explorer 开始

spec-explorer：
  调用 exp-search 检索历史经验...
  探索项目代码库，产出 explorer/exploration-report.html
  更新 lead/team-context.md 的「任务进度」

spec-explorer → TeamLead 中转给 spec-writer + spec-tester

spec-writer ↔ spec-tester 协作讨论接口边界
spec-writer：创建 writer/plan.html（设计方案）
spec-tester：创建 tester/test-plan.html（测试计划）

TeamLead → 用户确认 writer/plan.html + tester/test-plan.html

用户：确认，开始实现

TeamLead → spec-executor 开始
spec-executor：
  读取 writer/plan.html 和 lead/team-context.md，检索历史经验
  按计划逐步实现
  创建 executor/summary.html
  更新 lead/team-context.md 的「任务进度」

TeamLead → 用户确认 executor/summary.html

TeamLead → spec-tester 开始执行测试

spec-tester：
  按 tester/test-plan.html 执行测试用例
  测试代码自动采集 tester/artifacts/test-logs/<run-id>/ 下的日志/JSON/证据
  发现 bug → 在 lead/team-context.md 的「问题闭环记录」记录问题并通知 TeamLead
  TeamLead → 用 intent-confirmation 与用户确认修复循环预算（max_rounds / max_no_progress_rounds）
           → 写入 lead/team-context.md 的「修复循环预算」
  TeamLead → spec-debugger 修复（每轮更新 rounds_used / no_progress_streak）→ TeamLead → spec-tester 重新验证
  触发预算上限或连续无进展 → 停止循环 → TeamLead 升级给用户（继续加预算 / 改方案 / 暂停）
  产出 tester/test-report.html

审查（gated 可选 / autopilot 强制）：
  TeamLead → spec-reviewer 审查 → reviewer/review.html

门禁 4：gated 由用户确认 tester/test-report.html（和 reviewer/review.html 如有）；autopilot 由 reviewer/review.html 替代

TeamLead → spec-ender 开始

spec-ender：
  向各角色发起讨论，收集经验素材
  调用 exp-reflect 分流沉淀
  审查是否需要维护 AGENTS.md / .agents/rules/
  创建 ender/end-report.html
  询问用户：是否归档、提交、推送并创建 PR？

用户：确认归档

spec-ender → 移动到 06-已归档 → 调用 git-work 提交、推送、创建 PR
spec-ender → 通知 TeamLead，Teams 进入待机

完整的 Agent Teams 流程适合复杂需求，但并非所有场景都需要走全套。以下两种轻量用法同样有效：

小需求 / 快速迭代：直接单独调用某个 Skill，例如只用 spec-write 写方案、只用 spec-update 做小改动，无需启动完整的 Agent Teams 流程。

非 Claude Code / Codex 用户（Cursor、Windsurf 等）：这套 Skills 同样适用。将 spec-start 的流程交给单 Agent 按顺序执行，并使用 .agents/roles/ 与 lead/team-context.md 保存状态。每个 Skill 文件都是独立的 Markdown 提示词，可以直接粘贴到任意 AI 编辑器中使用。

R&K Flow 不依赖 Claude Code 的 /goal 或 Dynamic Workflows；它们只是 Claude Code 用户的可选增强层。推荐原则：

• /goal 适合让 Claude Code 按 R&K Flow 持续推进，直到实现、测试和审查条件满足。
• Dynamic Workflows 适合由 TeamLead 在探索、测试、审查阶段发起并行扫描。
• Workflow 可以并行收集素材，但最终状态必须写回当前 Spec 目录。
• 不建议让多个 workflow agent 同时修改同一批代码文件。

/goal 使用 /spec-start 启动一个新 Spec，目标是实现「用户登录失败次数限制」功能。
请按 R&K Flow 推进：探索 → plan.html → 实现 → 测试 → review。
无需在每个阶段停下来问我，除非发现需求不清、会破坏现有接口、需要删除数据或涉及高风险改动。

完成条件：
1. executor/summary.html 已生成
2. tester/test-report.html 显示关键用例通过
3. reviewer/review.html 没有高优先级问题
4. 构建和相关测试命令通过
5. 最后给出改动摘要和验证证据

/spec-start 为「personal-web 增加文章搜索高亮」创建 Spec。

等 spec-start 建好上下文后：

/goal 从当前 Spec 继续推进，直到实现完成、测试通过、review 无阻塞问题。
阶段间不用反复确认，按 R&K Flow 写回所有角色产物。
如果 plan.html 与实际代码冲突，停止并说明冲突点。

/spec-start 为「重构订单结算模块」创建 Spec。

TeamLead：在 spec-explore 阶段使用 Claude Code Dynamic Workflow 做并行探索。
请让 workflow 分成以下方向：
1. 订单状态流转
2. 支付与退款调用链
3. 数据模型和数据库写入点
4. 权限与异常处理
5. 现有测试覆盖和缺口

要求：
- workflow 只读代码，不修改文件
- 最终汇总到 explorer/exploration-report.html
- 标出高风险区域、建议改动边界和测试重点

TeamLead：当前 executor/summary.html 已完成。
请在 spec-review 阶段使用 Dynamic Workflow 并行审查实现。

分工：
1. 对照 writer/plan.html 检查功能完整性
2. 检查接口签名、数据结构、命名是否一致
3. 检查是否有 Spec 未定义的额外实现
4. 检查测试证据是否覆盖关键路径
5. 检查潜在安全、权限、回归风险

要求：
- 不修改代码
- 所有发现汇总进 reviewer/review.html
- 每个问题必须带 Spec 位置和代码位置

TeamLead：让 spec-tester 使用 Dynamic Workflow 扩展测试覆盖。
请并行分析以下测试面：
1. 正常用户路径
2. 空值和边界输入
3. 权限失败路径
4. 网络/API 异常路径
5. 回归风险路径

输出：
- 更新 tester/test-plan.html
- 执行可运行的测试
- 把日志、截图、trace 或命令输出放入 tester/artifacts/test-logs/
- 最终生成 tester/test-report.html

本项目实现了双层互补的记忆架构：运行时原生记忆负责轻量上下文，基于 MUSE 框架的项目级经验系统负责可追溯沉淀。不同 CLI 的原生记忆能力不同，但显式层始终落在项目目录中。

┌─────────────────────────────────────────────────────────────────────┐
│                     双层互补记忆架构                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Auto Memory（自动层）— 运行时原生                             │  │
│  │  ├─ 日常编码经验、调试技巧、项目模式                          │  │
│  │  ├─ 运行时自主判断是否记录，零摩擦                            │  │
│  │  ├─ 覆盖 ~80% 的轻量经验捕获                                 │  │
│  │  └─ 存储：由 Claude Code / Codex 等运行环境决定               │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  exp-* 系统（显式层）— 项目级结构化记忆                       │  │
│  │  ├─ 经验记忆：重大困境-策略对 → spec/context/experience/      │  │
│  │  ├─ 知识记忆：项目理解/技术调研 → spec/context/knowledge/     │  │
│  │  ├─ 程序记忆：可复用 SOP → sop-xxx Skill                     │  │
│  │  ├─ 工具记忆：Skill 后续动作 → Skill 末尾                    │  │
│  │  └─ 覆盖 ~20% 的重要记忆，Markdown 记忆库 + 索引检索          │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  职责边界：                                                          │
│  • Auto Memory 和 exp-* 互补不冲突，各自管各自的存储                │
│  • exp-* 系统不写运行时原生记忆文件                                 │
│  • exp-search 可只读检索运行时原生记忆（若当前环境提供）             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

管理者：当前运行环境自身（自主判断）

内容：日常编码经验、调试技巧、项目模式、个人编码习惯

特点：个人的、自动的、非结构化的、零摩擦

存储位置：由运行环境决定。例如 Claude Code 可使用 ~/.claude/projects/*/memory/。

写入时机：当前运行环境在工作过程中自主判断，无需用户干预

存储位置：spec/context/experience/exp-xxx-标题.md

索引位置：spec/context/experience/index.md

加载方式：索引全量加载，详情按需检索

存储格式：

---
id: EXP-xxx
title: 标题
keywords: [关键词1, 关键词2]
scenario: 适用场景
created: YYYY-MM-DD
---

# 标题

## 困境
[描述遇到的问题]

## 策略
[解决方案步骤]

## 理由
[为什么这个策略有效]

写入时机（仅重大经验）：

• 涉及多组件协调、非显而易见的解决方案
• 需要链接到 Spec/代码文件的结构化记录
• 团队/项目级别需要共享的经验
• 长期有效的架构决策和设计模式

管理 Skill：exp-search、exp-reflect、exp-write

存储位置：spec/context/knowledge/know-xxx-标题.md

索引位置：spec/context/knowledge/index.md

加载方式：索引全量加载，详情按需检索

存储格式：

---
id: KNOW-xxx
title: 标题
type: 项目理解 / 技术调研 / 代码分析
keywords: [关键词1, 关键词2]
created: YYYY-MM-DD
---

# 标题

## 概述
[简要说明核心内容]

## 详细内容
[根据类型组织内容：项目理解/技术调研/代码分析]

## 相关文件
[涉及的文件路径]

写入时机：

• 探索项目架构、数据流后
• 完成技术调研、框架对比后
• 深入分析某个模块的设计后

管理 Skill：exp-search、exp-reflect、exp-write

存储位置：.agents/skills/sop-xxx-名称/SKILL.md

加载方式：

• Skill 的 description 作为索引（始终可见）
• Skill 的正文作为 SOP 内容（触发时才加载）

SOP 判断标准（只有满足以下条件才创建 SOP）：

• 有明确的触发动作（如"部署"、"发布"）
• 有可机械执行的步骤序列
• 每次都按相同顺序执行
• 核心是"怎么做"而非"为什么"

写入时机：

• 完成了可重复执行的操作流程
• 发现了固定的操作模式

存储位置：每个 Skill 文件的末尾「后续动作」章节

加载方式：随 Skill 一起加载，执行完 Skill 后自动参考

写入时机：

• 发现某个操作后总是需要特定的后续步骤
• 工具调用有固定的检查或验证模式
• 一个 Skill 执行后经常需要调用另一个 Skill

exp-reflect 会对识别出的经验进行权重判断，自动分流：

手动触发：

/exp-search <关键词>        # 检索相关记忆（含 Auto Memory 只读搜索）
/exp-reflect               # 反思当前 Spec 文档，自动识别记忆类型并分流
/exp-reflect 记录数据流     # 带提示词，引导识别为知识记忆
/exp-write type=experience # 写入经验记忆（通常由 exp-reflect 调用）
/exp-write type=knowledge  # 写入知识记忆（通常由 exp-reflect 调用）

自动提示：

• 解决了反复出现的困难问题 → 经验记忆（exp-write）
• 探索了项目架构、数据流 → 知识记忆（exp-write）
• 完成了技术调研、框架对比 → 知识记忆（exp-write）
• 完成了一个可重复的操作流程 → 程序记忆（SOP）
• 形成长期编码、安全、测试、日志、审计、产品体验或前端样式约束 → 项目规范/规则（薄入口 AGENTS.md 或 rules）
• 发现某个操作后总是需要特定的后续步骤 → 工具记忆
• 日常编码技巧和调试经验 → Auto Memory（自动处理）

spec-init 负责创建薄入口 AGENTS.md 和 .agents/rules/，spec-end 负责让它们在每个 Spec 收尾时被轻量审查。审查问题是：本次是否产生了以后都要遵守的项目规范、项目偏好或前端样式？

原则：AGENTS.md 只写入口清单和身份摘要，不承载长篇规范；长期规则和项目偏好优先更新已有 rules 文件，必要时再创建新规则文件；规范文件每次会话都会加载，必须短、明确、可执行。

• 明确性：需求和设计必须清晰明确
• 完整性：包含所有必要的技术细节
• 可追溯性：设计决策要有依据
• 可实施性：提供具体的实现步骤

• Spec 优先：只实现 Spec 中定义的功能
• 开发顺序：Framework 服务层 → Agent 层 → API 层
• 严格遵循：不添加 Spec 中未定义的功能
• 可追溯性：每个功能都能追溯到 Spec 的具体章节

• 命名规范：YYYYMMDD-HHMM-任务描述（任务描述必须中文）
• 分类存放：必须按任务主意图放入对应工作类型目录，不要默认放入 03-能力交付
• 关联可追溯：报告末尾「关联产物」用相对路径 <a href> 链接上下游产物
• 元数据完整：报告头 .rk-meta 写全类型/Spec/角色/分支/创建日期/修订号；Markdown 文档保留完整 frontmatter

• 意图确认：满足触发条件时使用 intent-confirmation 避免理解偏差
  • 触发条件：抽象需求、设计决策、多义表达、大范围影响
  • 确认方式：复述用户意图、列出关键理解点、询问"是这个意思吗？"
• 门禁机制：每个阶段转换都等待用户确认
• 审查机制：spec-review 验证实现是否符合 Spec
• 防止重复：exp-search 检索是否已存在相似经验
• 测试闭环：spec-tester 与 spec-debugger 的 bug 修复闭环

• 角色职责清晰：不越权操作（如 spec-executor 只写自己实现代码的单元测试，不出最终测试结论）
• TeamLead 中转：跨角色通信默认通过 TeamLead 转交，角色只声明建议接收方
• Team Context 及时更新：TeamLead 维护控制面；各角色维护自己在「任务进度」和「问题闭环记录」中的行
• 闭环通知：完成工作后必须把产物路径、状态和需要的 handoff 返回 TeamLead
• 不跳过门禁：阶段转换必须经过用户确认
• TeamLead 统一协调：所有用户交互由 TeamLead 发起

1. 理解 Spec 驱动开发理念

   • 阅读 AGENTS.md 了解项目身份和入口路由，再阅读 .agents/rules/ 的长期规则
   • 阅读 spec/ 目录下现有 Spec 了解文档风格

2. 熟悉 Agent Teams 工作流

   • 了解 7 个项目级角色的分工和协作方式
   • 了解 5 个阶段和门禁机制
   • 了解 lead/team-context.md 的维护边界
   • 阅读各 Skill 的 SKILL.md 了解具体流程

3. 熟悉 HTML 报告规范

   • 阅读 html-report/SKILL.md 了解固定骨架、组件和修订标记
   • 打开 html-report/example/test-report.html 直观感受三视图切换

4. 开始第一个 Spec

   • 使用 spec-init 初始化项目基础设施
   • 使用 spec-start 启动 Agent Teams
   • 经历完整的 5 阶段流程，体验门禁机制和多角色协作

# 在支持 Skills 的 CLI 中调用

/spec-init        # 项目初始化（一次性）
/spec-start       # 创建 Spec 分支、角色目录和 Team Context，并启动 Agent Teams
/spec-explore     # 前置信息收集
/spec-write       # 撰写设计方案
/spec-test        # 撰写测试计划 / 执行测试
/spec-execute     # 执行新功能开发
/spec-debug       # 诊断并修复问题
/spec-end         # 收尾（经验沉淀 + 归档 + 推送 PR）
/spec-update      # 在当前 Spec 分支内执行小更新
/spec-review      # 审查实现情况

/exp-search       # 检索历史经验
/exp-reflect      # 反思并沉淀经验
/find-skills      # 搜索开源 Skill
/intent-confirmation  # 确认用户意图

• AI Agent: OMP（推荐）/ Claude Code / Codex / 兼容 AI 编程 Agent
• 报告格式: HTML（固定样式 + ins/del 修订标记 + 三视图）
• 版本控制: Git
• 文档格式: 标准 Markdown（账本与记忆）+ HTML（报告）
• 数据格式: YAML (frontmatter)

• AGENTS.md - 项目身份与入口清单
• spec/ - 所有 Spec 文档
• .agents/roles/ - CLI 中立的项目级角色定义
• .agents/skills/*/SKILL.md - 各 Skill 的详细说明
• html-report/SKILL.md - 报告 HTML 契约；html-report/assets/ - 共享样式与脚本

• Claude Code Documentation
• Skills CLI & Ecosystem

1. 参考 skill-creator/SKILL.md 的指南
2. 在 .agents/skills/ 下创建新目录
3. 编写 SKILL.md 文件
4. 核心工作流 / 记忆管理类 Skill 在标题后补一张「运行契约」表（输入/权限/验证/停止/升级）
5. 更新本 README 的 Skills 列表

1. 直接编辑对应 Skill 的 SKILL.md
2. 遵循 Skill 的更新规范
3. 修改职责或边界时，同步更新该 Skill 的「运行契约」表
4. 更新相关文档引用

版本: 2.8.0 最后更新: 2026-08-09 维护者: 项目团队

核心改进：

1. 双运行模式：每个 Spec 在阶段一确定 mode（gated 门禁 / autopilot 自动驾驶），写入账本 frontmatter 与各报告 rk:mode。模式的语义是换验证器，不是放宽标准——门禁模式下人是验证器，自动驾驶把人拿掉就必须由指定的机械纪律补位；找不到补位物的门禁一律列入「永远门禁」。.agents/rules/spec-workflow.md 把「已确认」定义为两义：用户确认，或自门禁通过（仅 autopilot，且必须附机械证据）。
2. 三条不可协商的纪律进常驻规则层：测试先行、根因优先、新鲜验证。放 .agents/rules/ 而非各 Skill，因为所有 spec-* 都是 disable-model-invocation: true、只在角色显式调用时加载；Iron Law 若也按需加载，等于让被约束者自己决定是否加载约束自己的规则。执行细则下沉各 Skill 的 references/，由运行契约按机械可判的条件路由（「任务涉及代码改动 → 开工前必读 X」，不写「如需要可参考」）。
3. 决策依据可机械校验：账本「决策记录」新增「依据」列，只接受三种形式——①文件路径+行号 ②命令+退出码+输出位置 ③用户原话引用。「根据经验」「通常做法」不是依据：理由可以被生成，依据必须可追。「门禁决策」新增「判定方式」列（user / self+evidence）。
4. spec-executor 取得单元测试所有权：分工改为按测试层级而非「能否写测试」划分——executor 拥有单元/聚焦测试并按 TDD 实现，tester 拥有集成/端到端/回归、测试质量评估与最终结论。新增 spec-execute/references/tdd-discipline.md（RED 三确认、测试有效性门函数「什么改动会让这个测试失败」、mock 四规则、假测试形态、非代码改动的三类处理）。原「executor 不写测试」散布六处，已同步清理。
5. 实现期证据不可手写：新增 executor/artifacts/，套用与 tester/artifacts/ 相同的规则——内容必须由测试运行本身产出，Agent 不得手写、补写或回填；必须能看出跑了什么命令、退出码多少、失败断言原文是什么。
6. 角色跨 Spec 持续在场：修正「运行时 handle 不重要」的误导表述——同一进程内 handle 是续接同一角色的唯一途径。账本「角色运行句柄」的状态改为映射真实四态（running / idle / parked / aborted），新增「续接方式」（hub-send / respawn+rebuild）与「累计参与 Spec 数」两列。续接只能发消息，不能重新 spawn：同名再 spawn 会得到零历史的影子角色。隔离工作区与角色持久化互斥，故不启用。
7. 默认分支不再写死 main：改为读 git symbolic-ref refs/remotes/origin/HEAD，兼容 master 等实际主分支名。

验证：.agents/rules/ 与 .claude/rules/ 5 个文件逐一比对一致（此前镜像漂移：.claude/ 版还在说 plan.md 与 Obsidian）；file:// 下实测确认 fetch 被安全策略拒绝而 <script src> 正常加载，据此选定导航树实现方式。

核心改进：

1. 报告统一用 HTML 承载：9 类报告产物（exploration-report / plan / test-plan / test-report / summary / debug-* / debug-*-fix / review / update-* / end-report）从 Markdown 改为 .html。动因是 Markdown 在「重点突出」和「反复修改可追溯」两件事上做不到位——报告是给人读的决策依据，需要固定版式和视觉层次，而不是纯文本流。
2. 新增 html-report Skill 作为报告契约：固定骨架、修订规范、组件用法、双向关联规则集中在一处。assets/rk-report.css 是唯一样式源（改一处即全部报告改版），assets/rk-report.js 提供修订视图切换。禁止在报告内写 <style> / 行内 style= / 外部 CDN，报告离线可读。
3. 可追溯修订机制：铁律是永不静默改写原文。每轮修改必须递增修订号、在「修订历史」表追加一行（改了什么 + 为什么），正文用 <ins class="rk-ins" data-rev="N"> / <del class="rk-del" data-rev="N"> 标记并带 rN 角标。配套三视图切换：全部修订（看完整演进）/ 仅最新修订（只看本轮改动）/ 终稿（隐藏删除、去高亮，当干净最终版读）。
4. 与「决策记录」联动：修订源于实质取舍时，「原因」列引用 v2.6.0 的决策编号（如 按 D-003（多实例部署需共享缓存））；纯笔误、措辞类修改直接写清，不编造决策编号。决策正文仍留在账本，不复制进报告。
5. 功能等价保留，不因换格式而丢能力：
   • frontmatter 双轨：原 YAML 字段逐项映射为 <meta name="rk:type|spec-dir|role|created|updated|revision|git-branch|base-branch|pr-url|tags">（机器可读，供检索与工具化处理）+ .rk-meta 可视镜像（人可读）；文档关联字段映射为 <link rel="rk-plan|rk-debug|rk-update|rk-ledger">。禁止因为「HTML 里看不见」就删字段。
   • 双链双向：Obsidian 双链的价值不只是跳转，更是反向可发现。关联产物拆成「本报告引用」（rk-links + data-rk-link）与「引用本报告」（rk-backlinks + data-rk-backlink）两组，关系可被脚本提取；谁新建关联谁补对侧反链，对侧未产出时标注（待创建）。
   • Callout 语义：> [!important] → rk-cal key、> [!warning] → rk-cal warn、> [!failure] → rk-cal risk、> [!success] → rk-cal ok。
6. 重点突出组件：rk-verdict（结论块，is-pass 绿 / is-fail 红，置顶显示最重要结论）、rk-kpis（指标卡，测试报告用于通过/失败/覆盖率）、rk-cal（四色 Callout）、rk-ref（src/x.ts:88 代码位置引用）。
7. 格式边界明确划分：lead/team-context.md 与 spec/context/experience|knowledge/*.md 保持 Markdown（账本这一条已于 v2.8.0 放开，见该版本条目）；tester/artifacts/test-logs/** 保持测试运行产出的原始格式。exp-reflect 读报告时按「终稿」语义取内容，不得把 <del> 里已删除的内容当作有效结论。
8. 移除 Obsidian 依赖：删除 obsidian-markdown、obsidian-bases、obsidian-plugin-dev、json-canvas 四个 Skill 与 .obsidian/ vault 配置及 .gitignore 条目；spec-init 不再注册 Obsidian Vault，改为交付 HTML 报告资产；清除全链路 [[wikilink]]、> [!note] Callout、#tag 语法。
9. 模板与文档同步：6 个模板重构为可直接打开的 HTML 骨架（plan-template / spec-execute 与 spec-update 两个 summary-template / update-template / debug-template 含诊断+修复双骨架 / review-template 含新功能+更新双骨架）；README.md、CODEMAP.md、AGENTS.md、CLAUDE.md、.agents/rules/ 同步 HTML 口径。

验证：6 个模板骨架与范例报告在真实 4 层目录深度（spec/<分类>/<spec目录>/<角色>/）以 file:// 实渲通过——样式表与脚本相对路径生效、rk:* meta 与双向链接全部解析、三视图切换实测（终稿视图 del 隐藏且 ins 去高亮）、无内嵌样式、无外部请求。

核心改进：

1. 提问前强制情境交代（Step 0）：intent-confirmation 把三步工作法升级为四步，任何提问前必须先输出「已做（Did）/ 发现（Found）/ 卡点（Blocked）/ 要你决策（Need）」四段极短情境，解决「Agent 直接抛问题、用户不知道在问什么」。配套模板、提问前三条自检、ask 结构化提问情境写在正文而非选项、反模式明确列出「裸问」。
2. 新增「决策记录」区块：lead/team-context.md 新增决策留痕区，记录每个实质取舍的候选项（含被否决项）、结论、理由和拍板者。与「门禁决策」分工：门禁只记通过/驳回，「为什么这么定」进「决策记录」。
3. 「问题闭环记录」扩展过程性问题：新增「分类」字段（bug / blocker / process / env / dependency / scope），从只记 bug 扩展到环境、依赖、阻塞、范围偏差等过程性问题。
4. 全链路落盘：7 个角色 Skill 各自更新共享区步骤——writer 记设计取舍、executor 记实现取舍、debugger 记修复路径、tester/explorer/reviewer 记过程性问题、ender 从「决策记录」汇总 end-report、updater 记更新范围判断。
5. 移除整套 Hook 机制：实践下来自动记账不好用——事实字段的自动同步价值有限，却带来运行时配置负担和「区块名被字符串匹配」的隐式耦合。删除 spec-init/references/team-context-hook-contract.md、runtime-hook-examples.md 和 spec-init 的 4.4 节，不再生成 .agents/hooks/、.claude/settings.json、.codex/hooks.json、.omp/hooks/；OMP session.compacting 自动重注入一并移除。账本回归全手动维护：产物落盘、问题闭环、取舍拍板后立即更新对应区块，跨上下文恢复靠角色主动重读落盘账本。维护边界（TeamLead 控制面 vs 角色共享区）不变。
6. 分发改为 git clone + 软链接：不再走 npm（@rnking3637/rk-flow 停止发布，package.json 标记 private）。改为 git clone 到 .agents/skills/，.claude/skills / .codex/skills / .omp/skills 软链接到同一份副本，git pull 一次三套运行时全部生效，避免多副本版本漂移；删除 bin/cli.js 与 rk-flow init。
7. team-context 模板全中文化：区块标题与表头改为中文（Task Progress → 「任务进度」、Problem Resolution Log → 「问题闭环记录」、Decision Log → 「决策记录」、Gate Decisions → 「门禁决策」、Loop Budget → 「修复循环预算」等），提升账本可读性。hook 移除后区块名不再被字符串匹配，中文化无耦合风险。frontmatter 字段名、角色 id 和状态枚举值（pending / done / open 等）保留英文，它们是跨 Skill 引用的标识符。
8. 文档同步：CODEMAP.md、README.md、spec-init/references/project-agent-roles.md 同步区块中文口径与「分类」字段，重写安装章节，清理约 50 处 hook 与 npm 引用。

核心改进：

1. 运行契约（Run Contract）：为 7 个核心工作流 Skill + 3 个记忆管理 Skill（exp-search/exp-reflect/exp-write）头部引入「运行契约」表，统一声明输入、权限、验证、停止、升级，把每个 Skill 当成有边界的循环单元。
2. Loop Budget 停止条件：spec-test ↔ spec-debug 修复循环在 lead/team-context.md 新增 Loop Budget 区，max_rounds / max_no_progress_rounds 由用户进入循环前确认，触发上限即停止并升级。
3. 新增 loop-design Skill：复用 intent-confirmation 澄清后，把重复任务设计成有边界的 Loop（运行契约 + 预算），只产出定义不驱动执行，可服务 R&K Flow 内 loop 或自定义 loop。
4. Lark Skill 套件：新增 lark-base / sheets / docs / im / mail / drive / calendar / task / wiki / okr / slides / whiteboard / vc / minutes / workflows 等飞书生态 Skill。
5. 辅助 Skill 扩充：新增 token-efficiency、agent-browser 等 Skill；38 个 Skill 标记 disable-model-invocation（仅显式调用）。
6. token-efficiency v0.3.1：从 v0.2.0 升级，新增 L2 大输出压缩（shrink.py + --vault 还原）、perf.py 前后对比基线、能力保障护栏（「省浪费不省智能」，避免效率规则阻断任务完成），扩展 Hermes / OpenClaw / Codex 适配。
7. 仓库治理：.gitignore 增加 *.gatebak、运行时产物（*.zip/*.sqlite*/*.log）、.system/ 和 R&K flow 运行时文件忽略规则；移除已废弃的 minimax-* / pptx-generator / ding-yuanying-perspective Skill；README 与 npm package 版本同步到 2.5.0。

核心改进：

1. AGENTS.md 入口化：明确 AGENTS.md 只承载项目身份、入口导入和目录路由，不再承载长篇规范。
2. 项目偏好下沉：长期项目偏好、产品体验、前端风格、测试/安全/文档约束统一维护在 .agents/rules/。
3. 初始化模板同步：spec-init 生成薄入口 AGENTS.md，并创建 project-preferences.md 与 documentation.md 等 rules 模板。
4. 规范维护分流收敛：spec-end / exp-reflect 将入口变化写入 AGENTS.md，详细规则和偏好写入 .agents/rules/。

核心改进：

1. 项目级角色定义：spec-init 统一创建 .agents/roles/ 中立角色定义，并生成 Claude Code / Codex 运行时适配。
2. 7 角色团队口径：新增 spec-reviewer，角色列表统一为探索、设计、测试、实现、调试、审查、收尾。
3. 角色目录化产物：每个 Spec 按 lead/、explorer/、writer/、tester/、executor/、debugger/、reviewer/、updater/、ender/ 保存产物。
4. Team Context 运行账本：lead/team-context.md 统一记录运行路径、Git/PR 元数据、runtime handles、产物注册、门禁、handoff、完成项和问题闭环。
5. 共享维护边界：TeamLead 维护控制面；各角色可共同维护「任务进度」和「问题闭环记录」中自己负责的行。
6. 中立 Hook 协议：定义事实事件由 Claude Code / Codex 在 spec-init 时按自身环境适配（该机制已于 v2.6.0 整套移除）。

核心改进：

1. 运行时抽象化：将创建团队、通知角色、请求确认等描述统一为抽象协作动作，避免把示例写成固定平台 API
2. 归档职责收敛：spec-execute 只负责实现和 summary.md，归档与 PR 收尾统一交给 spec-end
3. 确认策略收敛：intent-confirmation 改为风险触发式确认，而不是所有任务第一步强制确认
4. 路径口径统一：显式记忆统一指向 spec/context/experience/ 与 spec/context/knowledge/
5. 规范演进闭环：spec-end 在归档前审查薄入口 AGENTS.md / .agents/rules/ 是否需要维护，exp-reflect 支持项目规范/规则/偏好分流
6. GitHub Flow 贯穿 Spec 生命周期：spec-start 创建工作分支，spec-update 复用当前 Spec 分支，spec-end 收尾创建 PR，update 收尾提交推送并在整体交付时创建/更新 PR
7. 版本同步：README 与 npm package 版本同步到 2.3.0

核心改进：

1. 跨工具通用化：将所有 Claude Code 专属路径改为通用命名

   • CLAUDE.md → AGENTS.md（与 GitHub AGENTS.md 标准对齐）
   • .claude/rules/ → .agents/rules/
   • .claude/skills/ → .agents/skills/
   • bin/cli.js 安装目标同步更新

2. Skill 重命名：git-workflow-sop → git-work（更简洁的调用名）

3. exp-reflect 状态外置：从读取"对话历史"改为读取 Spec 文档（plan.md、summary.md、debug-*.md）作为反思素材，对齐 Harness 哲学中"状态外置、不依赖对话"原则

4. spec-start 角色描述增强：团队初始化说明中明确角色与 Skill 的映射关系

5. spec-end 信息传递优化：启动 exp-reflect 时传入当前 Spec 目录路径，避免 Agent 依赖记忆

核心改进：

1. spec-update 独立化：移除对 spec-write 的依赖，update-xxx.md 的创建由 spec-update 自身负责
2. spec-update 单 Agent 化：移除路径 B（Agent Teams），更新流程统一为单 Agent；若更新规模需要多角色协作，应新建 Spec 走 spec-start 流程
3. update-template.md 精简：去掉 execution_mode 字段

核心改进：

1. Agent Teams 多角色协作架构：

   • 引入 TeamLead + 6 专职角色的协作模型
   • 当前 Agent 即 TeamLead，统一协调全局
   • 明确区分角色（Who）与 Skill（How）

2. 5 阶段开发流程：

   • 阶段一：需求对齐（TeamLead + intent-confirmation）
   • 阶段二：Spec 创建（spec-explorer → spec-writer ↔ spec-tester 协作）
   • 阶段三：实现（spec-executor）
   • 阶段四：测试（spec-tester ↔ spec-debugger 闭环）
   • 阶段五：收尾（spec-ender：多角色讨论 + 经验沉淀 + 归档）

3. Skill 重命名（角色 vs Skill 分离）：

   • spec-writer → spec-write（Skill）
   • spec-executor → spec-execute（Skill）
   • spec-debugger → spec-debug（Skill）
   • spec-reviewer → spec-review（Skill）
   • spec-updater → spec-update（Skill）

4. 新增 Skill：

   • spec-init：完整项目骨架搭建（AGENTS.md + .agents/rules/ + .agents/skills/ + spec/ + 报告资产）
   • spec-start：启动 Agent Teams，创建 6 个专职角色（与 spec-end 对应）
   • spec-explore：Spec 前置信息收集（经验检索 + 代码探索 + 外部资源）
   • spec-test：测试计划撰写（test-plan.md）+ 测试执行（test-report.md）
   • spec-end：收尾工作（多角色讨论 + 经验沉淀 + 归档 + git 提交）
   • find-skills：搜索和安装开源 Skill（npx skills）

5. 职责拆分：

   • plan.md 不再包含测试计划章节（由 spec-tester 单独创建 test-plan.md）
   • spec-execute 移除路径 B（agent-teams）和测试步骤
   • spec-debug 修复后必须通知 spec-tester 重新验证，不自行判断

6. 新增文档类型：

   • exploration-report.md：探索报告（spec-explore 产出）
   • test-plan.md：测试计划（spec-test 阶段一产出）
   • test-report.md：测试报告（spec-test 阶段二产出）

核心改进：

1. 扩展记忆类型，支持知识记忆：

   • 原有经验记忆（困境-策略对）→ spec/context/experience/
   • 新增知识记忆（项目理解/技术调研）→ spec/context/knowledge/
   • 统一入口，自动分类：用户只需调用 /exp-reflect，Skill 自动识别类型

2. exp-reflect 增强：

   • 支持用户提示词参数（如 /exp-reflect 记录数据流）
   • 自动识别记忆类型：困境-策略对 vs 项目理解/技术调研
   • 根据类型调用 exp-write type=experience 或 type=knowledge
   • 新增知识记忆草稿格式模板

3. exp-search 扩展搜索范围：

   • 从 4 层扩展到 5 层记忆检索
   • 新增知识记忆搜索（spec/context/knowledge/）
   • 同时搜索 experience/index.md 和 knowledge/index.md
   • 搜索结果按类型分组展示（经验记忆、知识记忆、程序记忆、工具记忆、Auto Memory）

4. exp-write 支持知识记忆写入：

   • 支持 type=experience 和 type=knowledge 参数
   • 根据类型选择文件名前缀（exp- 或 know-）
   • 根据类型选择 ID 格式（EXP-xxx 或 KNOW-xxx）
   • 提供知识记忆文档模板（项目理解/技术调研/代码分析）
   • 支持写入和更新 spec/context/knowledge/ 目录

文件命名规范：

• 经验记忆：exp-001-中文标题.md → spec/context/experience/
• 知识记忆：know-001-中文标题.md → spec/context/knowledge/

使用场景：

• 探索项目数据流、架构后，使用 /exp-reflect 记录数据流 自动识别为知识记忆
• 技术选型、框架对比后，使用 /exp-reflect 记录技术调研 自动识别为知识记忆
• 解决困难问题后，使用 /exp-reflect 自动识别为经验记忆

核心改进：

1. 废弃 MCP 确认插件，改用 Claude Code 原生特性：

   • MCP 确认插件（后已移除）目前存在 Bug，暂时废弃
   • 所有 Spec 确认流程改用运行环境提供的原生确认能力
   • 后续 MCP 插件完善后再投入使用

2. 更新所有 Skill 的确认机制：

   • spec-writer：plan.md 确认改用原生确认能力
   • spec-executor：summary.md 确认改用原生确认能力
   • spec-updater：update-xxx.md 和 review.md 确认改用原生确认能力
   • spec-reviewer：review.md 确认改用原生确认能力
   • spec-debugger：debug-xxx.md 和 debug-xxx-fix.md 确认改用原生确认能力

3. 用户确认节点：

   • 方案确认：spec-writer 创建 plan.md 后
   • 实现确认：spec-executor 创建 summary.md 后
   • 更新方案确认：spec-writer 创建 update-xxx.md 后
   • 审查确认：spec-reviewer 创建 review.md 后
   • 诊断确认：spec-debugger 创建 debug-xxx.md 后
   • 修复确认：spec-debugger 创建 debug-xxx-fix.md 后

文档更新：

• README.md：删除 MCP 插件章节，新增"用户确认机制"章节
• MCP 确认插件 README：添加废弃警告

核心改进：

1. 双层互补记忆架构：

   • 新增 Auto Memory（自动层）：Claude Code 原生跨会话记忆，自主管理，零摩擦
   • exp-* 系统定位为显式层：仅处理重大困境-策略对，需要结构化文件关联
   • 明确职责边界：exp-* 不写 MEMORY.md，exp-search 可读 MEMORY.md（只读）

2. exp-reflect 经验权重分流：

   • 新增经验权重判断步骤（复杂度/关联性/共享性/持久性）
   • 重大经验 → exp-write 结构化记录
   • 轻量经验 → 引导 Auto Memory 自动处理
   • spec-executor 的强制 exp-reflect 改为建议性

3. exp-write 职责边界明确：

   • 明确只写 spec/context/experience/ 目录
   • 不写 MEMORY.md（由 Claude Code 自主管理）

4. exp-search 搜索范围扩展：

   • 新增 Auto Memory 只读搜索（MEMORY.md + memory/*.md）
   • 无匹配结果时引导检查 Auto Memory

5. spec-writer 新增 Agent Teams 评估：

   • 规划阶段评估任务是否适合 Agent Teams（可分解性/独立性/复杂度/测试独立性）
   • plan.md 新增「执行模式」章节和 execution_mode frontmatter 字段
   • 设计任务拆分方案（队友名称/职责/依赖关系）

6. spec-executor 双轨工作流：

   • 路径 A（单 Agent）：保持现有流程不变
   • 路径 B（Agent Teams）：创建团队 → 创建任务 → 生成队友 → 监控 → 汇总 → 关闭团队
   • 根据 plan.md 的 execution_mode 自动选择路径

7. spec-updater 双轨工作流：

   • 同 spec-executor 的双轨改造
   • 路径 B 增加回归测试和 spec-reviewer 审查

8. skill-creator 增强：

   • 创建 Skill 时评估是否需要 .agents/rules/ 摘要文件
   • 规范摘要不超过 20 行，引用 Skill 获取详情

9. Skill 模块化重构（遵循 skill-creator 渐进式披露原则）：

   • spec-writer：592 → 116 行（-80%），提取 references/plan-template.md + references/templates.md
   • spec-executor：1224 → 238 行（-80%），提取 references/ 模板
   • spec-updater：1257 → 104 行（-92%），提取 references/ 模板
   • spec-reviewer：690 → 94 行（-86%），提取 references/review-template.md
   • 删除所有 Skill 中的 README.md、EXAMPLES.md 等辅助文件
   • Frontmatter 统一只保留 name + description（移除 allowed-tools、model）

信息分层架构：

AGENTS.md          → 项目身份 + 入口清单 + 路由（薄入口）
.agents/rules/     → 长期规则 + 项目偏好 + 前端风格（每文件 ≤ 20 行）
MEMORY.md          → Auto Memory 跨会话记忆（Claude 自主管理）
spec/context/      → 项目级结构化经验与知识（显式层）
skills/            → 工作流程定义（按需加载）

核心改进：

1. spec-executor 归档前自动触发经验反思：

   • 用户确认 summary.md 后，必须调用 /exp-reflect 进行经验反思
   • 解决了「归档只是移动文件，不是学习」的问题
   • 将执行过程中的知识转化为可复用经验

2. summary.md 通过相对链接引用沉淀的经验：

   • 文档关联章节新增「沉淀经验」字段
   • 使用相对路径链接 spec/context/experience/exp-xxx-标题.md 引用
   • 实现 Spec 文档与经验记忆的关联

3. 经验记忆目录迁移到 spec/ 下：

   • 路径从 context/experience/ 改为 spec/context/experience/
   • 记忆系统与 Spec 工作流保持一致的目录结构
   • 更新了 exp-search、exp-reflect、exp-write 的路径引用

4. 执行前检索历史经验，形成完整闭环：

   • spec-executor、spec-updater、spec-debugger 新增检索历史经验步骤
   • 开发/更新/调试前调用 /exp-search 检索相关经验，避免重复踩坑
   • 形成闭环：开发前检索（exp-search）→ 开发后反思（exp-reflect）

更新的流程：

读取并理解 plan.md
    ↓
检索历史经验（exp-search）  ← 新增
    ↓
创建任务清单并实现
    ↓
用户确认 summary.md
    ↓
调用 exp-reflect 进行经验反思
    ↓
如有经验沉淀，更新 summary.md 添加经验引用
    ↓
移动到 spec/06-已归档

重大变更：

1. 废弃 memory Skill，拆分为三个独立 Skill：

   • exp-search - 经验检索，支持三层记忆检索
   • exp-reflect - 经验反思，分析对话提取可沉淀的经验
   • exp-write - 经验写入，将经验写入文件并更新索引

2. 新增 context/experience/ 目录：

   • 经验记忆从 AGENTS.md 迁移到独立文件
   • 索引全量加载，详情按需检索，避免上下文膨胀
   • 文件使用中文命名：exp-xxx-标题.md

3. 明确经验记忆与 SOP 的边界：

   • 经验记忆：知识点、决策依据、踩坑经验（核心是"为什么"）
   • 程序记忆（SOP）：可重复执行的操作流程（核心是"怎么做"）

4. SOP 判断标准：

   • 有明确的触发动作（如"部署"、"发布"）
   • 有可机械执行的步骤序列
   • 核心是"怎么做"而非"为什么"

5. 新增 spec-debugger Skill：

   • 诊断并修复 Spec 执行过程中发现的问题
   • 不修改已确认的 plan.md，创建独立的 debug 文档
   • 保持设计的可追溯性

6. 新增 agent-browser Skill：

   • 基于 agent-browser CLI 的无头浏览器自动化
   • 支持网页交互、表单填写、截图等操作

7. 优化 spec-executor 流程：

   • 简化确认流程：summary.md 确认后直接归档
   • spec-reviewer 改为可选步骤，用户需要时单独调用

参考：

• 认知重建：Speckit 用了三个月，我放弃了

• 初始版本
• Spec 驱动式开发工作流
• 三层记忆架构（memory Skill）