VLCode-Lite/docs/vlclaw-workflow-landing-plan.md

VLClaw Workflow Landing Plan

Why This Matters

/Users/ivx/Documents/VLClaw already contains most of a real multi-agent manager:

• Run state machine: run-manager.js
• Supervisor orchestrator: supervisor-core.js
• Worker queue + dispatch: task-queue.js
• Human inbox/gates: human-gate.js
• Descriptive supervisor workflow: project-delivery-supervisor.json

The core idea was correct: use a manager node to supervise multiple VLCode / Claude workers.

The main issue was not vision. It was execution shape:

• The manager logic lives partly in JS state machines and partly in chat conventions.
• Worker completion is still too coarse: “chat finished” is not the same as “task contract satisfied”.
• The old WorkflowRun path in VLCode-Lite was an async UI trigger, not a true child-workflow call.
• Result contracts are weak; artifacts/checkpoints/review state are not yet the primary source of truth.

Current Conclusion

The most practical path is:

1. Keep VLClaw's broker / instance / human-gate ideas.
2. Move the actual project-delivery orchestration into executable workflows.
3. Treat workers as child workflows or externally dispatched jobs with structured checkpoints and artifacts.

This gives VLClaw a real control plane instead of a mostly chat-driven manager.

What I Added In VLCode-Lite

To make this path real, VLCode-Lite now has one key new capability:

• WorkflowRun sync

File: workflow-run.js

What it does:

• Runs a child workflow synchronously inside the parent tool call.
• Returns structured result data: status, runID, filesWritten, variables, checkpoint, completedSteps, events.
• Forwards child workflow events upward through tool runtime messages, so the outer workflow/editor/UI can see them.

This is the missing primitive for “workflow managing workflows”.

Minimal Working Pattern

The smallest viable VLClaw manager pattern is:

1. Supervisor workflow receives goal, outputDir, constraints.
2. Supervisor fans out child workflows in parallel with Tool_WorkflowRun { mode: "sync" }.
3. Each child workflow writes artifacts and returns structured checkpoint variables.
4. Supervisor aggregates those results.
5. Quality gates run on artifacts and structured outputs.
6. If needed, pause at a human gate or rerun from a failed/rework node.

This is now demonstrated by:

• vlclaw-supervisor-prototype.json
• vlclaw-worker-spec.json
• vlclaw-worker-review.json
• test-workflow-run-sync.js

Recommended Architecture

1. Control Plane = Workflow

Use one workflow per project run as the canonical state machine.

Suggested top-level states:

• intake
• planning
• dispatching
• implementing
• self_testing
• reviewing
• reworking
• waiting_human
• done
• blocked

This matches the existing VLClaw run model and should replace ad-hoc orchestration branches in JS where possible.

2. Worker Plane = Two Execution Modes

Use two worker execution modes, both behind tools:

• Local child workflow

  • Best for deterministic or semi-deterministic work.
  • Use WorkflowRun sync.
  • Returns checkpoint/artifacts immediately to the manager workflow.

• External agent dispatch

  • Best for real VLCode / Claude instances with long-running interactive work.
  • Should become a dedicated tool pair:
  • DispatchTask
  • AwaitTask

The manager workflow should not care whether the worker is a local child workflow or a remote insect/primate. Both need the same result contract.

3. Artifact Plane = Local Files + Checkpoints

Every worker task should produce:

• task-result.json
• artifacts/*
• checkpoint.json
• optional review-input.json

The manager should review these, not only free-form chat text.

Required Next Tools For Real VLClaw

These are the next practical tools to add in VLClaw/VLCode-Lite if we want a production manager:

DispatchTask

Inputs:

• target
• goal
• scope
• constraints
• acceptanceCriteria
• conversationId?
• timeoutMs?

Output:

• taskId
• assignedTo
• startedAt

AwaitTask

Inputs:

• taskId
• pollMs?
• timeoutMs?

Output:

• status
• resultEnvelope
• artifacts
• taskEvents
• errorType?

RecordReview

Inputs:

• runId
• taskId?
• decision
• issues
• reworkInstructions

Output:

• persisted review object

HumanGate

Inputs:

• type
• question
• options
• context

Output:

• decision
• decisionAt

What Should Stay In JS

Not everything needs to become workflow nodes.

JS should still own:

• broker transport
• instance lifecycle
• port allocation
• OpenClaw desktop automation bridge
• persistent stores / indexes
• auth/cookie/spec sync

Workflow should own:

• run orchestration
• dispatch order
• review/rework loop
• checkpointed human gates
• artifact-driven decisions

What Should Change In VLClaw

These are the highest-value refactors, in order:

1. Replace “task done because chat stream ended” with a structured result envelope.
2. Make project-delivery-supervisor.json executable instead of descriptive-only.
3. Introduce DispatchTask / AwaitTask as workflow tools.
4. Move review/rework/human-gate transitions into workflow checkpoints.
5. Use workflow checkpoints as the canonical run state; JS mirrors them for dashboard/API use.

Practical Rollout Plan

Phase A: Local proof

Use only local child workflows and WorkflowRun sync.

Goal:

• prove that manager workflows can fan out workers, collect artifacts, and aggregate review state.

Status:

• done in VLCode-Lite via the new prototype/test.

Phase B: Hybrid manager

Replace one child workflow branch with real VLClaw task dispatch.

Goal:

• same supervisor workflow, but one branch uses DispatchTask/AwaitTask against real workers.

Phase C: Full VLClaw manager workflow

Run the entire project-delivery cycle as one resumable workflow:

• planning
• parallel implementation
• compile/test gates
• Codex review
• rework dispatch
• human approval

At that point, VLClaw becomes a real “manager of AI software engineers”, not only a broker plus dashboard.

Key Design Rule

The manager must reason over structured state, not only chat text.

That means:

• workflow checkpoints over ephemeral memory
• artifacts over prose summaries
• explicit review objects over “looks done”
• rerun from node over restarting the whole run

That is the path that makes the original VLClaw idea genuinely land.