Wf Composer

Workflow Design

Parse user's semantic workflow description → decompose into nodes → map to executors → auto-inject checkpoints → confirm pipeline → save as reusable workflow-template.json.

Architecture

User describes workflow in natural language
  -> Phase 1: Parse — extract intent steps + variables
  -> Phase 2: Resolve — map each step to executor (skill/cli/agent/command)
  -> Phase 3: Enrich — inject checkpoint nodes, set DAG edges
  -> Phase 4: Confirm — visualize pipeline, user approval/edit
  -> Phase 5: Persist — save .workflow/templates/<name>.json

Shared Constants

Entry Router

Parse $ARGUMENTS.

Phase 0: Resume / Edit (optional)

Resume design session: 1. Scan .workflow/templates/design-drafts/WFD-*.json for in-progress designs 2. Multiple found → AskUserQuestion for selection 3. Load draft → skip to last incomplete phase

Edit existing template: 1. Load template from --edit path 2. Show current pipeline visualization 3. AskUserQuestion: which nodes to modify/add/remove 4. Re-enter at Phase 3 (Enrich) with edits applied

---

Phase 1: Parse

Read phases/01-parse.md and execute.

Objective: Extract structured semantic steps + context variables from natural language.

Success: design-session/intent.json written with: steps[], variables[], task_type, complexity.

---

Phase 2: Resolve

Read phases/02-resolve.md and execute.

Objective: Map each intent step to a concrete executor node.

Executor types:

• skill — invoke via Skill(skill=..., args=...)
• cli — invoke via ccw cli -p "..." --tool ... --mode ...
• command — invoke via Skill(skill="<namespace:command>", args=...)
• agent — invoke via Agent(subagent_type=..., prompt=...)
• checkpoint — state save + optional user pause

Success: design-session/nodes.json written with resolved executor for each step.

---

Phase 3: Enrich

Read phases/03-enrich.md and execute.

Objective: Build DAG edges, auto-inject checkpoints at phase boundaries, validate port compatibility.

Checkpoint injection rules:

• After every skill → skill transition that crosses a semantic phase boundary
• Before any long-running agent spawn
• After any node that produces a persistent artifact (plan, spec, analysis)
• At user-defined breakpoints (if any)

Success: design-session/dag.json with nodes[], edges[], checkpoints[], context_schema{}.

---

Phase 4: Confirm

Read phases/04-confirm.md and execute.

Objective: Visualize the pipeline, present to user, incorporate edits.

Display format:

Pipeline: <template-name>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
N-001 [skill]      workflow-lite-plan       "{goal}"
  |
CP-01 [checkpoint] After Plan               auto-continue
  |
N-002 [skill]      workflow-test-fix        "--session N-001"
  |
CP-02 [checkpoint] After Tests              pause-for-user
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Variables: goal (required)
Checkpoints: 2 (1 auto, 1 pause)

AskUserQuestion:

• Confirm & Save
• Edit node (select node ID)
• Add node after (select position)
• Remove node (select node ID)
• Rename template

Success: User confirmed pipeline. Final dag.json ready.

---

Phase 5: Persist

Read phases/05-persist.md and execute.

Objective: Assemble final template JSON, write to template library, output summary.

Output:

• .workflow/templates/<slug>.json — the reusable template
• Console summary with template path + usage command

Success: Template saved. User shown: Skill(skill="wf-player", args="<template-path>")

---

Specs Reference

Phase 1: Parse — Semantic Intent Extraction

Objective

Extract structured semantic steps and context variables from the user's natural language workflow description.

Workflow

Step 1.1 — Read Input

Parse $ARGUMENTS as the workflow description. If empty or ambiguous, AskUserQuestion:

• "Describe the workflow you want to automate. Include: what steps to run, in what order, and what varies each time (inputs)."

Step 1.2 — Extract Steps

Scan the description for sequential actions. Each action becomes a candidate node.

Signal patterns (not exhaustive — apply NL understanding):

Step 1.3 — Extract Variables

Identify inputs that vary per run. These become context_schema entries.

Variable detection:

• Direct mentions: "the goal", "the target", "my task", "user-provided X"
• Parameterized slots: {goal}, [feature], <scope> patterns in the description
• Implicit from task type: any "feature/bugfix/topic" is goal

For each variable: assign name, type (string|path|boolean), required flag, description.

Step 1.4 — Detect Task Type

Use ccw-coordinator task detection logic to classify the overall workflow:

bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap |
refactor | integration-test | greenfield | quick-task | custom

custom = user describes a non-standard combination.

Step 1.5 — Complexity Assessment

Count nodes, detect parallel tracks, identify dependencies:

• simple = 1-3 nodes, linear
• medium = 4-7 nodes, at most 1 parallel track
• complex = 8+ nodes or multiple parallel tracks

Step 1.6 — Write Output

Create session dir: .workflow/templates/design-drafts/WFD-<slug>-<date>/

Write intent.json:

{
  "session_id": "WFD-<slug>-<date>",
  "raw_description": "<original user input>",
  "task_type": "<detected type>",
  "complexity": "simple|medium|complex",
  "steps": [
    {
      "seq": 1,
      "description": "<extracted step description>",
      "type_hint": "analysis|planning|execution|testing|review|checkpoint|agent|cli",
      "parallel_with": null,
      "variables": ["goal"]
    }
  ],
  "variables": {
    "goal": { "type": "string", "required": true, "description": "<inferred description>" }
  },
  "created_at": "<ISO timestamp>"
}

Success Criteria

• intent.json exists with at least 1 step
• All referenced variables extracted to variables map
• task_type and complexity assigned

Phase 2: Resolve — Map Steps to Executor Nodes

Objective

Map each intent step from intent.json into a concrete executor node with assigned type, executor, and arg template.

Workflow

Step 2.1 — Load Intent

Read design-session/intent.json. Load steps[], variables{}.

Step 2.2 — Map Each Step to Executor

For each step, determine the executor node using the Node Catalog (specs/node-catalog.md).

Resolution algorithm: 1. Match type_hint to executor candidates in catalog 2. If multiple candidates, select by semantic fit to step description 3. If no catalog match, emit cli node with inferred --rule and --mode

Node type assignment:

Step 2.3 — Build Arg Templates

For each node, build args_template by substituting variable references:

skill node:   args_template = `{goal}`  (or `--session {prev_session}`)
cli node:     args_template = `PURPOSE: {goal}\nTASK: ...\nMODE: analysis\nCONTEXT: @**/*`
agent node:   args_template = `{goal}\nContext: {prev_output}`

Context injection rules:

• Planning nodes that follow analysis: inject --context {prev_output_path}
• Execution nodes that follow planning: inject --resume-session {prev_session_id}
• Testing nodes that follow execution: inject --session {prev_session_id}

Use {prev_session_id} and {prev_output_path} as runtime-resolved references — the executor will substitute these from node state at run time.

Step 2.4 — Assign Parallel Groups

For steps with parallel_with set:

• Assign same parallel_group string to both nodes
• Parallel nodes share no data dependency (each gets same input)

Step 2.5 — Write Output

Write design-session/nodes.json:

{
  "session_id": "<WFD-id>",
  "nodes": [
    {
      "id": "N-001",
      "seq": 1,
      "name": "<step description shortened>",
      "type": "skill|cli|command|agent|checkpoint",
      "executor": "<skill name | cli command | agent subagent_type>",
      "args_template": "<template string with {variable} placeholders>",
      "input_ports": ["<port>"],
      "output_ports": ["<port>"],
      "parallel_group": null,
      "on_fail": "abort"
    }
  ]
}

Success Criteria

• Every intent step has a corresponding node in nodes.json
• Every node has a non-empty executor and args_template
• Parallel groups correctly assigned where step.parallel_with is set

Phase 3: Enrich — Inject Checkpoints + Build DAG

Objective

Build the directed acyclic graph (DAG) with proper edges, auto-inject checkpoint nodes at phase boundaries, and finalize the context_schema.

Workflow

Step 3.1 — Load Nodes

Read design-session/nodes.json. Get nodes[] list.

Step 3.2 — Build Sequential Edges

Start with a linear chain: N-001 → N-002 → N-003 → ...

For nodes with the same parallel_group:

• Remove edges between them
• Add fan-out from the last non-parallel node to all group members
• Add fan-in from all group members to the next non-parallel node

Step 3.3 — Auto-Inject Checkpoint Nodes

Scan the edge list and inject a checkpoint node between edges that cross a phase boundary.

Phase boundary detection rules (inject checkpoint if ANY rule triggers):

Checkpoint node template:

{
  "id": "CP-<seq>",
  "name": "Checkpoint: <description>",
  "type": "checkpoint",
  "description": "<what was just completed>",
  "auto_continue": true,
  "save_fields": ["session_id", "artifacts", "output_path"]
}

Set auto_continue: false for checkpoints that:

• Precede a user-facing deliverable (spec, plan, review report)
• Are explicitly requested by the user ("pause and show me")

Step 3.4 — Insert Checkpoint Edges

For each injected checkpoint CP-X between edge (A → B):

• Remove edge A → B
• Add edges: A → CP-X, CP-X → B

Step 3.5 — Finalize context_schema

Aggregate all {variable} references found in nodes' args_template strings.

For each unique variable name found:

• Look up from intent.json#variables if already defined
• Otherwise infer: type=string, required=true, description="<variable name>"

Produce final context_schema{} map.

Step 3.6 — Validate DAG

Check:

• No cycles (topological sort must succeed)
• No orphan nodes (every node reachable from start)
• Every non-start node has at least one incoming edge
• Every non-terminal node has at least one outgoing edge

On cycle detection: report error, ask user to resolve.

Step 3.7 — Write Output

Write design-session/dag.json:

{
  "session_id": "<WFD-id>",
  "nodes": [ /* all nodes including injected checkpoints */ ],
  "edges": [
    { "from": "N-001", "to": "CP-01" },
    { "from": "CP-01", "to": "N-002" }
  ],
  "checkpoints": ["CP-01", "CP-02"],
  "parallel_groups": { "<group-name>": ["N-003", "N-004"] },
  "context_schema": {
    "goal": { "type": "string", "required": true, "description": "..." }
  },
  "topological_order": ["N-001", "CP-01", "N-002"]
}

Success Criteria

• dag.json exists and is valid (no cycles)
• At least one checkpoint exists (or user explicitly opted out)
• context_schema contains all variables referenced in args_templates
• topological_order covers all nodes

Phase 4: Confirm — Visualize + User Approval

Objective

Render the pipeline as an ASCII diagram, present to user for confirmation and optional edits.

Workflow

Step 4.1 — Render Pipeline

Load design-session/dag.json. Render in topological order:

Pipeline: <template-name>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 N-001  [skill]       workflow-lite-plan         "{goal}"
   |
 CP-01  [checkpoint]  After Plan                 auto-continue
   |
 N-002  [skill]       workflow-execute            --resume {N-001.session_id}
   |
 CP-02  [checkpoint]  Before Review              pause-for-user
   |
 N-003  [skill]       review-cycle               --session {N-002.session_id}
   |
 N-004  [skill]       workflow-test-fix           --session {N-002.session_id}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Variables (required):  goal
Checkpoints:           2  (1 auto-continue, 1 pause-for-user)
Nodes:                 4 work + 2 checkpoints

For parallel groups, show fan-out/fan-in:

 N-003a [skill]  review-cycle    ─┐
                                   ├─ N-004 [skill] workflow-test-fix
 N-003b [cli]    gemini analysis  ─┘

Step 4.2 — Ask User

AskUserQuestion({
  questions: [{
    question: "Review the workflow pipeline above.",
    header: "Confirm Pipeline",
    options: [
      { label: "Confirm & Save", description: "Save as reusable template" },
      { label: "Edit a node", description: "Modify executor or args of a specific node" },
      { label: "Add a node", description: "Insert a new step at a position" },
      { label: "Remove a node", description: "Delete a step from the pipeline" },
      { label: "Rename template", description: "Change the template name" },
      { label: "Re-run checkpoint injection", description: "Reset and re-inject checkpoints" },
      { label: "Cancel", description: "Discard and exit" }
    ]
  }]
})

Step 4.3 — Handle Edit Actions

Edit a node:

• AskUserQuestion: "Which node ID to edit?" → show fields → apply change
• Re-render pipeline and re-ask

Add a node:

• AskUserQuestion: "Insert after which node ID?" + "Describe the new step"
• Re-run Phase 2 (resolve) for the new step description
• Insert new node + update edges
• Re-run Phase 3 (enrich) for checkpoint injection
• Re-render and re-ask

Remove a node:

• AskUserQuestion: "Which node ID to remove?"
• If node is a checkpoint: also remove it, re-wire edges
• If node is a work node: re-wire edges, re-run checkpoint injection
• Re-render and re-ask

Rename template:

• AskUserQuestion: "New template name?"
• Update slug for template_id

Step 4.4 — Finalize

On "Confirm & Save":

• Freeze dag.json (mark as confirmed)
• Proceed to Phase 5

On "Cancel":

• Save draft to design-session/dag-draft.json
• Output: "Draft saved. Resume with: Skill(skill='wf-composer', args='--resume <session-id>')"
• Exit

Success Criteria

• User selected "Confirm & Save"
• dag.json frozen with all user edits applied

Phase 5: Persist — Assemble + Save Template

Objective

Assemble the final workflow template JSON from design session data, write to template library, output usage instructions.

Workflow

Step 5.1 — Load Design Session

Read:

• design-session/intent.json → template metadata
• design-session/dag.json → nodes, edges, checkpoints, context_schema

Step 5.2 — Determine Template Name + Path

Name: Use user's confirmed name from Phase 4. If not set, derive from intent.task_type + first 3 meaningful words of raw_description.

Slug: kebab-case from name (e.g. "Feature TDD with Review" → "feature-tdd-with-review")

Path: .workflow/templates/<slug>.json

template_id: wft-<slug>-<YYYYMMDD>

Check for existing file:

• If exists and different content: append -v2, -v3, etc.
• If exists and identical: skip write, output "Template already exists"

Step 5.3 — Assemble Template JSON

See specs/template-schema.md for full schema. Assemble:

{
  "template_id": "wft-<slug>-<date>",
  "name": "<human name>",
  "description": "<raw_description truncated to 120 chars>",
  "version": "1.0",
  "created_at": "<ISO timestamp>",
  "source_session": "<WFD-id>",
  "tags": ["<task_type>", "<complexity>"],
  "context_schema": { /* from dag.json */ },
  "nodes": [ /* from dag.json, full node objects */ ],
  "edges": [ /* from dag.json */ ],
  "checkpoints": [ /* checkpoint node IDs */ ],
  "atomic_groups": [ /* from intent.json parallel groups */ ],
  "execution_mode": "serial",
  "metadata": {
    "node_count": <n>,
    "checkpoint_count": <n>,
    "estimated_duration": "<rough estimate based on node types>"
  }
}

Step 5.4 — Write Template

Write assembled JSON to .workflow/templates/<slug>.json.

Ensure .workflow/templates/ directory exists (create if not).

Step 5.5 — Update Template Index

Read/create .workflow/templates/index.json:

{
  "templates": [
    {
      "template_id": "wft-<slug>-<date>",
      "name": "<name>",
      "path": ".workflow/templates/<slug>.json",
      "tags": ["<task_type>"],
      "created_at": "<ISO>",
      "node_count": <n>
    }
  ]
}

Append or update entry for this template. Write back.

Step 5.6 — Output Summary

Template saved: .workflow/templates/<slug>.json
  ID:          wft-<slug>-<date>
  Nodes:       <n> work nodes + <n> checkpoints
  Variables:   <comma-separated required vars>

To execute:
  Skill(skill="wf-player", args="<slug> --context goal='<your goal>'")

To edit later:
  Skill(skill="wf-composer", args="--edit .workflow/templates/<slug>.json")

To list all templates:
  Skill(skill="wf-player", args="--list")

Step 5.7 — Clean Up Draft

Delete design-session/ directory (or move to .workflow/templates/design-drafts/archive/).

Success Criteria

• .workflow/templates/<slug>.json exists and is valid JSON
• index.json updated with new entry
• Console shows template path + usage command

Node Catalog — Available Executors

All executors available for node resolution in Phase 2.

Skill Nodes

Command Nodes (namespace skills)

CLI Nodes

CLI nodes use ccw cli with a tool + mode + rule.

CLI node args_template format:

PURPOSE: {goal}
TASK: • [derived from step description]
MODE: analysis
CONTEXT: @**/* | Memory: {memory_context}
EXPECTED: [derived from step output_ports]
CONSTRAINTS: {scope}

Agent Nodes

Agent node args_template format:

Task: {goal}

Context from previous step:
{prev_output}

Deliver: [specify expected output format]

Checkpoint Nodes

Checkpoints are auto-generated — not selected from catalog.

Set auto_continue: false when:

• The next node is user-facing (plan display, spec review)
• The user requested an explicit pause in their workflow description
• The next node spawns a background agent (give user chance to cancel)

Workflow Template Schema

File Location

.workflow/templates/<slug>.json

Full Schema

{
  "template_id": "wft-<slug>-<YYYYMMDD>",
  "name": "Human readable template name",
  "description": "Brief description of what this workflow achieves",
  "version": "1.0",
  "created_at": "2026-03-17T10:00:00Z",
  "source_session": "WFD-<slug>-<date>",
  "tags": ["feature", "medium"],

  "context_schema": {
    "goal": {
      "type": "string",
      "required": true,
      "description": "Main task goal or feature to implement"
    },
    "scope": {
      "type": "string",
      "required": false,
      "description": "Target file or module scope",
      "default": "src/**/*"
    }
  },

  "nodes": [
    {
      "id": "N-001",
      "name": "Plan Feature",
      "type": "skill",
      "executor": "workflow-lite-plan",
      "args_template": "{goal}",
      "input_ports": ["requirement"],
      "output_ports": ["plan"],
      "parallel_group": null,
      "on_fail": "abort"
    },
    {
      "id": "CP-01",
      "name": "Checkpoint: After Plan",
      "type": "checkpoint",
      "description": "Plan artifact saved before execution proceeds",
      "auto_continue": true,
      "save_fields": ["session_id", "artifacts", "output_path"]
    },
    {
      "id": "N-002",
      "name": "Execute Implementation",
      "type": "skill",
      "executor": "workflow-execute",
      "args_template": "--resume-session {N-001.session_id}",
      "input_ports": ["plan"],
      "output_ports": ["code"],
      "parallel_group": null,
      "on_fail": "abort"
    },
    {
      "id": "CP-02",
      "name": "Checkpoint: Before Testing",
      "type": "checkpoint",
      "description": "Implementation complete, ready for test validation",
      "auto_continue": true,
      "save_fields": ["session_id", "artifacts"]
    },
    {
      "id": "N-003",
      "name": "Run Tests",
      "type": "skill",
      "executor": "workflow-test-fix",
      "args_template": "--session {N-002.session_id}",
      "input_ports": ["code"],
      "output_ports": ["test-passed"],
      "parallel_group": null,
      "on_fail": "abort"
    }
  ],

  "edges": [
    { "from": "N-001", "to": "CP-01" },
    { "from": "CP-01", "to": "N-002" },
    { "from": "N-002", "to": "CP-02" },
    { "from": "CP-02", "to": "N-003" }
  ],

  "checkpoints": ["CP-01", "CP-02"],

  "atomic_groups": [
    {
      "name": "planning-execution",
      "nodes": ["N-001", "CP-01", "N-002"],
      "description": "Plan must be followed by execution"
    }
  ],

  "execution_mode": "serial",

  "metadata": {
    "node_count": 3,
    "checkpoint_count": 2,
    "estimated_duration": "20-40 min"
  }
}

Node Type Definitions

skill node

{
  "id": "N-<seq>",
  "name": "<descriptive name>",
  "type": "skill",
  "executor": "<skill-name>",
  "args_template": "<string with {variable} and {prev-node-id.field} refs>",
  "input_ports": ["<port-name>"],
  "output_ports": ["<port-name>"],
  "parallel_group": "<group-name> | null",
  "on_fail": "abort | skip | retry"
}

cli node

{
  "id": "N-<seq>",
  "name": "<descriptive name>",
  "type": "cli",
  "executor": "ccw cli",
  "cli_tool": "gemini | qwen | codex",
  "cli_mode": "analysis | write",
  "cli_rule": "<rule-template-name>",
  "args_template": "PURPOSE: {goal}\nTASK: ...\nMODE: analysis\nCONTEXT: @**/*\nEXPECTED: ...\nCONSTRAINTS: ...",
  "input_ports": ["analysis-topic"],
  "output_ports": ["analysis"],
  "parallel_group": null,
  "on_fail": "abort"
}

command node

{
  "id": "N-<seq>",
  "name": "<descriptive name>",
  "type": "command",
  "executor": "workflow:refactor-cycle",
  "args_template": "{goal}",
  "input_ports": ["codebase"],
  "output_ports": ["refactored-code"],
  "parallel_group": null,
  "on_fail": "abort"
}

agent node

{
  "id": "N-<seq>",
  "name": "<descriptive name>",
  "type": "agent",
  "executor": "general-purpose",
  "args_template": "Task: {goal}\n\nContext from previous step:\n{prev_output}",
  "input_ports": ["requirement"],
  "output_ports": ["analysis"],
  "parallel_group": "<group-name> | null",
  "run_in_background": false,
  "on_fail": "abort"
}

checkpoint node

{
  "id": "CP-<seq>",
  "name": "Checkpoint: <description>",
  "type": "checkpoint",
  "description": "<what was just completed, what comes next>",
  "auto_continue": true,
  "save_fields": ["session_id", "artifacts", "output_path"]
}

Runtime Reference Syntax

In args_template strings, these references are resolved at execution time by wf-player: