save-workflow-state
Save conductor workflow state to JSON file for smart resumption, tracking current phase, completed phases, issue context, and branch information
When & Why to Use This Skill
This Claude skill enables robust workflow persistence by saving the execution state of complex agentic tasks to a structured JSON file. It facilitates 'smart resumption,' allowing AI agents to seamlessly pick up where they left off by tracking completed phases, issue context, and branch information, effectively preventing redundant work and ensuring consistency across long-running development sessions.
Use Cases
- Smart Resumption: Recover the progress of multi-stage coding workflows after session restarts or interruptions, ensuring the agent retains context of previous actions.
- Phase-Based Progress Tracking: Maintain a verifiable record of completed and pending tasks within a structured software development lifecycle (SDLC) to ensure process compliance.
- Context Preservation: Persist critical metadata such as issue IDs, branch names, and architecture plans to provide the AI agent with continuous context across different execution environments.
- Workflow Auditing and Debugging: Generate timestamped state files that serve as a detailed log for auditing the agent's decision-making process and implementation history.
| name | save-workflow-state |
|---|---|
| description | Save conductor workflow state to JSON file for smart resumption, tracking current phase, completed phases, issue context, and branch information |
Save Workflow State
Purpose
Persist conductor workflow state after each phase completion to enable smart resumption across sessions, preventing duplicate work and allowing workflow recovery.
When to Use
- After completing conductor Phase 1 (Issue Discovery and Planning)
- After completing conductor Phase 2 (Branch Setup and Implementation)
- After completing conductor Phase 3 (Quality Assurance)
- After completing conductor Phase 4 (PR Creation)
- After completing conductor Phase 5 (Gemini Review)
- After completing conductor Phase 6 (Final Report)
Frequency: 6 times per full-cycle workflow
Instructions
Step 1: Create State Directory
# Ensure state directory exists
mkdir -p .claude/state
Step 2: Build State Object
Collect workflow metadata:
# Required fields with safe defaults
ISSUE_NUMBER=${1:-null}
ISSUE_TITLE=${2:-""}
CURRENT_PHASE=${3:-1}
BRANCH_NAME=${4:-""}
# Optional fields
PR_NUMBER=${5:-null}
AUDIT_SCORE=${6:-null}
ARCHITECTURE_PLAN=${7:-""}
IMPLEMENTATION_SUMMARY=${8:-""}
# Validate required fields
if [ "$ISSUE_NUMBER" = "null" ] || [ -z "$ISSUE_TITLE" ] || [ -z "$CURRENT_PHASE" ]; then
echo "❌ Error: Missing required parameters"
echo "Usage: save-workflow-state <issue_number> <issue_title> <current_phase> <branch_name> [pr_number] [audit_score] [architecture_plan] [implementation_summary]"
exit 1
fi
# Get current timestamp
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
# Calculate completed phases
COMPLETED_PHASES="["
for i in $(seq 1 $((CURRENT_PHASE - 1))); do
if [ $i -gt 1 ]; then
COMPLETED_PHASES="$COMPLETED_PHASES,"
fi
COMPLETED_PHASES="$COMPLETED_PHASES$i"
done
COMPLETED_PHASES="$COMPLETED_PHASES]"
Step 3: Write State File
STATE_FILE=".claude/state/conductor.json"
cat > "$STATE_FILE" << EOF
{
"conductor_version": "1.0",
"timestamp": "$TIMESTAMP",
"workflow": "full-cycle",
"issue": {
"number": ${ISSUE_NUMBER},
"title": "${ISSUE_TITLE}",
"type": "feature",
"hasAiAnalysis": true
},
"currentPhase": ${CURRENT_PHASE},
"completedPhases": ${COMPLETED_PHASES},
"context": {
"branchName": "${BRANCH_NAME}",
"filesChanged": [],
"commitCount": 0,
"prNumber": ${PR_NUMBER},
"architecturePlan": "${ARCHITECTURE_PLAN}",
"implementationNotes": "${IMPLEMENTATION_SUMMARY}"
},
"phases": {
"1": {
"name": "Issue Discovery and Planning",
"status": "$([ ${CURRENT_PHASE} -gt 1 ] && echo 'completed' || echo 'in_progress')",
"timestamp": "$TIMESTAMP",
"outputs": {
"issueSelected": ${ISSUE_NUMBER},
"architectureValidated": true,
"aiAnalysisUsed": true
}
},
"2": {
"name": "Branch Setup and Implementation",
"status": "$([ $CURRENT_PHASE -gt 2 ] && echo 'completed' || [ $CURRENT_PHASE -eq 2 ] && echo 'in_progress' || echo 'pending')",
"timestamp": "$([ $CURRENT_PHASE -ge 2 ] && echo $TIMESTAMP || echo '')",
"outputs": {}
},
"3": {
"name": "Quality Assurance",
"status": "$([ $CURRENT_PHASE -gt 3 ] && echo 'completed' || [ $CURRENT_PHASE -eq 3 ] && echo 'in_progress' || echo 'pending')",
"timestamp": "$([ $CURRENT_PHASE -ge 3 ] && echo $TIMESTAMP || echo '')",
"outputs": {}
},
"4": {
"name": "PR Creation",
"status": "$([ $CURRENT_PHASE -gt 4 ] && echo 'completed' || [ $CURRENT_PHASE -eq 4 ] && echo 'in_progress' || echo 'pending')",
"timestamp": "$([ $CURRENT_PHASE -ge 4 ] && echo $TIMESTAMP || echo '')",
"outputs": {}
},
"5": {
"name": "Gemini Review",
"status": "$([ $CURRENT_PHASE -gt 5 ] && echo 'completed' || [ $CURRENT_PHASE -eq 5 ] && echo 'in_progress' || echo 'pending')",
"timestamp": "$([ $CURRENT_PHASE -ge 5 ] && echo $TIMESTAMP || echo '')",
"outputs": {}
},
"6": {
"name": "Final Report",
"status": "$([ $CURRENT_PHASE -gt 6 ] && echo 'completed' || [ $CURRENT_PHASE -eq 6 ] && echo 'in_progress' || echo 'pending')",
"timestamp": "$([ $CURRENT_PHASE -ge 6 ] && echo $TIMESTAMP || echo '')",
"outputs": {}
}
}
}
EOF
Step 4: Verify State Written
if [ -f "$STATE_FILE" ]; then
echo "✅ Workflow state saved: Phase $CURRENT_PHASE"
# Validate JSON
if jq empty "$STATE_FILE" 2>/dev/null; then
echo "✅ State file is valid JSON"
else
echo "❌ State file has invalid JSON - workflow resumption may fail"
fi
else
echo "❌ Failed to save workflow state"
fi
State Schema
interface ConductorState {
conductor_version: string;
timestamp: string;
workflow: "full-cycle" | "implementation-only" | "quality-gate";
issue: {
number: number;
title: string;
type: "feature" | "bug" | "refactor" | "research-heavy";
hasAiAnalysis: boolean;
};
currentPhase: 1 | 2 | 3 | 4 | 5 | 6;
completedPhases: number[];
context: {
branchName: string;
filesChanged: string[];
commitCount: number;
prNumber: number | null;
architecturePlan: string;
implementationNotes: string;
};
phases: {
[key: string]: {
name: string;
status: "pending" | "in_progress" | "completed";
timestamp: string;
outputs: Record<string, any>;
};
};
}
Usage Examples
After Phase 1 Completion
# Save state after Phase 1
save-workflow-state \
137 \
"Add user dark mode preference toggle" \
1 \
"feature/issue-137-dark-mode" \
null \
null \
"VSA compliant, no violations found"
After Phase 3 Completion
# Save state after Phase 3 with quality metrics
save-workflow-state \
137 \
"Add user dark mode preference toggle" \
3 \
"feature/issue-137-dark-mode" \
null \
8.5 \
"VSA compliant" \
"Implemented dark mode toggle with state management"
After Phase 4 Completion
# Save state after PR creation
save-workflow-state \
137 \
"Add user dark mode preference toggle" \
4 \
"feature/issue-137-dark-mode" \
45 \
8.5 \
"VSA compliant" \
"Implemented dark mode toggle"
Integration with Conductor
Used after each phase in conductor workflow:
### Phase 1: Issue Discovery and Planning
... [phase work] ...
**ACTION: Save state after Phase 1 completion:**
Use `save-workflow-state` skill:
- issue_number: $ISSUE_NUMBER
- issue_title: $ISSUE_TITLE
- current_phase: 1
- branch_name: $BRANCH_NAME (if created)
- architecture_plan: Summary from architect agent
→ Proceed to Phase 2
Related Skills
load-resumption-state- Load saved state for workflow resumptiondetermine-resumption-phase- Analyze state to determine restart pointclear-workflow-state- Clean up state after workflow completion
State File Location
- Path:
.claude/state/conductor.json - Git: Should be in
.gitignore(session-specific) - Persistence: Survives across Claude Code restarts
- Cleanup: Manually delete or use
clear-workflow-stateskill
Best Practices
- Save after each phase - Don't batch multiple phases
- Include phase outputs - Save key metrics and decisions
- Validate JSON - Use
jqto verify valid JSON - Update completedPhases - Accurately track completed work
- Timestamp everything - Helps debug resumption issues
- Don't commit state - Add to
.gitignore
Error Handling
Directory Creation Fails
if ! mkdir -p .claude/state; then
echo "❌ Cannot create state directory"
return 1
fi
Write Permission Denied
if [ ! -w .claude/state ]; then
echo "❌ No write permission for state directory"
return 1
fi
Invalid JSON Generated
if ! jq empty "$STATE_FILE" 2>/dev/null; then
echo "⚠️ Invalid JSON in state file - resumption may fail"
echo "State file location: $STATE_FILE"
fi
Notes
- State file enables smart resumption across sessions
- Should be created in
.claude/state/directory - Not committed to git (session-specific)
- Used by
load-resumption-stateskill for workflow recovery - Critical for long-running workflows spanning multiple sessions