Your First Vision

A step-by-step guide to submitting and tracking your first vision.

This guide walks you through submitting your first vision in Starweft and experiencing the full workflow of task decomposition, execution, and evaluation.

Prerequisites

Make sure the following preparations are complete.

Principal, owner, and worker nodes have been initialized with starweft init
Ed25519 identities have been created on each node with starweft identity create
Peers have been mutually registered with starweft peer add

Submitting a Vision

Prepare the vision text

A vision is a natural language description of the goal you want to achieve. To improve task decomposition accuracy, it is recommended to include:

Specific deliverables
Acceptance criteria
Risks and constraints

Preview with vision plan

Before actually submitting, you can preview the plan (task decomposition plan).

bash

starweft vision plan \
  --data-dir ./demo/principal \
  --title "Build a REST API" \
  --text "Build a Hello World REST API in Rust. Include a GET /health endpoint and verify behavior with tests."

The preview includes the following information:

task_count — Number of tasks the vision will be decomposed into
confidence — Confidence score for plan quality (0.0 to 1.0)
planning_risk — Risk assessment (low / medium / high)
missing_information — List of missing information
approval_token — Token for approval

Add constraints (recommended)

Specifying constraints with the --constraint flag improves the confidence score.

bash

starweft vision plan \
  --data-dir ./demo/principal \
  --title "Build a REST API" \
  --text "Build a Hello World REST API in Rust. Include a GET /health endpoint and verify behavior with tests." \
  --constraint budget_mode=balanced \
  --constraint allow_external_agents=true \
  --constraint human_intervention=required

Key constraints:

Constraint	Description	Recommended Value
`budget_mode`	Execution cost policy	`balanced`
`allow_external_agents`	Whether external agents are allowed	`true`
`human_intervention`	Whether human approval is required	`required`

Submit with vision submit

If the preview looks good, submit the vision.

bash

starweft vision submit \
  --data-dir ./demo/principal \
  --title "Build a REST API" \
  --text "Build a Hello World REST API in Rust. Include a GET /health endpoint and verify behavior with tests." \
  --constraint budget_mode=balanced \
  --constraint allow_external_agents=true \
  --constraint human_intervention=required

On success, a vision_id and msg_id are output.

plaintext

vision_id: 01J...
msg_id: 01J...
owner_actor_id: actor_...

Submission with Approval

When human_intervention=required is specified, an approval token is required before submission.

Obtain the approval token via preview

bash

starweft vision submit \
  --data-dir ./demo/principal \
  --title "Build a REST API" \
  --text "..." \
  --constraint human_intervention=required \
  --dry-run

Check the approval_token and approval_command in the output.

Submit with the approval token

bash

starweft vision submit \
  --data-dir ./demo/principal \
  --title "Build a REST API" \
  --text "..." \
  --constraint human_intervention=required \
  --approve <APPROVAL_TOKEN>

Monitoring Progress

Once the vision is submitted and nodes are running, the owner decomposes tasks and distributes them to workers.

Check node status

bash

starweft status --data-dir ./demo/principal

Use the --watch flag for real-time monitoring.

bash

starweft status --data-dir ./demo/owner --watch --interval-sec 3

View the project list

Visions are managed as "projects" on the owner node.

bash

starweft project list --data-dir ./demo/owner

You can also filter by status.

bash

starweft project list --data-dir ./demo/owner --status active

View the task tree

Display the task structure under a project in tree format.

bash

starweft task tree --data-dir ./demo/owner --project <PROJECT_ID>

View the task list

Display a flat task list. Filter conditions can also be specified.

bash

starweft task list --data-dir ./demo/owner --project <PROJECT_ID>
starweft task list --data-dir ./demo/owner --status running

Retrieve a snapshot

Retrieve a detailed snapshot of a specific project or task.

bash

starweft snapshot --data-dir ./demo/owner --project <PROJECT_ID>

Use --watch to periodically check for updates.

bash

starweft snapshot --data-dir ./demo/owner --project <PROJECT_ID> --watch

View the event log

View the history of message exchanges in chronological order.

bash

starweft events --data-dir ./demo/owner --project <PROJECT_ID> --tail 30

Use the --follow flag to track events in real time.

bash

starweft events --data-dir ./demo/owner --follow

TUI Dashboard

View real-time status in a TUI dashboard.

bash

starweft dashboard --data-dir ./demo/owner

Reviewing Results and Evaluation

Viewing evaluation results

When a task completes, the owner node performs a heuristic evaluation. Evaluation results are recorded in the event log.

bash

starweft events --data-dir ./demo/owner --msg-type evaluation_issued

Exporting artifacts

You can export project or task results as JSON.

bash

# Entire project
starweft export project --data-dir ./demo/owner --project <PROJECT_ID>
 
# Specific task
starweft export task --data-dir ./demo/owner --task <TASK_ID>
 
# Evaluation results
starweft export evaluation --data-dir ./demo/owner --project <PROJECT_ID>

Use --output to save to a file.

bash

starweft export project --data-dir ./demo/owner --project <PROJECT_ID> --output result.json

Stop Control

To stop the execution of a project or task tree, use the stop command from the principal node.

bash

starweft stop \
  --data-dir ./demo/principal \
  --project <PROJECT_ID> \
  --reason-code user_request \
  --reason "Stopping because the goal has been achieved" \
  --yes

To stop only a specific task tree:

bash

starweft stop \
  --data-dir ./demo/principal \
  --task-tree <TASK_ID> \
  --reason-code user_request \
  --reason "This task is no longer needed" \
  --yes

Loading a Vision from a File

Long vision texts can be loaded from a file.

bash

starweft vision submit \
  --data-dir ./demo/principal \
  --title "Large-scale refactoring" \
  --file ./vision.txt \
  --constraint human_intervention=required

JSON Output

All commands support the --json flag for machine-readable JSON output. This is useful when calling from scripts.

bash

starweft vision plan --data-dir ./demo/principal \
  --title "Test" --text "Test vision" --json

Next Steps

OpenClaw Integration

Connect OpenClaw to a Worker node to automatically execute tasks

Configuration Guide

Customize behavior with TOML configuration files

Multi-Machine Setup

Build node configurations spanning multiple machines