Introduction

autoducks lets you run code agents on your CI/CD platform, triggered by issue comments, with any LLM provider. One command drives a full design → plan → build pipeline: each agent checks its own Definition of Ready and automatically dispatches the missing prerequisite, so you always get a reviewed design and plan before code is written.

Four agents, one command

Agent	Layer	What it does	You type
Architect	Design	Creates or revises the design in the issue body, classifies it as Feature or Bug	/architect
Engineer	Tactics	Breaks the design into task issues organized in dependency waves	/engineer
Maestro	Orchestration	Owns branches/PRs, dispatches execution waves in parallel — pure bash, no LLM	/execute
Developer	Build	Implements one task, merges its PR into the pipeline branch	dispatched by the Maestro

You never have to know which workflow answers: the same execute comment routes by issue state. On a Task issue it runs the Developer; on a planned issue (Tactics:done) it runs the Maestro; on anything else it runs the Engineer — which cascades to the Architect if there’s no design yet.

The cascade, concretely

Here’s what happens when you comment /execute on a raw issue — just a title and a couple of sentences:

flowchart LR
  A["Architect\ndesigns"]
  E["Engineer\nplans"]
  M["Maestro\norchestrates"]
  D["Developer\nbuilds"]

  A --> E --> M --> D
  E -. "no Design:done →\ndispatches Architect first" .-> A
  M -. "no Tactics:done →\ndispatches Engineer first" .-> E

  class A designPurple
  class E tacticalPink
  class M waveGreen
  class D executionBlue

  classDef designPurple fill:#f0d4f8,stroke:#a836e5,color:#a836e5
  classDef tacticalPink fill:#f8d4e4,stroke:#e55398,color:#e55398
  classDef waveGreen fill:#d4f8d4,stroke:#28a745,color:#28a745
  classDef executionBlue fill:#cfe8ff,stroke:#0366d6,color:#0366d6

1. Your comment routes to the Engineer (the issue isn’t planned yet). Its Definition of Ready fails — no Design:done label — so it posts a 🔁 status and dispatches the Architect, re-queuing itself (and your execute intent) behind it.
2. The Architect writes the design into the issue body, labels it Feature (or Bug), applies Design:done, and hands the chain back to the Engineer.
3. The Engineer produces the tactical plan — task issues in dependency waves — applies Tactics:done, and continues the chain to the Maestro.
4. The Maestro creates the pipeline branch and a draft PR, then dispatches one Developer per task, wave by wave. Every merged task PR re-triggers it until the final PR is ready for your review.

Each hop is visible: a bot-owned status comment on the issue is edited in place (Running → ✅ done / 🔁 delegated / ⚠️ failed), and stage labels track progress. See the full lifecycle walkthrough.

Prefer to review each stage? Run /architect, review, /engineer, review, then /execute. Or chain explicitly with your own stops: /architect #auto:engineer designs and plans, then waits for you.

Core principles

One command, guarded stages. Every agent has a Definition of Ready and a Definition of Done. Missing prerequisites are dispatched automatically instead of failing — the pipeline guarantees a reviewed design and plan exist before any code is written.

Native triggers, native state. Triggers are issue comments, PR merges, and workflow dispatches. State lives in your issue tracker and repository: issue bodies, labels, branches, PRs. No external state, no vendor bot, no per-seat licensing.

BYO harness, BYO subscription. You provide your own API key. autoducks does not proxy or meter LLM calls.

LLM for reasoning, bash for orchestration. The Maestro and the utility agents are 100% deterministic bash — fast, free, and auditable. LLMs only run where reasoning is required: designing, planning, coding, fixing.

Pluggable providers. Three interfaces — ITS (issue tracking), Git, and LLM — keep agent logic decoupled from GitHub and Claude specifics.

Utility commands

Outside the pipeline, three utilities handle recovery and lifecycle: /fix (repair a failed task run, resuming preserved partial work), /revert (undo planning, restore the human-authored issue), and /close (tear down branches, PRs, and task issues). See Utility commands.

What autoducks is not

• Not a CI/CD system. It writes code and opens PRs — not tests, deploys, or environments.
• Not a code review tool. The final PR always requires human review before merging.
• Not vendor-locked. The LLM provider defaults to Claude, but the interface is swappable.