@crewx/workflow 0.3.6 → 0.3.8

package/SKILL.md

@@ -1,409 +1,409 @@
----
-name: crewx/workflow
-description: Workflow management built-in tool. List, view details (with Mermaid), validate syntax, and manage execution state.
-argument-hint: "<list|show|validate|run> [args]"
-metadata:
-  version: 0.3.3
-  built-in: true
-  entrypoint: cli.ts
-  schema: workflow-schema.json
----
-
-# CrewX Workflow
-
-A built-in tool for managing agent collaboration flows using **semantic workflow YAML**. Define multi-agent processes as directed graphs, visualize them as Mermaid diagrams, validate syntax, and track execution state.
-
-## When to Use
-
-- "Show available workflows" / "List workflows"
-- "Show me the workflow diagram" / "Visualize the dev process"
-- "Validate my workflow YAML"
-- "Start the code-review workflow" / "Execute the next step"
-- "What's the current state of the running workflow?"
-- When you need to orchestrate multiple agents in a defined sequence
-- When you want to design a reusable collaboration recipe
-
-## Quick Start
-
-```bash
-# List all workflows
-crewx workflow list
-
-# View workflow details with Mermaid diagram
-crewx workflow show standard-dev-core --mermaid
-
-# Validate all workflow files
-crewx workflow validate
-
-# Start a workflow execution
-crewx workflow run start standard-dev-core --set goal="implement feature X"
-
-# Move to a node
-crewx workflow run node <exec-id> research
-
-# Check execution state
-crewx workflow run state <exec-id>
-```
-
-## Commands
-
-### `workflow list`
-
-Scans `workflows/*.yaml` and outputs all workflow definitions.
-
-```bash
-crewx workflow list              # Human-readable table
-crewx workflow list --json       # JSON output
-```
-
-### `workflow show <id|file>`
-
-Displays workflow details: metadata, nodes, agents, and optionally a Mermaid diagram.
-
-```bash
-crewx workflow show standard-dev-core
-crewx workflow show standard-dev-core --mermaid   # Include Mermaid code
-crewx workflow show standard-dev-core --json      # JSON output
-```
-
-### `workflow validate [file]`
-
-Three-phase validation: JSON Schema -> required fields -> reference integrity (node references, agent existence).
-
-```bash
-crewx workflow validate                              # Validate all files in workflows/
-crewx workflow validate workflows/standard-dev.yaml  # Validate a specific file
-```
-
-### `workflow run start <id|file>`
-
-Creates a new execution instance. State is stored as a JSON file in `.crewx/workflow-runs/`.
-
-```bash
-crewx workflow run start standard-dev-core
-crewx workflow run start standard-dev-core --set goal="build auth module"
-crewx workflow run start workflows/idea-validation.yaml
-```
-
-### `workflow run state <exec-id>`
-
-Query or modify execution state.
-
-```bash
-crewx workflow run state wfr_abc12345                          # View state
-crewx workflow run state wfr_abc12345 --set result="completed" # Set a value
-echo "Long text..." | crewx workflow run state wfr_abc12345 --set analysis=-  # Pipe via stdin
-```
-
-### `workflow run node <exec-id> <node-id>`
-
-Move to a node: sets `current_node` and appends to `completed_nodes`. For `agent_task` nodes, triggers agent execution via `crewx q/x`.
-
-```bash
-crewx workflow run node wfr_abc12345 research
-crewx workflow run node wfr_abc12345 end
-```
-
-### `workflow run reset <exec-id>`
-
-Restores execution state to `initial_state`.
-
-```bash
-crewx workflow run reset wfr_abc12345
-```
-
-### `workflow run list`
-
-Lists all execution instances.
-
-```bash
-crewx workflow run list
-crewx workflow run list --json
-```
-
-All `run` subcommands support the `--json` flag.
-
-## Name Resolution
-
-`<id|file>` resolves in this order:
-
-1. `.yaml` / `.yml` extension -> treated as direct file path
-2. Workflow ID -> scans all YAML files for matching `workflows:` key
-3. Filename slug -> `workflows/<name>.yaml`
-
-## Workflow YAML Structure
-
-```yaml
-workflows:
-  process-name:
-    metadata:
-      name: "Process Name"
-      description: "What this workflow does"
-      version: "1.0"
-    timeout: 300          # Global timeout (seconds)
-    max_iterations: 50    # Max node transitions
-    state:                # Initial state variables
-      goal: ""
-      result: ""
-    nodes:
-      step_id:
-        type: agent_task
-        ...
-```
-
-### Top-Level Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `metadata` | object | No | `name` (required), `description`, `version` |
-| `timeout` | number | No | Global timeout in seconds |
-| `max_iterations` | number | No | Maximum node transitions |
-| `state` | object | No | Initial state variables (accessible via `{{var}}`) |
-| `nodes` | object | **Yes** | Node definitions (keyed by node ID) |
-
-## Node Types
-
-### `agent_task` -- Assign task to an agent
-
-```yaml
-analyze:
-  type: agent_task
-  agent: tax_lawyer
-  mode: query              # query (read-only) | execute (read-write)
-  input: |
-    Analyze the tax law: {{user_input}}
-  output: law_analysis     # State key to store the result
-  next: calculate
-```
-
-### `parallel` -- Fan-out to concurrent branches
-
-```yaml
-parallel_review:
-  type: parallel
-  branches: [cpo_review, persona_survey]
-  join: merge_feedback     # Node to converge at
-```
-
-### `join` -- Fan-in from parallel branches
-
-```yaml
-merge_feedback:
-  type: join
-  on_failure: continue     # continue even if a branch failed
-  next: check_quality
-```
-
-### `branch` -- Conditional routing
-
-```yaml
-check_approval:
-  type: branch
-  condition: "state.cpo_feedback.includes('approved')"
-  branches:
-    "true": end
-    "false": persona_survey
-  default: persona_survey
-```
-
-### `approval` -- Wait for human decision
-
-```yaml
-human_check:
-  type: approval
-  description: "Would you like to review and approve the result?"
-  assignee: "@manager"
-  on_approve: publish
-  on_reject: revise
-```
-
-### `expression` -- Safe state computation
-
-Evaluates safe expressions (arithmetic, string, comparison, ternary) and stores results in state. No agent call -- runs instantly.
-
-**Allowed:** `+`, `-`, `*`, `/`, `%`, `>`, `<`, `>=`, `<=`, `==`, `!=`, `&&`, `||`, `!`, `? :`, `()`, number/string/boolean literals, state variable references.
-
-**Blocked:** `require`, `import`, `process`, `eval`, `Function`, `.` (property access), `[` (bracket access), `__proto__`, `constructor`, `prototype`.
-
-```yaml
-# Increment counter
-increment_fix:
-  type: expression
-  set:
-    fix_count: "fix_count + 1"
-  next: fix
-
-# Multiple keys
-calculate:
-  type: expression
-  set:
-    score: "(pass_count / total_count) * 100"
-    remaining: "max_retry - fix_count"
-    summary: "wi_id + ' - attempt ' + fix_count"
-  next: check_score
-
-# Ternary
-decide:
-  type: expression
-  set:
-    action: "fix_count > 3 ? 'escalate' : 'retry'"
-  next: route
-```
-
-State values are auto-coerced: numeric strings become numbers for arithmetic, results are stored as strings.
-
-### `end` -- Termination
-
-```yaml
-end:
-  type: end
-```
-
-## Common Node Options
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `timeout` | number | Per-node timeout in seconds |
-| `retry` | object | `{ max, delay: "exponential" \| "fixed" }` |
-| `hooks` | string[] | Hook packages to apply |
-| `on_failure` | string | `fail_fast` \| `continue` \| `ignore` |
-| `on_error` | object | `{ handler?, fallback_node? }` |
-| `comment` | string | Human-readable annotation |
-
-## Template Syntax
-
-Use `{{variable_name}}` in `input` fields to reference `state` values.
-
-```yaml
-state:
-  goal: "implement auth"
-nodes:
-  plan:
-    type: agent_task
-    agent: architect
-    input: "Create a plan for: {{goal}}"
-    output: plan_result
-    next: implement
-```
-
-## Programmatic API
-
-### WorkflowEngine
-
-YAML loading, validation, and Mermaid generation. Used by both CLI and server.
-
-```typescript
-import { WorkflowEngine } from '@crewx/workflow';
-
-const engine = new WorkflowEngine();
-
-// Load all workflows from a directory
-const workflows: LoadedWorkflow[] = engine.loadWorkflows('workflows/');
-
-// Validate a workflow file (schema -> fields -> references)
-const result = engine.validateFile('workflows/standard-dev.yaml');
-// { success: boolean; results: ValidationResult[]; error?: string }
-
-// Generate Mermaid diagram
-const mermaid: string = engine.toMermaid(spec);
-```
-
-### RunManager
-
-Execution state management. Stores state as JSON files in `.crewx/workflow-runs/`.
-
-```typescript
-import { RunManager } from '@crewx/workflow';
-
-const manager = new RunManager();
-
-// Start execution
-const exec: RunExecution = manager.start('workflows/dev.yaml', 'dev-core', { goal: 'build feature' });
-
-// Execute a node (triggers agent call for agent_task nodes)
-const updated: RunExecution = await manager.executeNode(exec.id, 'research');
-
-// Move to node without executing
-const moved: RunExecution = manager.moveNode(exec.id, 'implement');
-```
-
-### Key Types
-
-```typescript
-type NodeType = 'agent_task' | 'parallel' | 'join' | 'branch' | 'approval' | 'expression' | 'end';
-
-interface RunExecution {
-  id: string;                          // 'wfr_{nanoid(8)}'
-  workflow_id: string;
-  workflow_file: string;
-  created_at: string;                  // ISO 8601
-  updated_at: string;
-  current_node: string;
-  completed_nodes: string[];
-  state: Record<string, unknown>;
-  initial_state: Record<string, unknown>;
-  status?: 'running' | 'completed' | 'failed';
-}
-```
-
-## Architecture
-
-```
-[CLI]  crewx workflow list/show/validate
-         |
-         v
-    WorkflowEngine  <-- YAML parsing, validation, Mermaid
-         |
-         v
-    workflows/*.yaml  (source files)
-
-[CLI]  crewx workflow run start/node/state
-         |
-         v
-    RunManager  <-- execution state management
-         |
-         +---> .crewx/workflow-runs/wfr_*.json  (state files)
-         +---> crewx q/x  (agent invocation for agent_task nodes)
-
-[Server]  GET /api/v1/workflows[/:id]
-         |
-         v
-    WorkflowService  --> fs (YAML read) + WorkflowEngine.toMermaid()
-```
-
-> **Note:** The server only uses `WorkflowEngine.toMermaid()`. YAML listing/parsing is handled by the server's own `WorkflowService`. `RunManager` (execution state) is CLI-only.
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CREWX_WORKSPACE` | Workspace directory (where `workflows/` lives) | `.` |
-| `CREWX_CLI` | CrewX CLI path (for agent execution in `run node`) | `npx crewx` |
-| `CREWX_WORKFLOW_TIMEOUT` | Node execution timeout (ms) | `1800000` (30 min) |
-| `CREWX_CONFIG` | Custom config file path | `crewx.yaml` |
-
-## WARNING: Check Agent List Before Designing
-
-**Specifying a non-existent agent in a workflow will prevent execution!** Always verify available agents first:
-
-```bash
-crewx agent ls
-```
-
-## File Layout
-
-```
-workflows/                      # Workflow YAML sources
-  standard-dev.yaml
-  idea-validation.yaml
-.crewx/workflow-runs/           # Execution state (auto-created)
-  wfr_abc12345.json
-packages/built-in/workflow/     # Package source
-  cli.ts                        # CLI entrypoint
-  src/
-    types.ts                    # TypeScript interfaces
-    engine.ts                   # WorkflowEngine
-    mermaid.ts                  # Mermaid diagram renderer
-    run-manager.ts              # RunManager
-  workflow-schema.json          # JSON Schema for validation
-```
+---
+name: crewx/workflow
+description: Workflow management built-in tool. List, view details (with Mermaid), validate syntax, and manage execution state.
+argument-hint: "<list|show|validate|run> [args]"
+metadata:
+  version: 0.3.3
+  built-in: true
+  entrypoint: cli.ts
+  schema: workflow-schema.json
+---
+
+# CrewX Workflow
+
+A built-in tool for managing agent collaboration flows using **semantic workflow YAML**. Define multi-agent processes as directed graphs, visualize them as Mermaid diagrams, validate syntax, and track execution state.
+
+## When to Use
+
+- "Show available workflows" / "List workflows"
+- "Show me the workflow diagram" / "Visualize the dev process"
+- "Validate my workflow YAML"
+- "Start the code-review workflow" / "Execute the next step"
+- "What's the current state of the running workflow?"
+- When you need to orchestrate multiple agents in a defined sequence
+- When you want to design a reusable collaboration recipe
+
+## Quick Start
+
+```bash
+# List all workflows
+crewx workflow list
+
+# View workflow details with Mermaid diagram
+crewx workflow show standard-dev-core --mermaid
+
+# Validate all workflow files
+crewx workflow validate
+
+# Start a workflow execution
+crewx workflow run start standard-dev-core --set goal="implement feature X"
+
+# Move to a node
+crewx workflow run node <exec-id> research
+
+# Check execution state
+crewx workflow run state <exec-id>
+```
+
+## Commands
+
+### `workflow list`
+
+Scans `workflows/*.yaml` and outputs all workflow definitions.
+
+```bash
+crewx workflow list              # Human-readable table
+crewx workflow list --json       # JSON output
+```
+
+### `workflow show <id|file>`
+
+Displays workflow details: metadata, nodes, agents, and optionally a Mermaid diagram.
+
+```bash
+crewx workflow show standard-dev-core
+crewx workflow show standard-dev-core --mermaid   # Include Mermaid code
+crewx workflow show standard-dev-core --json      # JSON output
+```
+
+### `workflow validate [file]`
+
+Three-phase validation: JSON Schema -> required fields -> reference integrity (node references, agent existence).
+
+```bash
+crewx workflow validate                              # Validate all files in workflows/
+crewx workflow validate workflows/standard-dev.yaml  # Validate a specific file
+```
+
+### `workflow run start <id|file>`
+
+Creates a new execution instance. State is stored as a JSON file in `.crewx/workflow-runs/`.
+
+```bash
+crewx workflow run start standard-dev-core
+crewx workflow run start standard-dev-core --set goal="build auth module"
+crewx workflow run start workflows/idea-validation.yaml
+```
+
+### `workflow run state <exec-id>`
+
+Query or modify execution state.
+
+```bash
+crewx workflow run state wfr_abc12345                          # View state
+crewx workflow run state wfr_abc12345 --set result="completed" # Set a value
+echo "Long text..." | crewx workflow run state wfr_abc12345 --set analysis=-  # Pipe via stdin
+```
+
+### `workflow run node <exec-id> <node-id>`
+
+Move to a node: sets `current_node` and appends to `completed_nodes`. For `agent_task` nodes, triggers agent execution via `crewx q/x`.
+
+```bash
+crewx workflow run node wfr_abc12345 research
+crewx workflow run node wfr_abc12345 end
+```
+
+### `workflow run reset <exec-id>`
+
+Restores execution state to `initial_state`.
+
+```bash
+crewx workflow run reset wfr_abc12345
+```
+
+### `workflow run list`
+
+Lists all execution instances.
+
+```bash
+crewx workflow run list
+crewx workflow run list --json
+```
+
+All `run` subcommands support the `--json` flag.
+
+## Name Resolution
+
+`<id|file>` resolves in this order:
+
+1. `.yaml` / `.yml` extension -> treated as direct file path
+2. Workflow ID -> scans all YAML files for matching `workflows:` key
+3. Filename slug -> `workflows/<name>.yaml`
+
+## Workflow YAML Structure
+
+```yaml
+workflows:
+  process-name:
+    metadata:
+      name: "Process Name"
+      description: "What this workflow does"
+      version: "1.0"
+    timeout: 300          # Global timeout (seconds)
+    max_iterations: 50    # Max node transitions
+    state:                # Initial state variables
+      goal: ""
+      result: ""
+    nodes:
+      step_id:
+        type: agent_task
+        ...
+```
+
+### Top-Level Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `metadata` | object | No | `name` (required), `description`, `version` |
+| `timeout` | number | No | Global timeout in seconds |
+| `max_iterations` | number | No | Maximum node transitions |
+| `state` | object | No | Initial state variables (accessible via `{{var}}`) |
+| `nodes` | object | **Yes** | Node definitions (keyed by node ID) |
+
+## Node Types
+
+### `agent_task` -- Assign task to an agent
+
+```yaml
+analyze:
+  type: agent_task
+  agent: tax_lawyer
+  mode: query              # query (read-only) | execute (read-write)
+  input: |
+    Analyze the tax law: {{user_input}}
+  output: law_analysis     # State key to store the result
+  next: calculate
+```
+
+### `parallel` -- Fan-out to concurrent branches
+
+```yaml
+parallel_review:
+  type: parallel
+  branches: [cpo_review, persona_survey]
+  join: merge_feedback     # Node to converge at
+```
+
+### `join` -- Fan-in from parallel branches
+
+```yaml
+merge_feedback:
+  type: join
+  on_failure: continue     # continue even if a branch failed
+  next: check_quality
+```
+
+### `branch` -- Conditional routing
+
+```yaml
+check_approval:
+  type: branch
+  condition: "state.cpo_feedback.includes('approved')"
+  branches:
+    "true": end
+    "false": persona_survey
+  default: persona_survey
+```
+
+### `approval` -- Wait for human decision
+
+```yaml
+human_check:
+  type: approval
+  description: "Would you like to review and approve the result?"
+  assignee: "@manager"
+  on_approve: publish
+  on_reject: revise
+```
+
+### `expression` -- Safe state computation
+
+Evaluates safe expressions (arithmetic, string, comparison, ternary) and stores results in state. No agent call -- runs instantly.
+
+**Allowed:** `+`, `-`, `*`, `/`, `%`, `>`, `<`, `>=`, `<=`, `==`, `!=`, `&&`, `||`, `!`, `? :`, `()`, number/string/boolean literals, state variable references.
+
+**Blocked:** `require`, `import`, `process`, `eval`, `Function`, `.` (property access), `[` (bracket access), `__proto__`, `constructor`, `prototype`.
+
+```yaml
+# Increment counter
+increment_fix:
+  type: expression
+  set:
+    fix_count: "fix_count + 1"
+  next: fix
+
+# Multiple keys
+calculate:
+  type: expression
+  set:
+    score: "(pass_count / total_count) * 100"
+    remaining: "max_retry - fix_count"
+    summary: "wi_id + ' - attempt ' + fix_count"
+  next: check_score
+
+# Ternary
+decide:
+  type: expression
+  set:
+    action: "fix_count > 3 ? 'escalate' : 'retry'"
+  next: route
+```
+
+State values are auto-coerced: numeric strings become numbers for arithmetic, results are stored as strings.
+
+### `end` -- Termination
+
+```yaml
+end:
+  type: end
+```
+
+## Common Node Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `timeout` | number | Per-node timeout in seconds |
+| `retry` | object | `{ max, delay: "exponential" \| "fixed" }` |
+| `hooks` | string[] | Hook packages to apply |
+| `on_failure` | string | `fail_fast` \| `continue` \| `ignore` |
+| `on_error` | object | `{ handler?, fallback_node? }` |
+| `comment` | string | Human-readable annotation |
+
+## Template Syntax
+
+Use `{{variable_name}}` in `input` fields to reference `state` values.
+
+```yaml
+state:
+  goal: "implement auth"
+nodes:
+  plan:
+    type: agent_task
+    agent: architect
+    input: "Create a plan for: {{goal}}"
+    output: plan_result
+    next: implement
+```
+
+## Programmatic API
+
+### WorkflowEngine
+
+YAML loading, validation, and Mermaid generation. Used by both CLI and server.
+
+```typescript
+import { WorkflowEngine } from '@crewx/workflow';
+
+const engine = new WorkflowEngine();
+
+// Load all workflows from a directory
+const workflows: LoadedWorkflow[] = engine.loadWorkflows('workflows/');
+
+// Validate a workflow file (schema -> fields -> references)
+const result = engine.validateFile('workflows/standard-dev.yaml');
+// { success: boolean; results: ValidationResult[]; error?: string }
+
+// Generate Mermaid diagram
+const mermaid: string = engine.toMermaid(spec);
+```
+
+### RunManager
+
+Execution state management. Stores state as JSON files in `.crewx/workflow-runs/`.
+
+```typescript
+import { RunManager } from '@crewx/workflow';
+
+const manager = new RunManager();
+
+// Start execution
+const exec: RunExecution = manager.start('workflows/dev.yaml', 'dev-core', { goal: 'build feature' });
+
+// Execute a node (triggers agent call for agent_task nodes)
+const updated: RunExecution = await manager.executeNode(exec.id, 'research');
+
+// Move to node without executing
+const moved: RunExecution = manager.moveNode(exec.id, 'implement');
+```
+
+### Key Types
+
+```typescript
+type NodeType = 'agent_task' | 'parallel' | 'join' | 'branch' | 'approval' | 'expression' | 'end';
+
+interface RunExecution {
+  id: string;                          // 'wfr_{nanoid(8)}'
+  workflow_id: string;
+  workflow_file: string;
+  created_at: string;                  // ISO 8601
+  updated_at: string;
+  current_node: string;
+  completed_nodes: string[];
+  state: Record<string, unknown>;
+  initial_state: Record<string, unknown>;
+  status?: 'running' | 'completed' | 'failed';
+}
+```
+
+## Architecture
+
+```
+[CLI]  crewx workflow list/show/validate
+         |
+         v
+    WorkflowEngine  <-- YAML parsing, validation, Mermaid
+         |
+         v
+    workflows/*.yaml  (source files)
+
+[CLI]  crewx workflow run start/node/state
+         |
+         v
+    RunManager  <-- execution state management
+         |
+         +---> .crewx/workflow-runs/wfr_*.json  (state files)
+         +---> crewx q/x  (agent invocation for agent_task nodes)
+
+[Server]  GET /api/v1/workflows[/:id]
+         |
+         v
+    WorkflowService  --> fs (YAML read) + WorkflowEngine.toMermaid()
+```
+
+> **Note:** The server only uses `WorkflowEngine.toMermaid()`. YAML listing/parsing is handled by the server's own `WorkflowService`. `RunManager` (execution state) is CLI-only.
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CREWX_WORKSPACE` | Workspace directory (where `workflows/` lives) | `.` |
+| `CREWX_CLI` | CrewX CLI path (for agent execution in `run node`) | `npx crewx` |
+| `CREWX_WORKFLOW_TIMEOUT` | Node execution timeout (ms) | `1800000` (30 min) |
+| `CREWX_CONFIG` | Custom config file path | `crewx.yaml` |
+
+## WARNING: Check Agent List Before Designing
+
+**Specifying a non-existent agent in a workflow will prevent execution!** Always verify available agents first:
+
+```bash
+crewx agent ls
+```
+
+## File Layout
+
+```
+workflows/                      # Workflow YAML sources
+  standard-dev.yaml
+  idea-validation.yaml
+.crewx/workflow-runs/           # Execution state (auto-created)
+  wfr_abc12345.json
+packages/built-in/workflow/     # Package source
+  cli.ts                        # CLI entrypoint
+  src/
+    types.ts                    # TypeScript interfaces
+    engine.ts                   # WorkflowEngine
+    mermaid.ts                  # Mermaid diagram renderer
+    run-manager.ts              # RunManager
+  workflow-schema.json          # JSON Schema for validation
+```