Utility commands

Utility commands handle recovery, cleanup, post-review follow-up, and lifecycle operations. They sit outside the pipeline: no stage labels, no Definition-of-Ready cascade — but they go through the same security gate and give the same status-comment feedback.

Command	Type	What it does	Default security
/fix	LLM	Repairs a failed task run, resuming preserved partial work	trusted associations
/rework	LLM	Distills unresolved PR review feedback into one follow-up task, reverts the PR to draft, and re-dispatches execution	trusted associations
/defer	LLM	Captures unresolved PR review feedback as a follow-up issue so the PR can be merged/closed now	trusted associations (broader — includes CONTRIBUTOR)
/revert	Bash	Undoes planning, restores the human-authored issue	OWNER, MEMBER
/close	Bash	Full cleanup: closes issues, PRs, and deletes branches	OWNER, MEMBER

---

/fix

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  FixAgent["Fix agent"]

  Triggers --triggers--> FixAgent

  class Triggers triggersOrange
  class FixAgent fixRed

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef fixRed fill:#ffd4d4,stroke:#d62828,color:#d62828

Recovers a failed task run. It finds the newest existing task branch for the issue (searching both feature/… and fix/… prefixes — including WIP: branches preserved after a max_turns cutoff), reads the failure context from the last 10 comments, and fixes or completes the implementation on top of what’s there.

Scripts: .autoducks/agents/fix/{pre,post}.sh · Trigger: /fix on a task issue

Behavior

1. Reacts 👀, posts the status comment.
2. Checks out the newest matching task branch, or creates …-issue-<n>-fix-<epoch> if none exists.
3. [LLM] Reads the task spec + failure context and repairs the implementation.
4. Commits (if there are changes — a reused branch may already carry them), pushes, reuses the existing PR or opens Fix: <title>.
5. Under a parent: single-attempt merge (a conflict posts the 🔀 report), then the Maestro resumes. Standalone-dispatched fixes leave the PR for review.
6. Assigns the command author; status comment flips to ✅.

Note

Fix ≠ the Bug flow. /fix repairs a failed agent run. A product bug goes through the full pipeline — /execute on the bug issue — and gets a fix/… pipeline branch via the Architect’s classification.

Tip

Before running /fix, comment what went wrong — the agent reads the last 10 comments as context, so more detail leads to better repairs.

---

/rework

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  ReworkAgent["Rework agent"]

  Triggers --triggers--> ReworkAgent

  class Triggers triggersOrange
  class ReworkAgent reworkIndigo

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef reworkIndigo fill:#e0d4f8,stroke:#6a3fd6,color:#6a3fd6

Distills unresolved PR review feedback into a single follow-up task, then hands it back to the pipeline. Unlike /review, it needs no prior /review run — it reads raw PR reviews, inline review-thread comments, PR conversation comments, and feature-issue comments directly.

Scripts: .autoducks/agents/rework/{pre,post}.sh · Trigger: /rework on the feature/bug issue or directly on its pull request, or a headless workflow_dispatch from the Reviewer’s auto-rework loop (pr_number set, no triggering comment)

Behavior

1. Reacts 👀, posts the status comment.
2. Resolves the target PR (same resolution the Reviewer uses) and the feature/bug issue it implements. If no open PR is found, or the PR is already closed/merged, posts “Nothing to rework” and exits green.
3. Checks for an already-open rework sub-issue for this feature (an idempotency marker in the body) — reuses it instead of minting a duplicate.
4. [LLM] Reads every PR review, comment, and feature-issue comment and judges each distinct concern resolved or unresolved. If everything is resolved, or the feedback was purely informational, writes only a “nothing to rework” explanation — no task is created.
5. Otherwise, folds every unresolved concern into exactly one follow-up task, citing the reviewer/comment behind each item.
6. post.sh parses that task with the same parser the Engineer uses, appends it as a new task on the feature issue (a new wave, or promoting a single-task issue into a two-wave plan), clears any lingering Review:* labels from both the feature issue and the PR, and reverts the PR to draft.
7. Dispatches execute on the feature issue so the Maestro/Developer builds the fix; the PR flips back to ready once it merges.

Note

/rework produces at most one task per run — several distinct concerns are folded into that task’s checklists, not split into separate tasks.

Headless dispatch and the rework-none hand-off

The Reviewer’s bounded auto-rework loop drives /rework via workflow_dispatch — pr_number (and, when available, actor) set directly, with no triggering comment, so COMMENT_ID defaults to "0". pre.sh/post.sh tolerate this: every step that would otherwise react to or read a triggering comment degrades gracefully when there isn’t one.

That headless origin changes what step 4 above does when it finds nothing to rework (everything already resolved, or purely informational feedback):

Origin	On nothing-to-rework
Manual /rework (a triggering comment exists)	Finishes green: posts “Nothing to rework,” no sub-issue, no draft flip, no dispatch.
Headless auto-dispatch (no triggering comment, COMMENT_ID is "0"/empty)	Posts an explicit human hand-off: “Nothing to rework — PR #<n> is still blocked,” plus the same /rework//defer next-step instructions the Reviewer posts on request-changes.

The distinction exists because a headless dispatch has no comment thread for a human to notice the outcome on — the PR the Reviewer requested changes on is still blocked either way, so a silent green stop from an unattended loop would strand it with no visible next step. A manual /rework always has a human already watching the thread it was run from, so a quiet green finish is safe there.

---

/defer

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  DeferAgent["Defer agent"]

  Triggers --triggers--> DeferAgent

  class Triggers triggersOrange
  class DeferAgent deferBlue

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef deferBlue fill:#d4e4f8,stroke:#2861c9,color:#2861c9

Captures outstanding PR review feedback as a self-contained follow-up issue, so you can merge or close the PR now without losing the discussion. It never touches the PR itself — no draft flip, no branch changes.

Scripts: .autoducks/agents/defer/{pre,post}.sh · Trigger: /defer on the feature/bug issue or directly on its pull request

Behavior

1. Reacts 👀, posts the status comment.
2. Resolves the target PR — deliberately allowed on closed or merged PRs too (unlike /review, which skips outright), since the point is to unblock a merge/close that’s already happened or is about to.
3. If the PR has no reviewer or human feedback at all, posts “Nothing to defer” and exits green.
4. Checks for an already-open deferral issue for this (PR, feature) pair (a marker string search) — updates it in place instead of creating a duplicate.
5. [LLM] Synthesizes the unresolved, substantive feedback into an Architect-ready issue body: a problem statement plus a bulleted list of concrete asks, each grounded in a cited comment. Nits, praise, and already-resolved points are dropped. If nothing substantive remains, writes only a “nothing to defer” explanation and no issue is created.
6. post.sh creates (or updates) the follow-up issue with an idempotency marker and a back-link to the feature issue, and reports how many review comments were deferred.

Tip

Run /architect on the new follow-up issue whenever you’re ready to act on the deferred feedback — it’s a plain issue, not yet designed or planned.

---

/revert

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  RevertAgent["Revert agent"]

  Triggers --triggers--> RevertAgent

  class Triggers triggersOrange
  class RevertAgent revertYellow

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef revertYellow fill:#fff3cd,stroke:#856d00,color:#856d00

Undoes the Engineer’s work: closes all task issues and restores the issue to how it looked before planning.

Script: .autoducks/agents/revert/run.sh · Type: Bash — no LLM · Trigger: /revert

Behavior

1. Extracts task numbers from the waves block and closes each task as not-planned.
2. Strips pipeline labels — current taxonomy and legacy labels from older installs.
3. Restores the original issue body from the edit history — the last edit made by a human (bot edits are ignored).
4. Deletes all bot comments; every human comment survives. This works because agents only ever post and edit their own comments — they never touch yours.

Does not delete branches or close PRs — use /close for that. After reverting, run /engineer (or the full pipeline) again.

---

/close

flowchart LR
  Triggers@{ shape: bolt, label: "Triggers" }
  CloseAgent["Close agent"]

  Triggers --triggers--> CloseAgent

  class Triggers triggersOrange
  class CloseAgent closeGray

  classDef triggersOrange fill:#ffe8d4,stroke:#d66a28,color:#d66a28
  classDef closeGray fill:#e8e8e8,stroke:#586069,color:#586069

Full teardown of a pipeline and all associated work.

Script: .autoducks/agents/close/run.sh · Type: Bash — no LLM · Trigger: /close

Behavior

1. For each task: finds its branches (both feature/… and fix/… prefixes), closes open PRs, deletes branches, closes the task issue.
2. Closes the pipeline PR and deletes the pipeline branch (checks both prefixes, so it works even if the issue’s kind changed after design).
3. Strips all pipeline labels (current + legacy) and closes the issue with a cleanup summary.

What gets removed

Object	Action
Task issues	Closed
Task PRs	Closed
Task branches	Deleted
Pipeline branch (feature/… or fix/…)	Deleted
Pipeline PR	Closed
The issue itself	Closed

Caution

/close is destructive — deleted branches cannot be easily recovered. Use /revert if you only want to undo the plan while keeping the issue open.