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 - 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.
At Each Step Completion
- Mark step as
completedin TodoWrite or YAML - Update
current_stepto 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.yamlif 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 FeedbackDetailed 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_completeanalyzes 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_completechecks
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: falsePhase 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_completeconsideration definition