Your first feature

This guide walks you through the full autoducks pipeline on a real issue: from a rough idea to merged code.

Before you start

Make sure you’ve completed Installation and the setup checks pass.

Step 1 — Create a feature issue

Create a new issue with a clear title and a brief description of what you want. It doesn’t need to be a full spec yet — the Design agent will write that.

Example:

Title: Add dark mode toggle to settings page

Body: Users should be able to switch between light and dark mode from the settings page. The preference should persist across sessions.

Tip

Use the Feature issue template if it’s available in your repo — it gets pre-populated with the right structure.

Step 2 — Design the feature

Comment /agents design on the issue:

/agents design

The Design agent will:

• React to your comment with 👀
• Read your issue and explore the codebase (read-only)
• Write a full technical specification back to the issue body
• Remove the Draft label (if present)

When it’s done, you’ll see a 👍 reaction and a comment suggesting the next step.

The issue body now contains: problem statement, proposed solution, architecture notes, affected files, out-of-scope items, and acceptance criteria.

Step 3 — Create the tactical plan

Comment /agents devise on the issue:

/agents devise

The Tactical agent will:

• Read the design spec
• Decompose it into numbered task issues (T1, T2, T3…)
• Create each task as a child issue with acceptance criteria
• Add the Ready label to the feature issue
• Create the feature branch feature/{id}-{slug}
• Create a draft PR from the feature branch to main

When it’s done, you’ll see:

• New child issues linked to your feature
• A comment listing the tasks and suggesting /agents execute

Note

If you comment /agents execute on a feature issue that doesn’t have Ready yet, autoducks automatically runs the tactical agent first (auto-escalation).

Step 4 — Execute

Comment /agents execute on the feature issue (the one with the Ready label):

/agents execute

The Wave Orchestrator takes over (pure bash, no LLM):

1. Parses the task list from the feature issue body
2. Groups tasks into dependency waves (tasks in the same wave run in parallel)
3. Dispatches one Execution agent per task

Each Execution agent:

• Creates a task branch off the feature branch
• Reads the task spec and implements the code
• Opens a PR targeting the feature branch
• Auto-merges the PR (since it’s merging to a feature branch, not main)

After each wave completes, the orchestrator dispatches the next wave. Task checkboxes in the feature issue are updated as tasks complete.

Step 5 — Review the feature PR

Once all tasks are done, the Wave Orchestrator creates the final feature PR (or updates the draft PR from Step 3). It targets main and includes Closes #N for every task and the feature issue.

This PR requires human review — autoducks never auto-merges to main.

Review, approve, and merge.

Recovering from failures

If an execution agent fails (no changes produced, or implementation errors):

1. The agent comments on the task issue with a 😕 reaction
2. Fix the issue description or acceptance criteria if needed
3. Comment /agents fix on the task issue to retry

The Fix agent picks up where the previous attempt left off, reading the failure context to avoid repeating mistakes.

Revising a plan

If the tactical plan needs changes before execution starts, comment /agents devise again on the feature issue. The Tactical agent runs in revision mode — it updates existing tasks, creates new ones, and closes dropped tasks without losing completed work.