@xgent-ai/skills 0.3.0 → 0.4.0

package/skills/debugging/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: debugging
+description: Four-phase debugging framework that ensures root cause investigation before attempting fixes. Never jump to solutions. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.
+license: MIT
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See root-cause-tracing skill for backward tracing technique
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Integration with Other Skills
+
+This skill works with:
+- root-cause-tracing - How to trace back through call stack
+- defense-in-depth-validation - Add validation after finding root cause
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/skills/dev-plan/SKILL.md

@@ -1,17 +1,15 @@
 ---
 name: dev-plan
-description: 基于用户需求、仓库规则和当前代码事实，撰写或评审可直接交给实现者执行并跨对话续做的开发计划、技术设计、立项方案与实施路线图；也用于按某份既有计划推进实施时的进度回写与跨对话续做。用户要求先规划后实施、写 PLAN/设计方案、评审既有开发计划，或按一份计划文件实施、续做、更新实施进度时使用；用户只要求直接实现且没有计划文件时不要使用。
+description: 基于用户需求、仓库规则和当前代码事实，撰写或评审可直接交给实现者执行、跨对话续做的开发计划、技术设计、立项方案与实施路线图。用户要求先规划后实施、写 PLAN/设计方案、评审既有开发计划时使用。按既有计划实施、续做或回写实施进度时不要使用——计划文件自带实施约定，直接读计划；用户只要求直接实现且没有计划文件时也不要使用。
 ---
 
 # dev-plan · 基于代码事实的可执行开发计划
 
 **路径约定**：`references/` 与 `scripts/` 均相对于本 `SKILL.md` 所在目录。运行脚本前，在目标仓根目录按实际加载位置设置 `SKILL_DIR="<本 SKILL.md 所在目录>"`；计划文件与仓库根参数仍按目标仓路径填写。
 
-## 实施期入口（按既有计划实施时只读本节）
+## 适用边界：只管写与评审，不管实施
 
-按既有计划实施或续做时，只读本节及 [references/execution-workflow.md](references/execution-workflow.md)：执行**简要进度回写、记录按需读取和无冲突任务的 subagent 并行调度**。下面的架构师角色定位、第 0–5 步及写计划参考都不适用，不要为实施加载它们。
-
-计划文件顶部的「实施者定位」和「实施进度」是实施期的合同。进度区只保留恢复快照与每个里程碑的一行状态、简要进展和记录链接；实现与验收详情单独保存，恢复时不自动读入。满足依赖、文件和运行资源互不干扰的任务，应启动多个 subagents 并发完成；无特别要求时继承主 agent 的模型。主 agent 统一集成、验收和回写计划。
+按既有计划实施或续做不用本 skill：计划开头的「实施须知」明确告诉实施者不要加载本 skill，「实施者定位」与「实施进度」已带齐实施需要的全部约定（进度回写、独立记录格式、subagent 并行、进度校验命令），实施者直接读计划。同一对话里写完计划接着实施，也按计划顶部两节执行，不再读本 skill 的参考。由此推出一条写作约束：**实施期需要的任何规则都必须写进骨架的这两节**，不能只留在本 skill 里。
 
 ## 角色定位（写计划前先采用）
 
@@ -37,12 +35,19 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 
 ## 交付约定
 
-- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。计划正文不声明用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
+- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。除开头固定的「实施须知」外，计划正文不提用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
 - **落盘**：用户指定路径优先；否则仓库根存在 `goal/` 时写 `goal/<代号>.md`，不存在时写 `docs/plan/<代号>.md`（按需创建目录）。目标文件已存在时先确认再覆盖。
 - **范例**：输出目录里若有同类型旧计划，可选读 1–2 份校准项目惯例；旧计划只是样例，不是事实源，路径、行为和数字仍须核实。
-- **代码基线**：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。
-- **计划状态**：使用 `Ready`、`Blocked` 或 `Proposed`。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 `Blocked`；设计完整但等待非阻塞评审时可为 `Proposed`；无实施阻塞才是 `Ready`。
-- **实施进度**：计划顶部是进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情默认按里程碑保存在计划旁的 `<计划文件名去扩展名>.records/M<n>.md`，从完成记录链接；不另造一份汇总进度，不预建空记录。
+- **代码基线**：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。只保留最近一次核对的一条基线，改稿时就地更新，不追加复核经过。
+- **计划状态**：使用 `Ready`、`Blocked` 或 `Proposed`。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 `Blocked`；设计完整但等待非阻塞评审时可为 `Proposed`；无实施阻塞才是 `Ready`。顶部状态行只写状态，定级理由写 §11，实施进展只写「实施进度」。
+- **实施进度**：计划顶部是进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情按里程碑保存在计划旁的 `<计划文件名去扩展名>.records/M<n>.md`，只留结果、验证证据与续做所需缺口；子任务不默认另建过程文档，不预建空记录。
+
+## 控制计划与执行成本
+
+- **信息只展开一次**：已有 PRD 就沿用需求 ID，以来源、差异和设计/验收链接建账本，不复制验收原文。账本已覆盖需求 → 设计 → 验证时，省略末尾重复映射表；接口、NFR、风险在所属章节定义，其余位置引用。保留影响实现的精确信息，删去重复解释。
+- **里程碑围绕可验证成果**：不要把每个模块或工种都升成独立里程碑。同一能力、同一环境且无独立发布/回滚或风险门的工作，可合成一个里程碑，内部保留任务依赖和局部检查。独立安全、数据迁移、不可逆操作、发布及用户约定的分期门仍单列。
+- **开发前置不等于终验前置**：依赖写到实际需要的契约/子任务与验证，不默认等待上游整个里程碑；前置检查必须证明该成果可用。端到端走查、全量回归、故障演练和评测可集中到阶段收口，各里程碑保留自身新增行为与风险的检查；阶段收口通过前不得宣称整期或整条跨期需求已验收。
+- **验证与证据复用**：§9 定义检查 ID/测试组、覆盖的需求或验收行、环境与执行时点，里程碑引用检查 ID，不重抄断言。执行时点须晚于所需能力/环境就绪，不让骨架里程碑验收尚未实现的端到端路径。同一部署可合并 API/UI 主路径走查；相关代码、配置、依赖、输入与环境未变时复用已通过证据，变更后重跑受影响检查，阶段收口跑必要集成回归。重构仍先建立行为基线。
 
 ## 流程总览
 
@@ -65,7 +70,7 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 
 ## 第 1 步：需求账本与计划定性
 
-把输入拆成四类，并在最终映射表逐条覆盖：
+把输入拆成四类，并在需求账本或映射表逐条覆盖（保留一份完整映射即可）：
 
 | 类型 | 内容 | 规则 |
 | --- | --- | --- |
@@ -120,31 +125,31 @@ description: 基于用户需求、仓库规则和当前代码事实，撰写或
 - 数字只能来自用户、代码/配置、项目规则或明确决策。热查询说明已有索引或迁移增量；未知规模不靠猜测决定新基础设施。
 - 多道闸写执行顺序，错误码与第一道实际失败的闸一致；安全、可靠性和 NFR 条目都要能转成可观察的验证。
 - 涉及持久化、对外契约或滚动部署时，写清兼容窗口、expand/migrate/contract、回填/重放、发布与回滚门。
-- 每个里程碑有独立验收；重构先保留行为基线，再通过模块接口验证结果，避免测试内部实现细节。
-- 写清里程碑及任务的前置依赖、可并行范围与共享文件/资源的单一负责人。只有前置已满足、契约已稳定且互不干扰的任务才可并行；收尾设集成验收，不保留“一律按编号串行”的限制。复杂调度按需读 [references/execution-workflow.md](references/execution-workflow.md) 的“并行执行”。
-- 每个里程碑的退出条件**逐行**以「回写『实施进度』」结尾。实施者是按行核对退出条件的：把这条只写在表外的总说明里，它就会被跳过，进度也就攒到本期收尾才补。
+- 每个里程碑有明确退出条件，局部检查与阶段终验按上文分工；验收合并须说明共同环境、覆盖范围和保留的风险门，不能只删检查或延后风险发现。
+- 写清实际前置成果及验证、可并行范围与共享文件/资源的单一负责人。前置已满足、契约稳定且互不干扰才可并行；按任务规模与集成成本决定是否委派，不为并行硬拆。复杂调度按需读 [references/execution-workflow.md](references/execution-workflow.md)。
+- 每个里程碑的退出条件逐行以「回写『实施进度』」结尾，防止完成后漏记。
 - 在计划顶部初始化实施进度：总里程碑数、当前状态、最近完成、下一步、阻塞和代码基线必须与里程碑表一致；计划尚未实施时如实写“0/N、尚未开始、下一步 M1”，不得预填完成记录。
-- 骨架顶部的“实施者定位”原样带入计划，不改写、不删减：它是给执行计划的 agent 的定位，与写计划的架构师定位是两回事。
+- 骨架开头的“实施须知”及“实施者定位”“实施进度”协议原样带入计划，不改写、不删减：它们是给执行计划的 agent 的完整合同，与写计划的架构师定位是两回事。唯一的填空是“回写后自查”里的 `<进度校验命令>`：本 skill 目录在目标仓内时，换成从仓库根可直接运行的 `bash <本 skill 目录相对仓库根的路径>/scripts/check_progress.sh <计划相对仓库根的路径> .`；不在仓内（全局安装）时把整句改成“每次回写后按上述条目人工核对”，不写本机绝对路径。
 - 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。
 
 ## 第 5 步：自检、就绪与交付
 
 1. 跑 `"$SKILL_DIR/scripts/check_paths.sh" <计划文件> <仓库根>`，人工区分新增路径与虚构的“复用/已核实”路径。
-2. 对照 `R-* / NFR-* / C-* / A-*` 检查映射：每条有设计、验证、排除去向或阻塞说明。
+2. 对照需求账本或映射表检查 `R-* / NFR-* / C-* / A-*`：每条有设计、验证、排除去向或阻塞说明；同一事实和断言没有多处展开。
 3. 按 `references/architecture-quality.md` 的一致性清单检查凭证/scope、接口/调用方、数据约束/生命周期、设计/验证、发布/回滚和多处重复口径。
 4. 建失败模式表：高影响失败至少写触发、爆炸半径、数据后果、用户表现、检测、恢复与验证；简单局部任务可说明“不引入新的运行期失败模式”及依据。
-5. 检查“实施者定位”与“实施进度”的回写协议为骨架原文在位；每个里程碑的退出条件都以「回写『实施进度』」结尾，依赖与可并行边界明确；跑 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根>` 确认进度与里程碑一致，记录链接有效；初稿不预填完成事实，不把实现与验收详情写回计划。
+5. 检查顶部实施协议为骨架原文在位、`<进度校验命令>` 已替换；每个里程碑退出条件以「回写『实施进度』」结尾，依赖与并行边界明确，阶段收口覆盖被集中的验收且保留必要风险门；跑 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根>` 确认进度与里程碑一致、记录链接有效；初稿不预填完成事实，详情不写回计划。
 6. 最终定级：存在影响范围、安全、数据、外部契约或关键 NFR 的未决项即 `Blocked`；只等非阻塞评审为 `Proposed`；所有实施前置已解决才是 `Ready`。
 7. 汇报计划路径与状态，并单列：待拍板问题、与用户假设冲突的事实、被砍/推迟的范围、未在真实环境完成的调查或验证。
 
-评审既有计划时，默认只输出问题、证据、严重度和修订建议；用户明确要求改稿时才覆盖原计划。
+评审既有计划时，默认只输出问题、证据、严重度和修订建议；用户明确要求改稿时才覆盖原计划。改稿把结论直接改进正文与对应决策、刷新调查基线；评审出处、采纳/拒绝理由和修订经过留在评审报告与提交说明，不写进计划。
 
 ## 红线
 
-- 写作/评审模式不实施功能；用户已要求按计划实施时，直接进入实施期入口，无需重复请求授权。
+- 写作/评审模式不实施功能；用户已要求按计划实施时，按计划顶部两节直接实施，无需重复请求授权。
 - 未读过的代码不写“已核实”，没有来源的数字不写成目标或现状。
 - 不吞需求，不把重大假设藏进正文，不把阻塞计划标为 `Ready`。
 - 不把未通过退出条件的里程碑写成已完成，不用聊天记录代替计划内的简要进度与独立的实现/验收记录；不在续做时批量加载历史记录。
 - 不为假想扩展造接缝、基础设施或抽象，也不照搬通用架构示例覆盖仓库现实。
-- 计划里不写写作过程：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查做了几轮，既不是实施事实也不是里程碑进展，还会诱导实施者去加载只有写计划才需要的上下文。
+- 计划里不写写作过程（开头固定的「实施须知」除外）：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查或复核做了几轮、评审意见的采纳与改稿经过、“本次只写/修订计划、未实施”这类写作当时的状态、“本轮/刚才”这类只在写作对话里成立的指代（来源写“用户 YYYY-MM-DD 确认”）。它们既不是实施事实也不是里程碑进展，会随实施过期、误导实施者、白占上下文；提到 skill 还会诱导实施者去加载只有写计划才需要的内容。
 - 不在出仓 skill 中硬编码某个仓库的模板、技术栈、端口、样板计划、本机路径或业务约定；这些必须在运行时从目标仓规则和代码读取。

package/skills/dev-plan/references/execution-workflow.md

@@ -1,78 +1,25 @@
-# 按计划实施：进度、记录与并行
+# 依赖与并行调度：写计划与评审时用
 
-实施或续做时读取本文件；写计划时仅在需要细化调度边界时读“并行执行”。不加载写作骨架或架构参考作为实施上下文。
-
-## 先恢复最小上下文
-
-先读仓库规则、计划的恢复快照/完成记录索引、当前任务对应的正文与依赖，再核对 `git status` / 相关 diff。记录与工作树不符时查明原因，不凭历史记录覆盖用户改动，不凭代码存在就推断验收已通过。
-
-**独立记录按需读取**：只有继续某个未完任务、核实其前置验收、排查失败/偏差或审查交付时，才打开该里程碑记录的相关章节。无需例行复读最近完成的详细记录，更不要 `cat` 全部记录或把历史日志传给每个 subagent。只查结构一致性时运行校验脚本，看简短结果即可。
-
-## 计划只存摘要，详情独立落盘
-
-- 计划顶部保留七行恢复快照。当前状态列出在做的里程碑及最近实质进展，下一步给可执行动作；不写命令、断言列表、调试过程或完整改动清单。
-- “完成记录”是一张里程碑索引：`Milestone / 状态 / 更新时间 / 简要记录 / 实现与验收记录`。每个已开始的里程碑最多一行，状态仅用 `进行中`、`阻塞`、`已完成`；摘要一到两句，写交付结果或“已做到哪里、还差什么”。进行中/阻塞不计入完成数。
-- 默认每个里程碑一份 `<计划名>.records/M<n>.md`，在其中分开写“实现记录”和“验收记录”；链接相对计划文件解析，例如 `[M1 记录](FEATURE.records/M1.md)`。用户已有记录目录时沿用。详情只从完成记录链接，不在正文/快照重复嵌入。
-- 记录首次有实施事实时再建；原始日志、截图、完整 diff 仅在有复核价值时单独保存并从记录链接。记录本身也要提炼证据，不复制终端流水、聊天或阅读清单。
-
-### 独立记录的最小内容
-
-按下面结构写真实内容，不预填通过；它不是另一份总进度表。
-
-```markdown
-# M1 · 实现与验收记录
-
-- 对应计划：相对链接
-- 最近更新：日期、时间与时区
-- 状态：进行中 / 阻塞 / 已完成
-- 代码基线：commit SHA；未提交写 dirty@起始SHA，非 Git 写可用版本标识
-
-## 实现记录
-
-- 已交付行为、关键改动路径、必要决策及计划偏差。
-- 尚未完成项、阻塞事实及继续动作；完成后写无。
-- 并行任务如有独立交付记录，在这里链接，不复制全部内容。
-
-## 验收记录
-
-| 退出条件 | 命令或走查步骤 | 环境/代码基线 | 结果与必要证据 |
-| --- | --- | --- | --- |
-
-逐条记录实际结果；未运行、失败、环境缺失明确区分。人工/UI 验证写环境、主路径与关键边界结论。必要的日志/截图用链接。
-```
-
-代码基线必须对应验证时的实现；dirty 时在实现记录列关键改动路径，不能用 HEAD 冒充已提交成果。主 agent 的集成修正若影响既有结果，应更新验收证据。subagent 完成自己的任务不等于里程碑通过验收。
-
-## 每个里程碑及时回写
-
-每次完成里程碑，或发生实质进展后准备暂停、受阻、切换任务、结束对话时，按顺序完成以下动作；并行任务逐个收敛，不等整个批次结束才补记：
-
-1. **先保存独立记录**：及时记下实现与实际验收结果。全部功能/验收条件通过才标 `已完成`；未通过则保存已有成果和缺口，保持 `进行中` 或 `阻塞`。
-2. **再刷新计划摘要**：同步七行快照和该里程碑的一行索引，链接到已存在的记录文件。由未完成转为已完成时，将该行移至已完成记录末尾，不增加重复行；已完成行按实际完成先后排列，“最近完成”取最后一条已完成记录，不按编号大小推算。并行时允许 M3 比 M2 先完成。
-3. **有偏差就修正文**：范围、决策、接口、数据、风险或退出条件变化，修订对应章节，快照只点明变化及影响。不要把偏差藏在独立记录里。
-4. **校验后再交接**：运行 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> [仓库根]`。先完成记录落盘与计划回写，再报告完成、提交代码或启动依赖该成果的任务；已经独立运行的任务可继续。
-
-脚本检查数量、状态、里程碑 ID、最近完成和引用文件存在性，不默认读取所有记录内容，也不证明验收真实通过。主 agent 在记完成时核验该里程碑的证据；后续恢复只按需要复核。
-
-旧计划首次按此流程续做时，将已有完成详情迁到独立记录，保留原时间、结果和基线；计划改成摘要索引。没有证据就保留缺口，不能补造通过记录。只迁移正在执行的这份计划，不批量改其他历史计划；旧规则中的串行限制若只是旧模板默认值，可按依赖核实后更新，项目确有顺序约束则保留。
+写计划时细化里程碑的依赖与并行边界、评审时核对编排能否安全执行，读本文件。实施者不读它：实施需要的并行、回写与记录约定已原样写进计划的「实施者定位」「实施进度」两节（见 `plan-skeleton.md`），改这里的规则时同步改那两节。
 
 ## 并行执行
 
-每次调度前检查依赖与当前工作树。**有两个以上可独立推进、不会互相干扰的任务且环境提供 subagent 能力时，启动多个 subagents 并发完成**；主 agent 同时处理不与它们冲突的任务或集成准备。不要只写“可以并行”却仍全部串行，也不要为了凑数量拆出无意义任务。
+每次调度前检查依赖与当前工作树。有独立任务、工具可用且并行收益超过委派与集成成本时，使用 subagents；主 agent 处理不冲突的任务或集成准备。小任务直接完成，不为凑数量拆任务。
 
 ### 哪些任务可同时启动
 
-- 前置成果已通过所需验收，输入/接口契约已稳定；同一里程碑内或不同里程碑之间都可并行，编号本身不是依赖。
+- 前置成果已通过所需检查，输入/接口契约已稳定；依赖落到实际成果与检查 ID，不默认等待上游里程碑全部终验。数据/安全/发布风险门及用户约定的分期门不能绕过。
+- 区分开发、集成和终验前置：稳定契约下可先用 fixture 开发；真实接口可用后再联调，同环境的 API/UI 主路径集中走查。局部检查通过不代替阶段终验，集成与评测放明确的收口里程碑负责。
 - 写入的文件集合互不重叠，不会在另一个任务仍依赖的文件中改接口/导出/行为。共享类型、公共入口、锁文件、生成产物和迁移序号指定一个负责人，先确定契约或串行集成。
 - 测试和运行资源互不影响：共享数据库、种子/迁移、端口、开发栈重启、同一浏览器会话或外部环境写入需隔离或串行。独立 worktree 只能隔离文件，不能自动隔离这些资源。
 - 无法证明独立就先串行完成前置或重新划界。用户要求串行、工具不可用或资源受限时如实说明，按可用并发数调度，其余串行，不虚构已启动的 subagents。
 
 ### 委派、交付与集成
 
-主 agent 给每个 subagent 一份精简任务说明：目标及计划章节/需求 ID、已稳定契约、允许写入与禁止修改的路径、可用运行资源、验收条件、独立记录路径、需回报的阻塞。不复制整段聊天或无关历史；工具支持时选择最小上下文，让 subagent 按需读取规则和相关文件。
+主 agent 给每个 subagent 一份精简任务说明：目标及章节/需求/检查 ID、已稳定契约、可写与禁改路径、运行资源、需回报的阻塞。不复制整段聊天或无关历史；工具支持时选择最小上下文，让 subagent 按需读取规则和相关文件。
 
 **模型默认继承**：如无特别要求，subagent 使用与主 agent 相同的模型。启动工具支持继承时省略模型覆盖参数；必须显式指定时填写主 agent 的模型。只有用户或适用指令明确要求其他模型时才覆盖，不自行因任务难度、成本或速度降级/换模型。
 
-每个文件同一时间只有一个写入者。**计划与里程碑汇总记录由主 agent 单写**；subagent 将详情写入各自的 `<计划名>.records/M<n>-<任务名>.md`，返回简要结果、改动路径、验证结论、缺口与记录链接。任务结束、阻塞或暂停时及时交付；不得替其他 agent 修改文件或回滚他人改动。边界变化先回报，主 agent 调整分工后再继续。
+每个文件同一时间只有一个写入者。**计划与里程碑记录由主 agent 单写**；subagent 返回结果、改动路径、验证命令/环境/基线/结果与缺口，主 agent 归入对应记录，默认不另建任务文件。复杂交接或证据确需独立保存时才指定任务记录路径并链接。任务结束、阻塞或暂停时及时交付；不得替其他 agent 修改文件或回滚他人改动。边界变化先回报，主 agent 调整分工后再继续。
 
-主 agent 逐项审查交付与当前 diff，按需读取相关任务记录，整合成果并完成里程碑所需的集成/回归验证；局部测试全绿不能替代集成验收。有任务失败就保留已交付成果，阻塞依赖它的任务，无关任务可继续。每个里程碑验收完成后立即独立回写，不能等所有 subagents 都结束。结束对话前收集或停止尚在运行的任务，记录可接续状态，不留下无人管理的写入任务。
+主 agent 审查交付与 diff，完成里程碑规定的检查；已通过且相关代码、配置、依赖、输入与环境未变的证据可引用，受影响检查重跑，收口仍做必要集成回归。有任务失败则保留成果，只阻塞依赖任务。里程碑完成立即回写，下游只需部分成果时保存其前置检查证据即可推进。结束对话前收集或停止尚在运行的任务，记录可接续状态。