workflow-state-patterns
Hook-based state machine patterns for multi-phase workflows. Use when designing sequential workflows with quality gates.
When & Why to Use This Skill
This Claude skill provides a robust framework for implementing hook-based state machine patterns in multi-phase workflows. It enables developers to enforce sequential execution through quality gates and file-based state tracking, ensuring that AI agents follow a strict 'analyze-plan-execute-verify' lifecycle. By utilizing PreToolUse and PostToolUse hooks, it prevents common agent errors like skipping planning phases or failing to verify results, significantly increasing the reliability of complex automated tasks.
Use Cases
- Complex Code Refactoring: Enforcing a mandatory 'plan-approved' state before the agent is allowed to use write tools, ensuring architectural alignment.
- Automated CI/CD Pipelines: Using state files to track progress through build, test, and deploy phases, allowing for safe retries and session continuity if a step fails.
- Data Migration Workflows: Implementing quality gates that require a successful 'dry-run' and audit-pass marker before any production data is modified.
- Multi-Step Research Tasks: Orchestrating a flow where a 'search-complete' state must be achieved and verified before the agent proceeds to the summarization and reporting phase.
| name | workflow-state-patterns |
|---|---|
| description | Hook-based state machine patterns for multi-phase workflows. Use when designing sequential workflows with quality gates. |
| allowed-tools | ["Read", "Write", "Grep", "Glob"] |
Workflow State Patterns
Multi-phase workflows need phase enforcement, session continuity, and quality gates. This pattern uses file-based state + hooks.
Quick Start
- Define phases: analyze → plan → execute → verify
- Create state files on phase completion:
.workflow-phase-done - Add PreToolUse hooks to check required state files
- Add PostToolUse hooks to create state files
Core Concept
Phase 1 → [POST HOOK] → .analysis-done
Phase 2 → [POST HOOK] → .plan-approved
Phase 3 → [PRE HOOK checks] → [POST HOOK] → .execution-done
Phase 4 → PASS: cleanup all / FAIL: preserve for retry
State Files
| File | Purpose |
|---|---|
.{workflow}-analysis-done |
Unlocks planning |
.{workflow}-plan-approved |
Unlocks execution |
.{workflow}-execution-done |
Marks modification complete |
.{workflow}-audit-passed |
Final success marker |
Hook Template (Claude Code 1.0.40+)
{
"hooks": {
"PreToolUse": [{
"matcher": "Task",
"hooks": [{
"type": "command",
"command": "python3 scripts/workflow-gate.py",
"timeout": 5
}]
}]
}
}
Gate script checks tool_input.subagent_type and state files.
Best Practices
- Prefix state files -
.refactor-*,.migration-* - gitignore state files - Don't commit workflow state
- Clean up on success - Remove all state files on completion
- Preserve on failure - Keep state for retry capability
References
- Complete Workflow Example - Full 4-phase implementation
- Hook Details - Detailed hook configurations