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 resumption
determine-resumption-phase - Analyze state to determine restart point
clear-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-state skill

Best Practices

Save after each phase - Don't batch multiple phases
Include phase outputs - Save key metrics and decisions
Validate JSON - Use jq to 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-state skill for workflow recovery
Critical for long-running workflows spanning multiple sessions