# 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](/Users/ivx/Documents/VLClaw/manager/run-manager.js)
- Supervisor orchestrator: [supervisor-core.js](/Users/ivx/Documents/VLClaw/manager/supervisor-core.js)
- Worker queue + dispatch: [task-queue.js](/Users/ivx/Documents/VLClaw/manager/task-queue.js)
- Human inbox/gates: [human-gate.js](/Users/ivx/Documents/VLClaw/manager/human-gate.js)
- Descriptive supervisor workflow: [project-delivery-supervisor.json](/Users/ivx/Documents/VLClaw/workflows/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](/Users/ivx/Documents/VLCode-Lite/src/tools/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](/Users/ivx/Documents/VLCode-Lite/examples/workflows/vlclaw-supervisor-prototype.json)
- [vlclaw-worker-spec.json](/Users/ivx/Documents/VLCode-Lite/examples/workflows/vlclaw-worker-spec.json)
- [vlclaw-worker-review.json](/Users/ivx/Documents/VLCode-Lite/examples/workflows/vlclaw-worker-review.json)
- [test-workflow-run-sync.js](/Users/ivx/Documents/VLCode-Lite/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.