工作流强制执行技能 - 确保AI代理完整执行开发流程步骤

workflow-enforcement by rysweet/amplihack

93 周安装量

44 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/rysweet/amplihack --skill workflow-enforcement

项目管理自动化代码规范

🇨🇳中文介绍

工作流强制执行技能

目的

引导 Claude 完成所有工作流步骤，通过：

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

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

Claude 自我遵守（当前状态）
未来：预提交钩子或 CI 检查（尚未实施）

问题（Issue #1607）

代理经常跳过强制性的工作流步骤，尤其是：

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

根本原因：

完成偏见：代理将“PR 已创建”视为完成，而不是“审查后 PR 已合并”
上下文衰减：经过大量实施后，代理忽略了剩余的步骤
自主性误用：混淆了“自主实施”与“跳过强制流程”

理念对齐与诚实局限性

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

135,700 周安装

GitHub Actions 官方文档查询助手 - 精准解答 CI/CD 工作流问题

45,200 周安装

开源项目教练指南 - 诊断问题、制定行动计划、优化开源项目运营

45,100 周安装

原则	此技能如何对齐
极致简洁	单一 YAML 文件用于状态；无复杂基础设施
零废话实施	诚实说明是指导，而非强制执行
模块化设计	自包含技能，具有清晰的集成点
故障开放	出错时记录并继续；绝不阻塞用户

+------------------------------------------------------------------+
|  检查点：PR 前验证                                                |
+------------------------------------------------------------------+
|  [ ] 步骤 10：预提交代码审查                                     |
|      状态：???（检查您的 TodoWrite/YAML 状态）                   |
|                                                                  |
|  如果步骤 10 未完成：                                            |
|  - 停止：不要继续到步骤 15                                       |
|  - 操作：调用审查代理进行代码审查                                |
|  - 操作：调用安全代理进行安全审查                                |
|  - 然后返回此处并验证完成情况                                    |
+------------------------------------------------------------------+

+------------------------------------------------------------------+
|  检查点：最终验证                                                 |
+------------------------------------------------------------------+
|  [ ] 步骤 10：预提交代码审查                                     |
|  [ ] 步骤 16：PR 审查                                            |
|  [ ] 步骤 17：审查反馈实施                                       |
|                                                                  |
|  所有强制步骤必须在步骤 21 之前完成。                            |
|  检查您的 TodoWrite/YAML 状态以获取状态。                        |
+------------------------------------------------------------------+

+======================================================================+
|                    默认工作流 - 进度                                  |
+======================================================================+
| 任务：添加身份验证功能                                               |
| 会话：session_20251125_143022                                        |
| 开始时间：2025-11-25T14:30:22                                        |
+----------------------------------------------------------------------+
|  进度：10/22 步骤 (45%)                                              |
|  [##########............] 10/22                                       |
+----------------------------------------------------------------------+
|  已完成 (10)：                                                       |
|    0, 1, 2, 3, 4, 5, 6, 7, 8, 9                                      |
|                                                                      |
|  当前：                                                              |
|    >> 步骤 10：预提交代码审查（强制） <<                              |
|                                                                      |
|  剩余 (12)：                                                         |
|    11, 12, 13, 14, 15, *16*, *17*, 18, 19, 20, 21                   |
|    (* = 强制)                                                        |
+----------------------------------------------------------------------+
|  强制关卡：                                                          |
|    [X] 步骤 0  - 工作流准备          已完成                          |
|    [ ] 步骤 10 - 预提交审查          进行中                          |
|    [ ] 步骤 16 - PR 审查             待处理                          |
|    [ ] 步骤 17 - 反馈实施            待处理                          |
+======================================================================+

workflow_id: "session_20251125_143022"
workflow_name: DEFAULT
task_description: "添加身份验证功能"
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" }
  # ... 步骤 2-9 ...
  10: { status: in_progress, mandatory: true }
  # ... 步骤 11-15 ...
  16: { status: pending, mandatory: true }
  17: { status: pending, mandatory: true }
  # ... 步骤 18-21 ...

mandatory_steps: [0, 10, 16, 17]

checkpoints:
  before_step_15:
    required_steps: [10]
    error_message: "未完成步骤 10 无法打开 PR"
  before_step_21:
    required_steps: [10, 16, 17]
    error_message: "未完成所有强制审查无法标记为可合并"

# 在 power_steering_checker.py 中（未来）
def _check_dev_workflow_complete(self, transcript, session_id):
    # 检查 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  # 强制步骤未完成

        return True  # 所有强制步骤已完成

    # 回退到启发式分析
    return self._check_workflow_heuristics(transcript)

TodoWrite(todos=[
    {"content": "步骤 0：工作流准备 - 为所有步骤创建待办事项", "status": "completed", "activeForm": "创建步骤待办事项"},
    {"content": "步骤 10：预提交代码审查 - 强制", "status": "in_progress", "activeForm": "审查代码"},
    {"content": "步骤 16：PR 审查 - 强制", "status": "pending", "activeForm": "审查 PR"},
    {"content": "步骤 17：实施审查反馈 - 强制", "status": "pending", "activeForm": "实施反馈"},
])

+======================================================================+
|                    工作流强制执行：已阻塞                              |
+======================================================================+
|                                                                      |
|  无法继续到步骤 15（以草稿形式打开 PR）。                            |
|                                                                      |
|  缺少的强制步骤：                                                    |
|    步骤 10：预提交代码审查                                           |
|                                                                      |
|  为什么这很重要：                                                    |
|    - 代码审查在错误到达 CI 之前捕获它们                              |
|    - 理念遵守确保质量                                                |
|    - Issue #1607 将此识别为反复出现的问题                            |
|                                                                      |
|  所需操作：                                                          |
|    1. 调用审查代理进行全面代码审查                                  |
|    2. 调用安全代理进行安全审查                                      |
|    3. 在 TodoWrite 中将步骤 10 标记为已完成                          |
|    4. 然后继续到步骤 15                                              |
|                                                                      |
+======================================================================+

# .github/workflows/ci.yml（未来）
- name: 验证工作流合规性
  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'失败：强制步骤 {step} 未完成')
            exit(1)
    print('通过：所有强制工作流步骤已完成')
    "

🇺🇸English

Workflow Enforcement Skill

Purpose

Guides Claude to complete all workflow steps by:

Reminding about step completion tracking (use TodoWrite or ~/.amplihack/.claude/runtime/workflow_state.yaml)
Emphasizing mandatory steps (0, 10, 16-17) that must not be skipped
Providing visual progress indicator format
Defining expected blocking behavior at checkpoints

Implementation Status : This skill is currently a SPECIFICATION that guides Claude behavior. Actual blocking enforcement requires either:

Claude self-compliance (current state)
Future: Pre-commit hooks or CI checks (not yet implemented)

The Problem (Issue #1607)

Agents routinely skip mandatory workflow steps, especially:

Step 0 : Workflow Preparation - Create todos for ALL steps (MANDATORY)
Step 10 : Pre-commit code review (MANDATORY)
Step 16 : PR review (MANDATORY)
Step 17 : Review feedback implementation (MANDATORY)

Root causes:

Completion Bias : Agent considers "PR created" as completion instead of "PR merged after review"
Context Decay : After heavy implementation, agent loses sight of remaining steps
Autonomy Misapplication : Confuses "autonomous implementation" with "skip mandatory process"

Philosophy Alignment and Honest Limitations

The Irony

This skill was created because an agent skipped workflow steps while building a feature. The same cognitive patterns that cause step-skipping can also cause this skill to be ignored. We acknowledge this limitation directly.

What This Skill CAN Do

Provide clear guidance patterns for Claude to follow
Define standard formats for progress tracking
Establish checkpoints where Claude SHOULD pause and validate
Integrate with power_steering for session-end verification
Document the expected behavior for future agents

What This Skill CANNOT Do

Force Claude to read this skill (relies on auto-activation triggers)
Prevent Claude from skipping steps if it "decides" to be autonomous
Hard-block operations (no pre-commit hooks implemented yet)
Catch workflow violations in real-time (only session-end checks exist)

Philosophy Alignment

Principle	How This Skill Aligns
Ruthless Simplicity	Single YAML file for state; no complex infrastructure
Zero-BS Implementation	Honest about being guidance, not enforcement
Modular Design	Self-contained skill with clear integration points
Fail-Open	On errors, log and continue; never block users

Self-Aware Note : This skill is itself a brick that could be regenerated from its specification. It does not contain executable code - it is documentation that guides Claude's behavior through loaded context.

How to Use This Skill

Step-by-Step Instructions

At Workflow Start (Step 0)

Initialize state tracking (choose one):

Option A - TodoWrite (Recommended) :

    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"

Option B - YAML state file :

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

2. Display initial progress :

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

3. Verify initialization : Confirm 22 todo items exist before proceeding.

At Each Step Completion

Mark step as completed in TodoWrite or YAML
Update current_step to next step number
Display progress indicator
If approaching mandatory step (10, 16, 17), display reminder

At Mandatory Checkpoints

Before Step 15 (Open PR as Draft) :

+------------------------------------------------------------------+
|  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                       |
+------------------------------------------------------------------+

Before Step 21 (Ensure Mergeable) :

+------------------------------------------------------------------+
|  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.                    |
+------------------------------------------------------------------+

At Workflow End

Verify all steps completed (or explicitly skipped with documented reason)
Final progress: [######################] 22/22 Steps Complete
Delete ~/.amplihack/.claude/runtime/workflow_state.yaml if used
Log completion to workflow_tracker.py

Visual Progress Formats

Standard Progress Bar

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

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

Detailed Status Display

+======================================================================+
|                    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                   |
+======================================================================+

Compact Status (For Updates)

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

State File Format

Template Location : ~/.amplihack/.claude/templates/workflow_state.yaml.template Active State Location : ~/.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"

Integration with Power Steering

Power steering provides session-end verification through the dev_workflow_complete consideration in considerations.yaml.

How It Works

During Session : This skill provides guidance; Claude should track steps in TodoWrite
At Session End : Power steering's _check_dev_workflow_complete analyzes the transcript
Heuristics Used :
- Were architect, builder, reviewer agents invoked?
- Were tests executed (Bash tool usage)?
- Were git operations performed?
Result : Blocks session completion if workflow evidence is missing

Integration Points

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"]

Current Limitation : Power steering checks for evidence of workflow (agent usage, test runs) but does NOT read workflow_state.yaml. This is a future enhancement opportunity.

Proposed Enhancement (Not Yet Implemented)

# 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)

Integration with TodoWrite

When using TodoWrite, ensure step numbers match workflow tracking:

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"},
])

Key Point : TodoWrite is the primary tracking mechanism. YAML state file is optional for additional persistence and structured validation.

Blocking Behavior (Self-Compliance Pattern)

When mandatory steps are skipped, Claude SHOULD display and follow this pattern:

+======================================================================+
|                    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                                        |
|                                                                      |
+======================================================================+

Error Recovery

If state file is missing or corrupt:

Check TodoWrite for current step information
Reconstruct state from conversation context
If unrecoverable, prompt user to confirm current step
Always fail-open: continue with warning rather than blocking

Future Work: Path to Hard Enforcement

Phase 1: Current State (Guidance Only)

Skill provides documentation and patterns
Claude self-compliance determines effectiveness
Power steering provides session-end warnings

Phase 2: Enhanced Power Steering (Planned)

Power steering reads workflow_state.yaml
Real-time validation at checkpoint steps
More granular dev_workflow_complete checks

Phase 3: Pre-Commit Integration (Future)

# .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

Phase 4: CI Gate (Future)

# .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')
    "

Related Components

DEFAULT_WORKFLOW.md : Canonical workflow definition with Step 0 guidance
templates/workflow_state.yaml.template : Template for structured state tracking
workflow_tracker.py : Historical logging (JSONL format)
power_steering_checker.py : Session-end enforcement (transcript-based)
considerations.yaml : dev_workflow_complete consideration definition

Weekly Installs

Repository

rysweet/amplihack

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode80

codex74

cursor74

claude-code74

gemini-cli73

github-copilot71

工作流强制执行技能 - 确保AI代理完整执行开发流程步骤

🇨🇳中文介绍

工作流强制执行技能

目的

问题（Issue #1607）

理念对齐与诚实局限性

相关 Skills

讽刺之处

此技能能做什么

此技能不能做什么

理念对齐

如何使用此技能

分步说明

工作流开始时（步骤 0）

每个步骤完成时

在强制检查点

工作流结束时

可视化进度格式

标准进度条

详细状态显示

紧凑状态（用于更新）

状态文件格式

与 Power Steering 集成

工作原理

集成点

建议的增强功能（尚未实施）

与 TodoWrite 集成

阻塞行为（自我遵守模式）

错误恢复

未来工作：硬性执行之路

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

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

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

阶段 4：CI 关卡（未来）

相关组件