workflow-enforcement

What this skill does

# Workflow Enforcement Skill

## Purpose

Guides Claude to complete all workflow steps by:

1. Reminding about step completion tracking (use TodoWrite or `~/.amplihack/.claude/runtime/workflow_state.yaml`)
2. Emphasizing mandatory steps (0, 10, 16-17) that must not be skipped
3. Providing visual progress indicator format
4. 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)

1. **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**:

   ```bash
   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

1. Mark step as `completed` in TodoWrite or YAML
2. Update `current_step` to next step number
3. Display progress indicator
4. 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

1. Verify all steps completed (or explicitly skipped with documented reason)
2. Final progress: `[######################] 22/22 Steps Complete`
3. Delete `~/.amplihack/.claude/runtime/workflow_state.yaml` if used
4. 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                   |
|    [ ]