/goal Quickstart

Run a bounded long-horizon goal in under five minutes.

Create a goal

Pass the objective as a positional argument, with hard budgets and a workspace root. Write the contract to a file with --output so you can review and run it.

picasso goal create "summarize the auth module changes since main" \
  --workspace-root . \
  --max-wall-time 30m \
  --max-cost-usd 2 \
  --max-steps 20 \
  --max-subagent-spawns 4 \
  --output goal.yaml

Expected result:

• Picasso writes a goal contract.
• The contract includes objective, scope, budgets, completion criteria, and allowed tools.
• The goal can be validated before running.

Validate the contract

picasso goal validate goal.yaml

Expected result:

• Schema validation passes.
• All budget fields are present.
• Completion criteria are concrete.

Run the goal

picasso goal run goal.yaml

Expected result:

• The loop enters PLAN, ACT, OBSERVE, and ASSESS phases.
• The TUI /goal monitor shows budget, state, current tool, memory writes, and iteration timeline.
• If a cap is hit, the goal pauses with a resume token instead of failing silently.

Monitor from the TUI

Inside Picasso:

/goal monitor

The monitor shows:

• Current state: running, retrying, paused, failed, or completed.
• Budget tiles for wall time, cost, steps, and subagents.
• Current tool work.
• Memory writes.
• Resume controls.

Resume

picasso goal resume <goal-id>

Use resume after:

• Wall-time cap reached.
• Cost cap reached.
• Provider credit exhausted.
• Crash recovery from a checkpoint.

Good first goal shape

objective: Summarize auth module behavior changes since main.
completionCriteria:
  - type: all-tests-pass
    testCommand: pnpm test auth
  - type: agent-self-assesses-complete
    rubric: The summary names behavior changes, risk, and verification.
budget:
  maxWallTime: 30m
  maxCostUSD: 2
  maxSteps: 20
  maxSubagentSpawns: 4
scope:
  allowedTools: [read_file, grep, glob, exec]
  allowedSubagents: [codebase_investigator]
  permissionMode: safe
  workspaceRoot: .