YYLO documentation

Install and initialize

npm install -g @yylo/cli@0.1.0-rc.24
yylo init --task "Describe one verifiable outcome" --subagent claude

The yy and yylo launchers are behaviorally equivalent. Use one installation; collisions or mixed legacy installs fail clearly.

Make the first run bounded

yy start -b shell -s claude -i 1 -v
# the long launcher is equivalent
yylo -b shell -s pi -i 1 -p "Fix the selected ready task and run its tests"

Use the System of Work layers

yy ledger --help
yy benchmark --help
# yylo ledger and yylo benchmark are equivalent

YYLO is the control plane, Ledger preserves Git-native task truth, and Benchmark retains evaluation evidence through independently installed contracts.

Repeat commands with yy loop

yy loop repeats arbitrary shell commands sequentially. Its -n/--iterations flag bounds the outer command workflow; the existing global and agent -i/--max-iterations flag keeps its meaning of bounding iterations inside one agent invocation. The loop never parses or rewrites yy pi, yy cc, clone, switch, or other provider commands.

yy loop -n 5 \
  --step 'yy pi "Implement the next increment"' \
  --step 'yy cc "Inspect and improve your work"' \
  --step 'npm test'

Save the same contract as YAML for a reusable workflow. CLI values override YAML top-level defaults, for example yy loop --workflow flow.yaml -n 2 --continuity run --on-error stop. The workflow accepts only iterations, continuity, on_error, and a nonempty ordered steps list; every step requires nonempty run text and may set its own on_error: continue|stop.

iterations: 5
continuity: iteration
on_error: continue
steps:
  - run: yy pi "Implement the next increment"
  - run: yy cc "Inspect and improve your work"
  - run: npm test

yy loop --workflow flow.yaml

Continuity controls which existing YYLO continue scope child commands share:

• iteration (default): every iteration gets a new scope. yy pi, yy cc, yy clone, and yy switch steps in that iteration share it; the next iteration is isolated.
• run: all iterations share one scope, enabling explicit continuation or cloning across iteration boundaries.
• shell: the loop injects no scope and preserves the caller’s inherited YYLO_CONTINUE_SCOPE behavior.

The default failure policy is continue: a failed step is recorded, the remaining steps in that iteration are skipped, and the next iteration starts. With --on-error stop (or a YAML step override of on_error: stop), nothing further is launched. Any failed command makes the final loop exit nonzero even if later iterations run. SIGINT/SIGTERM stop the active child and prevent later launches, and the terminal summary reports the loop ID with completed, failed, and skipped work.

Every step receives one-based loop metadata through YYLO_LOOP_ID, YYLO_ITERATION, YYLO_ITERATION_COUNT, YYLO_STEP, and YYLO_STEP_COUNT.

Mental model

Engineering Change direction

Task is today's operational unit. YYLO is progressively connecting task and lifecycle evidence into an Engineering Change record spanning intent, decisions, attempts, validated code, and eventually real-world outcomes. PR, deployment, production-outcome learning, and automatic workflow selection are direction rather than current-release claims.

Source

Review YYLO on GitHub.