@xulthekl/team-flow 0.32.2 → 0.34.0

package/.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# team-flow v0.32.2 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.34.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "team-flow",
       "description": "8-state spec workflow + compound global compounding + architecture-design (4A/DDD) + local HTML prototype + product-level orchestration + bootstrap + e2e + session handoff + workflow feedback. 24 skills + 15 agents with embedded TDD, SDD, code review, debugging, delta spec sync, and design-system-driven prototyping.",
-      "version": "0.32.2",
+      "version": "0.34.0",
       "source": "./",
       "author": {
         "name": "LT",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.32.2",
+  "version": "0.34.0",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
   "source": "./",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "team-flow",
-  "version": "0.32.2",
+  "version": "0.34.0",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

package/.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Unified workflow plugin marketplace for Cursor (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.32.2"
+    "version": "0.34.0"
   },
   "plugins": [
     {

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "team-flow",
   "displayName": "team-flow",
   "description": "Unified workflow plugin: team-flow (spec-driven dev: TDD/SDD/code-review/debugging) + compound-engineering core subset (brainstorm/plan/compound/strategy/ideate/proof, global compounding) + architecture-design (4A+DDD incremental design & global compounding) + prototype (local HTML prototype, zero external deps) + e2e (Playwright E2E, AC-driven) + workflow-orchestrator (product-level workflow orchestration) + workflow-bootstrap (existing project onboarding) + session-handoff (context transfer) + workflow-feedback (issue tracking). 24 skills + 15 agents, one install.",
-  "version": "0.32.2",
+  "version": "0.34.0",
   "author": {
     "name": "LT",
     "url": "https://github.com/LT"

package/.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Unified workflow plugins and skills for AI coding agents (team-flow: team-flow + compound + architecture-design + prototype).",
-    "version": "0.32.2"
+    "version": "0.34.0"
   },
   "plugins": [
     {
       "name": "team-flow",
       "description": "Unified workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, delta spec sync, architecture-design, and local HTML prototyping.",
-      "version": "0.32.2",
+      "version": "0.34.0",
       "source": ".",
       "author": {
         "name": "LT",

package/AGENTS.md

@@ -210,6 +210,8 @@ STRATEGY.md CONCEPTS.md 产品策略(BA) / 领域词汇
 
 ### Agents 索引（v0.7 新增，v0.30.0 增至 15 个）
 
+> **agent 文件设计规范见 CONTRIBUTING.md §6 + `templates/agent-template.md`**（v0.33.0）：frontmatter 必须合法 YAML（非法时 Claude Code 静默降级，skills: 预加载与 tools: 限制全部失效）；description 单句、禁 `<example>` 块；新增/修改 agent 必过 frontmatter-lint + 实证探针。
+
 | Agent | 职责 | Tools | 触发场景 |
 |-------|------|-------|---------|
 | architecture-design | 架构设计门控 agent——五项检查 + 三件套产出 + SQL 制品（workflow-start 子代理调用，判断+执行一体化） | Read/Bash/Grep/Glob/Write | workflow-start exploring→specifying 状态转换时（架构设计门控，v0.27.2） |

package/CHANGELOG.md

@@ -6,6 +6,62 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.34.0] - 2026-08-04
+
+### Added（测试能力增强——吸收 glaf4-test 通用能力 + conventions 机制，设计见工作区级文档 team-flow-workspace/docs/plan/test-capability-enhancement-design.md）
+
+#### P0：组合覆盖声明（test-strategy SKILL.md）
+- **§8 组合覆盖声明**：多参数方法（param_count > 1）必须声明 `pairwise`，有分支逻辑必须声明 `branch`；contract-builder 生成矩阵后强制对账
+
+#### P1：测试质量规则 + failure 分类法
+- **skills/test-strategy/references/test-quality-rules.md**：从 glaf4-test scan-generated-tests.py 抽取 16 条通用规则（断言质量、调试代码残留、测试状态、测试数据、测试结构、矩阵对账、语言特定）
+- **scripts/lib/test-record.mjs**：新增 `classifyFailure` 函数，测试失败时自动分类为 6 类（assertion_failure / runtime_error / framework_error / compile_error / dependency_blocker / unknown），记录到 test_result
+
+#### P2：社交测试契约 + 测试隔离分级
+- **skills/test-strategy/references/integration-test-contracts.md**：5 种契约类型（入口/协作者/数据/中间件/清理），集成测试的组织方法论
+- **skills/test-strategy/references/integration-test-isolation.md**：4 级隔离策略（L1 进程内 / L2 事务 / L3 手动清理 / L4 无隔离），基础设施隔离策略
+
+#### P2：conventions 机制建设（v0.34.0 核心特性）
+- **templates/conventions/**：plugin 内置 conventions 模板
+  - `glaf4-compliant/java-testing.md`：Java 测试规范（JUnit 5 + Mockito），符合 glaf4-test 要求
+  - `glaf4-compliant/spring-patterns.md`：Spring Boot 测试规范，符合 glaf4-test 要求
+  - `js-testing.md`：JavaScript 测试规范（Jest/Vitest）
+  - `python-testing.md`：Python 测试规范（Pytest）
+  - `_manifest.json`：模板清单（版本、描述、适用技术栈）
+- **scripts/lib/conventions-generator.mjs**：conventions 生成器脚本
+  - 技术栈自动检测（Java/JavaScript/Python）
+  - conventions 模板选择和生成
+  - 版本管理机制（.versions.json）
+  - team-flow.config.json 自动更新
+  - 支持存量项目（自动识别）和全新项目（交互式引导）
+- **skills/workflow-bootstrap/SKILL.md**：增加 B1.5 阶段（Conventions Generator）
+
+### Tests
+- **tests/lib/conventions-generator.test.mjs**：15 个测试（detectTechStack/selectTemplates/generateConventions/updateConfig）
+- 全量回归：571/571 通过（含 15 个新增测试）
+- check-versions ✅
+
+## [0.33.0] - 2026-08-03
+
+### Fixed（skills 注入恢复——frontmatter YAML 非法导致预加载静默失效，设计见工作区级文档 team-flow-workspace/docs/architecture-api-db-design-enhancement-v0.13.md §54）
+
+#### 根因（P2-41）
+- 全部 15 个 agent .md 的 frontmatter 是非法 YAML：`description` 块标量内顶格书写 `<example>`，缩进断裂 → Claude Code 解析静默降级：`skills:` 预加载被丢弃、`tools:` 限制失效、description 回退泛化标签，且无任何警告。插件诞生至今 SKILL.md 方法论从未被注入子代理（v0.32.1 的 contract-builder test-strategy 预加载修复同样未生效）
+- **agents/*.md（15 个）**：description 单句化 + 删除 `<example>` 块（LT 决策，学 glaf4 合法写法）；`skills:`/`tools:` 声明保持
+- **skills/e2e/SKILL.md**、**skills/test-strategy/SKILL.md**：description 含裸 `: `（非法 YAML）→ 加引号/改写修复；test-strategy 顺带修正预加载主体表述（build-executor / contract-builder）
+
+#### 行为变更
+- `skills:` 预加载开始真实生效：dispatch 时 SKILL.md 全文注入子代理上下文
+- `tools:` 限制开始真实生效：子代理工具集从全量（117 个，含全部 MCP）收紧为 frontmatter 声明集
+
+### Added
+- **tests/lib/frontmatter-lint.test.mjs**（P3-12）：frontmatter 合法性长效门禁——js-yaml 严格解析全部 agents/skills/commands frontmatter + name/description 必填断言 + agent name 与文件名一致 + skills: 引用必须解析到真实 skills/<name>/SKILL.md；进 npm test（58 例），杜绝同类缺陷复发
+- devDependency：js-yaml
+
+### Tests
+- 全量回归：556/556（lib 498 + lint 58）+ Tier1 e2e + check-versions ✅
+- 变异验证：门禁对旧式病态 frontmatter 样本可捕获
+
 ## [0.32.2] - 2026-08-03
 
 ### Fixed（C1 死锁链修复三件套，设计见工作区级文档 team-flow-workspace/docs/plan/v0.32.2-hook-and-gate-fix.md）

package/CONTRIBUTING.md

@@ -86,6 +86,50 @@ Skill text should help an agent decide:
 
 Avoid vague motivational language when an operational rule would be clearer.
 
+### 6. Agent file design spec (v0.33.0+)
+
+Background: before v0.33.0, every agent's YAML frontmatter was invalid (an
+`<example>` block at column 0 inside the `description` field). Claude Code
+degrades SILENTLY on invalid frontmatter — `skills:` preload and `tools:`
+restrictions are dropped with no warning, and the agent body alone is kept.
+The defect survived the entire plugin lifetime. `tests/lib/frontmatter-lint.test.mjs`
+(npm test) is the machine gate; this spec is the human gate.
+
+Copy `templates/agent-template.md` when creating a new agent. Hard rules:
+
+1. **`description` is a single-line string.** No `>-` block scalars, no
+   `<example>` blocks — the official Anthropic plugin-dev agents use that
+   pattern and it is a trap (it breaks YAML indentation and silently disables
+   the whole frontmatter). If the text must contain an ASCII `: `, wrap the
+   entire value in double quotes. team-flow agents are dispatched explicitly
+   by `workflow-start`, so example-driven auto-triggering buys nothing.
+2. **`name` must equal the file name** (minus `.md`). On degraded parsing the
+   registry falls back to the file name — a mismatch means silent mislabeling.
+3. **Declare `tools` explicitly.** Since v0.33.0 the restriction is enforced;
+   the subagent holds ONLY the declared tools (no MCP tools unless listed).
+4. **`skills` entries must resolve.** Each entry must match an existing
+   `skills/<name>/SKILL.md` (bare name, same as glaf4-test's proven pattern).
+   A dangling entry means a silent no-preload.
+5. **Body ≤ 100 lines, WHO/WHAT only.** No SOP/methodology in the body — that
+   belongs to the preloaded Skill. If the body says "Your preloaded Skill
+   contains the detailed methodology", the `skills:` field MUST declare it.
+
+Anti-patterns (forbidden):
+
+- `<example>` blocks anywhere in frontmatter
+- Unquoted ASCII `: ` inside `description` values
+- Copying frontmatter style from other plugins without running the lint
+
+Verification (mandatory for new/changed agents):
+
+1. `npm test` — the frontmatter-lint gate must pass.
+2. **Empirical probe** — dispatch the agent once and verify with a BEHAVIORAL
+   probe (ask it to recite a rule that exists only in the preloaded Skill or
+   the agent body). Do NOT rely on exact-string introspection questions — they
+   produce false negatives. Do not write "mechanism works" claims into any doc
+   without this probe. See design doc §54.6 (workspace-level
+   `docs/architecture-api-db-design-enhancement-v0.13.md`).
+
 ## Pull Request Guidance
 
 When opening a change, explain:

package/GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- team-flow-phase-guard-start -->
-# team-flow v0.32.2 | 阶段: {{state}} | 工作流: {{workflow}}
+# team-flow v0.34.0 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- team-flow-phase-guard-end -->

package/INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.32.2**。
+当前发布版本：**v0.34.0**。
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # team-flow
 
-> 当前版本：`v0.32.2`
+> 当前版本：`v0.34.0`
 
 > 统一插件：**team-flow**（spec 驱动开发）+ **compound-engineering 核心子集**（全局复利）+ **architecture-design**（4A+DDD 增量设计）+ **prototype**（本地 HTML 原型）+ **e2e**（AC 驱动 E2E）+ **workflow-orchestrator**（产品级编排）+ **workflow-bootstrap**（既有项目接入）。一次安装，七套能力协同。
 

package/agents/architecture-design.md

@@ -1,39 +1,6 @@
 ---
 name: architecture-design
-description: >-
-  架构设计门控 agent——基于 4A+DDD 执行五项检查，判断是否需要架构增量设计，
-  若需要则产出三件套（architecture.md + database.md + api.md）+ SQL 制品。
-  在 workflow-start 编排中作为子代理调用，承担判断+执行一体化职责。
-  Examples:
-
-<example>
-Context: workflow-start 在 exploring 完成后，需要判断本 change 是否涉及架构变更。
-user: "exploring 完成了，帮我做架构设计判断"
-assistant: "我来启动 architecture-design agent，执行五项检查判定是否需要架构增量设计。"
-<commentary>
-architecture-design 是 exploring→specifying 之间的门控 agent。五项检查全部为否则 skipped，
-任一为是则 required 并产出三件套。workflow-start 负责后续的 auto-review + reasonableness check。
-</commentary>
-</example>
-
-<example>
-Context: hotfix 模式下仍需要经过架构设计判断门（hotfix 可能正是架构缺陷导致）。
-user: "这是一个 hotfix，需要过架构设计门控吗？"
-assistant: "需要。architecture-design 判断门对 hotfix/tweak 不豁免——启动 agent 执行五项检查。"
-<commentary>
-v0.9 §26 明确要求 hotfix/tweak 同样过 architecture-design 子代理判断门。
-</commentary>
-</example>
-
-<example>
-Context: 五项检查判定为 skipped，但 change-brief 中包含"新增 API"字样。
-user: "brief 里说新增 API，但 agent 说 skipped，这不合理吧？"
-assistant: "workflow-start 的 reasonableness check 检测到不一致——skipped + brief 含架构变更关键词 → BLOCK。需要重新执行架构设计。"
-<commentary>
-reasonableness check 是 workflow-start 的职责，不是 architecture-design agent 的。
-agent 只负责判断+产出，workflow-start 负责确认合理性。
-</commentary>
-</example>
+description: 架构设计门控 agent——基于 4A+DDD 执行五项检查判断是否需要架构增量设计，需要则产出三件套（architecture.md + database.md + api.md）+ SQL 制品。在 workflow-start 编排中作为子代理调用，承担判断+执行一体化职责。
 
 model: inherit
 color: blue

package/agents/architecture-reviewer.md

@@ -1,47 +1,6 @@
 ---
 name: architecture-reviewer
-description: >-
-  架构设计自动审查 agent——独立上下文、只读审查，对照 PRD/plan/change-brief + 全局基线 +
-  conventions 审查架构产出质量（6 维度 A1-A6）。填补 architecture-design 阶段
-  "设计完无审查"的缺口。循环修正 ≤3 轮 + 收敛检测。
-  Examples:
-
-<example>
-Context: architecture-design agent 刚产出三件套，workflow-start 需要自动审查质量。
-user: "架构设计完成了，帮我审查一下产出质量"
-assistant: "我来启动 architecture-reviewer agent，独立审查架构产出的 6 维度质量。"
-<commentary>
-architecture-reviewer 在独立上下文中运行，未参与架构设计产出，规避锚定效应。
-审查报告写在 response 中，由编排层落盘到 changes/<name>/architecture/auto-review.md。
-</commentary>
-</example>
-
-<example>
-Context: 架构产出经过修正后需要重新审查（第 2 轮）。
-user: "架构设计修正完了，重新跑一下审查"
-assistant: "我启动 architecture-reviewer agent 进行第 2 轮审查，对比修正前后不一致项是否收敛。"
-<commentary>
-FAIL 后修正→重新审查，最多 3 轮。连续两轮不一致项集合无缩小则转人工，避免死循环。
-</commentary>
-</example>
-
-<example>
-Context: 用户想确认架构产出是否覆盖了 change-brief 中的所有需求。
-user: "brief 里定义了 5 个功能点，架构设计是不是都覆盖了？"
-assistant: "让 architecture-reviewer agent 做 A4 需求覆盖的结构化检查。"
-<commentary>
-A4 需求覆盖是最关键的维度——遗漏意味着需求在架构层面丢失，下游 spec/code 无法弥补。
-</commentary>
-</example>
-
-<example>
-Context: 想检查架构产出是否遵循项目级 conventions。
-user: "帮我看看架构设计是否符合项目的 DB 命名规范和 API 规范"
-assistant: "我启动 architecture-reviewer agent 做 A6 conventions 合规检查。"
-<commentary>
-A6 读取 .team-flow/conventions/ 下的规范文件，逐项比对架构产出是否遵循。
-</commentary>
-</example>
+description: 架构设计自动审查 agent——独立上下文、只读审查，对照 PRD/plan/change-brief + 全局基线 + conventions 审查架构产出质量（6 维度 A1-A6），填补 architecture-design 阶段"设计完无审查"的缺口。循环修正 ≤3 轮 + 收敛检测。
 
 model: inherit
 color: yellow

package/agents/bug-investigator.md

@@ -1,42 +1,6 @@
 ---
 name: bug-investigator
-description: Use this agent when the user encounters a bug, test failure, unexpected behavior, build failure, or performance issue and wants autonomous root-cause investigation. The agent explores the codebase, forms hypotheses, tests them, and produces a structured root-cause analysis report. Examples:
-
-<example>
-Context: A test is failing and the user wants to understand why before attempting a fix.
-user: "This test has been failing since yesterday, can you investigate why?"
-assistant: "I'll launch the bug-investigator agent to systematically trace the root cause of the test failure."
-<commentary>
-The user wants root-cause analysis, not a quick patch. The bug-investigator agent follows a scientific method: read errors → reproduce → trace data flow → form hypothesis → test → report. It writes investigation notes but does not fix the code.
-</commentary>
-</example>
-
-<example>
-Context: Unexpected behavior in production that doesn't reproduce easily.
-user: "用户在生产环境报了一个诡异的 bug，偶发性的，帮我排查一下"
-assistant: "我来启动 bug-investigator agent，系统性地排查这个偶发问题的根因。"
-<commentary>
-Intermittent bugs require structured investigation — gathering evidence, checking component boundaries, tracing data flow. The agent excels at methodical root-cause analysis for hard-to-reproduce issues.
-</commentary>
-</example>
-
-<example>
-Context: Multiple fix attempts have failed and the user suspects a deeper issue.
-user: "I've tried fixing this three times and it keeps breaking in different ways — something is fundamentally wrong"
-assistant: "This sounds like an architectural issue. Let me dispatch the bug-investigator agent to do a deep root-cause investigation."
-<commentary>
-Multiple failed fixes indicate the symptom is being addressed, not the cause. The agent's DP-5 escalation logic specifically handles this: 3+ failures = question the architecture.
-</commentary>
-</example>
-
-<example>
-Context: A build failure with unclear error messages.
-user: "The build broke and the error message doesn't make sense, can you figure out what's going on?"
-assistant: "I'll use the bug-investigator agent to trace the build failure to its root cause."
-<commentary>
-Unclear errors require careful reading of stack traces, checking recent changes, and tracing dependency chains. The agent systematically narrows down the cause.
-</commentary>
-</example>
+description: Use this agent when the user encounters a bug, test failure, unexpected behavior, build failure, or performance issue and wants autonomous root-cause investigation. The agent explores the codebase, forms hypotheses, tests them, and produces a structured root-cause analysis report without implementing fixes.
 
 model: inherit
 color: yellow

package/agents/build-executor.md

@@ -1,27 +1,6 @@
 ---
 name: build-executor
-description: >-
-  构建执行 agent——在 execution-contract.md 经 DP-3 批准之后、release-archivist 之前,
-  以契约为权威驱动 TDD 批次实施(SDD/Inline/Batch Inline)。可写型,负责实施代码产出。
-  Examples:
-
-<example>
-Context: 契约已批准,用户希望按纪律逐批实施。
-user: "契约批了,开始按 TDD 实施"
-assistant: "I'll launch the build-executor agent to govern the batch-by-batch TDD build."
-<commentary>
-build-executor 是 executing 阶段的实施 agent,守 TDD Iron Law 与契约优先,产出实施代码。
-</commentary>
-</example>
-
-<example>
-Context: 实施中出现契约外新行为,需要回退而非硬做。
-user: "做着做着发现要加一个契约里没有的能力"
-assistant: "I'll have build-executor rewind to specifying/bridging instead of silently expanding scope."
-<commentary>
-Law 4 Rewind on Contract Break:新行为/接口实质变化/设计假设失效 → 回退规划,不私自扩 scope。
-</commentary>
-</example>
+description: 构建执行 agent——在 execution-contract.md 经 DP-3 批准之后、release-archivist 之前，以契约为权威驱动 TDD 批次实施（SDD/Inline/Batch Inline）。可写型，负责实施代码产出。
 
 model: inherit
 color: green

package/agents/change-split-auditor.md

@@ -1,47 +1,6 @@
 ---
 name: change-split-auditor
-description: >-
-  plan.md 拆分质量审计。在 ce-plan 产出 plan.md 后、change 脚手架前，
-  独立审计拆分质量：PRD 需求覆盖矩阵、DAG 无环、粒度均衡、字段完整性、所有权粒度合规（v0.9 根因判据硬门禁：切碎检测/无设计单元/跨单元臃肿）。
-  输出 PASS/FAIL verdict。只读审查。
-  Examples:
-
-<example>
-Context: ce-plan 刚产出 plan.md，orchestrator 需要在创建 change 目录前验证拆分质量。
-user: "plan.md 写好了，帮我检查一下拆分是否合理"
-assistant: "我来启动 change-split-auditor agent，独立审计 plan.md 的拆分质量。"
-<commentary>
-拆分质量审计是 orchestrator S4 阶段的前置门禁。审计失败时编排层携 findings
-回退 ce-plan 加深，避免有缺陷的拆分进入执行。
-</commentary>
-</example>
-
-<example>
-Context: 用户担心 plan 遗漏了 PRD 中的某些需求。
-user: "PRD 里有 12 个功能点，plan 的 change 是不是都覆盖了？"
-assistant: "让 change-split-auditor agent 构建 PRD→change 覆盖矩阵，检查有无遗漏或重叠。"
-<commentary>
-需求覆盖矩阵是 5 维度审计中最关键的一环——遗漏意味着需求丢失，重叠意味着重复工作。
-</commentary>
-</example>
-
-<example>
-Context: plan 中有多组依赖关系，用户想确认不存在循环依赖。
-user: "change-3 依赖 change-1，change-1 又依赖 change-3，这不是死循环了吗？"
-assistant: "我启动 change-split-auditor agent 做 DAG 无环验证和依赖完整性检查。"
-<commentary>
-循环依赖会导致所有涉及的 change 永远无法启动。DAG 验证是机械化的拓扑排序检查。
-</commentary>
-</example>
-
-<example>
-Context: plan 修订后需要重新审计。
-user: "plan 改过了，重新跑一下拆分审计"
-assistant: "我启动 change-split-auditor agent 对修订后的 plan.md 重新做 5 维度审计。"
-<commentary>
-FAIL 后 ce-plan 加深→重新审计，直到 PASS 才进入 change 脚手架。
-</commentary>
-</example>
+description: plan.md 拆分质量审计。在 ce-plan 产出 plan.md 后、change 脚手架前，独立审计拆分质量——PRD 需求覆盖矩阵、DAG 无环、粒度均衡、字段完整性、所有权粒度合规（v0.9 根因判据硬门禁：切碎检测/无设计单元/跨单元臃肿）。输出 PASS/FAIL verdict。只读审查。
 
 model: inherit
 color: cyan

package/agents/code-reviewer.md

@@ -1,47 +1,6 @@
 ---
 name: code-reviewer
-description: >-
-  代码审查 agent——审查代码质量、规格合规性、架构合理性、实现完整性。在 build-executor
-  执行后、release-archivist 归档前，独立审查实现质量。只读审查，不修改任何文件。
-  Examples:
-
-<example>
-Context: build-executor 刚完成一个 wave 的实现，orchestrator 需要审查代码质量。
-user: "wave-1 实现完了，帮我 review 一下代码"
-assistant: "我来启动 code-reviewer agent，独立审查 wave-1 的代码质量。"
-<commentary>
-代码审查是 build-executor 完成后、release-archivist 归档前的关键门禁。本 agent 在独立上下文中运行，
-未参与实现，规避锚定效应。审查报告写在 response 中，由编排层落盘。
-</commentary>
-</example>
-
-<example>
-Context: 用户担心实现偏离了规格说明。
-user: "帮我看看实现有没有偏离 design.md 和 specs/"
-assistant: "让 code-reviewer agent 做规格合规性检查，逐项核对实现与 spec 的一致性。"
-<commentary>
-规格合规性是审查的核心维度——实现必须忠实反映 design.md 的决策和 specs/ 的要求。
-偏离必须有明确理由（如技术约束），否则是 Critical finding。
-</commentary>
-</example>
-
-<example>
-Context: 实现经过修正后需要重新审查（第 2 轮）。
-user: "按上一轮 review 意见改了，重新跑一下审查"
-assistant: "我启动 code-reviewer agent 进行第 2 轮审查，对比修正前后问题是否收敛。"
-<commentary>
-FAIL→修正→重新审查，最多 3 轮。连续两轮问题集合无缩小则转人工，避免死循环。
-</commentary>
-</example>
-
-<example>
-Context: 复杂架构变更需要专项审查。
-user: "这次改了 3 个聚合的边界，帮我重点看看架构是否合理"
-assistant: "我启动 code-reviewer agent，重点审查架构决策、模块边界、依赖方向。"
-<commentary>
-架构审查关注分离关注点、依赖方向、接口设计、可扩展性。复杂变更需要专项深度审查。
-</commentary>
-</example>
+description: 代码审查 agent——审查代码质量、规格合规性、架构合理性、实现完整性。在 build-executor 执行后、release-archivist 归档前，独立审查实现质量。只读审查，不修改任何文件。
 
 model: inherit
 color: blue

package/agents/contract-builder.md

@@ -1,27 +1,6 @@
 ---
 name: contract-builder
-description: >-
-  执行契约 agent——在 spec-writer 产出规划制品并通过 DP-2 之后、build-executor 之前,
-  将规划制品压缩为单一执行握手 execution-contract.md。可写型,负责执行契约文件。
-  Examples:
-
-<example>
-Context: 四件规划制品已稳定且 DP-2 已记录,准备进入实施。
-user: "规划都确认了,帮我生成执行契约,准备开干"
-assistant: "I'll launch the contract-builder agent to convert the artifacts into execution-contract.md."
-<commentary>
-contract-builder 是 bridging 阶段的核心 agent,产出 execution-contract.md 并守 DP-3 批准门。
-</commentary>
-</example>
-
-<example>
-Context: 既有契约因 scope 变更而过期,需要刷新。
-user: "specs 改了,执行契约好像对不上了"
-assistant: "I'll have contract-builder detect staleness and refresh the contract."
-<commentary>
-契约过期检测:scope/requirements/constraints/batches 变化即刷新,不静默放行陈旧契约。
-</commentary>
-</example>
+description: 执行契约 agent——在 spec-writer 产出规划制品并通过 DP-2 之后、build-executor 之前，将规划制品压缩为单一执行握手 execution-contract.md。可写型，负责执行契约文件。
 
 model: inherit
 color: magenta

package/agents/cross-change-consistency-checker.md

@@ -1,48 +1,7 @@
 ---
 name: cross-change-consistency-checker
-description: >-
-  跨 change 冲突检测。在多 change 并行执行期或 change closing 时，
-  检测共享聚合/实体被多个 change 修改、API 签名变更影响、
-  与全局架构锚点漂移、与原型 testid 契约漂移。只读审查。
-  Examples:
-
-<example>
-Context: 两个 change 正在并行开发，orchestrator 在 S5 监控阶段触发一致性检测。
-user: "change-1 和 change-2 都在跑，帮我看看有没有冲突"
-assistant: "我来启动 cross-change-consistency-checker agent，检测跨 change 的 4 维度冲突。"
-<commentary>
-多 change 并行执行时，共享聚合/API/架构锚点可能被不同 change 独立修改导致冲突。
-S5 全局监控阶段（change≥2 时必选）定期触发此检测。
-</commentary>
-</example>
-
-<example>
-Context: 一个 change 即将 closing，需要检查它的修改是否与其他 change 矛盾。
-user: "change-3 要合并了，先检查一下跟其他 change 有没有冲突"
-assistant: "我启动 cross-change-consistency-checker agent 做 closing 前的跨 change 冲突检测。"
-<commentary>
-Change closing 是冲突检测的关键时机——合并后再发现冲突代价更高。
-</commentary>
-</example>
-
-<example>
-Context: 用户怀疑某个 change 的实现偏离了全局架构文档。
-user: "change-2 改的数据模型跟 DATABASE.md 里定义的对不上"
-assistant: "让 cross-change-consistency-checker agent 检测 change-2 与全局架构锚点的漂移。"
-<commentary>
-架构锚点漂移检测（Dim 3）比对 change 实际修改与 ARCHITECTURE.md/DATABASE.md
-的声明，发现未回写的结构性变更。
-</commentary>
-</example>
-
-<example>
-Context: 原型中定义了 data-testid 契约，需要检查各 change 是否遵守。
-user: "原型里定义了 testid，看看各个 change 有没有按契约来"
-assistant: "我启动 cross-change-consistency-checker agent 做 testid 契约漂移检测。"
-<commentary>
-Dim 4 检测原型 testid 契约是否被 change 实现正确引用，保障 E2E 测试基础。
-</commentary>
-</example>
+description: 跨 change 冲突检测。在多 change 并行执行期或 change closing 时，检测共享聚合/实体被多个 change 修改、API 签名变更影响、与全局架构锚点漂移、与原型 testid 契约漂移。只读审查。
+
 
 model: inherit
 color: red

package/agents/need-explorer.md

@@ -1,27 +1,6 @@
 ---
 name: need-explorer
-description: >-
-  需求探索 agent——在 workflow-start 路由后、spec-writer 之前,于 change 上下文内交互式
-  澄清意图/scope/约束/成功标准,稳定 change 定义并守 DP-1 门。只读型,不产出制品不写代码。
-  Examples:
-
-<example>
-Context: change 上下文内请求模糊,需要先澄清再写制品。
-user: "我想给这块加点东西,但还没想清楚"
-assistant: "I'll launch the need-explorer agent to clarify intent and scope before any artifact."
-<commentary>
-need-explorer 是 exploring 阶段的澄清 agent,一次一问、偏好选择题,稳定 change 定义。
-</commentary>
-</example>
-
-<example>
-Context: 本 change 由 workflow-orchestrator S4 分发,change-brief.md 已存在。
-user: "这是 orchestrator 拆出来的 change,帮我确认下范围"
-assistant: "I'll have need-explorer read the brief first and only probe what it leaves open."
-<commentary>
-brief 存在时先读再问,把 brief 的 Scope/约束/AC 作为默认值,默认不再二次拆分。
-</commentary>
-</example>
+description: 需求探索 agent——在 workflow-start 路由后、spec-writer 之前，于 change 上下文内交互式澄清意图/scope/约束/成功标准，稳定 change 定义并守 DP-1 门。只读型，不产出制品不写代码。
 
 model: inherit
 color: blue