yolorun

name	yolorun
description	Design and operate Yolorun worktree workflows for long-running agentic feature work, recurring loops, objective gates, safe reviews, and draft PR handoff.

Yolorun

Use this skill when a user asks an agent to build a substantial feature, keep working until tests pass, create or update e2e coverage, run in the background, design recurring loops, or coordinate multiple agent runs with local worktrees.

Yolorun is a local-first workflow OS. Agents may propose loops and feature workflows, but the Yolorun kernel decides what is runnable.

Current Contract

Yolorun supports three workflow kinds:

• yolorun.feature for large feature work: plan, write e2e tests when possible, implement, run gates, review, fix, summarize, and optionally create a draft PR.
• yolorun.loop for small recurring work: CI triage, lint fixes, dependency review drafts, flaky-test reproduction, and similar repeatable tasks.
• yolorun.graph for dependency-aware groups of feature workflows designed by an agent or human.

Use feature workflows for user requests like:

• "Build this feature and make sure all e2e tests pass."
• "Create the e2e tests, implement the feature, review the diff, and fix failures."
• "Run this in a worktree and make a draft PR."
• "Split this into several safe parallel workstreams."

Use recurring loops for tasks that repeat or are triggered by events.

Use graph workflows when a large goal needs multiple feature loops with ordering constraints. Prefer a graph over one giant feature when some work must happen first and other work can run later or in parallel.

Important v1 boundary: recurring loops can run under yolorun daemon start. Feature workflows currently run foreground per process; to run several features at once, create one worktree-backed feature workflow per feature and run each in its own terminal or Codex thread. Do not claim that daemon-backed feature queues exist until the CLI actually exposes them.

Feature Workflow Procedure

When asked to build a large feature with Yolorun:

1. Inspect the repo first.
   • Identify package manager, scripts, CI gates, app entry points, test setup, e2e framework, and risky ownership boundaries.
   • Prefer project-defined commands over inventing new gates.
2. Initialize Yolorun if needed.
   • Run yolorun init when .yolorun/yolorun.json is missing.
3. Create a worktree-backed feature workflow.
   • Run yolorun feature "<user request>" --worktree.
   • Preserve the created feature id and worktree path.
4. Make acceptance criteria explicit.
   • Include behavior, e2e expectations, required gates, review expectations, and things that must not happen.
5. Write or update e2e tests first when possible.
   • If tests cannot be written first, explain the blocker in STATE.md and add the test as soon as the required surface exists.
6. Implement inside the workflow worktree.
   • Stay inside allowed paths and permissions.
   • Keep unrelated refactors out of the run.
7. Run all required gates.
   • Typical gates are bun run typecheck, bun test, bun run e2e, CI reproduction commands, and app-specific smoke tests.
8. Review the diff against PLAN.md and ACCEPTANCE.md.
   • The reviewer must be logically separate from the maker.
   • Blocking findings require another fix iteration.
9. Repeat implement -> run-gates -> review -> fix until completion or escalation.
10. Summarize and prepare handoff.

• Update STATE.md, REVIEW.md, run logs, and a draft PR body.
• Use yolorun feature pr <feature-id> --draft only after local success or an explicit user request.

Never merge, deploy, change production data, rotate secrets, or make unattended dependency upgrades in v1.

Observable Runs

Yolorun feature runs are intentionally visible in the terminal.

Use:

yolorun feature "<request>" --worktree --verbose

The output should show:

• feature id and status
• artifact paths
• worktree path or current-checkout mode
• selected backend for every role
• model metadata when available
• phase progress
• gate commands and results
• final state/log/review pointers

Use machine-readable output when another agent is supervising:

yolorun feature "<request>" --worktree --json

Use quiet output only when a parent process already captures logs:

yolorun feature "<request>" --worktree --quiet

Real agents can take minutes per role. Do not assume a run is stuck just because planner, reviewer, or summarizer spends a long time running. Inspect .yolorun/features/<feature-id>/state.json and runs/*.jsonl for the current phase, role, backend, command, duration, and gate status.

Codex model metadata is reported from YOLORUN_CODEX_MODEL when set; otherwise the model field may show auto/unknown because the Codex CLI does not expose a stable selected-model value to Yolorun yet.

Parallel Feature Work

Parallelism is worktree-based, not one giant shared checkout.

For multiple independent features:

1. Split the request into small feature ids with explicit acceptance criteria.
2. Create a separate yolorun.feature workflow and git worktree for each.
3. Run each workflow from a separate terminal or Codex thread.
4. Avoid overlapping file ownership. If two workflows need the same files, serialize or redefine the split.
5. Land by review order. Rebase later worktrees after earlier PRs land.

Do not run parallel feature agents directly in a dirty main checkout. Worktrees are the isolation boundary.

Loop Graphs

A loop graph is a queue-shaped plan made of feature workflow nodes.

Use this when the user describes dependencies like:

bootstrap project
  -> app shell
  -> database schema
      -> onboarding
      -> dashboard
      -> settings

Create the graph first:

yolorun graph create "<large goal>"

Then inspect or edit .yolorun/graphs/<graph-id>/yolorun.json. Each node must have id, title, request, dependsOn, and status.

Run the graph:

yolorun graph run <graph-id> --max-parallel 3

If any child feature is rerun manually or in another terminal/thread, repair the graph record before judging completion:

yolorun graph reconcile <graph-id>
yolorun graph report <graph-id>

Rules:

• A node starts only when all dependencies have passed.
• Each node becomes a child yolorun.feature workflow.
• Each child feature should use a worktree.
• Passed nodes write HANDOFF.md for downstream nodes.
• Failed or escalated nodes block dependents.
• Reconcile syncs node status from child feature manifests and state.json checkpoints.
• Report writes .yolorun/graphs/<graph-id>/REPORT.md, which is the durable completion record.
• Agents communicate through graph state, child feature artifacts, and handoff files, not hidden chat context.
• V1 accepts maxParallel in the graph contract but may execute ready nodes conservatively; never claim auto-merge or deploy.

Recurring Loop Qualification

A recurring loop is a good candidate only when all are true:

• The task repeats at least weekly or is triggered by a recurring event.
• An objective gate can reject bad output.
• The agent can reproduce the task locally or through a safe read-only integration.
• The loop has hard stops for iterations, time, and estimated token budget.
• A human reviews before merge, deploy, dependency changes, billing, auth, or irreversible actions.

Create runnable loops only when objective gates, budgets, permissions, stop conditions, worktrees, and escalation rules are present. Otherwise create a draft loop.

Commands

Feature workflow commands:

yolorun feature "<request>" --worktree
yolorun feature run <feature-id>
yolorun feature status <feature-id>
yolorun feature review <feature-id>
yolorun feature resume <feature-id>
yolorun feature pr <feature-id> --draft

Graph workflow commands:

yolorun graph create "<goal>"
yolorun graph run <graph-id> --max-parallel 3
yolorun graph resume <graph-id>
yolorun graph reconcile <graph-id>
yolorun graph report <graph-id>
yolorun graph status <graph-id>
yolorun graph plan <graph-id>

Recurring loop commands:

yolorun design
yolorun validate [loop-id]
yolorun run <loop-id>
yolorun enable <loop-id> --every 30m
yolorun enable <loop-id> --cron "0 9 * * 1"
yolorun daemon start
yolorun daemon status
yolorun logs <loop-id>

Use the binary command yolorun when the package is installed. In this repository, use bun run yolorun ....

Required Artifacts

Repo-level files:

.yolorun/
  yolorun.json
  OS.md
  skills/yolorun/SKILL.md

Feature workflow files:

.yolorun/features/<feature-id>/
  yolorun.json
  PLAN.md
  ACCEPTANCE.md
  STATE.md
  REVIEW.md
  runs/*.jsonl
  logs/*.log

Graph workflow files:

.yolorun/graphs/<graph-id>/
  yolorun.json
  PLAN.md
  GRAPH.md
  STATE.md
  state.json
  runs/*.jsonl
  nodes/<node-id>/HANDOFF.md

Recurring loop files:

.yolorun/loops/<loop-id>/
  yolorun.json
  SKILL.md
  STATE.md
  runs/*.jsonl
  logs/*.log

Safety Rules

Escalate instead of continuing when:

• Budget is exhausted.
• Required permissions are denied.
• Gates fail after configured retries.
• The reviewer still has blocking findings.
• Acceptance criteria are vague or subjective.
• The task touches auth, payments, billing, secrets, deploys, migrations, or irreversible external actions.
• Parallel workstreams overlap in ways that make merges unsafe.
• A phase artifact is only a placeholder such as OpenAI Codex v..., Claude Code v..., done, or looks good.

A trustworthy phase summary names concrete files, gates, behaviors checked, and remaining risks. Weak artifacts are not completion evidence.

Prefer draft PRs, explicit review notes, and local logs over silent automation.