workflow-enforcement
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWorkflow Enforcement Skill
工作流强制合规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)
通过以下方式引导Claude完成所有工作流步骤:
- 提醒进行步骤完成追踪(使用TodoWrite或)
~/.amplihack/.claude/runtime/workflow_state.yaml - 强调不可跳过的强制步骤(0、10、16-17)
- 提供可视化进度指示器格式
- 定义检查点处的预期阻塞行为
实施状态:该Skill目前是指导Claude行为的规范文档。实际的阻塞强制需要通过以下方式实现:
- Claude自我合规(当前状态)
- 未来:Pre-commit hooks或CI检查(尚未实现)
The Problem (Issue #1607)
问题(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"
Agent经常会跳过强制工作流步骤,尤其是:
- 步骤0:工作流准备 - 为所有步骤创建待办事项(强制)
- 步骤10:预提交代码审查(强制)
- 步骤16:PR审查(强制)
- 步骤17:审查反馈落地(强制)
根本原因:
- 完成偏差:Agent将“PR已创建”视为完成,而非“PR经审查后合并”
- 上下文衰减:在大量实现工作后,Agent会忽略剩余步骤
- 自主性误用:将“自主实现”混淆为“跳过强制流程”
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.
创建该Skill的原因是某个Agent在构建功能时跳过了工作流步骤。导致步骤跳过的认知模式,同样可能导致该Skill被忽略。我们直接承认这一局限性。
What This Skill CAN Do
该Skill能实现的功能
- 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
- 为Claude提供清晰的指导模式
- 定义进度追踪的标准格式
- 建立Claude应暂停并验证的检查点
- 与power_steering集成,用于会话结束验证
- 为未来的Agent记录预期行为
What This Skill CANNOT Do
该Skill无法实现的功能
- 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)
- 强制Claude阅读该Skill(依赖自动激活触发器)
- 若Claude“决定”自主操作,无法阻止其跳过步骤
- 硬阻塞操作(尚未实现Pre-commit hooks)
- 实时捕捉工作流违规(仅存在会话结束检查)
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.
| 原则 | 该Skill的对齐方式 |
|---|---|
| 极致简洁 | 单一YAML文件存储状态;无复杂基础设施 |
| 零冗余实现 | 坦诚说明自身仅为指导,而非强制机制 |
| 模块化设计 | 独立封装的Skill,具备清晰的集成点 |
| 故障开放 | 出错时记录日志并继续;绝不阻塞用户 |
自我认知说明:该Skill本身是可从其规范重新生成的组件。它不包含可执行代码——是通过加载上下文来指导Claude行为的文档。
How to Use This Skill
如何使用该Skill
Step-by-Step Instructions
分步说明
At Workflow Start (Step 0)
工作流启动时(步骤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:bashcp .claude/templates/workflow_state.yaml.template \ .claude/runtime/workflow_state.yaml # Edit workflow_id, task_description, started_at -
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) -
Verify initialization: Confirm 22 todo items exist before proceeding.
-
初始化状态追踪(二选一):选项A - TodoWrite(推荐):
为全部22个步骤(0-21)创建TodoWrite条目: - "步骤0:工作流准备 - 为所有步骤创建待办事项" - "步骤1:准备工作区" - ... - "步骤21:确保PR可合并 - 任务完成"选项B - YAML状态文件:bashcp .claude/templates/workflow_state.yaml.template \ .claude/runtime/workflow_state.yaml # 编辑workflow_id、task_description、started_at -
显示初始进度:
WORKFLOW PROGRESS [0/22] [.......................] 步骤0:工作流准备 强制关卡:步骤0(准备)、步骤10(审查)、步骤16(PR审查)、步骤17(反馈) -
验证初始化:确认存在22个待办事项后再继续。
At Each Step Completion
每个步骤完成时
- Mark step as in TodoWrite or YAML
completed - Update to next step number
current_step - Display progress indicator
- If approaching mandatory step (10, 16, 17), display reminder
- 在TodoWrite或YAML中标记步骤为
completed - 将更新为下一个步骤编号
current_step - 显示进度指示器
- 若即将到达强制步骤(10、16、17),显示提醒
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. |
+------------------------------------------------------------------+步骤15(以草稿形式打开PR)之前:
+------------------------------------------------------------------+
| CHECKPOINT: PR前验证 |
+------------------------------------------------------------------+
| [ ] 步骤10:预提交代码审查 |
| 状态:???(检查你的TodoWrite/YAML状态) |
| |
| 如果步骤10未完成: |
| - 停止:不要继续执行步骤15 |
| - 操作:调用reviewer agent进行代码审查 |
| - 操作:调用security agent进行安全审查 |
| - 然后返回此处验证完成状态 |
+------------------------------------------------------------------+步骤21(确保可合并)之前:
+------------------------------------------------------------------+
| CHECKPOINT: 最终验证 |
+------------------------------------------------------------------+
| [ ] 步骤10:预提交代码审查 |
| [ ] 步骤16:PR审查 |
| [ ] 步骤17:审查反馈落地 |
| |
| 所有强制步骤必须在步骤21前完成。 |
| 检查你的TodoWrite/YAML状态获取状态信息。 |
+------------------------------------------------------------------+At Workflow End
工作流结束时
- Verify all steps completed (or explicitly skipped with documented reason)
- Final progress:
[######################] 22/22 Steps Complete - Delete if used
~/.amplihack/.claude/runtime/workflow_state.yaml - Log completion to workflow_tracker.py
- 验证所有步骤已完成(或已记录理由并明确跳过)
- 最终进度:
[######################] 22/22 步骤完成 - 若使用了则删除该文件
~/.amplihack/.claude/runtime/workflow_state.yaml - 将完成情况记录到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 FeedbackWORKFLOW: DEFAULT_WORKFLOW v1.1.0
PROGRESS: [##########............] 10/22 (45%)
当前:步骤10 - 预提交代码审查(MANDATORY)
下一步:步骤11 - 整合审查反馈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 |
+======================================================================++======================================================================+
| DEFAULT WORKFLOW - 进度 |
+======================================================================+
| 任务:添加认证功能 |
| 会话: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:预提交代码审查(MANDATORY) << |
| |
| 剩余步骤(12个): |
| 11, 12, 13, 14, 15, *16*, *17*, 18, 19, 20, 21 |
| (* = 强制步骤) |
+----------------------------------------------------------------------+
| 强制关卡: |
| [X] 步骤0 - 工作流准备 已完成 |
| [ ] 步骤10 - 预提交审查 进行中 |
| [ ] 步骤16 - PR审查 待处理 |
| [ ] 步骤17 - 反馈落地 待处理 |
+======================================================================+Compact Status (For Updates)
紧凑状态(用于更新)
[10/22] Step 10 (MANDATORY) | Gates: 0[X] 10[>] 16[ ] 17[ ][10/22] 步骤10(MANDATORY) | 关卡:0[X] 10[>] 16[ ] 17[ ]State File Format
状态文件格式
Template Location:
Active State Location:
~/.amplihack/.claude/templates/workflow_state.yaml.template~/.amplihack/.claude/runtime/workflow_state.yamlyaml
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"模板位置:
活跃状态位置:
~/.amplihack/.claude/templates/workflow_state.yaml.template~/.amplihack/.claude/runtime/workflow_state.yamlyaml
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" }
# ... 步骤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: "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的集成
Power steering provides session-end verification through the consideration in .
dev_workflow_completeconsiderations.yamlPower Steering通过中的检查项提供会话结束验证。
considerations.yamldev_workflow_completeHow It Works
工作原理
- During Session: This skill provides guidance; Claude should track steps in TodoWrite
- At Session End: Power steering's analyzes the transcript
_check_dev_workflow_complete - 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
- 会话期间:该Skill提供指导;Claude应在TodoWrite中追踪步骤
- 会话结束时:Power Steering的分析对话记录
_check_dev_workflow_complete - 使用的启发式规则:
- 是否调用了architect、builder、reviewer agent?
- 是否执行了测试(Bash工具使用情况)?
- 是否执行了git操作?
- 结果:若缺少工作流证据,将阻止会话完成
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 . This is a future enhancement opportunity.
workflow_state.yamlconsiderations.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.yamlProposed Enhancement (Not Yet Implemented)
拟议增强(尚未实现)
python
undefinedpython
undefinedIn power_steering_checker.py (future)
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)undefineddef _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)undefinedIntegration with TodoWrite
与TodoWrite的集成
When using TodoWrite, ensure step numbers match workflow tracking:
python
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.
使用TodoWrite时,确保步骤编号与工作流追踪匹配:
python
TodoWrite(todos=[
{"content": "步骤0:工作流准备 - 为所有步骤创建待办事项", "status": "completed", "activeForm": "创建步骤待办"},
{"content": "步骤10:预提交代码审查 - MANDATORY", "status": "in_progress", "activeForm": "审查代码"},
{"content": "步骤16:PR审查 - MANDATORY", "status": "pending", "activeForm": "审查PR"},
{"content": "步骤17:落地审查反馈 - MANDATORY", "status": "pending", "activeForm": "落地反馈"},
])关键点:TodoWrite是主要的追踪机制。YAML状态文件是可选的,用于额外的持久化和结构化验证。
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 |
| |
+======================================================================+当强制步骤被跳过,Claude应显示并遵循以下模式:
+======================================================================+
| 工作流强制合规:已阻塞 |
+======================================================================+
| |
| 无法继续执行步骤15(以草稿形式打开PR)。 |
| |
| 缺失强制步骤: |
| 步骤10:预提交代码审查 |
| |
| 重要性: |
| - 代码审查在问题进入CI前捕获Bug |
| - 符合理念要求确保质量 |
| - Issue #1607已将此列为反复出现的问题 |
| |
| 所需操作: |
| 1. 调用reviewer agent进行全面代码审查 |
| 2. 调用security agent进行安全审查 |
| 3. 在TodoWrite中标记步骤10为已完成 |
| 4. 然后继续执行步骤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
若状态文件缺失或损坏:
- 检查TodoWrite获取当前步骤信息
- 从对话上下文重建状态
- 若无法恢复,提示用户确认当前步骤
- 始终故障开放:发出警告后继续,而非阻塞
Future Work: Path to Hard Enforcement
未来工作:硬强制的实现路径
Phase 1: Current State (Guidance Only)
阶段1:当前状态(仅指导)
- Skill provides documentation and patterns
- Claude self-compliance determines effectiveness
- Power steering provides session-end warnings
- Skill提供文档和模式
- Claude自我合规决定有效性
- Power Steering提供会话结束警告
Phase 2: Enhanced Power Steering (Planned)
阶段2:增强型Power Steering(已规划)
- Power steering reads workflow_state.yaml
- Real-time validation at checkpoint steps
- More granular checks
dev_workflow_complete
- Power Steering读取workflow_state.yaml
- 在检查点步骤进行实时验证
- 更细粒度的检查
dev_workflow_complete
Phase 3: Pre-Commit Integration (Future)
阶段3:Pre-commit集成(未来)
bash
undefinedbash
undefined.pre-commit-config.yaml (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
undefined- repo: local
hooks:
- id: workflow-validation name: Validate workflow completion entry: python .claude/tools/amplihack/validate_workflow.py language: system pass_filenames: false
undefinedPhase 4: CI Gate (Future)
阶段4:CI关卡(未来)
yaml
undefinedyaml
undefined.github/workflows/ci.yml (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') "
undefined- 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') "
undefinedRelated 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: consideration definition
dev_workflow_complete
- DEFAULT_WORKFLOW.md:包含步骤0指导的标准工作流定义
- templates/workflow_state.yaml.template:结构化状态追踪模板
- workflow_tracker.py:历史记录(JSONL格式)
- power_steering_checker.py:会话结束强制(基于对话记录)
- considerations.yaml:检查项定义
dev_workflow_complete