# Changelog

All notable changes to the AgentForge AI team template are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [v3.1.1] — 2026-05-15 — README 总-分-总 重构 + 日文版 + Claude Code v2.1.130

### Why

v3.1.0 release 后用户对 README 提了三类反馈："格式有点乱 / 逻辑不清晰 / 缺日文受众"。本 PATCH 一次性收口：

1. **结构重构（总-分-总 + 组织/流程/机制）**：v3.1.0 的 README 用 7 个章节平铺呈现，读者要靠 emoji 自悟主题划分。本次按"开篇结论先行 → 3 大支柱（组织/流程/机制）+ 入门/工具 → 收尾对比/总结"重组，并在顶部加阅读路径导航（3 行视觉化）。
2. **日文受众覆盖**：新增 `README.ja.md`，与中英文版完全同构（412 行、10 章节、同 anchors）。三语切换器同步更新。
3. **Claude Code 最低版本升 v2.1.32 → v2.1.130**：跨 5 个文件同步（README × 3 + init-team.sh + agf-team-start.sh + docs/FIRST_RUN.md）。属于推荐版本调整 — `init-team.sh` 检查为 warn 不 block，旧版用户仍可用 subagent 路径。
4. **微调**："Java / Go / Rust 主线" 从"不适合"挪到 📝 callout（不是不适合，仅需 `tech-lead` 重写 ADR-000）；TDD enforcement 链路从 ASCII 改为 mermaid（LR 横向 + 失败回路虚线，匹配 🧭 端到端全景图样式）。

### Changed

- **README.md / README.en.md**：重写为总-分-总 + 组织/流程/机制结构（412 行 × 2，同构）
  - 顶部加 3 行视觉化阅读路径导航
  - 💡 开篇 5 事实 bullet 每条带 anchor 跳转到详情章节
  - ⚙️ 机制章节集中：TDD enforcement mermaid + 4 Hook 防御表 + 阶段 × Hook × Skill 触发点（合并视图）+ Release 纪律 + 术语速查
  - ✨ 总结章新增 🚀 下一步 CTA 表，把 `examples/login-feature/` 推到收尾（之前被埋没）
  - "Java / Go / Rust 主线" 从"不适合"移到 📝 callout
- **init-team.sh** / **agf-team-start.sh** / **docs/FIRST_RUN.md**：Claude Code 最低版本 v2.1.32 → v2.1.130

### Added

- **README.ja.md**：日本語版（412 行、10 章节与中英版同构、所有 anchors 与链接全绿）
- 三语切换器（顶部 lang switcher + 底部 CTA）同步加 🇯🇵 日本語入口

### Migration steps

无 BREAKING，无需 migration。

注意：Claude Code 最低版本调整仅 `warn` 不 `block`，v2.1.32-v2.1.129 用户仍可用 subagent 路径（Agent Team 实验功能在 v2.1.130+ 有更稳定的 sub-agent skill discovery / `--bg` headless 支持）。

### Verification

- `bash .claude/hooks/test-block-dangerous-bash.sh` → 73 PASS / 0 FAIL
- `bash .claude/hooks/test-scan-secrets.sh` → 35 PASS / 0 FAIL
- `bash .claude/hooks/test-validate-task-schema.sh` → 7/7 PASS
- `./init-team.sh` → 全绿（含 Claude Code v2.1.142 ≥ v2.1.130 ✅）
- 三语 README 各 412 行 / 10 章节 / 44+45+45 处本地链接全绿（含跨语言 anchors）

### Tag-along commits

> 按 versioning.md AI-2 规则核对 `v3.1.0..v3.1.1` 范围内 commit：

- `f7dfa4f` docs(readme): restructure with 总-分-总 + 组织/流程/机制 + add ja translation + bump Claude Code min to v2.1.130（本 release 唯一 commit）

**无 tagged-along 漂移**：单 commit 直接对应本 release 主线。

---

## [v3.1.0] — 2026-05-15 — Agile/Scrum/TDD enforcement traceability + README rewrite

### Why

v3.0.0 后做了一轮"逐文件 Agile + Scrum + TDD 一致性审查"，把心法在团队模板中的 enforcement 路径（skill / hook / DoD 三层）做到可追溯。三个层次：

1. **审查 traceability gap 并修复**：uiux-designer 设计 spec 与 PRD AC 没双向引用 / miniapp testing matrix 中 SIT 责任归属表头模糊 / 5 个执行层 agent Output Conventions 中 Unit 测试 must 列措辞弱化了 TDD red-green commit 顺序
2. **新增结构性载体**：team-capability-map.md §1.6 一表说清 "Scrum 词汇 ↔ 本项目载体（feature 流变体）" 13 行映射；agf-running-release-retro skill 加 §4.1 feature cycle time trend 评估步骤（≥3 retros 后强制执行，作为 Velocity 的隐式形式）
3. **README 重写**：把 Agile + Scrum + TDD 从一行 bullet 升格为第二大节，并把 `docs/product-workflow.md` + `docs/team-capability-map.md` 的关键内容（阶段图 / Hook×Skill 触发点 / 失败回路 / 协作动作词典 / 状态指示符）折进 README，让单文件就能讲清"心法 → enforcement 路径"

### Added

- `docs/team-capability-map.md` §1.6 **Scrum 词汇 ↔ 本项目载体（feature 流变体）** — 13 行映射表覆盖 Sprint / Backlog / Sprint Backlog / Increment / PO / SM / Dev Team / Daily Standup / Sprint Planning / Sprint Review / Sprint Retrospective / DoD / DoR / AC / Refinement / Story Points & Velocity
- `.claude/skills/agf-running-release-retro/SKILL.md` §4.1 **Feature cycle time trend** — ≥3 retros 后强制评估，作为 Velocity 的隐式形式；<3 retros 写"数据点不足"
- `.claude/agents/uiux-designer.md` spec.md 结构加 `## AC 覆盖` 节 — PRD §4 AC ID 与 design spec 双向引用
- `README.md` 重写：新增 🧠 核心思想（Agile + Scrum + TDD）大节 + 📊 端到端全景节（mermaid + Hook×Skill 合并视图 + 失败回路）+ 📖 术语速查节（协作动作 9 条 + 状态指示符 7 emoji）+ 🤝 一个 feature = 一个 Sprint 8 行表（含 PRD → Task 拆分 3 铁律）

### Changed

- `.claude/agents/uiux-designer.md` Output Conventions 表 must 列：spec.md 行加 "**AC 覆盖表（逐条引用 PRD §4 AC ID + 承载方式或 N/A 理由）**" 必填要求
- `.claude/standards/miniapp.md` §6 testing matrix：加"责任角色"列，SIT 行明标 `miniapp-dev 自跑（v2.0.0+）`，证据进 `progress/miniapp-dev.md`
- 5 个执行层 dev agent（`frontend-dev` / `backend-dev` / `ai-agent-dev` / `ml-engineer` / `miniapp-dev`）Output Conventions 表 Unit 测试 must 列统一为 "**test 先行 commit（red 阶段，参见 `ac-lifecycle.md` DoD red→green→refactor）+ 与功能代码同 PR**"
- `.claude/agents/product-lead.md` 派单示例同步更新 TDD commit 顺序措辞
- `docs/reviews/retro-_TEMPLATE.md` 顶部加 Scrum Retrospective **三柱映射注释**（What worked / didn't / improve → §1+§2+§4 / §1+§2+§3+§4 / §5）
- `README.md` 减重：删 14 同事重复 mermaid（已有表）/ 合并 hook×skill 表从 18 → 9 行 / 砍开篇说理段；最终 339 行，22 处 Agile/Scrum/TDD 提及

### Migration steps (for users on v3.0.0)

本 release 无 BREAKING 变更；fork 用户建议同步：

1. **fork uiux-designer.md 的项目**：对齐补充 `## AC 覆盖` 节到 spec.md 结构；下次设计交付的 spec.md 应含 AC 覆盖表（引用 PRD AC ID + 承载方式或 `N/A — backend only` 理由）
2. **fork 任一执行层 dev agent 的项目**：对齐更新 Output Conventions 表中 Unit 测试 must 列的 TDD wording（先红 commit 再绿 commit）
3. **跑过 ≥3 次 retro 的项目**：下次 retro 起按 `agf-running-release-retro` §4.1 评估 feature cycle time 趋势，写入 §1 末或 §4 流程协作段
4. **fork retro 模板的项目**：可对齐补充 Scrum 三柱映射注释（注释式，不改 §0-§6 结构）

### Verification

- `bash .claude/hooks/test-block-dangerous-bash.sh` → 73 PASS / 0 FAIL
- `bash .claude/hooks/test-scan-secrets.sh` → 35 PASS / 0 FAIL
- `bash .claude/hooks/test-validate-task-schema.sh` → 7/7 PASS
- `python3 -c "import json; json.load(open('.claude/settings.json'))"` → JSON valid
- `python3 -c "import json; json.load(open('.claude/hooks/skill-rules.json'))"` → JSON valid
- `./init-team.sh` → 10 通过 / 2 警告（ADR-000 模板 + permissions 人工核对，与本 release 无关）
- `grep -n "^### 4\.4 \|^### 1\.5 \|^### 1\.6 " docs/product-workflow.md docs/team-capability-map.md` → 3 锚点全部存在
- `README.md` 44 处本地链接全部有效

### Tag-along commits

> 按 versioning.md AI-2 规则核对 `v3.0.0..v3.1.0` 范围内 commit：

主线 commit（Agile/Scrum/TDD enforcement traceability）：
- `e5348de` 6th-pass audit：P1 + P2 + P3 traceability 三层修（11 文件，含 §1.6 / §4.1 / AC 覆盖 / TDD wording / responsibility column / retro 三柱注释）
- `8f5569a` 显式化 Agile Scrum + TDD（无行为变更）
- `3786e67` README 重写（本 release 主体）

模板内部清理（非 traceability 主线，但围绕同一审查 pass）：
- `334caed` v3.0.0 release retrospective（post-tag，属 v3.0.0 复盘归档）
- `05b6aac` docs cleanup（公共模板卫生）
- `0c6c9af` v2.0.0/v3.0.0 SSOT drift 修复
- `f12f96d` 4th-pass markdown links 修复
- `e84b504` 5th-pass 21 SSOT/workflow drift 修复
- `d7384e4` login-feature PRD 按当前标准重写（去 Epic / 用 P0/P1）
- `7c7d71d` product-workflow.md Retrospective 定义修复
- `df1615c` team-capability-map.md 2 处 stale entries 修复

**无 tagged-along 漂移**：以上 11 个 commit 全部围绕"Agile/Scrum/TDD enforcement traceability + 模板内部 docs 清理"主线。

---

## [v3.0.0] — 2026-05-15 — Remove cost audit feature (BREAKING)

> **数字撞号说明**：CHANGELOG SemVer 跨入 **v3.0.0**；CLAUDE.md 顶部 internal Template Version 也是 **v3.0.0**（v1.4.0 设定，agent prefix rollback 起算）— 两者数字相同纯属巧合，语义维度不同：SemVer 追溯所有 BREAKING；Template Version 只追溯 namespace migration 事件。本 release 不涉 namespace migration，Template Version 保持 v3.0.0 不变。

### Why

`/agf-usage` + `docs/reviews/cost-[YYYY-MM].md` 这套会话级成本审计在 v1.6.0 引入，初衷是用 `/usage` 包装 + 月度趋势对账让 PL 主动管 token 预算。运行近一个月（v1.6.0 → v3.0.0）的实际数据：

- v1.7.0 / v2.0.0 两个 release 周期 `/agf-usage` 全部漏跑，cost-2026-05.md 直到 v2.0.0 retro AI-6 才被回填一行，月度趋势 = 一行无趋势可言
- 真要看用量，Claude Code 内置 `/usage` 已含本会话 token / cost / cache hit / 周限额可视化，比 markdown 表格强；wrapper 唯一新增价值是"持久化历史" — 但每月一行的密度 + 用户从不回头看的事实表明这价值不存在
- CLAUDE.md "每次会话结束前必须跑 `/agf-usage`" 的强制点反而成为 retro AI 的常驻"漂移项"（v1.5.0 retro 已显式记录"流程钉死了但没人查"）

按 "三月内连续两次空转的纪律 = 误纪律，应删除" 原则，整套移除。token 预算管理保留在 `cost-budget.md`（会话规模上限 / cache 利用率 / 14 agent 默认 model 路由），用户仍可手动跑内置 `/usage` 查当下用量。

### Changed (BREAKING)

#### Commands

| v2.x | v3.0.0 |
|---|---|
| `/agf-usage` | **删除**（仍可用 Claude Code 内置 `/usage` 查会话用量） |

5 commands → 4：`/agf-team-start`、`/agf-uat`、`/agf-tasks`、`/agf-release-retro`（原 5，去 `/agf-usage`）。

#### Standards / hooks

- `.claude/standards/cost-budget.md`：删 "## 检查点 / ### 每次会话结束前（必须）" 段；删 "## 月度账单核账" 段；agent model 路由表脚注 "在月度成本审计中复核效果" 改 "在 PRD 顶部备注复核效果"
- `.claude/hooks/skill-rules.json`：删 `id: cost` 整条规则（原 trigger 是 token / `/usage` / 预算 / cost.*audit prompt 关键词或 `docs/reviews/cost-.*\.md` path 命中时建议跑 `/agf-usage`）

#### Docs

- `CLAUDE.md` Project-Specific Rules："每次会话结束前必须跑 `/agf-usage`" → 改为指向内置 `/usage`
- `.claude/rules/repo-layout.md`：commands 列表去 `agf-usage`；docs/reviews 描述去"月度成本累积"
- `docs/FIRST_RUN.md` 命令行示例：去 `/agf-usage`
- `README.md` / `README.en.md` Slash Commands 表：6 → 4（去 `/agf-usage`，注：`/agf-sit` 已在 v2.0.0 删除但 README 漏更新，本节同步移除）

#### Generated artifacts

- `docs/reviews/cost-2026-05.md`：删（v2.0.0 retro AI-6 在 commit `0806092` 创建，刚回填一行，本 release 直接清掉）

### Reverse impact on v2.0.0 retro

`docs/reviews/retro-v2.0.0-2026-05-15.md` §5 不回写（按"已签字归档不动"原则）；下一份 retro（若有）的 §0 应显式列：

| 项 | 状态 | 备注 |
|---|---|---|
| AI-4: 把 `/agf-usage` 强制点延伸到 release prep | dropped | per v3.0.0 — feature removed |
| AI-6: 跑 `/agf-usage` 创建 cost-2026-05.md | dropped | per v3.0.0 — file removed |

### Migration steps (for users on v2.x)

1. **进行中的 v2 feature 不受影响**——本次只删 cost audit，feature 工作流（H3 SIT 责任分工）完全不动
2. **Pull v3.0.0 后**：
   - 任何 macro / alias 引用 `/agf-usage` 删除
   - 如果你 fork 了 cost-budget.md 自定义版本，对齐删 "每次会话结束前必须跑 `/agf-usage`" 段；保留会话规模上限 / Cache 利用率 / 14 agent model 路由
   - 如果有 `docs/reviews/cost-YYYY-MM.md` 文件，自行决定保留作历史归档或删除（v3.0.0 不再生成新文件）
3. **查会话用量**：直接在 Claude Code 输入框跑 **`/usage`**（内置命令），含 token / cost / cache hit / 周限额可视化，比原 wrapper 信息更全
4. **token 预算管理**仍按 `cost-budget.md`（会话规模上限 + cache 利用率 ≥ 60% + 14 agent model 路由）

### Verification

- `bash .claude/hooks/test-block-dangerous-bash.sh` → 73 PASS / 0 FAIL
- `bash .claude/hooks/test-scan-secrets.sh` → 35 PASS / 0 FAIL
- `bash .claude/hooks/test-validate-task-schema.sh` → 7/7 PASS
- `python3 -c "import json; json.load(open('.claude/hooks/skill-rules.json'))"` → JSON valid
- `./init-team.sh` → 全绿（仅原有 ADR-000 模板 + permissions 警告，与本次无关）
- `grep -rwn "agf-usage" .claude/ docs/ CLAUDE.md README.md README.en.md` → 仅 CHANGELOG（本节 + v2.0.0 历史段）+ 3 历史 retro + 1 历史 archive — 全部合规

### Tag-along commits

> 按 versioning.md AI-2 规则核对 `v2.0.0..v3.0.0` 范围内 commit：含 `deff1ae` (v2.0.0 retro) + `0806092` (cost log，本 release 一并删) + 本 release 实施 commit。retro 与 cost log 严格说不属于"删除 cost audit"主线，但它们是 v2.0.0 retro 触发本决策的直接证据链 — 列出而非划归漂移。

---

## [v2.0.0] — 2026-05-15 — H3 late-stage workflow refactor (BREAKING)

> **Note**: CHANGELOG SemVer 跨入 **v2.0.0**（首个 MAJOR）— 后期阶段从 4 阶（dev → SIT(qa) → review → E2E/UAT(qa)）压成 3 阶（dev+SIT(self) → review+SIT-audit → E2E/UAT(qa)）。SIT 责任从 `qa-engineer` 下沉到执行层 dev，证据落 `progress/<role>.md`，由 `code-reviewer` 在 code review 时 audit。CLAUDE.md 顶部的 internal Template Version 维持 **v3.0.0**（仅追溯 namespace migration 事件）— 本次是 workflow architecture 变更，不动 Template Version。

### Why

v1.x 把 SIT 作为独立派单阶段交给 `qa-engineer`，在真实 feature run 中暴露两个结构性损耗：(1) **环境复刻成本**——qa 在另一个 worktree / 上下文里重建 dev 已经搭好的本地环境（DB schema、env vars、外部 API mock），SIT 准备时间常常超过执行时间；(2) **知识割裂**——qa 重新走一遍 PRD / API / DB 心智模型 + AC walk + evidence 采集，本质是"复述 dev 已有的事实"。dev 写完代码顺手跑 SIT 的边际成本接近零，但 v1 流程强行让 qa 走一遍，是制度化的双工。

把 SIT 责任迁回 dev 后，`code-reviewer` 在 code review 时多承担一项独立第三方 audit（不重跑 SIT，只查证据本身：progress 完整性 / AC 覆盖 / 证据可信度 / 否定结果完整性），qa 专注 E2E + UAT。后期阶段 4→3 减一次派单，预计单 feature 节省 10–20% wall-clock。完整决策依据见 commit `7f75177` (spec) + `c60581b` (plan)（原路径 `docs/superpowers/{specs,plans}/2026-05-14-h3-late-stage-workflow-refactor*.md`，v3.0.0 docs cleanup 时移除自 working tree，仍可通过 `git show 7f75177:<path>` 查阅）。

### Changed (BREAKING)

#### Role contracts (10 agents)

| Agent | v1.x 职责 | v2.0.0 职责 |
|---|---|---|
| `qa-engineer` | SIT / E2E / UAT | **E2E + UAT only**（删 SIT） |
| `miniapp-qa-engineer` | SIT / E2E / UAT | **E2E + UAT only**（删 SIT） |
| `code-reviewer` | 代码 review | 代码 review **+ SIT Audit**（4 项检查 + 3 档 verdict）|
| `miniapp-code-reviewer` | 代码 review | 代码 review **+ SIT Audit**（与 code-reviewer 平行）|
| `backend-dev` / `frontend-dev` / `ai-agent-dev` / `ml-engineer` / `miniapp-dev` | 实现 + Unit | 实现 + Unit **+ SIT (API+DB+external) 自跑** |
| `product-lead` | 派单序列 4 阶 | 派单序列 3 阶；失败回退把 SIT redo 并入 code-review 段 |

#### Skills

| v1.x | v2.0.0 |
|---|---|
| `.claude/skills/agf-writing-sit-report/` | **重命名** → `.claude/skills/agf-writing-qa-report/`；Stage 集合 `{sit, e2e, uat}` → `{e2e, uat}`；SIT 例子改 E2E / UAT；description 明确"SIT 不在覆盖范围" |
| `.claude/skills/agf-running-sit-tests/` | 受众改 dev；触发条件改"Unit 完成后、code-review 前"；Report template 段删，改指向 `ac-lifecycle.md` 的新 progress `**SIT 证据**` 段格式；hand-off 改 `product-lead` |

#### Commands

| v1.x | v2.0.0 |
|---|---|
| `/agf-sit` | **删除**（SIT 不再是独立派单阶段；`product-lead` 不再派 SIT 任务）|

6 commands → 5：`/agf-team-start`、`/agf-usage`、`/agf-uat`、`/agf-tasks`、`/agf-release-retro`（去 `/agf-sit`）。

#### Standards / docs

- `.claude/standards/testing.md`：SIT 编写者 qa → dev；阶段门槛改 "code-review (含 SIT audit) → E2E → UAT"
- `.claude/standards/ac-lifecycle.md`：DoD 加 SIT；progress 完整条目格式新增 `**SIT 证据**` 段；SendMessage 完成模板加 SIT 行
- `.claude/standards/workflow.md`：工作流 ASCII 图删独立 SIT 节点；阶段门槛行重写
- `.claude/standards/team-roles.md`：qa Focus 列删 SIT；`agf-running-sit-tests` 预加载从 qa 移到 5 个 dev；`agf-writing-qa-report` 留 qa
- `CLAUDE.md` Project-Specific Rules：SIT 段重写（指向 dev-owned skill + reviewer audit 段）；skill 引用更新（含 rename）
- `docs/team-capability-map.md` / `docs/product-workflow.md`：Mermaid + 主要输出列同步
- `docs/qa/_TEMPLATE.md`：Stage 集合改 `{e2e, uat}`；canonical verdict casing 统一

### Migration steps (for users on v1.x)

1. **进行中的 v1 feature 可在原契约下完成**——本次重构不强制中途切换。已派 `qa-engineer` 做 SIT 的任务跑完即止，下一个 feature 用 v2 流程启动。
2. **Pull v2.0.0 后**：
   - 老 skill 名 `agf-writing-sit-report` 已不存在 — 任何外部 prompt / 文档引用改成 `agf-writing-qa-report`
   - 老命令 `/agf-sit` 已不存在 — 任何 macro / alias 删除
   - 如果你 fork 了 `qa-engineer` / `miniapp-qa-engineer` 自定义版本，对齐删 SIT 段；如果 fork 了 `code-reviewer` / `miniapp-code-reviewer`，对齐加 `## SIT Audit` 节（4 项检查 + 3 档 verdict 见 `.claude/agents/code-reviewer.md`）
3. **Dev 角色行为变化**：`backend-dev` / `frontend-dev` / `ai-agent-dev` / `ml-engineer` / `miniapp-dev` 的 DoD 现含 "SIT (API+DB+external)"；写完代码不能直接 SendMessage 报 done，必须先按 skill `agf-running-sit-tests` 自跑并 append `**SIT 证据**` 到 `progress/<role>.md`，否则 `code-reviewer` SIT Audit 会判 `❌ Redo SIT` 打回。
4. **Settings / hooks / permissions 不变**——`.claude/settings.json` / `.claude/hooks/check-progress-file.sh` / git pre-commit 全部沿用 v1.7.0 配置。

### Verification

- `bash .claude/hooks/test-block-dangerous-bash.sh` → 73 PASS / 0 FAIL
- `bash .claude/hooks/test-scan-secrets.sh` → 35 PASS / 0 FAIL
- `bash .claude/hooks/test-validate-task-schema.sh` → 7/7 PASS
- `./init-team.sh` → 10 通过 / 2 警告（ADR-000 模板 + permissions 人工核对，与本次重构无关）
- `grep -rwn "agf-sit" .claude/ docs/ CLAUDE.md` → 仅 specs/plans/CHANGELOG（设计稿 + 本节）
- `grep -rn "agf-writing-sit-report" .claude/ docs/ CLAUDE.md` → 仅 specs/plans/retro/CHANGELOG（历史归档 + 本节 rename 表）

### Tag-along commits

> 按 versioning.md AI-2 规则核对 `v1.7.0..v2.0.0` 范围内 commit：8 个非 CHANGELOG-本身 commit（`7f75177` spec、`c60581b` plan、`14a0bc7` Phase 1、`fedec46` Task 1 quality fix、`f7b7a9a` Phase 2、`49fe622` Task 2 quality fix、`153540c` Phase 3、`1db3bad` Task 3 quality fix、`187d953` Phase 4、`5b90abb` Task 4 quality fix）均落在 H3 重构主线（spec → plan → Phase 1–4 + 各自 quality review fix）。**无 tagged-along 漂移 commit**——本 MAJOR 是该规则的第三次干净执行实例。

---

## [v1.5.0 → v1.7.0] — 2026-05-09 ~ 2026-05-13 — Earlier MINOR/PATCH releases (folded)

> v3.0.0 docs cleanup pass：早期 MINOR/PATCH 节已折叠为下方一段摘要。完整原文见 `git log v1.4.0..v2.0.0` + 各 tag annotation。

- **v1.5.0** (2026-05-09) — Release 复盘流程：引入 skill `agf-running-release-retro` + slash `/agf-release-retro` + template `docs/reviews/retro-_TEMPLATE.md`；versioning.md 加 Step 7（MAJOR/MINOR 触发）+ 2 条反模式（缺 retro 文件 / 缺 owner-due）
- **v1.6.0** (2026-05-13) — Team dashboard：单任务本地 web 看板（`tools/team-dashboard/`，FastAPI + watchfiles + SSE + React/Vite，零侵入）；versioning.md 加 `❌ tag-orphan` 反模式 + Step 4 强制 tag annotation 列 out-of-scope commits
- **v1.6.1** (2026-05-13) — `install-to-existing.sh` 一键搬到已有 git 仓库；README 全面刷新到 v1.6.0
- **v1.7.0** (2026-05-13) — 两个 code-reviewer 角色加 `/simplify` skill；`docs/qa/`、`docs/reviews/` 一次性产物清理

---

## [v1.4.0] — 2026-05-03 — Agent prefix rollback (BREAKING)

> **Note**: internal Template Version moves to **v3.0.0** (CLAUDE.md), CHANGELOG semver stays pragmatic at v1.4.0. This is the **second namespace migration** — reverses the agent-prefix portion of v1.3.2 (v2.0.0).

### Why

Real-world data point: after running a feature through `/agf-team-start`, inter-teammate `SendMessage` routing showed messages getting lost when agent `name:` field carried the `agf-` prefix. Working teams in this Claude Code environment (e.g. user's `projectrebaselineteam`) consistently used bare names (`product-lead`, `tech-lead`, `backend-dev`, …) without issue. The v1.3.2 (v2.0) decision to apply `agf-` prefix uniformly across **all** project objects was right in spirit (namespace isolation) but wrong in scope — the agent path has runtime side effects the skills/commands paths don't.

### Changed (BREAKING)

#### Agents (14) — `.claude/agents/<name>.md` reverted to bare names

| v2.0 (v1.3.2) | v3.0 (this release) |
|---|---|
| `agf-product-lead` | `product-lead` |
| `agf-tech-lead` | `tech-lead` |
| `agf-uiux-designer` | `uiux-designer` |
| `agf-frontend-dev` | `frontend-dev` |
| `agf-backend-dev` | `backend-dev` |
| `agf-ai-agent-dev` | `ai-agent-dev` |
| `agf-ml-engineer` | `ml-engineer` |
| `agf-code-reviewer` | `code-reviewer` |
| `agf-qa-engineer` | `qa-engineer` |
| `agf-miniapp-dev` | `miniapp-dev` |
| `agf-miniapp-code-reviewer` | `miniapp-code-reviewer` |
| `agf-miniapp-qa-engineer` | `miniapp-qa-engineer` |
| `agf-content-writer` | `content-writer` |
| `agf-growth-analyst` | `growth-analyst` |

Both the file names (`.claude/agents/agf-foo.md` → `.claude/agents/foo.md`) and the `name:` field in each frontmatter are reverted.

### Unchanged (intentionally keep `agf-` prefix)

These objects have **no routing side-effects** in Agent Teams runtime, and the prefix still serves as namespace-isolation against built-ins / plugins:

- **5 project skills**: `agf-writing-prd`, `agf-writing-adr`, `agf-running-sit-tests`, `agf-writing-sit-report`, `agf-wiring-multi-llm-sdk`
- **5 project slash commands**: `/agf-team-start`, `/agf-usage`, `/agf-sit`, `/agf-uat`, `/agf-tasks`

### Migration steps (for forks pinned to v1.3.2 / v2.0)

1. Pull this release.
2. If you have local agent files at `.claude/agents/agf-*.md`, they have been renamed to `.claude/agents/*.md` — update any external scripts that reference these paths.
3. If you have local code/docs that reference agent names (e.g. `agf-product-lead`), the global sed replacement in this release covers project files; check your **own** untracked files for stale `agf-<role>` agent references.
4. **Skills and commands paths are unchanged** — no migration needed for those.
5. Existing teams in `~/.claude/teams/` and tasks in `~/.claude/tasks/` are unaffected (they were created using bare names already, since that's what works at runtime).

### Lessons (for the project's own retrospective)

- v1.3.2 (v2.0) was a paper design that was never validated against real Agent Teams runs. v1.4.0 (v3.0) is the first release informed by **real-world feature-run data** — the kind we asked for in earlier sessions.
- Future namespace decisions should be **scoped by runtime impact**, not applied uniformly. A naming convention that works for static config (skills, commands) may break dynamic routing (agents, MCP servers, etc.).

### Added (also in v3.0.0)

- **`.claude/standards/plans-format.md`** — 约束 `superpowers:writing-plans` 生成的实施计划：去 inline 代码块、去逐 step commit、去行号级文件映射；改为"做什么 + 如何验"描述 + ≤3 步/Task + ≤500 字/Plan。执行层收到的是轻量化 plan，具体实现细节由他们自己在 sub-task 内补充。

---

## [v1.3.2] — 2026-05-02 — Namespace pass (folded)

> v3.0.0 docs cleanup pass：v1.3.2 是 v1.4.0 BREAKING 的前置——首次给 `.claude/` 全套对象（agents / skills / commands）加 `agf-` 前缀做 namespace 隔离；v1.4.0 因真实 Agent Teams 运行数据反向 rollback agent 前缀（保留 skills / commands 前缀）。完整原文见 `git log v1.3.0..v1.4.0` + tag annotation。

---

## [v1.x] — pre-2026-05-01 — Initial template

Pre-namespace state. All agents, skills, commands used bare names. See `git log v1.x..main` for the implementation arc:

- 12-agent team with role-based separation (PM / TL / design / FE / BE / AI / ML / QA / CR + 3 miniapp-*)
- 4-layer hook defense (block-dangerous-bash, scan-secrets, sanitize-tool-output, scan-commit)
- Workflow standards (parallel dispatch, AC lifecycle, testing pyramid, cost budget, observability)
- Agent Teams enabled via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
- 5 project skills + 8 slash commands + scheduled job recommendations
- Evals framework with `evals/run.sh validate / checklist`
- ADR-000 baseline (React + Vite + FastAPI + PostgreSQL + DeepSeek/Doubao/Qwen/MiniMax)
