Agents overview

autoducks runs four pipeline agents — Architect → Engineer → Maestro → Developer — plus a set of utility commands you invoke directly. You drive them with one command surface, and each agent guards its own entry: if a prerequisite is missing, the agent dispatches it automatically and re-queues itself behind it (the Definition-of-Ready cascade).

flowchart LR
  A["Architect\ndesign"]
  E["Engineer\nplan"]
  M["Maestro\norchestrate"]
  D["Developer\nbuild"]

  A --> E --> M --> D
  E -. "no Design:done →\nArchitect first" .-> A
  M -. "no Tactics:done →\nEngineer 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

The four agents at a glance

	Architect	Engineer	Maestro	Developer
Purpose	Creates or revises the design of features and bugs	Creates the execution plan: tasks + dependency waves	Coordinates parallel execution waves, owns branches/PRs	Implements one task
Type	LLM	LLM	Bash (no LLM)	LLM
Trigger phrases	architect, design	engineer, tactics — or execute on an unplanned issue	execute, run, work on an issue with Tactics:done	same verbs, on a Task issue
Definition of Ready	none (any issue)	Design:done	Tactics:done	Task with a parent whose pipeline branch exists
Auto-dispatch when not ready	—	Architect	Engineer #auto:execute	Maestro on the parent
Stage labels	Design:draft → Design:done	Tactics:crafting → Tactics:done	Work:orchestrating → Work:done	Work:coding → Work:done
Definition of Done	structured design; type/label Feature/Bug	plan + subtasks created and linked	all subtasks closed, final PR ready	task PR merged; task closed

How execute routes

The same comment is claimed by exactly one workflow, decided by issue state — you never pick the agent yourself:

You comment /execute on…	Who answers
A Task issue (type or label Task)	Developer
An issue with the Tactics:done label	Maestro
Anything else (raw issue, or designed but unplanned)	Engineer — cascading to the Architect if Design:done is missing

So /execute on a fresh issue runs the whole pipeline: Architect → Engineer → Maestro → Developers. See the lifecycle walkthrough for what that looks like comment by comment.

Utility commands

Command	Type	What it does
/review	LLM	Reviews a PR against its design and acceptance criteria — read-only, never merges
/triage	LLM	Grooms the backlog: assigns priorities and proposes duplicate groupings — scheduled, on issue open, or on demand
/merge	Bash	Deterministically closes one issue as a duplicate of another
/fix	LLM	Repairs a failed task run, resuming preserved partial work
/revert	Bash	Undoes planning, restores the human-authored issue
/close	Bash	Full cleanup: closes issues, PRs, and deletes branches

The Reviewer is a post-execution gate, not a pipeline stage: run it once a feature/bug PR exists to get a verdict (approve/comment/request-changes) and severity-ranked findings before you merge.

The Product Owner is the only agent that also runs unattended — a daily schedule sweep (or an issues.opened event) grooms the backlog without any comment at all; /triage and /merge are how you drive it on demand.

LLM vs. bash

A deliberate design choice: only agents that need reasoning use an LLM. Orchestration, reconciliation, and cleanup are pure deterministic bash.

Needs LLM	Pure bash
Architect, Engineer, Developer, Reviewer, Fix, /triage	Maestro, Revert, Close, /merge

This makes wave progression fast, cheap (no API calls), and auditable.

Feedback protocol

Every run gives feedback in two layers:

1. Reactions on your comment — 👀 started, 👍 success, 😕 failure.
2. A bot-owned status comment, edited in place as the run progresses:

Status	Meaning
Agent: running on workflow #id	The run is in progress
✅ Agent: finished working	Done — the friendly details and next step follow
🔁 Agent: not ready — delegated	A Definition-of-Ready guard dispatched the prerequisite agent
⚠️ Agent: failed	See the categorized failure report posted below it

The bot never edits your comment — reactions stay on it, and /revert can safely delete all bot content while preserving everything human-authored.

Provider abstraction

All agents use three provider interfaces:

Interface	Prefix	Supported	Responsibility
ITS	its::	github	Issues, PRs, labels, comments
Git	git::	github	Branches, commits, merges
LLM	llm::	claude	Agent reasoning, code writing

Switching providers means implementing the same function signatures under a new provider directory — agent logic stays unchanged.