The Complete Production SOP: How to Deploy and Run Finite State Machine (FSM) Agent State Engine in Autonomous AI Agents

export type WorkflowState = 'INITIAL' | 'PLANNING' | 'EXECUTING' | 'AUDITING' | 'TERMINATED' | 'FAILED';

export interface StateTransitionEvent {
  type: 'START' | 'PLAN_APPROVED' | 'EXECUTION_SUCCESS' | 'AUDIT_PASSED' | 'AUDIT_FAILED' | 'FATAL_ERROR';
  payload?: Record<string, unknown>;
}

export const VALID_TRANSITIONS: Record<WorkflowState, WorkflowState[]> = {
  INITIAL: ['PLANNING'],
  PLANNING: ['EXECUTING', 'FAILED'],
  EXECUTING: ['AUDITING', 'FAILED'],
  AUDITING: ['TERMINATED', 'EXECUTING', 'FAILED'],
  TERMINATED: [],
  FAILED: ['PLANNING', 'TERMINATED']
};

import { WorkflowState, StateTransitionEvent, VALID_TRANSITIONS } from './fsm.schema.js';

export class AgentStateEngine {
  private currentState: WorkflowState = 'INITIAL';
  private history: { from: WorkflowState; to: WorkflowState; timestamp: number }[] = [];

  public getState(): WorkflowState {
    return this.currentState;
  }

  public transition(targetState: WorkflowState, guardCondition: boolean = true): void {
    if (!guardCondition) {
      throw new Error(`[FSM_GUARD_VIOLATION] Guard rejected transition to: ${targetState}`);
    }
    const allowed = VALID_TRANSITIONS[this.currentState];
    if (!allowed.includes(targetState)) {
      throw new Error(`[INVALID_TRANSITION] Cannot transition from ${this.currentState} to ${targetState}`);
    }
    this.history.push({ from: this.currentState, to: targetState, timestamp: Date.now() });
    this.currentState = targetState;
  }
}

You are assigned to refactor our auth pipeline.
Trigger: enforce deterministic state transitions
Skill: agentic-workflow-state-machine
Rules:
1. Move to PLANNING and write execution plan.
2. Do NOT write code until PLANNING state outputs plan.json.
3. Transition to EXECUTING only after guard check passes.
4. Move to AUDITING and execute test suite before marking TERMINATED.

#!/usr/bin/env bash
set -euo pipefail
echo "[FSM Quality Gate] Validating state engine output..."
npx tsc --noEmit
if [ $? -eq 0 ]; then
  echo "[FSM Guard] Compilation verified: PASS"
  exit 0
else
  echo "[FSM Guard] Compilation error: Transition to AUDITING failed." >&2
  exit 1
fi