workflow-enforcement

工作流强制执行技能

用途

指导 Claude 完成所有工作流步骤，方法如下：

1. 提醒跟踪步骤完成情况（使用 TodoWrite 或 ~/.amplihack/.claude/runtime/workflow_state.yaml）
2. 强调不得跳过的强制步骤（0、10、16-17）
3. 提供可视化进度指示器格式
4. 定义检查点处预期的阻塞行为

实施状态：此技能目前是一份指导 Claude 行为的规范。实际的阻塞强制执行需要以下方式之一：

• Claude 自行遵守（当前状态）
• 未来：Pre-commit 钩子或 CI 检查（尚未实现）

问题所在（Issue #1607）

Agent 经常跳过强制工作流步骤，尤其是：

• 步骤 0：工作流准备 — 为所有步骤创建待办事项（强制）
• 步骤 10：提交前代码审查（强制）
• 步骤 16：PR 审查（强制）
• 步骤 17：落实审查反馈（强制）

根本原因：

• 完成偏见：Agent 将“已创建 PR”视为完成，而非“经审查后 PR 已合并”
• 上下文衰减：完成大量实现工作后，Agent 会忽视剩余步骤
• 自主性误用：将“自主实现”误解为“跳过强制流程”

与理念的一致性及诚实说明限制

讽刺之处

此技能的创建缘于某个 Agent 在构建功能时跳过了工作流步骤。导致跳过步骤的相同认知模式，也可能导致此技能被忽略。我们坦诚承认这一限制。

此技能可以做什么

• 提供明确的指导模式，供 Claude 遵循
• 定义进度跟踪的标准格式
• 设立检查点，让 Claude 应当暂停并验证
• 与 power_steering 集成，以便在会话结束时进行验证
• 记录预期行为，供未来的 Agent 参考

此技能无法做什么

• 强制 Claude 阅读此技能（依赖自动激活触发器）
• 阻止 Claude 在“决定”自主行事时跳过步骤
• 硬性阻止操作（目前尚未实现 pre-commit 钩子）
• 实时捕获工作流违规（目前只有会话结束检查）

与理念的一致性

原则	此技能如何与之保持一致
极致简洁	使用单个 YAML 文件保存状态；不引入复杂基础设施
拒绝虚假宣传	坦诚说明这是指导，而非强制执行
模块化设计	技能自成一体，集成点明确
失败时放行	发生错误时记录日志并继续；绝不阻止用户

自我认知说明：此技能本身也是一块可根据规范重新生成的构件。它不包含可执行代码，而是通过加载的上下文指导 Claude 行为的文档。

如何使用此技能

分步说明

工作流开始时（步骤 0）

1. 初始化状态跟踪（任选一种）：

   选项 A — TodoWrite（推荐）：

   Create TodoWrite entries for ALL 22 steps (0-21):
   - "Step 0: Workflow Preparation - Create todos for ALL steps"
   - "Step 1: Prepare the Workspace"
   - ...
   - "Step 21: Ensure PR is Mergeable - TASK COMPLETION"
   

   选项 B — YAML 状态文件：

   cp .claude/templates/workflow_state.yaml.template \
      .claude/runtime/workflow_state.yaml
   # Edit workflow_id, task_description, started_at
   

2. 显示初始进度：

   WORKFLOW PROGRESS [0/22] [.......................] Step 0: Workflow Preparation
   Mandatory gates: Step 0 (Prep), Step 10 (Review), Step 16 (PR Review), Step 17 (Feedback)
   

3. 确认初始化：继续之前，确认存在 22 项待办事项。

完成每个步骤时

1. 在 TodoWrite 或 YAML 中将步骤标记为 completed
2. 将 current_step 更新为下一步骤的编号
3. 显示进度指示器
4. 临近强制步骤（10、16、17）时，显示提醒

在强制检查点

步骤 15 之前（以草稿形式创建 PR）：

+------------------------------------------------------------------+
|  CHECKPOINT: Pre-PR Validation                                   |
+------------------------------------------------------------------+
|  [ ] Step 10: Pre-commit code review                            |
|      Status: ??? (check your TodoWrite/YAML state)              |
|                                                                  |
|  If Step 10 is NOT completed:                                    |
|  - STOP: Do not proceed to Step 15                              |
|  - ACTION: Invoke reviewer agent for code review                |
|  - ACTION: Invoke security agent for security review            |
|  - Then return here and verify completion                       |
+------------------------------------------------------------------+

步骤 21 之前（确保可合并）：

+------------------------------------------------------------------+
|  CHECKPOINT: Final Validation                                    |
+------------------------------------------------------------------+
|  [ ] Step 10: Pre-commit code review                            |
|  [ ] Step 16: PR review                                         |
|  [ ] Step 17: Review feedback implementation                    |
|                                                                  |
|  ALL mandatory steps must be completed before Step 21.          |
|  Check your TodoWrite/YAML state for status.                    |
+------------------------------------------------------------------+

工作流结束时

1. 确认所有步骤均已完成（或已明确跳过并记录原因）
2. 最终进度：[######################] 22/22 Steps Complete
3. 如果使用了 ~/.amplihack/.claude/runtime/workflow_state.yaml，则将其删除
4. 将完成情况记录到 workflow_tracker.py

可视化进度格式

标准进度条

WORKFLOW: DEFAULT_WORKFLOW v1.1.0
PROGRESS: [##########............] 10/22 (45%)

Current: Step 10 - Pre-commit code review (MANDATORY)
Next: Step 11 - Incorporate Review Feedback

详细状态显示

+======================================================================+
|                    DEFAULT WORKFLOW - Progress                        |
+======================================================================+
| Task: Add authentication feature                                     |
| Session: session_20251125_143022                                     |
| Started: 2025-11-25T14:30:22                                         |
+----------------------------------------------------------------------+
|  Progress: 10/22 steps (45%)                                         |
|  [##########............] 10/22                                       |
+----------------------------------------------------------------------+
|  COMPLETED (10):                                                     |
|    0, 1, 2, 3, 4, 5, 6, 7, 8, 9                                      |
|                                                                      |
|  CURRENT:                                                            |
|    >> Step 10: Pre-commit code review (MANDATORY) <<                 |
|                                                                      |
|  REMAINING (12):                                                     |
|    11, 12, 13, 14, 15, *16*, *17*, 18, 19, 20, 21                   |
|    (* = mandatory)                                                   |
+----------------------------------------------------------------------+
|  MANDATORY GATES:                                                    |
|    [X] Step 0  - Workflow Preparation      COMPLETED                 |
|    [ ] Step 10 - Pre-commit Review         IN PROGRESS               |
|    [ ] Step 16 - PR Review                 PENDING                   |
|    [ ] Step 17 - Feedback Implementation   PENDING                   |
+======================================================================+

精简状态（用于更新）

[10/22] Step 10 (MANDATORY) | Gates: 0[X] 10[>] 16[ ] 17[ ]

状态文件格式

模板位置：~/.amplihack/.claude/templates/workflow_state.yaml.template 活动状态位置：~/.amplihack/.claude/runtime/workflow_state.yaml

workflow_id: "session_20251125_143022"
workflow_name: DEFAULT
task_description: "Add authentication feature"
started_at: "2025-11-25T14:30:22"
current_step: 10

steps:
  0: { status: completed, timestamp: "2025-11-25T14:30:22", mandatory: true }
  1: { status: completed, timestamp: "2025-11-25T14:31:05" }
  # ... steps 2-9 ...
  10: { status: in_progress, mandatory: true }
  # ... steps 11-15 ...
  16: { status: pending, mandatory: true }
  17: { status: pending, mandatory: true }
  # ... steps 18-21 ...

mandatory_steps: [0, 10, 16, 17]

checkpoints:
  before_step_15:
    required_steps: [10]
    error_message: "Cannot open PR without completing Step 10"
  before_step_21:
    required_steps: [10, 16, 17]
    error_message: "Cannot mark mergeable without all mandatory reviews"

与 Power Steering 集成

Power Steering 通过 considerations.yaml 中的 dev_workflow_complete 检查项提供会话结束验证。

工作原理

1. 会话期间：此技能提供指导；Claude 应在 TodoWrite 中跟踪步骤
2. 会话结束时：Power Steering 的 _check_dev_workflow_complete 会分析对话记录
3. 使用的启发式规则：
   • 是否调用了 architect、builder 和 reviewer Agent？
   • 是否执行了测试（使用 Bash 工具）？
   • 是否执行了 Git 操作？
4. 结果：如果缺少工作流证据，则阻止完成会话

集成点

considerations.yaml
==================
- id: dev_workflow_complete
  category: Workflow Process Adherence
  question: Was full DEFAULT_WORKFLOW followed?
  severity: blocker
  checker: _check_dev_workflow_complete
  applicable_session_types: ["DEVELOPMENT"]

当前限制：Power Steering 会检查工作流证据（Agent 使用情况、测试运行），但不会读取 workflow_state.yaml。这是未来可改进的方向。

提议的改进（尚未实现）

# In power_steering_checker.py (future)
def _check_dev_workflow_complete(self, transcript, session_id):
    # Check for workflow_state.yaml
    state_file = Path(".claude/runtime/workflow_state.yaml")
    if state_file.exists():
        state = yaml.safe_load(state_file.read_text())
        mandatory = state.get("mandatory_steps", [0, 10, 16, 17])
        steps = state.get("steps", {})

        for step_num in mandatory:
            step = steps.get(step_num, {})
            if step.get("status") != "completed":
                return False  # Mandatory step incomplete

        return True  # All mandatory steps completed

    # Fall back to heuristic analysis
    return self._check_workflow_heuristics(transcript)

与 TodoWrite 集成

使用 TodoWrite 时，请确保步骤编号与工作流跟踪一致：

TodoWrite(todos=[
    {"content": "Step 0: Workflow Preparation - Create todos for ALL steps", "status": "completed", "activeForm": "Creating step todos"},
    {"content": "Step 10: Pre-commit code review - MANDATORY", "status": "in_progress", "activeForm": "Reviewing code"},
    {"content": "Step 16: PR review - MANDATORY", "status": "pending", "activeForm": "Reviewing PR"},
    {"content": "Step 17: Implement review feedback - MANDATORY", "status": "pending", "activeForm": "Implementing feedback"},
])

要点：TodoWrite 是主要的跟踪机制。YAML 状态文件是可选的，可用于额外持久化和结构化验证。

阻止行为（自我遵循模式）

跳过强制步骤时，Claude SHOULD 显示并遵循以下模式：

+======================================================================+
|                    WORKFLOW ENFORCEMENT: BLOCKED                      |
+======================================================================+
|                                                                      |
|  Cannot proceed to Step 15 (Open PR as Draft).                       |
|                                                                      |
|  MISSING MANDATORY STEP:                                             |
|    Step 10: Pre-commit code review                                   |
|                                                                      |
|  WHY THIS MATTERS:                                                   |
|    - Code review catches bugs before they reach CI                   |
|    - Philosophy compliance ensures quality                           |
|    - Issue #1607 identified this as a recurring problem              |
|                                                                      |
|  ACTION REQUIRED:                                                    |
|    1. Invoke reviewer agent for comprehensive code review            |
|    2. Invoke security agent for security review                      |
|    3. Mark Step 10 as completed in TodoWrite                         |
|    4. Then proceed to Step 15                                        |
|                                                                      |
+======================================================================+

错误恢复

如果状态文件缺失或损坏：

1. 检查 TodoWrite，了解当前步骤信息
2. 根据对话上下文重建状态
3. 如果无法恢复，请提示用户确认当前步骤
4. 始终采用开放失败策略：发出警告后继续，而不是阻止操作

未来工作：实现强制执行的路径

阶段 1：当前状态（仅提供指导）

• 技能提供文档和模式
• 效果取决于 Claude 是否自我遵循
• Power Steering 提供会话结束警告

阶段 2：增强 Power Steering（计划中）

• Power Steering 读取 workflow_state.yaml
• 在检查点步骤进行实时验证
• 更精细地检查 dev_workflow_complete

阶段 3：提交前集成（未来）

# .pre-commit-config.yaml (future)
- repo: local
  hooks:
    - id: workflow-validation
      name: Validate workflow completion
      entry: python .claude/tools/amplihack/validate_workflow.py
      language: system
      pass_filenames: false

阶段 4：CI 门禁（未来）

# .github/workflows/ci.yml (future)
- name: Validate Workflow Compliance
  run: |
    python -c "
    from pathlib import Path
    import yaml
    state = yaml.safe_load(Path('.claude/runtime/workflow_state.yaml').read_text())
    mandatory = state.get('mandatory_steps', [0, 10, 16, 17])
    for step in mandatory:
        if state['steps'].get(step, {}).get('status') != 'completed':
            print(f'FAIL: Mandatory step {step} not completed')
            exit(1)
    print('PASS: All mandatory workflow steps completed')
    "

相关组件

• DEFAULT_WORKFLOW.md：规范工作流定义，包含步骤 0 指南
• templates/workflow_state.yaml.template：用于结构化状态跟踪的模板
• workflow_tracker.py：历史记录（JSONL 格式）
• power_steering_checker.py：会话结束时的强制检查（基于对话记录）
• considerations.yaml：dev_workflow_complete 检查项定义