Branch naming

autoducks uses a predictable, issue-number-rooted branch naming convention. Every branch can be traced back to its source issue(s).

Patterns

Context	Pattern	Example
Feature branch	feature/{feature_id}-{slug}	feature/42-user-auth
Task under feature	feature/{feature_id}-issue-{task_id}-{timestamp}	feature/42-issue-43-1735000000
Orphan task	feature/0-issue-{task_id}-{timestamp}	feature/0-issue-99-1735000000
Fix branch (new)	feature/{feature_id}-issue-{task_id}-fix-{timestamp}	feature/42-issue-43-fix-1735000000

Slug generation

Slugs are generated from the issue title:

1. Lowercase the title
2. Replace non-alphanumeric characters with hyphens
3. Collapse consecutive hyphens
4. Truncate to a reasonable length

Example: "Add dark mode toggle to settings" → add-dark-mode-toggle-to-settings

Feature branch example: feature/42-add-dark-mode-toggle-to-settings

Why timestamps in task branches?

Task branches include a Unix timestamp in the name. This allows:

• Multiple execution attempts without branch collision
• The Fix agent to locate partial work from prior attempts via prefix matching
• Clean identification of which attempt a branch belongs to

Branch relationships

main
└── feature/42-my-feature            ← feature branch (PR → main, human review)
    ├── feature/42-issue-43-...      ← task 1 branch (PR → feature, auto-merge)
    ├── feature/42-issue-44-...      ← task 2 branch (PR → feature, auto-merge)
    └── feature/42-issue-45-...      ← task 3 branch (PR → feature, auto-merge)

Lifecycle

Branch type	Created by	Deleted by
Feature branch	Tactical agent	Close agent (on /agents close)
Task branch	Execution agent	Merge policy (GitHub auto-deletes on PR merge)
Fix branch	Fix agent	Merge policy

Feature branches are not auto-deleted when the feature PR merges — GitHub’s delete-on-merge policy handles task and fix branches.