---
name: github-issues-workflow
description: Coordinate work across multiple agents using GitHub issues. Use when picking an issue to work on, starting a new task from the backlog, or collaborating on a project where other agents may be active. Covers issue selection, claiming via assignment, branch naming, and conflict avoidance.
---

# GitHub Issues Workflow

Coordinate with other agents using GitHub issues as a lightweight kanban board. Multiple agents may be working on behalf of the same user concurrently, so assignment is the sole source of ownership — if an issue has **any** assignee (even `@me` / your own user), another agent has already claimed it. PRs auto-link via `#N` references.

**Prerequisites:** `gh` CLI authenticated.

## 1. Pick an issue

```bash
gh issue list --state open --json number,title,assignees,labels,body
```

Choose an **unassigned** issue (empty `assignees`). Any non-empty assignee list — including your own username — means another agent is already working on it. Self-assess priority and impact to decide which one — no label scheme required.

## 2. Assess scope

Before claiming, consider whether the issue is too large for a single PR. If it would touch many files or multiple unrelated areas, break it into sub-issues:

```bash
gh issue create --title "Sub-task title" --body "Part of #<parent-number>. ..."
```

Then pick one sub-issue to start with. This also creates parallelizable work for other agents.

## 3. Check for recent overlapping work

Before committing to an issue, check open PRs from the last 24 hours for scope overlap:

```bash
gh pr list --state open --search "created:>=$(date -u +%Y-%m-%dT%H:%M:%SZ -d '24 hours ago' 2>/dev/null || date -u -v-24H +%Y-%m-%dT%H:%M:%SZ)" --json number,title,headRefName,createdAt,body
```

If a recent PR covers the same scope or topic, skip the issue or pick a complementary angle to avoid conflicts.

## 4. Claim the issue

Self-assign:

```bash
gh issue edit <N> --add-assignee @me
```

Then re-read the issue to verify you are the sole assignee. If someone else also assigned themselves, back off and pick a different issue.

## 5. Work on the issue

- **Branch naming:** `issue-<N>-<short-slug>` (e.g. `issue-42-fix-auth-timeout`)
- **Commits:** Reference `#N` so GitHub auto-links (e.g. `fix(auth): handle token expiry (#42)`)
- **Standards:** Follow the repo's `AGENTS.md` for lint, test, and style requirements.

## 6. Complete the work

Create a PR with `Closes #N` in the body. GitHub auto-closes the issue on merge and links the PR to the issue.

If a `create-pr` skill exists in the repo, follow its format for the PR title and description.
