Claude-Code-Workflow/.claude/skills/wf-player/specs/node-executor.md

# Node Executor — Execution Mechanisms per Node Type

## Overview

Each node type uses a specific execution mechanism. This spec defines the exact invocation pattern.

## 1. skill node

**Mechanism**: `Skill()` tool — synchronous, blocks until complete.

```
Skill({
  skill: "<node.executor>",
  args: "<resolved_args>"
})
```

**Output extraction**: Parse Skill() result for:
- Session ID pattern: `WFS-[a-z]+-\d{8}` or `TC-[a-z]+-\d{8}`
- Output path: last `.md` or `.json` file path mentioned
- Artifacts: all file paths in output

**Session ID sources**:
- Explicit: "Session: WFS-plan-20260317" in output
- Implicit: first session-like ID in output

**Examples**:
```
// Planning skill
Skill({ skill: "workflow-lite-plan", args: "Implement user authentication" })

// Execute skill (with prior session)
Skill({ skill: "workflow-execute", args: "--resume-session WFS-plan-20260317" })

// Test skill (with prior session)
Skill({ skill: "workflow-test-fix", args: "--session WFS-exec-20260317" })
```

---

## 2. command node

**Mechanism**: `Skill()` tool with namespace command name — synchronous.

```
Skill({
  skill: "<node.executor>",  // e.g. "workflow:refactor-cycle"
  args: "<resolved_args>"
})
```

**Examples**:
```
Skill({ skill: "workflow:refactor-cycle", args: "Reduce coupling in auth module" })
Skill({ skill: "workflow:debug-with-file", args: "Login fails with 401 on valid tokens" })
Skill({ skill: "issue:discover", args: "" })
Skill({ skill: "issue:queue", args: "" })
```

---

## 3. cli node

**Mechanism**: `Bash()` with `run_in_background: true` — STOP after launch, resume via hook callback.

```
// Build command
const prompt = resolveArgs(node.args_template, ...)
const cmd = `ccw cli -p "${escapeForShell(prompt)}" --tool ${node.cli_tool} --mode ${node.cli_mode} --rule ${node.cli_rule}`

// Launch background
Bash({ command: cmd, run_in_background: true })

// Save CLI task ID to node state for hook matching
node_state.cli_task_id = <captured from stderr CCW_EXEC_ID>

// Write session-state.json
// STOP — do not proceed until hook callback fires
```

**Hook callback** (triggered when ccw cli completes):
```
// Identify which node was running (status = "running" with cli_task_id set)
// Extract from CLI output:
//   - output_path: file written by CLI
//   - cli_exec_id: from CCW_EXEC_ID
// Mark node completed
// Advance to next node
```

**CLI output escaping**:
```javascript
function escapeForShell(s) {
  // Use single quotes with escaped single quotes inside
  return "'" + s.replace(/'/g, "'\\''") + "'"
}
```

**Example**:
```
Bash({
  command: `ccw cli -p 'PURPOSE: Analyze auth module architecture\nTASK: • Review class structure • Check dependencies\nMODE: analysis\nCONTEXT: @src/auth/**/*\nEXPECTED: Architecture report with issues list\nCONSTRAINTS: Read only' --tool gemini --mode analysis --rule analysis-review-architecture`,
  run_in_background: true
})
```

---

## 4. agent node

**Mechanism**: `Agent()` tool.

Single agent (serial):
```
Agent({
  subagent_type: node.executor,       // "general-purpose" or "code-reviewer"
  prompt: resolveArgs(node.args_template, ...),
  run_in_background: false,           // blocks until complete
  description: node.name
})
```

Parallel agents (same parallel_group — use team-coordinate pattern):
```
// For 2-3 parallel agents: launch all with run_in_background: true
// Use SendMessage/callback or wait with sequential Skill() calls
// For complex parallel pipelines: delegate to team-coordinate

Skill({
  skill: "team-coordinate",
  args: "<description of parallel work>"
})
```

**Output extraction**:
- Agent output is usually the full response text
- Look for file paths in output for `output_path`

---

## 5. checkpoint node

**Mechanism**: Pure state management — no external calls unless `auto_continue: false`.

```
// 1. Write checkpoint snapshot
Write({
  file_path: "<session_dir>/checkpoints/<node.id>.json",
  content: JSON.stringify({
    session_id, checkpoint_id: node.id, checkpoint_name: node.name,
    saved_at: now(), context_snapshot: session_state.context,
    node_states_snapshot: session_state.node_states,
    last_completed_node: prev_node_id,
    next_node: next_node_id
  }, null, 2)
})

// 2. Update session state
session_state.last_checkpoint = node.id
node_states[node.id].status = "completed"
node_states[node.id].saved_at = now()
node_states[node.id].snapshot_path = checkpointPath

Write({ file_path: session_state_path, content: JSON.stringify(session_state, null, 2) })

// 3. If auto_continue = false: pause for user (see 03-execute.md)
// 4. If auto_continue = true: proceed immediately
```

---

## Context Passing Between Nodes

The runtime reference resolver in `03-execute.md` handles `{N-xxx.field}` substitution.

**Key resolved fields by node type**:

| Node type | Exposes | Referenced as |
|-----------|---------|---------------|
| skill | session_id | `{N-001.session_id}` |
| skill | output_path | `{N-001.output_path}` |
| skill | artifacts[0] | `{N-001.artifacts[0]}` |
| cli | output_path | `{N-001.output_path}` |
| agent | output_path | `{N-001.output_path}` |
| any | shorthand prev | `{prev_session_id}`, `{prev_output_path}` |

**Fallback**: If referenced field is null/empty, the args_template substitution results in empty string. The executor should handle gracefully (most skills default to latest session).