| name | wf-player |
| description | Workflow template player — load a JSON template produced by wf-composer, bind context variables, execute nodes in DAG order (serial/parallel), persist state at checkpoints, support resume from any checkpoint. Uses ccw-coordinator serial-blocking for CLI nodes and team-coordinate worker pattern for parallel agent nodes. Triggers on "wf-player " or "/wf-player". |
| argument-hint | <template-slug|path> [--context key=value...] [--resume <session-id>] [--list] [--dry-run] |
| allowed-tools | Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), Skill(*) |
Workflow Run
Load a workflow template → bind variables → execute DAG → persist checkpoints → resume capable.
Architecture
Skill(skill="wf-player", args="<template> --context goal='...'")
|
+-- Phase 0: Entry Router
|-- --list -> list available templates, exit
|-- --resume -> load session, skip to Phase 3 (Execute)
|-- --dry-run -> load + show execution plan, no execution
|-- default -> Phase 1 (Load)
|
+-- Phase 1: Load & Bind
| Load template JSON, bind {variables} from --context, validate required vars
|
+-- Phase 2: Instantiate
| Init session state, topological sort, write WFR session file
|
+-- Phase 3: Execute Loop
| For each node in order:
| skill node -> Skill(skill=...) [synchronous]
| cli node -> ccw cli [background + stop, hook callback]
| command node -> Skill(skill="namespace:cmd") [synchronous]
| agent node -> Agent(...) [run_in_background per node config]
| checkpoint -> save state, optionally pause
|
+-- Phase 4: Complete
Archive session, output summary
Shared Constants
| Constant | Value |
|---|
| Session prefix | WFR |
| Session dir | .workflow/sessions/WFR-<slug>-<date>/ |
| State file | session-state.json |
| Template dir | .workflow/templates/ |
| Template index | .workflow/templates/index.json |
Entry Router
Parse $ARGUMENTS:
| Detection | Condition | Handler |
|---|
| List templates | --list in args | -> handleList |
| Resume session | --resume <session-id> in args | -> Phase 2 (resume) |
| Dry run | --dry-run in args | -> Phase 1 + 2, print plan, exit |
| Normal | Template slug/path provided | -> Phase 1 |
| No args | Empty args | -> handleList + AskUserQuestion |
handleList
Scan .workflow/templates/index.json. Display:
Available workflow templates:
feature-tdd-review [feature, complex] 3 work nodes, 2 checkpoints
quick-bugfix [bugfix, simple] 2 work nodes, 1 checkpoint
...
Run: Skill(skill="wf-player", args="<slug> --context goal='...'")
Phase 0 (Resume): Session Reconciliation
Trigger: --resume <session-id> or active WFR session found in .workflow/sessions/WFR-*/
- Scan
.workflow/sessions/WFR-*/session-state.json for status = "running" | "paused"
- Multiple found → AskUserQuestion for selection
- Load session-state.json
- Identify
last_checkpoint and node_states
- Reset any
running nodes back to pending (they were interrupted)
- Determine next executable node from
topological_order after last checkpoint
- Resume at Phase 3 (Execute Loop) from that node
Phase 1: Load & Bind
Read phases/01-load.md and execute.
Objective: Load template, collect missing variables, bind all {variable} references.
Success: Template loaded, all required variables bound, bound_context{} ready.
Phase 2: Instantiate
Read phases/02-instantiate.md and execute.
Objective: Create WFR session directory, init state, compute execution plan.
Success: session-state.json written, topological_order ready.
Phase 3: Execute Loop
Read phases/03-execute.md and execute.
Objective: Execute each node in topological_order using appropriate mechanism.
CRITICAL — CLI node blocking:
- CLI nodes launch
ccw cli in background and immediately STOP
- Wait for hook callback — DO NOT poll with TaskOutput
- Hook callback resumes execution at next node
Success: All nodes completed, all checkpoints saved.
Phase 4: Complete
Read phases/04-complete.md and execute.
Objective: Archive session, output execution summary and artifact paths.
Error Handling
| Scenario | Resolution |
|---|
| Required variable missing | AskUserQuestion to collect it |
| Template not found | Show --list and suggest closest match |
| Node failed (on_fail=abort) | AskUserQuestion: Retry / Skip / Abort |
| Node failed (on_fail=skip) | Log warning, continue to next node |
| Node failed (on_fail=retry) | Retry once, then abort |
| Interrupted mid-execution | State saved at last checkpoint; resume with --resume <session-id> |
| Cycle in DAG | Error immediately, point to template for fix |
Specs Reference
