YYLO · stable 0.2.11

YYLO documentation

Install YYLO, run your first coding-agent task, and keep workflows, validation and Git delivery explicit.

On this page

Install and verify

Node.js 20.10+, npm, Git; install your chosen coding agent and configure provider credentials separately.

Stable is the default. The latest published prerelease is an explicit choice, not a stable upgrade. Source version 0.2.11 is tracked separately from publication.

npm install --global '@yylo/cli@0.2.11'

npm install --global '@yylo/cli@0.2.3-rc.3'

Registry channels checked 2026-10-07. A prerelease channel may be older than stable; compare the exact versions above.

yy --version
yy --help
# In a new project directory:
git init
yy init --task "Document onboarding" --subagent pi
pwd

Source candidate · check installed yy init --help

Choose Simple or Advanced

For a new project, the final interactive initialization question selects the workspace mode. This source behavior is not a claim about the stable release above.

Simple (recommended to start): code, notebooks, notes and Ledger in one Git checkout. Agents share files and the Git index; coordinate overlapping edits. Task completion is local bookkeeping, not managed delivery.
Advanced: a separate metadata controller, isolated task worktrees and managed merging. Use this when you need managed parallel development and protected-target delivery.

git init
yy init
# Guided Simple, skipping only the mode question:
yy init --interactive --mode simple
# Explicit Advanced automation:
yy init "Build an API" --mode advanced

Simple requires prior Git initialization, preserves existing project instructions, and does not install dependencies, stage, commit or create worktrees. The selected agent and project goal are saved locally. Leave the Advanced-only Git URL blank.

Existing inline automation stays Advanced. Noninteractive yy init --mode simple remains a read-only preview; use --plan-file then --apply-plan for reviewed setup. Normal initialization never converts an existing workspace; do not toggle the mode field manually.

Advanced to Simple: a fresh copy

For a settled registered metadata-only controller with a same-repository product branch, an explicit plan/apply flow creates a new Simple checkout. It preserves product history and committed Ledger data while leaving the original controller, registrations and worktrees unchanged. Simple to Advanced is unsupported, even with force.

yy init --mode simple --from-advanced /controller --directory /new-project --plan-file /external/conversion.json
yy init --mode simple --apply-plan /external/conversion.json

Stop writers and settle managed tasks first. Dirty worktrees, ignored durable data, symlinks, submodules, conflicting product-side Ledger data and existing destinations are refused. Other legacy or combined layouts are not supported.

Review inactive old instructions and settings under .juno_task/advanced-backup, restore only compatible project conventions, and configure agents, dependencies and credentials manually. No automatic remote, staging, commit, cleanup or live cutover occurs. The new Ledger is an independent snapshot. Preserve interrupted destinations for inspection; never delete a reservation to force startup.

Stable 0.2.11

First run

Run one small, verifiable change with your chosen coding agent.

The yy and yylo launchers are equivalent. Initialize a project, inspect local workspace health, then deliberately choose whether to contact a provider.

Agent invocations can use paid providers. Start with a read-only question; keep prompts in files when they contain shell-sensitive text.

yy --version
yy --help
yy info --json

yy pi --no-session 'Summarize this repository. Do not edit files.'

Boundary: Provider authentication and model availability belong to the agent, not YYLO.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Bounded command loops

Repeat a short sequence without hiding its stop conditions.

The outer loop uses -n/--iterations; -i/--max-iterations bounds work inside one agent invocation. Commands remain literal and sequential.

Reusable YAML can declare iterations, continuity, on_error and ordered run steps. Choose failure behavior deliberately.

yy loop -n 2 --step 'yy pi "Implement one verified increment"' --step 'npm test'

Boundary: Iteration limits do not grant spending, integration or production authority.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Sessions and models

Continue work without reconstructing it from terminal scrollback.

Use continue, clone, branches, switch and continuity for explicit session context. Model aliases are agent-specific; inspect installed help rather than assuming the same alias across agents.

yy pi --help
yy continue --help
yy continuity --help

Boundary: Provider sessions and project task state are different sources of truth.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Observe existing execution evidence

Read status without launching, retrying or completing work.

External agents implement, test and commit. Watch status, await and follow observe existing execution evidence only. A process exit is not task completion.

yy watch status RUN_ID
yy watch await RUN_ID
yy watch follow RUN_ID

Boundary: Observation never grants ownership, launches a producer or completes a task.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Task lifecycle and native Git delivery

Start a task worktree, validate a clean commit, then land exactly that task.

Run lifecycle commands from the registered metadata controller: the checkout owning task state. Implementation belongs in the feature worktree printed by task start, never the protected integration checkout.

Start freezes the target and completes configured dependency hydration. Preflight is read-only; finish queues a clean committed candidate. The target owner separately runs land.

Native merge performs no model calls, reviewer selection or test scheduling. Tests and reviews are explicit project checks. A moved target requires recomposition; preserve conflicts and dirty files.

Git integration and Ledger projection are separate. Successful land attempts projection automatically; use project only to retry a failed or stale projection, not to repeat integration.

Autonomous task run/resume and budget recovery are retired. Preserve interrupted work and verify current ownership before explicit continuation. Preflight is optional; finish independently enforces admission and validation.

yy task start TASK_ID
# Enter the returned worktree, implement, test and commit.
# Return to the controller.
yy task preflight TASK_ID
yy task finish TASK_ID
yy merge status TASK_ID
# Target owner only:
yy merge land TASK_ID

Boundary: Push, deployment, package publication and cleanup require separate authorization.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Versioned machine output

Read strict JSON or NDJSON rather than parsing terminal prose.

Task, merge and integration commands support --format json|ndjson --raw. Capabilities publishes command-specific projections. Ledger independently supports -f json|ndjson --raw.

yy capabilities --format json --raw
yy merge --format json --raw status TASK_ID

Boundary: Consumers must inspect schema and projection versions; stdout data is distinct from diagnostics.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md docs/machine-output.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Install agent skills

Install eight independently versioned skills, preserving customized copies.

YYLO stages acquisition, validates the selected skill tree and copies it to Claude, Codex and Pi locations. Differing or customized local skills are preserved unless replacement is explicitly authorized.

Install and update use the network; list and status are local reads. There is no silent skill refresh during ordinary product commands.

CLI 0.2.11 requires Skills ^2.1.1. Fresh Simple initialization installs skills by default; --no-skills opts out. CLI upgrades alone do not update installed skills.

yy skills install
yy skills status

Boundary: Skill instructions are not bundled runtime behavior. Review the selected version before installation.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Source candidate · publication not verified

Tmux workspaces

Organize local agent terminals and inspect workspace completion state.

The source tree contains session, window, unread and monitor commands. Documentation of their availability is deliberately separate from the package version number.

Inspect the installed command before use. A source checkout does not prove this surface exists in a published artifact.

yy tmux --help

Boundary: Source-only evidence: no published capability claim is made for tmux here.

Capability evidence

Source command and tests inspected; no published-artifact verification.

Verified exact releases: none; source only.

Package-owned source files: src/cli/commands/tmux.ts src/cli/__tests__/tmux-command.test.ts . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Managed scripts and workflows

Use parallel execution for independent work and workflows for ordered steps.

Fresh initialization installs managed scripts. Scripts update preserves customized files and reports conflicts; do not force replacement casually.

Workflow Runner retains rendered commands, stdout, stderr, responses, session IDs and manifests. Lint and dry-run a reviewed workflow before execution.

Parallel Runner caps fan-out; dependencies must remain explicit. Its per-item JSON and aggregation files are stronger evidence than terminal scrollback.

yy scripts update
./.juno_task/scripts/workflow_runner.sh lint --workflow workflow.yaml
./.juno_task/scripts/workflow_runner.sh --workflow workflow.yaml --dry-run

Boundary: Workflow storage in Ledger is separate from execution by a runner.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

Stable 0.2.11

Independent packages and compatibility

Use standalone Ledger and Benchmark, or compatible YYLO delegates.

Install all packages independently. Delegation preserves the canonical package command surface; it is not a bundled implementation.

CLI 0.2.11 declares Ledger 0.4.0 and Benchmark 0.2.1 exactly. Install matching standalone packages explicitly; delegation does not silently upgrade them.

yy ledger --help
yy benchmark --help
yy doctor workspace

Boundary: Compatibility comes from the installed CLI package, not the website latest label.

Capability evidence

Published README and package metadata reviewed on 2026-10-07. Current compatibility and skill count use package declarations where README prose is stale; no live-provider validation is claimed.

Verified exact releases: 0.2.11.

Package-owned source files: README.md . Their fingerprints are checked by the frontend generator.

These managed-script reference sections consolidate the former script documentation. Check the installed script help and project policy before execution; registry inventory alone does not verify every option in every release.

Parallel Runner

Run independent tasks or complete commands concurrently with a bounded worker pool.

When to use it

Items are independent, concurrency is explicitly capped, and each result can be reviewed separately.

Avoid: One step consumes another step’s output; model that sequence with Workflow Runner instead.

Prerequisites

An initialized .juno_task directory, installed scripts, valid task IDs or another input mode, and tmux only for tmux modes.

./.juno_task/scripts/parallel_runner.sh --kanban T1,T2 --parallel 2

Safety and evidence

Use ready tasks for dependency-aware work. Pi --live with tmux is supported only at --parallel 1. Lint raw command files before unattended runs.

Per-item JSON, parallel_runner_status.json, aggregation_*.json, logs, and an optional tmux_handoff_manifest.json under the printed output directory.

Troubleshooting

Inspect the status and aggregation JSON first; use parallel_runner_wait.sh for deterministic waits and --stop/--stop-all for sessions.

Bounded concurrent fan-out for independent kanban tasks, data items, or complete commands—with structured evidence for every item.

Use it for independent work

Choose Parallel Runner when each item can finish without consuming another item’s response. It owns queueing, a maximum worker count, per-item execution, and aggregation.

Do not use it to hide dependencies. Use Workflow Runner when outputs or session IDs must flow in order.

Prerequisites

Run yy init so project-local scripts and kanban exist.
Choose exactly one input: task IDs, kanban filter, items/file, or command file.
Include {{task_id}} or {{item}} in custom prompts.
Install tmux only when using windows, tabs, panes, or handoff.

Inputs and execution modes

Input	Best for
`--kanban` / `--kanban-filter ready`	Dependency-aware task fan-out
`--items-file`	JSONL, CSV, TSV, or XLSX records
`--commands-file`	Complete commands or multiple workflows

Headless mode logs in the background worker pool. Tmux windows/panes make work visible. --tmux-handoff never reuses completed panes and can split them with --max-panes-per-session.

Representative commands

./.juno_task/scripts/parallel_runner.sh --kanban-filter "ready" --parallel 3

./.juno_task/scripts/parallel_runner.sh --lint-commands-file workflows.yaml
./.juno_task/scripts/parallel_runner.sh --commands-file workflows.yaml --parallel 2

./.juno_task/scripts/parallel_runner.sh --tmux panes --no-attach --kanban T1,T2 --parallel 2
./.juno_task/scripts/parallel_runner_wait.sh --timeout 7200

Safety contract

Cap --parallel for provider quotas and shared files.
Run only ready tasks; related tasks are not dependency edges.
Pi --live with tmux is valid only with --parallel 1.
Use --strict only with --file-format; it fails an item when the expected fenced block is absent.
Lint raw command YAML before launching expensive work.

Artifacts and handoff

The printed output directory contains per-item JSON with exit code, elapsed time, final response and session ID; parallel_runner_status.json; logs; and aggregation_*.json. Capped handoff also writes tmux_handoff_manifest.json. Continue a captured session with yy continue SESSION_ID; do not reconstruct work from tmux scrollback.

Troubleshooting

Tail the printed log; the runner has no --verbose flag.
Inspect status and aggregation JSON before retrying.
Use --stop --name NAME or --stop-all for tmux sessions.
If a custom prompt ignores task context, verify its explicit placeholder.

Freshness sources

Reviewed against the current YYLO README sections Autonomous Execution and Parallel Execution, plus parallel_runner.sh --help and parallel_runner_wait.sh in the generated inventory.

Workflow Runner

Turn ordered operator procedures into reviewed YAML workflows with durable step evidence.

When to use it

Steps exchange responses, files, or session IDs, or when a final agent session must be continued.

Avoid: Items are independent fan-out work; use Parallel Runner, optionally to launch several workflow files.

Prerequisites

An initialized project, installed scripts, a YAML workflow, and commands available from the selected run root.

./.juno_task/scripts/workflow_runner.sh lint --workflow workflow.yaml

Safety and evidence

Lint before execution. Failures continue by default; set fail_workflow: true where automation must stop. Empty agent responses fail.

A manifest, per-step stdout/stderr/response files, rendered workflow data, summary, and captured session IDs under .juno_task/specs/workflows/.

Troubleshooting

Run workflow_runner.sh doctor RUN_DIR (or dr) and inspect successful stderr in artifacts rather than expecting it on the console.

Ordered YAML automation for commands and agents whose responses, artifacts, and sessions must survive every process boundary.

Use it for ordered work

Choose Workflow Runner when a step consumes {{ steps.<id>.response }}, a generated file, or a session from an earlier step. It is appropriate for reviewed operator playbooks, validation pipelines, agent chains, and final handoff.

Do not use it as an unnecessary wrapper around independent items. Parallel Runner owns concurrent fan-out and can launch several complete workflows through command-file mode.

Prerequisites

An initialized project and installed workflow_runner.sh.
A YAML workflow path or --workflow - for stdin.
Commands available from --run-root; relative paths resolve there.
A reviewed failure policy for each costly or destructive step.

Start from an example, then lint

./.juno_task/scripts/workflow_runner.sh --init-example agent-chain .juno_task/workflows/agent-chain.yaml
./.juno_task/scripts/workflow_runner.sh lint --workflow .juno_task/workflows/agent-chain.yaml
./.juno_task/scripts/workflow_runner.sh --workflow .juno_task/workflows/agent-chain.yaml --dry-run
./.juno_task/scripts/workflow_runner.sh --workflow .juno_task/workflows/agent-chain.yaml

Resume by zero-based index, step id/name, or -1 for the final step. Use --print-output summary|none|STEP to control final console output without discarding artifacts.

Safety and failure contract

Step failures are recorded but the workflow exits zero by default. Set fail_workflow: true where automation must stop.
Agent commands that exit zero with an empty response are failed.
The runner does not inject --quiet; agent stdout is the response and successful stderr remains an artifact.
Use response fields, not raw stderr, in downstream prompts.
Lint before cron or unattended execution and dry-run rendered commands first.

Artifacts and session handoff

Runs default to .juno_task/specs/workflows/WORKFLOW_ID/RUN_ID and persist the manifest, rendered configuration, step stdout/stderr/response, statuses, summary, and session IDs. Detected YYLO, yy, and ypl steps receive capture variables automatically.

The final successful agent session is persisted for yy cc. Set top-level continue_from_step to hand off one explicit step; selection is strict and fails when that step has no session ID.

Lint before; doctor after

./.juno_task/scripts/workflow_runner.sh lint --workflow workflow.yaml
./.juno_task/scripts/workflow_runner.sh doctor .juno_task/specs/workflows/<workflow_id>/<run_id>
# short alias
./.juno_task/scripts/workflow_runner.sh dr .juno_task/specs/workflows/<workflow_id>/<run_id>

Lint catches noisy stdout/stderr template anti-patterns before launch. Doctor inspects the manifest and response artifacts after a run.

Troubleshooting

If a downstream value is empty, inspect the producing step’s response artifact and use {{ steps.<id>.response }}.
If the process unexpectedly exits zero, check whether the failed step omitted fail_workflow: true.
If continuation selects the wrong session, set continue_from_step and run doctor.
If output is noisy, choose --no-print-step-stdout --print-output summary; evidence remains on disk.

Freshness sources

Reviewed against the current YYLO README Workflow Runner contract and workflow_runner.sh --help, including subprocess failure, response, artifact, and continue-handoff behavior.

Run Until Completion

Repeat bounded YYLO iterations until no open kanban work remains.

When to use it

A queue can advance autonomously and every iteration has validation and stop conditions.

Avoid: You need one reviewable run, independent workers, or an unbounded process.

Prerequisites

An initialized kanban, a configured subagent, and explicit iteration and stale thresholds.

./.juno_task/scripts/run_until_completion.sh -s claude -i 5 --stale-threshold 3

Safety and evidence

The loop runs at least once. Stale detection exits after unchanged iterations; keep it enabled unless another bounded stop owns the risk.

Normal YYLO logs plus kanban responses and commits; pre-run hooks execute in documented environment/flag order.

Troubleshooting

Inspect open statuses and stale-hook output; reduce each iteration before raising limits.

Kanban wrapper

Keep structured task truth available through the project-local YYLO Ledger wrapper.

When to use it

Agents and operators need statuses, blockers, responses, and commit evidence from one NDJSON source.

Avoid: Do not use task prose as a substitute for dependency declarations or validation evidence.

Prerequisites

An initialized .juno_task directory and the Python environment installed by YYLO.

./.juno_task/scripts/kanban.sh ready --sort asc

Safety and evidence

Use --body-file/--response-file for shell-sensitive Markdown. Only run ready tasks and attach the validating commit when done.

.juno_task task NDJSON, responses, dependency metadata, and commit references.

Troubleshooting

Use get --compact for focused context and deps TASK_ID to explain why work is blocked.

Bootstrap and requirements

Create the project Python environment and install script dependencies consistently.

When to use it

Initializing a checkout or refreshing declared script requirements.

Avoid: Do not repurpose setup scripts as a general package manager or rename their managed paths.

Prerequisites

Python 3, npm-installed YYLO, and filesystem access to the project.

./.juno_task/scripts/install_requirements.sh --force-update

Safety and evidence

The virtualenv is .venv_juno; .env.yylo is the canonical environment-variable file. Review upgrades before forcing them.

.venv_juno and setup diagnostics; bootstrap then dispatches the selected YYLO entrypoint.

Troubleshooting

Confirm Python resolution and that the command runs from the intended project root.

Log Scanner

Detect known Python, Node.js, fatal, and resource errors and turn them into kanban bug reports.

When to use it

Logs are durable enough to scan and deduplicated findings should enter the task queue.

Avoid: Do not treat pattern matching as proof of root cause or scan secret-bearing logs without review.

Prerequisites

Readable logs; ripgrep is preferred with grep fallback.

./.juno_task/scripts/log_scanner.sh --dry-run --verbose

Safety and evidence

Preview with --dry-run before task creation; reset state only when intentional re-scanning is acceptable.

Scanner state and generated kanban tasks containing matched error context.

Troubleshooting

Use --status to inspect scan state and --reset only to deliberately re-scan all input.

Slack and GitHub integrations

Bring Slack messages or GitHub issues into kanban and return completed responses to their source thread.

When to use it

A team has reviewed token scopes, labels/channels, and the response/closure policy.

Avoid: Do not enable bidirectional writes with unreviewed credentials or task-closing behavior.

Prerequisites

Slack bot or GitHub token environment variables and access to the selected channel/repository.

./.juno_task/scripts/github.py respond --dry-run --verbose

Safety and evidence

Start with dry-run, least-privilege credentials, and narrow labels/channels. Keep secrets out of content and task bodies.

Tagged kanban tasks, integration state, source identifiers, and posted threaded responses/comments.

Troubleshooting

Verify scopes, repository/channel identifiers, tags, and state before continuous mode.

Attachments and maintenance helpers

Download referenced attachments and clean generated logs or feedback artifacts deliberately.

When to use it

An operator has inspected paths and needs a narrow housekeeping action.

Avoid: Do not run cleanup blindly or treat downloaded content as trusted executable input.

Prerequisites

An initialized project, appropriate network credentials for attachments, and reviewed target paths.

./.juno_task/scripts/clean_logs_folder.sh --help

Safety and evidence

Inspect help and targets first; attachments are untrusted data and cleanup may be destructive.

Downloaded attachment files or reduced generated log/feedback directories.

Troubleshooting

Check permissions, credentials, destination paths, and each helper’s --help output.

Troubleshooting

Start with the executable’s --version and --help. If a command is missing, compare its availability label with your installed version. Do not silently install a prerelease to make an example work.

Ledger and Benchmark can be used standalone. YYLO delegates enforce compatibility separately; newest packages are not automatically a compatible combination. For sandbox, credential or workspace failures, repair the named prerequisite before dispatch. Preserve logs and retained evidence; do not delete state to hide a failure.

Sources and release evidence

Capability review: 2026-10-07. Reviewed version: 0.2.11. Changes by version. Canonical package repository. Published availability below is verified for exact versions, never inferred from the current source version.

@yylo/cli 0.2.2 artifact
Integrity and provenance
sha512-Lp9efAhOfH/Ni4Axl6RPUNzn4/1Qj/VcTtxEF29lUr8tGiDsb1ZtGw26R8b1nfelOXsOei7IygQo0LUrb6GE3g==
README SHA-256: 2e827a7b8fd48ce3385b72902692b8748fafaac0050e22adfbbf436c1d73213f
@yylo/cli 0.2.3-rc.3 artifact
Integrity and provenance
sha512-6+dF/oqXEeB7UHQQUXMPqiOabdM+OLggk2IdggUiQum3j76UlvxQBzbVv3kmeInviZcmbEyz46ZJorkXXibzgw==
README SHA-256: 2c245dc6f265ec69987f56efe2bf2368f15aca61794cecfd8007aef7b1552d82
@yylo/cli 0.2.11 artifact
Integrity and provenance
sha512-KNy4Ry2j/RlKceRNlIoC0292lvexzL4725XBw9ujSt3iUOw66UJ2wmLVbni8KGC7ZM0h9YON0gcI0dpiZYLp1A==
README SHA-256: 649b7e1c9fb7b1c954c17ebec80094e5aa9f4f971d2a62d90f2d9588afa45005

Discover Skills for reusable agent procedures. Skills summarize intent here; the tagged repository owns the complete instructions.