Your first run

This guide walks you through the full autoducks pipeline on a real issue — from a rough idea to a PR waiting for your review. There are two ways to drive it: one command (the pipeline cascades through every stage) or stage by stage (you review between stages).

Before you start

Make sure you’ve completed Installation and the setup checks pass.

Path A — one command

1. Create an issue. A clear title and a couple of sentences are enough — the Architect writes the real design.

   Title: Add dark mode toggle to settings page

   Body: Users should be able to switch between light and dark mode from the settings page. The preference should persist across sessions.

2. Comment on it:

   /execute

3. Watch the status comment. The bot posts one status comment per agent run and edits it in place. First you’ll see the Engineer delegate:

   🔁 Engineer: not ready — delegated on workflow #123

   This issue has no Design:done label, so the Architect was dispatched first to create (or revise) the design. The Engineer will re-run automatically when it finishes.

4. The Architect designs. A few minutes later the issue body holds a full design — problem statement, proposed solution, technical design, dependencies, constraints, out of scope — and the issue is labeled Feature (or Bug) and Design:done.

5. The Engineer plans. Task issues appear (T1, T2, …), linked as sub-issues, organized in dependency waves inside the issue body’s tactical zone. The issue gets Tactics:done.

6. The Maestro executes. It creates the pipeline branch (feature/<id>-<slug>, or fix/… for Bugs) and a draft PR, then dispatches one Developer per task, wave by wave:

   🌊 Wave 1 of 2 dispatched: Foundation

   Dispatched: 44 45

   The orchestrator advances automatically as each task PR merges.

   Each Developer implements its task, opens a PR into the pipeline branch, and auto-merges it. Every merge re-triggers the Maestro; checkboxes in the issue body tick as tasks complete.

7. Review the final PR. When every wave is done, the Maestro marks the PR ready, fills it with Closes #… references and a Work Log, and requests your review:

   🎉 All waves complete!

   This PR requires human review — autoducks never auto-merges it.

Path B — stage by stage

Same pipeline, with you reviewing between stages:

1. /architect — review the design in the issue body; edit anything you want to steer. Re-running the Architect revises rather than rewrites, and never touches the plan zone.

2. /engineer — review the tasks and waves. Re-running enters revision mode (existing tasks preserved by number). If the design was insufficient, the Engineer posts blocking questions instead of guessing — answer them and re-run.

3. /execute — the Maestro takes it from here, exactly as in Path A.

Tip

You can also chain stages with explicit stops: /architect #auto:engineer designs and plans, then waits for you before any code is written. See Chaining & overrides.

If something fails

Failures never end as a silent red X: the status comment flips to ⚠️ and a categorized failure report is posted with a link to the run logs and the exact retry command. The usual fix is:

/fix

on the failed task issue — it resumes from any preserved partial work. Full details in When things fail.

Cleaning up

• /revert — undo the planning: closes task issues, restores your original issue body, deletes bot comments.
• /close — full teardown: closes tasks and PRs, deletes branches, closes the issue.