Architect

/architect

The Architect turns a rough request into a complete, actionable design — or revises a design that already exists. It bridges “here’s an idea” and “here’s what to build and how”, and classifies the issue as a Feature or a Bug.

Type: LLM (Claude) · Scripts: .autoducks/agents/architect/{pre,post}.sh · Verbs: architect, design

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  Architect["Architect"]
  Issue@{ shape: notch-rect, label: "Issue\ntype: Feature or Bug\nlabel: Design:done" }

  Triggers --triggers--> Architect
  Architect -- edits --> Issue

  class Triggers triggersOrange
  class Architect designPurple

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef designPurple fill:#f0d4f8,stroke:#a836e5,color:#a836e5

Triggers

Event	Condition
Issue comment	/architect or /design
Workflow dispatch	Dispatched by the Engineer’s Definition-of-Ready guard (with the chain re-queued)

There is no automatic trigger from labels — entry is by command or cascade only. The Architect itself has no Definition of Ready: it accepts any issue.

Create or revise

The Architect judges the maturity of what’s already in the issue:

• Raw idea / thin draft → authors the full design from scratch.
• Already a solid design — human-written, or a previous run with human edits → revision mode: it keeps the author’s structure, decisions, and wording where sound, fills gaps, structures loose prose, and grounds claims against the actual codebase. Explicit requirements, code blocks, and type definitions are preserved verbatim.

This is why the pipeline can require a design for every issue without punishing teams that write their own specs: a mature spec passes through structured, not rewritten.

Behavior

1. Reacts 👀, posts the status comment, applies Design:draft.
2. Delivery-phase lock: if delivery has already started — a Work:* label is present, or the pipeline branch already exists — the run is refused with a comment pointing at /quack revert (or /quack close) as the way back to the discovery phase. Nothing else runs.
3. If the body already has a tactical zone (<!-- autoducks:tactical:begin/end -->), it is stripped — not preserved — with a warning comment explaining that the plan is stale now that the design is being revised; malformed markers abort loudly with restore instructions instead.
4. [LLM] Explores the repository (read-only, including read-only git/gh commands — mutations stay forbidden) and writes the design with sections: Problem Statement, Proposed Solution, Technical Design, Dependencies, Constraints, Out of Scope. Classifies the issue as Feature or Bug.
5. Publishes the design zone to the issue body.
6. Sets the native issue type and the label to Feature or Bug (the label is route-critical everywhere; the native type is best-effort, org-only). Removes Draft if present.
7. Design:draft → Design:done; assigns the command author (who owns the next action); edits the status comment to ✅ with the next step; continues the #auto: chain if one is queued.

Caution

The Architect only runs while the issue is still in the discovery phase. Once the Engineer has planned it and delivery has started (Work:* label, or the pipeline branch exists), re-running the Architect is refused — run /quack revert (keep the issue, undo the plan) or /quack close (full teardown) first, then re-run.

Bug classification

/tmp/issue-type written by the LLM decides the kind. Bugs go through the same pipeline as features — plan, waves, execution — but the Maestro cuts their pipeline branch as fix/<id>-<slug> instead of feature/<id>-<slug>. See Branch naming.

Output

• Issue body holds the full design (tactical zone stripped, with a warning, if one was present)
• Type + label set to Feature or Bug; Draft removed
• Design:done applied — the Engineer’s Definition of Ready
• Assignee = whoever ran the command

Overrides

/architect model:opus effort:max turns:40
/architect #auto:engineer          # design, then plan, then stop
/architect #auto:engineer+execute  # full pipeline from here

See Slash commands for the full grammar.

Tip

Already have a detailed spec in the issue? Run /architect anyway — revision mode structures it and applies Design:done without rewriting your content, and the rest of the pipeline is then guaranteed a reviewed design.

Steering a re-run

Editing the issue body before re-running is the primary way to steer the Architect today — revision mode preserves your edits rather than rewriting them. A trigger-comment prompt (free text right in the /architect comment) is a planned enhancement for steering without editing the body first. See Re-running agents for the full picture across every stage.