chorus-yolo

name	chorus-yolo
description	Full-auto AI-DLC pipeline — from prompt to done. Automates the entire Idea -> Proposal -> Execute -> Verify lifecycle.
license	AGPL-3.0
metadata	{"author":"chorus","version":"0.16.4","category":"project-management","mcp_server":"chorus"}

Chorus Yolo Skill

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

---

Overview

/chorus-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 Kiro subagents
4. Verification -- task-reviewer adversarial loop + admin verify 4.5. Code-Review Gateway -- code-reviewer reviews the Idea's aggregate change before ship (FAIL → add fix tasks → re-run)
5. Report -- completion summary

/chorus-yolo <prompt>
       |
       v
  Project + Idea + Elaboration + Proposal
       |
       v
  Proposal Reviewer (auto, up to maxProposalReviewRounds)
       |
       v
  Admin Approve --> Tasks materialize
       |
       v
  Wave-based subagent execution
       |  (dev subagent + task-reviewer per task)
       v
  Admin Verify each wave --> unblock next
       |
       v
  Code-Review Gateway (auto, up to maxCodeReviewRounds)
       |  PASS --> ship   |   FAIL --> add fix tasks --> re-run
       v
  Done. Report summary.

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

---

Prerequisites

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

Needs	Why
idea: [write]	Create ideas, run elaboration
proposal: [write, admin]	Create proposals; approve them
task: [write, admin]	Create, execute, verify tasks
project: [write]	Create the project if none is given

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 "/chorus-yolo needs {resource}: {missing}. Use an Admin-preset API key."

---

Input

/chorus-yolo <natural language prompt>
/chorus-yolo <prompt> --project <project-uuid>

• <prompt> -- what you want built (becomes the Idea content). Available as $ARGUMENTS.
• --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 /chorus-yolo mode, the agent generates elaboration questions and answers them itself -- no interactive user questions. 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, 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 /chorus-idea flow is explicitly waived under /chorus-yolo automation):

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

   chorus_pm_validate_elaboration requires idea:admin. /chorus-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. Detect OpenSpec mode. Load the /chorus-openspec-aware skill and run its §1 detection contract. The result determines how the rest of this step authors documents:

   • CHORUS_OPENSPEC_ACTIVE=1 → spec-driven branch (sub-step 2a below).
   • CHORUS_OPENSPEC_ACTIVE=0 → free-form branch (sub-step 2b below).

   This is mandatory — yolo runs unattended, so silently picking the wrong mode is exactly the failure scenario the detection contract exists to prevent.

2. Create the empty proposal container. In OpenSpec mode, the description MUST contain the literal line OpenSpec change slug: <slug> (use the $SLUG you'll pick in 2a); in free-form mode, omit that line.

   chorus_pm_create_proposal({
     projectUuid: "<project-uuid>",
     title: "<feature name>",
     description: "<summary>\n\nOpenSpec change slug: <slug>",   // OpenSpec mode
     // description: "<summary>",                                 // free-form mode
     inputType: "idea",
     inputUuids: ["<idea-uuid>"]
   })
   

   Then branch:

   2a. OpenSpec mode (CHORUS_OPENSPEC_ACTIVE=1). Follow /chorus-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 $API, json_encode_file, chorus_check_response helpers (§3.4, §6).
   • Mirror each local file via "$API" mcp-tool chorus_pm_add_document_draft "$PAYLOAD" (§3.6) — one call per file, with the document type from /chorus-openspec-aware §5.

   ⛔ Do not invoke chorus_pm_add_document_draft / chorus_pm_update_document_draft / chorus_pm_update_document from the 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 /chorus-openspec-aware §2 Rule 1.

   Then continue to step 3 (task drafts).

---

Phase 2: Proposal Review Loop

After chorus_pm_submit_proposal, the postToolUse hook injects a nudge to spawn the chorus-proposal-reviewer. You MUST manually spawn it as a read-only subagent in the foreground. Wait for it to complete, then:

1. Read the reviewer's VERDICT:

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

   Look for the most recent comment containing VERDICT:.

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 the nudge again — spawn the reviewer yourself for Round 2.

3. Max rounds: Loop up to maxProposalReviewRounds (default 3). If exhausted:

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

4. No new VERDICT comment after reviewer returns? The reviewer exhausted its turn budget. Respawn it ONCE with a concise-budget hint: "Stay within turn budget. Skip deep source verification. Fetch proposal + comments + idea only, skim for obvious BLOCKERs, and post your VERDICT within the first 10 turns." If the second attempt still produces no VERDICT, treat the proposal as PASS WITH NOTES and proceed — the pipeline cannot loop forever on a silent reviewer.

---

Phase 3: Task Execution (Wave-Based)

After proposal approval, tasks exist in open status. Execute them in dependency-ordered waves using Kiro subagents. If subagent spawning is unavailable, fall back to main agent execution.

Primary: Kiro subagents (parallel)

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. Spawn a subagent for each unblocked task (Kiro allows up to 4 concurrent).
  #    You have `subagent` in your tools. For each task, dispatch a developer
  #    subagent with the task UUID + project UUID + a sessionUuid, instructing it
  #    to follow the /chorus-develop workflow:
  #      "Your Chorus task UUID: {task.uuid}. Project UUID: {project-uuid}.
  #       Session UUID: {fresh-session-uuid}. Implement the task per its
  #       description and acceptance criteria. Follow /chorus-develop. Read the
  #       task, proposal, and project documents for context."
  #    If more than 4 tasks are unblocked, dispatch in batches of 4.

  # 3. Wait for all subagents to complete
  #    Each subagent follows /chorus-develop:
  #    claim -> in_progress -> develop -> report -> self-check AC -> submit_for_verify
  #    After each submit_for_verify, the main agent's postToolUse hook nudges the
  #    task-reviewer spawn (handled in Phase 4).

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

What each subagent prompt needs:

• Task UUID(s) + Project UUID
• A sessionUuid to pass on chorus_update_task / chorus_report_work
• The instruction to follow the /chorus-develop workflow

Fallback: Main Agent (sequential)

If subagent spawning fails (unavailable, permission denied, or subagents crash repeatedly), fall back to executing tasks sequentially as the main agent:

for each task in unblocked:
  # Follow the /chorus-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 the task-reviewer nudge — you must spawn it 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 nudges the same way in both modes — you must always spawn the reviewer manually.

---

Phase 4: Verification

After each wave's subagents 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":
    # Subagent may have failed; skip or handle
    continue

  # 2. Spawn the chorus-task-reviewer subagent in the FOREGROUND (hook nudged it —
  #    you must spawn it yourself). Wait for the VERDICT before proceeding.
  #    Prompt: "Review task <task-uuid>. Round: N."

  # 3. Read task-reviewer VERDICT
  comments = chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
  # Find the most recent comment containing "VERDICT:"

  # 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 (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 comment after the task-reviewer returns? It exhausted its turn budget. Respawn it ONCE with a concise-budget hint: "Stay within turn budget. Skip deep verification. Fetch task/proposal/comments, demand the developer's run evidence, and post your VERDICT within the first 12 turns." If the second attempt also produces no VERDICT, treat as PASS WITH NOTES and proceed — do not loop indefinitely.

---

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

Once every task of the idea's proposal is verified (done) — i.e. Phase 3 finds no more unblocked tasks and all are terminal — run the final ship-time code-review gateway before declaring the Idea done and before the Phase 5b completion report. After the last task is verified, the postToolUse hook injects a reminder to spawn the code-reviewer; you MUST spawn it yourself in the foreground.

# Spawn the chorus-code-reviewer subagent for the IDEA (not a task). Determine the
# round number by reading prior code-review VERDICT comments on the idea.
#   Prompt: "Review the aggregate code for idea <idea-uuid>. Round: N."

# Read its VERDICT on the idea
comments = chorus_get_comments({ targetType: "idea", targetUuid: "<idea-uuid>" })
# Find the most recent comment containing "VERDICT:"

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 (/chorus-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).

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

No new VERDICT comment after the code-reviewer returns? It exhausted its turn budget (the code-reviewer runs with a larger budget than the task-reviewer because it reviews the whole feature). Respawn it ONCE with a concise-budget hint, then if still silent treat as PASS WITH NOTES and proceed — do not loop forever on a silent reviewer.

The code-review gateway is behavioral, consistent with the proposal/task reviewers: its verdict is advisory and does not change the Idea's stored status. The /chorus-yolo orchestrator honors it — PASS to ship, FAIL to loop. It runs before the completion report so the report is never written for a feature with an outstanding FAIL.

---

Phase 5: Report

After all waves complete, output a markdown summary:

## /chorus-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 /chorus-yolo run always finishes the Idea — call chorus_create_report once with proposalUuid set to the last verified proposal. The content parameter's description carries the section template; follow it. Surface the returned documentUuid in the Phase 5 summary. Skipping is a protocol violation.

Order: the completion report is written only after the Phase 4.5 code-review gateway returns PASS / PASS WITH NOTES. Never write it while a code-review FAIL is outstanding — the report is a ship-time summary, and the gateway is what clears the feature to ship.

---

Error Handling

Scenario	Action
Missing permissions at startup	Abort with message listing the missing resource/action pairs (see Prerequisites). Recommend an Admin-preset API key.
Project creation fails	Report error, suggest user create project manually and retry with --project
Proposal reviewer FAIL after maxRounds	Stop pipeline, report persisting BLOCKERs, suggest manual review
Task reviewer FAIL after maxRounds	Flag task as escalation-needed, continue with other tasks
Code-review gateway FAIL after maxCodeReviewRounds	Stop before ship, escalate the persisting feature-level BLOCKERs to a human (Idea UUID), do not write the completion report
Subagent crash / no submit	Log error, skip task, pick it up in next wave if possible
Ctrl+C	All entities persist in Chorus. User can resume via /chorus-develop or /chorus-review

---

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 /chorus-quick-dev instead -- it skips the Idea->Proposal overhead
• Subagents share your API key; ensure it has the permissions listed in Prerequisites before starting

---

Next

• To manually review proposals: /chorus-review
• To manually develop tasks: /chorus-develop
• To create quick standalone tasks: /chorus-quick-dev
• For platform overview: see the chorus steering doc.