mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-18 18:48:48 +08:00
152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
---
|
|
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-*/`
|
|
|
|
1. Scan `.workflow/sessions/WFR-*/session-state.json` for status = "running" | "paused"
|
|
2. Multiple found → AskUserQuestion for selection
|
|
3. Load session-state.json
|
|
4. Identify `last_checkpoint` and `node_states`
|
|
5. Reset any `running` nodes back to `pending` (they were interrupted)
|
|
6. Determine next executable node from `topological_order` after last checkpoint
|
|
7. 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
|
|
|
|
| Spec | Purpose |
|
|
|------|---------|
|
|
| [specs/node-executor.md](specs/node-executor.md) | Execution mechanism per node type |
|
|
| [specs/state-schema.md](specs/state-schema.md) | session-state.json schema |
|