Design agent

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  DesignAgent["Design agent"]
  Issue@{ shape: notch-rect, label: "Issue
type: Feature / labels: Draft" }

  Triggers --triggers--> DesignAgent
  DesignAgent -- edits --> Issue

  class Triggers triggersOrange
  class DesignAgent designPurple

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

The Design agent reads a feature request, explores the codebase, and writes a comprehensive technical specification back to the issue. It bridges the gap between “here’s an idea” and “here’s what to build and how.”

Type: LLM (Claude)
Script: .autoducks/agents/design/pre.sh + post.sh

Triggers

Event	Condition
Issue comment	/agents design
Issue assigned	Issue has the Draft label

Behavior

Pre-execution

1. Reacts to the trigger comment with 👀.
2. Fetches the issue content (title + body) and writes it to /tmp/issue-request.md.

LLM execution

The agent reads /tmp/issue-request.md and CLAUDE.md (codebase context), then explores the repository (read-only: Read, Bash for listing/grepping).

It writes a full design specification to /tmp/design-spec.md covering:

• Problem statement — what the feature request is actually asking for
• Proposed solution — the approach, with rationale
• Architecture / design notes — how it fits into existing code
• Affected files — which files will need to change and why
• Out of scope — what won’t be addressed
• Acceptance criteria — testable criteria for the implementation

Post-execution

4. Validates that /tmp/design-spec.md was produced. On failure: reacts with 😕, posts an error comment, exits.
5. Updates the issue body with the design specification.
6. Sets the issue type to Feature.
7. Removes the Draft label.
8. Reacts with 👍 and posts a comment suggesting /agents devise to create the tactical plan.

Output

• Issue body updated with the full design specification
• Issue type set to Feature
• Draft label removed

Required permissions

permissions:
  contents: read
  issues: write
  pull-requests: write
  id-token: write

Directive arguments

You can override model and reasoning settings inline:

/agents design --model claude-opus-4-7 --reasoning high

Argument	Default	Description
--model	From .autoducks/autoducks.json	Claude model to use
--reasoning	From .autoducks/autoducks.json	Reasoning effort (low, medium, high)

Tip

The Design agent is optional — if your feature issue already has a detailed spec, you can skip straight to /agents devise. The Tactical agent doesn’t require a design step first.