# Agent Task State Machine

> Design and review generic agent task and step state machines. Use when adding business-level task progress, step lifecycle tracking, task events, persistence, streaming timelines, resumable task state, or cross-layer task status APIs.

- **Type:** Skill
- **Install:** `agentstack add skill-hsienw-ai-agent-engineering-playbook-agent-task-state-machine`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [HsienW](https://agentstack.voostack.com/s/hsienw)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [HsienW](https://github.com/HsienW)
- **Source:** https://github.com/HsienW/ai-agent-engineering-playbook/tree/master/skills-runtime-governance/agent-task-state-machine

## Install

```sh
agentstack add skill-hsienw-ai-agent-engineering-playbook-agent-task-state-machine
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent Task State Machine

## Skill Interface

- Name: agent-task-state-machine.
- Description: Design and review generic agent task and step state machines for business-level task progress, step lifecycle tracking, task events, persistence, streaming timelines, resumable task state, and cross-layer status APIs.
- Parameters: Task statuses, step statuses, legal transitions, event model, persistence requirements, retry and compensation rules, timeline consumers, redaction policy, and lifecycle verification cases.
- Instructions: Use this skill when product or operator workflows need task semantics beyond graph checkpoints. Define legal transitions in one module, keep terminal states final, persist append-only events when history matters, and test lifecycle, retry, resume, cancellation, and compensation paths.

Model business progress separately from graph execution state. A graph may
checkpoint execution, but product and operator workflows often need task,
step, audit, and timeline semantics.

## Core Model

Use generic names and inject domain-specific step names from the caller:

```ts
type TaskStatus =
  | 'created'
  | 'running'
  | 'waiting_confirmation'
  | 'completed'
  | 'partially_failed'
  | 'compensating'
  | 'failed'
  | 'cancelled';

type StepStatus =
  | 'pending'
  | 'running'
  | 'waiting_confirmation'
  | 'succeeded'
  | 'retryable_failed'
  | 'terminal_failed'
  | 'compensating'
  | 'compensated'
  | 'skipped';

type AgentTask = {
  taskId: string;
  taskType: string;
  status: TaskStatus;
  steps: AgentStep[];
  createdAt: string;
  updatedAt: string;
  metadata?: Record;
};

type AgentStep = {
  stepId: string;
  stepName: TStep;
  status: StepStatus;
  attempt: number;
  maxAttempts: number;
  input?: unknown;
  output?: unknown;
  error?: StepError;
  startedAt?: string;
  completedAt?: string;
};
```

## Transition Rules

- Define legal transitions in one owned module.
- Reject illegal transitions with stable error codes.
- Terminal states must not transition back to running.
- Step completion should drive task completion only through an explicit policy.
- Store transition events before notifying downstream listeners when durable
  history matters.
- Preserve enough data to resume or explain an interrupted task.

## Event Model

Use append-only task events:

- `task_created`
- `step_started`
- `step_completed`
- `step_failed`
- `step_retrying`
- `waiting_confirmation`
- `resumed`
- `task_completed`
- `task_failed`
- `compensation_triggered`
- `compensation_completed`

Events should include identifiers, event type, payload, and creation time. Keep
payloads structured, redacted, and safe for persistence.

## Verification

Test complete lifecycle, illegal transitions, retryable and terminal failures,
waiting and resume, cancellation, partial failure, compensation, event ordering,
and timeline rendering from persisted events.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HsienW](https://github.com/HsienW)
- **Source:** [HsienW/ai-agent-engineering-playbook](https://github.com/HsienW/ai-agent-engineering-playbook)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hsienw-ai-agent-engineering-playbook-agent-task-state-machine
- Seller: https://agentstack.voostack.com/s/hsienw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.