skill-pipeline

技能流程

协调者，而非执行者。此技能负责对任务进行分类、选择流程变体、校准深度，并协调技能之间的交接。它本身不会生成任何产物——其输出是用于激活其他技能的路由决策。

任务分类

每项编码任务开始前，都要先分类。评估范围信号并映射到任务类别。

**输入信号：**文件数量、任务描述、现有计划／交接文件、批处理指标、CI 环境。

Task received
  │
  ├─ Trivial (typo, rename, version bump)
  │  → No skills. Just do it.
  │
  ├─ Small (isolated fix, single-file, <10 logic lines)
  │  → verify-gate + simplify-and-harden
  │
  ├─ Medium (feature in known area, 2-5 files)
  │  → intent-framed-agent + session-context + verify-gate + simplify-and-harden
  │
  ├─ Large (complex refactor, new architecture, unfamiliar codebase, high-risk logic)
  │  → Full standard pipeline
  │  → Recommend /plan-interview before starting
  │
  ├─ Long-running (multi-session, high context pressure, prior handoff exists)
  │  → Full standard pipeline with context-surfing as critical skill
  │
  └─ Batch (multiple features from spec, 5+ discrete tasks, issue triage)
     → Orchestrated standard pipeline with bounded work units and independent audits

不确定时，从 Medium 开始。如果任务中途出现偏差或质量问题，再添加技能。

详细的启发式规则、边缘情况和示例，请阅读 references/classification-rules.md。

流程选择

将任务类别路由到相应的变体：

任务类别	变体	原因
Trivial	None	无需额外开销
Small	Standard (minimal)	仅需 Verify + S&H
Medium	Standard (partial)	Intent + 会话上下文 + Verify + Review
Large	Standard (full)	包含规划的完整内循环
Long-running	Standard (full)	上下文巡航至关重要
Batch	Orchestrated standard	将工作划分为有界单元，并为每个单元设置关卡
CI environment	CI	无头审查
Periodic	Outer loop	跨会话改进

**启发式规则：**深度和广度任务都使用 Standard 流程。对于批处理任务，将范围拆分为有界单元；只有在持久化的多会话协调可用且有帮助时，才使用 control-session-orchestrator。当 CI=true 或 GITHUB_ACTIONS=true 时，使用 CI 流程。

激活顺序

Standard Pipeline（内循环）

pre-flight-check (SessionStart hook — surfaces prior learnings + heals)
  → classify
  → (recommend /plan-interview if Large or Long-running)
  → intent-framed-agent (clarify material gaps; emit initial frame)
  → session-context (invoked by intent framing; bounded history retrieval)
  → finalize approach in the same intent frame
  → context-surfing (Large/Long-running or explicit high-context-pressure use; concurrent with intent monitoring)
  → [IMPLEMENTATION]
  → self-healing  ← inner-loop recovery primitive; called whenever a command/test/build/external call fails or a helper is missing.
  →                Diagnoses, patches, verifies, files HEAL- entry. Resumes when verified.
  → verify-gate (compile + test + lint; fix loop if red — fix loop calls self-healing)
  → simplify-and-harden (post-completion, if non-trivial diff)
  → self-improvement (on errors, corrections, S&H learning candidates, recurring heal handoffs)

按任务类别激活技能：

技能	Trivial	Small	Medium	Large	Long-running
pre-flight-check	Hook	Hook	Hook	Hook	Hook
plan-interview	-	-	-	Recommend	Recommend
intent-framed-agent	-	-	Activate	Activate	Activate
session-context	-	On request	After frame	After frame	After frame; resume 时复用
context-surfing	-	-	-	Activate	Critical
verify-gate	-	Activate	Activate	Activate	Activate
self-healing	失败时	失败时	失败时	失败时	失败时
simplify-and-harden	-	如非简单任务	如非简单任务	如非简单任务	如非简单任务
self-improvement	仅出错时	仅出错时	出错／完成时	出错／完成时	出错／完成时

intent-framed-agent 负责调用 session-context；这是按顺序执行的步骤， 而非两个彼此独立的触发器。缺少历史记录来源或没有有用的匹配结果， 都不得阻碍实现。恢复任务时，复用先前的发现；只有存在具体的新缺口时才检索。此路由是 Agent 遵循的指导，而非启动钩子。

Orchestrated Batch Pipeline（编排式批处理流程）

classify (Batch)
  → (recommend /plan-interview if no spec exists)
  → split the scope into bounded work units
  → control-session-orchestrator when persistent multi-session coordination is available
    ├─ each unit follows its appropriate standard-pipeline depth
    ├─ verify-gate after each implementation unit
    ├─ independent simplify, harden, and spec auditors review the combined result
    └─ verify-gate after audit-driven fixes
  → self-improvement

如果无法进行持久化编排，则按顺序处理相同的有界单元。即使无法并行执行， 也不得降低验证、审批或独立审查关卡的要求。

CI Pipeline（CI 流程）

classify (CI detected)
  → simplify-and-harden-ci (headless scan, PR changed files only)
  → self-improvement-ci (pattern aggregation, promotion recommendations)

Outer Loop Pipeline（外循环流程）

外循环跨会话运行，而非在单个会话内运行。按周期触发（每周、冲刺节点），或在 pre-flight-check 发现可晋升模式时触发。

learning-aggregator (read .learnings/, find patterns, rank promotion candidates)
  → self-improvement (human-approved promotions to project instructions)
  → eval-creator (create permanent test cases from promoted patterns)
  → eval-creator run (regression check on all existing evals)

触发外循环的时机：

• 每周：建议的最低频率
• 冲刺节点：一轮密集会话结束后
• 当 pre-flight-check 报告可晋升数量 > 3 时
• 发生重大事故或重复故障后
• 手动：用户调用 /learning-aggregator

外循环始终需要人工把关。learning-aggregator 会生成差距报告。主 Agent 遵循 self-improvement，在应用晋升前展示拟议差异并征求批准。未经人工审查，不得自动写入指令文件。

深度校准

不仅要确定使用哪些技能，还要确定每项技能的执行深度：

维度	小型	中型	大型	长时间运行	批处理
预检	Hook	Hook	Hook	Hook	Hook
规划轮次	0	0-1	1-2	深度迭代	按任务或统筹
意图框架	-	单一框架	完整框架 + 监控	完整框架 + 交接	统筹不变量 + 单元框架
会话上下文	按需	有界简报	有界简报	有界简报；恢复时复用	共享相关简报；仅补充单元级缺口
上下文游走	-	-	主动执行	至关重要（退出协议已就绪）	对每个大型/长时间运行的单元执行
验证门	编译 + 测试	编译 + 测试	编译 + 测试 + lint	编译 + 测试 + lint	单元级 + 综合结果
自愈	失败时（记录 HEAL 文件）	失败时（记录 HEAL 文件）	失败时 + 检查复发情况	失败时 + 检查复发情况	每个单元失败时
S&H 预算	20% 差异，60s	20% 差异，60s	20% 差异，60s	20% 差异，60s	每个非简单单元
独立审查	-	-	建议	必需	必须审查综合结果
自我改进	由错误触发	由错误触发	错误 + S&H 输入	错误 + S&H 输入	错误 + S&H 输入

交接规则

工件会在技能之间流转。编排器确保每项技能都能获得所需内容。

关键交接：

1. 计划文件（docs/plans/plan-NNN-<slug>.md）——由 plan-interview 生成，供 intent-framed-agent（上下文）、context-surfing（波次锚点）以及可选的 control-session-orchestrator 工作单元拆分使用。

2. 意图框架——由 intent-framed-agent 生成，首先供 session-context（用于检索的任务和范围）使用，然后供 context-surfing（强化波次锚点）使用。有用的历史信息可在同一框架中优化处理方法，但不能授权更改。上下文偏移退出时，会将其复制到交接文件中。

3. 交接文件（.context-surfing/handoff-[slug]-[timestamp].md）——由 context-surfing 在上下文偏移退出时生成，供下一会话恢复时使用。

4. 验证门信号——由 verify-gate 生成（通过/失败 + 诊断信息），供 simplify-and-harden 使用（仅在验证通过后启动），也供修复循环使用（失败时——verify-gate 将诊断信息交给自愈流程，由其诊断、修补并重新验证，然后通知 verify-gate 再次检查）。

5. HEAL 条目 + 工件（.learnings/HEALS.md、.learnings/heals/<HEAL-ID>/）——由 self-healing 生成，供 pre-flight-check（在会话开始时按 Pattern-Key / Active-Context 显示先前的修复）、learning-aggregator（跨会话复发分析）以及 self-improvement（当 Handoff 块在 Recurrence ≥ 3 时标记晋升）使用。

6. 学习候选项（learning_loop.candidates）——由 simplify-and-harden 生成，供 self-improvement 进行模式跟踪。

7. 学习条目（.learnings/*.md）——由 self-improvement 生成，供 learning-aggregator 进行跨会话分析，也供 pre-flight-check 在会话开始时使用。

8. 缺口报告——由 learning-aggregator 生成，供 self-improvement 进行经人工批准的晋升，以及供 eval-creator 生成测试用例。

9. 评估用例（.evals/cases/*.md）——由 eval-creator 生成，供回归运行使用，并由 pre-flight-check 显示。

**优先级：**如果 context-surfing 和 intent-framed-agent 同时触发，则以 context-surfing 的退出为准。上下文退化会使范围检查不可靠。

完整的工件/信号/预算表请参阅 references/handoff-matrix.md。

决策点

编排器会在以下时刻介入：

任务到达

对任务进行分类，选择流水线变体和深度，并输出路由决策。如果是大型/长时间运行的任务，建议使用 /plan-interview。如果是批处理，则定义有界工作单元，并且仅在宿主支持时建议进行编排。

计划审批

用户批准 plan-interview 中的计划后，直接进入执行阶段，不要另外询问“是否继续”。激活 intent-framed-agent 并输出忠实的意图框架，但复用对计划的批准，不要再次请求确认。仅当框架引入了实质性决策、假设或范围变更时才提问。使用清单项填充任务跟踪。

从计划过渡到执行

无论是否使用 plan-interview，对于明确的实现请求，都要激活 intent-framed-agent。只询问尚未解决的实质性决策，输出初始框架，并让意图框架调用一次 session-context。根据适用证据确定最终方案，同时保留当前批准状态和约束。不要一概设置框架确认关卡，也不要强制进行访谈。如果发现实质性冲突，则提问；否则继续实现。

实现中途失败

如果命令、测试、构建、lint 或外部调用在 verify-gate 运行之前失败（或出现其他任何任务中断情况，例如缺少辅助工具、环境漂移、API 变更），则转入 self-healing：诊断、修补、验证并记录 HEAL 条目。随后从当前可工作的状态继续执行。大多数修复都是对既有问题的再次处理——self-healing 会先按 Pattern-Key 搜索 HEALS.md。

实现完成

激活 verify-gate，运行编译、测试和 lint 检查。如果有任何检查失败，则转入 self-healing，进行诊断／修补／验证循环（每个阶段最多尝试 3 次）。每次修复后，verify-gate 都会重新运行检查。所有检查通过且差异达到非平凡阈值后（参见 references/classification-rules.md），激活 simplify-and-harden。如果差异很小，则在 verify-gate 检查通过后直接报告完成。

检测到漂移

如果 context-surfing 触发漂移退出，则停止执行。写入交接文件。如果任务被归类为低于 Large，可考虑在下一个会话中将其重新分类为更高等级。

恢复会话

检查 .context-surfing/ 中是否有待处理的交接文件。如果有，请完整读取相关文件。复用已批准的计划和意图；如果仍有实质性决策未解决，则重新分类（如有需要），并从建议的重新进入点继续。复用任何现有的 session-context 简报，不要在没有明确新缺口的情况下重复检索。只有重新进入成功后，才将交接标记为已处理。

覆盖项

用户可以覆盖任何路由决策：

• 强制指定深度： depth=small / depth=large — 覆盖分类
• 强制指定变体： variant=orchestrated / variant=standard — 覆盖流水线选择
• 跳过审查： --no-review — 跳过 simplify-and-harden
• 强制规划： 无论任务分类如何，都调用 /plan-interview
• 跳过所有技能： 对于非平凡任务，用户说“直接做”时，遵从此覆盖项

重新分类

任务可能在执行过程中改变类别。注意以下信号：

• 升级信号： 范围超出原估计、受影响的文件远多于预期、context-surfing 触发漂移退出、intent-framed-agent 检测到显著的范围变更
• 降级信号： 任务实际比计划简单、计划表明只需进行少量更改

需要重新分类时：

1. 说明触发重新分类的信号
2. 调整当前启用的技能（添加或移除流水线阶段）
3. 如果升级为 Large 且没有计划，则建议使用 /plan-interview
4. 如果降级，则移除不必要的阶段，改用更轻量的流水线继续执行

反模式

• 不要重新实现技能逻辑。 此技能负责分类和分派。每项技能各自负责其操作流程。
• 不要自动调用 plan-interview。 这是一个人工把关环节。可以推荐，但由用户决定。
• 不要创建第三层监控。 执行期间，intent-framed-agent 负责监控范围，context-surfing 负责监控质量。编排器只在决策点进行分派，然后不再干预。
• 不要覆盖各项技能的防护措施。 如果 simplify-and-harden 设有 20% 的预算上限，编排器就应遵守。
• 不要在琐碎任务中强制使用技能。 该流程旨在提供帮助，而不是拖慢简单工作。

流程变体详情

如需查看各变体的完整分步说明，包括混合场景和会话恢复，请阅读 references/pipeline-variants.md。