Claude-Code-Workflow/.claude/skills/wf-player/specs/state-schema.md

Session State Schema

File Location

.workflow/sessions/WFR-<slug>-<date>-<time>/session-state.json

Full Schema

{
  "session_id": "WFR-feature-tdd-review-20260317-143022",
  "template_id": "wft-feature-tdd-review-20260310",
  "template_path": ".workflow/templates/feature-tdd-review.json",
  "template_name": "Feature TDD with Review",

  "status": "running | paused | completed | failed | aborted | archived",

  "context": {
    "goal": "Implement user authentication",
    "scope": "src/auth"
  },

  "execution_plan": [
    { "batch": 1, "nodes": ["N-001"], "parallel": false },
    { "batch": 2, "nodes": ["CP-01"], "parallel": false },
    { "batch": 3, "nodes": ["N-002"], "parallel": false },
    { "batch": 4, "nodes": ["CP-02"], "parallel": false },
    { "batch": 5, "nodes": ["N-003a", "N-003b"], "parallel": true },
    { "batch": 6, "nodes": ["N-004"], "parallel": false }
  ],

  "current_batch": 3,
  "current_node": "N-002",
  "last_checkpoint": "CP-01",

  "node_states": {
    "N-001": {
      "status": "completed",
      "started_at": "2026-03-17T14:30:25Z",
      "completed_at": "2026-03-17T14:35:10Z",
      "session_id": "WFS-plan-20260317",
      "output_path": ".workflow/sessions/WFS-plan-20260317/IMPL_PLAN.md",
      "artifacts": [
        ".workflow/sessions/WFS-plan-20260317/IMPL_PLAN.md"
      ],
      "error": null
    },
    "CP-01": {
      "status": "completed",
      "saved_at": "2026-03-17T14:35:12Z",
      "snapshot_path": ".workflow/sessions/WFR-feature-tdd-review-20260317-143022/checkpoints/CP-01.json",
      "auto_continue": true
    },
    "N-002": {
      "status": "running",
      "started_at": "2026-03-17T14:35:14Z",
      "completed_at": null,
      "session_id": null,
      "output_path": null,
      "artifacts": [],
      "error": null,
      "cli_task_id": "gem-143514-x7k2"
    },
    "CP-02": {
      "status": "pending",
      "saved_at": null,
      "snapshot_path": null
    },
    "N-003a": {
      "status": "pending",
      "started_at": null,
      "completed_at": null,
      "session_id": null,
      "output_path": null,
      "artifacts": [],
      "error": null
    },
    "N-003b": { "status": "pending", "..." : "..." },
    "N-004": { "status": "pending", "..." : "..." }
  },

  "created_at": "2026-03-17T14:30:22Z",
  "updated_at": "2026-03-17T14:35:14Z",
  "completed_at": null
}

Status Values

Status	Description
running	Active execution in progress
paused	User paused at checkpoint — resume with --resume
completed	All nodes executed successfully
failed	A node failed and abort was chosen
aborted	User aborted at checkpoint
archived	Completed and moved to archive/

Node State Status Values

Status	Description
pending	Not yet started
running	Currently executing (may be waiting for CLI callback)
completed	Successfully finished
skipped	Skipped due to on_fail: skip
failed	Execution error

Checkpoint Snapshot Schema

.workflow/sessions/<wfr-id>/checkpoints/<CP-id>.json:

{
  "session_id": "WFR-<id>",
  "checkpoint_id": "CP-01",
  "checkpoint_name": "After Plan",
  "saved_at": "2026-03-17T14:35:12Z",
  "context_snapshot": { "goal": "...", "scope": "..." },
  "node_states_snapshot": { /* full node_states at this point */ },
  "last_completed_node": "N-001",
  "next_node": "N-002"
}

Session Directory Structure

.workflow/sessions/WFR-<slug>-<date>-<time>/
+-- session-state.json       # Main state file, updated after every node
+-- checkpoints/             # Checkpoint snapshots
|   +-- CP-01.json
|   +-- CP-02.json
+-- artifacts/               # Optional: copies of key artifacts
    +-- N-001-output.md