Design philosophy

One command, guarded stages

autoducks is designed so the simplest thing a user can do — comment /execute on an issue — is also the safest: every agent has a Definition of Ready, and when a prerequisite is missing it dispatches the missing agent automatically instead of failing or, worse, coding without a plan. The pipeline guarantees that a reviewed design and a tactical plan exist before any code is written.

This replaced an earlier “standalone execution” mode where any issue could go straight to code. It was convenient, but nothing guaranteed the issue was actually well-defined. The current answer keeps the convenience (one comment, full autonomy) and adds the guarantee — and because the Architect revises rather than rewrites, teams that write detailed specs pass through the design stage without losing a word.

Key decisions

Issues as the coordination surface

Issues are not just tickets — they’re the specification store, the state machine, and the progress tracker. The issue body holds the design (design zone) and the plan, waves, and real-time progress (tactical zone). Labels are the state machine; the assignee marks who owns the next action.

No external state means no sync problems. An interrupted run resumes by re-issuing the same comment — agents recompute everything from visible state.

Bash for orchestration, LLM for reasoning

The Maestro, Revert, and Close agents are 100% deterministic bash. They read ITS and Git state (merged PRs, labels, branch existence) and take deterministic actions. LLMs run only where reasoning is required: designing, planning, coding, fixing.

This separation means wave progression is fast (no API latency), cheap ($0 per cycle), and auditable.

A single verb, routed by state

Users shouldn’t need to know which agent answers — execute means “make progress on this issue”. Routing by issue state (Task? planned? raw?) plus the Definition-of-Ready cascade turns four agents into one interface. Explicit verbs (architect, engineer) exist for when you do want a specific stage.

Names that carry the mental model

Architect → Engineer → Maestro → Developer mirrors how humans staff the same pipeline: design, tactics, coordination, build. The Maestro name (an orchestra conductor) is doing real work here — it coordinates many Developers playing in parallel waves.

Python parser for plan extraction

The Engineer outputs a plan in structured Markdown. A deterministic Python parser (parse-plan.py) extracts tasks — not a second LLM call. It runs in under a second (vs ~8 minutes for the LLM approach it replaced) and produces consistent output regardless of model variation.

Event-driven advancement

Every task PR merged into a pipeline branch re-triggers the Maestro, which recomputes wave state and continues. No polling, no queue, no daemon — the CI platform’s own events are the scheduler. Three independent idempotency guards make racing events harmless.

BYO harness, BYO subscription

autoducks does not proxy LLM calls, charge per-seat, or require a vendor bot. You supply your own API key and own the relationship with your LLM provider. autoducks is infrastructure, not a service.

Feedback that edits itself

Each run posts one bot-owned status comment and edits it in place (Running → ✅ / 🔁 / ⚠️), instead of stacking milestone comments. Reactions (👀 👍 😕) stay on your comment. The bot never edits human content — which is what makes /revert’s “delete bot comments, restore the human body” contract possible.

Security before feedback

The Authorization Gate runs before any observable side effect. A denied actor doesn’t get a “Running…” comment — on a public repository, even feedback is budget.