Yolo

Yolo Skill

Full-auto AI-DLC pipeline. User provides a prompt; agent drives the entire lifecycle: Idea -> Elaboration -> Proposal -> Review -> Execute -> Verify -> Done.

Overview

$yolo automates the complete AI-DLC workflow. You provide a natural language description of what you want built, and the agent handles everything:

1. Planning -- create project, idea, self-elaboration, proposal with docs & tasks
2. Proposal Review -- proposal-reviewer adversarial loop
3. Execution -- wave-based parallel task dispatch via spawn_agent
4. Verification -- task-reviewer adversarial loop + admin verify
5. Report -- completion summary

$yolo <prompt>
       |
       v
  Project + Idea + Elaboration + Proposal
       |
       v
  Proposal Reviewer (auto, up to maxProposalReviewRounds)
       |
       v
  Admin Approve --> Tasks materialize
       |
       v
  Wave-based spawn_agent parallel execution
       |  (dev agent + task-reviewer per task)
       v
  Admin Verify each wave --> unblock next
       |
       v
  Done. Report summary.

Escape hatch: Ctrl+C at any time. All created entities (project, idea, proposal, tasks) persist in Chorus. Resume manually via $develop or $review.

Prerequisites

The API key needs write + admin on every resource it touches:

Check at startup:

perms = chorus_checkin().agent.permissions
need = { idea: ["write"], proposal: ["write","admin"],
         task: ["write","admin"], project: ["write"] }

for resource, actions in need:
  missing = [a for a in actions if a not in (perms[resource] or [])]
  if missing: ABORT "$yolo needs {resource}: {missing}. Use an Admin-preset API key."

Input

$yolo <natural language prompt>
$yolo <prompt> --project <project-uuid>

• <prompt> -- what you want built (becomes the Idea content)
• --project <uuid> -- optional; use an existing project instead of creating a new one

Workflow

Phase 1: Planning

Step 1.1: Resolve Project

Parse the arguments for --project <uuid>.

If --project is provided:

chorus_get_project({ projectUuid: "<uuid>" })

Verify it exists and proceed.

If not provided, search for a suitable existing project first:

# 1. Search for projects matching the prompt topic
chorus_search({ query: "<key terms from prompt>", entityTypes: ["project"] })

# 2. Or list recent projects to find a match
chorus_list_projects()

Review the results. If a project clearly matches the user's intent (same topic, active, relevant scope), use it. If no suitable project exists, create a new one:

chorus_admin_create_project({
  name: "<short title derived from prompt>",
  description: "<1-2 sentence summary of the prompt>"
})

Step 1.2: Create Idea

chorus_pm_create_idea({
  projectUuid: "<project-uuid>",
  title: "<concise title derived from prompt>",
  content: "<full user prompt as-is>"
})

Then claim it:

chorus_claim_idea({ ideaUuid: "<idea-uuid>" })

Step 1.3: Self-Elaboration

In $yolo mode, the agent generates elaboration questions and answers them itself -- no AskUserQuestion calls. This preserves an audit trail without interrupting the user.

Self-elaboration is still a loop. If answering your own questions surfaces a new question, contradiction, or gap, loop back to chorus_pm_start_elaboration for another self-answered round before resolving — don't force a resolve over unresolved ambiguity. There is no human gate in YOLO, so the loop exits on your judgment that nothing material is left open (round cap 10). Steps 1–2 are one round; repeat them as needed, then resolve once in Step 3.

1. Generate and submit questions:

   chorus_pm_start_elaboration({
     ideaUuid: "<idea-uuid>",
     depth: "standard",
     questions: [
       {
         id: "q1",
         text: "<question about scope, architecture, etc.>",
         category: "functional",
         options: [
           { id: "a", label: "<option A>" },
           { id: "b", label: "<option B>" }
         ]
       }
       // ... 5-8 questions covering functional, technical_context, scope aspects
     ]
   })
   

2. Answer immediately (agent selects best options based on the prompt):

   chorus_answer_elaboration({
     ideaUuid: "<idea-uuid>",
     roundUuid: "<round-uuid>",
     answers: [
       { questionId: "q1", selectedOptionId: "a", customText: "Rationale: ..." },
       // ...
     ]
   })
   

3. Resolve — in YOLO mode the agent resolves elaboration autonomously, with no human-confirmation gate (the human-confirmation requirement that applies to the interactive $idea flow is explicitly waived under $yolo automation):

   chorus_pm_validate_elaboration({
     ideaUuid: "<idea-uuid>"
   })
   

   chorus_pm_validate_elaboration requires idea:admin. $yolo already mandates an Admin-preset key in Prerequisites, so this is satisfied. To open another self-elaboration round instead of resolving, just call chorus_pm_start_elaboration again.

Step 1.4: Create Proposal

1. Read the spec mode (already computed). The SessionStart hook (hooks/resolve-spec-mode.sh) has already resolved it — do NOT re-derive. Read the ## Spec Mode section: CHORUS_SPEC_MODE=<lite|openspec|off> + a routing note. Act on it: openspec (usable, shows CHORUS_OPENSPEC_ACTIVE=1) → 2a; off → 2b; lite → 2c. If it says the mode cannot be honored (explicit openspec but unusable), halt and surface it — do NOT fall back or enter 2a with no OpenSpec. (Spawned without context? Source the same helper; openspec-aware §1.) This matters because yolo runs unattended.

2. Create the empty proposal container. The description MUST carry the mode's locator line — OpenSpec: OpenSpec change slug: <slug>; spec-lite: Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/; free-form: none. description is only settable at creation, so decide the slug/dated-path first.

   chorus_pm_create_proposal({
     projectUuid: "<project-uuid>",
     title: "<feature name>",
     description: "<summary>\n\nOpenSpec change slug: <slug>",                          // OpenSpec (2a)
     // description: "<summary>\n\nSpec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/", // spec-lite (2c)
     // description: "<summary>",                                                        // free-form (2b)
     inputType: "idea",
     inputUuids: ["<idea-uuid>"]
   })
   

   Then branch:

   2a. OpenSpec mode (CHORUS_OPENSPEC_ACTIVE=1). Follow openspec-aware §3 end-to-end:

   • Pick $SLUG, run openspec new change "$SLUG" (§3.1–§3.2).
   • Author proposal.md, design.md, and one specs/<capability>/spec.md per capability locally on disk (§3.3). ADDED Requirements only; per-spec fallback to free-form Markdown if MODIFIED/REMOVED is needed.
   • Define the chorus_check_response helper (§6); prefer chorus mcp call … --arg-file content=<file> for mirrors (§3.4/§3.6) — the bash-wrapper fallback's $API (§2.1) + json_encode_file are only needed when chorus is not on PATH.
   • Mirror each local file via chorus mcp call chorus_pm_add_document_draft … --arg-file content=<file> (§3.6; fallback = "$API" chorus_pm_add_document_draft "$PAYLOAD") — one call per file, with the document type from openspec-aware §5. (Codex's chorus-mcp-call.sh takes <TOOL_NAME> <JSON> directly; no mcp-tool subcommand.)

   ⛔ Do not invoke chorus_pm_add_document_draft / chorus_pm_update_document_draft / chorus_pm_update_document from Codex's MCP harness with a hand-typed content field in this branch. Re-typing the markdown body wastes 20k+ tokens per proposal and breaks byte-equality with the local files. See openspec-aware §2 Rule 1.

   Then continue to step 3 (task drafts).

   2b. Free-form mode (resolved mode = free-form). Only when step 1 resolved to free-form — i.e. explicit CHORUS_SPEC_MODE=off (unset never comes here: it resolves to OpenSpec when usable, else spec-lite/2c). Add a tech design document draft directly via MCP, content authored inline:

   chorus_pm_add_document_draft({
     proposalUuid: "<proposal-uuid>",
     type: "tech_design",
     title: "Tech Design: <feature>",
     content: "<markdown tech design covering architecture, data model, API, module contracts>"
   })
   

   2c. spec-lite mode (resolved mode = lite). Load the spec-lite skill (~/.codex/skills/spec-lite/SKILL.md). Pick $SLUG (a capability). Ensure the durable .chorus/specs/<slug>/spec.md exists (local-only, no ids; use the spec-lite skill's inline durable-spec template) and update it in place. Create this change's dated folder .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/ with its synced Chorus-typed docs (shape = the spec-lite skill's inline dated-folder document template) — prd.md (primary), optional tech_design.md… The description carries the Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/ locator (step 2). Mirror each dated-folder <type>.md to its persistent Document byte-exact — first time chorus mcp call chorus_pm_add_document_draft "{\"proposalUuid\":\"<uuid>\",\"type\":\"prd\",\"title\":\"PRD: <feature>\"}" --arg-file content=.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/prd.md, later edits via chorus_pm_update_document against the recorded documentUuid (chorus-mcp-call.sh fallback when chorus not on PATH). spec.md is never mirrored. No openspec/changes/ scaffold; no tasks.md. Then continue to step 3.

3. Add task drafts incrementally (use returned draftUuid for dependency chaining). acceptanceCriteriaItems is required on every draft — at least one non-blank criterion, or the call is rejected:

   # First task
   result1 = chorus_pm_add_task_draft({
     proposalUuid: "<proposal-uuid>",
     title: "<module name>",
     description: "<what to build, referencing tech design>",
     priority: "high",
     storyPoints: 3,
     acceptanceCriteriaItems: [
       { description: "<testable criterion>", required: true },
       // ...
     ]
   })
   
   # Second task, depends on first
   chorus_pm_add_task_draft({
     proposalUuid: "<proposal-uuid>",
     title: "<dependent module>",
     description: "...",
     priority: "medium",
     storyPoints: 2,
     acceptanceCriteriaItems: [...],
     dependsOnDraftUuids: ["<result1.draftUuid>"]
   })
   

4. Validate:

   chorus_pm_validate_proposal({ proposalUuid: "<proposal-uuid>" })
   

   Fix any errors, then proceed.

5. Submit:

   chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })
   

   After this call, the PostToolUse hook injects context instructing you to spawn the chorus-proposal-reviewer sub-agent. You MUST spawn it yourself via spawn_agent and wait for its return with wait_agent — it is NOT auto-launched.

Reviewer contract (applies to every review gate below)

Every gate in Phases 2, 4 and 4.5 follows the same three steps. They are written once here; the phases below only name their entity and their stage-specific actions.

1. Spawn and wait. Spawn the reviewer as a read-only sub-agent, then wait for it: spawn it with spawn_agent, wait for it with wait_agent, then release the thread slot with close_agent. The agent's returned text is not the verdict — the verdict is the VERDICT: comment it posts.
2. Read THIS round's VERDICT. Call chorus_get_comments on the entity and find the VERDICT: comment posted after your dispatch, not an older round's. Do not advance the gate before you have read it.
3. No VERDICT for this round? Check what the reviewer did post:
   • A reported round limit, or any other explicit refusal to review — a deliberate escalation to a human. STOP: do not respawn, do not self-review, do not post a VERDICT of your own.
   • Nothing at all — respawn ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the entity yourself as a read-only pass and POST the VERDICT, then proceed on what you posted rather than looping forever.

Absence is never a PASS, and a round limit reached by someone else is never yours to clear.

Phase 2: Proposal Review Loop

After chorus_pm_submit_proposal, the PostToolUse hook injects context instructing you to spawn the chorus-proposal-reviewer sub-agent. Mount the reviewer skill explicitly:

reviewer = spawn_agent({
  items: [
    { type: "skill", name: "Chorus Proposal Reviewer", path: "chorus:chorus-proposal-reviewer" },
    { type: "text",  text: "Review proposal <proposal-uuid>. Max review rounds: 3. Post VERDICT comment." }
  ]
})
wait_agent({ targets: [reviewer.agent_id] })

Then:

1. Read the reviewer's VERDICT:

   chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
   

   Look for THIS round's VERDICT: comment — the one posted after your dispatch, not an older round's.

   IMPORTANT — release thread slot: after wait_agent returns, immediately call close_agent({ target: reviewer.agent_id }). Codex caps concurrent agent threads at 6; completed status does NOT free a slot — only close_agent does. On long $yolo runs you WILL hit the limit if you don't close each reviewer after use.

2. Act on the VERDICT:

   • PASS or PASS WITH NOTES --

     chorus_admin_approve_proposal({
       proposalUuid: "<proposal-uuid>",
       reviewNote: "PASS from reviewer. <brief summary of notes if any>"
     })
     

     Tasks and documents materialize automatically. Proceed to Phase 3.

   • FAIL -- Read the BLOCKERs from the reviewer comment. Then:

     chorus_pm_reject_proposal({
       proposalUuid: "<proposal-uuid>",
       reviewNote: "FAIL from reviewer. Fixing BLOCKERs: <list>"
     })
     

     Revise the drafts (chorus_pm_update_document_draft, chorus_pm_update_task_draft) to address each BLOCKER, then resubmit:

     chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })
     

     After resubmission, the hook injects context again — spawn the reviewer yourself for Round 2.

3. Max rounds: Loop up to maxProposalReviewRounds (from plugin config, default 3). If exhausted:

   STOP: "Proposal review failed after {maxRounds} rounds. 
          Remaining BLOCKERs: <list>. Human review needed.
          Proposal UUID: <uuid>"
   

4. No new VERDICT for this round? Apply step 3 of the Reviewer contract, reviewing the proposal yourself if the reviewer stays silent.

Phase 3: Task Execution (Wave-Based)

After proposal approval, tasks exist in open status. Execute them in dependency-ordered waves using Codex spawn_agent. If parallel spawn is not desired or too many workers in flight, fall back to sequential main-agent execution.

Primary: Parallel spawn_agent workers

wave = 1

loop:
  # 1. Find ready tasks
  unblocked = chorus_get_unblocked_tasks({ projectUuid: "<project-uuid>" })

  if no unblocked tasks and all tasks done:
    break  # All complete

  if no unblocked tasks and some tasks not done:
    # Stuck -- tasks failed review and can't proceed
    break with escalation report

  # 2. For each unblocked task, spawn a worker
  for each task in unblocked:
    spawn_agent({
      items: [
        { type: "skill", name: "Chorus Develop", path: "chorus:develop" },
        { type: "text", text: f"""Implement this Chorus task:
Task UUID: {task.uuid}
Project UUID: {project_uuid}

Follow the mounted develop workflow and the task acceptance criteria. Read the task, proposal, and project documents through Chorus. After chorus_submit_for_verify, exit; the main agent owns independent review and admin verification.""" }
      ]
    })

  # 3. Wait for workers to return (use wait_agent)
  #    Each worker follows $develop skill:
  #    claim -> in_progress -> develop -> report -> self-check AC -> submit_for_verify

  # 4. Proceed to Phase 4 (verification) for this wave
  wave += 1

What the worker prompt needs:

• taskUuid (required)
• projectUuid (required for context lookups)
• Explicit instruction to follow $develop skill — the skill itself has all the workflow detail

Fallback: Main Agent (sequential)

If parallel spawn is not practical (rate limits, token budget, or simpler debugging wanted), fall back to executing tasks sequentially as the main agent:

for each task in unblocked:
  # Follow the $develop workflow directly as main agent
  chorus_claim_task({ taskUuid: "<task-uuid>" })
  chorus_update_task({ taskUuid: "<task-uuid>", status: "in_progress" })

  # ... implement the task: read context, write code, run tests ...

  chorus_report_work({ taskUuid: "<task-uuid>", report: "..." })
  chorus_report_criteria_self_check({ taskUuid: "<task-uuid>", criteria: [...] })
  chorus_submit_for_verify({ taskUuid: "<task-uuid>", summary: "..." })

  # PostToolUse hook injects context — you must spawn task-reviewer yourself
  # Proceed to Phase 4 verification for this task before moving to next

The fallback is slower (sequential, not parallel) but still completes the pipeline. The PostToolUse hook injects reviewer instructions the same way in both modes — you must always spawn the reviewer manually.

Phase 4: Verification

After each wave's sub-agents complete, verify their tasks:

for each task in wave_tasks:
  # 1. Check task status
  task = chorus_get_task({ taskUuid: "<task-uuid>" })

  if task.status != "to_verify":
    # Sub-agent may have failed; skip or handle
    continue

  # 2. Spawn task-reviewer in FOREGROUND and wait for it (use wait_agent)
  #    Mount the chorus-task-reviewer SKILL explicitly.
  reviewer = spawn_agent({
    items: [
      { type: "skill", name: "Chorus Task Reviewer", path: "chorus:chorus-task-reviewer" },
      { type: "text",  text: "Review Chorus task <task-uuid>. Post VERDICT as a comment before exit." }
    ]
  })
  wait_agent({ targets: [reviewer.agent_id] })
  close_agent({ target: reviewer.agent_id })   # completed != closed

  # 3. Read task-reviewer VERDICT
  comments = chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
  # Find THIS round's "VERDICT:" comment — the one posted after your dispatch, not an older round's

  # 4. Act on VERDICT — three possible outcomes:
  if VERDICT is "PASS":
    # All AC verified, no issues. Mark AC and verify.
    chorus_mark_acceptance_criteria({
      taskUuid: "<task-uuid>",
      criteria: [
        { uuid: "<ac-uuid>", status: "passed", evidence: "<from reviewer>" },
        // ...
      ]
    })
    chorus_admin_verify_task({ taskUuid: "<task-uuid>" })
    # Task is now "done" -- unblocks dependents

  if VERDICT is "PASS WITH NOTES":
    # All AC verified, minor non-blocking notes. Still mark AC and verify.
    chorus_mark_acceptance_criteria({ ... })
    chorus_admin_verify_task({ taskUuid: "<task-uuid>" })

  if VERDICT is "FAIL":
    # BLOCKERs found. Do NOT verify. Reopen for rework.
    chorus_admin_reopen_task({ taskUuid: "<task-uuid>" })
    # Task returns to "open", will be picked up in next wave

After verifying all tasks in the wave, return to Phase 3 to check for newly unblocked tasks.

Max rounds per task: Tracked by maxTaskReviewRounds from plugin config (default 3). If a task has been reopened maxRounds times, skip it and flag for human escalation:

ESCALATE: "Task '{title}' failed review after {maxRounds} rounds. 
           Last BLOCKERs: <list>. Manual intervention needed.
           Task UUID: <uuid>"

Continue with remaining tasks -- do not halt the entire pipeline for one stuck task.

No new VERDICT for this round? Apply step 3 of the Reviewer contract, reviewing the task yourself if the reviewer stays silent.

Phase 4.5: Code-Review Gateway (mandatory pre-ship)

Once every task of the idea's proposal is verified (done) — Phase 3 finds no more unblocked tasks and none remain non-terminal — run the final ship-time code-review gateway before the Phase 5b completion report. It reviews the whole Idea's aggregate code change across all tasks (not a single task) and posts its verdict on the Idea. After the last task is verified, the PostToolUse hook injects a reminder to spawn it.

Mount the code-reviewer skill explicitly and wait for it:

reviewer = spawn_agent({ items: [
    { type: "skill", name: "Chorus Code Reviewer", path: "chorus:chorus-code-reviewer" },
    { type: "text", text: "Review the aggregate code for idea <idea-uuid>. Round: N. Post VERDICT on the idea." }
] })
wait_agent({ targets: [reviewer.agent_id] })
close_agent({ target: reviewer.agent_id })

# Read the VERDICT on the IDEA
comments = chorus_get_comments({ targetType: "idea", targetUuid: "<idea-uuid>" })

Act on the VERDICT:

• PASS / PASS WITH NOTES — the feature is cleared to ship. Proceed to Phase 5 / 5b.
• FAIL — do NOT ship. Read the BLOCKERs, then fix them via the quick-dev workflow ($quick-dev): call chorus_create_tasks with proposalUuid set to the current approved proposal so the fix tasks attach to it — do not reopen the already-verified tasks. Group related small BLOCKERs into one cohesive task by default; split only materially large or independently testable fixes. Drive every fix task through Phase 3 → Phase 4, including AC self-check, independent task review, and admin verification. Re-spawn the code-reviewer only after every fix task is successfully done; a failed or cancelled fix task, stop the automatic loop and escalate. Loop bounded by maxCodeReviewRounds (default 3; 0 = unlimited).

ESCALATE: "Idea '{title}' failed code review after {maxCodeReviewRounds} rounds.
           Last BLOCKERs: <list>. Manual intervention needed. Idea UUID: <uuid>"

No new VERDICT for this round? Apply step 3 of the Reviewer contract, reviewing the idea's aggregate change yourself if the reviewer stays silent.

The gateway is behavioral like the other two reviewers: its verdict is advisory and does not change the Idea's stored status; the orchestrator honors it. It runs before the completion report so the report is never written while a FAIL is outstanding.

Codex sub-agent context and lifecycle

Routine Chorus workers and reviewers start with a fresh context: their mounted skill plus entity UUIDs let them retrieve authoritative state through MCP. Use fork_context: true only when a child needs material parent-conversation evidence or decisions that cannot be conveyed cleanly in its assignment, and state why. Call wait_agent only when the next pipeline action depends on the result; use send_input to redirect an active child, close_agent promptly when interaction is finished, and resume_agent only for a previously closed child. Codex manages these execution threads; Chorus MCP remains authoritative for claims, statuses, work reports, acceptance evidence, submissions, and verdict comments.

Phase 5: Report

After all waves complete, output a markdown summary:

## $yolo Complete

**Project:** <project-name> (<project-uuid>)
**Proposal:** <proposal-title> (<proposal-uuid>)
**Idea:** <idea-title> (<idea-uuid>)

### Tasks
| Task | Status | Review Rounds |
|------|--------|---------------|
| <title> | done | 1 |
| <title> | done | 2 |
| <title> | ESCALATED | 3 (max) |

### Summary
- Total tasks: N
- Completed: X / N
- Escalated: Y (need human review)
- Waves executed: W

Phase 5b: Idea Completion Report (mandatory)

A successful $yolo run always finishes the Idea — call chorus_create_report once with proposalUuid set to the last verified proposal. The call requires title (a short report title) plus content; content's parameter description carries the three-section template (## Summary / ## Decisions / ## Follow-ups); follow it. Surface the returned documentUuid in the Phase 5 summary. Skipping is a protocol violation.

Order: write the completion report only after the Phase 4.5 code-review gateway returns PASS / PASS WITH NOTES — never while a code-review FAIL is outstanding.

Error Handling

Tips

• Keep the initial prompt detailed -- the more context you provide, the better the auto-generated proposal quality
• The proposal-reviewer is your quality gate -- if it keeps FAILing, the prompt may be too vague
• Watch the wave count -- if tasks keep getting reopened, consider Ctrl+C and manually reviewing the feedback
• All audit trail is preserved: elaboration Q&A, reviewer VERDICTs, work reports. Check Chorus UI for full history
• For small/simple tasks, consider $quick-dev instead -- it skips the Idea->Proposal overhead
• Sub-agents share your API key; ensure it has the permissions listed in Prerequisites before starting

Next

• To manually review proposals: $review
• To manually develop tasks: $develop
• To create quick standalone tasks: $quick-dev
• For platform overview: $chorus