ADR-061: GitHub Issues for planned work with AI agent instructions¶
Category: development Provenance: human
Decision¶
All planned work tracked in GitHub Issues with dedicated "AI Instructions" section. Work done in feature branches linked to issues. AI agents implement issues with human guidance, then open PRs with auto-rebase on completion.
Rationale¶
GitHub Issues provide structured planning with visibility and tracking. AI Instructions field guides agents with context-specific hints (modules to focus on, constraints, known issues). Reduces back-and-forth by frontloading guidance. Feature branches isolate work-in-progress from main. Auto-rebase keeps history clean without manual intervention. Human verification before PR prevents premature merging. Auto-merge after checks pass reduces manual overhead while ensuring CI validates changes. Issue linking provides traceability from problem to solution. Standardized workflow enables consistent collaboration between humans and AI agents.
Agent Instructions¶
GitHub Issues are the single source of truth for planned work. Issue template at .github/ISSUE_TEMPLATE/issue.yml includes "AI Instructions" field for agent-specific guidance (line 43-52). Workflow: 1) Create issue with description and AI instructions, 2) Create feature branch linked to issue, 3) AI agent implements following instructions, asking user for missing input/decisions, 4) Human verifies work, 5) AI opens PR with auto-rebase (gh pr merge --auto --rebase), 6) PR auto-merges when checks pass. Branch naming: feature/issue-123-description or fix/issue-123-description. PR title references issue: "feat: implement X (#123)".
Rejected Alternatives¶
Work directly on main branch¶
No isolation for WIP. Risky - broken code affects everyone. Can't review before merge.
Manual PR merging¶
Requires human to monitor CI and click merge. Wastes time. Auto-merge with checks is safer and faster.
No AI Instructions field in issues¶
Agents lack context. More questions, slower implementation. AI Instructions provide upfront guidance.
Linear or Jira for issue tracking¶
GitHub Issues integrates with PRs, code, CI. External tools add friction. GitHub native is simpler.