Migrating from /agents

This guide upgrades repositories running the previous topology — /agents commands, design/tactical/wave/execution agents, Spec:*/Ready labels — to the current one. The rename shipped without retroactive aliases: old commands stop working after the upgrade.

What changed, at a glance

	Before	After
Prefix	`/agents` (hardcoded)	(none, by default) — bare `/architect`, `/execute`, etc.; optionally namespaced via `command`
Design	`/agents design` · `plan`	`/architect` · `design`
Planning	`/agents devise` · `drilldown` · `specify`	`/engineer` · `tactics`
Execution	`/agents execute` · `work` · `run` · `start`	`/execute` · `work` · `run`
Effort	`--reasoning` / `reasoning`	`effort:` / `effort`
Labels	`Spec:draft`/`Spec:plan`, `Tactics:ready`+`Ready`, `Work:progress`, `Tactics:single`, `priority:P0-3`	`Design:draft`/`Design:done`, `Tactics:done`, `Work:orchestrating`/`Work:coding` — the rest retired
Workflows	`autoducks-{design,tactical,wave,execute}.yml`	`autoducks-{architect,engineer,maestro,developer}.yml`
Standalone tasks	`execute` on any non-Feature issue	Retired — the pipeline guarantees design + plan first
Bug issues	(no concept)	`Bug` classification; `fix/…` pipeline branches

Migration steps

Finish or park in-flight pipelines. Features mid-execution are simplest to finish on the old install. If you migrate with one in flight, re-run /engineer afterwards — revision mode reconciles existing task issues by number.
Re-run the installer from your repo root:
Terminal window
```
curl -fsSL https://raw.githubusercontent.com/deepducks/autoducks/main/scripts/install.sh | bash
```
This replaces .autoducks/ and the workflow files. Old workflow files (autoducks-design.yml, autoducks-tactical.yml, autoducks-wave.yml, autoducks-execute.yml) are superseded by the renamed ones — delete the old ones if the installer left them behind:
Terminal window
```
git rm .github/workflows/autoducks-{design,tactical,wave,execute}.yml
```
Migrate .autoducks/autoducks.json:
- defaults.reasoning → defaults.effort
- triggers keys: design→architect, tactical→engineer (values — your custom aliases — carry over; devise etc. are no longer built-in)
- security.per_agent keys: design→architect, devise→engineer (execute, fix, revert, close unchanged; the Maestro and Developer share execute)
- Optionally set command to a namespace word (e.g. quack) if you want a namespaced prefix instead of the short-form default — see Short-form commands below
Migrate per-agent defaults — the directories were renamed (design→architect, tactical→engineer, waveOrchestrator→maestro, execution→developer); if you customized any defaults.json, port your values and rename reasoning→effort.
Re-bake the workflow guards (required if you set a custom prefix or aliases; harmless otherwise):
Terminal window
```
bash scripts/update-triggers.sh && git add -A && git commit -m "chore: rebake autoducks triggers"
```

Run the setup checks:

./scripts/setup.sh

This creates the new labels. Old labels on existing issues are cleaned up automatically by the agents as they touch each issue; to purge them repo-wide now:

for l in "Spec:draft" "Spec:plan" "Tactics:ready" "Ready" "Work:progress" \
         "Tactics:single" "priority:P0" "priority:P1" "priority:P2" "priority:P3"; do
  gh label delete "$l" --yes 2>/dev/null || true
done

Tell your team. The one-liner: “/agents is now /execute — no prefix needed; it designs and plans by itself when needed.”

Short-form commands

command in .autoducks/autoducks.json defaults to "" (empty), so every trigger is a bare verb — /execute, /architect, /fix, and so on. There’s no namespace word to type or remember.

If you’d rather keep a namespaced prefix (matching the old /agents habit, or to avoid colliding with another bot’s commands), opt in by setting command to a word:

{ "command": "quack" }

which turns every trigger into /quack <verb> (/quack execute, /quack architect, …). To opt back out, set it back to "". Either way, re-bake and commit the workflow guards afterward:

bash scripts/update-triggers.sh && git add -A && git commit -m "chore: rebake autoducks triggers"

See command for the full validation rules and the bounded-blast-radius rationale for the short-form default.

Behavior changes to be aware of

/execute on a plain issue no longer codes directly. It cascades through design and planning first. If you relied on standalone execution for tiny tasks, the equivalent is /architect #auto:engineer+execute — one comment, same autonomy, but with a reviewed design and plan in the middle.
Plans no longer carry priority:PN — old plan bodies still parse (the suffix is tolerated and ignored).
Re-planning marker changed: revision mode now keys off Tactics:done (the old Ready is removed on sight).
The bot posts one status comment per run and edits it — if you had tooling scraping the old milestone comments, anchor on the status comment instead.